From 8f4a8fbc075a672fee15df3582f88e813c9520b8 Mon Sep 17 00:00:00 2001 From: iris Date: Fri, 5 Jun 2026 18:12:43 +0200 Subject: [PATCH 1/3] docs(turn-loop): document passwordlessSudo, dashboardLinks, extraFiles, connectivity overrides Five previously undocumented per-agent agent.nix options: - hyperhive.user.passwordlessSudo: default-true sudo grant; note added with cross-reference to companion user.* options in agent-hierarchy.md - hyperhive.dashboardLinks: declarative extra nav links on the dashboard card and per-agent page header; table of fields (label/url/icon) - hyperhive.frontend.extraFiles: overlay files over the default agent dist; source/target semantics, constraints, collision guard, mergedDist - hyperhive.forge.url: per-agent Forgejo base URL for tea login; default localhost:3000; validation note - hyperhive.matrix.url: per-agent matrix-sdk homeserver URL; default localhost:8008; per-agent override use-cases (remote hive, VPN) --- docs/turn-loop.md | 110 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) diff --git a/docs/turn-loop.md b/docs/turn-loop.md index 01fb7232..2661d308 100644 --- a/docs/turn-loop.md +++ b/docs/turn-loop.md @@ -291,6 +291,116 @@ write_settings, write_system_prompt, run_turn, drive_turn, emit_turn_end, wait_for_login, compact_session}` so the two binaries can't drift. +### `user.passwordlessSudo` + +```nix +hyperhive.user.passwordlessSudo = true; # default +``` + +Grants the per-agent unix user passwordless `sudo` (`NOPASSWD: ALL`). +Enabled by default so claude's shell tools work for operations that +need root inside the container (`systemctl`, package managers in dev +shells, etc.) — the same privilege surface the previous root-user shape +had, now elevated explicitly rather than implicitly. + +Set to `false` for agents that should be strictly unprivileged. +Any tool invocation that needs root then fails loudly with the standard +sudo rejection rather than silently succeeding — easier to audit. + +`hyperhive.user.uid`, `hyperhive.user.gid`, and +`hyperhive.user.name` are the companion options; see +`docs/agent-hierarchy.md` — "Harness systemd unit shape" for the full +`user.*` surface. + +### Dashboard links + +```nix +hyperhive.dashboardLinks = [ + { label = "Stats"; icon = "📊"; url = "http://localhost:9001/stats"; } + { label = "Scratchpad"; url = "http://localhost:8080"; } +]; +``` + +Declares extra navigation links that appear on the agent's dashboard +card and in the per-agent page header alongside the built-in forge / +config / container links. Each entry has: + +| Field | Required | Description | +|-------|----------|-------------| +| `label` | yes | Display text shown in the icon strip tooltip and meta-nav. | +| `url` | yes | Absolute URL — may include a different port (the dashboard renders it as a plain anchor). | +| `icon` | no | Emoji or short glyph prefix. Defaults to empty string. | + +The list is written to `/hyperhive-dashboard-links.json` by a +one-shot systemd unit at container boot. `hive-c0re` reads the file on +each container-view snapshot and attaches the links to the agent card +(`kind = External`) without any code change. Omitting the option +(default empty) produces no extra links. + +### Custom static files + +```nix +hyperhive.frontend.extraFiles = { + "games/bitburner" = { + source = ./bitburner-dist; # path relative to agent.nix + # target defaults to attribute name: "games/bitburner" + }; + "my-page" = { + source = ./my-page.html; + target = "my-page.html"; # explicit override + }; +}; +``` + +Layers additional files over the default per-agent web UI dist. Each +attribute defines one overlay entry: + +- **`source`** — a Nix path (file or directory) copied into the merged + static tree. Evaluated at nix build time; the resulting derivation is + pointed at by `HIVE_STATIC_DIR`. +- **`target`** — destination path within the merged tree, used as both + the served URL prefix (`//…`) and the on-disk layout. + Defaults to the attribute name. Forward slashes create nested layouts + (`"games/bitburner"` serves at `/games/bitburner/…`). + +Constraints: `target` must start with an alphanumeric or `_` and +contain only alphanumerics, `_`, `.`, `/`, `-`. `..` segments are +rejected by a config assertion. The merge step refuses to overwrite +files already present in the default dist — pick a target name that +does not collide with existing paths (`static/`, `index.html`, etc.). + +The default dist ships at `hyperhive.frontend.dist` (the +`hyperhive-frontend` package output, read-only). To replace the +entire UI rather than layer on top, override `frontend.dist` directly. + +### Connectivity overrides + +Two `hyperhive.forge.*` / `hyperhive.matrix.*` options override where +the per-agent daemons connect. Both rarely need changing on a standard +single-host deploy, but are useful for multi-hive or custom-network +setups. + +```nix +hyperhive.forge.url = "http://localhost:3000"; # default +hyperhive.matrix.url = "http://localhost:8008"; # default +``` + +**`hyperhive.forge.url`** — base URL of the Forgejo instance. Used by +a one-shot boot unit that runs `tea login add --url --token +$(cat $HYPERHIVE_STATE_DIR/forge-token)`, making `tea` and +`hive-forge` work without an extra auth step. The unit is a no-op +when `forge-token` is absent. Override when the agent should connect +to a Forgejo on a different host or port (e.g. a swarm peer's forge). +Validated: must be an `http://` or `https://` URL or the empty string. + +**`hyperhive.matrix.url`** — homeserver URL used by +`hive-matrix-daemon` when connecting via the matrix-sdk. Default +points at the in-host tuwunel (`localhost:8008`), reachable over the +host loopback in shared-netns mode. Override per-agent when an agent +should talk to a different homeserver — for example a remote hive's +tuwunel reached over a VPN, or an external Matrix server for a +federation-only agent. + ## MCP surface The harness ships an embedded MCP server (rmcp 1.7). Claude launches From 20269873bd5d0594888ecdf7e64420537d7dbc46 Mon Sep 17 00:00:00 2001 From: iris Date: Fri, 5 Jun 2026 18:14:38 +0200 Subject: [PATCH 2/3] docs(turn-loop): also document hyperhive.icon option MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit SVG path for per-agent visual identity — used in the page header, favicon, Forgejo profile avatar (forge-avatar-sync), and Matrix profile avatar (matrix-avatar-sync). --- docs/turn-loop.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/turn-loop.md b/docs/turn-loop.md index 2661d308..48348b4a 100644 --- a/docs/turn-loop.md +++ b/docs/turn-loop.md @@ -291,6 +291,23 @@ write_settings, write_system_prompt, run_turn, drive_turn, emit_turn_end, wait_for_login, compact_session}` so the two binaries can't drift. +### Agent icon + +```nix +hyperhive.icon = ./icon.svg; # default: null (falls back to shared hyperhive logo) +``` + +Path to an SVG file used as this agent's visual identity — shown in +the per-agent page header, as the page favicon, and uploaded to the +agent's Forgejo profile avatar (via the `forge-avatar-sync` boot +unit) and Matrix profile avatar (via `matrix-avatar-sync`). Commit +the SVG next to `agent.nix` in the config repo and reference it as a +relative path. + +When `null` (the default), the agent falls back to the shared +hyperhive branding mark. The harness serves whichever icon is active +at `GET /icon` on the per-agent web port. + ### `user.passwordlessSudo` ```nix From 330fdf8dc7e2266d2d531a013d26c119eb660cf7 Mon Sep 17 00:00:00 2001 From: iris Date: Fri, 5 Jun 2026 18:17:19 +0200 Subject: [PATCH 3/3] fix(docs/turn-loop): correct forge.url tea-login description The tea-login oneshot writes ~/.config/tea/config.yml directly via heredoc; it never calls 'tea login add'. Fix the implementation detail. --- docs/turn-loop.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/turn-loop.md b/docs/turn-loop.md index 48348b4a..4d295b82 100644 --- a/docs/turn-loop.md +++ b/docs/turn-loop.md @@ -403,11 +403,11 @@ hyperhive.matrix.url = "http://localhost:8008"; # default ``` **`hyperhive.forge.url`** — base URL of the Forgejo instance. Used by -a one-shot boot unit that runs `tea login add --url --token -$(cat $HYPERHIVE_STATE_DIR/forge-token)`, making `tea` and -`hive-forge` work without an extra auth step. The unit is a no-op -when `forge-token` is absent. Override when the agent should connect -to a Forgejo on a different host or port (e.g. a swarm peer's forge). +a one-shot boot unit (`tea-login`) that writes `~/.config/tea/config.yml` +directly from the agent's `forge-token`, so `tea` and `hive-forge` +work without an interactive auth step. The unit is a no-op when +`forge-token` is absent. Override when the agent should connect to a +Forgejo on a different host or port (e.g. a swarm peer's forge). Validated: must be an `http://` or `https://` URL or the empty string. **`hyperhive.matrix.url`** — homeserver URL used by