Infra Atlas
A Hermes Agent plugin that turns a Markdown infrastructure registry into a live,
self-healing infrastructure graph — and enforces the rule that an agent reads the
documentation before it touches the box.

- Knowledge layer —
servers/,services/,projects/entries with optional YAML
frontmatter; legacy prose-only entries are parsed heuristically so nothing has to be
rewritten by hand. - Live layer — zero-config discovery of this host (systemd user/system units, listening
ports, Docker/Podman, the Tailscale CLI) and of the Hermes runtime (model endpoints, MCP
servers, cron jobs and their freshness); opt-in Proxmox VE and Headscale APIs; bounded
TCP/HTTP probes. - Fusion layer — every node is classified as
matched,changed,unregistered,
staleordoc_only, with field-level evidence, and one call adopts reality back into
the Markdown. - Read-before-you-touch guardrail — a
pre_tool_callpolicy hook blocks a
terminal/write_file/patchcall that touches a documented host, VM, container,
IP, systemd unit or project path when the session has not read that entry yet, and tells
the agent exactly which entry to read (including the pitfalls you documented). - Uptime + autonomous downtime response — rolling probe history, flap suppression,
incidents, and a two-stage heal: a deterministic local restart playbook first, then the
agent itself, woken with the node's own runbook as the brief. Healthy ticks cost zero
LLM tokens ({"wakeAgent": false}).
Install
hermes plugins install <owner>/infra-atlas # or link a checkout:
ln -s ~/src/infra-atlas ~/.hermes/plugins/infra-atlas
hermes plugins enable infra-atlas
Then open Infra Atlas in the desktop sidebar (or ⌘K → “Infra Atlas: open the
infrastructure graph”). The desktop half is opt-in: flip it on in Capabilities → Plugins.
First five minutes
/atlas # counts, guardrail mode, open incidents
infra_bootstrap # add frontmatter to an existing Markdown registry
infra_sweep # discover + probe + diff
infra_query node_id=… # read one entry (and unlock it for this session)
No registry yet? infra_bootstrap mode=scaffold_from_live writes a starter directory from
what the collectors can actually see (this host, the Hermes runtime, and Proxmox or Headscale
when those are configured). To see the whole thing working without touching a real machine,
point registry_path at the fictional fleet in examples/registry and
run infra_sweep — six entries, documentation addresses only, one retiring and two failing
on purpose.
The registry entry
---
id: svc-litellm
kind: service
label: LiteLLM Gateway
parent_id: lxc-201
host_ip: 10.0.0.212
ports: [4000]
managed_by: systemd-system
systemd_unit: litellm.service
probe: http://10.0.0.212:4000/health/liveliness
recovery_cmd: "systemctl restart litellm.service"
auto_heal_policy: auto
depends_on: [svc-litellm-postgres]
pitfalls: "Dial 10.0.0.212:4000 directly; the old front was removed."
---
# LiteLLM Gateway
…your runbook, untouched…
infra_upsert merges frontmatter and never truncates the prose below it; it also updates
INDEX.md and prepends a change-log.md entry.
kind decides which terrace a node lands on, so an entry that sits in servers/ but is
really a guest is corrected at parse time: anything with a vmid — or a Proxmox guest with
a parent_id — is drawn as a VM on COMPUTE, not as metal on HARDWARE. A hypervisor has no
vmid, so the test is safe both ways, and you never have to file entries in a different folder
to get the picture right.
pitfalls is surfaced in the guardrail
block message and in the outage brief, so the operator's hard-won rules reach the agent at
the moment they matter.
Tools
| Tool | What it does |
|---|---|
infra_query | Read a node (runbook + live diff + uptime + blast radius). Unlocks it for write/terminal use in this session. |
infra_sweep | Run collectors + probes, recompute drift, evaluate incidents, attempt the safe local heal. |
infra_diff | What changed, which incidents opened, who touched what — over a window. |
infra_upsert | Create/update/adopt/remove a registry entry, with change-log. |
infra_bootstrap | Annotate an existing KB, or scaffold one from live discovery. |
infra_incidents | List/get/heal/resolve/escalate incidents; install the zero-token watchdog. heal runs the documented restart through Hermes' command approval. |
infra_credentials | Private credential vault: list, get (gated), set/rotate, remove, and scan the KB for literals. |
Bundled skill: infra-atlas:infra-atlas (loaded automatically when the plugin is enabled).
Settings
registry_path, credentials_path / credentials_key_path (see below),
guardrail_mode (block/warn/off), auto_heal_mode
(notify_only (default) / auto / playbook_only / off), failure_threshold, heal_cooldown_sec,
the three zero-config collectors, and the opt-in Proxmox/Headscale
credentials (secrets go to .env through Hermes and are read with agent.secret_scope).
registry_path, credentials_path and credentials_key_path all default to empty, which
means "under the active profile's data dir" (ctx.state.data_dir). Two profiles therefore never
share a vault or a registry. An existing ~/.hermes/infra-registry keeps being used when it is
present, so upgrading changes nothing on disk.
Credentials never live in the registry
The registry is documentation — it is read by agents, mirrored to Nextcloud and
committed to git, so a password in a runbook is a leak in triplicate. Entries
reference credentials by name:
---
id: srv-cyberfield
kind: server
credentials: [cyberfield-pve-token, cyberfield-root-ssh]
---
The value lives in a private vault under $HERMES_HOME/plugin-data/infra-atlas/
(settings credentials_path / credentials_key_path), written through
infra_credentials:
- the file is
0600in a0700directory and Fernet-encrypted with a0600
key whencryptographyis installed; without it the vault records
encrypted: falserather than pretending, action="list"returns names, owners and stored/missing status — never values,action="get"returns one value, records the read in the activity ledger, and
refuses unless the node's registry entry was read first,action="set"/"remove"require areason, writechange-log.md, and never
echo the value back,action="scan"finds credential literals still sitting in the Markdown (masked
previews only) so they can be migrated into the vault.
The dashboard exposes GET /api/plugins/infra-atlas/credentials (masked list).
Writes are agent-side only — the vault is never writable over HTTP.
What it touches
- Reads the registry directory,
$HERMES_HOME/cron/jobs.json, the Hermes config
(read-only),/proc/net/tcp, and — only when configured — the Proxmox and Headscale
APIs. - Writes only inside the registry directory (entry files,
INDEX.md,change-log.md)
and its own SQLite database under the active profile'splugin-data/infra-atlas/.
Every write path is validated: the node id must match^[a-z0-9][a-z0-9._-]{0,63}$and
the resolved file must stay inside the registry root. - Runs commands only for
recovery_cmd, only on this host, and only when the command is
exactly one allow-listed restart shape —systemctl [--user] restart|start <unit>,
service <unit> restart|start,docker compose restart|start|up [-d]inside a
registry-declaredproject_path, orpct|qm start <vmid>. Power-state verbs (stop,
disable),destroy,exec,podman run,docker compose down, and anything carrying a
shell metacharacter are refused. - Never executes a restart itself. The command is dispatched through the host
terminal
tool, so Hermes' dangerous-command approval applies exactly as if the agent had typed it.
A process with no approval channel — the cron watchdog, the dashboard backend — does not
run restarts at all; it opens the incident and hands the agent the brief.
recovery_cmdis therefore not writable throughinfra_upsert: it is an operator
field in the registry entry. auto_heal_modedefaults tonotify_only— record the incident and wake the agent.
autoadditionally lets the agent-side sweep attempt the allow-listed restart (still
through approval);playbook_onlynever wakes the agent;offdisables the response.- Blocks mutating tool calls while the guardrail is in
blockmode; set it towarnor
offto disable. Inspection is never blocked and never unlocks:systemctl status|cat|show,
journalctl,docker ps|logs|inspect,qm list,pvesh get,ip addr, a plaincurl/wget
GET. A-X POST/-d/--datarequest, or anysystemctl start|stop|restart|reload|enable,
still requires the entry to have been read. - Passes a minimal environment to every child process:
PATH,LANG/LC_ALL,
SYSTEMD_PAGER, plusXDG_RUNTIME_DIR/DBUS_SESSION_BUS_ADDRESSforsystemctl --user.
The agent's API keys and tokens are never inherited.
No telemetry, no network calls to anything not configured above.
Layout
plugin.yaml manifest (tools, hooks, settings)
__init__.py register(ctx)
registry_kb.py Markdown ↔ node model, atomic writer, change-log
credentials.py private 0600 credential vault + registry literal scanner
collectors/ local host, Hermes runtime, Proxmox, Headscale, probes
fusion.py correlation + drift classification + sweep
uptime.py probes → incidents → playbook/agent response, watchdog script
matcher.py tool call → nodes (IPs, units, VMIDs, paths)
hooks.py pre_tool_call guardrail, post_tool_call activity
atlas_tools.py the seven tools
dashboard/ FastAPI routes under /api/plugins/infra-atlas
desktop/plugin.js full-page graph, inspector, statusbar chip, ::infra / ::drift cards
skills/infra-atlas/ the bundled protocol skill
tests/ pytest suite (registry, fusion, gate, uptime, collectors, API, registration)
Tests
After a reload, the page tells you which bundle it is running:
`document.querySelector('.ia-root').dataset.build` in the desktop devtools. It is bumped on
every shipped change.
tools/check.sh # every gate: compile, syntax, 8 surfaces, gestures,
# layout, manifest validation, pytest, coverage floor
PYTHONPATH=<hermes-agent checkout> python -m pytest
PYTHONPATH=<hermes-agent checkout> python -m coverage run --source=. --omit='tests/*,tools/*,desktop/*' -m pytest
python -m coverage report # 82% of statements; tools/check.sh fails under 75%
hermes plugins doctor .
hermes plugins validate .
The desktop half has its own check — it is loaded uncompiled by the app, so a bad
component only fails at render time:
node tools/render_smoke.mjs --modules /path/to/a/node_modules # needs react + react-dom
It renders every registered surface (page, chip, both transcript cards) with
react-dom/server against a stubbed @hermes/plugin-sdk, fails on any crash,
and asserts that the page actually renders the isometric scene (platforms,
per-kind shapes, routed edges, packets). Eight of eight surfaces render on this
tree.
The isometric topology
The page draws the fleet as a terraced isometric diorama (SVG, viewBox
pan/zoom — still selectable, keyboard-reachable and crisp at any zoom):
- One terrace per stratum (hardware → compute → services → agents), cascading
downhill toward the viewer so dependency edges literally flow down the hill.
Terrace fronts drop to the base plane and slope risers fuse them into one
landmass. - Every node kind is its own 3-D silhouette: server = LED-blinking rack,
VM = tower with a scanning screen, LXC = tank whose liquid level tracks
uptime, container = corrugated cargo crate with doors, service = pad,
inference server = low GPU chassis with two spinning fan discs and a heat
shimmer, project = plate, agent = hovering bot, model endpoint = orbiting
orb, cron = clock with a rotating hand, peer = pyramid with ping rings.
Health is a colored beacon; drift is a floating chip and an underglow. - Container and inference silhouettes are inferred, not hand-filed: an entry
managed by docker/podman/compose draws as a crate, and one that names a model
server (llama-server, llama.cpp, vLLM, Ollama, SGLang, TensorRT-LLM, TGI,
llama.cpp forks…) draws as a GPU rig — while its control plane (dashboard,
control, proxy, metrics shim, router) stays a plain service. - Edges are routed on the tile grid (A* with footprint obstacles + congestion
cost): parallel connections fan into side-by-side lanes, terrace steps are
crossed squarely, and each relation has its own color, dash rhythm and a
travelling packet dot. - Micro-animations (entrance drop-in, LEDs, slosh, scanline, bob, orbit, flow),
phase-shifted per node, suppressed on large fleets (see Decoration is data)
and disabled underprefers-reduced-motion. Guardrail pulses keep their
semantics: blocked
calls shake the node with red ripples and scatter red packets along its
edges; reads and allowed touches flash cyan/green. - Guests follow their hypervisor. Within a terrace a node whose parent sits in a lower
terrace sorts by the parent's position, so the VMs of a host land together in the same part
of the grid as that host, ahead of unrelated nodes that happen to sort earlier. - Tailnet peers report
upwhen online andunknownwhen not: a laptop with the lid shut is
not an outage, and eighteen red beacons would drown the fleet's real signal. - Terraces pack up to three rows deep and the depth is chosen per tier: every row
combination (at most 3⁴) is measured and the one closest to a 1.4:1 footprint wins, with
the most compact packing breaking ties. A forty-service tier becomes 14×3 instead of a
40-tile ribbon, so a big fleet reads as a block rather than a letterbox.
The page around it stays deliberately sparse:
- One floating command bar — brand + live 24h fleet uptime + sweep age, the view switcher
(Live/Alerts/Synced/All), inline search, a single policy popover (guardrail
mode, downtime response, background watchdog), and one primarySweepaction. - A slide-over inspector drawer that only exists while a node is selected: one contextual
primary action (Adopt Live Driftwhen it has drifted,Run Playbookwhen it is down), a
symmetric secondary row (Unlock Chat,Ask Hermes), and three tabs —Overview
(pitfalls callout, field-by-field diff, properties, clickable blast radius),Uptime
(24h %, latency sparkline, probe target, incident history with inline resolve),Runbook. - Direct manipulation: drag to pan (content follows the cursor), a mouse-wheel notch or
trackpad pinch zooms around the pointer, two-finger trackpad scrolling pans, double-click
zooms in (shift double-click out), and the− 100% +cluster resets or steps. The camera is
owned imperatively — a drag survives the pointer crossing the toolbar, the drawer or the
window edge, and labels freeze while it moves so the scene keeps its frame rate. Gestures are handled imperatively — the viewBox is written in a
rAF and React state only syncs when the gesture ends — so a hundred-node fleet pans at
frame rate instead of re-rendering the whole tree per pointermove. - Both themes, by construction. The diorama derives its whole palette from the two values
the plugin host provides —--card(surface) and--foreground(ink): the ground is the
card colour, node bodies are a card/ink mix tinted 14% with the kind's accent, terraces are
the same mix with a tier tint, labels use the ink with a card-coloured halo. Nothing is
hard-coded to one theme, so a light app gets light terraces and dark labels and a dark app
gets the inverse, with contrast around 7:1 (dark) and 9:1 (light). A lightweight probe only
tunes shadows and the glow. - Decoration is data. Past ~44 nodes the canvas goes lean: perpetual LED/scan/packet
animation is kept only for the selected node, nodes with incidents and their edges, and
everything else holds still (andprefers-reduced-motionwins everywhere). - Two corner docks: a collapsible live-activity feed (reads / touches / blocked calls) and
a combined zoom + legend control.Escor a click on empty canvas closes the drawer and
gives the whole viewport back to the map. - Retired entries stay off the map. An entry with
status: removedis history, not
infrastructure: it is not drawn as an empty shape, not probed, and not counted in the
Allbadge (the legend says how many are hidden). Opening one anyway — a stale selection,
a::infra{}link — explains that it is retired and offers Restore to active, instead
of showing a panel full of empty fields.
To see it live without the desktop app:
node tools/iso_preview.mjs # then open the printed URL
# ?fleet=stub | live | single | flat — the control bar can fire guardrail pulses so you
# can watch the shake/ripple animations.
MIT.
README from the reviewed commit 5e3e602; it updates when the author re-pins.

hnasheralneam