hyperhive/README.md

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

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](https://agentclientprotocol.com) 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
    ├── hive-ci                Forgejo Actions runner (deploy.forgejo.ci)
    ├── 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, 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

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 and the operator,
  `remind` and recurring schedules to wake itself, and a todo list that
  forge notifications and other producers feed. →
  [scheduling](docs/tools/scheduling.md)
- **background bash** — long-running commands as tracked tasks
  (`run` / `status` / `kill`), so a build doesn't block the turn. →
  [bash](docs/tools/bash.md)
- **subagents** — nested sessions on the agent's own runtime, optionally
  re-prompted toward a goal over several turns. →
  [subagent](docs/tools/subagent.md)
- **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](docs/integrations/forge.md) · [github](docs/integrations/github.md)
- **matrix** — its own account(s) on the swarm homeserver, as MCP tools. →
  [matrix](docs/tools/matrix.md)
- **knowledge** — the swarm's shared `internal/knowledge` repo, read-only
  at `/knowledge`, plus hyperhive's own docs in the container. →
  [knowledge](docs/integrations/knowledge.md)
- **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/`](docs/swarm/README.md)
covers spreading a swarm across hosts.

```nix
{
  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

            # c0re.operatorPronouns = "they/them"; # default "she/her"
          };

          # ... 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 CA, 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`](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`](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](docs/tools/swarmctl-cli.md)
- **per-hive** — each hive's dashboard (approvals, container state,
  rebuild queue) and `hivectl` for host-level administration and
  container shells. → [`docs/web-ui/`](docs/web-ui/README.md) ·
  [hivectl](docs/tools/hivectl.md)

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.

## Where to read next

[`docs/README.md`](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/`](docs/swarm/README.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)
- what an agent's turn looks like → [`turn-loop/`](docs/turn-loop/README.md)
- every `services.hyperhive.*` option → [options reference](https://hyperhive.darkest.space/options/)

## Hacking on it

```sh
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`](docs/process/conventions.md).
Issues + backlog are on the
[forge](https://forge.darkest.space/hyperhive/hyperhive/issues).