vantage/README.md

Vantage

A desktop dashboard for a self-hosted homelab: per-host CPU / memory / disk / load / uptime, Docker container control, and HTTP / TCP health checks. Built with C# and Avalonia 11, targeting net6.0.

Vantage is designed to be dogfooded against a real VPS and lab hosts over SSH, but it runs fully offline out of the box using deterministic mock providers, so the UI and the whole data flow work without a single live host.

Architecture

Two projects plus two test projects:

• src/Vantage.Core - models, provider abstractions, parsers, health checks, config store. No UI dependency, fully unit tested.
• src/Vantage.App - the Avalonia application: views, view models, a hand-rolled sparkline control, dependency injection wiring.
• tests/Vantage.Core.Tests - parsers, providers, health checks, config store.
• tests/Vantage.App.Tests - view models and a headless Avalonia smoke test that loads the real window and binds the real view model.

Provider abstractions

Everything that touches a remote host sits behind an interface, with a real SSH implementation and a mock implementation:

• IMetricsProvider - SshMetricsProvider runs one batched shell command per poll (/proc/loadavg, /proc/uptime, /proc/meminfo, df, two /proc/stat snapshots for the CPU delta) and parses it; MockMetricsProvider synthesizes time-varying, per-host-stable metrics so sparklines animate offline.
• IDockerProvider - SshDockerProvider shells out to docker ps / docker start|stop|restart; MockDockerProvider keeps an in-memory container set whose state transitions on actions.
• IHealthChecker - HealthChecker is a real implementation (HttpClient for HTTP, TcpClient for TCP) and works against any reachable endpoint right now.

The SSH transport is isolated in ISshCommandRunner / SshNetCommandRunner. Because of that, the SSH providers are exercised in tests with a fake runner feeding captured command output - no live host needed to test the parse path.

Metrics parse path

The remote command emits marker lines (@@vantage:loadavg, @@vantage:df, ...). Each section has its own pure parser (LoadAvgParser, MemInfoParser, DfParser, ProcStatParser, CpuUsage), and MetricsBundleParser stitches them into a HostMetrics. Every parser is a pure function with a fixture-based test.

Wave 2 (depth)

Built additively on top of v1, all in Vantage.Core behind the same interface-plus-mock pattern:

• Metrics history - IMetricsStore / SqliteMetricsStore writes a time-series of cpu / memory / disk / load into SQLite (~/.config/vantage/history.db), with range queries and rolling retention (PruneOlderThanAsync). The monitor loop records every successful poll.
• Alerts - AlertRule (threshold + comparison + For duration + severity) evaluated per host by AlertRuleEvaluator (Ok -> Pending -> Firing, with a Resolved transition on recovery). AlertEngine fans transitions out to sinks: LogAlertSink (in-memory alert log), DesktopAlertSink (via an IDesktopNotifier seam), and WebhookAlertSink (POSTs JSON). The app wires the engine into the poll loop and shows live alert state in an Alerts tab.
• More collectors - each is parser + ISomethingProvider + SSH impl + mock: network rx/tx (/proc/net/dev + throughput delta), top processes (ps), systemd services (systemctl list-units), temperatures (/sys/class/thermal) and GPU (nvidia-smi).
• Log viewer - LogCommand builds journalctl -u ... -o short-iso or tail -n ... file (with an optional shell-quoted grep filter), LogLineParser splits timestamp / unit / message, behind ILogProvider (SSH + mock).
• Prometheus provider - PrometheusTextParser parses the text exposition format (labels with escapes, +Inf / -Inf / NaN, optional timestamp); PrometheusMetricsProvider scrapes a node_exporter /metrics endpoint and maps it to HostMetrics (CPU from a two-scrape counter delta). Select it with VANTAGE_PROVIDERS=prometheus.
• Multi-host view - OverviewViewModel aggregates online/offline counts, average and peak CPU, and firing-alert count; surfaced as a Fleet grid tab.

Running

Requires the .NET 6 SDK.

dotnet build
dotnet test
dotnet run --project src/Vantage.App

By default the app uses the mock providers, so it comes up populated with demo hosts and health checks and needs nothing configured. To point it at real hosts over SSH:

VANTAGE_PROVIDERS=ssh dotnet run --project src/Vantage.App

VANTAGE_PROVIDERS accepts mock (default), ssh, or prometheus.

Configuration

Host and health-check configuration persists as JSON at %APPDATA%/vantage/config.json (Linux: ~/.config/vantage/config.json). On first run with no config file, the app seeds demo data. The persistence layer (JsonConfigStore) is done and tested; for now edit that JSON file and restart to change hosts. An in-app editor is the next piece of UI (see below).

Verification status

• dotnet build is clean (0 warnings, 0 errors).
• dotnet test is green (110 tests): v1 parsers and providers, plus wave-2 coverage - SQLite time-series write/read/retention, alert-rule evaluation (pending/firing/resolved and the counterfactual "never fires early" cases), alert sinks (webhook posts JSON to a stubbed handler, log/desktop sinks), the network / process / systemd / thermal / GPU parsers, log command building and line parsing, the Prometheus text parser and node_exporter mapping (including two-scrape CPU rate), and the app-side wiring test proving a poll records history and fires an alert.
• A headless Avalonia test loads the actual MainWindow (Fleet / Host / Alerts / Docker / Health tabs), binds the real view model, and asserts the visual tree materialized.

This environment is headless (no X server), so the window's appearance has not been visually verified. Screenshots need to be taken on a machine with a display.

What is intentionally not in v1

• In-app host / health-check editor forms (config is file-based for now).
• SSH connection pooling (a fresh connection per poll today) and SSH-agent auth (SshAuthMethod.Agent throws a clear NotSupported until wired).
• Packaging / installers, mobile, live charting library (the sparkline is hand-rolled).