Host health scanner, optimization advisor and rolling-update reporter for Aetheris nodes
App | Docs | Website | Addons | Themes | Game Eggs | Windows Installer | Installer | Ops | Status | Android Discord | Donate
Pure standard-library Python host inspector that scans the machine running the Aetheris control plane, grades it with a single 0-100 health score, surfaces kernel / memory / disk / networking optimization opportunities, detects pending package updates across distros, and publishes everything automatically — a shields.io badge, a Markdown report and deduplicated GitHub issues for every critical finding.
Read-only by design. Scanning requires no privileges, no third-party packages, and the tool never modifies system state.
|
Single 0-100 grade with A-F letter class, weighted across kernel, memory, disk, load and update findings. |
swappiness · THP · TCP BBR · vm.dirty_ratio · load/cores · CPU governor · journald sizing · disk fill · swap pressure |
apt (Debian/Ubuntu) |
|
Scheduled Actions refresh the live badge, post the report to job summary and open dedup'd issues labeled |
Every collector degrades gracefully to |
Human-readable Markdown, machine JSON, shield endpoint compatible with shields.io |
# 1. Clone (or just grab aetheris_ops/ — no deps required)
git clone https://github.com/aetheris-project/aetheris-ops && cd aetheris-ops
# 2. Optional editable install (adds the `aetheris-ops` CLI)
python -m venv .venv
# Linux / macOS
source .venv/bin/activate
# Windows PowerShell
# .venv\Scripts\activate
pip install -e .
# 3. One-shot health summary
aetheris-ops check
# 4. Full report (stdout + files + badge JSON)
aetheris-ops report --markdown
aetheris-ops report --out-md reports/latest.md --out-json reports/latest.json
# 5. Pending updates only
aetheris-ops updates
# 6. Skip update check (restricted / offline runners)
aetheris-ops check --no-updates| Code | Meaning |
|---|---|
| 0 | Clean — no warnings, no criticals, no pending updates |
| 1 | Warnings and/or pending updates present |
| 2 | Critical findings — review immediately |
| Rule ID | Trigger (info / warn / critical) | Suggested fix |
|---|---|---|
vm-swappiness |
> 30 info · > 60 warn |
sysctl -w vm.swappiness=10 |
mem-pressure |
< 20% warn · < 10% critical |
Review workloads / add RAM |
swap-pressure |
> 80% swap used — warn |
Reassess memory sizing |
disk-full |
> 80% warn · > 92% critical |
Prune logs, images, backups |
thp |
Transparent HugePages always |
echo madvise > /sys/kernel/mm/transparent_hugepage/enabled |
tcp-cc |
Non-default congestion control — info | Consider tcp_bbr |
ip-forward |
net.ipv4.ip_forward=1 — info |
Disable unless routing / KVM |
vm-dirty-ratio |
> 30 info |
sysctl -w vm.dirty_ratio=20 |
load |
load/cores > 1 info · > 2 warn |
Rebalance workloads across nodes |
cpu-governor |
Non-performance governor — info | cpupower frequency-set -g performance |
journald-size |
SystemMaxUse=0 unbounded — info |
Set SystemMaxUse=500M in journald.conf |
.github/workflows/ops-report.yml runs daily at 04:17 UTC and on every push touching the scanner. On each run:
- The package is installed and
aetheris-ops reportregeneratesreports/latest.md,reports/latest.jsonandreports/badge.json. - Changes are committed back to
main— the top-of-readme score badge always reflects the last run. - The Markdown report is appended to the GitHub Actions job summary.
- A deduplicated issue labeled
ops:<rule-id>is opened per critical finding. Open issues for the same rule are never duplicated.
To publish the scan of a production host instead of the runner:
aetheris-ops report --out-md reports/latest.md --out-json reports/latest.json
git add reports/
git commit -m "chore(ops): refresh production host report"
git pushaetheris-ops/
├── aetheris_ops/
│ ├── cli.py # argparse entrypoint (aetheris-ops check|report|updates)
│ ├── collectors.py # sysfs / proc / psutil-free metric collection (stdlib only)
│ ├── optimizations.py # 11-rule engine + weighted A-F scoring
│ ├── updates.py # apt / brew / winget pending-update detectors
│ ├── report.py # Markdown · JSON · shields-endpoint renderers
│ └── __main__.py
├── .github/workflows/
│ └── ops-report.yml # Scheduled daily scan → badge + report + issues
├── reports/ # committed output: latest.md · latest.json · badge.json
├── tests/ # Scoring, ranking, dedup, exit-code tests
└── pyproject.toml
python -m pip install pytest
python -m pytest -qSuite covers: scoring math and grade boundaries, rule severity thresholds, report formatting, exit-code mapping, issue dedup keys.
Made with care by Leonardo Galli
App · Docs · Installer · Discord · Donate
Licensed under GNU Affero General Public License v3.0 (AGPL-3.0). See LICENSE.md. You may use, study, modify and redistribute for any purpose provided distributed or network-served modified versions keep this license, preserve Leonardo Galli's copyright notice and release source under AGPL-3.0. The Aetheris core and author credit may not be removed.
App | Docs | Website | Addons | Themes | Game Eggs | Installer | Windows Installer | Status | Community
Copyright (C) 2026 Leonardo Galli (Leo-Galli), Aetheris Project. Licensed under AGPL-3.0.
All contributions require a Pull Request with automated CI checks (lint, typecheck, build) before manual review.
Contact: hello@another-horizon.eu | Discord: discord.gg/6GcfebuT2A