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. 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 hyperhive, in the three layers that make it up, plus the accounts an agent can hold outside it. Some pages here still carry implementation detail next to the operator content; sorting those out is later work.

Swarm

The services that exist once per swarm. Start at 2-handbook/swarm/.

• How are two hives connected into a swarm? → 2-handbook/swarm/ (peer hives, TLS trust).
• How to spread the swarm over a few machines, with a VPN, and only the swarm UI, forge, matrix and SSO login answering the internet? → 2-handbook/swarm/semi-spread-deploy.md (worked example: machines, WireGuard, DNS).
• What does the swarm UI show, and what does swarmctl do? → 2-handbook/swarm/ui.md (the full page reference is 4-implementation/web-ui/swarm-ui.md) and 2-handbook/swarm/swarmctl-cli.md (the generated flag reference).
• How do per-agent forge accounts work? What does forge_notify poll, and how does it format wake messages? → 2-handbook/swarm/forge.md (the swarm's Forgejo); 4-implementation/agent-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/swarm/matrix.md (the homeserver); 4-implementation/agent-tools/matrix.md for the MCP tool surface and services.hyperhive.agent.matrixAccounts.
• What's /knowledge? How does the swarm-wide knowledge repo sync, and how to contribute a document? → 2-handbook/swarm/knowledge.md.
• Who mints each credential, who reads it, and how does it rotate? → 2-handbook/swarm/credentials.md (the rules, where each secret goes and why, adding a secret) and 4-implementation/swarm/credentials-reference.md (the tables: each credential and where each file lives). The store's identities, keys and login: 4-implementation/swarm/credentials.md.
• 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? → 2-handbook/swarm/claude-login.md. Why a stale stored copy doesn't log the agent out again, and the minter's grants: 4-implementation/swarm/claude-login.md.
• Where do the hives back up each agent's state, how long does it stay, and how to check it? → 2-handbook/swarm/archive.md.

Hives

The host a hive runs on and the operator's tools for it. Start at 2-handbook/hives/.

• What does the dashboard look like, and how to use it? → 2-handbook/hives/, with the full tab-by-tab reference in dashboard.
• What does hivectl do? Provisioning, gateway users, container shells? → 2-handbook/hives/hivectl.md (the curated guide); 2-handbook/hives/hivectl-cli.md for the exhaustive, autogenerated flag reference. The agents' own tool surface is in 4-implementation/agent-tools/.
• What's the operator/agent trust boundary? What's a permission? → 2-handbook/hives/boundary.md.

Agents

One agent: its roster entry, state, config and page. Start at 2-handbook/agents/.

• How do config changes flow from agent to operator to container? → 2-handbook/agents/persistence.md. The meta flake and system messages: 4-implementation/agent-state/config-changes.md.
• What state survives destroy / purge / restart? → 2-handbook/agents/persistence.md; the tables and directory layout: 4-implementation/agent-state/persistence.md.
• Who can do what to whom — the agent roster and privilege? → 2-handbook/agents/agent-roster.md; how topology.json is rebuilt and what's special about the manager: 4-implementation/agent-state/roster.md.
• What does an agent's own page show? → 2-handbook/agents/web-page.md; the full reference is agent-page.
• Agent trust model, prompt-injection threat model, credential isolation? → 2-handbook/agents/security.md.

External accounts

Accounts outside the swarm that an agent can hold. Start at 2-handbook/external-accounts/.

• How to give an agent a GitHub account (gh + git push)? how's the PAT injected? → 2-handbook/external-accounts/github.md; the gh/git-push and notification-poller mechanics are in 4-implementation/agent-tools/github.md.
• How to give an agent GitLab accounts (glab + git push, more than one instance)? → 2-handbook/external-accounts/gitlab.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

Agent tools

• What can an agent do inside its container? bash, subagent, forge, matrix, and the hive-forge, swarm-logs and swarm-metrics CLI references? → 4-implementation/agent-tools/.
• How does the forge notification poller wake an agent, and how does it format and de-duplicate what it delivers? → 4-implementation/agent-tools/forge-notify.md.
• How do an agent's gh and git push authenticate to GitHub? → 4-implementation/agent-tools/github.md.

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.
• What does the matrix homeserver's module assert at evaluation, how fluffychat-web gets built, and what replaced the hive-side matrix code? → 4-implementation/networking/matrix-homeserver.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.
• How does the controller take in hive status, give agents the queue, keep an agent's AGENTS.md and register forge webhooks? → 4-implementation/swarm/controller.md.
• How are the metrics store, Grafana, log store and OTEL collector wired, and who may reach each? → 4-implementation/swarm/telemetry.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.