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. The docs sit in five sections, by what the reader wants:

1. Getting started: what hyperhive is, and how to bring one up.
2. Handbook: running and using a hive and a swarm.
3. Options reference: every NixOS option.
4. Implementation: how it works inside.
5. Project: how the project itself works.

1. Getting started

• Adding hyperhive to a NixOS flake? Which options does it need? → 1-getting-started/nixos.md.
• Bringing a fresh swarm online? → 1-getting-started/setup.md (the hand steps after the first switch).

2. Handbook

Using and operating the hive and the swarm. Some pages here still carry implementation detail next to the operator content; sorting those out is later work.

Web UI and tools

• What does the dashboard look like, and how to use it? → 2-handbook/web-ui/ — the operator-facing starting point, with dashboard and agent.
• What tools does an agent (or the operator) have available? → 2-handbook/tools/ — hivectl (yours) plus every agent's MCP tool surface (bash, forge, lifecycle, matrix).
• What does hivectl do? Provisioning, gateway users, container shells? → 2-handbook/tools/hivectl.md (the curated guide); 2-handbook/tools/hivectl-cli.md for the exhaustive, autogenerated flag reference. The other command-line references sit beside it in 2-handbook/tools/.

Agent lifecycle

• How do config changes flow from manager to operator to container? → 2-handbook/agent-lifecycle/config-changes.md (config PRs, the meta flake, system messages).
• What state survives destroy / purge / restart? → 2-handbook/agent-lifecycle/persistence.md.
• Who can do what to whom — the agent roster and privilege? → 2-handbook/agent-lifecycle/agent-roster.md.

Trust boundary and security

• What's the operator/agent trust boundary? What's a permission? → 2-handbook/trust-boundary/boundary.md.
• Agent trust model, prompt-injection threat model, credential isolation? → 2-handbook/trust-boundary/security.md.

Accounts and integrations

• How do per-agent forge accounts work? What does forge_notify poll, and how does it format wake messages? → 2-handbook/integrations/forge.md (the swarm's Forgejo); 2-handbook/tools/forge.md for the hive-forge CLI verbs agents actually call.
• How does the matrix-tuwunel container work? Multiple accounts per agent? → 2-handbook/integrations/matrix.md (the homeserver); 2-handbook/tools/matrix.md for the MCP tool surface and services.hyperhive.agent.matrixAccounts.
• How to give an agent a GitHub account (gh + git push)? how's the PAT injected? → 2-handbook/integrations/github.md (operator content up top; the gh/git-push + notification-poller mechanics are in a collapsed "Implementation" section at the bottom).
• How to give an agent GitLab accounts (glab + git push, more than one instance)? → 2-handbook/integrations/gitlab.md.
• What's /knowledge? How does the swarm-wide knowledge repo sync, and how to contribute a document? → 2-handbook/integrations/knowledge.md.

Swarm

• How are two hives connected into a swarm? → 2-handbook/swarm/ (peer hives, TLS trust).
• Who mints each credential, who reads it, and how does it rotate — and where's that shape headed? → 2-handbook/swarm/credentials.md (the rules, where each secret goes and why) and 2-handbook/swarm/credentials-reference.md (the tables: each credential, current state and target state, and where each file lives today).
• How does an agent get a prompt at set times, and why doesn't it fire twice after downtime? → 2-handbook/swarm/schedules.md.
• How to create an agent from a ready-made set of permissions and settings? → 2-handbook/swarm/archetypes.md.
• How to log an agent in to claude from the swarm UI, and why doesn't a stale stored copy log it out again? → 2-handbook/swarm/claude-login.md.

3. Options reference

The autogenerated NixOS options reference (every services.hyperhive.* / hyperhive.* option, host and agent) lives on the website, built from the module declarations: the options site. Nothing of it sits in this tree.

4. Implementation

Turn loop, scheduler, CI, observability

• How does claude get its prompt, and what tools does it have? → 4-implementation/turn-loop/ — the loop, binary shape, turn outcomes; sub-pages: claude-invocation, config, mcp.
• what's the job queue, as a general idea (not hive-c0re specifics)? → 4-implementation/scheduler/jobq.md — operator-facing, no implementation detail.
• How does the rebuild queue work? What are the concrete step kinds, queue sources, scheduler internals? → 4-implementation/scheduler/coordinator.md.
• How does the CI runner work? How does it register? → 4-implementation/scheduler/ci.md.
• How are Claude Code metrics (tokens, cost, tool calls) exported to Prometheus/Grafana? → 4-implementation/scheduler/observability.md.

Networking

• What nginx vhosts does the gateway serve? How does matrix discovery work? → 4-implementation/networking/gateway.md.
• How does DNS resolution work in agent containers? What's the bridge network for? → 4-implementation/networking/network.md.
• Where do agent snapshots go? How does the swarm's btrfs receive endpoint authenticate a pushing hive? → 4-implementation/networking/snapshot-store.md.

Swarm services

• How does the secret store come up, who writes its grants, how's it sealed? → 4-implementation/swarm/bao.md.
• How to set an agent's model or effort from the swarm, and what happens to its own pick? → 4-implementation/swarm/inference.md.
• How does a PR get checked against its repo's own yes/no rules before a full review? → 4-implementation/swarm/review-classifier.md.
• Does an agent config PR build before it's merged? → 4-implementation/swarm/builder.md.
• How long do CI runs take, per repo and PR, and where does the board get it? → 4-implementation/swarm/ci-metrics.md.
• How does an agent get a todo when someone assigns it an issue, and lose it when the issue closes? → 4-implementation/swarm/notify-router.md.

Trust boundary mechanics

• How does systemd activate hive-priv, and how does the per-agent socket directory get its owner and mode? → 4-implementation/trust-boundary/boundary-mechanism.md.
• How does hive-c0re run unprivileged and delegate root operations? → 4-implementation/trust-boundary/hive-c0re-privilege.md.
• How do in-container nix builds stay apart from the credentials? → 4-implementation/trust-boundary/nix-builds.md.

Web UI internals

• How's the dashboard built, and how does the terminal render? → shape, css-vars, terminal-rendering.

Crate reference

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

5. Project

How the project itself works: processes, conventions, design guides.

• Naming, commit style, wire protocol, the data-async pattern? → 5-project/process/conventions.md.
• Why does the nspawn flag look like that? → 5-project/process/gotchas.md (bind mounts, conf flags, other NixOS/nspawn quirks).
• What does a PR review verdict actually gate? → 5-project/process/pr-review-gate.md.
• How are the web UIs designed to look and behave? → 5-project/web-ui/design-guide.md.