Why a living scene instead of a dashboard

Most homelab dashboards are grids of status tiles — accurate, but static and a little forgettable. I wanted something that felt like it was actually alive: a WebGL scene rendered in the browser, showing the real Proxmox nodes, the real Kubernetes cluster, and the firewall, colored by real health data, updating without a page reload. Not a decoration disconnected from reality — a genuinely honest representation of what's running, right now.

The scene shows three real Proxmox hosts as hexagons, a ring representing the Kubernetes cluster, a separate plate for the firewall appliance, and a central sphere representing the small team of AI agents that helps operate this lab. Only infrastructure elements I've explicitly chosen to expose ever appear — nothing is inferred or guessed at.

The source of truth: topology.json, plus a live cache

The scene's data comes from two things merged together on every request:

• A small, versioned overlay file (config/topology.json) declaring what's expected to exist: which physical nodes, which links between them, and an explicit allow-list of which guest VMs/containers are even eligible to appear in the scene at all, by internal ID. A VM that exists in the cluster but isn't on this allow-list is never shown — that's a safety choice (allow-list, not a blocklist to maintain).
• A short-lived cache of the real, live state from the hypervisor API (which nodes are online, which guests are actually running and where).

The two are merged at request time, on the server, before anything is sent to your browser: the public API response never contains a raw internal VM ID, only public labels and statuses. If a VM migrates from one physical host to another, the scene reflects that automatically on the next refresh — no code change, no redeploy needed for that kind of update. What does need a manual edit is adding an entirely new physical node: the overlay is deliberately authoritative rather than guessing, which is a trade-off — see the technical note below.

Isolated by design — the probe never reaches into the protected network

The firewall protecting this lab's internal network sits on a segment that is intentionally unreachable from the servers running this portal — that isolation is a deliberate security boundary, not an oversight, and it's not something I was willing to poke a hole through just to display a green dot on a web page.

So instead of the portal pulling status from the firewall, a small administrative host that already legitimately sits on that protected segment pushes a health report outward every 30 seconds, authenticated with a dedicated, low-privilege API account and a pinned TLS certificate. The portal only ever receives; it never initiates a connection into the protected zone. If those push reports stop arriving, the portal doesn't assume the firewall is down — it shows an honest "unknown/stale" state rather than a false alarm, because "no news" and "bad news" are genuinely different things.

A physical touch: a Raspberry Pi kiosk

A small Raspberry Pi, running a browser in kiosk mode, sits pointed at this very page, so the scene is also visible as a physical, always-on display in the room where the lab lives — a nice reminder that all of this represents real, physical hardware, not just numbers in a browser tab.

The honest trade-off

Building this taught me a very transferable lesson: an allow-list and a declarative overlay are excellent for safety (nothing leaks by accident), but they come at the cost of a manual step whenever something genuinely new joins the infrastructure. I'd rather have that small manual step than a system that silently infers things that shouldn't be inferred.