vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity

README: lead with the swarm, hives as substrate

Browse source
This commit is contained in:
müde 2026-10-01 20:36:12 +02:00
commit eced5e0365
1 changed files with 69 additions and 63 deletions
Download patch file Download diff file Expand all files Collapse all files

130
README.md
View file

@ -1,9 +1,10 @@
# <img src="branding/hyperhive.svg" alt="" width="38" align="top"> hyperhive # <img src="branding/hyperhive.svg" alt="" width="38" align="top"> hyperhive
> a swarm of coding agents spread across NixOS hosts — every agent in its > a swarm of coding agents with one control plane: one identity, one
> own nspawn cage, every host a hive, one control plane over all of them. > forge, one homeserver, one secret store, one UI. agents run caged on
> config changes flow as git commits, the operator approves them in a > whichever host has room. config changes flow as git commits, the
> browser, every deploy is a tag. cyberpunk dashboard included. 💜⚡ > operator approves them in a browser, every deploy is a tag. cyberpunk
> dashboards included. 💜⚡
**[→ website](https://hyperhive.darkest.space)** · **[→ website](https://hyperhive.darkest.space)** ·
**[→ docs](https://hyperhive.darkest.space/docs/)** · **[→ docs](https://hyperhive.darkest.space/docs/)** ·
@ -11,55 +12,42 @@
A coding agent is great in one window, _exponentielle_ across many — as A coding agent is great in one window, _exponentielle_ across many — as
long as the agents stay off each other's toes, keep a durable identity, long as the agents stay off each other's toes, keep a durable identity,
and leave production alone. hyperhive is the substrate for that, as a set and leave production alone. hyperhive is a set of NixOS modules that runs
of NixOS modules: that many-agent setup as a **swarm**:
- a **hive** is one host running `hive-c0re` and the agent containers it - **the swarm is where things live** — agent identities and accounts,
owns; secrets, the job graph that creates and places agents, telemetry, and
- a **swarm** is any number of hives sharing one identity plane — SSO, the UI you drive it all from.
forge, matrix, secret store, telemetry — with a controller that places - **hives are the substrate** — NixOS hosts that run agent containers on
agents on hives and tracks them across all of them. the swarm's behalf. Add a hive to add capacity.
Start with everything on one box; move services and add hives as the Start with everything on one box; move services and add hives as the
swarm grows. Which host runs what is a per-host `deploy.*` toggle, swarm grows. Which host runs what is a per-host `deploy.*` toggle, not an
not an architecture change. architecture change.
| concern | how hyperhive answers it | | concern | how hyperhive answers it |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **scale-out** | hives share one directory (`swarm.hives`, identical on every host); `swarmctl agent create --hive <h>` places an agent and the controller keeps the roster | | **control plane** | `swarm-controller` holds the hive directory, the agent roster and the job graph. Create an agent from the swarm UI or `swarmctl agent create --hive <h>`: it provisions the SSO identity, forge user and config repo, then deploys the agent onto that hive |
| **identity** | every agent gets swarm-wide accounts — SSO subject, forge user, matrix account, secret-store cert identity — and is addressable as `name@hive.domain` | | **identity** | every agent is a swarm-wide principal — SSO subject, forge user, matrix account, secret-store cert identity — addressable as `name@hive.domain` |
| **shared plane** | one forge, homeserver, secret store, SSO, queue and metrics/logs stack per swarm, each on whichever host you put it | | **secrets** | one OpenBao store; each agent fetches its own credentials under its own identity, nothing copied between hosts by hand |
| **blast radius** | one `nixos-container` per agent; the host daemon runs unprivileged, and a tiny socket-activated helper does the few root ops | | **shared services** | one forge, homeserver, SSO, message queue and metrics/logs stack per swarm, each on whichever host you put it |
| **config** | git: an agent proposes, the operator approves, the deploy lands as a `deployed/<id>` tag | | **config** | git: an agent proposes, the operator approves, the deploy lands as a `deployed/<id>` tag |
| **runtime** | `claude --print` by default; any [ACP](https://agentclientprotocol.com) agent (e.g. opencode) per agent with `services.hyperhive.agent.runtime = "acp"` | | **runtime** | `claude --print` by default; any [ACP](https://agentclientprotocol.com) agent (e.g. opencode) per agent with `services.hyperhive.agent.runtime = "acp"` |
| **watching** | per-agent web UI with a live terminal, a per-hive dashboard, the swarm UI, Grafana over OTEL | | **substrate** | each hive runs one `nixos-container` per agent, under an unprivileged daemon with a tiny socket-activated helper for the few root ops |
| **watching** | the swarm UI (hives, agents with live terminals, jobs, a cross-repo issue report), Grafana over OTEL, and a per-hive dashboard for host-level detail |
## Shape ## Shape
``` ```
every hive (NixOS host, deploy.hive-controller.enable) the swarm — one of each, each on whichever host you choose
│ │
├── operator ├── swarm-controller hive directory, agent roster, job graph
│ ├── browser → :80/:443 (hive-gateway) dashboard + /agent/<name>/ UIs │ ├── swarm-ui the operator's UI, served off the gateway on the swarm apex
│ └── hivectl → /run/hyperhive/host.sock admin protocol │ └── swarmctl its CLI, on the controller's host
│ ├── swarm-authelia SSO in front of the swarm UI, forge, grafana, …
├── hive-c0re Rust daemon: lifecycle, broker, approvals, job queue, ├── swarm-bao OpenBao — secrets, a cert identity per agent
│ auto-rebuild, dashboard — runs as the unprivileged hive-core user ├── hive-forge Forgejo — per-agent accounts, config repos
├── hive-priv root helper, socket-activated, does bind-mounts + nsenter
├── hive-gateway nginx + dnsmasq in front of c0re and every agent socket
│
└── agent containers
├── h-ruth manager — privileged MCP surface, spawns + configures agents
└── h-<name> agent — claude / ACP runtime, MCP tools, web UI, own socket
the swarm's shared services (one host each — any hive, or a dedicated box)
│
├── hive-forge Forgejo — per-agent accounts, config mirror
├── hive-matrix tuwunel — matrix homeserver, per-agent accounts ├── hive-matrix tuwunel — matrix homeserver, per-agent accounts
├── swarm-bao OpenBao — the swarm's secret store, cert auth per agent
├── swarm-controller cross-hive state: hive directory, agent roster, jobs
│ (+ swarmctl, + swarm-ui served off the gateway)
├── swarm-authelia SSO in front of swarm-ui, forge, grafana, …
├── swarm-nats message queue (JetStream KV: hive status, …) ├── swarm-nats message queue (JetStream KV: hive status, …)
├── swarm-otel telemetry collector, sole holder of upstream creds ├── swarm-otel telemetry collector, sole holder of upstream creds
├── swarm-victoriametrics metrics store ├── swarm-victoriametrics metrics store
@ -70,6 +58,18 @@ the swarm's shared services (one host each — any hive, or a dedicated box)
├── hive-ci Forgejo Actions runner (deploy.forgejo.ci) ├── hive-ci Forgejo Actions runner (deploy.forgejo.ci)
├── swarm-snapshot-store btrfs-receive endpoint for agent snapshots ├── swarm-snapshot-store btrfs-receive endpoint for agent snapshots
└── wg-hive WireGuard mesh between hives (deploy.wireguard) └── wg-hive WireGuard mesh between hives (deploy.wireguard)
the hives — the substrate, as many as you like (deploy.hive-controller.enable)
│
├── hive-c0re runs the agent containers: lifecycle, approvals, broker,
│ auto-rebuild, the per-hive dashboard; unprivileged
├── hive-priv root helper, socket-activated, does bind-mounts + nsenter
├── hive-gateway nginx + dnsmasq on :80/:443, fronts every agent's web UI
├── hivectl host-level CLI
│
└── agent containers
├── h-ruth manager — privileged MCP surface, configures agents
└── h-<name> agent — claude / ACP runtime, MCP tools, web UI
``` ```
## Inside an agent ## Inside an agent
@ -117,8 +117,10 @@ covers spreading a swarm across hosts.
{ {
inputs = { inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05"; nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05";
hyperhive.url = "git+https://forge.darkest.space/hyperhive/hyperhive"; hyperhive = {
hyperhive.inputs.nixpkgs.follows = "nixpkgs"; # see "Overriding nixpkgs" url = "git+https://forge.darkest.space/hyperhive/hyperhive";
inputs.nixpkgs.follows = "nixpkgs"; # see "Overriding nixpkgs"
};
}; };
outputs = { nixpkgs, hyperhive, ... }: { outputs = { nixpkgs, hyperhive, ... }: {
@ -128,7 +130,8 @@ covers spreading a swarm across hosts.
hyperhive.nixosModules.default # the whole host stack, one import hyperhive.nixosModules.default # the whole host stack, one import
{ {
services.hyperhive = { services.hyperhive = {
deploy.singleHostSwarm = true; # run everything on one machine deploy.singleHostSwarm = true; # every swarm service on this machine
deploy.hive-controller.enable = true; # …and a hive to run agents on
swarm.domain = "hive.example"; # the swarm's DNS domain swarm.domain = "hive.example"; # the swarm's DNS domain
hiveName = "pr1ma"; # this hive's label in it hiveName = "pr1ma"; # this hive's label in it
@ -152,10 +155,10 @@ the shared services above, the swarm CA, the swarm controller, and
`claude-code` is unfree — hyperhive scopes the allowance to itself, so `claude-code` is unfree — hyperhive scopes the allowance to itself, so
there's nothing to set. there's nothing to set.
After `nixos-rebuild switch`, hive-c0re creates the manager (`ruth`) and After `nixos-rebuild switch` the swarm UI answers on the swarm domain, and
keeps every container rebuilt whenever its hyperhive rev goes stale. A few the hive brings up the manager agent (`ruth`). A few steps stay
steps stay deliberately human — initialising the secret store, giving ruth deliberately human — initialising the secret store, giving ruth her store
her store identity, adding a gateway login, SSO. Walk through identity, creating your SSO account. Walk through
**[`docs/getting-started/setup.md`](docs/getting-started/setup.md)** **[`docs/getting-started/setup.md`](docs/getting-started/setup.md)**
once, top to bottom. once, top to bottom.
@ -169,19 +172,22 @@ newer channel breaks in ways hyperhive's CI doesn't catch.
## Operating it ## Operating it
- **`hivectl`** — the hive's operator CLI, on every hive host: agents, - **swarm UI** — the day-to-day surface, on the swarm apex behind SSO
approvals, gateway logins, container shells. Talks to hive-c0re over (`admins` group): hive roster and status, every agent with its live
`/run/hyperhive/host.sock`. → [guide](docs/tools/hivectl.md) · terminal and wanted state, creating agents, linking external forge and
[full reference](docs/tools/hivectl-cli.md) matrix accounts, the job graph, a cross-repo issue report. →
- **`swarmctl`** — the swarm's operator CLI, on the swarm-controller host: [`docs/swarm/ui.md`](docs/swarm/ui.md)
creating agents with their identities, SSO users, forge admins. - **`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/tools/swarmctl-cli.md)
- **Dashboard** — approvals, agent state, the job graph, per-agent - **per-hive** — each hive's dashboard (approvals, container state,
terminals. → [`docs/web-ui/`](docs/web-ui/README.md) rebuild queue) and `hivectl` for host-level administration and
container shells. → [`docs/web-ui/`](docs/web-ui/README.md) ·
[hivectl](docs/tools/hivectl.md)
Human accounts come from SSO: a first login through authelia creates your You are an SSO user too: `swarmctl user add <you> --group admins`, and a
forge and matrix accounts; `swarmctl forge make-admin <you>` promotes the first login through authelia creates your forge and matrix accounts;
forge one. `swarmctl forge make-admin <you>` promotes the forge one.
## Where to read next ## Where to read next
@ -189,10 +195,10 @@ forge one.
pick the page for your task rather than reading front to back. Some pick the page for your task rather than reading front to back. Some
common entry points: common entry points:
- connecting hives into a swarm → [`swarm/`](docs/swarm/README.md)
- how config changes flow → [`agent-lifecycle/approvals.md`](docs/agent-lifecycle/approvals.md) - how config changes flow → [`agent-lifecycle/approvals.md`](docs/agent-lifecycle/approvals.md)
- trust boundary + threat model → [`trust-boundary/`](docs/trust-boundary/boundary.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) - what an agent's turn looks like → [`turn-loop/`](docs/turn-loop/README.md)
- connecting hives into a swarm → [`swarm/`](docs/swarm/README.md)
- every `services.hyperhive.*` option → [options reference](https://hyperhive.darkest.space/options/) - every `services.hyperhive.*` option → [options reference](https://hyperhive.darkest.space/options/)
## Hacking on it ## Hacking on it