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` / `remind`)
- config = git (manager proposes, operator approves, deploys land as
  tagged commits)
- blast radius = container

```
every hive (NixOS host, 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)
│
├── hive-gateway (optional)   nginx — proxies :80 → c0re dashboard + per-agent sockets
│
└── agent containers
    ├── h-ruth     manager (privileged MCP surface, approval gating)
    └── h-<name>   sub-agent (claude + MCP tools + per-agent web UI + unix socket)

one host per swarm (optional — connects hives; can be any hive, including
one that's also running the tree above)
│
├── hive-forge             Forgejo — swarm-wide singleton, per-agent accounts + config mirror
├── hive-matrix            tuwunel — swarm-wide singleton, Matrix homeserver + per-agent accounts
├── swarm-controller       cross-hive state: hive directory, agent roster, jobs
├── swarm-ui               swarm-wide SPA, served straight off the gateway (no own container)
├── swarm-authelia         SSO — one login gates swarm-ui + Grafana + more
├── swarm-nats             message queue (JetStream KV: hive-status, …)
├── swarm-otel             telemetry collector, sole holder of the upstream credential
├── swarm-victoriametrics  metrics store
├── swarm-victorialogs     log store
└── swarm-grafana          dashboards over the metrics/log stores, own OIDC login
```

**[→ website](https://hyperhive.darkest.space)** ·
**[→ docs](https://hyperhive.darkest.space/docs/)** ·
**[→ options reference](https://hyperhive.darkest.space/options/)**

Depth lives in [`docs/`](docs/) (rendered at
[hyperhive.darkest.space/docs/](https://hyperhive.darkest.space/docs/)) —
start at [`docs/README.md`](docs/README.md) and pick the page matching
your task rather than reading front to back.

## 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.deploy.hive-controller.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 pins its own `nixpkgs` so it builds standalone in CI. Add
`hyperhive.inputs.nixpkgs.follows = "nixpkgs"` (as in the quick-start above)
to build it against your host's `nixpkgs` instead — one less nixpkgs
evaluation, no version drift from the rest of your system. Standard flake
`follows` pattern; works as long as your channel is reasonably close to the
`nixos-26.05` hyperhive develops against. Drop it again if a much
older/newer channel hits breakage hyperhive's CI doesn't catch.

For the full list of host and agent NixOS options see the
**[options reference](https://hyperhive.darkest.space/options/)**.

## 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 matrix create-user mara                      # provisions a matrix user
sudo hivectl matrix create-user mara --password-stdin     # … reading one line from stdin
```

For a name that's a managed agent, `hivectl` persists the resulting token
to that agent's state dir, the same as the boot sweep does. For a
non-agent name (for example the operator's own matrix account), it prints the
token to stdout and writes nothing.

A human's first SSO login to the forge makes their forge account, not
`hivectl`; `swarmctl forge make-admin <name>` on the swarm-controller's
host makes it a site admin.

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