# 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. For the auto-generated NixOS options reference
(every `services.hyperhive.*` / `hyperhive.*` option, host and agent), see
[the options site](https://hyperhive.darkest.space/options/) instead —
this tree is prose, that one's generated straight from the module
declarations.

## Getting started

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

## Agent lifecycle

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

## Trust boundary & security

- **What's the operator/agent trust boundary? What's a capability?** →
  [`trust-boundary/boundary.md`](trust-boundary/boundary.md).
- **Agent trust model, prompt-injection threat model, credential
  isolation?** → [`trust-boundary/security.md`](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`](integrations/forge.md)
  (the hive's own Forgejo); [`tools/forge.md`](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`](integrations/matrix.md) (the homeserver);
  [`tools/matrix.md`](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?** → [`integrations/github.md`](integrations/github.md).
- **What is `/knowledge`? How does the hive-wide knowledge repo sync,
  and how do I contribute a document?** → [`integrations/knowledge.md`](integrations/knowledge.md).
- **What does `hivectl` do? Provisioning, gateway users, container
  shells?** → [`tools/hivectl.md`](tools/hivectl.md) (the curated guide);
  [`tools/hivectl-cli.md`](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?** → [`networking/gateway.md`](networking/gateway.md).
- **How does DNS resolution work in agent containers? What's the
  bridge network for?** → [`networking/network.md`](networking/network.md).
- **How do I connect two hives into a swarm?** → [`swarm/`](swarm/README.md)
  (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`](networking/snapshot-store.md).

## Scheduler, CI, observability

- **What is the job queue, as a general idea (not hive-c0re specifics)?** →
  [`scheduler/jobq.md`](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`](scheduler/coordinator.md).
- **How does the CI runner work? What's the auto-registration flow?** →
  [`scheduler/ci.md`](scheduler/ci.md).
- **How do I export Claude Code metrics (tokens, cost, tool calls) to
  Prometheus/Grafana?** → [`scheduler/observability.md`](scheduler/observability.md).

## Crate reference

- **What does a specific Rust crate do, on its own terms?** →
  [`crates/`](crates/README.md) — 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?** →
  [`process/conventions.md`](process/conventions.md).
- **Why does the nspawn flag look like that?** → [`process/gotchas.md`](process/gotchas.md)
  (bind mounts, conf flags, other NixOS/nspawn quirks).
- **What does a PR review verdict actually gate?** →
  [`process/pr-review-gate.md`](process/pr-review-gate.md).