hyperhive

a swarm of claude-code agents, each in its own nspawn cage, gossiping over unix sockets. config changes flow as git commits, the operator approves them in a browser, every deploy is a tag. cyberpunk-themed dashboard included. 💜⚡

Claude code is great in one window, exponentielle across many — but only if you can keep the agents from stepping on each other, give them durable identity, and stop them from eating production. hyperhive is the substrate.

• identity = unix socket
• communication = sqlite-backed broker (send / recv / ask / answer / remind)
• config = git (manager proposes, operator approves, deploys land as tagged commits)
• blast radius = container

host (NixOS, runs hive-c0re.service)
│
├── operator
│   ├── browser → :80 (hive-gateway)    dashboard + per-agent UIs
│   │                                   /agent/<name>/ → per-agent unix socket
│   └── CLI     → /run/hyperhive/host.sock   admin protocol
│
├── hive-c0re  (Rust daemon: lifecycle / broker / approvals /
│               auto-update / dashboard / sockets)
│
├── optional containers
│   ├── hive-gateway   nginx — proxies :80 → c0re dashboard + per-agent sockets
│   ├── hive-forge     Forgejo — per-agent accounts, config mirror (agent-configs/)
│   └── hive-matrix    tuwunel — Matrix homeserver + per-agent accounts
│
└── agent containers
    ├── h-ruth     manager (privileged MCP surface, approval gating)
    └── h-<name>   sub-agent (claude + MCP tools + per-agent web UI + unix socket)

→ website · → options reference

Depth lives in docs/ — pick the one matching your task:

reading path	doc
dashboard layout + endpoints	docs/web-ui.md (shape · dashboard · agent)
claude turn loop + MCP tools	docs/turn-loop.md
config-edit + approval state machine	docs/approvals.md
what survives destroy / purge / restart	docs/persistence.md
naming, wire protocol, commit style	docs/conventions.md
nginx vhost map + sub-domain routing	docs/gateway.md
NixOS / nspawn gotchas	docs/gotchas.md

Quick start

Minimal flake.nix for a host that runs hive-c0re:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05";
    hyperhive.url = "git+https://forge.darkest.space/hyperhive/hyperhive";
    # Pin hyperhive to your own nixpkgs instead of the one it ships with
    # (see "Overriding nixpkgs" below) — recommended for most hosts:
    hyperhive.inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs = { nixpkgs, hyperhive, ... }: {
    nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        hyperhive.nixosModules.default  # hive-c0re + hive-forge + hive-gateway in one import
        ({ ... }: {
          services.hyperhive.enable = true;
          # services.hyperhive.c0re.operatorPronouns = "they/them";  # default: "she/her"

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

hive-c0re opens its admin socket + dashboard, auto-creates the manager container, and auto-rebuilds any container whose hyperhive rev goes stale. claude-code is unfree — hyperhive scopes the whitelist to itself, nothing for the operator to set.

Overriding nixpkgs

hyperhive's own flake.nix pins nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05" so the repo builds standalone (nix flake check, CI, nix develop) without depending on a consumer's host flake. When you import hyperhive as a flake input into your own host config, that pin becomes a second nixpkgs evaluation living alongside your host's — extra closure to build/cache, and a second place package versions can drift from what the rest of your system runs.

Add hyperhive.inputs.nixpkgs.follows = "nixpkgs" to your input declaration (as in the quick-start above) to make hyperhive build against your host's nixpkgs input instead of its own pinned one. This is the standard flake follows pattern — nothing hyperhive-specific — and works as long as your nixpkgs is reasonably close to the nixos-26.05 release hyperhive is developed against; a much older or newer channel may hit nixpkgs-side breakage hyperhive's CI doesn't catch. If you hit that, drop the follows line and let hyperhive use its own pin again.

For the full list of host and agent NixOS options see the options reference.

Agent configuration

Per-agent config lives in each agent's agent.nix (proposed, operator-approved, deployed as git commits). Key options:

Multi-account Matrix support

hyperhive.matrixAccounts declares additional matrix accounts for an agent, beyond the hive-internal one. Each entry is keyed by account name and specifies:

• tokenFile — path to the matrix bearer token (provisioned out-of-band)
• sessionDir — path to the per-account matrix-sdk sqlite state (crypto keys + cache)
• homeserver — optional homeserver URL (defaults to hyperhive.matrix.url)

Example:

hyperhive.matrixAccounts = {
  external-public = {
    tokenFile = "/agents/myagent/state/matrix-token-external";
    sessionDir = "/agents/myagent/state/matrix-sdk-state-external";
    homeserver = "https://matrix.org";
  };
};

The hive-internal account is always named main (synthesized from hyperhive.matrix.url + agent state). This option only declares extras; the main name is reserved and cannot be used here. Requires hyperhive.matrix.enable = true.

For more details see docs/matrix.md.

GitHub account

Every agent gets a managed GitHub identity — a gh CLI wrapper and git push over HTTPS — on by default (hyperhive.github.enable), inert until a PAT is provisioned. There is nothing per-agent to declare: paste an operator-supplied personal access token into the agent's dashboard credentials tab (or hivectl github set-token <agent> --token-stdin) and it works. The gh wrapper + git credential helper read the token live (git auths as x-access-token + the PAT; github.com only), so a rotated PAT takes effect with no rebuild.

Turn the integration off for the whole hive with the host option:

services.hyperhive.github.enable = false;

The PAT value is never in nix — only the enable flag. For more details see docs/github.md.

Operator CLI

hivectl is the operator-facing host CLI for ad-hoc administration that doesn't go through the broker (built alongside hive-c0re when the host module is enabled):

sudo hivectl forge create-user mara                       # provisions a forge user
sudo hivectl forge create-user mara --password 'hunter2'  # … with a fixed password
sudo hivectl matrix create-user mara                      # provisions a matrix user
sudo hivectl matrix create-user mara --password-stdin     # … reading one line from stdin

For agent names (i.e., a Coordinator::agent_state_root(name) exists), hivectl persists the resulting token to the agent's state dir like the boot sweep does. For non-agent names (e.g. the operator's own forge/matrix account), it prints the token to stdout and writes nothing.

Build / deploy

nix develop -c cargo check
nix flake check        # rust + nix + toml fmt + clippy

# deploy from a host config that imports hyperhive.nixosModules.default
nix flake update --update-input hyperhive
sudo nixos-rebuild switch --flake .#<host>