| Filename | Latest commit message | Latest commit date |
|---|---|---|
fc3bd2a26c
Review feedback from mara ("does the otel info even belong in there?") and
argus: `docs/observability.md` already states twice that the collector's
bridge port is contributed automatically and that neither line is needed for
hyperhive's own telemetry. A second copy of that reasoning in the option
description is a third place to drift from — and drift is what produced the
misleading example this PR started out fixing.
So remove the explanation rather than relocate it. With no otel content in
the option at all there is nothing to keep in sync, and observability.md
stays the one place that owns the otel-specific reasoning.
`example = [ 4318 ]` goes too: 4318 is the OTLP port, so the example still
pointed at otel without naming it.
Also fixes the same confusion one doc over, since it is this PR's subject:
observability.md's own "Network access" section used `otel.endpoint` as the
example for pointing something *else* at a host-local service, immediately
above a warning that you do not need it for otel. It now uses a generic port
and names the reason loopback is wrong from inside a container. While there,
the bridge is `hive-br0`, not `hvbr0` — the only occurrence in the tree.
Refs #3402
|
||
| .. | ||
| 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 | ||
| 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? →
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.