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: scrub #NNN self-references (closes #719)

Browse source 
Last pass of the docs-from-code → docs/ epic (#708). Drops every
attribution cookie from docs/ + README.md + CLAUDE.md so the
source-tree files no longer reference the issue tracker. Issue
threads + commit history retain the references — those are the
canonical record.

- README.md: drop #701 / #660×2 / #551 from matrix + display-name
  sections, rephrase to convey the semantics directly
- CLAUDE.md: scrub 18 cookies from the file map (#655, #15, #784,
  #832, #444, #425, #361, #548, #598, #539, #544, #589, #701,
  #658, #280, #660, #551, #764, #772, #793, #14, #805)
- docs/agent-hierarchy.md: drop #658 ×3 (per-agent user is the
  current shape, not a transition)
- docs/conventions.md: drop #571 (replaced with a docs xref to
  persistence.md::matrix-avatar-sync)
- docs/gateway.md: scrub vhost-map table cookies + Sub-domain
  rationale + Per-agent unix-socket upstream + Self-signed TLS +
  Firewall posture + HIVE_FORGE_URL + Per-agent error pages
  sections; drop the trailing 'Sequencing history' issue list +
  the 'Next-up' issue-link footnote
- docs/matrix.md: scrub serverName/gatewayHost + Default-closed
  firewall + Provisioning flow + Initial rollout + Assertion
  rationale + fluffychat-web build fixes; drop the trailing
  'Sequencing history' issue list
- docs/network.md: drop 'Why ship before #14' #805 quote +
  Container shape #805 attribution + trailing 'Sequencing history'
  + Cross-references issue links; rename v2 column to 'after netns
  isolation'
- docs/web-ui.md: drop #784 from Container row, replace with a
  docs xref to docs/gateway.md::Per-agent unix-socket upstream

Only remaining #NNN in docs/ is the literal markdown-heading
example in docs/forge.md (`#tag`, `#123`, `#!/bin/bash`)
which demonstrates the renderer's behaviour — not an attribution
cookie.
This commit is contained in:
iris 2026-05-31 17:47:21 +02:00
commit 6bdfe52386
8 changed files with 142 additions and 187 deletions
Download patch file Download diff file Expand all files Collapse all files

52
CLAUDE.md
View file

