a0b1846006
swarm-controller keeps every scheduled prompt (id, name, agents, body,
anchor, interval, paused) as one document under one key of a new
`schedule-definitions` KV bucket, so each change is a single
compare-and-set and a prompt exists for all of its agents or none. It
writes each agent's key of a new `agent-schedules` bucket as the prompts
naming that agent, without names or other agents, after every change and
on a one-minute reconcile pass. It is the only writer of both, behind
GET/POST /api/schedules and PATCH/DELETE /api/schedules/{id}.
`swarmctl schedule add|list|edit|pause|resume|rm` drives those routes over
the controller socket.
An agent's own queue credential is granted one more subject, the direct
get of its own key in `agent-schedules`. A KV watch is not granted: its
consumer create subject carries no key, so it would cover every agent's.
hive-agent's new schedule ticker reads that key every 10 seconds and fires
due slots as the same `schedule:<id>` todo hive-c0re's worker pushes. Fire
times are anchor + k*interval; the last fired slot per schedule id is kept
in the state db, so a body edit or list refresh never moves or refires a
slot, downtime fires the latest missed slot once, a restart refires
nothing, a one-shot fires once, and paused slots are skipped.
Refs #4914
113 lines
6 KiB
Markdown
113 lines
6 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, scheduling).
|
|
|
|
## Agent lifecycle
|
|
|
|
- **How do config changes flow from manager to operator to container?** →
|
|
[`agent-lifecycle/approvals.md`](agent-lifecycle/approvals.md) (approval kinds, approval
|
|
state machine, `flake.lock` validation).
|
|
- **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 capability?** →
|
|
[`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 hive's own 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 hive-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).
|
|
|
|
## 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? What's the autoregistration flow?** →
|
|
[`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).
|