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](../swarm/ui.md) instead. If you want implementation
detail — wire formats, DOM structure, event plumbing — see [Dashboard
layout](dashboard.md), [Per-agent page](agent.md), [Shape](shape.md),
and [CSS theme variables](css-vars.md) 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`](../agent-lifecycle/config-changes.md#config-changes).

**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`](../process/conventions.md#permissions).

**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`](../swarm/services.md#logs-victorialogs).

**Set up a schedule.** Scheduled prompts are swarm-level: set them with
`swarmctl schedule` ([`swarm/schedules.md`](../swarm/schedules.md)) or
in the schedules card on the swarm UI's messages tab ([`swarm/ui.md`](../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](dashboard.md)** — every tab and standalone page,
  in full implementation detail: endpoint shapes, event wiring, exact
  badge-derivation rules.
- **[Per-agent page](agent.md)** — the per-agent terminal, composer,
  side panel, slash commands, and per-agent endpoints.
- **[Shape (shared by both)](shape.md)** — the SPA skeleton, SSE
  multiplexing, terminal pane, listener bind, per-agent relative
  paths, `data-async` form pattern, atomic repaint.
- **[CSS theme variables](css-vars.md)** — 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](design-guide.md)** — 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`](shape.md) (SSE multiplexing, Worker-death self-heal,
  atomic repaint).
- **"What does a container row contain?"** →
  [`dashboard.md`](dashboard.md) (Container row, Selection bar).
- **"What endpoints does the dashboard expose?"** →
  [`dashboard.md`](dashboard.md) (Dashboard endpoints, Dashboard event
  channel).
- **"How does the per-agent terminal render tool calls?"** →
  [`terminal-rendering.md`](terminal-rendering.md) (full row taxonomy
  and dispatch walkthrough); for a high-level summary see
  [`agent.md`](agent.md) (Per-stream rendering).
- **"What slash commands does the agent accept?"** →
  [`agent.md`](agent.md) (Terminal-embedded prompt).
- **"What are the per-agent HTTP endpoints?"** →
  [`agent.md`](agent.md) (Per-agent endpoints).
- **"Which CSS variable to use / where are colours defined?"** →
  [`css-vars.md`](css-vars.md) (Palette, single-source `base.css`
  rule).