The dashboard mounts @hive/shared's AppShell, the header, nav and settings menu the swarm UI has, from a new shell.js: the hive's name for the brand, the tabs agents, rebuild queue and kept state routed by the URL hash, the theme, motion and solid-background settings in this page's own browser storage, and the shared links and user menus. The three tab panes stay plain DOM, kept hidden in index.html and moved into the shell's content column by shell.js. The tabs, the hash-to-tab parse and the menu entries sit in shell-routes.js, which npm test covers (the dashboard package gets a test script). The old header, the createTabStrip tabbar, the leet tab names, the identity headline and title code, the sticky-top wrapper, the links-menu.js and user-menu.js mounts and their CSS are removed. The docs say the plain tab names and the new chrome.
112 lines
5.6 KiB
Markdown
112 lines
5.6 KiB
Markdown
# 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:
|
|
|
|
- **agents** — every agent, live. This is the default tab and the one you
|
|
check most.
|
|
- **rebuild queue** — the rebuild queue. A build's output and history are on
|
|
the swarm's `builds` Grafana board.
|
|
- **kept state** — kept state from agents with no container (tombstones),
|
|
with a purge button per entry.
|
|
|
|
Each agent also serves a small web server, with its stats and screen pages: open
|
|
`/agent/<name>/` (or `http://<host>:<port>/` if the gateway isn't in front).
|
|
[The agent's web server](../agents/web-page.md) covers it. To watch an agent
|
|
work, use its terminal in the swarm UI.
|
|
|
|
## 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).
|
|
Open the agent in the swarm UI to 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
|
|
[`persistence.md`](../agents/persistence.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 swarm page ([`swarm-ui.md`](../../4-implementation/web-ui/swarm-ui.md)).
|
|
|
|
## More depth
|
|
|
|
The dashboard is a single-page app: `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`](../../4-implementation/web-ui/dashboard.md) (Container row,
|
|
Selection bar).
|
|
- **"What endpoints does the dashboard expose?"** →
|
|
[`dashboard.md`](../../4-implementation/web-ui/dashboard.md) (Dashboard endpoints,
|
|
Dashboard event channel).
|
|
- **"How does a terminal render tool calls?"** →
|
|
[`terminal-rendering.md`](../../4-implementation/web-ui/terminal-rendering.md)
|
|
(the full row taxonomy and dispatch walkthrough).
|
|
- **"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).
|