127 lines
4.9 KiB
Markdown
127 lines
4.9 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)** ·
|
|
**[→ docs](https://hyperhive.darkest.space/docs/)** ·
|
|
**[→ options reference](https://hyperhive.darkest.space/options/)**
|
|
|
|
Depth lives in [`docs/`](docs/) (rendered at
|
|
[hyperhive.darkest.space/docs/](https://hyperhive.darkest.space/docs/)) —
|
|
start at [`docs/README.md`](docs/README.md) and pick the page matching
|
|
your task rather than reading front to back.
|
|
|
|
## 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";
|
|
# Pin hyperhive to your own nixpkgs instead of the one it ships with
|
|
# (see "Overriding nixpkgs" below) — recommended for most hosts:
|
|
hyperhive.inputs.nixpkgs.follows = "nixpkgs";
|
|
};
|
|
|
|
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.
|
|
|
|
### Overriding nixpkgs
|
|
|
|
hyperhive pins its own `nixpkgs` so it builds standalone in CI. Add
|
|
`hyperhive.inputs.nixpkgs.follows = "nixpkgs"` (as in the quick-start above)
|
|
to build it against your host's `nixpkgs` instead — one less nixpkgs
|
|
evaluation, no version drift from the rest of your system. Standard flake
|
|
`follows` pattern; works as long as your channel is reasonably close to the
|
|
`nixos-26.05` hyperhive develops against. Drop it again if a much
|
|
older/newer channel hits breakage hyperhive's CI doesn't catch.
|
|
|
|
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 a name that's a managed agent, `hivectl` persists the resulting token
|
|
to that agent's state dir, the same as the boot sweep does. For a
|
|
non-agent name (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.default
|
|
nix flake update --update-input hyperhive
|
|
sudo nixos-rebuild switch --flake .#<host>
|
|
```
|