Browser-based homelab cluster management sim — walk your Kubernetes settlement built from live cluster scans, inspect Flux HelmReleases, ingress, storage, networking, and respond to alerts as missions.
| GitHub | nerddotdad/hearth |
| Image | ghcr.io/nerddotdad/hearth |
| Cluster pin | truecharts → clusters/.../observability/hearth/ |
- Godot 4 client (
godot/) — snap navigation, districts, belts, inspector, options menu - Python API (
bridge.py+cluster/) — parallel K8s scan →/api/world - Auto-refresh — world rescans every 20s (configurable in-game)
There is no demo/offline mode. If the Kubernetes API is unreachable, the client shows an error with setup hints.
Alert ingest (POST /hook), Hermes agents, sandbox triage, and ntfy notifications remain on the backend.
Requires a real cluster connection via kubeconfig or port-forward to the in-cluster pod.
# Ensure homelab kubeconfig (example)
clustertool talos kubeconfig
kubectl get nodes
# Terminal 1 — API (uses KUBECONFIG)
pip install -r requirements.txt
python3 bridge.py
# Terminal 2 — Godot editor
# Open godot/project.godot and press F5Web export (optional — same origin as API):
./godot/scripts/export_web.sh
python3 bridge.py
# http://127.0.0.1:8000/Alternative: kubectl -n observability port-forward svc/hearth 8000:8000 and skip local bridge.py.
| Endpoint | Purpose |
|---|---|
GET /health |
Service health + version |
GET /api/world |
Live cluster world snapshot (503 if API unavailable) |
GET /api/world/defaults |
World layout settings schema |
GET /api/object/describe |
kubectl-style object detail |
POST /hook |
Alertmanager webhook ingest |
| Variable | Purpose |
|---|---|
KUBECONFIG |
Local dev cluster credentials |
HEARTH_MAX_BUILDINGS_PER_DISTRICT |
Server default for buildings cap (overridden by client headers) |
HEARTH_MAX_CALL_BELTS_PER_DISTRICT |
Server default for cross-app belts |
HEARTH_STATIC |
Path to Godot web export (godot/export/web) |
INCIDENT_DIR |
SQLite + settings directory (defaults to .data/incidents) |
hearth/
├── bridge.py # HTTP API + static UI server
├── cluster/ # K8s scan → world JSON + belt layout
├── godot/ # Godot 4 game client (primary UI)
├── integrations/ # Prometheus, ntfy, Hermes
├── sandbox/ # Triage pods + MCP
└── hermes_plugin/ # Hermes secret-source plugin
CI exports the Godot web client, then builds the Python image with godot/export/web baked in. The Hearth pod uses its in-cluster ServiceAccount (read-only RBAC) to scan the cluster. Hermes Agent runs as a sidecar.