hyperhive/README.md

# <img src="branding/hyperhive.svg" alt="" width="38" align="top"> 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](https://hyperhive.darkest.space)** ·
**[→ options reference](https://hyperhive.darkest.space/options/)**

Depth lives in [`docs/`](docs/) — pick the one matching your task:

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

## Quick start

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

```nix
{
  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](https://hyperhive.darkest.space/options/)**.

## 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:**

```nix
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`](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:

```nix
services.hyperhive.github.enable = false;
```

The PAT value is never in nix — only the enable flag. For more details see [`docs/github.md`](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):

```sh
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

```sh
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>
```