docs(#1182): remove component-diagram.svg; trim README; link to website + options
This commit is contained in:
iris
parent
453ee9c44c
commit
82d9487913
2 changed files with 6 additions and 525 deletions
133
README.md
133
README.md
|
|
@ -38,6 +38,9 @@ host (NixOS, runs hive-c0re.service)
|
|||
└── 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 |
|
||||
|
|
@ -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://<services.hyperhive.domain>` 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 `<domain>` (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.<domain>";` 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
|
||||
`<state>/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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue