docs(coordinator): document agentCpuQuota, agentMemoryMax, preBuildAgentTemplates

Three host-level NixOS options in services.hyperhive.c0re were
undocumented. Add a new 'Host-level resource + performance options'
section to coordinator.md covering:

- agentCpuQuota (default 200%) — CPUQuota= drop-in per container
- agentMemoryMax (default 4G) — MemoryMax= drop-in per container
- preBuildAgentTemplates (default false) — pre-fetch agent closures
  into host nix store; trade system closure size for first-spawn speed;
  warn against enabling on aarch64 hosts
This commit is contained in:
iris 2026-06-05 17:58:20 +02:00 committed by mara
commit 2c7d723de6

View file

@ -212,6 +212,53 @@ or the flake root directly — none of which exist in the rendered meta flake.
---
## Host-level resource + performance options
Three `services.hyperhive.c0re.*` options tune container resource
limits and first-spawn latency. All three apply uniformly to every
agent container.
### Container resource limits
`agentCpuQuota` and `agentMemoryMax` map directly to systemd
`CPUQuota=` and `MemoryMax=`. hive-c0re writes a
`container@h-<name>.service.d/` drop-in file on each spawn and
rebuild, so changes take effect on the next lifecycle op without
requiring a host rebuild.
| Option | Default | Description |
|--------|---------|-------------|
| `services.hyperhive.c0re.agentCpuQuota` | `"200%"` | CPU cap per agent, as a percentage of one core (`"200%"` = 2 cores). Raise if agents hit CPU limits during builds or heavy tool use. |
| `services.hyperhive.c0re.agentMemoryMax` | `"4G"` | Memory cap per agent. Raise for agents that run large nix builds or hold big in-memory data. |
For a hive-wide cap across all containers together, set
`systemd.slices.machine.serviceConfig.CPUQuota` in your NixOS
config — all nspawn containers live in `machine.slice`.
### Pre-building agent templates
`preBuildAgentTemplates` (default `false`) causes the host NixOS
build to pre-fetch the per-container system closures
(`agent-base` + manager toplevels) into `/nix/store`, instead of
leaving that work to the first `nixos-container start`. The
trade-off:
- **On** (recommended for x86_64 hosts that care about first-spawn
latency): the first `nixos-container start` for any new agent
completes in seconds because nothing is left to fetch. Cost:
the full nixpkgs runtime closure + claude-code + the harness
binary are added to the host system closure (low single-digit GB
additional).
- **Off** (default): the host closure stays lean; the first spawn
does all the eval + fetch work at runtime (can take several
minutes on a fresh store).
**Note**: toplevels are pinned to `x86_64-linux`. Enabling on an
`aarch64` host forces a cross-compilation or remote-builder build,
which is almost never desired. Leave off on non-x86 hosts.
---
## See also
- `docs/approvals.md` — approval flow + scheduled prompts