| Filename | Latest commit message | Latest commit date |
|---|---|---|
0e1a975f9f
`agents.conf` and `gateway.htpasswd` move from /var/lib/hyperhive/gateway to /var/lib/hive-gateway/conf, alongside the `tls/` the gateway already kept there. nginx reads both as an unprivileged user. Under c0re's state dir it could only reach them by traversing a directory systemd re-declares `0750 hive-core` on every c0re start — so nginx was given `SupplementaryGroups = [ "hive-core" ]`, which also handed it read access to everything else group-readable in that tree. The tokens are individually 0600, but the broker sqlite carries no explicit mode: every message between every agent was readable by the process whose job is parsing untrusted network input. Moving the files removes the need and the exposure together. The group is gone, and its absence is now commented as load-bearing so it doesn't come back as a fix for a symptom it would recreate. Also drops this module's `/var/lib/hyperhive` tmpfiles rule. It declared `0755 root root` and could never win against `StateDirectoryMode`, and a losing declaration still reads as a guarantee — that is what sent the first diagnosis of the outage looking for who had changed the mode. Ordering is unchanged and still the thing that makes a fresh boot work: tmpfiles runs before services and seeds both files empty-but-valid, nginx names them (an `include` of a missing file is fatal, not empty), and content arrives when c0re writes and reloads — which it does on every topology change, so a boot against the empty seed resolves itself. Folds in the mode fix: `write` now sets 0644 on the tmp file before the rename, because a rename carries the source's mode and discards the destination's, and the tmpfiles rule that declares 0644 is create-if-absent so it never re-applies. |
||
| .. | ||
| components | ||
| 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 | ||
| 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
- How does the rebuild queue work? What are queue kinds and
sources? →
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? →
components/— 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.