docs: sort the top-level directories into five sections by what the reader wants
Every docs directory moves under 1-getting-started, 2-handbook, 4-implementation or 5-project; the options reference (section 3) comes from the website and has no directory here. trust-boundary stays whole under the handbook for now. web-ui, swarm and tools split between handbook and implementation, and the command-line references move to 2-handbook/reference. Links, path references in code and nix, and the docs index follow the moves; no page content changes.
This commit is contained in:
parent
53ccbcb4b3
commit
6739bb903d
232 changed files with 736 additions and 701 deletions
|
|
@ -4,25 +4,25 @@
|
|||
# generator, not the formatter, owns these files' layout. Every CLI
|
||||
# reference doc belongs here — adding one and forgetting this line is
|
||||
# what made swarmctl's fail.
|
||||
docs/tools/hivectl-cli.md
|
||||
docs/tools/swarmctl-cli.md
|
||||
docs/tools/forge-cli.md
|
||||
docs/tools/swarm-logs-cli.md
|
||||
docs/tools/swarm-metrics-cli.md
|
||||
docs/2-handbook/reference/hivectl-cli.md
|
||||
docs/2-handbook/reference/swarmctl-cli.md
|
||||
docs/2-handbook/reference/forge-cli.md
|
||||
docs/2-handbook/reference/swarm-logs-cli.md
|
||||
docs/2-handbook/reference/swarm-metrics-cli.md
|
||||
|
||||
# Files with multi-line list-item continuations that prettier strips to col 0.
|
||||
# prettier's `proseWrap: "preserve"` prevents prose reflow but not list-item
|
||||
# indentation normalisation, so these files need manual re-wrap before
|
||||
# adding them back to the formatter scope.
|
||||
AGENTS.md
|
||||
docs/agent-lifecycle/config-changes.md
|
||||
docs/process/conventions.md
|
||||
docs/networking/gateway.md
|
||||
docs/integrations/matrix.md
|
||||
docs/agent-lifecycle/persistence.md
|
||||
docs/web-ui/terminal-rendering.md
|
||||
docs/tools/forge.md
|
||||
docs/tools/matrix.md
|
||||
docs/turn-loop/README.md
|
||||
docs/web-ui/agent.md
|
||||
docs/web-ui/dashboard.md
|
||||
docs/2-handbook/agent-lifecycle/config-changes.md
|
||||
docs/5-project/process/conventions.md
|
||||
docs/4-implementation/networking/gateway.md
|
||||
docs/2-handbook/integrations/matrix.md
|
||||
docs/2-handbook/agent-lifecycle/persistence.md
|
||||
docs/4-implementation/web-ui/terminal-rendering.md
|
||||
docs/2-handbook/tools/forge.md
|
||||
docs/2-handbook/tools/matrix.md
|
||||
docs/4-implementation/turn-loop/README.md
|
||||
docs/2-handbook/web-ui/agent.md
|
||||
docs/2-handbook/web-ui/dashboard.md
|
||||
|
|
|
|||
32
AGENTS.md
32
AGENTS.md
|
|
@ -10,20 +10,20 @@ when you need depth on a subsystem. This file is the index.
|
|||
the env var — inside an agent container `localhost` is the *agent*, not
|
||||
the forge, so a hardcoded loopback address fails to connect.
|
||||
- Operator/agent trust-boundary design:
|
||||
**[docs/trust-boundary/boundary.md](docs/trust-boundary/boundary.md)** (`area/ops` issues
|
||||
**[docs/2-handbook/trust-boundary/boundary.md](docs/2-handbook/trust-boundary/boundary.md)** (`area/ops` issues
|
||||
for the deployment/gateway/privsep work — the separator is a **slash**,
|
||||
and `--label area:ops` now fails with `did you mean "area/ops"?`).
|
||||
- Agent trust model (trust boundary, prompt-injection threat model,
|
||||
capability = accepted risk), credential isolation + sandbox threat model:
|
||||
**[docs/trust-boundary/security.md](docs/trust-boundary/security.md)**.
|
||||
**[docs/2-handbook/trust-boundary/security.md](docs/2-handbook/trust-boundary/security.md)**.
|
||||
- Odd-looking nspawn / container plumbing usually has a story:
|
||||
**[docs/process/gotchas.md](docs/process/gotchas.md)**.
|
||||
**[docs/5-project/process/gotchas.md](docs/5-project/process/gotchas.md)**.
|
||||
|
||||
## Build & check
|
||||
|
||||
Always through the devshell — a bare `cargo` fails (`failed to find tool
|
||||
"cc"`, `cannot find -lsqlite3`). Details:
|
||||
[`docs/process/conventions.md`](docs/process/conventions.md#building--local-checks).
|
||||
[`docs/5-project/process/conventions.md`](docs/5-project/process/conventions.md#building--local-checks).
|
||||
|
||||
```sh
|
||||
nix develop -c cargo clippy --all-targets -- -D warnings
|
||||
|
|
@ -33,8 +33,8 @@ nix fmt # treefmt is the CI gate, NOT bare cargo fmt
|
|||
|
||||
Changed a `hivectl` / `swarmctl` verb or flag? Regenerate its doc — only
|
||||
CI's `nix flake check` catches the drift:
|
||||
`nix develop -c cargo run --bin hivectl -- markdown-docs > docs/tools/hivectl-cli.md`
|
||||
(same for `swarmctl` → `docs/tools/swarmctl-cli.md`). CI red but local
|
||||
`nix develop -c cargo run --bin hivectl -- markdown-docs > docs/2-handbook/reference/hivectl-cli.md`
|
||||
(same for `swarmctl` → `docs/2-handbook/reference/swarmctl-cli.md`). CI red but local
|
||||
green → build the suspect check (e.g. `nix build
|
||||
.#checks.x86_64-linux.hivectl-docs`) before blaming the builder.
|
||||
|
||||
|
|
@ -58,10 +58,10 @@ Per-hive (host + in-container):
|
|||
crate.
|
||||
- **`hivectl/`** — operator CLI; talks to `hive-c0re` over the host admin
|
||||
socket, does NOT link it. Verb reference (CI-enforced):
|
||||
[`docs/tools/hivectl-cli.md`](docs/tools/hivectl-cli.md).
|
||||
[`docs/2-handbook/reference/hivectl-cli.md`](docs/2-handbook/reference/hivectl-cli.md).
|
||||
- **`hive-priv/`** — minimal root helper, socket-activated at
|
||||
`/run/hive/priv.sock`; the few root ops (bind-mount edits, nsenter)
|
||||
`hive-c0re` delegates. See `docs/trust-boundary/boundary.md`.
|
||||
`hive-c0re` delegates. See `docs/2-handbook/trust-boundary/boundary.md`.
|
||||
- **`hive-agent/`** — the in-container serve loop: turn-loop *policy*
|
||||
(`turn.rs`) over `hive-runtime`, per-agent web UI, event + turn-stats
|
||||
sinks, system-prompt renderer, claude launch config (`mcp_config.rs`).
|
||||
|
|
@ -130,7 +130,7 @@ Swarm-level:
|
|||
**`users.yml` in place**, shared with `swarm-authelia-bridge`; that
|
||||
crate's README says what both writers must uphold. Verb reference
|
||||
(CI-enforced):
|
||||
[`docs/tools/swarmctl-cli.md`](docs/tools/swarmctl-cli.md).
|
||||
[`docs/2-handbook/reference/swarmctl-cli.md`](docs/2-handbook/reference/swarmctl-cli.md).
|
||||
- **`swarm-authelia-bridge/`** (+ **`swarm-authelia-bridge-sock/`** wire
|
||||
types) — the other writer of authelia's users DB; runs inside
|
||||
`swarm-authelia`.
|
||||
|
|
@ -164,20 +164,20 @@ Swarm-level:
|
|||
- **`swarm-builder/`** — builds agent config PR heads for commit status,
|
||||
builds each agent from `internal/meta` before its deploy, and evaluates the
|
||||
agent archetypes the create form lists.
|
||||
Design: [`docs/swarm/builder.md`](docs/swarm/builder.md).
|
||||
Design: [`docs/4-implementation/swarm/builder.md`](docs/4-implementation/swarm/builder.md).
|
||||
- **`swarm-ci-metrics/`** — polls the forge's Actions runs and pushes each
|
||||
finished run's duration and queue wait to the metrics store. Design:
|
||||
[`docs/swarm/ci-metrics.md`](docs/swarm/ci-metrics.md).
|
||||
[`docs/4-implementation/swarm/ci-metrics.md`](docs/4-implementation/swarm/ci-metrics.md).
|
||||
- **`swarm-claude-login/`** — runs `claude auth login` for one agent and
|
||||
stores the credentials at `swarm/agents/<agent>/claude-credentials`.
|
||||
Design: [`docs/swarm/claude-login.md`](docs/swarm/claude-login.md).
|
||||
Design: [`docs/2-handbook/swarm/claude-login.md`](docs/2-handbook/swarm/claude-login.md).
|
||||
- **`swarm-notify-router/`** — forge events from swarm-controller's
|
||||
webhooks to todos on the agents they concern, through each agent's own
|
||||
consumer on the `ROUTER_TODOS` stream. Design:
|
||||
[`docs/swarm/notify-router.md`](docs/swarm/notify-router.md).
|
||||
[`docs/4-implementation/swarm/notify-router.md`](docs/4-implementation/swarm/notify-router.md).
|
||||
- **`swarm-review-classifier/`** — one `claude --print` per PR
|
||||
classification, no tools, no forge credential. Design:
|
||||
[`docs/swarm/review-classifier.md`](docs/swarm/review-classifier.md).
|
||||
[`docs/4-implementation/swarm/review-classifier.md`](docs/4-implementation/swarm/review-classifier.md).
|
||||
|
||||
### External dependencies with no directory here
|
||||
|
||||
|
|
@ -213,7 +213,7 @@ in this file and drifted.
|
|||
|
||||
- **Never add `#[allow(clippy::…)]`** — fix the lint instead (extract a
|
||||
helper, add backticks, etc.). Worked examples:
|
||||
[`docs/process/conventions.md`](docs/process/conventions.md#building--local-checks).
|
||||
[`docs/5-project/process/conventions.md`](docs/5-project/process/conventions.md#building--local-checks).
|
||||
- **Pre-push lint hook** (catches tracker-tag and comment-block failures
|
||||
before CI does — install once per clone):
|
||||
`ln -sf ../../scripts/pre-push .git/hooks/pre-push`
|
||||
|
|
@ -225,7 +225,7 @@ in this file and drifted.
|
|||
- **Operator-facing doc with real implementation detail mixed in**: wrap
|
||||
the implementation part in a `<details><summary>…</summary>` block
|
||||
(blank line after `<summary>` so the markdown inside renders) rather
|
||||
than a sibling page — see `docs/integrations/github.md`'s
|
||||
than a sibling page — see `docs/2-handbook/integrations/github.md`'s
|
||||
"Implementation" section. It only collapses in a rendered browser, and
|
||||
the `<summary>` line isn't markdown-processed, so keep it plain prose
|
||||
with no backticks.
|
||||
|
|
|
|||
|
|
@ -290,5 +290,5 @@ x509-cert = { version = "0.2", default-features = false, features = ["pem"] }
|
|||
# Test doubles with expectations (canned replies, call counts, argument
|
||||
# matchers). Dev-dependency only, and used behind `#[cfg(test)]`, so release
|
||||
# builds never compile it. See "Testing seams and test doubles" in
|
||||
# `docs/process/conventions.md`.
|
||||
# `docs/5-project/process/conventions.md`.
|
||||
mockall = "0.15"
|
||||
|
|
|
|||
38
README.md
38
README.md
|
|
@ -81,24 +81,24 @@ box it gets:
|
|||
- **messaging** — peers and the operator talk over matrix; `send` / `recv` is the hive-local broker for system traffic and agents without matrix,
|
||||
`remind` to wake itself, scheduled prompts the operator sets for it at
|
||||
swarm level, and a todo list that forge notifications and other
|
||||
producers feed. → [schedules](docs/swarm/schedules.md)
|
||||
producers feed. → [schedules](docs/2-handbook/swarm/schedules.md)
|
||||
- **background bash** — long-running commands as tracked tasks
|
||||
(`run` / `status` / `kill`), so a build doesn't block the turn. →
|
||||
[bash](docs/tools/bash.md)
|
||||
[bash](docs/2-handbook/tools/bash.md)
|
||||
- **subagents** — nested sessions on the agent's own runtime, optionally
|
||||
re-prompted toward a goal over several turns. →
|
||||
[subagent](docs/tools/subagent.md)
|
||||
[subagent](docs/2-handbook/tools/subagent.md)
|
||||
- **forge** — its own Forgejo account, the `hive-forge` CLI, git
|
||||
credentials, and notifications turned into todos. Optional linked
|
||||
accounts on other forges, GitLab (`glab` + push), and GitHub (`gh` + push) via
|
||||
`services.hyperhive.agent.github.enable`. →
|
||||
[forge](docs/integrations/forge.md) · [gitlab](docs/integrations/gitlab.md) ·
|
||||
[github](docs/integrations/github.md)
|
||||
[forge](docs/2-handbook/integrations/forge.md) · [gitlab](docs/2-handbook/integrations/gitlab.md) ·
|
||||
[github](docs/2-handbook/integrations/github.md)
|
||||
- **matrix** — its own account(s) on the swarm homeserver, as MCP tools. →
|
||||
[matrix](docs/tools/matrix.md)
|
||||
[matrix](docs/2-handbook/tools/matrix.md)
|
||||
- **knowledge** — the swarm's shared `internal/knowledge` repo, read-only
|
||||
at `/knowledge`, plus hyperhive's own docs in the container. →
|
||||
[knowledge](docs/integrations/knowledge.md)
|
||||
[knowledge](docs/2-handbook/integrations/knowledge.md)
|
||||
- **web UI** — a per-agent page behind the gateway: live terminal of the
|
||||
turn stream, model / effort switching, cancel.
|
||||
- **GUI** (opt-in, `services.hyperhive.agent.gui.enable`) — a Wayland
|
||||
|
|
@ -106,7 +106,7 @@ box it gets:
|
|||
the web UI.
|
||||
- **reverse engineering** (opt-in, `services.hyperhive.agent.rea.enable`, or the
|
||||
`reverse-engineer` archetype) — REA and Ghidra 12.1 in the container, with
|
||||
their MCP tools allowed. → [archetypes](docs/swarm/archetypes.md)
|
||||
their MCP tools allowed. → [archetypes](docs/2-handbook/swarm/archetypes.md)
|
||||
- **your own tools** — any extra MCP server (stdio or http) via
|
||||
`services.hyperhive.agent.extraMcpServers`, and any NixOS config you'd
|
||||
put on a machine.
|
||||
|
|
@ -114,7 +114,7 @@ box it gets:
|
|||
## Quick start: an all-local swarm
|
||||
|
||||
The whole swarm on one box — a hive plus every shared service. Good for a
|
||||
dev box or a single-host deployment; [`docs/swarm/`](docs/swarm/README.md)
|
||||
dev box or a single-host deployment; [`docs/swarm/`](docs/2-handbook/swarm/README.md)
|
||||
covers spreading a swarm across hosts.
|
||||
|
||||
```nix
|
||||
|
|
@ -158,7 +158,7 @@ After `nixos-rebuild switch` the swarm UI answers on the swarm domain, and
|
|||
the hive brings up the manager agent (`ruth`). A few steps stay
|
||||
deliberately human — initialising the secret store, giving ruth her store
|
||||
identity, creating your SSO account. Walk through
|
||||
**[`docs/getting-started/setup.md`](docs/getting-started/setup.md)**
|
||||
**[`docs/1-getting-started/setup.md`](docs/1-getting-started/setup.md)**
|
||||
once, top to bottom.
|
||||
|
||||
## Operating it
|
||||
|
|
@ -167,14 +167,14 @@ once, top to bottom.
|
|||
(`admins` group): hive roster and status, every agent with its live
|
||||
terminal and wanted state, creating agents, linking external forge and
|
||||
matrix accounts, the job graph, a cross-repo issue report. →
|
||||
[`docs/swarm/ui.md`](docs/swarm/ui.md)
|
||||
[`docs/2-handbook/swarm/ui.md`](docs/2-handbook/swarm/ui.md)
|
||||
- **`swarmctl`** — the swarm's CLI, on the swarm-controller host: create
|
||||
agents and mint their identities, manage SSO users, make forge admins.
|
||||
→ [reference](docs/tools/swarmctl-cli.md)
|
||||
→ [reference](docs/2-handbook/reference/swarmctl-cli.md)
|
||||
- **per-hive** — each hive's dashboard (container state,
|
||||
rebuild queue) and `hivectl` for host-level administration and
|
||||
container shells. → [`docs/web-ui/`](docs/web-ui/README.md) ·
|
||||
[hivectl](docs/tools/hivectl.md)
|
||||
container shells. → [`docs/web-ui/`](docs/2-handbook/web-ui/README.md) ·
|
||||
[hivectl](docs/2-handbook/tools/hivectl.md)
|
||||
|
||||
You are an SSO user too: `swarmctl user add <you> --group admins`, and a
|
||||
first login through authelia creates your forge and matrix accounts;
|
||||
|
|
@ -187,10 +187,10 @@ one becomes a homeserver admin within five minutes of that first login.
|
|||
pick the page for your task rather than reading front to back. Some
|
||||
common entry points:
|
||||
|
||||
- connecting hives into a swarm → [`swarm/`](docs/swarm/README.md)
|
||||
- how config changes flow → [`agent-lifecycle/config-changes.md`](docs/agent-lifecycle/config-changes.md)
|
||||
- trust boundary + threat model → [`trust-boundary/`](docs/trust-boundary/boundary.md)
|
||||
- what an agent's turn looks like → [`turn-loop/`](docs/turn-loop/README.md)
|
||||
- connecting hives into a swarm → [`swarm/`](docs/2-handbook/swarm/README.md)
|
||||
- how config changes flow → [`agent-lifecycle/config-changes.md`](docs/2-handbook/agent-lifecycle/config-changes.md)
|
||||
- trust boundary + threat model → [`trust-boundary/`](docs/2-handbook/trust-boundary/boundary.md)
|
||||
- what an agent's turn looks like → [`turn-loop/`](docs/4-implementation/turn-loop/README.md)
|
||||
- every `services.hyperhive.*` option → [options reference](https://hyperhive.darkest.space/options/)
|
||||
|
||||
## Hacking on it
|
||||
|
|
@ -205,6 +205,6 @@ sudo nixos-rebuild switch --flake .#<host>
|
|||
```
|
||||
|
||||
Conventions (commit style, no `#[allow(clippy::…)]`, the pre-push hook)
|
||||
live in [`docs/process/conventions.md`](docs/process/conventions.md).
|
||||
live in [`docs/5-project/process/conventions.md`](docs/5-project/process/conventions.md).
|
||||
Issues + backlog are on the
|
||||
[forge](https://forge.darkest.space/hyperhive/hyperhive/issues).
|
||||
|
|
|
|||
|
|
@ -84,11 +84,11 @@ Run `nixos-rebuild switch --flake .#my-host`. The swarm UI then answers at
|
|||
Leave the other options at their defaults until you need them:
|
||||
|
||||
- Spreading a swarm over more than one host, and the credentials a split swarm
|
||||
needs: [`swarm/README.md`](../swarm/README.md) and
|
||||
[`swarm/credentials.md`](../swarm/credentials.md).
|
||||
needs: [`swarm/README.md`](../2-handbook/swarm/README.md) and
|
||||
[`swarm/credentials.md`](../2-handbook/swarm/credentials.md).
|
||||
- Every option, with its type and default:
|
||||
[the options reference](https://hyperhive.darkest.space/options/).
|
||||
- The secret store's seal and the granter: [`swarm/bao.md`](../swarm/bao.md).
|
||||
- The secret store's seal and the granter: [`swarm/bao.md`](../4-implementation/swarm/bao.md).
|
||||
|
||||
## Next
|
||||
|
||||
|
|
@ -10,7 +10,7 @@ Every command runs as **root on the host**.
|
|||
|
||||
> **Not all-local?** Each step says which host it runs on. A split swarm
|
||||
> also has credentials you can't generate where they're read — each
|
||||
> host's mTLS identity at the secret store. Read [`swarm/credentials.md`](../swarm/credentials.md) first; it
|
||||
> host's mTLS identity at the secret store. Read [`swarm/credentials.md`](../2-handbook/swarm/credentials.md) first; it
|
||||
> says which files you place, and where.
|
||||
|
||||
## 1 · Secret store
|
||||
|
|
@ -53,7 +53,7 @@ active` while the store comes up; the units retry every 30s for a day.
|
|||
With the default `pkcs11` seal the store unseals itself from here on. With
|
||||
`deploy.bao.seal = "shamir"`, run `bao operator unseal` after every restart.
|
||||
What the granter is, why it's root-equivalent, and the store's TLS:
|
||||
[`swarm/bao.md`](../swarm/bao.md).
|
||||
[`swarm/bao.md`](../4-implementation/swarm/bao.md).
|
||||
|
||||
## 2 · Your SSO account
|
||||
|
||||
|
|
@ -71,13 +71,13 @@ It prints a generated password once — record it. Keep both flags:
|
|||
- **`--email`** — the forge won't create an account without one.
|
||||
|
||||
Fix either afterwards with `swarmctl user update mara --add-group admins
|
||||
--email …`. Details: [`swarm/sso.md`](../swarm/sso.md).
|
||||
--email …`. Details: [`swarm/sso.md`](../2-handbook/swarm/sso.md).
|
||||
|
||||
## 3 · Swarm UI login
|
||||
|
||||
Open `https://<swarm.domain>/` and sign in with the account from step 2. The
|
||||
name resolves on the box itself through `/etc/hosts`; from anywhere else it
|
||||
needs a real DNS record. → [`swarm/ui.md`](../swarm/ui.md)
|
||||
needs a real DNS record. → [`swarm/ui.md`](../2-handbook/swarm/ui.md)
|
||||
|
||||
Signing in to the forge once through SSO creates your forge account under the
|
||||
same username. Then, _on the swarm-controller's host_:
|
||||
|
|
@ -114,7 +114,7 @@ container keeps starting with the hive meanwhile.
|
|||
From here on, ask ruth. Open her card on `/agents` in the swarm UI and use the
|
||||
message box under her terminal. She is the manager agent: her MCP surface is the
|
||||
privileged one that configures agents, and she can recover the others. Changes to
|
||||
an agent's config arrive as PRs you merge. → [`agent-lifecycle/agent-roster.md`](../agent-lifecycle/agent-roster.md)
|
||||
an agent's config arrive as PRs you merge. → [`agent-lifecycle/agent-roster.md`](../2-handbook/agent-lifecycle/agent-roster.md)
|
||||
|
||||
To create an agent yourself instead, use the swarm UI, or:
|
||||
|
||||
|
|
@ -129,10 +129,10 @@ swarm UI's job view for progress.
|
|||
|
||||
Later config changes are PRs on `agent-configs/iris`; you merge them on the
|
||||
forge, and the merge deploys them. →
|
||||
[`agent-lifecycle/config-changes.md`](../agent-lifecycle/config-changes.md#config-changes)
|
||||
[`agent-lifecycle/config-changes.md`](../2-handbook/agent-lifecycle/config-changes.md#config-changes)
|
||||
|
||||
## After setup: use the swarm UI
|
||||
|
||||
Day-to-day operation happens in the swarm UI at `https://<swarm.domain>/`:
|
||||
agents, hives, jobs and messages. Swarm-level operations take over from the
|
||||
per-hive dashboard and `hivectl`. → [`swarm/ui.md`](../swarm/ui.md)
|
||||
per-hive dashboard and `hivectl`. → [`swarm/ui.md`](../2-handbook/swarm/ui.md)
|
||||
|
|
@ -13,7 +13,7 @@ This doc covers what the roster file holds, the map-shaped alternative
|
|||
## Where the roster lives
|
||||
|
||||
"The roster" means two different, non-overlapping things depending on
|
||||
scope. The [README](../../README.md)'s control-plane row ("`swarm-controller`
|
||||
scope. The [README](../../../README.md)'s control-plane row ("`swarm-controller`
|
||||
holds the hive directory, the agent roster and the job graph") is the
|
||||
**swarm-wide** one: `GET /api/agents` on swarm-controller reads
|
||||
straight from the swarm's authelia identity store over
|
||||
|
|
@ -96,7 +96,7 @@ state dirs work as for every other agent.
|
|||
into the caller's own inbox) is on this socket too, unprivileged on
|
||||
both flavours; matrix, bash and forge don't call it — their
|
||||
notifications push a todo on the harness's in-agent socket (see
|
||||
[`docs/turn-loop/mcp.md`](../turn-loop/mcp.md#waking-the-agent-from-inside-the-container)).
|
||||
[`docs/4-implementation/turn-loop/mcp.md`](../../4-implementation/turn-loop/mcp.md#waking-the-agent-from-inside-the-container)).
|
||||
- **Storage/mounts** — the `manage_root_agent` permission, which the swarm
|
||||
UI's setup assistant creates ruth with, gets a container
|
||||
`/var/lib/hyperhive/agents` bind-mounted RW at `/agents` (so it can
|
||||
|
|
@ -115,7 +115,7 @@ state dirs work as for every other agent.
|
|||
from an [archetype](../swarm/archetypes.md) is told it has no config repo.
|
||||
- **Tool allow-list** — the MCP tools claude sees come from the agent's
|
||||
permissions alone, the same mechanism for every agent
|
||||
([`docs/turn-loop/mcp.md`](../turn-loop/mcp.md)). Ruth's permissions
|
||||
([`docs/4-implementation/turn-loop/mcp.md`](../../4-implementation/turn-loop/mcp.md)). Ruth's permissions
|
||||
are the default plus `manage_root_agent`, stored for her like any grant.
|
||||
- **State dirs** — _not_ treated as an exception: `HYPERHIVE_STATE_DIR` is
|
||||
injected uniformly via `systemd.globalEnvironment` for every
|
||||
|
|
@ -116,7 +116,7 @@ agent's forge config repo, the one config PRs merge into) and one
|
|||
(the dashboard port, the pinned claude-code, extra OTEL labels, the queue
|
||||
address) aren't in it:
|
||||
`hive-priv` writes them to the container's `/etc/hyperhive-hive-facts` at
|
||||
start (see `docs/process/conventions.md`).
|
||||
start (see `docs/5-project/process/conventions.md`).
|
||||
A config that sits only in a local checkout, not on forge `main`, never
|
||||
deploys.
|
||||
|
||||
|
|
@ -134,14 +134,14 @@ is unset, since every agent would come up with no forge.
|
|||
|
||||
swarm-controller commits `internal/meta`: one `flake.nix` and `flake.lock` for
|
||||
every agent any hive places (the pins:
|
||||
[`docs/swarm/builder.md`](../swarm/builder.md#meta-flake-lock)). The swarm
|
||||
[`docs/4-implementation/swarm/builder.md`](../../4-implementation/swarm/builder.md#meta-flake-lock)). The swarm
|
||||
builder builds every agent from it, and a hive deploys that build. While the
|
||||
swarm has recorded no build of an agent, that agent's deploy fails and names the
|
||||
agent. The controller queues
|
||||
its update of the repo before the deploy request for a merged config commit
|
||||
and for a new agent, and sends the deploy only when that update succeeded and
|
||||
the swarm builder built the agent from the updated repo (the
|
||||
[deploy gate](../swarm/builder.md#deploy-gate)). A failed build skips the deploy, and the timer builds again. A merge whose webhook delivery never arrives gets the same update, build and deploy within five minutes, from the controller's drift pass (see the paragraph on config drift in the deploy gate section).
|
||||
[deploy gate](../../4-implementation/swarm/builder.md#deploy-gate)). A failed build skips the deploy, and the timer builds again. A merge whose webhook delivery never arrives gets the same update, build and deploy within five minutes, from the controller's drift pass (see the paragraph on config drift in the deploy gate section).
|
||||
|
||||
- **Choosing the closure.** The hive doesn't choose. It deploys the closure the
|
||||
agent's record in `agent-closures` declares, whichever `internal/meta` commit
|
||||
|
|
@ -163,7 +163,7 @@ the swarm builder built the agent from the updated repo (the
|
|||
`{"op":"update_container","name":"atlas","stream":true,"toplevel":"/nix/store/<hash>-nixos-system-atlas"}`.
|
||||
A rebuild with no record, or none the builder pushed, fails with an error
|
||||
that names the agent; see
|
||||
[`docs/swarm/builder.md`](../swarm/builder.md#rebuilds-download-the-closure).
|
||||
[`docs/4-implementation/swarm/builder.md`](../../4-implementation/swarm/builder.md#rebuilds-download-the-closure).
|
||||
- **Hyperhive.** The commit pins one hyperhive rev for the swarm, so an agent
|
||||
runs the hyperhive of the controller's deploy, not its hive's.
|
||||
- **Marker.** After a successful swap or create `hive-c0re` writes the closure's
|
||||
|
|
@ -218,7 +218,7 @@ each `git` call inline, never writing it into a repo's config, so
|
|||
no stored token sits in a repo an agent might one day read.
|
||||
|
||||
The dashboard deep-links into this org — a `config repo` link
|
||||
per container row. See `docs/web-ui/dashboard.md`.
|
||||
per container row. See `docs/2-handbook/web-ui/dashboard.md`.
|
||||
|
||||
### Submitting agent's view of config repos
|
||||
|
||||
|
|
@ -234,7 +234,7 @@ path reaches the same file without the review.
|
|||
|
||||
Agents holding the `manage_root_agent` permission (granted per agent in
|
||||
the swarm's `agent-permissions` record; see
|
||||
`docs/process/conventions.md#permissions`) get additional host-side bind
|
||||
`docs/5-project/process/conventions.md#permissions`) get additional host-side bind
|
||||
mounts via `set_nspawn_flags`:
|
||||
|
||||
- `/var/lib/hyperhive/agents/<n>/state` → `/agents/<n>/state` (RW) for
|
||||
|
|
@ -329,7 +329,7 @@ Today hive-c0re sends two: the `/knowledge updated` broadcast
|
|||
detected"`; a swarm-level grafana alert matches that log line directly
|
||||
and pages the operator, with no agent (and no per-hive dashboard
|
||||
banner) in the loop. See
|
||||
[`docs/scheduler/observability.md`](../scheduler/observability.md#container-crash-alerting-hive-c0re).
|
||||
[`docs/4-implementation/scheduler/observability.md`](../../4-implementation/scheduler/observability.md#container-crash-alerting-hive-c0re).
|
||||
|
||||
The remaining lower-urgency lifecycle notices — `Rebuilt`, `Killed`,
|
||||
`Destroyed`, `NeedsLogin`, `LoggedIn` — are "FYI, check
|
||||
|
|
@ -62,8 +62,8 @@ table, and the per-agent power-intent registry:
|
|||
This is the durable power *intent* the job queue reconciles the
|
||||
observed container state against; intent survives hive-c0re
|
||||
restarts even though in-flight queue work doesn't. See
|
||||
[`docs/scheduler/coordinator.md`'s Desired-state
|
||||
section](../scheduler/coordinator.md#desired-state-spec-vs-status) for who
|
||||
[`docs/4-implementation/scheduler/coordinator.md`'s Desired-state
|
||||
section](../../4-implementation/scheduler/coordinator.md#desired-state-spec-vs-status) for who
|
||||
writes and reads it and how reconciliation works.
|
||||
|
||||
On a host whose hive-c0re once kept scheduled prompts, the file also
|
||||
|
|
@ -114,7 +114,7 @@ back through when debugging a regression. Age-only within the
|
|||
history sooner than a quiet one. The trade-off (accepted): a
|
||||
misbehaving harness can skip its own cleanup — but a compromised harness is
|
||||
already inside the container trust boundary
|
||||
([`docs/trust-boundary/security.md`](../trust-boundary/security.md)), and these are ephemeral local
|
||||
([`docs/2-handbook/trust-boundary/security.md`](../trust-boundary/security.md)), and these are ephemeral local
|
||||
artifacts, so cleaning them up where they live is the honest fix.
|
||||
<!-- vale write-good.Passive = YES -->
|
||||
|
||||
|
|
@ -236,7 +236,7 @@ destroy/recreate, gone on `--purge`.
|
|||
Empty marker file. Its presence parks the agent's turn loop: the
|
||||
harness keeps serving its web UI and MCP daemons but drives no turns,
|
||||
and inbox messages queue unacked until it's removed (see
|
||||
[turn loop](../turn-loop/README.md#the-loop)).
|
||||
[turn loop](../../4-implementation/turn-loop/README.md#the-loop)).
|
||||
|
||||
<!-- vale write-good.Passive = NO -->
|
||||
Unusually, it's read and written from **both** sides of the harness
|
||||
|
|
@ -278,7 +278,7 @@ Under `/var/lib/hyperhive/agents/<name>/`:
|
|||
has a value.
|
||||
- `hyperhive-harness.json` — rate-limited / needs-login flags read
|
||||
by the dashboard's async container-state fetch. See
|
||||
`docs/web-ui/dashboard.md::Container row`.
|
||||
`docs/2-handbook/web-ui/dashboard.md::Container row`.
|
||||
|
||||
The agent writes its own instructions to `AGENTS.md` here; claude and
|
||||
opencode load it automatically from their cwd, `state/`. At boot,
|
||||
|
|
@ -289,7 +289,7 @@ Under `/var/lib/hyperhive/agents/<name>/`:
|
|||
to the swarm, which reads that copy, and applies the git diffs the
|
||||
swarm sends to edit it. A new agent's first start writes the text given at
|
||||
create, only when no file exists. This file stays the only copy that counts:
|
||||
[`docs/swarm/README.md`](../swarm/README.md#an-agents-agentsmd).
|
||||
[`docs/2-handbook/swarm/README.md`](../swarm/README.md#an-agents-agentsmd).
|
||||
- `harness/` — harness-internal ephemeral state; not intended for
|
||||
agent consumption. Bind-mounted to `/agents/<name>/harness`
|
||||
inside the container (`$HYPERHIVE_HARNESS_DIR`). Contents:
|
||||
|
|
@ -667,7 +667,7 @@ subvolume creation/deletion above.
|
|||
|
||||
This is the same subvolume `hivectl agent <name> subvol snapshot push`
|
||||
sends to the swarm's snapshot store — see
|
||||
[`docs/networking/snapshot-store.md`](../networking/snapshot-store.md) for what a pushed
|
||||
[`docs/4-implementation/networking/snapshot-store.md`](../../4-implementation/networking/snapshot-store.md) for what a pushed
|
||||
snapshot contains and how the store authenticates a sender.
|
||||
|
||||
The subvolume is the whole agent state root, so `work/` is part of every
|
||||
|
|
@ -704,7 +704,7 @@ the store answers that it holds none, never because a read failed.
|
|||
place; a missing file is an empty set. A file the controller can't
|
||||
read or parse stops the sync, grants included, and the controller logs
|
||||
`operator matrix admin: pass failed` on every pass. See
|
||||
[`docs/integrations/matrix.md`](../integrations/matrix.md#operators-are-homeserver-admins).
|
||||
[`docs/2-handbook/integrations/matrix.md`](../integrations/matrix.md#operators-are-homeserver-admins).
|
||||
|
||||
## Run-time dirs
|
||||
|
||||
|
|
@ -10,7 +10,7 @@ which build it runs, how it's served, what it mirrors, where its
|
|||
host-local secrets sit).
|
||||
Container
|
||||
shape, ROOT_URL / sub-domain routing, and operator-vs-in-cluster URL
|
||||
handling live in [`docs/networking/gateway.md`](../networking/gateway.md); this file owns the
|
||||
handling live in [`docs/4-implementation/networking/gateway.md`](../../4-implementation/networking/gateway.md); this file owns the
|
||||
per-agent integration story and the notification pump that wakes
|
||||
each agent on relevant activity.
|
||||
|
||||
|
|
@ -114,7 +114,7 @@ git+<forge>/agent-configs/<n>.git?rev=<sha>`; see
|
|||
[config-changes.md § Meta flake](../agent-lifecycle/config-changes.md#meta-flake)).
|
||||
|
||||
The `hive-forge` CLI (separate workspace crate, see
|
||||
[`README.md`](../README.md) file map) wraps the Forgejo REST API
|
||||
[`README.md`](../../README.md) file map) wraps the Forgejo REST API
|
||||
with the per-agent token; agents call it for issue / PR / comment
|
||||
ops as if it were a peer. All REST calls across the workspace
|
||||
(`hive-forge` verbs, hive-c0re provisioning, this poller) go through
|
||||
|
|
@ -392,4 +392,4 @@ delivers every unread notification it's handed. A hive-forge CLI
|
|||
subscription verb bounds the firehose explicitly (dropping broad repo
|
||||
watches an agent doesn't need) — the poller never guesses which
|
||||
watches to drop. See the `subscription` verb in
|
||||
[`docs/tools/forge.md`](../tools/forge.md).
|
||||
[`docs/2-handbook/tools/forge.md`](../tools/forge.md).
|
||||
|
|
@ -44,7 +44,7 @@ hive-c0re maintains the local clone at
|
|||
`/var/lib/hyperhive/knowledge` via two paths:
|
||||
|
||||
1. **Swarm event** — the swarm controller holds the single push hook on
|
||||
`internal/knowledge` (see `docs/swarm/README.md` § Swarm-wide forge
|
||||
`internal/knowledge` (see `docs/2-handbook/swarm/README.md` § Swarm-wide forge
|
||||
webhooks). On any push to main, including merge commits, it sends an
|
||||
event to every hive over the swarm queue and each hive runs `git
|
||||
pull`, so agents see the new content on their next turn.
|
||||
|
|
@ -11,11 +11,11 @@ homeserver, on one host. Two namespaces configure it:
|
|||
`enable`, `gui.package`, `trustedServers`,
|
||||
`maxRequestSize`, `sso.clientSecretFile`.
|
||||
|
||||
Vhost routing lives in [`gateway.md`](../networking/gateway.md).
|
||||
Vhost routing lives in [`gateway.md`](../../4-implementation/networking/gateway.md).
|
||||
|
||||
## Container shape
|
||||
|
||||
Same shape as [`gateway.md::hive-forge container shape`](../networking/gateway.md):
|
||||
Same shape as [`gateway.md::hive-forge container shape`](../../4-implementation/networking/gateway.md):
|
||||
|
||||
- Container name `hive-matrix` (not `h-*`) so c0re's lifecycle
|
||||
scanner ignores it; operator manages via the standard
|
||||
|
|
@ -101,7 +101,7 @@ the hive has no matrix API URL to set.
|
|||
|
||||
Federation peers find the homeserver through `.well-known/matrix/server`
|
||||
at the server name, which names `<gatewayHost>:443`
|
||||
([`gateway.md::Discovery flow`](../networking/gateway.md#discovery-flow-matrix)).
|
||||
([`gateway.md::Discovery flow`](../../4-implementation/networking/gateway.md#discovery-flow-matrix)).
|
||||
Port 8448 isn't used.
|
||||
|
||||
Outbound, the container sits on the hive bridge like the CI runner: it
|
||||
|
|
@ -392,7 +392,7 @@ homeserver at all rather than of a setting:
|
|||
|
||||
`server_name`'s own bogus-value guard lives in `hive-network.nix`
|
||||
(`services.hyperhive.domain != null`), not here — see
|
||||
[`docs/networking/network.md`](../networking/network.md).
|
||||
[`docs/4-implementation/networking/network.md`](../../4-implementation/networking/network.md).
|
||||
|
||||
## fluffychat-web build fixes
|
||||
|
||||
|
|
@ -8,8 +8,8 @@ host is a swarm of one.
|
|||
|
||||
This page is for the operator. It covers the control plane, how a hive
|
||||
joins the directory, and how hives and agents report upward. The steps for a
|
||||
fresh swarm are in [`setup.md`](../getting-started/setup.md); the all-local
|
||||
config is the [README quick start](../../README.md#quick-start-an-all-local-swarm).
|
||||
fresh swarm are in [`setup.md`](../../1-getting-started/setup.md); the all-local
|
||||
config is the [README quick start](../../../README.md#quick-start-an-all-local-swarm).
|
||||
|
||||
Option reference: `services.hyperhive.swarm.*` (swarm-wide facts, identical
|
||||
on every host) and `services.hyperhive.deploy.*` (whether _this_ host runs
|
||||
|
|
@ -24,17 +24,17 @@ grafana, the controller, authelia, …) →
|
|||
- **scheduled prompts** — named prompts for one or more agents at set times,
|
||||
kept by the swarm and fired in each agent's container. → [`schedules.md`](schedules.md)
|
||||
- **inference settings** — the model and effort the swarm sets for an agent,
|
||||
over its own. → [`inference.md`](inference.md)
|
||||
over its own. → [`inference.md`](../../4-implementation/swarm/inference.md)
|
||||
- **resource caps** — the CPU and memory cap the swarm sets for an agent,
|
||||
over its hive's. →
|
||||
[`coordinator.md`](../scheduler/coordinator.md#container-resource-limits)
|
||||
[`coordinator.md`](../../4-implementation/scheduler/coordinator.md#container-resource-limits)
|
||||
- **review classifier** — checks a PR against its repo's own yes/no rules
|
||||
and posts the result as a review. →
|
||||
[`review-classifier.md`](review-classifier.md)
|
||||
[`review-classifier.md`](../../4-implementation/swarm/review-classifier.md)
|
||||
- **notification router** — forge events turned into todos on the agents
|
||||
they concern: assigned, unassigned, cleared on close; and the classifier's
|
||||
review requested on a push. →
|
||||
[`notify-router.md`](notify-router.md)
|
||||
[`notify-router.md`](../../4-implementation/swarm/notify-router.md)
|
||||
- **swarm UI** — the operator's day-to-day surface, on the swarm apex,
|
||||
`admins` only. → [`ui.md`](ui.md)
|
||||
- **shared services** — one forge, homeserver, SSO, queue and metrics/logs
|
||||
|
|
@ -45,12 +45,12 @@ grafana, the controller, authelia, …) →
|
|||
every credential the swarm holds, who mints it, who reads it, how it renews
|
||||
and where it lives → [`credentials-reference.md`](credentials-reference.md) ·
|
||||
how the store comes up, who writes its grants and how it unseals →
|
||||
[`bao.md`](bao.md)
|
||||
[`bao.md`](../../4-implementation/swarm/bao.md)
|
||||
- **swarm CA** — the store root every hive's gateway leaf chains to, and what to
|
||||
hand a peer. → [`ca.md`](ca.md)
|
||||
hand a peer. → [`ca.md`](../../4-implementation/swarm/ca.md)
|
||||
- **snapshot store** — the swarm's one `btrfs receive` endpoint,
|
||||
`swarm.snapshotStore.{address,port}`. →
|
||||
[`snapshot-store.md`](../networking/snapshot-store.md)
|
||||
[`snapshot-store.md`](../../4-implementation/networking/snapshot-store.md)
|
||||
|
||||
## Swarm controller
|
||||
|
||||
|
|
@ -74,7 +74,7 @@ fact about swarm topology, not about whether this host runs a hive.
|
|||
|
||||
What it serves, why it's a unix socket rather than a port, and the
|
||||
socket-directory constraint that governs where `socketPath` may point:
|
||||
[`swarm-controller/README.md`](../../swarm-controller/README.md).
|
||||
[`swarm-controller/README.md`](../../../swarm-controller/README.md).
|
||||
|
||||
### Per-hive status (`GET /api/hives/status`)
|
||||
|
||||
|
|
@ -102,7 +102,7 @@ needs. A hive on an older release lists none.
|
|||
The snapshot also carries `egress_deny_applied`, the revision of the egress deny
|
||||
list the hive last rendered into its proxy (`0` when the swarm has none). A hive
|
||||
on an older release, or one that hasn't read the list yet, leaves it out; see
|
||||
[the egress proxy](../networking/network.md#egress-proxy-squid).
|
||||
[the egress proxy](../../4-implementation/networking/network.md#egress-proxy-squid).
|
||||
|
||||
Every row also carries `last_seen_unix` and `age_seconds` if you want to
|
||||
apply your own threshold. The timestamp is the one the queue recorded on
|
||||
|
|
@ -292,7 +292,7 @@ Swarm-side, `GET /api/agents/<name>/state/stream` relays that subject as SSE,
|
|||
resolving the agent's hive at request time exactly as the terminal stream does.
|
||||
The payload passes through opaquely. Separately, the controller keeps each
|
||||
agent's latest `model`, `effort` and their sources for
|
||||
`GET /api/agents/<name>/inference` ([`inference.md`](inference.md)), and each
|
||||
`GET /api/agents/<name>/inference` ([`inference.md`](../../4-implementation/swarm/inference.md)), and each
|
||||
agent's latest `needs_login` for the `needs_login` field of
|
||||
`GET /api/agents/status`. That field is `null` until a header carrying the flag
|
||||
arrives, so for up to a minute after the controller starts, and for an agent
|
||||
|
|
@ -434,12 +434,12 @@ itself, all under `https://<swarm.domain>/webhook/forge/`:
|
|||
- a `pull_request` hook on the `agent-configs` org
|
||||
- an instance-wide `push` system hook, for commit metrics
|
||||
- an instance-wide `pull_request_review_request` system hook, which starts
|
||||
the [review classifier](review-classifier.md#trigger-and-lifecycle)
|
||||
the [review classifier](../../4-implementation/swarm/review-classifier.md#trigger-and-lifecycle)
|
||||
- instance-wide `issues` + `issue_assign` and `pull_request` +
|
||||
`pull_request_assign` + `pull_request_sync` + `pull_request_review_approved` +
|
||||
`pull_request_review_rejected` + `pull_request_review_comment` system hooks, whose deliveries it
|
||||
keeps in the `SWARM_EVENTS` stream for the
|
||||
[notification router](notify-router.md#the-path)
|
||||
[notification router](../../4-implementation/swarm/notify-router.md#the-path)
|
||||
|
||||
The controller **interprets** a delivery and sends hives a specific
|
||||
message — _the knowledge repo changed_, _deploy agent `foo` at rev
|
||||
|
|
@ -478,7 +478,7 @@ host also serves the swarm UI vhost — that's what publishes the
|
|||
endpoint, and a hook the forge can't reach would collect failed
|
||||
deliveries while looking healthy. The controller generates the HMAC
|
||||
secret on first start and keeps it
|
||||
(see [`docs/agent-lifecycle/persistence.md`](../agent-lifecycle/persistence.md)).
|
||||
(see [`docs/2-handbook/agent-lifecycle/persistence.md`](../agent-lifecycle/persistence.md)).
|
||||
|
||||
To check it's working, push to `internal/knowledge` and look for
|
||||
`webhook: verified delivery` in `journalctl -u swarm-controller`. A
|
||||
|
|
@ -559,10 +559,10 @@ system prompts — and federated hives at different domains can share one.
|
|||
hive's domain. `swarm.name` names the group; `hiveName` names this hive.
|
||||
|
||||
The env-var chain and `qualify()` semantics:
|
||||
[`conventions.md`](../process/conventions.md) § Hive identity.
|
||||
[`conventions.md`](../../5-project/process/conventions.md) § Hive identity.
|
||||
|
||||
Trust inside a swarm comes from the secret store's `pki` root
|
||||
([`ca.md`](ca.md)): every hive's gateway leaf chains to it. Trusting a
|
||||
([`ca.md`](../../4-implementation/swarm/ca.md)): every hive's gateway leaf chains to it. Trusting a
|
||||
hive whose root this swarm doesn't own — another swarm's — has no
|
||||
mechanism.
|
||||
|
||||
|
|
@ -672,11 +672,11 @@ If both hosts are behind NAT, you need a STUN relay or a third host
|
|||
## Cross-references
|
||||
|
||||
- [`ui.md`](ui.md) — the swarm UI, the operator surface for "what hives exist"
|
||||
- [`../networking/snapshot-store.md`](../networking/snapshot-store.md) — the
|
||||
- [`../networking/snapshot-store.md`](../../4-implementation/networking/snapshot-store.md) — the
|
||||
swarm's `btrfs receive` endpoint and the `swarm.snapshotStore` option
|
||||
- [`../process/conventions.md`](../process/conventions.md) § Hive identity —
|
||||
- [`../process/conventions.md`](../../5-project/process/conventions.md) § Hive identity —
|
||||
env vars, qualified labels
|
||||
- [`../integrations/matrix.md`](../integrations/matrix.md) — matrix
|
||||
federation, TLS cert autogeneration, firewall posture
|
||||
- [`../networking/gateway.md`](../networking/gateway.md) — nginx vhosts and
|
||||
- [`../networking/gateway.md`](../../4-implementation/networking/gateway.md) — nginx vhosts and
|
||||
the `.well-known/matrix/` autodiscovery scheme
|
||||
Some files were not shown because too many files have changed in this diff Show more
Loading…
Reference in a new issue