133 lines
5.6 KiB
Markdown
133 lines
5.6 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 → :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.default # hive-c0re + hive-forge in one import
|
|
({ ... }: {
|
|
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.
|
|
|
|
## Agent configuration
|
|
|
|
Per-agent settings live in each agent's `agent.nix` and are synced to
|
|
the container as environment variables. Common options:
|
|
|
|
- **`hyperhive.model`** — Claude model for this agent (default: `"haiku"`).
|
|
Sets `HIVE_DEFAULT_MODEL` in the container; the harness applies it at
|
|
boot and it takes priority over any persisted runtime override. The
|
|
operator can still switch the model at runtime via the per-agent web UI,
|
|
but that choice is reset by any rebuild that changes this option.
|
|
- **`hyperhive.allowedRecipients`** — List of agent names this agent can
|
|
message (via `send`). If unset, all agents are allowed. Useful to
|
|
restrict an agent to talking only to the manager.
|
|
- **`hyperhive.forge.url`** — Base URL of the hyperhive-managed Forgejo
|
|
(default: `"http://localhost:3000"`). Used to configure the agent's
|
|
tea login at boot; no-op if `/state/forge-token` is missing.
|
|
- **`hyperhive.forge.keepSubscriptions`** — Boolean. If `true`, the agent's
|
|
forge repo subscriptions are never auto-cleaned during rebuild; useful
|
|
for agents that want to watch specific repos. Rendered as
|
|
`HIVE_FORGE_KEEP_SUBSCRIPTIONS`.
|
|
- **`hyperhive.forge.skipNotifyReasons`** — List of forge notification
|
|
`reason` values to suppress (e.g. `[ "subscribed" "participating" ]`).
|
|
Notifications matching these reasons are silently dropped; all others
|
|
including direct mentions and reviews are delivered. Empty list (default)
|
|
delivers all notifications. Rendered as `HIVE_FORGE_NOTIFY_SKIP_REASONS`
|
|
(comma-separated).
|
|
- **`hyperhive.frontend.dist`** — Override the default frontend package
|
|
(`pkgs.hyperhive-frontend`, built by `nix/frontend.nix`). Set to a custom
|
|
derivation to ship a fully custom per-agent SPA. The JSON contract
|
|
(`/api/state`, `/events/stream`, action endpoints) is the source of truth
|
|
for any replacement.
|
|
- **`hyperhive.frontend.extraFiles`** — Attrset of extra files/directories
|
|
to layer on top of the default agent dist. Each entry has a `source` (nix
|
|
path) and an optional `target` (URL prefix in the static tree, defaults to
|
|
the attribute name). Example: `{ bitburner.source = ./bitburner-dist; }`
|
|
serves that dist at `/bitburner/`. Pure additions only — overwriting an
|
|
existing default file is a hard eval-time error; use `frontend.dist` to
|
|
replace the whole dist. Paths with leading `/` or `..` segments are
|
|
rejected at eval time.
|
|
|
|
See `nix/templates/harness-base.nix` for the full list of options and
|
|
their descriptions.
|
|
|
|
## 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>
|
|
```
|