vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2

docs: repoint agent-tier option paths to services.hyperhive.agent.*

Browse source 
Refs #4479
This commit is contained in:
atlas 2026-09-18 00:55:51 +02:00 • committed by mara
commit 7570597190
18 changed files with 78 additions and 78 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/turn-loop/README.md
View file

@ -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 <addr>` 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).

12
docs/turn-loop/claude-invocation.md
View file

@ -42,7 +42,7 @@ deliberately not in that file — the `--effort` flag
live, which managed scope would otherwise lock.
The harness reads `<name>` 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 <name>` 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`.

44
docs/turn-loop/config.md
View file

@ -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.<swarm-domain>` 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)

6
docs/turn-loop/mcp.md
View file

@ -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:<hyperhive.mcp.httpPort>`,
streamable HTTP (loopback, `127.0.0.1:<services.hyperhive.agent.mcp.httpPort>`,
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 —