From 2c7d723de69c25fff6505a87950ccff4bc38a9e3 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Fri, 5 Jun 2026 17:58:20 +0200
Subject: [PATCH] docs(coordinator): document agentCpuQuota, agentMemoryMax,
 preBuildAgentTemplates
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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
---
 docs/coordinator.md | 47 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/docs/coordinator.md b/docs/coordinator.md
index 44749143..e990d359 100644
--- a/docs/coordinator.md
+++ b/docs/coordinator.md
@@ -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