Watch
0
0
Fork
You've already forked hyperhive
0
a swarm o 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. 💜⚡
  • Rust 65.5%
  • Nix 22.9%
  • TypeScript 6.3%
  • JavaScript 2.3%
  • CSS 1.4%
  • Other 1.5%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
iris e4cfac6926 frontend: root test and typecheck scripts, and tests for the review runs wording and the terminal drag
npm test and npm run typecheck now run in every workspace that has them (the repo root had only build and clean). New tests cover RunsTypes (labels and tones for every outcome, the classification count) and termDrag (what a drag carries and how the hover reads it). instructions.ts cannot be imported by a test under Node because of its .js specifier for unified-diff.ts, so it is not covered, and the conventions doc says so.
2026-11-20 00:28:04 +01:00
.forgejo/workflows vm-nightly: one job per test, with a lint that keeps the matrix list in step 2026-11-19 21:55:34 +01:00
.hyperhive review classifier: presentational layout math needs no test 2026-11-18 22:14:19 +01:00
branding icons for the swarm's own forge accounts, and a default agent icon 2026-11-15 17:14:16 +01:00
claude-plugins claude-subagents skill: a failed command is reported verbatim, never filled in 2026-11-12 12:19:20 +01:00
docs frontend: root test and typecheck scripts, and tests for the review runs wording and the terminal drag 2026-11-20 00:28:04 +01:00
forge-client forge-client: take the token as a string, drop TokenSource and StaticToken 2026-11-15 23:22:48 +01:00
frontend frontend: root test and typecheck scripts, and tests for the review runs wording and the terminal drag 2026-11-20 00:28:04 +01:00
hive-agent docs: drop the turn-stats sqlite section and stale mentions, point the grafana check at the daemon 2026-11-18 20:53:12 +01:00
hive-agent-mcp hive-agent: let an agent compact from 40% context usage instead of 66% 2026-11-14 12:35:27 +01:00
hive-agent-sock bash OOM order: subagent test expects 900, const asserts for clippy 2026-11-19 08:03:07 +01:00
hive-bash-mcp bash tasks are the OOM killer's first victims: score 1000, subagent runs 900, MemoryHigh on the bash daemon 2026-11-19 08:03:07 +01:00
hive-c0re reconcile tick: create a placed agent whose deploy event was missed 2026-11-19 12:28:42 +01:00
hive-core-agent-sock remove hive and agent apis nothing calls: build-log routes, /api/compact, host.sock list, mcp.sock wake 2026-11-13 03:09:24 +01:00
hive-forge hive-forge: ci-rerun takes repeatable --input key=value for workflow dispatch 2026-11-19 10:52:33 +01:00
hive-forge-notify seven daemons log through hive-log so the log store gets their severities 2026-11-19 08:36:10 +01:00
hive-host-sock remove the hivectl-only quota verbs and the trollshell status feed 2026-11-13 16:14:41 +01:00
hive-jobq hive-jobq: treat a panicking job runner as a failed node 2026-10-09 15:14:04 +02:00
hive-jobq-metrics drop the remaining HYPERHIVE_OTEL_METRIC_INTERVAL_MS readers 2026-10-17 08:00:14 +02:00
hive-jobq-wire remove what no longer has a reader: build-log store, dashboard sent/delivered events, graph resource dep 2026-11-13 10:58:49 +01:00
hive-log log: send records natively to journald, keep stdout off-unit 2026-09-21 15:52:57 +02:00
hive-matrix-mcp hive-matrix-mcp: test direct messages, replies and anchored reads 2026-11-17 09:03:53 +01:00
hive-meta-flake full-setup vm test: spawn, a reviewer-archetype agent, replaces ruth 2026-11-10 06:47:34 +01:00
hive-metric docs: sort the top-level directories into five sections by what the reader wants 2026-11-06 18:46:57 +01:00
hive-priv seven daemons log through hive-log so the log store gets their severities 2026-11-19 08:36:10 +01:00
hive-priv-sock reconcile: start a stopped harness inside a running container 2026-11-19 08:03:56 +01:00
hive-runtime remove hive and agent apis nothing calls: build-log routes, /api/compact, host.sock list, mcp.sock wake 2026-11-13 03:09:24 +01:00
hive-screen-mcp drop option renames and removals older than two weeks 2026-10-16 22:04:57 +02:00
hive-sh4re swarm ui: show thinking is a toggle of its own, apart from the developer details 2026-11-16 20:52:58 +01:00
hive-sock-client hive-agent: the per-agent page has no message box; its send route and the broker's operator message are removed 2026-11-06 01:13:44 +01:00
hive-subagent-mcp bash OOM order: the stale +1000/task (0) comments say 900 and 1000 2026-11-19 08:03:07 +01:00
hive-template templates: the agent system prompt is a Jinja template, rendered through hive-template 2026-11-11 09:04:42 +01:00
hive-types agents can transcribe an audio file: the transcribe_audio tool, through the harness and the speech-to-text service 2026-11-12 12:18:18 +01:00
hivectl remove the swarm wireguard mesh; tombstone its options 2026-11-15 02:17:44 +01:00
nix hive-egress: the spoof log line says which check failed 2026-11-20 00:27:20 +01:00
scripts vm-nightly: one job per test, with a lint that keeps the matrix list in step 2026-11-19 21:55:34 +01:00
swagger-ui-theme treefmt: apply prettier 2026-09-02 15:25:07 +02:00
swarm-agent-verify readiness follows a cached store check instead of a constant or a login per probe 2026-11-19 08:43:43 +01:00
swarm-authelia-bridge readiness follows a cached store check instead of a constant or a login per probe 2026-11-19 08:43:43 +01:00
swarm-authelia-bridge-sock swarm-controller: make authelia's operators matrix homeserver admins 2026-10-04 16:45:08 +02:00
swarm-builder swarm daemons exit 0 when told to stop while still waiting for the store at startup 2026-11-19 08:06:36 +01:00
swarm-ci-metrics forge-client: take the token as a string, drop TokenSource and StaticToken 2026-11-15 23:22:48 +01:00
swarm-claude-login swarm daemons exit 0 when told to stop while still waiting for the store at startup 2026-11-19 08:06:36 +01:00
swarm-controller swarm-controller: an opt-in plain /healthz and /readyz listener a kubelet can probe 2026-11-19 12:23:17 +01:00
swarm-controller-api gate ssh signing per agent: ssh permission, signing policy on the login role, ca key endpoint 2026-11-16 20:31:18 +01:00
swarm-logs docs: move the agent tool docs to 4-implementation/agent-tools 2026-11-07 09:04:27 +01:00
swarm-logs-auth readiness follows a cached store check instead of a constant or a login per probe 2026-11-19 08:43:43 +01:00
swarm-matrix-client swarm-controller: stop minting the per-hive matrix sender account and token nothing reads 2026-11-12 15:38:34 +01:00
swarm-matrix-ctl seven daemons log through hive-log so the log store gets their severities 2026-11-19 08:36:10 +01:00
swarm-metrics docs: move the agent tool docs to 4-implementation/agent-tools 2026-11-07 09:04:27 +01:00
swarm-metrics-auth readiness follows a cached store check instead of a constant or a login per probe 2026-11-19 08:43:43 +01:00
swarm-nats-auth seven daemons log through hive-log so the log store gets their severities 2026-11-19 08:36:10 +01:00
swarm-notify-router swarm daemons exit 0 when told to stop while still waiting for the store at startup 2026-11-19 08:06:36 +01:00
swarm-queue-client swarm daemons: opt-in /healthz and /readyz listener, and /readyz on the controller 2026-11-18 19:06:04 +01:00
swarm-review-classifier swarm daemons exit 0 when told to stop while still waiting for the store at startup 2026-11-19 08:06:36 +01:00
swarm-secret-client readiness follows a cached store check instead of a constant or a login per probe 2026-11-19 08:43:43 +01:00
swarm-stt swarm daemons exit 0 when told to stop while still waiting for the store at startup 2026-11-19 08:06:36 +01:00
swarm-wire agent_icon: the subject's docs no longer mention a writer that publishes directly 2026-11-17 06:47:48 +01:00
swarmctl grant-bootstrap re-applies the granter and restarts failed policy units; setup treats a refused granting unit as not done 2026-11-19 08:17:02 +01:00
.gitignore fetch vale styles in nix, pinned, and drop vale sync 2026-10-28 23:08:48 +01:00
.mailmap chore(#2165): add damocles@pr1ma + lexis@pr1ma mailmap entries 2026-07-04 13:50:16 +02:00
.prettierignore docs: persistence and config changes become one operator page 2026-11-11 01:50:35 +01:00
.prettierrc temp: add prettier configs 2026-07-02 23:33:11 +02:00
.vale.ini fetch vale styles in nix, pinned, and drop vale sync 2026-10-28 23:08:48 +01:00
AGENTS.md hive-agent: keep the last turn's context size in the harness state file and drop the turn sqlite writes 2026-11-18 03:09:14 +01:00
Cargo.lock seven daemons log through hive-log so the log store gets their severities 2026-11-19 08:36:10 +01:00
Cargo.toml bump hive-claude to 0.1.5 for the failed-to-authenticate marker 2026-11-16 20:23:29 +01:00
clippy.toml swarm-logs: an agent's CLI for the swarm log store 2026-09-17 01:02:14 +02:00
flake.lock nix flake update 2026-11-19 08:05:59 +01:00
flake.nix add an ssh ca to bao, agent ssh certificates and a target module 2026-11-16 20:31:18 +01:00
README.md remove the agent's stats page and its endpoint 2026-11-16 19:00:52 +01:00

hyperhive

a swarm of coding agents with one control plane: one identity, one forge, one homeserver, one secret store, one UI. agents run caged on whichever host has room. config changes flow as git commits, the operator approves them in a browser, every deploy is a tag. cyberpunk dashboards included. 💜⚡

→ website · → docs · → options reference

A coding agent is great in one window, exponentielle across many — as long as the agents stay off each other's toes, keep a durable identity, and leave production alone. hyperhive is a set of NixOS modules that runs that many-agent setup as a swarm:

  • the swarm is where things live — agent identities and accounts, secrets, the job graph that creates and places agents, telemetry, and the UI you drive it all from.
  • hives are the substrate — NixOS hosts that run agent containers on the swarm's behalf. Add a hive to add capacity.

Start with everything on one box; move services and add hives as the swarm grows. Which host runs what is a per-host deploy.* toggle, not an architecture change.

concern how hyperhive answers it
control plane swarm-controller holds the hive directory, the agent roster and the job graph. Create an agent from the swarm UI or swarmctl agent create --hive <h>: it provisions the SSO identity, forge user and config repo, then deploys the agent onto that hive
identity every agent is a swarm-wide principal — SSO subject, forge user, matrix account, secret-store cert identity — addressable as name@hive.domain
secrets one OpenBao store; the operator places one mTLS identity per host, and everything else — every agent's credentials included — is fetched from the store under an identity rather than copied by hand
shared services one forge, homeserver, SSO, message queue and metrics/logs stack per swarm, each on whichever host you put it
config git: an agent opens a PR on its config repo, an operator merges it on the forge, and the merge deploys
runtime claude --print by default; any ACP agent (e.g. opencode) per agent with services.hyperhive.agent.runtime = "acp"
substrate each hive runs one nixos-container per agent, under an unprivileged daemon with a tiny socket-activated helper for the few root ops
watching the swarm UI (hives, agents with live terminals, jobs, a cross-repo issue report), Grafana over OTEL, and a per-hive dashboard for host-level detail

Shape

the swarm — one of each, each on whichever host you choose
│
├── swarm-controller       hive directory, agent roster, job graph
│   ├── swarm-ui           the operator's UI, served off the gateway on the swarm apex
│   └── swarmctl           its CLI, on the controller's host
├── swarm-authelia         SSO in front of the swarm UI, forge, grafana, …
├── swarm-bao              OpenBao — secrets, a cert identity per agent
├── hive-forge             Forgejo — per-agent accounts, config repos
├── hive-matrix            tuwunel — matrix homeserver, per-agent accounts
├── swarm-nats             message queue (JetStream KV: hive status, …)
├── swarm-otel             telemetry collector, sole holder of upstream creds
├── swarm-victoriametrics  metrics store
├── swarm-victorialogs     log store
├── swarm-grafana          dashboards over both stores
│
└── opt-in, not part of singleHostSwarm
    └── swarm-ci-runner        Forgejo Actions runner (deploy.ci-runner)

the hives — the substrate, as many as you like (deploy.hive-controller.enable)
│
├── hive-c0re      runs the agent containers: lifecycle, broker,
│                  auto-rebuild, the per-hive dashboard; unprivileged
├── hive-priv      root helper, socket-activated, does bind-mounts + nsenter
├── hive-gateway   nginx + dnsmasq on :80/:443, fronts every agent's web UI
├── hivectl        host-level CLI
│
└── agent containers
    ├── h-ruth     manager — privileged MCP surface, configures agents
    └── h-<name>   agent — claude / ACP runtime, MCP tools, web UI

Inside an agent

Every agent is a full NixOS container with its own unix user (passwordless sudo inside the cage) and a durable, self-compacting session. Out of the box it gets:

  • messaging — peers and the operator talk over matrix; agents without matrix are cut off from peers on purpose, remind to wake itself, scheduled prompts the operator sets for it at swarm level, and a todo list that forge notifications and other producers feed. → schedules
  • background bash — long-running commands as tracked tasks (run / status / kill), so a build doesn't block the turn. → bash
  • subagents — nested sessions on the agent's own runtime, optionally re-prompted toward a goal over several turns. → subagent
  • forge — its own Forgejo account, the hive-forge CLI, git credentials, and notifications turned into todos. Optional linked accounts on other forges, GitLab (glab + push), and GitHub (gh + push) via services.hyperhive.agent.github.enable. → forge · gitlab · github
  • matrix — its own account(s) on the swarm homeserver, as MCP tools. → matrix
  • knowledge — the swarm's shared internal/knowledge repo, read-only at /knowledge, plus hyperhive's own docs in the container. → knowledge
  • web UI — the swarm UI's terminal for each agent: the live turn stream and a message box, with /compact and /clear.
  • GUI (opt-in, services.hyperhive.agent.gui.enable) — a Wayland desktop with screenshot / keyboard / mouse tools, viewable over VNC in the web UI.
  • reverse engineering (opt-in, services.hyperhive.agent.rea.enable, or the reverse-engineer archetype) — REA and Ghidra 12.1 in the container, with their MCP tools allowed. → archetypes
  • your own tools — any extra MCP server (stdio or http) via services.hyperhive.agent.extraMcpServers, and any NixOS config you'd put on a machine.

Quick start: an all-local swarm

The whole swarm on one box — a hive plus every shared service. Good for a dev box or a single-host deployment; docs/2-handbook/swarm/ covers spreading a swarm across hosts.

{
  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 # the whole host stack, one import
        {
          services.hyperhive = {
            swarm = {
              domain = "myswarm.example"; # the swarm's DNS domain
              hives.firsthive = { }; # the directory: just us
            };
            deploy = {
              singleHostSwarm = true; # every swarm service on this machine
              hive-controller = {
                enable = true; # …and a hive to run agents on
                hiveName = "firsthive"; # this hive's label in it
              };
            };
          };

          # ... the rest of your host config
          system.stateVersion = "25.11";
        }
      ];
    };
  };
}