@ -25,9 +25,9 @@ hive-c0re/ host daemon + sibling operator CLI (lib + 2 bins)
deny / destroy [--purge] / request-spawn /
set-parent (--parent / --root); periodic
vacuum tasks.
src/bin/hivectl.rs `hivectl` binary (#655): operator-facing host
CLI for ad-hoc administration that doesn't
go through the broker. v0 verbs: `forge
src/bin/hivectl.rs `hivectl` binary: operator-facing host CLI
for ad-hoc administration that doesn't go
through the broker. v0 verbs: `forge
create-user <name>`, `matrix create-user
<name>` — wrap the same idempotent
`forge::ensure_user_for` /
@ -39,15 +39,15 @@ hive-c0re/ host daemon + sibling operator CLI (lib + 2 bins)
src/manager_server.rs manager-privileged socket (ManagerRequest)
src/agent_ports.rs writes `/var/lib/hyperhive/agent-ports.json` on
meta sync; gateway reads name→port map for
per-agent `/agent/<name>/` routing (#15).
per-agent `/agent/<name>/` routing.
src/agent_sockets.rs writes `/var/lib/hyperhive/agent-sockets.json` on
meta sync; gateway reads name→socket-path
map for unix-domain per-agent UI binding (#784).
map for unix-domain per-agent UI binding.
Entries are filtered by a `.bound` marker file
the harness drops next to its socket after a
successful `bind()` (#832) — pre-bind agents
stay out of the map so the gateway never races
a missing-socket upstream. A 10s poll loop
successful `bind()` — pre-bind agents stay out
of the map so the gateway never races a
missing-socket upstream. A 10s poll loop
(`spawn_poll`) re-fires the writer so the map
reconverges if a marker appears between
meta-sync ticks.
@ -76,7 +76,7 @@ hive-c0re/ host daemon + sibling operator CLI (lib + 2 bins)
src/scheduled_prompts.rs sqlite layer for scheduled prompts —
schema, CRUD helpers (`cancel_all`,
`cancel_targets`, `reap_cancelled`), catch-up
clamp on resume (#444)
clamp on resume
src/scheduled_prompts_worker.rs 5s poll loop: fires due rows,
fans out one Message per active target,
re-arms recurring rows, deletes fired one-shots
@ -86,7 +86,7 @@ hive-c0re/ host daemon + sibling operator CLI (lib + 2 bins)
when a previously-running container disappears
without an operator-initiated transient (or a
RECENT_TRANSIENT_GRACE tombstone within the
last 30s, closes #425)
last 30s)
src/container_view.rs ContainerView struct + build_all helper;
shared between dashboard.rs (cold-load via
/api/state) and coordinator.rs's
@ -128,7 +128,7 @@ hive-c0re/ host daemon + sibling operator CLI (lib + 2 bins)
and the eventual cap-enforcement plumbing all
read). Reconciled by `meta::sync_agents`;
operator/manager edits land via the
eventual write API (#361 follow-ups).
eventual write API.
src/forge.rs optional Forgejo wiring: per-agent users +
tokens, the `agent-configs` org (`push_config`),
and meta read access; mirrors each applied repo
@ -142,7 +142,7 @@ hive-c0re/ host daemon + sibling operator CLI (lib + 2 bins)
persists each agent's access_token to
`<state>/matrix-token`. Idempotent — skips
registration when token file already exists.
No-op when `hive-matrix` container absent (#548).
No-op when `hive-matrix` container absent.
src/dashboard.rs axum HTTP: /api/state JSON + actions
+ journald viewer + bind-with-retry (SO_REUSEADDR)
+ deployed_sha chip per container +
@ -169,7 +169,7 @@ frontend/ npm workspaces (esbuild → static dist). Built
+ agent.css → dist/{*.html, static/*}.
hive-ag3nt/ in-container harness crate; produces ONE `hive`
binary (post-#598) picking role from `HIVE_ROLE` env
binary picking role from `HIVE_ROLE` env
src/lib.rs re-exports + DEFAULT_SOCKET, DEFAULT_WEB_PORT
src/client.rs generic JSON-line request/response over unix socket
src/web_ui.rs per-container axum HTTP page (incl /api/cancel,
@ -194,15 +194,15 @@ hive-ag3nt/ in-container harness crate; produces ONE `hive`
escaped) and surfaces any @mention lines that
fell outside the truncation window in a
trailing `mentions (truncated from body):`
block (#539 / #544).
src/identity.rs hive-qualified agent label (#589 phase A):
`label()` / `qualified_label()` / `qualify(label)`.
Reads `HYPERHIVE_HIVE_DOMAIN`; falls back to short
name when unset. Display-name accessors (#701):
block.
src/identity.rs hive-qualified agent label: `label()` /
`qualified_label()` / `qualify(label)`. Reads
`HYPERHIVE_HIVE_DOMAIN`; falls back to short
name when unset. Display-name accessors:
`hive_name()` / `swarm_name()` read
`HYPERHIVE_HIVE_NAME` / `HYPERHIVE_SWARM_NAME`,
both `Option<String>`.
src/login.rs probe $HOME/.claude/ (post-#658 `/home/<agent>/.claude`)
src/login.rs probe $HOME/.claude/ (= `/home/<agent>/.claude`)
for a valid session
src/login_session.rs drives `claude auth login` over stdio pipes
src/prompt.rs system prompt renderer: filters the unified
@ -234,9 +234,9 @@ hive-forge/ Forgejo CLI wrapper (`hive-forge` binary)
close, labels, list, milestone, branches,
tree-sha, diff, subscription, attach-issue,
attach-comment, lint). Replaces the 600-line
hive-forge-tools.nix bash script (closes #280).
hive-forge-tools.nix bash script.
hive-matrix-mcp/ per-agent matrix-sdk integration (#548 phase 3).
hive-matrix-mcp/ per-agent matrix-sdk integration.
src/main.rs `hive-matrix-daemon` binary entry — long-running
matrix-sdk Client + sync per agent; serves the
MCP bridge over /run/hive-matrix/socket; emits
@ -277,9 +277,9 @@ nix/
modules/hive-matrix.nix optional in-container matrix-tuwunel
homeserver (`services.hyperhive.matrix.enable`,
default off); server_name defaults to bare
`services.hyperhive.domain` (#660); gateway serves
`services.hyperhive.domain`; gateway serves
`.well-known/matrix/{client,server}` for
auto-discovery; federation on, e2ee deferred (#551)
auto-discovery; federation on, e2ee deferred
templates/harness-base.nix shared harness for all containers; `hyperhive.role`
(`"agent"` | `"manager"`) drives service unit + forge
defaults; `hyperhive.model` option (HIVE_DEFAULT_MODEL)
@ -304,10 +304,10 @@ docs/
persistence.md sqlite dbs, retention, state dir layout
terminal-rendering.md per-agent terminal row taxonomy (as built)
boundary.md operator/agent trust model rationale
agent-hierarchy.md tree-shape topology design + manager-privilege audit (#361)
agent-hierarchy.md tree-shape topology design + manager-privilege audit
damocles-migration.md future migration plan for damocles → hyperhive
gateway.md nginx vhost map, matrix discovery flow, firewall posture,
HIVE_FORGE_URL loopback rationale (#764, #772, #793)
HIVE_FORGE_URL loopback rationale
forge.md per-agent forge accounts + agent-configs mirror;
forge_notify poller (gates, self-filter, body excerpt
pipeline, wrapper formats, reason drop-list,
@ -315,7 +315,7 @@ docs/
matrix.md matrix container shape, serverName/gatewayHost split,
firewall + federation, provisioning flow, fluffychat-web build
network.md host-side bridge + dnsmasq resolver, v1/v2 roadmap,
foundation for #14 netns isolation (#805)
foundation for netns isolation
```
## Reading paths

9
README.md
View file

@ -112,7 +112,7 @@ the wider swarm human-readable display labels. Distinct from
the dashboard chrome and the per-agent system prompt; the domain is
how things are addressed on the wire. Federated hives at different
domains can share a swarm name. Both default to null — chrome falls
back to the domain, the prompt simply doesn't mention them (#701).
back to the domain, the prompt simply doesn't mention them.
Optional: set `services.hyperhive.matrix.enable = true;` to spin up a
private [matrix-tuwunel](https://github.com/matrix-construct/tuwunel)
@ -120,16 +120,17 @@ homeserver in a nixos-container. Requires either
`services.hyperhive.domain` or `services.hyperhive.matrix.serverName`
to be set (eval fails with a clear error if both are absent). The
`server_name` (embedded irrevocably in every user and room ID)
defaults to `<domain>` (bare hive domain, since #660); the hive-gateway serves
defaults to `<domain>` (bare hive domain); the hive-gateway serves
`.well-known/matrix/{client,server}` endpoints so clients auto-discover the
homeserver without a subdomain. **Existing homeservers** must set
`services.hyperhive.matrix.serverName = "matrix.<domain>";` explicitly to
preserve pre-#660 user/room IDs. Override with
preserve their existing user/room IDs (the `server_name` is embedded
into every ID). Override with
`services.hyperhive.matrix.serverName = "chat.example.com";` for a custom
server name. State
lives at `/var/lib/nixos-containers/hive-matrix/`. Federation is
enabled with an empty `trusted_servers` list; e2ee is deferred to
a follow-up (#551).
a follow-up.
The hive-gateway nginx container serves a
[fluffychat-web](https://fluffychat.im) matrix client at `/matrix/`

14
docs/agent-hierarchy.md
View file

@ -251,9 +251,9 @@ boundary.
### Environment variables set on the unit
- `HOME = /home/<userName>` — systemd defaults `HOME` to `/` for
services without `User=` set; with the per-agent user (#658) the
harness needs the right home so claude finds its bind-mounted
`~/.claude/` session dir.
services without `User=` set; with the per-agent user the harness
needs the right home so claude finds its bind-mounted `~/.claude/`
session dir.
- `HIVE_STATIC_DIR = <mergedDist>` — `tower_http::ServeDir` root for
the per-agent web UI; merged dist = agent default + every
`hyperhive.frontend.extraFiles` overlay.
@ -275,9 +275,9 @@ resolve before bare nix-store binaries. NixOS's
`systemd.services.<unit>.path` appends `/bin` to every entry via
`lib.makeBinPath`; passing `/run/wrappers/bin` directly produces
`/run/wrappers/bin/bin` which doesn't exist (`docs/gotchas.md::
systemd.services.*.path appends /bin to every entry`). Post-#658
when the harness runs as the per-agent user this matters: without
the wrapper dir on PATH, `sudo` resolves to the un-setuid nix-store
systemd.services.*.path appends /bin to every entry`). With the
harness running as the per-agent user this matters: without the
wrapper dir on PATH, `sudo` resolves to the un-setuid nix-store
binary and rejects with `must be owned by uid 0 and have the setuid
bit set` regardless of `hyperhive.user.passwordlessSudo`.
@ -292,7 +292,7 @@ bit set` regardless of `hyperhive.user.passwordlessSudo`.
`claude-{mcp-config,settings,system-prompt}` files there
(`paths::config_dir`). Deliberately separate from `/run/hive`,
which the host bind-mounts in root-owned and which holds
hive-c0re's `mcp.sock` (#658 fixup).
hive-c0re's `mcp.sock`.
- `User = Group = userName` — drops root inside the container; sudo
is the explicit escalation surface
(`hyperhive.user.passwordlessSudo`).

4
docs/conventions.md
View file

@ -350,8 +350,8 @@ Shape contract — every one of these:
`systemctl restart` gymnastics).
5. **Re-runnable**: a second invocation produces the same final
state (idempotent uploads, idempotent config rewrites). Used
by the `.path` watchers that re-fire on token appearance
(#571 — see `docs/persistence.md::matrix-avatar-sync`).
by the `.path` watchers that re-fire on token appearance (see
`docs/persistence.md::matrix-avatar-sync`).
The artefact lives under the agent user's home where applicable
(`~/.config/tea/config.yml`) and is chown'd to that user, but the

98
docs/gateway.md
View file

@ -7,15 +7,15 @@ Single nginx in front of every hyperhive web surface. Container `hive-gateway`,
| URL | vhost | upstream | source |
| --- | --- | --- | --- |
| `<hive>/` | `_` (catch-all) | hive-c0re dashboard (`7000`) | always |
| `<hive>/agent/<name>/` | `_` | per-agent harness on `agent_web_port(name)` | `agentPortsFile` JSON, #15 |
| `<hive>/.well-known/matrix/{client,server}` | `_` | inline JSON (no upstream) | `matrix.enable && domain != null`, #660 / #747 |
| `<hive>/matrix/` (deprecated) | `_` | 301 → `matrix.<hive>/` | `matrix.gui.enable`, #772 |
| `forge.<hive>/` | `forge.<hive>` | forgejo (`3000`) | `forge.behindGateway`, #754 |
| `matrix.<hive>/_matrix/*` | `matrix.<hive>` | tuwunel (`8008`) | `matrix.gatewayHost != null`, #764 |
| `matrix.<hive>/` | `matrix.<hive>` | fluffychat-web static | `matrix.gui.enable`, #772 |
| `matrix.<hive>/config.json` | `matrix.<hive>` | inline JSON (FluffyChat boot config) | `matrix.gui.enable && domain != null`, #736 |
| `<hive>/agent/<name>/` | `_` | per-agent harness on `agent_web_port(name)` | `agentPortsFile` JSON |
| `<hive>/.well-known/matrix/{client,server}` | `_` | inline JSON (no upstream) | `matrix.enable && domain != null` |
| `<hive>/matrix/` (deprecated) | `_` | 301 → `matrix.<hive>/` | `matrix.gui.enable` |
| `forge.<hive>/` | `forge.<hive>` | forgejo (`3000`) | `forge.behindGateway` |
| `matrix.<hive>/_matrix/*` | `matrix.<hive>` | tuwunel (`8008`) | `matrix.gatewayHost != null` |
| `matrix.<hive>/` | `matrix.<hive>` | fluffychat-web static | `matrix.gui.enable` |
| `matrix.<hive>/config.json` | `matrix.<hive>` | inline JSON (FluffyChat boot config) | `matrix.gui.enable && domain != null` |
Per-agent UIs stay sub-path because they're hyperhive-internal and base-path-aware (iris #731). External standard apps (forge / matrix) get sub-domains because their defaults work cleanly at sub-domain root + per-origin cookies / storage isolation matters.
Per-agent UIs stay sub-path because they're hyperhive-internal and base-path-aware. External standard apps (forge / matrix) get sub-domains because their defaults work cleanly at sub-domain root + per-origin cookies / storage isolation matters.
## Discovery flow (matrix)
@ -34,9 +34,9 @@ Federation peers fetch `.well-known/matrix/server` → `{"m.server":"matrix.<hiv
The `<hive>` catch-all and the `matrix.<hive>` vhost both serve a flutter SPA (per-agent UI, fluffychat). Two requirements collide:
- hard-refresh on a sub-route must serve `index.html` (SPA's client-side router takes over after JS bootstrap)
- missing assets must surface as 404, not as HTML with wrong content-type (the original #643 bug)
- missing assets must surface as 404, not as HTML with wrong content-type
Solution: an `nginx http`-context `map $http_accept $matrix_spa_target { ... }` keyed on the request's Accept header. Browser navigations (`Accept: text/html,...`) get `index.html`; asset fetches (`Accept: image/*`, `*/*`, etc.) get a sentinel nonexistent path → `try_files` falls through to `=404`. No extension allowlist, no `if` block, no regex heuristics. #686 + #729 thread for the design history.
Solution: an `nginx http`-context `map $http_accept $matrix_spa_target { ... }` keyed on the request's Accept header. Browser navigations (`Accept: text/html,...`) get `index.html`; asset fetches (`Accept: image/*`, `*/*`, etc.) get a sentinel nonexistent path → `try_files` falls through to `=404`. No extension allowlist, no `if` block, no regex heuristics.
## Local dev (`localHostsEntry`)
@ -50,14 +50,14 @@ Solution: an `nginx http`-context `map $http_accept $matrix_spa_target { ... }`
## Sub-domain shape (rationale)
mara verdict at #749:9609 + #747:9722: sub-domain over sub-path for forge + matrix, sub-path for per-agent UIs.
Operator decision: sub-domain over sub-path for forge + matrix, sub-path for per-agent UIs.
- forgejo's default `ROOT_URL = http://<host>/` works without any `X-Forwarded-Prefix` gymnastics — sub-domain hosting is the canonical Forgejo deploy shape.
- matrix-spec deployments universally use `matrix.<server_name>` for the actual API listener — federation already expects this.
- per-agent UIs are hyperhive-internal; iris's #731 made them base-path-aware specifically for `/agent/<name>/`. Sub-domain per agent would multiply DNS + TLS-per-subdomain cost without per-app config wins.
- per-agent UIs are hyperhive-internal and base-path-aware specifically for `/agent/<name>/`. Sub-domain per agent would multiply DNS + TLS-per-subdomain cost without per-app config wins.
- cookie / storage isolation: a future forge XSS can't reach the dashboard session because they're different origins.
`services.hyperhive.{forge.domain,matrix.gatewayHost}` take the full hostname (`forge.darkest.space`, `git.example.com`) rather than a label that gets concatenated with hive-domain — mara on #754:9684 wanted operator control over the full shape, not a forced `<label>.<hive-domain>` pattern.
`services.hyperhive.{forge.domain,matrix.gatewayHost}` take the full hostname (`forge.darkest.space`, `git.example.com`) rather than a label that gets concatenated with hive-domain — operators want control over the full shape, not a forced `<label>.<hive-domain>` pattern.
## Tuning knobs
@ -69,29 +69,28 @@ Per-vhost timeouts + body-size limits live in the location blocks:
SSH for forge stays direct on `cfg.sshPort` — separate listener protocol, not HTTP-over-nginx.
## Per-agent unix-socket upstream (#784)
## Per-agent unix-socket upstream
Sub-agent `/agent/<name>/` upstreams flip from TCP loopback to a
unix-domain socket as each agent opts in. The mechanism:
1. **Agent side** (`hyperhive.web.useUnixSocket = true` in
`agent.nix`, #815). Sets `HIVE_WEB_SOCKET=/run/hive-agent/<name>/web.sock`
`agent.nix`). Sets `HIVE_WEB_SOCKET=/run/hive-agent/<name>/web.sock`
on the harness service env; `web_ui::serve` binds a `UnixListener`
at that path instead of TCP.
2. **Host side**. `hive-c0re` bind-mounts the per-agent subdir
(`/run/hive-agent/<name>/`) into the agent's container (#813). Dir
(`/run/hive-agent/<name>/`) into the agent's container. Dir
bind, not file bind — file bind-mounts don't survive the
harness's `unlink + bind(2)` cycle on socket replace. Per-agent
subdir keeps each agent's container blind to siblings'
sockets (mara on #800).
subdir keeps each agent's container blind to siblings' sockets.
3. **Marker gate**. After successful `bind_unix`, the harness drops
`<dir>/.bound` next to the socket. c0re's `agent_sockets::write`
filters its JSON map by marker presence — only agents whose
harness has actually bound the socket appear there (#784 atlas
gate). Without this filter, the gateway would `proxy_pass` to a
non-existent socket for every sub-agent that hasn't opted in yet.
4. **Gateway side** (#829). Reads `agent-sockets.json` at
request-handling time and routes `/agent/<name>/` to
harness has actually bound the socket appear there. Without this
filter, the gateway would `proxy_pass` to a non-existent socket
for every sub-agent that hasn't opted in yet.
4. **Gateway side**. Reads `agent-sockets.json` at request-handling
time and routes `/agent/<name>/` to
`http://unix:/run/hive-agent/<name>/web.sock:/`. Whole
`/run/hive-agent/` is bind-mounted read-only into the gateway
container so it can reach every published socket.
@ -103,7 +102,7 @@ one stat per agent per tick.
Transition: agents that haven't flipped `useUnixSocket = true` still
appear in `agent-ports.json` (the legacy TCP map) and the gateway
falls back to TCP for them. Step 4 of #784 will drop the TCP map +
falls back to TCP for them. A future cleanup will drop the TCP map +
the harness's TCP bind once every agent's flipped.
## Dashboard link shape (gateway vs direct)
@ -122,22 +121,11 @@ tracked by `forge.behindGateway`); `external`-kind links are
already absolute. See `docs/web-ui.md::Container row` for the
frontend-side derivation.
## Sequencing history
- #15 v0 (per-agent routing, #740) — first sub-app behind the gateway, JSON port table from c0re.
- #686 / #729 — Accept-header SPA fallback pattern.
- #749 / #754 — forge to sub-domain (mara: sub-domain over sub-path).
- #747 / #764 — matrix sub-domain vhost + `.well-known` delegation.
- #772 / #775 — fluffychat hops from `<hive>/matrix/` to `matrix.<hive>/`.
- #784 / #800 / #813 / #815 / #822 / #829 — sub-agent UI flips to unix-domain socket upstream, opt-in per agent.
Next-up tracked separately: #14 (container netns isolation), TLS (#594).
## Self-signed TLS (`selfSignedTls`)
On by default since #837. The gateway generates a self-signed RSA-4096 cert at first boot (10-year validity) and listens on `httpsPort` (default 443) on every vhost beside the plain-http `port` (default 80).
On by default. The gateway generates a self-signed RSA-4096 cert at first boot (10-year validity) and listens on `httpsPort` (default 443) on every vhost beside the plain-http `port` (default 80).
**Why on by default**: matrix-dart-sdk (FluffyChat's SDK) hardcodes `https://<host>/.well-known/matrix/client` for homeserver discovery and refuses to fall back to plain http. Without TLS the browser client cannot bootstrap (#837). For headless agent traffic and operator dashboard reach plain http is fine, so the http listen stays in parallel — operators can keep using `http://<hive>/` from the dashboard if they don't care about the cert prompt.
**Why on by default**: matrix-dart-sdk (FluffyChat's SDK) hardcodes `https://<host>/.well-known/matrix/client` for homeserver discovery and refuses to fall back to plain http. Without TLS the browser client cannot bootstrap. For headless agent traffic and operator dashboard reach plain http is fine, so the http listen stays in parallel — operators can keep using `http://<hive>/` from the dashboard if they don't care about the cert prompt.
**Cert shape**: subject CN = bare hive domain; subjectAltName covers `<hive>` + wildcard `*.<hive>` so all current and future sub-domain vhosts (matrix, forge, ...) validate under the same cert. Stored at `/var/lib/hive-gateway/tls/{cert,key}.pem` inside the gateway container (`ephemeral = false`, so persisted across container restart).
@ -156,25 +144,24 @@ On by default since #837. The gateway generates a self-signed RSA-4096 cert at f
`services.hyperhive.gateway.enable = false`**. With the gateway on
(default), it's the sole external entry point and proxies to
`127.0.0.1:<port>` internally — leaving the per-agent ports
firewall-open would defeat the single-front-door story (closes
#621).
firewall-open would defeat the single-front-door story.
`services.hyperhive.gateway.openFirewall = true` opens `port` plus
`httpsPort` when `selfSignedTls = true` (default). Operators who
flip `selfSignedTls = false` to front the gateway with a real
TLS-terminating reverse proxy on the host get only `port` opened.
Manager hashes into the same range since #753 (no more
The manager hashes into the same port range as sub-agents (no
"manager pinned at 8000" special case), so one range opening covers
every container.
The dashboard port (`cfg.dashboardPort`, default 7000) is *not*
listed in either case — since #652 it binds `127.0.0.1` only, so a
firewall hole would be a no-op. Remote dashboard access flows
through the gateway. Operators who opt out of the gateway lose
external dashboard reach by design — the surface is privileged
(approve / deny / destroy) and must not be exposed without a real
reverse proxy in front.
listed in either case — it binds `127.0.0.1` only, so a firewall
hole would be a no-op. Remote dashboard access flows through the
gateway. Operators who opt out of the gateway lose external
dashboard reach by design — the surface is privileged (approve /
deny / destroy) and must not be exposed without a real reverse
proxy in front.
## `HIVE_FORGE_URL`: loopback for in-cluster, sub-domain for the operator
@ -182,14 +169,13 @@ Agents poll `HIVE_FORGE_URL` for Forgejo notifications + run all
`hive-forge` calls against it. `hive-c0re.nix` pins this to
`http://127.0.0.1:<forge.httpPort>` for the in-cluster path: every
agent container shares the host's network namespace, so loopback
reaches the forge container directly with no DNS lookup needed
(closes #761).
reaches the forge container directly with no DNS lookup needed.
The post-#754 sub-domain default (`forge.<hive-domain>`) is for
**operator browsers + cross-host clients**, not in-cluster traffic.
Using the sub-domain URL inside agent containers would fail every
`hive-forge` invocation with "Name or service not known" — the
agent's nspawn doesn't have DNS for the external hostname.
The sub-domain default (`forge.<hive-domain>`) is for **operator
browsers + cross-host clients**, not in-cluster traffic. Using the
sub-domain URL inside agent containers would fail every `hive-forge`
invocation with "Name or service not known" — the agent's nspawn
doesn't have DNS for the external hostname.
## hive-forge container shape
@ -213,7 +199,7 @@ container.
## Per-agent error pages
`/agent/<name>/` requests hit two failure modes; both get static
HTML pages instead of nginx's default error chrome (#755):
HTML pages instead of nginx's default error chrome:
- **Agent not found** (`/agent/<unknown>/...`) — name isn't in
`agentPortsTable`. nginx's prefix match falls back to the bare
@ -238,8 +224,8 @@ palette (`#1e1e2e` bg, `#cdd6f4` text, `#cba6f7` heading). No
dependencies on the frontend dist — these pages render even when
hive-c0re itself is down.
Scope is intentionally narrow per mara on #755: "only for routes
already special cased in the nginx config". Other gateway routes
Scope is intentionally narrow: only routes already special-cased in
the nginx config get custom error pages. Other gateway routes
(forge / matrix / fluffychat) get nginx defaults — extending the
custom-error pattern there is a separate follow-up.

99
docs/matrix.md
View file

@ -34,34 +34,33 @@ Two distinct hostnames:
*irrevocably* in every `@user:<server_name>` and `!room:<server_name>`
identifier minted on this homeserver. Cannot be changed later
without abandoning every account and chat history. Defaults to the
bare `services.hyperhive.domain` per mara on #660; clients
auto-discover the actual API endpoint via the
`.well-known/matrix/{client,server}` routes the hive-gateway serves
at that domain.
bare `services.hyperhive.domain`; clients auto-discover the actual
API endpoint via the `.well-known/matrix/{client,server}` routes
the hive-gateway serves at that domain.
- **`gatewayHost`** — the API listener hostname, where the gateway's
matrix vhost proxies `/_matrix/*` to tuwunel. Defaults to
`matrix.<services.hyperhive.domain>` (sub-domain shape per mara on
#749:9609). Set to `null` to skip the gateway vhost (tuwunel stays
direct on `httpPort`).
`matrix.<services.hyperhive.domain>` (sub-domain shape). Set to
`null` to skip the gateway vhost (tuwunel stays direct on
`httpPort`).
**Breaking change** (#660): `serverName` used to default to
**Breaking change**: `serverName` used to default to
`matrix.${services.hyperhive.domain}`. Existing homeservers must set
the option explicitly to preserve their pre-#660 user / room IDs
the option explicitly to preserve their existing user / room IDs
before rebuilding. The default flipped because the bare hive-domain
makes for cleaner matrix IDs and `.well-known` delegation hides the
sub-domain from the user-facing identifier.
## Default-closed firewall
`openFirewall` defaults to `false` (#651, secure-by-default): the
`openFirewall` defaults to `false` (secure-by-default): the
homeserver is reachable from the host + every agent container via
loopback either way (shared netns), so the firewall hole only
matters for access from *outside* the host. Flip to `true` when
announcing the homeserver to other hives or when an external matrix
client needs to reach the client-server API directly.
**Breaking change** (#651): used to default to `true`. Operators
relying on external reach must add
**Breaking change**: used to default to `true`. Operators relying on
external reach must add
`services.hyperhive.matrix.openFirewall = true;` before rebuilding.
Federation port 8448 is intentionally not opened here — tuwunel
@ -82,10 +81,10 @@ see it. The agent only receives the resulting `access_token`.
writes when the file is missing or empty; always re-applies 0600
(normalises any 0640 / world-readable carry-over from
pre-LoadCredential deployments). This runs at activation time
(not first container start) to dodge the argus #565 race where
nspawn creates an empty file when the bind-mount target is
missing and tuwunel reads `registration_token_file=""` rejecting
every registration until next restart.
(not first container start) to dodge a race where nspawn creates
an empty file when the bind-mount target is missing and tuwunel
reads `registration_token_file=""`, rejecting every registration
until next restart.
2. **Read-only bind-mount** maps the host file into the tuwunel
container at the same path.
3. **systemd `LoadCredential=`** inside the container copies the
@ -93,8 +92,7 @@ see it. The agent only receives the resulting `access_token`.
`/run/credentials/tuwunel.service/registration_token`, owned by
tuwunel's dynamic user with mode `0400`, at service start. The
host file stays `root:root 0600` — no `chown :tuwunel` /
`chmod 0640` / GID-pin gymnastics required (per iris on #644
8043, dropping the shape #649 originally shipped with). Keeps
`chmod 0640` / GID-pin gymnastics required. Keeps
`DynamicUser = true` + `PrivateUsers = true` intact.
4. tuwunel's `registration_token_file` points at the credentials
path, not the original bind-mount path.
@ -104,7 +102,7 @@ see it. The agent only receives the resulting `access_token`.
matrix MCP client authenticates with that access_token and
never touches the shared registration token.
Initial rollout settings (#548):
Initial rollout settings:
- `allow_federation = true` at the protocol level so swarms can be
wired up later by extending `trustedServers` without a homeserver
@ -114,25 +112,25 @@ Initial rollout settings (#548):
engage). The absent
`yes_i_am_very_very_sure_…_open_registration_…` flag keeps the
server closed to anyone without the token.
- `allow_encryption = false` per operator call (#548). E2EE
re-enabling tracked at #551.
- `allow_encryption = false` per operator call; E2EE re-enabling is
deferred to a follow-up.
## Assertion rationale
Two `config.assertions` entries fail eval early rather than ship
surprising behaviour:
- **`hyperhiveDomain != null || cfg.serverName != null`** (mara on
#548) — `server_name` is embedded into every user / room ID
irrevocably; we refuse to spawn the homeserver with a bogus
server_name we can never change later.
- **`cfg.gatewayHost != ""`** (argus 🟡 on #764) — same footgun as
`forge.domain` (#754). Empty string renders `.<hive>`-shaped
garbage in both nginx `server_name` (treated as wildcard
catch-all, surprising) and `/etc/hosts` (invalid entry). `null`
is the right opt-out shape; empty string is rejected explicitly.
- **`hyperhiveDomain != null || cfg.serverName != null`** —
`server_name` is embedded into every user / room ID irrevocably;
we refuse to spawn the homeserver with a bogus `server_name` we
can never change later.
- **`cfg.gatewayHost != ""`** — same footgun as `forge.domain`:
empty string renders `.<hive>`-shaped garbage in both nginx
`server_name` (treated as wildcard catch-all, surprising) and
`/etc/hosts` (invalid entry). `null` is the right opt-out shape;
empty string is rejected explicitly.
## fluffychat-web build fixes (#685)
## fluffychat-web build fixes
`pkgs.fluffychat-web` ships from `flutter341.buildFlutterApplication`,
which has two upstream gaps for fluffychat's web target:
@ -163,37 +161,18 @@ Both fixed in `nix/modules/hive-matrix.nix` via two derivations:
Two non-obvious fixes from review history:
- **`make -C js`** instead of `cd js; make` (argus 🟡 on #697 v2)
— keeps the build-phase pwd at the source root so `installPhase`
doesn't have to know about the cd. Robust against future
reorders / `dontBuild`.
- **`make -C js`** instead of `cd js; make` — keeps the build-phase
pwd at the source root so `installPhase` doesn't have to know
about the cd. Robust against future reorders / `dontBuild`.
- **`web/native_executor.dart`** as a build-CWD-relative path,
*not* `$src/web/...` (#685 / #733 fixup) — `dart`'s
`package_config.json` walk-up needs to hit
`buildFlutterApplication`'s pub-get output (`.dart_tool/` in the
build CWD). Walking up from a read-only `$src/` store path finds
no `.dart_tool/` and errors with "Couldn't resolve the package
'matrix'". Confused two PRs.
*not* `$src/web/...` — `dart`'s `package_config.json` walk-up
needs to hit `buildFlutterApplication`'s pub-get output
(`.dart_tool/` in the build CWD). Walking up from a read-only
`$src/` store path finds no `.dart_tool/` and errors with
"Couldn't resolve the package 'matrix'".
Drop both derivations when nixpkgs's flutter builder grows worker
+ emcc support upstream.
Mount point is `matrix.<hive>/` (#772); upstream `--base-href "/"`
is correct at sub-domain root, no override.
## Sequencing history
- #548 — initial rollout (federation enabled, registration enabled,
E2EE disabled)
- #565 — first-boot empty-token race fix → activation-time token
generation
- #644 / iris 8043 / #649 — registration token ownership shape
(dropped chown/GID-pin; LoadCredential delivers as 0400 dynamic-user)
- #651 — `openFirewall` default flipped to `false`
- #660 — `serverName` default flipped to bare hive-domain (was
`matrix.<hive>`)
- #685 / #697 / #733 — fluffychat-web build fixes (Imaging emscripten,
native_executor dart worker, build-CWD path)
- #736 — fluffychat config.json inline JSON at sub-domain root
- #749 / #764 — gateway sub-domain shape verdict
- #772 / #775 — fluffychat hops from `<hive>/matrix/` to `matrix.<hive>/`
Mount point is `matrix.<hive>/`; upstream `--base-href "/"` is
correct at sub-domain root, no override.

49
docs/network.md
View file

@ -1,23 +1,21 @@
# hive-network
Host-side bridge + per-agent DNS resolver — the foundation that
makes [`#14` container netns isolation](http://localhost:3000/hyperhive/hyperhive/issues/14)
safe to land. Configured via `services.hyperhive.network.*`; off by
default during rollout.
makes container netns isolation safe to land. Configured via
`services.hyperhive.network.*`; off by default during rollout.
## Why ship before #14
## Why ship before netns isolation
Mara on #805#issuecomment-11541: "we need it before #14 so nothing
breaks when we switch over". If netns isolation lands first, agent
containers lose `/etc/resolv.conf` propagation from the host and DNS
breaks until a separate resolver is up. Inverting the sequence —
bridge + dnsmasq first, netns flip second — makes the flag day
boring: the resolver endpoint is already live, agents just discover
it via veth instead of shared netns.
If netns isolation lands first, agent containers lose
`/etc/resolv.conf` propagation from the host and DNS breaks until a
separate resolver is up. Inverting the sequence — bridge + dnsmasq
first, netns flip second — makes the flag day boring: the resolver
endpoint is already live, agents just discover it via veth instead
of shared netns.
## v1 vs v2
| feature | v1 (this PR) | v2 (after #14) |
| feature | v1 (this PR) | v2 (after netns isolation) |
|---|---|---|
| bridge interface | created on host, no slave NICs | per-agent veth pairs attach |
| dnsmasq binding | bridge IP (reachable via host loopback in shared netns) | bridge IP (reachable via veth in private netns) |
@ -27,18 +25,17 @@ it via veth instead of shared netns.
The `address` rules ship pointing at the bridge IP from v1 so the
DNS contract is fixed before any container actually depends on it
— minimises the things that flip on #14 day.
— minimises the things that flip on netns day.
## Container shape (where dnsmasq lives)
Co-located in the existing `hive-gateway` container per mara on
#805:10957 — single front-door for both DNS and HTTP, saves a
sibling container, single systemd-unit / state surface to monitor.
The gateway shares host netns (`privateNetwork = false`) so
dnsmasq's `bind-interfaces` listener on `bridgeIp` works without
any veth gymnastics today; when #14 flips agent containers to
private netns the binding doesn't change (it's still on the host's
bridge interface).
Co-located in the existing `hive-gateway` container — single
front-door for both DNS and HTTP, saves a sibling container, single
systemd-unit / state surface to monitor. The gateway shares host
netns (`privateNetwork = false`) so dnsmasq's `bind-interfaces`
listener on `bridgeIp` works without any veth gymnastics today; when
agent containers flip to private netns the binding doesn't change
(it's still on the host's bridge interface).
## Configuration
@ -98,16 +95,6 @@ agent containers.
interface only. Other interfaces stay closed. The hive resolver
isn't an external-facing service.
## Sequencing history
- mara on #805 (`comment-10957`): "can we put the resolver into the
gateway container?" — yes, this v1 does that.
- mara on #805 (`comment-11541`): "we need it before #14 so nothing
breaks when we switch over" — flipped the dependency direction;
v1 ships now, #14 flips containers later.
## Cross-references
- Issue [#805](http://localhost:3000/hyperhive/hyperhive/issues/805) — DNS resolver tracking
- Issue [#14](http://localhost:3000/hyperhive/hyperhive/issues/14) — netns isolation (downstream consumer)
- `docs/gateway.md` — vhost map + the gateway container's other duties

4
docs/web-ui.md
View file

@ -540,7 +540,9 @@ fetch entirely.
module sets when `services.hyperhive.gateway.enable = true`).
Gateway-on (default): `container` → `/agent/<name>/<url>` (same
origin, gateway proxies to the per-agent harness — TCP or
unix-domain per #784). Gateway-off (legacy / local dev):
unix-domain depending on the agent's `HIVE_WEB_SOCKET` opt-in,
see `docs/gateway.md::Per-agent unix-socket upstream`).
Gateway-off (legacy / local dev):
`container` → `http://<host>:<container.port>/<url>` (direct TCP
fallback). Forge links resolve against `http://<host>:3000`,
external links are already absolute. The same flag drives the