| Filename | Latest commit message | Latest commit date |
|---|---|---|
0e9b1c563d
Third and last of #2860's agent-facing URL fallbacks. The operator's ruling was "any special casing is done on the nix side - same binaries, no hard coded fallback", so the default is deleted rather than replaced. Every layer guessed the same wrong thing, and each guess was only ever correct for a process sharing the host netns: - nix/agent-modules/matrix.nix: matrixUrlDefault = localhost:8008, both as the option's default and as a sentinel the daemon unit compared against to decide whether to write HIVE_MATRIX_URL. Now nullOr str, default null, the guard is != null, and the doc says what forge.url's already says: null means "no matrix", not "guess one". - nix/host-modules/hive-c0re/environment.nix: forwarded http://127.0.0.1:<port> when no gatewayHost was set. hive-c0re shares the host netns so it reads as harmless, but the value is handed to agents, which do not -- there it names the agent itself. Now forwarded only when there is a gateway vhost to name, matching the guard HIVE_MATRIX_PUBLIC_URL already uses twelve lines below. - hive-matrix-mcp: paths::DEFAULT_HOMESERVER was the same address compiled in, so dropping the nix defaults alone would have left the daemon dialling loopback inside the agent's own netns -- the very bug, one layer down. homeserver_url() is now Option, and an account with no homeserver is skipped with a log, exactly as one with no token is. discover_token_accounts already refused to guess for the same reason. Two comments taught the assumption back to the next reader ("shared host netns means every agent container resolves localhost to the same machine"); both now say which side of the netns boundary they describe. MATRIX_HTTP keeps its value -- hive-c0re really does share the host netns -- but no longer claims agents do. Gated with nix eval against the extended agent-base config, as a pair: with no url set the daemon unit carries no HIVE_MATRIX_URL, and with one set it carries exactly that. Either check alone passes on a broken guard. |
||
| .. | ||
| 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 | ||
| README.md | ||
| security.md | ||
| setup.md | ||
| snapshot-store.md | ||
| swarm.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.md(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.
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.