mara/hyperhive
mara/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity
hyperhive/docs/2-handbook/hives/README.md
iris d516bb890c remove the forge links from the hive dashboard and the agent page 
Each agent row on the hive dashboard, and the agent page's link menu, linked
to the agent's forge profile and its config repo. Both are gone, with what
only they used:

- hive-agent no longer builds the two links, the `Forge` link kind, or the
  `forge_public_url` field of its state, and no longer reads
  `HIVE_FORGE_PUBLIC_URL`. The agent page's link menu and the dashboard row's
  icon strip (which skips a forge link an agent not yet rebuilt still sends)
  drop their forge handling.
- hive-c0re's dashboard state no longer carries `forge_public_url`.
- `HIVE_FORGE_PUBLIC_URL` is no longer forwarded to agents through the meta
  flake (the forwarded-variable list, its test fixture, the controller's
  settings and the VM test), so the next meta flake render differs by that
  one line. hive-c0re still reads it for the forge URL a hive publishes, so
  `swarm.forge.publicUrl` stays, with its description corrected.
- The docs stop describing the links.
2026-11-07 13:43:44 +01:00

5.7 KiB
Raw Blame History

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 instead.

  • Dashboard — every tab and standalone page of the per-hive dashboard, in full detail: endpoint shapes, event wiring, badge rules.
  • hivectl — the curated guide to the host CLI: provisioning forge and matrix accounts, container lifecycle shortcuts, interactive agent shell access.
  • hivectl-cli — the flag-by-flag reference, generated from the binary and kept in lockstep by CI.
  • The operator/agent boundary — 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. The tool surface agents get inside their containers is in 4-implementation/agent-tools/.

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 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). 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.

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.

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 says.

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

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) — the SPA skeleton, SSE multiplexing, terminal pane, listener bind, per-agent relative paths, the data-async form pattern and atomic repaint.
  • CSS theme variables — 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 — 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 (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 (the full row taxonomy and dispatch walkthrough); for a summary see web-page.md (Per-stream rendering).
  • "Which CSS variable to use, and where are the colours defined?" → css-vars.md (Palette, the single-source base.css rule).