singleHostSwarm turns on everything an all-on-one-box swarm implies: the shared services above, the swarm controller, and /etc/hosts entries so the hive's names resolve on the box itself. claude-code is unfree — hyperhive scopes the allowance to itself, so there's nothing to set.

After nixos-rebuild switch the swarm UI answers on the swarm domain, and the hive brings up the manager agent (ruth). A few steps stay deliberately human — initialising the secret store, giving ruth her store identity, creating your SSO account. Walk through docs/1-getting-started/setup.md once, top to bottom.

Operating it

  • swarm UI — the day-to-day surface, on the swarm apex behind SSO (admins group): hive roster and status, every agent with its live terminal and wanted state, creating agents, linking external forge and matrix accounts, the job graph, a cross-repo issue report. → docs/2-handbook/swarm/ui.md
  • swarmctl — the swarm's CLI, on the swarm-controller host: create agents and mint their identities, manage SSO users, make forge admins. → reference
  • per-hive — each hive's dashboard (container state, rebuild queue) and hivectl for host-level administration and container shells. → docs/2-handbook/hives/ · hivectl

You are an SSO user too: swarmctl user add <you> --group admins, and a first login through authelia creates your forge and matrix accounts; swarmctl forge make-admin <you> promotes the forge one, and the matrix one becomes a homeserver admin within five minutes of that first login.

docs/README.md is the index, grouped by question — pick the page for your task rather than reading front to back. Some common entry points:

Hacking on it

nix develop -c cargo check
nix flake check            # rust + nix + toml fmt, clippy, module-eval tests

# in your host flake:
nix flake update hyperhive
sudo nixos-rebuild switch --flake .#<host>

Conventions (commit style, no #[allow(clippy::…)], the pre-push hook) live in docs/5-project/process/conventions.md. Issues + backlog are on the forge.