hyperhive/docs

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

• Adding hyperhive to a NixOS flake? Which options does it need? → getting-started/nixos.md.
• Bringing a fresh swarm online? → getting-started/setup.md (the hand steps after the first switch).
• What does the dashboard look like, and how to use it? → web-ui/ — the operator-facing starting point; its own sub-pages (shape, dashboard, agent, css-vars, terminal-rendering) 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).

Agent lifecycle

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

Trust boundary & security

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

Accounts & integrations

• How do per-agent forge accounts work? What does forge_notify poll, and how does it format wake messages? → integrations/forge.md (the swarm's Forgejo); tools/forge.md for the hive-forge CLI verbs agents actually call.
• How does the matrix-tuwunel container work? Multiple accounts per agent? → integrations/matrix.md (the homeserver); 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? → 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)? → integrations/gitlab.md.
• What's /knowledge? How does the swarm-wide knowledge repo sync, and how to contribute a document? → integrations/knowledge.md.
• What does hivectl do? Provisioning, gateway users, container shells? → tools/hivectl.md (the curated guide); tools/hivectl-cli.md for the exhaustive, autogenerated flag reference.

Networking & swarms

• What nginx vhosts does the gateway serve? How does matrix discovery work? → networking/gateway.md.
• How does DNS resolution work in agent containers? What's the bridge network for? → networking/network.md.
• How are two hives connected 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? → networking/snapshot-store.md.
• Who mints each credential, who reads it, and how does it rotate — and where's that shape headed? → swarm/credentials.md (the rules, where each secret goes and why) and swarm/credentials-reference.md (the tables: each credential, current state and target state, and where each file lives today).
• How does the secret store come up, who writes its grants, how's it sealed? → swarm/bao.md.
• How does an agent get a prompt at set times, and why doesn't it fire twice after downtime? → swarm/schedules.md.
• How to set an agent's model or effort from the swarm, and what happens to its own pick? → swarm/inference.md.
• How does a PR get checked against its repo's own yes/no rules before a full review? → swarm/review-classifier.md.
• Does an agent config PR build before it's merged? → swarm/builder.md.
• How to create an agent from a ready-made set of permissions and settings? → swarm/archetypes.md.
• How long do CI runs take, per repo and PR, and where does the board get it? → swarm/ci-metrics.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? → swarm/claude-login.md.
• How does an agent get a todo when someone assigns it an issue, and lose it when the issue closes? → swarm/notify-router.md.

Scheduler, CI, observability

• what's the job queue, as a general idea (not hive-c0re specifics)? → scheduler/jobq.md — operator-facing, no implementation detail.
• How does the rebuild queue work? What are the concrete step kinds, queue sources, scheduler internals? → scheduler/coordinator.md.
• How does the CI runner work? How does it register? → scheduler/ci.md.
• How are Claude Code metrics (tokens, cost, tool calls) exported to Prometheus/Grafana? → scheduler/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; 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? → process/conventions.md.
• Why does the nspawn flag look like that? → process/gotchas.md (bind mounts, conf flags, other NixOS/nspawn quirks).
• What does a PR review verdict actually gate? → process/pr-review-gate.md.