hyperhive/docs/README.md

hyperhive docs

Depth reference for hyperhive — the substrate, not the pitch (that's the top-level README / website). Every page here stands alone; pick the one matching your task rather than reading top to bottom. For the auto-generated NixOS options reference (every services.hyperhive.* / hyperhive.* option, host and agent), see the options site instead — this tree is prose, that one's generated straight from the module declarations.

Getting started

• Bringing a fresh hive online? → setup.md (first-run hivectl bootstrap).
• What does the dashboard look like, and how do I use it? → web-ui/ — the operator-facing starting point; its own sub-pages (shape, dashboard, agent, css-vars) go deeper into implementation.
• What tools does an agent (or the operator) have available? → tools/ — hivectl (yours) plus every agent's MCP tool surface (bash, forge, lifecycle, matrix, scheduling).

Dashboard & agent UI internals

• How does the per-agent terminal classify + colour events? → terminal-rendering.md.

Turn loop, config, approvals

• How does claude get its prompt, and what tools does it have? → turn-loop/ — the loop, binary shape, turn outcomes; sub-pages: claude-invocation, config, mcp.
• How do config changes flow from manager to operator to container? → approvals.md (two-step spawn, approval state machine, flake.lock validation).
• What state survives destroy / purge / restart? → persistence.md.

Trust boundary & security

• What's the operator/agent trust boundary? What's a capability? → boundary.md.
• Agent trust model, prompt-injection threat model, credential isolation? → security.md.
• Who can do what to whom — agent hierarchy and privilege? → agent-hierarchy.md.

Accounts & integrations

• How do per-agent forge accounts work? What does forge_notify poll, and how does it format wake messages? → forge.md (the hive's own Forgejo); tools/forge.md for the hive-forge CLI verbs agents actually call.
• How does the matrix-tuwunel container work? Multiple accounts per agent? → matrix.md (the homeserver); tools/matrix.md for the MCP tool surface and hyperhive.matrixAccounts.
• How do I give an agent a GitHub account (gh + git push)? How is the PAT injected? → github.md.
• What does hivectl do? Provisioning, gateway users, container shells? → tools/hivectl.md (the curated guide); tools/hivectl-cli.md for the exhaustive, auto-generated flag reference.

Networking & swarms

• What nginx vhosts does the gateway serve? How does matrix discovery work? → gateway.md.
• How does DNS resolution work in agent containers? What's the bridge network for? → network.md.
• How do I connect two hives into a swarm? → swarm/ (peer hives, TLS trust).
• Where do agent snapshots go? How does the swarm's btrfs receive endpoint authenticate a pushing hive? → snapshot-store.md.

Scheduler, CI, observability

• What am I looking at in the build queue / R3BU1LD QU3U3? What does each step mean? → jobq.md — operator-facing, no implementation detail.
• How does the rebuild queue work internally? What are queue kinds and sources? → coordinator.md.
• How does the CI runner work? What's the auto-registration flow? → ci.md.
• How do I export Claude Code metrics (tokens, cost, tool calls) to Prometheus/Grafana? → observability.md.

Crate reference

• What does a specific Rust crate do, on its own terms? → crates/ — every workspace crate's own README.md, one level up from source (hyperhive#3051); the crate itself is still the source of truth, this is just a walkable mirror.

Process & conventions

• Naming, commit style, wire protocol, the data-async pattern? → conventions.md.
• Why does the nspawn flag look like that? → gotchas.md (bind mounts, conf flags, other NixOS/nspawn quirks).
• What is /knowledge? How does the hive-wide knowledge repo sync, and how do I contribute a document? → knowledge.md.