# hyperhive docs

Depth reference for hyperhive — the substrate, not the pitch (that's the
[top-level README](../README.md) / [website](https://hyperhive.darkest.space)).
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](#1-getting-started): what hyperhive is, and how to bring one up.
2. [Handbook](#2-handbook): running and using a hive and a swarm.
3. [Options reference](#3-options-reference): every NixOS option.
4. [Implementation](#4-implementation): how it works inside.
5. [Project](#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`](1-getting-started/nixos.md).
- **Bringing a fresh swarm online?** → [`1-getting-started/setup.md`](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/`](2-handbook/swarm/README.md).

- **How are two hives connected into a swarm?** → [`2-handbook/swarm/`](2-handbook/swarm/README.md)
  (peer hives, TLS trust).
- **What does the swarm UI show, and what does `swarmctl` do?** →
  [`2-handbook/swarm/ui.md`](2-handbook/swarm/ui.md) and
  [`2-handbook/swarm/swarmctl-cli.md`](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`](2-handbook/swarm/forge.md)
  (the swarm's Forgejo); [`4-implementation/agent-tools/forge.md`](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`](2-handbook/swarm/matrix.md) (the homeserver);
  [`4-implementation/agent-tools/matrix.md`](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`](2-handbook/swarm/knowledge.md).
- **Who mints each credential, who reads it, and how does it rotate — and
  where's that shape headed?** → [`2-handbook/swarm/credentials.md`](2-handbook/swarm/credentials.md)
  (the rules, where each secret goes and why) and
  [`2-handbook/swarm/credentials-reference.md`](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`](2-handbook/swarm/schedules.md).
- **How to create an agent from a ready-made set of permissions and
  settings?** → [`2-handbook/swarm/archetypes.md`](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`](2-handbook/swarm/claude-login.md).

### Hives

The host a hive runs on and the operator's tools for it. Start at
[`2-handbook/hives/`](2-handbook/hives/README.md).

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

### Agents

One agent: its roster entry, state, config and page. Start at
[`2-handbook/agents/`](2-handbook/agents/README.md).

- **How do config changes flow from manager to operator to container?** →
  [`2-handbook/agents/config-changes.md`](2-handbook/agents/config-changes.md)
  (config PRs, the meta flake, system messages).
- **What state survives destroy / purge / restart?** →
  [`2-handbook/agents/persistence.md`](2-handbook/agents/persistence.md).
- **Who can do what to whom — the agent roster and privilege?** →
  [`2-handbook/agents/agent-roster.md`](2-handbook/agents/agent-roster.md).
- **What does an agent's own page show?** →
  [`2-handbook/agents/web-page.md`](2-handbook/agents/web-page.md).
- **Agent trust model, prompt-injection threat model, credential
  isolation?** → [`2-handbook/agents/security.md`](2-handbook/agents/security.md).

### External accounts

Accounts outside the swarm that an agent can hold. Start at
[`2-handbook/external-accounts/`](2-handbook/external-accounts/README.md).

- **How to give an agent a GitHub account (`gh` + `git push`)? how's
  the PAT injected?** → [`2-handbook/external-accounts/github.md`](2-handbook/external-accounts/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/external-accounts/gitlab.md`](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](https://hyperhive.darkest.space/options/).
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/`](4-implementation/agent-tools/README.md).

### Turn loop, scheduler, CI, observability

- **How does claude get its prompt, and what tools does it have?** →
  [`4-implementation/turn-loop/`](4-implementation/turn-loop/README.md) — the loop, binary shape, turn
  outcomes; sub-pages: [`claude-invocation`](4-implementation/turn-loop/claude-invocation.md),
  [`config`](4-implementation/turn-loop/config.md), [`mcp`](4-implementation/turn-loop/mcp.md).
- **what's the job queue, as a general idea (not hive-c0re specifics)?** →
  [`4-implementation/scheduler/jobq.md`](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`](4-implementation/scheduler/coordinator.md).
- **How does the CI runner work? How does it register?** →
  [`4-implementation/scheduler/ci.md`](4-implementation/scheduler/ci.md).
- **How are Claude Code metrics (tokens, cost, tool calls) exported to
  Prometheus/Grafana?** → [`4-implementation/scheduler/observability.md`](4-implementation/scheduler/observability.md).

### Networking

- **What nginx vhosts does the gateway serve? How does matrix
  discovery work?** → [`4-implementation/networking/gateway.md`](4-implementation/networking/gateway.md).
- **How does DNS resolution work in agent containers? What's the
  bridge network for?** → [`4-implementation/networking/network.md`](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`](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`](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`](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`](4-implementation/swarm/review-classifier.md).
- **Does an agent config PR build before it's merged?** →
  [`4-implementation/swarm/builder.md`](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`](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`](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`](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`](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`](4-implementation/trust-boundary/nix-builds.md).

### Web UI internals

- **How's the dashboard built, and how does the terminal render?** →
  [`shape`](4-implementation/web-ui/shape.md),
  [`css-vars`](4-implementation/web-ui/css-vars.md),
  [`terminal-rendering`](4-implementation/web-ui/terminal-rendering.md).

### Crate reference

- **What does a specific Rust crate do, on its own terms?** →
  [`4-implementation/crates/`](4-implementation/crates/README.md) — 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`](5-project/process/conventions.md).
- **Why does the nspawn flag look like that?** → [`5-project/process/gotchas.md`](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`](5-project/process/pr-review-gate.md).
- **How are the web UIs designed to look and behave?** →
  [`5-project/web-ui/design-guide.md`](5-project/web-ui/design-guide.md).