mara/hyperhive
mara/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity
hyperhive/docs/README.md
iris 0e84fe8bc4 docs: the handbook follows the three layers: swarm, hives, agents 
The handbook's sections were agent-lifecycle, integrations, swarm, tools,
trust-boundary and web-ui, which do not follow how the system is built, so a
reader could not tell which layer a page is about. Its pages now sit in
swarm/, hives/ and agents/, with the accounts an agent can hold outside the
system in external-accounts/.

- swarm/: forge, matrix and the knowledge repo join the swarm pages, and so
  does the swarmctl reference.
- hives/: the dashboard, hivectl and its reference, and the operator/agent
  boundary, with a README that takes over the old web-ui and tools pages.
- agents/: the roster, persistence, config changes, the agent's own web page
  (was web-ui/agent) and the security model, with a README.
- external-accounts/: GitHub and GitLab.

Pages are moved whole; none is split yet. Every reference follows: relative
links in the docs, `docs/2-handbook/...` paths in code comments, the nix
checks that regenerate the CLI references and the ignore list, and docs/README.md,
whose handbook section is now by layer.
2026-11-07 12:19:36 +01:00

197 lines
11 KiB
Markdown
Raw Blame History

# hyperhive docs
Depth reference for hyperhive — the substrate, not the pitch (that's the
[top-level README](../README.md) / [website](https://hyperhive.darkest.space)).
Every page here stands alone; pick the one matching your task rather than
reading top to bottom. The docs sit in five sections, by what the reader wants:
1. [Getting started](#1-getting-started): what hyperhive is, and how to bring one up.
2. [Handbook](#2-handbook): running and using a hive and a swarm.
3. [Options reference](#3-options-reference): every NixOS option.
4. [Implementation](#4-implementation): how it works inside.
5. [Project](#5-project): how the project itself works.
## 1. Getting started
- **Adding hyperhive to a NixOS flake? Which options does it need?** →
[`1-getting-started/nixos.md`](1-getting-started/nixos.md).
- **Bringing a fresh swarm online?** → [`1-getting-started/setup.md`](1-getting-started/setup.md)
(the hand steps after the first switch).
## 2. Handbook
Using and operating hyperhive, in the three layers that make it up, plus the
accounts an agent can hold outside it. Some pages here still carry
implementation detail next to the operator content; sorting those out is
later work.
### Swarm
The services that exist once per swarm. Start at
[`2-handbook/swarm/`](2-handbook/swarm/README.md).
- **How are two hives connected into a swarm?** → [`2-handbook/swarm/`](2-handbook/swarm/README.md)
(peer hives, TLS trust).
- **What does the swarm UI show, and what does `swarmctl` do?** →
[`2-handbook/swarm/ui.md`](2-handbook/swarm/ui.md) and
[`2-handbook/swarm/swarmctl-cli.md`](2-handbook/swarm/swarmctl-cli.md) (the
generated flag reference).
- **How do per-agent forge accounts work? What does `forge_notify` poll,
and how does it format wake messages?** → [`2-handbook/swarm/forge.md`](2-handbook/swarm/forge.md)
(the swarm's Forgejo); [`4-implementation/agent-tools/forge.md`](4-implementation/agent-tools/forge.md) for the
`hive-forge` CLI verbs agents actually call.
- **How does the matrix-tuwunel container work? Multiple accounts per
agent?** → [`2-handbook/swarm/matrix.md`](2-handbook/swarm/matrix.md) (the homeserver);
[`4-implementation/agent-tools/matrix.md`](4-implementation/agent-tools/matrix.md) for the MCP tool surface and
`services.hyperhive.agent.matrixAccounts`.
- **What's `/knowledge`? How does the swarm-wide knowledge repo sync,
and how to contribute a document?** → [`2-handbook/swarm/knowledge.md`](2-handbook/swarm/knowledge.md).
- **Who mints each credential, who reads it, and how does it rotate — and
where's that shape headed?** → [`2-handbook/swarm/credentials.md`](2-handbook/swarm/credentials.md)
(the rules, where each secret goes and why) and
[`2-handbook/swarm/credentials-reference.md`](2-handbook/swarm/credentials-reference.md) (the
tables: each credential, current state and target state, and where each
file lives today).
- **How does an agent get a prompt at set times, and why doesn't it fire
twice after downtime?** → [`2-handbook/swarm/schedules.md`](2-handbook/swarm/schedules.md).
- **How to create an agent from a ready-made set of permissions and
settings?** → [`2-handbook/swarm/archetypes.md`](2-handbook/swarm/archetypes.md).
- **How to log an agent in to claude from the swarm UI, and why doesn't a
stale stored copy log it out again?** →
[`2-handbook/swarm/claude-login.md`](2-handbook/swarm/claude-login.md).
### Hives
The host a hive runs on and the operator's tools for it. Start at
[`2-handbook/hives/`](2-handbook/hives/README.md).
- **What does the dashboard look like, and how to use it?** →
[`2-handbook/hives/`](2-handbook/hives/README.md), with the full tab-by-tab
reference in [`dashboard`](2-handbook/hives/dashboard.md).
- **What does `hivectl` do? Provisioning, gateway users, container
shells?** → [`2-handbook/hives/hivectl.md`](2-handbook/hives/hivectl.md) (the curated guide);
[`2-handbook/hives/hivectl-cli.md`](2-handbook/hives/hivectl-cli.md) for the exhaustive,
autogenerated flag reference. The agents' own tool surface is in
[`4-implementation/agent-tools/`](4-implementation/agent-tools/README.md).
- **What's the operator/agent trust boundary? What's a permission?** →
[`2-handbook/hives/boundary.md`](2-handbook/hives/boundary.md).
### Agents
One agent: its roster entry, state, config and page. Start at
[`2-handbook/agents/`](2-handbook/agents/README.md).
- **How do config changes flow from manager to operator to container?** →
[`2-handbook/agents/config-changes.md`](2-handbook/agents/config-changes.md)
(config PRs, the meta flake, system messages).
- **What state survives destroy / purge / restart?** →
[`2-handbook/agents/persistence.md`](2-handbook/agents/persistence.md).
- **Who can do what to whom — the agent roster and privilege?** →
[`2-handbook/agents/agent-roster.md`](2-handbook/agents/agent-roster.md).
- **What does an agent's own page show?** →
[`2-handbook/agents/web-page.md`](2-handbook/agents/web-page.md).
- **Agent trust model, prompt-injection threat model, credential
isolation?** → [`2-handbook/agents/security.md`](2-handbook/agents/security.md).
### External accounts
Accounts outside the swarm that an agent can hold. Start at
[`2-handbook/external-accounts/`](2-handbook/external-accounts/README.md).
- **How to give an agent a GitHub account (`gh` + `git push`)? how's
the PAT injected?** → [`2-handbook/external-accounts/github.md`](2-handbook/external-accounts/github.md)
(operator content up top; the `gh`/git-push + notification-poller
mechanics are in a collapsed "Implementation" section at the bottom).
- **How to give an agent GitLab accounts (`glab` + `git push`, more than one
instance)?** → [`2-handbook/external-accounts/gitlab.md`](2-handbook/external-accounts/gitlab.md).
## 3. Options reference
The autogenerated NixOS options reference (every `services.hyperhive.*` /
`hyperhive.*` option, host and agent) lives on the website, built from the
module declarations: [the options site](https://hyperhive.darkest.space/options/).
Nothing of it sits in this tree.
## 4. Implementation
### Agent tools
- **What can an agent do inside its container? bash, subagent, forge, matrix, and the
`hive-forge`, `swarm-logs` and `swarm-metrics` CLI references?** →
[`4-implementation/agent-tools/`](4-implementation/agent-tools/README.md).
### Turn loop, scheduler, CI, observability
- **How does claude get its prompt, and what tools does it have?** →
[`4-implementation/turn-loop/`](4-implementation/turn-loop/README.md) — the loop, binary shape, turn
outcomes; sub-pages: [`claude-invocation`](4-implementation/turn-loop/claude-invocation.md),
[`config`](4-implementation/turn-loop/config.md), [`mcp`](4-implementation/turn-loop/mcp.md).
- **what's the job queue, as a general idea (not hive-c0re specifics)?** →
[`4-implementation/scheduler/jobq.md`](4-implementation/scheduler/jobq.md) — operator-facing, no implementation detail.
- **How does the rebuild queue work? What are the concrete step kinds,
queue sources, scheduler internals?** → [`4-implementation/scheduler/coordinator.md`](4-implementation/scheduler/coordinator.md).
- **How does the CI runner work? How does it register?** →
[`4-implementation/scheduler/ci.md`](4-implementation/scheduler/ci.md).
- **How are Claude Code metrics (tokens, cost, tool calls) exported to
Prometheus/Grafana?** → [`4-implementation/scheduler/observability.md`](4-implementation/scheduler/observability.md).
### Networking
- **What nginx vhosts does the gateway serve? How does matrix
discovery work?** → [`4-implementation/networking/gateway.md`](4-implementation/networking/gateway.md).
- **How does DNS resolution work in agent containers? What's the
bridge network for?** → [`4-implementation/networking/network.md`](4-implementation/networking/network.md).
- **Where do agent snapshots go? How does the swarm's `btrfs receive`
endpoint authenticate a pushing hive?** →
[`4-implementation/networking/snapshot-store.md`](4-implementation/networking/snapshot-store.md).
### Swarm services
- **How does the secret store come up, who writes its grants, how's it
sealed?** → [`4-implementation/swarm/bao.md`](4-implementation/swarm/bao.md).
- **How to set an agent's model or effort from the swarm, and what happens
to its own pick?** → [`4-implementation/swarm/inference.md`](4-implementation/swarm/inference.md).
- **How does a PR get checked against its repo's own yes/no rules before
a full review?** → [`4-implementation/swarm/review-classifier.md`](4-implementation/swarm/review-classifier.md).
- **Does an agent config PR build before it's merged?** →
[`4-implementation/swarm/builder.md`](4-implementation/swarm/builder.md).
- **How long do CI runs take, per repo and PR, and where does the board get
it?** → [`4-implementation/swarm/ci-metrics.md`](4-implementation/swarm/ci-metrics.md).
- **How does an agent get a todo when someone assigns it an issue, and lose it
when the issue closes?** → [`4-implementation/swarm/notify-router.md`](4-implementation/swarm/notify-router.md).
### Trust boundary mechanics
- **How does systemd activate `hive-priv`, and how does the per-agent socket
directory get its owner and mode?** → [`4-implementation/trust-boundary/boundary-mechanism.md`](4-implementation/trust-boundary/boundary-mechanism.md).
- **How does `hive-c0re` run unprivileged and delegate root operations?** →
[`4-implementation/trust-boundary/hive-c0re-privilege.md`](4-implementation/trust-boundary/hive-c0re-privilege.md).
- **How do in-container nix builds stay apart from the credentials?** →
[`4-implementation/trust-boundary/nix-builds.md`](4-implementation/trust-boundary/nix-builds.md).
### Web UI internals
- **How's the dashboard built, and how does the terminal render?** →
[`shape`](4-implementation/web-ui/shape.md),
[`css-vars`](4-implementation/web-ui/css-vars.md),
[`terminal-rendering`](4-implementation/web-ui/terminal-rendering.md).
### Crate reference
- **What does a specific Rust crate do, on its own terms?** →
[`4-implementation/crates/`](4-implementation/crates/README.md) — every workspace crate's own
`README.md`, one level up from source; the crate
itself is still the source of truth, this is just a walkable mirror.
## 5. Project
How the project itself works: processes, conventions, design guides.
- **Naming, commit style, wire protocol, the `data-async` pattern?** →
[`5-project/process/conventions.md`](5-project/process/conventions.md).
- **Why does the nspawn flag look like that?** → [`5-project/process/gotchas.md`](5-project/process/gotchas.md)
(bind mounts, conf flags, other NixOS/nspawn quirks).
- **What does a PR review verdict actually gate?** →
[`5-project/process/pr-review-gate.md`](5-project/process/pr-review-gate.md).
- **How are the web UIs designed to look and behave?** →
[`5-project/web-ui/design-guide.md`](5-project/web-ui/design-guide.md).
View git blame Copy permalink