From 82d9487913e14b7ac925cc77d4949228f033c20f Mon Sep 17 00:00:00 2001 From: iris Date: Wed, 3 Jun 2026 19:06:06 +0200 Subject: [PATCH] docs(#1182): remove component-diagram.svg; trim README; link to website + options --- README.md | 133 +---------- branding/component-diagram.svg | 398 --------------------------------- 2 files changed, 6 insertions(+), 525 deletions(-) delete mode 100644 branding/component-diagram.svg diff --git a/README.md b/README.md index 56c49373..4a62114e 100644 --- a/README.md +++ b/README.md @@ -38,6 +38,9 @@ host (NixOS, runs hive-c0re.service) └── h- 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 | @@ -50,7 +53,7 @@ Depth lives in [`docs/`](docs/) — pick the one matching your task: | nginx vhost map + sub-domain routing | [`docs/gateway.md`](docs/gateway.md) | | NixOS / nspawn gotchas | [`docs/gotchas.md`](docs/gotchas.md) | -## Host config +## Quick start Minimal `flake.nix` for a host that runs hive-c0re: @@ -84,132 +87,8 @@ 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. -Optional: set `services.hyperhive.gateway.enable = false;` to bypass -the default nginx in front. By default (`gateway.enable = true`) every -request hits a small nginx in its own nixos-container that proxies -to hive-c0re's dashboard on the upstream port; `/matrix/` is served -directly from `services.hyperhive.matrix.gui.package` when the matrix -GUI is on. v0 is HTTP-only (TLS lives in a follow-up); pair with -`services.hyperhive.gateway.localHostsEntry = true;` for local dev so -`http://` resolves to the host without -setting up real DNS. - -Optional: set `services.hyperhive.c0re.preBuildAgentTemplates = true;` -to pre-fetch the per-container system closures into your host's -/nix/store as part of `nixos-rebuild`. First-agent-spawn then -completes in seconds instead of minutes (no nixpkgs/claude-code -fetch on the critical path), at the cost of a few GB extra in your -system closure. Off by default (the toplevels are pinned to -`x86_64-linux`, so non-x86 hosts would otherwise force a cross-build). -Alternatively warm the store manually: -`nix build git+https://forge.darkest.space/hyperhive/hyperhive#agent-base-toplevel`. - -Optional: set `services.hyperhive.domain = "example.com";` to define the -canonical hostname for hyperhive subsystems that need a stable public -name. No default — subsystems that require it (currently: -`services.hyperhive.matrix`) assert non-null at eval time with a clear -error message if it is missing. - -Optional: set `services.hyperhive.hiveName = "pr1ma";` and / or -`services.hyperhive.swarmName = "constellat1on";` to give the hive and -the wider swarm human-readable display labels. Distinct from -`services.hyperhive.domain` (the DNS address): the names surface in -the dashboard chrome and the per-agent system prompt; the domain is -how things are addressed on the wire. Federated hives at different -domains can share a swarm name. Both default to null — chrome falls -back to the domain, the prompt simply doesn't mention them. - -Optional: set `services.hyperhive.matrix.enable = true;` to spin up a -private [matrix-tuwunel](https://github.com/matrix-construct/tuwunel) -homeserver in a nixos-container. Requires either -`services.hyperhive.domain` or `services.hyperhive.matrix.serverName` -to be set (eval fails with a clear error if both are absent). The -`server_name` (embedded irrevocably in every user and room ID) -defaults to `` (bare hive domain); the hive-gateway serves -`.well-known/matrix/{client,server}` endpoints so clients auto-discover the -homeserver without a subdomain. **Existing homeservers** must set -`services.hyperhive.matrix.serverName = "matrix.";` explicitly to -preserve their existing user/room IDs (the `server_name` is embedded -into every ID). Override with -`services.hyperhive.matrix.serverName = "chat.example.com";` for a custom -server name. State -lives at `/var/lib/nixos-containers/hive-matrix/`. Federation is -enabled with an empty `trusted_servers` list; e2ee is deferred to -a follow-up. - -The hive-gateway nginx container serves a -[fluffychat-web](https://fluffychat.im) matrix client at `/matrix/` -when `services.hyperhive.matrix.gui.enable` is on. This defaults to -`services.hyperhive.matrix.enable`, so enabling the homeserver enables -the web client by default; set `gui.enable = false` explicitly to keep -the homeserver without the GUI. The `◆ M4TR1X ◆ →` tab appears in -the dashboard chrome when enabled. The web client can -connect to any Matrix homeserver; enter the URL at first visit (e.g. -the local tuwunel instance if `services.hyperhive.matrix.enable = true`, or -any external homeserver). - -## 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. - -- **`hyperhive.matrix.enable`** — Boolean (default `true`). When true, - each agent container runs `hive-matrix-daemon` (a long-running - matrix-sdk process that holds the per-agent client + sync) and - auto-injects `hive-matrix-mcp` as a stdio MCP server so claude can - call the matrix tools (`mcp__matrix__send_message`, `send_dm`, - `send_reaction`, `send_reply`, `mark_read`, `list_rooms`, - `list_room_members`, `read_room`; `room` args accept both - `!id:server` and `#alias:server` forms). Silently no-ops when - `/matrix-token` is absent (i.e., the host-level - `hyperhive.matrix` tuwunel container hasn't provisioned the account - yet). Set to `false` to opt a specific agent out of matrix. -- **`hyperhive.user.name`** — Unix username the agent runs as inside - the container (default: the agent's own label, injected by the - meta-flake). Agents no longer run as root. Stand-alone module eval - without the meta-flake falls back to `"agent"`. -- **`hyperhive.user.passwordlessSudo`** — Boolean (default `true`). - Grants the agent user `NOPASSWD: ALL` sudo so claude's `Bash` tool - can still escalate when needed — same surface as the old root-user - shape, just explicit. Set `false` for strictly unprivileged agents. - -See `nix/templates/harness-base.nix` for the full list of options and -their descriptions. +For the full list of host and agent NixOS options see the +**[options reference](https://hyperhive.darkest.space/options/)**. ## Operator CLI diff --git a/branding/component-diagram.svg b/branding/component-diagram.svg deleted file mode 100644 index dda6b476..00000000 --- a/branding/component-diagram.svg +++ /dev/null @@ -1,398 +0,0 @@ - - hyperhive — component diagram - Architecture diagram: host machine running hive-c0re, optional service containers (gateway, forge, matrix), and agent containers (manager + sub-agents) communicating over unix sockets and a sqlite broker. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - HOST (NixOS) - - - - - OPERATOR - browser - + CLI - - - - - - - - hive-c0re - - lifecycle · broker · approvals - auto-update · dashboard - sockets · rebuild-queue - - :7000 · /run/hyperhive/host.sock - /run/hyperhive/agent-*.sock - - - - - - - - hive-gateway - - nginx container · :80 - /agent/<name>/ → unix sock - forge.<domain> vhost - - - - - - hive-forge - - Forgejo · :3000 - per-agent accounts + tokens - agent-configs/ mirror - - - - - - hive-matrix - - tuwunel Matrix server - per-agent accounts - federation enabled - - - - - - - - h-ruth - - manager agent - privileged MCP surface - approval gating - config proposals - unix sock + web UI - - - - - - h-iris - - sub-agent - claude + MCP tools - send/recv/ask - bash tasks - unix sock + web UI - - - - - - h-damocles - - sub-agent - claude + MCP tools - NixOS plumbing - harness ergonomics - unix sock + web UI - - - - - - h-<name> - - ··· - any number of agents - - - - - - - :80 - - - - :7000 - - - - - - - config mirror - - - - - - - manager sock - - - - - - - - - - - - sqlite broker - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - LEGEND - - - - - unix sockets (control) - - - - broker messages - - - - HTTP / web proxy - - - - config / git - - - - Matrix homeserver - - - - optional / many - - optional containers dashed - - - - - hyperhive — identity = unix socket · communication = broker · config = git - - -