120 lines
4.7 KiB
Markdown
120 lines
4.7 KiB
Markdown
# <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` / `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 → :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)
|
|
│
|
|
├── optional containers
|
|
│ ├── hive-gateway nginx — proxies :80 → c0re dashboard + per-agent sockets
|
|
│ ├── hive-forge Forgejo — per-agent accounts, config mirror (agent-configs/)
|
|
│ └── hive-matrix tuwunel — Matrix homeserver + per-agent accounts
|
|
│
|
|
└── agent containers
|
|
├── h-ruth manager (privileged MCP surface, approval gating)
|
|
└── h-<name> sub-agent (claude + MCP tools + per-agent web UI + unix socket)
|
|
```
|
|
|
|
**[→ website](https://hyperhive.darkest.space)** ·
|
|
**[→ options reference](https://hyperhive.darkest.space/options/)**
|
|
|
|
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) ([shape](docs/web-ui/shape.md) · [dashboard](docs/web-ui/dashboard.md) · [agent](docs/web-ui/agent.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) |
|
|
| nginx vhost map + sub-domain routing | [`docs/gateway.md`](docs/gateway.md) |
|
|
| NixOS / nspawn gotchas | [`docs/gotchas.md`](docs/gotchas.md) |
|
|
|
|
## 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";
|
|
};
|
|
|
|
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.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.
|
|
|
|
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 forge create-user mara # provisions a forge user
|
|
sudo hivectl forge create-user mara --password 'hunter2' # … with a fixed password
|
|
sudo hivectl matrix create-user mara # provisions a matrix user
|
|
sudo hivectl matrix create-user mara --password-stdin # … reading one line from stdin
|
|
```
|
|
|
|
For agent names (i.e., a `Coordinator::agent_state_root(name)` exists),
|
|
`hivectl` persists the resulting token to the agent's state dir like the
|
|
boot sweep does. For non-agent names (e.g. the operator's own forge/matrix
|
|
account), it prints the token to stdout and writes nothing.
|
|
|
|
## 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>
|
|
```
|