vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
hyperhive/docs
History
Repository files (latest commit first)
Filename Latest commit message Latest commit date
atlas 602ae92a3e docs(swarm): make the status section operator-facing 
Per mara on the PR: less implementation detail, more operator focus. The
section argued why the design is shaped as it is - a cache would
disagree with itself, freshness must be derived rather than stored, the
timestamp is the server's - which is reasoning a reader of this page does
not need and cannot act on.

It now answers what an operator actually asks: what each freshness value
means they should do, what to set the threshold to and why that number,
what a 503 tells them, and that nothing publishes yet so an empty board
is expected rather than broken.

The design rationale is not lost, it is just homed where it belongs: the
status module's own doc comment, next to the code it constrains.
2026-08-15 18:48:51 +02:00
..
crates docs: rename docs/components to docs/crates 2026-08-12 13:32:55 +02:00
swarm docs(swarm): make the status section operator-facing 2026-08-15 18:48:51 +02:00
tools docs(matrix): fix invite-wake mechanism and todo message format 2026-08-15 12:45:22 +02:00
turn-loop docs(turn-loop): fix wrong HelperEvent lifecycle-event list 2026-08-15 12:45:22 +02:00
web-ui docs(web-ui/agent): fix stale NavLink type name 2026-08-15 12:45:22 +02:00
agent-hierarchy.md docs(agent-hierarchy): fix stale topology.rs path, ManagerRequest, dead reminder_scheduler.rs ref, and hardcoded forge URLs 2026-08-15 12:45:22 +02:00
approvals.md docs(approvals): fix stale internal refs verified against source 2026-08-15 12:45:22 +02:00
boundary.md docs(boundary): fix answer-question path and nonexistent AgentRequest type 2026-08-15 12:45:22 +02:00
ci.md docs(ci): fix stale nix option namespace and ensure_mirrors file path 2026-08-15 12:45:22 +02:00
conventions.md docs(conventions): fix one more stale hive-c0re.nix bare-file ref 2026-08-15 12:45:22 +02:00
coordinator.md docs(coordinator): fix stale DAG-history cap, wire request name, infra container list 2026-08-15 12:45:22 +02:00
forge.md docs(forge): fix stale nix option namespace (services.hyperhive.swarm.forge) 2026-08-15 12:45:22 +02:00
gateway.md docs(gateway): fix stale gateway.enable, selfSignedTls, rootUrl, vhost claims 2026-08-15 12:45:22 +02:00
github.md docs(github): move impl detail below the operator-facing sections 2026-08-02 23:54:55 +02:00
gotchas.md docs(gotchas): fix wrong claim that hyperhive-events.sqlite lives in state dir 2026-08-15 12:45:22 +02:00
knowledge.md docs(knowledge): fix stale collaborator model and webhook delivery claims 2026-08-15 12:45:22 +02:00
matrix.md docs(matrix): fix stale matrix.<hive> vhost + assertion-list claims 2026-08-15 12:45:22 +02:00
network.md docs(network): fix stale forge/matrix zone claim in resolver behaviour 2026-08-15 12:45:22 +02:00
observability.md docs(otel): say what the agent->collector hop is and is not 2026-08-15 11:46:24 +02:00
persistence.md docs(persistence): fix stale facts — reminders/todos moved in-container, vacuum ownership, topology writer, matrix glob, qgroup quotas shipped 2026-08-15 12:45:22 +02:00
pr-review-gate.md docs: revise per review — no specific example, gate is per-repo config, soften auto-merge framing 2026-08-04 17:23:12 +02:00
README.md docs: rename docs/components to docs/crates 2026-08-12 13:32:55 +02:00
security.md docs(security): fix stale forge.rs path, GetAgentMeta validator, hive-priv table 2026-08-15 12:45:22 +02:00
setup.md docs: link the secrets page from setup, fix a dropped word 2026-08-14 13:22:43 +02:00
snapshot-store.md docs(snapshot-store): cross-link the state subvolume to persistence.md 2026-08-15 12:45:22 +02:00
terminal-rendering.md docs(terminal-rendering): re-attribute dispatch logic to stream_enrich.rs, fix Write/TodoWrite/Bash dead-path claims 2026-08-15 12:45:22 +02:00
web-ui.md docs(web-ui): point port-hash detail at gotchas.md instead of restating it 2026-08-15 12:45:22 +02:00

README.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-run hivectl bootstrap).
  • 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

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.lock validation).
  • 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_notify poll, and how does it format wake messages? → forge.md (the hive's own Forgejo); tools/forge.md for the hive-forge CLI verbs agents actually call.
  • How does the matrix-tuwunel container work? Multiple accounts per agent? → matrix.md (the homeserver); 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? → github.md.
  • What does hivectl do? Provisioning, gateway users, container shells? → tools/hivectl.md (the curated guide); 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? → 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 receive endpoint 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 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? → 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.