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)
This commit is contained in:
iris
mara
parent
83059a0fcb
commit
8f4a8fbc07
1 changed files with 110 additions and 0 deletions
|
|
@ -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 `<state>/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 (`/<target>/…`) 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 <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
|
||||
|
|
|
|||
Loading…
Reference in a new issue