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

```
                     ┌────────────────────────┐
                     │  hive-c0re (Rust)      │
        operator ──▶ │  • lifecycle           │ ─▶ nixos-containers
                     │  • broker (sqlite)     │     ├── hm1nd       (manager)
                     │  • approvals (sqlite)  │     ├── h-alice     (sub-agent)
                     │  • dashboard :7000     │     └── h-bob       ...
                     │  • per-agent sockets   │
                     └────────────────────────┘
```

Each container runs a harness binary that drives `claude --print --continue`
in a turn loop, exposes a per-agent web UI with a live event stream, and
talks to the broker over a bind-mounted unix socket via an embedded MCP
server claude calls into.

## 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
        ({ ... }: {
          nixpkgs.overlays = [
            hyperhive.overlays.default
            hyperhive.overlays.claude-unstable
          ];
          services.hive-c0re = {
            enable = true;
            hyperhiveFlake = "${hyperhive}";
          };
          # ... 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.

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

The host config also needs `hyperhive.overlays.default` applied — the
module's default `package = pkgs.hyperhive` requires the overlay.