90 lines
3 KiB
Markdown
90 lines
3 KiB
Markdown
# 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 → :7000 hive-c0re dashboard
|
|
│ ├── browser → :8000 / :8100-8999 per-agent web UIs
|
|
│ └── CLI → /run/hyperhive/host.sock admin protocol
|
|
│
|
|
├── hive-c0re (Rust daemon: lifecycle / broker / approvals /
|
|
│ auto-update / dashboard / sockets)
|
|
│
|
|
└── nixos-containers
|
|
├── hm1nd manager agent (privileged MCP surface)
|
|
└── h-<name> sub-agent (vanilla MCP surface + per-agent extras)
|
|
```
|
|
|
|
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) |
|
|
| 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) |
|
|
| NixOS / nspawn gotchas | [`docs/gotchas.md`](docs/gotchas.md) |
|
|
|
|
## 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;
|
|
# services.hive-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.
|
|
|
|
## 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.hive-c0re
|
|
nix flake update --update-input hyperhive
|
|
sudo nixos-rebuild switch --flake .#<host>
|
|
```
|