diff --git a/docs/README.md b/docs/README.md index 1ae0fda8..163fcd63 100644 --- a/docs/README.md +++ b/docs/README.md @@ -53,7 +53,7 @@ declarations. - **How does the matrix-tuwunel container work? Multiple accounts per agent?** → [`integrations/matrix.md`](integrations/matrix.md) (the homeserver); [`tools/matrix.md`](tools/matrix.md) for the MCP tool surface and - `hyperhive.matrixAccounts`. + `services.hyperhive.agent.matrixAccounts`. - **How do I give an agent a GitHub account (`gh` + `git push`)? how's the PAT injected?** → [`integrations/github.md`](integrations/github.md) (operator content up top; the `gh`/git-push + notification-poller diff --git a/docs/agent-lifecycle/agent-hierarchy.md b/docs/agent-lifecycle/agent-hierarchy.md index 7e66d48d..481d4994 100644 --- a/docs/agent-lifecycle/agent-hierarchy.md +++ b/docs/agent-lifecycle/agent-hierarchy.md @@ -194,7 +194,7 @@ direct mentions, reviews, and assignments. session dir. - `HIVE_STATIC_DIR = ` — `tower_http::ServeDir` root for the per-agent web UI; merged dist = agent default + every - `hyperhive.frontend.extraFiles` overlay. + `services.hyperhive.agent.frontend.extraFiles` overlay. - `HIVE_ASSETS_DIR = pkgs.hyperhive-assets/share/hyperhive` — set directly on the unit, **not** via `environment.variables`, because the latter only populates `/etc/profile` which systemd services @@ -213,7 +213,7 @@ wrappers — notably `sudo` — resolve before bare nix-store binaries; see general. It's load-bearing here because the harness runs as the per-agent user: without the wrapper dir on `PATH`, `sudo` resolves to the non-setuid nix-store binary and every -`hyperhive.user.passwordlessSudo` grant fails with "must be owned by +`services.hyperhive.agent.user.passwordlessSudo` grant fails with "must be owned by uid 0 and have the setuid bit set." ### `serviceConfig` highlights @@ -229,7 +229,7 @@ uid 0 and have the setuid bit set." the host bind-mounts in root-owned and which holds hive-c0re's `mcp.sock`. - `User = Group = userName` — drops root inside the container; sudo is - the explicit escalation surface (`hyperhive.user.passwordlessSudo`). + the explicit escalation surface (`services.hyperhive.agent.user.passwordlessSudo`). ## Cross-references diff --git a/docs/agent-lifecycle/persistence.md b/docs/agent-lifecycle/persistence.md index 218b7ce2..e93d36c6 100644 --- a/docs/agent-lifecycle/persistence.md +++ b/docs/agent-lifecycle/persistence.md @@ -505,7 +505,7 @@ reinstall. ## First-boot agent-user migration The harness runs as a per-agent unix user inside the container -(`hyperhive.user.name`, defaults to the agent's logical label so each +(`services.hyperhive.agent.user.name`, defaults to the agent's logical label so each container has a uniquely named user). Operators with legacy root-owned state dirs need a one-time data shuffle so they don't lose their claude session. @@ -544,10 +544,10 @@ the body + marker check at that point. `hive-matrix-daemon` is a long-running matrix-sdk Client + sync process per agent. Serves its MCP tools directly over -streamable-http (`hyperhive.mcp.matrixHttpPort`, no stdio bridge — +streamable-http (`services.hyperhive.agent.mcp.matrixHttpPort`, no stdio bridge — same shape as `hive-bash-daemon`), emits hyperhive wake signals on incoming room events via `/run/hive/mcp.sock`. Conditional on -`hyperhive.matrix.enable` (which both the daemon AND the +`services.hyperhive.agent.matrix.enable` (which both the daemon AND the autoinjected `extraMcpServers.matrix` entry read). **First-boot ordering**: hive-c0re provisions the matrix token AFTER @@ -565,7 +565,7 @@ avatar (see below). ### matrix avatar (set by the daemon over the live Client) -`hive-matrix-daemon` itself publishes the agent icon (`hyperhive.icon`, an SVG) as each matrix +`hive-matrix-daemon` itself publishes the agent icon (`services.hyperhive.agent.icon`, an SVG) as each matrix account's profile avatar (`hive-matrix-mcp::client::sync_avatar`), not a separate oneshot. After the daemon builds + restores an account's `Client` (authenticated, @@ -578,7 +578,7 @@ bring-up loop, so it sets the avatar for **every** account. Nix rasterizes the SVG to a 512x512 PNG at build time (`iconPng`, via librsvg) and forwards its store path as `HIVE_ICON_PNG` on the daemon -unit, gated on `hyperhive.icon != null`. No icon configured → the env is +unit, gated on `services.hyperhive.agent.icon != null`. No icon configured → the env is unset → `sync_avatar` returns early and no avatar is set. Idempotency is **per-account**: an `avatar-icon-hash` file in each diff --git a/docs/integrations/github.md b/docs/integrations/github.md index f0676498..8ea4fc4a 100644 --- a/docs/integrations/github.md +++ b/docs/integrations/github.md @@ -12,7 +12,7 @@ injects the token into the agent's state dir out of band. ## Enabling -The integration is **on by default** for every agent (`hyperhive.github.enable +The integration is **on by default** for every agent (`services.hyperhive.agent.github.enable = true`), inert until the operator provisions a PAT. No per-agent declaration is needed — an agent gains GitHub by having a PAT written to its token file. @@ -23,9 +23,9 @@ To turn it off for the whole hive, set the host option: services.hyperhive.github.enable = false; ``` -hive-c0re's meta-flake renderer then injects `hyperhive.github.enable = false` +hive-c0re's meta-flake renderer then injects `services.hyperhive.agent.github.enable = false` into every agent, so no agent ships the `gh` wrapper or credential helper. -(`hyperhive.github.enable` also exists per-agent for completeness, but the +(`services.hyperhive.agent.github.enable` also exists per-agent for completeness, but the hive-wide host switch is the intended control.) github.com only. The token **value** never touches nix — it's written to @@ -92,7 +92,7 @@ notification thread into a todo. it's a **separate binary and a separate systemd unit** from the internal forge's poller (`hive-forge-notify`, see [forge.md](forge.md#notification-poller-hive-forge-notifysrcnotifyrs)), installed by `nix/agent-modules/github.nix` under -`hyperhive.github.enable`. Both binaries ship from the one +`services.hyperhive.agent.github.enable`. Both binaries ship from the one `hive-forge-notify` derivation, so the unit is a second `ExecStart` path, not a new package. diff --git a/docs/networking/gateway.md b/docs/networking/gateway.md index 91da6c0f..63838294 100644 --- a/docs/networking/gateway.md +++ b/docs/networking/gateway.md @@ -461,7 +461,7 @@ unset (for example a build that predates `services.hyperhive.c0re.frontend`), ea legacy single-proxy block and nginx forwards all traffic to the agent daemon as before. -**`extraFiles`**: per-agent `hyperhive.frontend.extraFiles` are in +**`extraFiles`**: per-agent `services.hyperhive.agent.frontend.extraFiles` are in `mergedDist`, not in the base `services.hyperhive.c0re.frontend` dist. They're not under the nix-store `alias` path, so requests for them fall through `try_files` to `@_dynamic`, and the agent daemon serves them diff --git a/docs/process/conventions.md b/docs/process/conventions.md index 4872cf81..54523c7c 100644 --- a/docs/process/conventions.md +++ b/docs/process/conventions.md @@ -523,7 +523,7 @@ the state dir at provisioning time: `forge-token` written by `hive-c0re::forge::ensure_user_for`, so `tea repos create` / `tea pulls create` work without interactive prompts. -- `forge-avatar-sync` — uploads `hyperhive.icon` SVG to the +- `forge-avatar-sync` — uploads `services.hyperhive.agent.icon` SVG to the agent's Forgejo profile, so the icon shows up on commits / PRs / issue comments. diff --git a/docs/process/gotchas.md b/docs/process/gotchas.md index 881bf8cc..8577205f 100644 --- a/docs/process/gotchas.md +++ b/docs/process/gotchas.md @@ -135,7 +135,7 @@ agent's flake as a string literal and the agent module symlinks `path:/nix/store/` flake input is re-copied into the store as a reference-less `-source` (so the runtime closure never arrives), and `lib.types.package` fed a bare path runs `builtins.storePath`, which -pure evaluation rejects. `hyperhive.docs.source` gets away with being +pure evaluation rejects. `services.hyperhive.agent.docs.source` gets away with being an input only because a docs tree has no runtime dependencies. The `storePath` trap is worth spelling out, because it's not confined @@ -366,15 +366,15 @@ Never use raw `curl` for forge access. ## GUI (weston/VNC) -### Weston VNC compositor (per-agent `hyperhive.gui.enable`) +### Weston VNC compositor (per-agent `services.hyperhive.agent.gui.enable`) `nix/agent-modules/weston-vnc.nix` adds an optional Weston Wayland compositor with the `vnc-backend` plugin, surfaced as -`hyperhive.gui.enable = true` per-agent. The harness's +`services.hyperhive.agent.gui.enable = true` per-agent. The harness's `/screen/ws` WebSocket relay (`docs/web-ui/agent.md::Per-agent endpoints`) connects to the compositor at `127.0.0.1:`. -- **Port allocation**: a **fixed** port (`hyperhive.gui.vncPort`, +- **Port allocation**: a **fixed** port (`services.hyperhive.agent.gui.vncPort`, default 5900). No per-agent hashing: network isolation is unconditional (each agent has its own netns — see `docs/networking/network.md#container-isolation`), so the VNC port is @@ -384,7 +384,7 @@ connects to the compositor at `127.0.0.1:`. the agent **web-UI** port, which is still an FNV-1a hash because those listen on the shared host stack — see `Web UI ports collide on hash`.) - **Non-root, shared user session**: weston runs as the agent's own - user (`hyperhive.user.name`, the same user hive-ag3nt runs as), not + user (`services.hyperhive.agent.user.name`, the same user hive-ag3nt runs as), not root, so the GUI and the agent share one session. The runtime dir is a fixed `/run/gui` (systemd `RuntimeDirectory=gui`, `0700`, `RuntimeDirectoryPreserve=yes` so it survives weston restarts for the @@ -407,7 +407,7 @@ connects to the compositor at `127.0.0.1:`. launched with `--socket=wayland-0` so the socket path is deterministic. `nix/agent-modules/weston-vnc.nix` exports `WAYLAND_DISPLAY=wayland-0` and `XDG_RUNTIME_DIR=/run/gui` as global system environment - variables (gated on `hyperhive.gui.enable`) so every systemd service + variables (gated on `services.hyperhive.agent.gui.enable`) so every systemd service in the container inherits them. Without this, services starting Wayland clients couldn't find the compositor — libwayland falls back to a headless display or errors out, the app "works" on a @@ -505,7 +505,7 @@ The fix (`nix/docs/default.nix`): context. The resulting store path is content-addressed from the nix/ file contents only. Docs drvs only change when a `.nix` file changes. -2. The package options the modules consume (`hyperhive.packages.*`, +2. The package options the modules consume (`services.hyperhive.agent.packages.*`, `services.hyperhive.c0re.*`) carry no in-module defaults and every default that references them has a `defaultText`, so the doc walk never forces a package — no stubs needed, and the Rust/frontend diff --git a/docs/swarm/ui.md b/docs/swarm/ui.md index 1d1a4d08..8c151f6b 100644 --- a/docs/swarm/ui.md +++ b/docs/swarm/ui.md @@ -97,7 +97,7 @@ opening a popover of links to other swarm-wide services — authelia, matrix, forge, this UI's own swagger docs. Backed by `GET /api/links` (swarm-controller), which serves `services.hyperhive.swarm.controller.links` (a `listOf { label, icon, url }`, same shape as the per-agent -`hyperhive.dashboardLinks`). +`services.hyperhive.agent.dashboardLinks`). Rather than one central hardcoded list, each service's own module contributes its own entry when it's actually enabled on the controller's diff --git a/docs/tools/bash.md b/docs/tools/bash.md index f0bd5cb6..ac0d7afc 100644 --- a/docs/tools/bash.md +++ b/docs/tools/bash.md @@ -2,7 +2,7 @@ Background shell execution via `hive-bash-daemon`. Tools land as `mcp__bash__` (the MCP server name is `bash`, not `hyperhive`). -`nix/agent-modules/mcp.nix` registers bash into `hyperhive.extraMcpServers` +`nix/agent-modules/mcp.nix` registers bash into `services.hyperhive.agent.extraMcpServers` by default (`lib.mkDefault`, with `allowedTools = ["*"]`) — an `agent.nix` can override or drop the entry, so this is a default, not an unconditional grant. Even where the entry is present, the server is only @@ -101,8 +101,8 @@ this structured path so tasks get task-id tracking and structured output. container, systemd service in `nix/agent-modules/mcp.nix`) — no stdio bridge. It owns subprocess management, output file writing, todo delivery on the harness's in-agent socket, **and** serves the `run`/`status`/`kill` -MCP tools directly over streamable-http on `hyperhive.mcp.bashHttpPort` -(declared in `hyperhive.extraMcpServers.bash` as `{ type = "http"; url = +MCP tools directly over streamable-http on `services.hyperhive.agent.mcp.bashHttpPort` +(declared in `services.hyperhive.agent.extraMcpServers.bash` as `{ type = "http"; url = ...; }`). Same shape as the built-in `hyperhive` surface (`hive-mcp-http`) — claude reconnects to the stable URL every turn instead of respawning a stdio child, so there's no per-turn MCP re-registration race and no diff --git a/docs/tools/hivectl.md b/docs/tools/hivectl.md index ab4b747a..2bfbfb24 100644 --- a/docs/tools/hivectl.md +++ b/docs/tools/hivectl.md @@ -97,7 +97,7 @@ agent's token file so its `gh` wrapper + git credential helper can act as the bot account. Unlike forge/matrix there is no account creation — the PAT is for an existing GitHub account. A CLI alternative to the dashboard credentials tab; the [GitHub integration](../integrations/github.md) is on by default -(`hyperhive.github.enable`), so no per-agent config is needed. +(`services.hyperhive.agent.github.enable`), so no per-agent config is needed. ```bash hivectl github set-token damocles --token-stdin # paste the PAT on stdin (preferred) diff --git a/docs/tools/matrix.md b/docs/tools/matrix.md index 8d39c7ed..147313a8 100644 --- a/docs/tools/matrix.md +++ b/docs/tools/matrix.md @@ -2,7 +2,7 @@ ## Built-in matrix MCP (`mcp__matrix__*`) -When `hyperhive.matrix.enable = true` and the host-level matrix +When `services.hyperhive.agent.matrix.enable = true` and the host-level matrix tuwunel is configured, the harness autoinjects `hive-matrix-daemon`'s streamable-http endpoint as a second MCP server (no stdio bridge — see Architecture below). Tools land as `mcp__matrix__`: @@ -69,17 +69,17 @@ room you haven't read yet. ## Multiple accounts -`hyperhive.matrixAccounts` (declared in `agent.nix`) gives an agent +`services.hyperhive.agent.matrixAccounts` (declared in `agent.nix`) gives an agent *additional* matrix identities beyond the hive-internal one — for example an external-facing account alongside the internal one. Each entry is keyed by account name and specifies `tokenFile` (bearer token, provisioned out-of-band; basename must start with `matrix-token`), `sessionDir` (per-account matrix-sdk sqlite state — crypto keys + cache), and an optional `homeserver` (defaults to -`hyperhive.matrix.url`). The hive-internal account is always named -`main`, synthesized from `hyperhive.matrix.url` + agent state — this +`services.hyperhive.agent.matrix.url`). The hive-internal account is always named +`main`, synthesized from `services.hyperhive.agent.matrix.url` + agent state — this option only declares extras, and `main` is a reserved key here. -Requires `hyperhive.matrix.enable = true`. +Requires `services.hyperhive.agent.matrix.enable = true`. Every matrix tool above takes an optional `account` parameter (a name from this map) to act as that identity instead of the primary one. @@ -94,8 +94,8 @@ bodies and invite todos gain an `[acct:]` prefix — see container, systemd service in `nix/agent-modules/matrix.nix`) — no stdio bridge, no separate bin. It owns the matrix-sdk `Client` + sync loop per configured account **and** serves the matrix tool surface -directly over streamable-http on `hyperhive.mcp.matrixHttpPort` -(declared in `hyperhive.extraMcpServers.matrix` as +directly over streamable-http on `services.hyperhive.agent.mcp.matrixHttpPort` +(declared in `services.hyperhive.agent.extraMcpServers.matrix` as `{ type = "http"; url = ...; }`). Same shape as `hive-bash-daemon` and the built-in `hyperhive` surface (`hive-mcp-http`) — claude reconnects to the stable URL every turn instead of respawning a stdio child. @@ -115,7 +115,7 @@ Incoming room events wake the agent via `AgentRequest::Wake` with per room) **Multi-account prefix**: when the daemon serves more than one account -(`hyperhive.matrixAccounts`), it prefixes every wake body and every invite todo +(`services.hyperhive.agent.matrixAccounts`), it prefixes every wake body and every invite todo below with `[acct:] `, so a wake arrives as `[acct:ccc] [matrix] in : …`. A single-account agent gets the formats exactly as written — the daemon adds nothing — which is why matching @@ -147,7 +147,7 @@ provisioning flow, and federation config. ## Extra MCP servers (per-agent) Each agent's NixOS config can declare additional MCP servers via -`hyperhive.extraMcpServers. = { type, command, args, env, url, +`services.hyperhive.agent.extraMcpServers. = { type, command, args, env, url, allowedTools }` — `type = "stdio"` (the default, uses `command`/`args`/ `env`) or `type = "http"` (uses `url`, a long-lived streamable-http endpoint — see `hive-bash-daemon` and `hive-matrix-daemon` above for diff --git a/docs/tools/subagent.md b/docs/tools/subagent.md index ea0a07ea..fb7d9750 100644 --- a/docs/tools/subagent.md +++ b/docs/tools/subagent.md @@ -8,7 +8,7 @@ capability than a background shell command, so it gets its own deployable/restartable unit rather than living inside the bash daemon. Shipped default-on for every agent — `nix/agent-modules/mcp.nix` injects -`subagent` into `hyperhive.extraMcpServers` via `lib.mkDefault` +`subagent` into `services.hyperhive.agent.extraMcpServers` via `lib.mkDefault` (`allowedTools = ["*"]`), same as `bash`. Default-on rather than unconditional: an `agent.nix` can override or drop the entry, which is what `mkDefault` is there for. The operator's own framing: default-on for @@ -210,7 +210,7 @@ assumption stops holding. ## Configuration -`hyperhive.mcp.subagentHttpPort` — the daemon's streamable-http listen +`services.hyperhive.agent.mcp.subagentHttpPort` — the daemon's streamable-http listen port. Same pattern as `bashHttpPort`/`matrixHttpPort`: a per-agent default assigned by `nix/agent-modules/mcp.nix`, only worth overriding for an agent that needs a stable or non-default port. @@ -284,7 +284,7 @@ all, and the automatically injected `bash`/`subagent` entries default to exclude too (a subagent can't spawn hive-bash tasks or its own nested subagents unless an operator opts them in explicitly, same as anything else). -Set `hyperhive.extraMcpServers..availableToSubagents = true` on a +Set `services.hyperhive.agent.extraMcpServers..availableToSubagents = true` on a specific entry to hand that one server to subagents as well — useful for, say, a read-only lookup or scraper MCP a subagent's bounded, single-batch task might need. `hive-subagent-mcp`'s `mcp_config` module renders the diff --git a/docs/turn-loop/README.md b/docs/turn-loop/README.md index c37fca1e..6ef2233e 100644 --- a/docs/turn-loop/README.md +++ b/docs/turn-loop/README.md @@ -74,7 +74,7 @@ regardless of who sends them): claude-pump + ack/requeue cycle described above). - `hive-agent-mcp` — MCP server for the built-in `hyperhive` surface. Run with `--http ` as a persistent streamable-HTTP daemon (the - `hive-mcp-http` systemd unit, on `hyperhive.mcp.httpPort`, default + `hive-mcp-http` systemd unit, on `services.hyperhive.agent.mcp.httpPort`, default 8790); claude connects to its URL via `--mcp-config`. HTTP is the sole transport — no per-turn stdio child (eliminates the re-registration race). diff --git a/docs/turn-loop/claude-invocation.md b/docs/turn-loop/claude-invocation.md index 4f964d35..f207e371 100644 --- a/docs/turn-loop/claude-invocation.md +++ b/docs/turn-loop/claude-invocation.md @@ -42,7 +42,7 @@ deliberately not in that file — the `--effort` flag live, which managed scope would otherwise lock. The harness reads `` from `Bus::model()` on each turn. -`hyperhive.model` in the agent's `agent.nix` sets the initial +`services.hyperhive.agent.model` in the agent's `agent.nix` sets the initial default (NixOS option; propagates via `HIVE_DEFAULT_MODEL` env var; falls back to `"haiku"` if unset). The operator can flip it at runtime with `/model ` in the web terminal — the next turn picks it @@ -146,7 +146,7 @@ deliberately _not_ the primary mechanism — it runs with no checkpoint and none of the `CHECKPOINT_PROMPT` notes-flush machinery above, so a session saved by it still loses whatever wasn't already durable — but it can act _mid-turn_, underneath `InfiniteSession::run`, which the two triggers above -structurally can't. Don't confuse this with the `hyperhive.autoCompact` +structurally can't. Don't confuse this with the `services.hyperhive.agent.autoCompact` nix option below: that one is a per-agent on/off for hyperhive's _own_ proactive watermark and has no effect on claude's native mechanism, which is fleet-wide and set once in `hive-agent/prompts/claude-settings.json`. @@ -171,7 +171,7 @@ a live claude process. To disable proactive compaction for a specific agent, use the nix option: ```nix -hyperhive.autoCompact = false; # default true +services.hyperhive.agent.autoCompact = false; # default true ``` Setting `autoCompact = false` sets `HIVE_COMPACT_WATERMARK_TOKENS=0`, which @@ -228,7 +228,7 @@ needs to `chown` a bind mount), once at startup: - `claude-mcp-config.json` — points claude at the persistent `hive-mcp-http` daemon (`http://127.0.0.1:{port}/mcp`, port from - `hyperhive.mcp.httpPort`, default 8790) for the built-in `hyperhive` + `services.hyperhive.agent.mcp.httpPort`, default 8790) for the built-in `hyperhive` surface. HTTP is the sole transport for it — no per-turn stdio child, so the URL survives the per-turn claude re-spawn (no re-registration race), trading that for a hard dependency on the daemon's uptime @@ -241,11 +241,11 @@ needs to `chown` a bind mount), once at startup: substituted: `{label}` (short agent name), `{qualified_label}` (hive-qualified `name@domain` form), `{operator_pronouns}`, `{hive_identity}` (for example `` on hive `pr1ma` ``; empty when - `hyperhive.hiveName` is unset), and `{swarm_identity}` (same + `services.hyperhive.agent.hiveName` is unset), and `{swarm_identity}` (same shape for the swarm). Pronouns come from `HIVE_OPERATOR_PRONOUNS` env (set by the meta flake from `services.hyperhive.c0re.operatorPronouns`, default `she/her`). - When `hyperhive.docs.enable` is set, `HIVE_DOCS_DIR` is present + When `services.hyperhive.agent.docs.enable` is set, `HIVE_DOCS_DIR` is present in the environment and `render()` appends a one-sentence pointer telling the agent the docs are mounted at that path. Passed via `--system-prompt-file`. diff --git a/docs/turn-loop/config.md b/docs/turn-loop/config.md index ebc14000..415c7ba1 100644 --- a/docs/turn-loop/config.md +++ b/docs/turn-loop/config.md @@ -5,10 +5,10 @@ Optional per-agent knobs, set under `hyperhive.*` in the agent's own Absent means the default. (The claude spawn + compaction themselves live in [claude-invocation](claude-invocation.md).) -## Reference docs (`hyperhive.docs.enable`) +## Reference docs (`services.hyperhive.agent.docs.enable`) ```nix -hyperhive.docs.enable = true; # default: false (true for the manager agent) +services.hyperhive.agent.docs.enable = true; # default: false (true for the manager agent) ``` Makes the hyperhive `docs/` tree available inside the container at a nix @@ -27,7 +27,7 @@ that input — not every agent's container gets rebuilt on a doc-only change. ## Agent icon ```nix -hyperhive.icon = ./icon.svg; # default: null (falls back to shared hyperhive logo) +services.hyperhive.agent.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 @@ -44,7 +44,7 @@ at `GET /icon` on the per-agent web port. ## `user.passwordlessSudo` ```nix -hyperhive.user.passwordlessSudo = true; # default +services.hyperhive.agent.user.passwordlessSudo = true; # default ``` Grants the per-agent unix user passwordless `sudo` (`NOPASSWD: ALL`). @@ -57,15 +57,15 @@ 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 +`services.hyperhive.agent.user.uid`, `services.hyperhive.agent.user.gid`, and +`services.hyperhive.agent.user.name` are the companion options; see `docs/agent-lifecycle/agent-hierarchy.md` — "Harness systemd unit shape" for the full `user.*` surface. ## Dashboard links ```nix -hyperhive.dashboardLinks = [ +services.hyperhive.agent.dashboardLinks = [ { label = "Stats"; icon = "📊"; url = "http://localhost:9001/stats"; } { label = "Scratchpad"; url = "http://localhost:8080"; } ]; @@ -92,7 +92,7 @@ Omitting the option (default empty) produces no extra links. ## Custom static files ```nix -hyperhive.frontend.extraFiles = { +services.hyperhive.agent.frontend.extraFiles = { "games/bitburner" = { source = ./bitburner-dist; # path relative to agent.nix # target defaults to attribute name: "games/bitburner" @@ -121,23 +121,23 @@ rejects `..` segments. The merge step refuses to overwrite files already present in the default dist — pick a target name that doesn't collide with existing paths (`static/`, `index.html`, etc.). -The default dist ships at `hyperhive.frontend.dist` (the +The default dist ships at `services.hyperhive.agent.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 +Two `services.hyperhive.agent.forge.*` / `services.hyperhive.agent.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://forge.example:3000"; # default: null -hyperhive.matrix.url = "https://matrix.example"; # default: null +services.hyperhive.agent.forge.url = "http://forge.example:3000"; # default: null +services.hyperhive.agent.matrix.url = "https://matrix.example"; # default: null ``` -**`hyperhive.forge.url`** — base URL of the Forgejo instance. Used by +**`services.hyperhive.agent.forge.url`** — base URL of the Forgejo instance. Used by 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 @@ -156,7 +156,7 @@ host's real forge URL into every agent, and refuses to write a meta flake without one, so `null` only survives where nix evaluates the agent modules outside a hive. -**`hyperhive.matrix.url`** — homeserver URL used by +**`services.hyperhive.agent.matrix.url`** — homeserver URL used by `hive-matrix-daemon` when connecting via the matrix-sdk. hive-c0re writes it into every agent at deploy time as the gateway-routed `chat.` URL, so isolated agents can reach the homeserver. @@ -179,15 +179,15 @@ The harness installs Claude Code plugins before the serve loop opens. Three per-agent `agent.nix` options control this: ```nix -hyperhive.claudeMarketplaces = [ # default +services.hyperhive.agent.claudeMarketplaces = [ # default "anthropics/claude-plugins-official" - "${hyperhive.packages.claude-plugins}" # hive's own local marketplace, registered as `hyperhive` + "${services.hyperhive.agent.packages.claude-plugins}" # hive's own local marketplace, registered as `hyperhive` ]; -hyperhive.claudePlugins = [ # default +services.hyperhive.agent.claudePlugins = [ # default "skill-creator@claude-plugins-official" "base@hyperhive" ]; -hyperhive.claudePluginsAutoUpdate = false; # default +services.hyperhive.agent.claudePluginsAutoUpdate = false; # default ``` - **`claudeMarketplaces`** — list of marketplace sources passed to @@ -222,7 +222,7 @@ hyperhive.claudePluginsAutoUpdate = false; # default ## `cargo.shortMessages` ```nix -hyperhive.cargo.shortMessages = true; # default +services.hyperhive.agent.cargo.shortMessages = true; # default ``` When enabled (the default), the harness injects a `cargo` shell @@ -243,10 +243,10 @@ programmatically and don't pass `--message-format json` themselves. ## API-key provider (`useApiKey` / `backendEnvironmentFile`) ```nix -hyperhive.useApiKey = true; # default: false -hyperhive.backendEnvironmentFile = +services.hyperhive.agent.useApiKey = true; # default: false +services.hyperhive.agent.backendEnvironmentFile = "/agents/myagent/harness/openrouter.env"; # default: null -hyperhive.model = "anthropic/claude-3.5-sonnet"; # provider-specific model string +services.hyperhive.agent.model = "anthropic/claude-3.5-sonnet"; # provider-specific model string ``` Runs this agent's `claude` against an API-key provider (for example OpenRouter) diff --git a/docs/turn-loop/mcp.md b/docs/turn-loop/mcp.md index c565a322..6272126b 100644 --- a/docs/turn-loop/mcp.md +++ b/docs/turn-loop/mcp.md @@ -2,13 +2,13 @@ The harness ships an embedded MCP server (rmcp 2). A persistent `hive-mcp-http` daemon serves the built-in `hyperhive` surface over -streamable HTTP (loopback, `127.0.0.1:`, +streamable HTTP (loopback, `127.0.0.1:`, per-container private netns). Claude connects to its stable URL via `--mcp-config` rather than respawning a stdio child each turn, so the URL survives the per-turn claude re-spawn (and a host-side hive-c0re restart) — there is no per-turn MCP re-registration race for the built-in surface. HTTP is the sole transport for it (no stdio fallback). -Extra servers (`hyperhive.extraMcpServers`) pick their own transport per +Extra servers (`services.hyperhive.agent.extraMcpServers`) pick their own transport per entry (`type = "stdio" | "http"`, default `"stdio"`): `matrix` stays a stdio bridge, `bash` runs its own persistent streamable-http listener (`hive-bash-daemon`) — same reasoning as the built-in surface. The @@ -33,7 +33,7 @@ preset (`AGENT_DEFAULT`) includes `messaging`, `meta`, `inbox`, and parent without hardcoding the label; the broker resolves the sentinel at delivery time. Optional `in_reply_to: i64` links the message to a prior id for thread rendering. Per-agent - `hyperhive.allowedRecipients` (default: empty = unrestricted) limits + `services.hyperhive.agent.allowedRecipients` (default: empty = unrestricted) limits which names `send` accepts — useful for sandboxing: set `[ "operator" ]` to restrict a sub-agent to operator messages only (the topology parent is always reachable regardless of this list — diff --git a/docs/web-ui/agent.md b/docs/web-ui/agent.md index c89436b4..c53fd28d 100644 --- a/docs/web-ui/agent.md +++ b/docs/web-ui/agent.md @@ -33,7 +33,7 @@ structurally rather than for one specific trigger. Two columns: the parent flex container open via `align-items: stretch`-driven height feedback. Falls back to the dimmed hyperhive mark (`/favicon.svg`) on load error (`/icon` 404s when the agent has no - `hyperhive.icon` override — there is no server-side default image). + `services.hyperhive.agent.icon` override — there is no server-side default image). - **Main column** (`.agent-header-main`, `Header.tsx`): two rows — title (`◆