| Filename | Latest commit message | Latest commit date |
|---|---|---|
5fcd2a9387
Review note from argus. The paragraph sits at the end of a subsection about
the agent-to-collector hop, and said "authenticating the hop will not change
that" — but the authentication it goes on to describe is on the hive-to-swarm
hop, a different one. A reader arriving from the issue that tracks this ("the
agent-to-collector hop presents no credential") would reasonably read "the hop"
as the one that issue names and take away the opposite of what is meant.
Both are now named where they are contrasted, as a two-item list rather than a
sentence that has to be parsed twice: agent-to-collector stays open on the
bridge, hive-to-swarm is where the credential goes and where the hive label
stops being sender-chosen.
Confirmed against swarm-otel.nix's own header rather than the issue history:
the swarm tier is "the place that will stamp hive= from the authenticated
connection rather than from anything a sender can choose".
|
||
| .. | ||
| crates | ||
| swarm | ||
| tools | ||
| turn-loop | ||
| web-ui | ||
| agent-hierarchy.md | ||
| approvals.md | ||
| boundary.md | ||
| ci.md | ||
| conventions.md | ||
| coordinator.md | ||
| forge.md | ||
| gateway.md | ||
| github.md | ||
| gotchas.md | ||
| jobq.md | ||
| knowledge.md | ||
| matrix.md | ||
| network.md | ||
| observability.md | ||
| persistence.md | ||
| pr-review-gate.md | ||
| README.md | ||
| security.md | ||
| setup.md | ||
| snapshot-store.md | ||
| terminal-rendering.md | ||
| web-ui.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. For the auto-generated 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
- Bringing a fresh hive online? →
setup.md(first-runhivectlbootstrap). - What does the dashboard look like, and how do I use it? →
web-ui/— the operator-facing starting point; its own sub-pages (shape,dashboard,agent,css-vars) 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, scheduling).
Dashboard & agent UI internals
- How does the per-agent terminal classify + colour events? →
terminal-rendering.md.
Turn loop, config, approvals
- 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. - How do config changes flow from manager to operator to container? →
approvals.md(two-step spawn, approval state machine,flake.lockvalidation). - What state survives destroy / purge / restart? →
persistence.md.
Trust boundary & security
- What's the operator/agent trust boundary? What's a capability? →
boundary.md. - Agent trust model, prompt-injection threat model, credential
isolation? →
security.md. - Who can do what to whom — agent hierarchy and privilege? →
agent-hierarchy.md.
Accounts & integrations
- How do per-agent forge accounts work? What does
forge_notifypoll, and how does it format wake messages? →forge.md(the hive's own Forgejo);tools/forge.mdfor thehive-forgeCLI verbs agents actually call. - How does the matrix-tuwunel container work? Multiple accounts per
agent? →
matrix.md(the homeserver);tools/matrix.mdfor the MCP tool surface andhyperhive.matrixAccounts. - How do I give an agent a GitHub account (
gh+git push)? How is the PAT injected? →github.md. - What does
hivectldo? Provisioning, gateway users, container shells? →tools/hivectl.md(the curated guide);tools/hivectl-cli.mdfor the exhaustive, auto-generated flag reference.
Networking & swarms
- What nginx vhosts does the gateway serve? How does matrix
discovery work? →
gateway.md. - How does DNS resolution work in agent containers? What's the
bridge network for? →
network.md. - How do I connect two hives into a swarm? →
swarm/(peer hives, TLS trust). - Where do agent snapshots go? How does the swarm's
btrfs receiveendpoint authenticate a pushing hive? →snapshot-store.md.
Scheduler, CI, observability
- What is the job queue, as a general idea (not hive-c0re specifics)? →
jobq.md— operator-facing, no implementation detail. - How does the rebuild queue work? What are the concrete step kinds,
queue sources, scheduler internals? →
coordinator.md. - How does the CI runner work? What's the auto-registration flow? →
ci.md. - How do I export Claude Code metrics (tokens, cost, tool calls) to
Prometheus/Grafana? →
observability.md.
Crate reference
- What does a specific Rust crate do, on its own terms? →
crates/— every workspace crate's ownREADME.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-asyncpattern? →conventions.md. - Why does the nspawn flag look like that? →
gotchas.md(bind mounts, conf flags, other NixOS/nspawn quirks). - What is
/knowledge? How does the hive-wide knowledge repo sync, and how do I contribute a document? →knowledge.md.