diff --git a/docs/gotchas.md b/docs/gotchas.md index 85fb1b85..680023b7 100644 --- a/docs/gotchas.md +++ b/docs/gotchas.md @@ -238,3 +238,105 @@ and fail outright if the host daemon's `nix/templates/harness-base.nix` does `lib.mkForce true` so builds fall back to unsandboxed local builds rather than failing. Security implications: `docs/security.md`. + +## Split asset derivations away from the rust workspace + +`nix/assets.nix` builds the branding SVG/PNG family + claude +system-prompt template + claude-settings JSON as its own derivation, +separate from the hive-ag3nt / hive-c0re crates. Reason: when the +rust build's `src` was the whole repo tree, any tweak to +`branding/agent-configs.svg` or `hive-ag3nt/prompts/system.md` +invalidated the cargo cache and forced a full rebuild. crane (and +naersk before it) couldn't see "these inputs are unused by rust" on +its own — the split breaks the coupling at the derivation boundary. +The agent-configs PNG is rendered from the SVG via `rsvg-convert` at +build time; librsvg dependency lives here, not in the rust +derivation's `nativeBuildInputs`. + +## Weston VNC compositor (per-agent `hyperhive.gui.enable`) + +`nix/templates/weston-vnc.nix` adds an optional Weston Wayland +compositor with the VNC backend, surfaced as +`hyperhive.gui.enable = true` per-agent. The harness's +`/screen/ws` WebSocket relay (`docs/web-ui.md::Per-agent endpoints`) +connects to the compositor at `127.0.0.1:`. + +- **Port allocation**: deterministic FNV-1a of the agent name + (read from `/etc/hostname`, leading `h-` stripped) mapped into + `[15900, 16799]`. Mirrors the agent web-UI port pattern from + `docs/gotchas.md::Web UI ports collide on hash` — same FNV-1a + constant, different range. The compositor's startup script writes + `/etc/hyperhive/gui.json = {"vnc_port":N,"auth":"none"}` so the + harness reads the port at runtime; no nix-side / harness-side hash + duplication. +- **VNC bind address**: weston's VNC backend has no CLI + bind-address flag (unlike the RDP backend's `--address`), so the + listener binds `0.0.0.0`. The harness relay only connects via + `127.0.0.1`; the host firewall blocks the per-agent VNC port range + from external access. A future weston.ini `[vnc] address=` will + let us restrict the bind directly once upstream supports it. +- **PAM service name**: literal `weston-remote-access` — that's the + string libweston passes to `pam_start()` in `libweston/auth.c`. + Using `weston` falls back to the system default PAM stack and + rejects auth. The service is configured to `pam_permit.so` for + all three module types (auth / account / session) so the + browser's empty Apple-DH credentials (type 30) always pass — + neatvnc ≥ 0.9 calls the PAM auth callback regardless of + `weston.ini` `auth-method=none`, so the permit fallback is what + actually lets the empty-cred client through. +- **`Type = "simple"` (not `notify`)**: `switch-to-configuration` + must never block on weston signalling readiness. A misconfigured + weston degrades to a `Restart=on-failure` loop visible in + `journalctl`, it does not abort the `nixos-container update`. + Same reasoning as the `tea-login` unit in `harness-base.nix`. +- **`[core] idle-time=0`**: disables weston's 300-second idle + timeout. Without it the VNC desktop fades to black and + desktop-shell shows its click-to-unlock screen — useless for an + agent desktop viewed over `/screen`. `idle-time=0` updates the + idle timer with a 0ms delay, which + `wl_event_source_timer_update` treats as "disarm", so the + compositor never goes idle and never locks. + +## Nix options reference (`nix/docs/default.nix`) + +`pkgs.nixosOptionsDoc` over two evaluated module trees: +`hostEval` (a stub NixOS system loading `self.nixosModules.default` +with every hyperhive subsystem `mkForce false` so heavy build +inputs stay out of the eval) and `agentEval` (reuses the already-evaluated +`agent-base` container config so the per-agent options tree is +identical to what a real agent container sees). + +Three output trees consumed by `flake.nix`: + +- `docs-host` — operator-facing host module options + (`services.hyperhive.*`) +- `docs-agent` — per-agent harness options (`hyperhive.*` + declared in `nix/templates/harness-base.nix`) +- `docs` — bundled static site (`index.html` + `host.html` + + `agent.html`, plus `.md` source-of-truth versions of each + options page) + +Rendering pipeline: + +- CommonMark from `nixosOptionsDoc.optionsCommonMark` — source of + truth, kept as `.md` in the bundle. +- HTML via `pkgs.cmark-gfm` over the CommonMark, wrapped in a + minimal inline-CSS template. `cmark-gfm` (not plain `cmark`) so + any future tables / autolinks Just Work without revisiting. +- Inline `