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

docs/gotchas.md: scrub self-ref cookies (#719 batch 3)

Browse source
This commit is contained in:
iris 2026-05-31 15:40:28 +02:00 • committed by mara
commit 680d13b9e9
1 changed files with 24 additions and 28 deletions
Download patch file Download diff file Expand all files Collapse all files

52
docs/gotchas.md
View file

@ -87,8 +87,7 @@ propagate in. Operators don't need to set anything on their side.
## Claude credentials are per-agent ## Claude credentials are per-agent
`/var/lib/hyperhive/agents/<name>/claude/` bind-mounts to `/var/lib/hyperhive/agents/<name>/claude/` bind-mounts to
`/home/<name>/.claude` (RW; was `/root/.claude` pre-#658 when every `/home/<name>/.claude` (RW). Sharing one dir across agents is NOT viable —
harness ran as root). Sharing one dir across agents is NOT viable —
OAuth refresh tokens rotate, so any sibling refresh invalidates all OAuth refresh tokens rotate, so any sibling refresh invalidates all
the others. Login flow runs from the per-agent web UI; creds persist the others. Login flow runs from the per-agent web UI; creds persist
across `destroy`/recreate (`--purge` wipes them). across `destroy`/recreate (`--purge` wipes them).
@ -96,8 +95,8 @@ across `destroy`/recreate (`--purge` wipes them).
## Persistent notes dir per agent ## Persistent notes dir per agent
`/var/lib/hyperhive/agents/<name>/state/` bind-mounts to `/var/lib/hyperhive/agents/<name>/state/` bind-mounts to
`/agents/<name>/state` (RW; uniform for sub-agents + manager `/agents/<name>/state` (RW; uniform for sub-agents + manager).
post-#604, was `/state` pre-#604). The harness exposes the same path The harness exposes the same path
via `$HYPERHIVE_STATE_DIR`. System prompts tell agents to keep via `$HYPERHIVE_STATE_DIR`. System prompts tell agents to keep
durable knowledge here (`notes.md`, anything else). The harness also durable knowledge here (`notes.md`, anything else). The harness also
writes its events log here (`hyperhive-events.sqlite`). writes its events log here (`hyperhive-events.sqlite`).
@ -112,8 +111,8 @@ unlucky. Operator resolves a collision by renaming the offending
agent (different hash → different port) and rebuilding. No state agent (different hash → different port) and rebuilding. No state
file, no probing, no port-allocation drift — the value is file, no probing, no port-allocation drift — the value is
reproducible from just the name. Every agent — including the reproducible from just the name. Every agent — including the
manager — hashes into 8100..8999 via the same FNV-1a since #753; manager — hashes into 8100..8999 via the same FNV-1a; dashboard
dashboard at `cfg.dashboardPort` (default 7000). at `cfg.dashboardPort` (default 7000).
## Restart races on TCP bind ## Restart races on TCP bind
@ -146,13 +145,12 @@ files in subdirectories) fails with `EPERM`. Fix: pass
The naive nginx pattern for a path-prefix SPA (`try_files $uri $uri/ The naive nginx pattern for a path-prefix SPA (`try_files $uri $uri/
/matrix/index.html`) silently swallows asset 404s — a missing JS file /matrix/index.html`) silently swallows asset 404s — a missing JS file
returns `index.html` with a 200, so the JS runtime never loads and the returns `index.html` with a 200, so the JS runtime never loads and the
page renders blank with no visible error (#685; fixed in PR #684; page renders blank with no visible error. Extension allowlists (tried
#686 filed the follow-up edge-case, addressed in PR #729). as an alternative) have the same maintenance problem: any new file
Extension allowlists (tried in #686 → PR #729) have the same maintenance extension the SPA ships breaks silently.
problem: any new file extension the SPA ships breaks silently.
The correct pattern (landed in PR #729, `hive-gateway.nix`) keys the The pattern that works (`hive-gateway.nix`) keys the fallback on the
fallback on the HTTP `Accept` header: HTTP `Accept` header:
```nginx ```nginx
# Outside the server block (appendHttpConfig): # Outside the server block (appendHttpConfig):
@ -188,22 +186,22 @@ nix build /var/lib/hyperhive/meta#argus.config.system.build.toplevel
nix build /var/lib/hyperhive/meta#nixosConfigurations.argus.config.system.build.toplevel nix build /var/lib/hyperhive/meta#nixosConfigurations.argus.config.system.build.toplevel
``` ```
`lifecycle::prebuild_toplevel` hit this in #721 (fixed in #738) by `lifecycle::prebuild_toplevel` hit this once by constructing the attr
constructing the attr path as `{flake_ref}.config…` — which produced path as `{flake_ref}.config…` — which produced `meta#argus.config…`
`meta#argus.config…` instead of `meta#nixosConfigurations.argus.config…`. instead of `meta#nixosConfigurations.argus.config…`. The fix:
The fix: `split_once('#')` to separate flake path from name, then `split_once('#')` to separate flake path from name, then template
template `{path}#nixosConfigurations.{name}.config.system.build.toplevel`. `{path}#nixosConfigurations.{name}.config.system.build.toplevel`.
## `hive-forge`: prefer over raw curl pipelines ## `hive-forge`: prefer over raw curl pipelines
Every agent container has `hive-forge` in PATH (installed via Every agent container has `hive-forge` in PATH (installed via
`harness-base.nix`; lives in `/hive-forge` as a proper Rust binary `harness-base.nix`; lives in `/hive-forge` as a proper Rust binary).
since #280). Use it instead of ad-hoc curl pipelines: Use it instead of ad-hoc curl pipelines:
```bash ```bash
hive-forge view 42 # title + body + comments hive-forge view 42 # title + body + comments
hive-forge comments 42 # list all comments (human-readable) hive-forge comments 42 # list all comments (human-readable)
hive-forge --json comments 42 # same as above, JSON array (global flag, closes #421) hive-forge --json comments 42 # same as above, JSON array (global flag)
hive-forge comment 42 --body "..." # post comment (inline body) hive-forge comment 42 --body "..." # post comment (inline body)
hive-forge comment 42 --body-file - <<EOF # ...or pipe a HEREDOC hive-forge comment 42 --body-file - <<EOF # ...or pipe a HEREDOC
multi-line body multi-line body
@ -212,7 +210,7 @@ hive-forge assign 42 damocles
hive-forge close 42 hive-forge close 42
hive-forge labels 42 add feature hive-forge labels 42 add feature
hive-forge pr 42 # PR metadata as JSON hive-forge pr 42 # PR metadata as JSON
hive-forge pr-create --title "..." --head my-branch --push # also `git push forge my-branch`, suppressing the post-push "Create a pull request" hint (#222) hive-forge pr-create --title "..." --head my-branch --push # also `git push forge my-branch`, suppressing the post-push "Create a pull request" hint
hive-forge diff 42 # unified diff (lockfile hunks collapsed by default) hive-forge diff 42 # unified diff (lockfile hunks collapsed by default)
hive-forge diff 42 --full # include unfiltered lockfile hunks hive-forge diff 42 --full # include unfiltered lockfile hunks
hive-forge branches deployed/ # filter branches by pattern hive-forge branches deployed/ # filter branches by pattern
@ -333,10 +331,8 @@ Rendering pipeline:
declaration paths and rewrites them as forge URLs, so the declaration paths and rewrites them as forge URLs, so the
rendered docs link back to the source. rendered docs link back to the source.
Post-#615 (closes #630) host options live entirely under Host options live entirely under `services.hyperhive.*`. The
`services.hyperhive.*`. Pre-#615 had a mix of `hyperhive.*` (forge, `pickSubtrees` filter is rooted at `["services" "hyperhive"]` so the
matrix, domain) and `services.hive-c0re.*`; picking against the options tree picks up everything under that root — picking against
old roots on current main silently produced an empty options tree, stray roots produces an empty tree and renders the host page as
so the rendered host page was just template chrome with no `<h2>` template chrome with no `<h2>` headers.
headers. The `pickSubtrees` filter is rooted at
`["services" "hyperhive"]` for that reason.