0f7b403803
A new swarm service, swarm-notify-router, in its own container on the host
that sets deploy.notify-router.enable (defaulted on by allSwarmServices where
the host has the router's store leaf, like the claude login minter).
- swarm-controller registers instance-wide hooks for `issues` +
`issue_assign` and `pull_request` + `pull_request_assign`, updates the
event list of a hook already registered with fewer (leaving its active flag as it is), and keeps each
verified body unchanged in the SWARM_EVENTS stream on
$SWARM.events.forge.<X-Forgejo-Event-Type>, deduped by X-Forgejo-Delivery.
A delivery the stream did not keep answers 503.
- swarm-notify-router drains its durable consumer on that stream, runs its
flows (source -> match -> todo sink, stored as nodes plus edges and checked
to be a tree) and queues each op on $SWARM.router.todo.<agent> in the
work-queue stream ROUTER_TODOS. Built-in flows: assigned, unassigned (same
key, rewritten) and closed (prefix-clears every holder's router todos). A
per-issue snapshot in its notify-router-state bucket holds the last
assignees and the todo holders; only agents in the agent-status bucket get
ops, and an assignee that was not one is left out of the snapshot so the
next assign event retries it. After the first event that must be retried,
the rest of the batch is nakked so redelivery keeps stream order.
- hive-agent creates its own durable consumer todo-<agent> and applies each
op to its todo store as subsystem `router`, then acks; a refused op stops
the rest of its batch the same way. The store's (subsystem, key) dedup
makes a redelivery harmless. New Todos::clear_prefix.
- swarm-nats-auth: a --notify-router-client arm; the controller may publish
$SWARM.events.forge.*; each agent gets three {agent} templates (extended
consumer create whose filter the server checks, MSG.NEXT, ACK).
- Credentials: a notify-router store leaf minted by glue-bao-tls, a
swarm-notify-router bao policy (read on its own queue client secret), an
authelia machine client, the secret publisher entry, a journal forwarder
route. No manual step.
hive-forge-notify is unchanged, so agents also still get forge's own
notifications.
Refs #5571
129 lines
7 KiB
Markdown
129 lines
7 KiB
Markdown
# 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. For the autogenerated NixOS options reference
|
|
(every `services.hyperhive.*` / `hyperhive.*` option, host and agent), see
|
|
[the options site](https://hyperhive.darkest.space/options/) instead —
|
|
this tree is prose, that one's generated straight from the module
|
|
declarations.
|
|
|
|
## Getting started
|
|
|
|
- **Bringing a fresh swarm online?** → [`getting-started/setup.md`](getting-started/setup.md)
|
|
(the hand steps after the first switch).
|
|
- **What does the dashboard look like, and how do I use it?** →
|
|
[`web-ui/`](web-ui/README.md) — the operator-facing starting point;
|
|
its own sub-pages ([`shape`](web-ui/shape.md),
|
|
[`dashboard`](web-ui/dashboard.md), [`agent`](web-ui/agent.md),
|
|
[`css-vars`](web-ui/css-vars.md), [`terminal-rendering`](web-ui/terminal-rendering.md))
|
|
go deeper into implementation.
|
|
- **What tools does an agent (or the operator) have available?** →
|
|
[`tools/`](tools/README.md) — `hivectl` (yours) plus every agent's MCP
|
|
tool surface (bash, forge, lifecycle, matrix).
|
|
|
|
## Agent lifecycle
|
|
|
|
- **How do config changes flow from manager to operator to container?** →
|
|
[`agent-lifecycle/config-changes.md`](agent-lifecycle/config-changes.md)
|
|
(config PRs, the meta flake, helper events).
|
|
- **What state survives destroy / purge / restart?** →
|
|
[`agent-lifecycle/persistence.md`](agent-lifecycle/persistence.md).
|
|
- **Who can do what to whom — the agent roster and privilege?** →
|
|
[`agent-lifecycle/agent-roster.md`](agent-lifecycle/agent-roster.md).
|
|
- **How does claude get its prompt, and what tools does it have?** →
|
|
[`turn-loop/`](turn-loop/README.md) — the loop, binary shape, turn
|
|
outcomes; sub-pages: [`claude-invocation`](turn-loop/claude-invocation.md),
|
|
[`config`](turn-loop/config.md), [`mcp`](turn-loop/mcp.md).
|
|
|
|
## Trust boundary & security
|
|
|
|
- **What's the operator/agent trust boundary? What's a permission?** →
|
|
[`trust-boundary/boundary.md`](trust-boundary/boundary.md).
|
|
- **Agent trust model, prompt-injection threat model, credential
|
|
isolation?** → [`trust-boundary/security.md`](trust-boundary/security.md).
|
|
|
|
## Accounts & integrations
|
|
|
|
- **How do per-agent forge accounts work? What does `forge_notify` poll,
|
|
and how does it format wake messages?** → [`integrations/forge.md`](integrations/forge.md)
|
|
(the swarm's Forgejo); [`tools/forge.md`](tools/forge.md) for the
|
|
`hive-forge` CLI verbs agents actually call.
|
|
- **How does the matrix-tuwunel container work? Multiple accounts per
|
|
agent?** → [`integrations/matrix.md`](integrations/matrix.md) (the homeserver);
|
|
[`tools/matrix.md`](tools/matrix.md) for the MCP tool surface and
|
|
`services.hyperhive.agent.matrixAccounts`.
|
|
- **How do I give an agent a GitHub account (`gh` + `git push`)? how's
|
|
the PAT injected?** → [`integrations/github.md`](integrations/github.md)
|
|
(operator content up top; the `gh`/git-push + notification-poller
|
|
mechanics are in a collapsed "Implementation" section at the bottom).
|
|
- **What's `/knowledge`? How does the swarm-wide knowledge repo sync,
|
|
and how do I contribute a document?** → [`integrations/knowledge.md`](integrations/knowledge.md).
|
|
- **What does `hivectl` do? Provisioning, gateway users, container
|
|
shells?** → [`tools/hivectl.md`](tools/hivectl.md) (the curated guide);
|
|
[`tools/hivectl-cli.md`](tools/hivectl-cli.md) for the exhaustive,
|
|
autogenerated flag reference.
|
|
|
|
## Networking & swarms
|
|
|
|
- **What nginx vhosts does the gateway serve? How does matrix
|
|
discovery work?** → [`networking/gateway.md`](networking/gateway.md).
|
|
- **How does DNS resolution work in agent containers? What's the
|
|
bridge network for?** → [`networking/network.md`](networking/network.md).
|
|
- **How do I connect two hives into a swarm?** → [`swarm/`](swarm/README.md)
|
|
(peer hives, TLS trust).
|
|
- **Where do agent snapshots go? How does the swarm's `btrfs receive`
|
|
endpoint authenticate a pushing hive?** →
|
|
[`networking/snapshot-store.md`](networking/snapshot-store.md).
|
|
- **Who mints each credential, who reads it, and how does it rotate — and
|
|
where's that shape headed?** → [`swarm/credentials.md`](swarm/credentials.md)
|
|
(current state, target state, and the progressive-enhancement rule);
|
|
[`swarm/secrets.md`](swarm/secrets.md) for where each file lives today.
|
|
- **How does the secret store come up, who writes its grants, how's it
|
|
sealed?** → [`swarm/bao.md`](swarm/bao.md).
|
|
- **How does an agent get a prompt at set times, and why doesn't it fire
|
|
twice after downtime?** → [`swarm/schedules.md`](swarm/schedules.md).
|
|
- **How do I set an agent's model or effort from the swarm, and what happens
|
|
to its own pick?** → [`swarm/inference.md`](swarm/inference.md).
|
|
- **How will a PR get checked against its repo's own yes/no rules before
|
|
a full review?** → [`swarm/review-classifier.md`](swarm/review-classifier.md)
|
|
(planned, not implemented yet).
|
|
- **Does an agent config PR build before it's merged?** →
|
|
[`swarm/builder.md`](swarm/builder.md).
|
|
- **How do I create an agent from a ready-made set of permissions and
|
|
settings?** → [`swarm/archetypes.md`](swarm/archetypes.md).
|
|
- **How long do CI runs take, per repo and PR, and where does the board get
|
|
it?** → [`swarm/ci-metrics.md`](swarm/ci-metrics.md).
|
|
- **How do I log an agent in to claude from the swarm UI, and why doesn't a
|
|
stale stored copy log it out again?** →
|
|
[`swarm/claude-login.md`](swarm/claude-login.md).
|
|
- **How does an agent get a todo when someone assigns it an issue, and lose it
|
|
when the issue closes?** → [`swarm/notify-router.md`](swarm/notify-router.md).
|
|
|
|
## Scheduler, CI, observability
|
|
|
|
- **what's the job queue, as a general idea (not hive-c0re specifics)?** →
|
|
[`scheduler/jobq.md`](scheduler/jobq.md) — operator-facing, no implementation detail.
|
|
- **How does the rebuild queue work? What are the concrete step kinds,
|
|
queue sources, scheduler internals?** → [`scheduler/coordinator.md`](scheduler/coordinator.md).
|
|
- **How does the CI runner work? How does it register?** →
|
|
[`scheduler/ci.md`](scheduler/ci.md).
|
|
- **How do I export Claude Code metrics (tokens, cost, tool calls) to
|
|
Prometheus/Grafana?** → [`scheduler/observability.md`](scheduler/observability.md).
|
|
|
|
## Crate reference
|
|
|
|
- **What does a specific Rust crate do, on its own terms?** →
|
|
[`crates/`](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.
|
|
|
|
## Process & conventions
|
|
|
|
- **Naming, commit style, wire protocol, the `data-async` pattern?** →
|
|
[`process/conventions.md`](process/conventions.md).
|
|
- **Why does the nspawn flag look like that?** → [`process/gotchas.md`](process/gotchas.md)
|
|
(bind mounts, conf flags, other NixOS/nspawn quirks).
|
|
- **What does a PR review verdict actually gate?** →
|
|
[`process/pr-review-gate.md`](process/pr-review-gate.md).
|