hyperhive/docs/2-handbook/hives/README.md

# Hives

A **hive** is one host running `hive-c0re` and its agent containers. This
section is for the operator of that host: the per-hive dashboard, the
`hivectl` CLI and the operator/agent trust boundary on the host. For what
the whole swarm shares, see [the swarm UI](../swarm/ui.md) instead.

- **[Dashboard](dashboard.md)** — every tab and standalone page of the
  per-hive dashboard, in full detail: endpoint shapes, event wiring, badge
  rules.
- **[hivectl](hivectl.md)** — the curated guide to the host CLI:
  provisioning forge and matrix accounts, container lifecycle shortcuts,
  interactive agent shell access.
- **[hivectl-cli](hivectl-cli.md)** — the flag-by-flag reference,
  generated from the binary and kept in lockstep by CI.
- **[The operator/agent boundary](boundary.md)** — what the operator may do
  that an agent may not, and why the line sits where it does.

For `swarmctl`, the swarm operator's CLI, see
[`swarmctl-cli.md`](../swarm/swarmctl-cli.md). The tool surface agents get
inside their containers is in
[`4-implementation/agent-tools/`](../../4-implementation/agent-tools/README.md).

## 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: the API docs and the swarm UI.

The dashboard is a single page with these tabs:

- **4G3NTS** — every agent, live. This is the default tab and the one you
  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.

Each agent also has its own page, a full terminal view of that agent's
session. Select its name anywhere in the dashboard, or open `/agent/<name>/`
(or `http://<host>:<port>/` if the gateway isn't in front). [The agent's web page](../agents/web-page.md)
covers it.

## The things you do here

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

**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`](../agents/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 downloads and applies the closure the swarm
declares for the agent again. The hive applies a changed declaration itself,
so use it to retry one that failed.

**Watch a build.** The R3BU1LD QU3U3 tab shows the rebuild queue live, plus a
streaming log of whatever's 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
[`5-project/process/conventions.md`](../../5-project/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**, as
[`swarm/services.md`](../swarm/services.md#logs-victorialogs) says.

**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

The dashboard and the per-agent pages are single-page apps that share one
skeleton: `GET /` returns a static shell, `/api/state` returns JSON, and
JavaScript renders, with no full-page reloads.

- **[Shape (shared by both)](../../4-implementation/web-ui/shape.md)** — the
  SPA skeleton, SSE multiplexing, terminal pane, listener bind, per-agent
  relative paths, the `data-async` form pattern and atomic repaint.
- **[CSS theme variables](../../4-implementation/web-ui/css-vars.md)** — the
  Catppuccin Mocha custom properties declared once in `base.css`, and the
  rule that per-page stylesheets reference them and never redeclare them.
- **[swarm-ui design guide](../../5-project/web-ui/design-guide.md)** — the
  visual language, motion, theming, error UX and component-first principles
  for the swarm-level Preact app. `/components` on a running swarm UI is the
  living demo of every building block it names.

For the code, these jump straight to the relevant section:

- **"How does the dashboard SPA stay live without polling?"** →
  [`shape.md`](../../4-implementation/web-ui/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`](../../4-implementation/web-ui/terminal-rendering.md)
  (the full row taxonomy and dispatch walkthrough); for a summary see
  [`web-page.md`](../agents/web-page.md) (Per-stream rendering).
- **"Which CSS variable to use, and where are the colours defined?"** →
  [`css-vars.md`](../../4-implementation/web-ui/css-vars.md) (Palette, the
  single-source `base.css` rule).