How kinncj/heimdall works
Heimdall collects host hardware and observability data with outbound-only daemons, sends it to a central hub, and presents the fleet through a terminal dashboard or JSON CLI. The hub also supports federation, alerts, durable and OpenMetrics export, discovery, and on-demand diagnostics. The principal flow is documented in the README and daemon excerpt; several secondary subsystem links are included only where the README explicitly describes them, since their implementation excerpts were not provided.
Main entry points: hub.go Hub server · daemon/main.go Metrics daemon · dashboard/main.go Dashboard client · cli.go JSON CLI
Components 20
Host collection
- Metrics daemon
app/cmd/daemon/main.go - Metric adapters
app/internal/adapters - Privileged helper
app/internal/helper/server.go - Log streaming
app/internal/logs/server.go - Process view
app/internal/proc/proc.go
Hub services
- Hub server
app/internal/hub/hub.go - Threshold alerts
app/internal/alert/engine.go - Hub federation
app/internal/hub/relay.go - mDNS discovery
app/internal/discovery/mdns.go - Metric storage
app/internal/store/prometheus.go - Metrics export
app/internal/observe/server.go
Fleet presentation
- Dashboard client
app/cmd/dashboard/main.go - Terminal interface
app/internal/tui/dashboard/model.go - JSON CLI
app/internal/cli/cli.go
Shared model
- Monitoring contract
common/proto/monitoring/v1/monitoring.proto - Host registry
app/internal/domain/hostregistry.go
External interfaces
- Prometheus scraper
- Alert webhook
- Parent hub
Other components
- Operator
Connections 24
- Operator → Metrics daemon: starts
- Metrics daemon → Metric adapters: samples
app/cmd/daemon/main.go - Metrics daemon → Privileged helper: requests privileged data
- Metrics daemon → Log streaming: pushes opted-in logs
- Metrics daemon → Process view: pushes process table
- Metrics daemon → Monitoring contract: streams snapshots
- Metrics daemon → Hub server: streams metrics
- Hub server → Host registry: updates host views
- Hub server → Monitoring contract: serves gRPC contract
- Hub server → Threshold alerts: evaluates rules
- Threshold alerts → Alert webhook: notifies transitions
- Hub server → Hub federation: relays upstream
- Hub federation → Parent hub: sends snapshots
- Hub server → Metric storage: persists metrics
- Hub server → Metrics export: exports fleet metrics
- Prometheus scraper → Metrics export: scrapes metrics
- Operator → Dashboard client: opens fleet view
- Dashboard client → Hub server: subscribes
- Dashboard client → mDNS discovery: resolves hub
- Dashboard client → Terminal interface: renders fleet
app/cmd/dashboard/main.go - Operator → JSON CLI: runs queries
- JSON CLI → Hub server: queries fleet
- Dashboard client → Hub server: routes commands
- JSON CLI → Hub server: runs commands