hyperhive

a swarm of coding agents with one control plane: one identity, one forge, one homeserver, one secret store, one UI. agents run caged on whichever host has room. config changes flow as git commits, the operator approves them in a browser, every deploy is a tag. cyberpunk dashboards included. 💜⚡

→ website · → docs · → options reference

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, and leave production alone. hyperhive is a set of NixOS modules that runs that many-agent setup as a swarm:

• the swarm is where things live — agent identities and accounts, secrets, the job graph that creates and places agents, telemetry, and the UI you drive it all from.
• hives are the substrate — NixOS hosts that run agent containers on the swarm's behalf. Add a hive to add capacity.

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, not an architecture change.

concern	how hyperhive answers it
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 is a swarm-wide principal — SSO subject, forge user, matrix account, secret-store cert identity — addressable as name@hive.domain
secrets	one OpenBao store; the operator places one mTLS identity per host, and everything else — every agent's credentials included — is fetched from the store under an identity rather than copied by hand
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 opens a PR on its config repo, an operator merges it on the forge, and the merge deploys
runtime	claude --print by default; any ACP agent (e.g. opencode) per agent with services.hyperhive.agent.runtime = "acp"
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

the swarm — one of each, each on whichever host you choose
│
├── swarm-controller       hive directory, agent roster, job graph
│   ├── swarm-ui           the operator's UI, served off the gateway on the swarm apex
│   └── swarmctl           its CLI, on the controller's host
├── swarm-authelia         SSO in front of the swarm UI, forge, grafana, …
├── swarm-bao              OpenBao — secrets, a cert identity per agent
├── hive-forge             Forgejo — per-agent accounts, config repos
├── hive-matrix            tuwunel — matrix homeserver, per-agent accounts
├── swarm-nats             message queue (JetStream KV: hive status, …)
├── swarm-otel             telemetry collector, sole holder of upstream creds
├── swarm-victoriametrics  metrics store
├── swarm-victorialogs     log store
├── swarm-grafana          dashboards over both stores
│
└── opt-in, not part of singleHostSwarm
    ├── swarm-ci-runner        Forgejo Actions runner (deploy.ci-runner)
    ├── swarm-snapshot-store   btrfs-receive endpoint for agent snapshots
    └── 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, 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

Every agent is a full NixOS container with its own unix user (passwordless sudo inside the cage) and a durable, self-compacting session. Out of the box it gets:

• messaging — send / recv to other agents (the operator is on 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
• background bash — long-running commands as tracked tasks (run / status / kill), so a build doesn't block the turn. → bash
• subagents — nested sessions on the agent's own runtime, optionally re-prompted toward a goal over several turns. → subagent
• forge — its own Forgejo account, the hive-forge CLI, git credentials, and notifications turned into todos. Optional linked accounts on other forges, and GitHub (gh + push) via services.hyperhive.agent.github.enable. → forge · github
• matrix — its own account(s) on the swarm homeserver, as MCP tools. → matrix
• knowledge — the swarm's shared internal/knowledge repo, read-only at /knowledge, plus hyperhive's own docs in the container. → knowledge
• web UI — a per-agent page behind the gateway: live terminal of the turn stream, model / effort switching, cancel, /compact.
• GUI (opt-in, services.hyperhive.agent.gui.enable) — a Wayland desktop with screenshot / keyboard / mouse tools, viewable over VNC in the web UI.
• 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.

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/ covers spreading a swarm across hosts.

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05";
    hyperhive = {
      url = "git+https://forge.darkest.space/hyperhive/hyperhive";
      inputs.nixpkgs.follows = "nixpkgs"; # see "Overriding nixpkgs"
    };
  };

  outputs = { nixpkgs, hyperhive, ... }: {
    nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        hyperhive.nixosModules.default # the whole host stack, one import
        {
          services.hyperhive = {
            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
            hiveName = "pr1ma";                   # this hive's label in it
            swarm.hives.pr1ma = { };              # the directory: just us
          };

          # ... the rest of your host config
          system.stateVersion = "25.11";
        }
      ];
    };
  };
}

singleHostSwarm turns on everything an all-on-one-box swarm implies: the shared services above, the swarm controller, and /etc/hosts entries so the hive's names resolve on the box itself. claude-code is unfree — hyperhive scopes the allowance to itself, so there's nothing to set.

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 once, top to bottom.

Overriding nixpkgs

hyperhive pins its own nixpkgs so it builds standalone in CI. The follows line above builds it against your host's nixpkgs instead: one evaluation, no version drift. It works as long as your channel is close to the nixos-26.05 hyperhive develops against — drop it if a much older or newer channel breaks in ways hyperhive's CI doesn't catch.

Operating it

• swarm UI — the day-to-day surface, on the swarm apex behind SSO (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
• swarmctl — the swarm's CLI, on the swarm-controller host: create agents and mint their identities, manage SSO users, make forge admins. → reference
• per-hive — each hive's dashboard (container state, rebuild queue) and hivectl for host-level administration and container shells. → docs/web-ui/ · hivectl

You are an SSO user too: swarmctl user add <you> --group admins, and a first login through authelia creates your forge and matrix accounts; swarmctl forge make-admin <you> promotes the forge one, and the matrix one becomes a homeserver admin within five minutes of that first login.

Where to read next

docs/README.md is the index, grouped by question — pick the page for your task rather than reading front to back. Some common entry points:

• connecting hives into a swarm → swarm/
• how config changes flow → agent-lifecycle/config-changes.md
• trust boundary + threat model → trust-boundary/
• what an agent's turn looks like → turn-loop/
• every services.hyperhive.* option → options reference

Hacking on it

nix develop -c cargo check
nix flake check            # rust + nix + toml fmt, clippy, module-eval tests

# in your host flake:
nix flake update hyperhive
sudo nixos-rebuild switch --flake .#<host>

Conventions (commit style, no #[allow(clippy::…)], the pre-push hook) live in docs/process/conventions.md. Issues + backlog are on the forge.