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

docs: 10 cited nix options that do not exist, two in pasteable blocks

Browse source 
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.<name>`. 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
This commit is contained in:
atlas 2026-09-02 10:17:40 +02:00 • committed by mara
commit 9e76589be3
5 changed files with 21 additions and 17 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/agent-lifecycle/persistence.md
View file

@ -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

12
docs/networking/gateway.md
View file

@ -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.

4
docs/tools/hivectl.md
View file

@ -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.

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

@ -1,7 +1,7 @@
# Agent config knobs
Optional per-agent knobs the meta flake wires into the container from
`services.hyperhive.agents.<name>`, 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).)

16
docs/web-ui/dashboard.md
View file

@ -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/<name>` (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/<name>` (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://<host>:<container.port>` (direct TCP fallback). Forge
Gateway-off is the flag-absent fallback (a dashboard served outside a
hyperhive deploy): base URL is
`http://<host>:<container.port>` (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 `<host>: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