hyperhive/docs/web-ui/README.md

Dashboard & Web UI

The per-hive dashboard: container state and the rebuild queue for one hive. For swarm-wide day to day, see the swarm UI instead. If you want implementation detail — wire formats, DOM structure, event plumbing — see Dashboard layout, Per-agent page, Shape, and CSS theme variables below; this page only covers what you actually do here.

Where things are

Everything starts at the dashboard, served at /. A pages menu (the link icon beside the profile avatar, at the right of the tab strip) links to the other surfaces — Stats, the API docs and the swarm UI — and each of those pages links back to the dashboard.

The dashboard is where you'll spend most of your time. It's a single page with four tabs:

• 4G3NTS — every agent, live. This is the default tab and the one you'll check most.
• R3BU1LD QU3U3 — the rebuild queue. A build's output and history are on the swarm's builds Grafana board.
• K3PT ST4T3 — kept state from agents with no container (tombstones), with a purge button per entry.

Usage stats live on their own page, reached from the pages menu: Stats (/stats.html, swarm-wide usage stats).

Each agent also has its own page — a full terminal view of that agent's session, reachable by selecting its name anywhere in the dashboard, or directly at /agent/<name>/ (or http://<host>:<port>/ if the gateway isn't in front).

The things you'll actually do

Check on an agent. 4G3NTS shows every container as a row: name, whether it's running, what it's currently doing (a live status pill — rebuilding…, starting…, or similar — while something's in flight), and quick links (stats, screen, forge profile). Select the name to open its terminal and watch it work in real time.

Review a config change. Agent config changes (new packages, env vars, MCP servers) are pull requests on the agent's agent-configs repo. Review and merge them on the forge; the merge deploys the change. See config-changes.md.

Start, stop, restart, or rebuild an agent. Select one or more agents on 4G3NTS (select the icon) and use the selection bar, or use the per-agent ⋮ menu on a single row. Rebuilding re-applies that agent's current config; use it whenever an agent shows as "needs update."

Watch a build. The dashboard's R3BU1LD QU3U3 tab shows the rebuild queue live, plus a streaming log of whatever's currently building. Useful right after merging a config change or bumping a flake input.

Grant or revoke a permission. Not on the hive dashboard: an agent's permissions live in the swarm. Set them with swarmctl agent permissions, or on the swarm UI's create-agent screen when creating the agent; see process/conventions.md.

Read an agent's logs. Logs aren't in the hive dashboard. Every hive ships its agents', daemons' and infra containers' journals to the swarm's VictoriaLogs; read them in Grafana's Explore — see swarm/services.md.

Set up a schedule. Scheduled prompts are swarm-level: set them with swarmctl schedule (swarm/schedules.md) or in the schedules card on the swarm UI's messages tab (swarm/ui.md).

More depth

Both the dashboard and the per-agent pages are SPAs sharing one skeleton: GET / returns a static shell, /api/state returns JSON, JS renders — no full-page reloads.

• Dashboard layout — every tab and standalone page, in full implementation detail: endpoint shapes, event wiring, exact badge-derivation rules.
• Per-agent page — the per-agent terminal, composer, side panel, slash commands, and per-agent endpoints.
• Shape (shared by both) — the SPA skeleton, SSE multiplexing, terminal pane, listener bind, per-agent relative paths, data-async form pattern, atomic repaint.
• CSS theme variables — the Catppuccin Mocha custom properties declared once in base.css and the rule that per-page stylesheets reference (never redeclare) them.
• swarm-ui design guide — visual language, motion, theming, error-UX, and component-first principles for the swarm-level Preact app specifically (not this page's dashboard/agent UIs). /components on a running swarm-ui is the companion living demo of every building block it references.

Implementation reading paths

Task-oriented jumps straight to the relevant section, for when you're touching the code rather than using the UI:

• "How does the dashboard SPA stay live without polling?" → shape.md (SSE multiplexing, Worker-death self-heal, atomic repaint).
• "What does a container row contain?" → dashboard.md (Container row, Selection bar).
• "What endpoints does the dashboard expose?" → dashboard.md (Dashboard endpoints, Dashboard event channel).
• "How does the per-agent terminal render tool calls?" → terminal-rendering.md (full row taxonomy and dispatch walkthrough); for a high-level summary see agent.md (Per-stream rendering).
• "What slash commands does the agent accept?" → agent.md (Terminal-embedded prompt).
• "What are the per-agent HTTP endpoints?" → agent.md (Per-agent endpoints).
• "Which CSS variable to use / where are colours defined?" → css-vars.md (Palette, single-source base.css rule).