Watch Over All Realms — a lightweight, cross-platform hardware monitoring system with a real-time terminal dashboard.
Start here, then jump to the guide for what you want to do.
🎉 v2.0.0 — the everything socket release is out: on-demand commands, in-dashboard logs & process view, and a JSON CLI, all with no inbound port on any host. → Release notes.
- Installation — get the binaries
- Quickstart — monitor your own machine in ~2 minutes
- Using the Dashboard — drive the TUI: navigation, logs, top, commands, search
- Architecture & Operations — how the pieces fit, with diagrams
| Guide | Use it when you want to… |
|---|---|
| Quickstart | watch a single machine (all-in-one) |
| Monitor a Fleet | watch many hosts from one station |
| Using the Dashboard | drive the TUI after setup — navigation, detail, logs, top, commands, search/filter, every key |
| Secure Deployment | require TLS + an enrollment token |
| Privileged Metrics | unlock power, GPU, and full thermal (overview + deployment) |
| ↳ macOS / Apple Silicon | IOReport GPU/power, SMC CPU + whole-system power, ANE |
| ↳ Linux + NVIDIA | GPU via nvidia-smi, CPU power via RAPL (helper) |
| ↳ Linux + AMD | Radeon / Strix Halo via amd-smi or amdgpu sysfs |
| ↳ Windows | WMI thermal, nvidia-smi GPU, CPU power via Scaphandre |
| Federation (Bifröst) | span multiple sites / networks |
| Process View & Commands | see a host's process table (top) and run allow-listed diagnostics |
| Log Streaming | tail host logs in the dashboard |
| Demo Mode | explore the UI with no setup |
| Metrics Export (Mímir) | scrape Heimdall from Prometheus / Grafana |
| Alerting (Gjallarhorn) | fire threshold alerts to a webhook |
heimdall-cli (programmatic & agents) |
query the fleet from scripts, CI/CD, or an AI agent |
| Top View (Hliðskjálf) | watch one host mactop-style — per-core, power, GPU/NPU, processes |
| Standardization & Adapters | contributors: how to add a cross-platform metric — adapters normalise, domain standardizes, consumers render |
| Doc | Contents |
|---|---|
| Configuration | every flag, env var, and the config file + first-run wizard, per binary |
| Metrics | every metric collected, with units and meaning |
| Glossary | codenames (Bifröst, Ratatoskr, …) and how to pronounce them |
| Architecture & Operations | topology, what-runs-where, sequence diagrams, ports |
| Troubleshooting | common issues and host-liveness states |
| Binary | Runs on | Privilege | Job |
|---|---|---|---|
heimdall-hub |
monitoring station | normal | receives metrics, fans out to dashboards, mediates directives |
heimdall-dashboard |
monitoring station (any number) | normal | renders the fleet — pure presentation |
heimdall-daemon |
every host | unprivileged | collects + streams metrics; pushes opt-in logs/processes; runs allow-listed commands |
heimdall-helper |
a host (optional) | root | serves privileged metrics + runs privileged allow-listed commands for the daemon |
heimdall-cli |
anywhere | normal | machine/AI-friendly JSON client over a hub (scripts, CI/CD, agents) |
Data flow: daemon → hub → dashboard(s) / cli; the helper is a local sidecar to a daemon (helper → daemon over a unix socket).
- System architecture
- Architecture Decision Records — enrollment, adapters, helper, GPU/power, federation, control plane, storage
- User stories — the Gherkin specs each feature implements
- Brand & terminal identity
make build-tui # build all five binaries
make test # unit tests
make lint # gofmt + go vet
make test-acceptance # behave acceptance suite (drives the real binaries)