From 9e76589be3b0928d3a5dd6531c05d655121ff043 Mon Sep 17 00:00:00 2001 From: atlas Date: Wed, 2 Sep 2026 10:17:40 +0200 Subject: [PATCH] docs: 10 cited nix options that do not exist, two in pasteable blocks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit An option name that is absent reads exactly like one that is present — the reader has no way to tell, and the failure surfaces as a nixos eval error at deploy time. Two namespace reorgs the prose never followed: `forge.*` moved under `swarm.`, and several flat paths under `c0re.`. docs/networking/gateway.md:335 services.hyperhive.forge = { … } docs/networking/gateway.md:367 forge.rootUrl → swarm.forge.rootUrl docs/networking/gateway.md:389 frontend → c0re.frontend docs/tools/hivectl.md:193 agentCpuQuota → c0re.agentCpuQuota docs/tools/hivectl.md:317 forge.behindGateway → swarm.forge.behindGateway docs/agent-lifecycle/persistence.md:404 agentCpuQuota → c0re.agentCpuQuota docs/web-ui/dashboard.md:610 modelPrices → c0re.modelPrices docs/web-ui/dashboard.md:789 forge.publicUrl → swarm.forge.publicUrl Both `gateway.md` blocks are fenced nix an operator is meant to paste. Two sites needed more than a rename: dashboard.md:781 cited `gateway.enable` as a live opt-in. It was removed; `gateway.md:269` already says the gateway is unconditional, and `hive-c0re/environment.nix:208` sets HIVE_GATEWAY_ENABLED = "1" with no condition. Rewritten to say so, keeping the flag-absent fallback the dashboard still implements. turn-loop/config.md:4 attributed the page's knobs to `services.hyperhive.agents.`. No such option exists — every knob the page documents is agent-side `hyperhive.*`, set in the agent's own agent.nix. Measured against the module system rather than a grep: `nix build .#docs` renders nixosOptionsDoc over the evaluated trees (279 option paths). That arm alone is wrong — it omits `internal = true` options and called `gateway.localNames` and `swarm.peerHives` dead, so a second arm requires the literal path to appear in nix/ and rescues exactly those. Four remaining unresolved citations are correct prose saying `gateway.enable` / `network.{enable,isolateContainers,upstreamDns}` were removed, and are left alone. Closes #3948 --- docs/agent-lifecycle/persistence.md | 2 +- docs/networking/gateway.md | 12 +++++++----- docs/tools/hivectl.md | 4 ++-- docs/turn-loop/config.md | 4 ++-- docs/web-ui/dashboard.md | 16 +++++++++------- 5 files changed, 21 insertions(+), 17 deletions(-) diff --git a/docs/agent-lifecycle/persistence.md b/docs/agent-lifecycle/persistence.md index 5bb14834..c2eb972f 100644 --- a/docs/agent-lifecycle/persistence.md +++ b/docs/agent-lifecycle/persistence.md @@ -401,7 +401,7 @@ Contents: into the container — these are host-side caps on the container, so the capped party never sees or sets them. Fallback is per *field*: an absent file, absent agent, or absent field falls back to the - hive-wide `services.hyperhive.agentCpuQuota` / `agentMemoryMax`, + hive-wide `services.hyperhive.c0re.agentCpuQuota` / `agentMemoryMax`, so an agent can override only its memory and still track the hive default for CPU. The `CPUWeight=` / `IOWeight=` shares in the same drop-in have **no** per-agent override — they are hive-wide only and diff --git a/docs/networking/gateway.md b/docs/networking/gateway.md index b3128d83..a5aa5c75 100644 --- a/docs/networking/gateway.md +++ b/docs/networking/gateway.md @@ -332,7 +332,7 @@ container. ### Network and port configuration ```nix -services.hyperhive.forge = { +services.hyperhive.swarm.forge = { httpPort = 3000; # default — HTTP listener; outside hyperhive's 7000/8100-8999 range sshPort = 2222; # default — git-over-SSH; kept off 22 so it doesn't collide with the host openssh openFirewall = false; # default — expose httpPort + sshPort to the host firewall @@ -364,7 +364,7 @@ that path. ### `rootUrl` override ```nix -services.hyperhive.forge.rootUrl = "https://forge.example.com/"; +services.hyperhive.swarm.forge.rootUrl = "https://forge.example.com/"; ``` `rootUrl` (default **null**) overrides the Forgejo `ROOT_URL` that is @@ -386,9 +386,11 @@ enforces this). ## Per-agent static frontend split -When `services.hyperhive.frontend` is configured, hive-c0re injects -`HIVE_AGENT_FRONTEND_DIR = "${cfg.frontend}/agent"` into its service -environment. The nginx include generator (`gateway_nginx::write`) reads +hive-c0re injects `HIVE_AGENT_FRONTEND_DIR` into its service +environment, pointing at the `agent/` subdirectory of the frontend dist +set by `services.hyperhive.c0re.frontend`. That option has a default, so +the variable is always set. +The nginx include generator (`gateway_nginx::write`) reads this variable and, when set, emits split location blocks per agent instead of the legacy single-proxy block. diff --git a/docs/tools/hivectl.md b/docs/tools/hivectl.md index 2b28892a..c701e39e 100644 --- a/docs/tools/hivectl.md +++ b/docs/tools/hivectl.md @@ -190,7 +190,7 @@ hivectl agent sock set-limits --memory-max 8G # CPU falls back to the hive de hivectl agent sock set-limits --reset # drop all overrides ``` -Overrides the hive-wide `services.hyperhive.agentCpuQuota` / +Overrides the hive-wide `services.hyperhive.c0re.agentCpuQuota` / `agentMemoryMax` for one agent, persisted to `meta/resource-limits.json` (see [`persistence.md`](../agent-lifecycle/persistence.md)). Values are systemd's @@ -314,6 +314,6 @@ an error. A surface has no URL when it isn't browser-reachable: `home` needs `services.hyperhive.domain`; `forge` needs -`services.hyperhive.forge.behindGateway = true`; `matrix` needs +`services.hyperhive.swarm.forge.behindGateway = true`; `matrix` needs `services.hyperhive.swarm.matrix.gui.enable = true`. In those cases the command exits with a hint naming the option to set. diff --git a/docs/turn-loop/config.md b/docs/turn-loop/config.md index e4a90d2d..0fea8fbf 100644 --- a/docs/turn-loop/config.md +++ b/docs/turn-loop/config.md @@ -1,7 +1,7 @@ # Agent config knobs -Optional per-agent knobs the meta flake wires into the container from -`services.hyperhive.agents.`, read at boot or per turn by the harness. +Optional per-agent knobs, set under `hyperhive.*` in the agent's own +`agent.nix` and read at boot or per turn by the harness. Absent means the default. (The claude spawn + compaction themselves live in [claude-invocation](claude-invocation.md).) diff --git a/docs/web-ui/dashboard.md b/docs/web-ui/dashboard.md index f7c415e6..116ae44a 100644 --- a/docs/web-ui/dashboard.md +++ b/docs/web-ui/dashboard.md @@ -607,7 +607,7 @@ library. The cost figure is a deliberately rough estimate from a per-model price table (`est_cost_usd`); it drifts with list pricing and is labelled accordingly. The table is operator-tunable via the -`services.hyperhive.modelPrices` nix option — each key is a +`services.hyperhive.c0re.modelPrices` nix option — each key is a model-family short name (matched case-insensitively as a substring of the model id, longest match wins) mapping to `{ input, output, cache_read, cache_write }` USD-per-million-token @@ -777,16 +777,18 @@ cache), `rate_limited`, `ctx_tokens` / `context_window_tokens` of truth for all of these. The dashboard resolves each `AgentLink.kind` against a per-agent base URL depending on whether hive-gateway is in front (`StateSnapshot.gateway_enabled`, sourced from the -`HIVE_GATEWAY_ENABLED` env the c0re NixOS module sets when -`services.hyperhive.gateway.enable = true`). Gateway-on (default): -base URL is `/agent/` (same origin, gateway proxies to the +`HIVE_GATEWAY_ENABLED` env). The c0re NixOS module sets that env +unconditionally — the gateway always runs; the flag stays so the +dashboard doesn't have to learn that. Gateway-on: base URL is +`/agent/` (same origin, gateway proxies to the per-agent harness — TCP or unix-domain depending on the agent's `HIVE_WEB_SOCKET` opt-in, see `docs/networking/gateway.md::Per-agent unix-socket upstream`). -Gateway-off (legacy / local dev): base URL is -`http://:` (direct TCP fallback). Forge +Gateway-off is the flag-absent fallback (a dashboard served outside a +hyperhive deploy): base URL is +`http://:` (direct TCP). Forge links resolve against `state.forge_public_url` (sourced from -`services.hyperhive.forge.publicUrl`) and are omitted entirely when +`services.hyperhive.swarm.forge.publicUrl`) and are omitted entirely when that's unset — never guessed from `:3000`. External links are already absolute. The same base URL drives the primary agent-name link + favicon fetch, so the whole row routes through the gateway