hyperhive/README.md

# hyperhive

Multi-Claude-Code-agent orchestration on **nixos-containers**.

A host-side Rust daemon (`hive-c0re`) spawns nspawn-isolated agent
containers and brokers messages between them. A manager agent (`hm1nd`)
coordinates the swarm and gates lifecycle changes on user approval via git
commits, surfaced through a vibec0re-styled HTTP dashboard.

```
host (NixOS, runs hive-c0re.service)
│
├── operator
│   ├── browser → :7000               hive-c0re dashboard (containers, approvals)
│   ├── browser → :8000 / :8100-8999  per-agent web UIs (live SSE, send, login)
│   └── CLI     → /run/hyperhive/host.sock         JSON-line admin protocol
│
├── hive-c0re  (Rust daemon)
│   ├── lifecycle    nixos-container CRUD + per-agent flake generation
│   ├── broker       sqlite messages + tokio broadcast (powers SSE + wake-ups)
│   ├── approvals    sqlite queue, two kinds: ApplyCommit (config) + Spawn
│   ├── auto_update  rebuilds any container whose recorded flake rev is stale
│   ├── dashboard    axum HTTP + async-form actions + SSE message flow
│   └── sockets      /run/hyperhive/{host,manager,agents/<n>}/mcp.sock
│
└── nixos-containers  (each bind-mounts its socket dir → /run/hive,
   │                   credentials dir → /root/.claude,
   │                   durable notes dir → /state;
   │                   manager additionally gets /agents RW
   │                   + /applied RO for the deployed-tag mirror)
   │
   ├── hm1nd      hive-m1nd serve : claude turn loop +
   │              MCP (send / recv / request_spawn / kill / start /
   │                   restart / update / request_apply_commit /
   │                   ask_operator) + web UI on :8000
   │
   └── h-<name>   hive-ag3nt serve : claude turn loop +
                  MCP (send / recv) + web UI on a hashed :8100-8999
```

Each turn: harness pops one inbox message (Recv long-polls server-side and
wakes on a broker Sent event) → builds a wake prompt → spawns
`claude --print --continue --output-format stream-json --mcp-config …` →
streams JSON events into the per-agent SSE bus + a sqlite history db →
claude drives any further `recv`/`send` itself via the embedded MCP server.

Operator surface per agent: terminal-themed live tail with a textarea
prompt; slash commands `/help` `/clear` `/cancel` `/compact`
`/model <name>`; granular state badge (idle / thinking /
compacting / offline) with age timer + last-turn duration chip +
model chip; cancel-turn button while thinking; sticky-bottom
auto-scroll with "↓ N new" pill; event history backfilled on page
load; collapsible inbox + collapsible journald viewer + collapsible
`agent.nix` viewer per agent on the dashboard.

Config changes flow the other way: manager edits files under
`/agents/<name>/config/` (`agent.nix` is the entry point, but arbitrary
sibling files in the commit are preserved) → commits → submits the sha
via `request_apply_commit`. Hive-c0re immediately fetches that commit
from the proposed repo into the applied repo and pins it as
`proposal/<id>` — from this moment the proposal is immutable from the
manager's side. Operator clicks ◆ APPR0VE on the dashboard → hive-c0re
moves the working tree to the proposal, runs `nixos-container update`,
and either fast-forwards `applied/main` (tagging `deployed/<id>`) or
annotates `failed/<id>` with the build error and rolls back to the
previous deployed tree. Denials leave a `denied/<id>` annotated tag
carrying the operator's note. The manager sees everything that
shipped (or didn't) via a read-only `/applied/<n>/.git` mirror inside
its container; `git show applied/deployed/<id>` etc. is the audit
trail. See [`docs/approvals.md`](docs/approvals.md) for the full tag
state machine.
For decisions the manager needs human signal on, `ask_operator(question,
options?, multi?)` queues a free-text/checkbox/radio form on the
dashboard; the answer arrives later as a `HelperEvent::OperatorAnswered`
in the manager's inbox.

## Host config

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

```nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11";
    hyperhive.url = "git+https://git.berlin.ccc.de/vinzenz/hyperhive";
  };

  outputs = { nixpkgs, hyperhive, ... }: {
    nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        hyperhive.nixosModules.hive-c0re
        ({ ... }: {
          services.hive-c0re.enable = true;
          # ... rest of your host config (hardware, networking, users, …)
          system.stateVersion = "25.11";
        })
      ];
    };
  };
}
```

hive-c0re will then:
- open its admin socket at `/run/hyperhive/host.sock` + dashboard on
  `:7000`,
- auto-create the manager container (`hm1nd`) if missing,
- auto-rebuild any managed container whose hyperhive rev is stale.

`claude-code` is unfree; hyperhive whitelists it for itself
(scoped: only `claude-code`, nothing else) inside the
`claude-unstable` overlay and `harness-base.nix`. Per-agent
containers evaluate their own nixpkgs instance so the operator's
host-level `allowUnfree` doesn't propagate in — the predicate has
to live inline. Nothing to set on the operator side.

## Build / deploy

```sh
# inside the repo (devshell first; no global cargo)
nix develop -c cargo check
nix develop -c cargo clippy --workspace --all-targets -- -D warnings

# evaluate everything (rust+nix+toml fmt + clippy)
nix flake check

# deploy to a host that imports `hyperhive.nixosModules.hive-c0re`
cd ~/Repos/<nixos-config-repo>
nix flake update --update-input hyperhive
sudo nixos-rebuild switch --flake .#<host>
```

No overlays on the host's `pkgs` — the module pulls hive-c0re's package
straight from `hyperhive.packages.<system>.default`. Just import the
module and the service is wired up.