diff --git a/docs/matrix.md b/docs/matrix.md index 7e3dd972..65c89276 100644 --- a/docs/matrix.md +++ b/docs/matrix.md @@ -17,10 +17,9 @@ Same shape as [`gateway.md::hive-forge container shape`](gateway.md): operator already runs on the host — separate systemd namespace, separate state dir. - Container shares the host network namespace - (`privateNetwork = false`) so agents reach tuwunel at - `http://localhost:` without extra plumbing — the - nixos-container is here for state + systemd-unit isolation, not - network isolation. + (`privateNetwork = false`) for state + systemd-unit isolation. Agents + reach the homeserver at `matrix.` via the gateway (agents + run in private netns and can't access host loopback directly). - Persistent state at `/var/lib/nixos-containers/hive-matrix/var/lib/matrix-tuwunel/` survives container restart / host reboot. To wipe, destroy the @@ -52,9 +51,9 @@ sub-domain from the user-facing identifier. ## Default-closed firewall -`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 +`openFirewall` defaults to `false` (secure-by-default): the host +reaches the homeserver on loopback, and agent containers reach it +at `matrix.` via the gateway — 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. diff --git a/docs/turn-loop.md b/docs/turn-loop.md index d6e987b7..75cef004 100644 --- a/docs/turn-loop.md +++ b/docs/turn-loop.md @@ -462,11 +462,11 @@ Validated: must be an `http://` or `https://` URL or the empty string. **`hyperhive.matrix.url`** — homeserver URL used by `hive-matrix-daemon` when connecting via the matrix-sdk. Default -points at the in-host tuwunel (`localhost:8008`), reachable over the -host loopback in shared-netns mode. Override per-agent when an agent -should talk to a different homeserver — for example a remote hive's -tuwunel reached over a VPN, or an external Matrix server for a -federation-only agent. +(`localhost:8008`) is overridden by hive-c0re at deploy time to the +gateway-routed `matrix.` URL so isolated agents can reach the +homeserver. Override per-agent when an agent should talk to a +different homeserver — for example a remote hive's tuwunel reached +over a VPN, or an external Matrix server for a federation-only agent. ### Claude Code plugins diff --git a/nix/modules/hive-forge.nix b/nix/modules/hive-forge.nix index c59e4d9a..8178e196 100644 --- a/nix/modules/hive-forge.nix +++ b/nix/modules/hive-forge.nix @@ -56,8 +56,8 @@ let in { # Private Forgejo in a `hive-forge` nixos-container, shared host - # netns so agents reach it on loopback. State at - # `/var/lib/nixos-containers/hive-forge/var/lib/forgejo/` survives + # netns. Agents reach it at `forge.` via the gateway. State + # at `/var/lib/nixos-containers/hive-forge/var/lib/forgejo/` survives # restart. See `docs/gateway.md::hive-forge container shape`. # The internal forge is mandatory — it's the canonical store for the @@ -182,13 +182,12 @@ in example = true; description = '' Open `httpPort` + `sshPort` in the host firewall. Off by - default (secure-by-default): the forge is reachable from the - host + every agent container via `localhost` either way - (shared netns), so the firewall opens only matter for access - from outside the host. Flip to `true` when you want the - operator's browser / external git clients to hit the forge - directly. (The container shares host netns, so this is the - only firewall layer that matters.) + default (secure-by-default): agent containers reach the forge + at `forge.` via the gateway (not directly), and the + host reaches it on loopback — so the firewall opens only + matter for access from outside the host. Flip to `true` when + you want the operator's browser or external git clients to + hit the forge directly. **Breaking change**: this used to default to `true`. If you relied on the old default for external reach, add diff --git a/nix/modules/hive-matrix.nix b/nix/modules/hive-matrix.nix index ed120fac..b8a7378a 100644 --- a/nix/modules/hive-matrix.nix +++ b/nix/modules/hive-matrix.nix @@ -173,12 +173,12 @@ in example = true; description = '' Open `httpPort` in the host firewall. Off by default - (secure-by-default): the homeserver is reachable from the - host + every agent container via `localhost` either way - (shared netns), so the firewall open 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. + (secure-by-default): the host reaches the homeserver on + loopback, and agent containers reach it at `matrix.` + via the gateway — so the firewall open 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**: this used to default to `true`. If you relied on the old default for external reach, add diff --git a/nix/templates/harness-base.nix b/nix/templates/harness-base.nix index 1610fa6f..6fadb368 100644 --- a/nix/templates/harness-base.nix +++ b/nix/templates/harness-base.nix @@ -510,10 +510,12 @@ in example = "https://matrix.darkest.space"; description = '' Matrix homeserver URL the agent's `hive-matrix-daemon` connects - to. Default points at the in-host tuwunel (shared netns). - Override per-agent when an agent should talk to an external - homeserver instead (e.g. a federation-only setup or a remote - hive's tuwunel reached via a vpn). + to. At runtime hive-c0re forwards the isolation-aware URL + (`matrix.` via the gateway) so isolated agents reach + the homeserver without crossing host loopback. Override + per-agent when an agent should talk to an external homeserver + instead (e.g. a federation-only setup or a remote hive's + tuwunel reached via a vpn). ''; }; @@ -1516,8 +1518,7 @@ in # for the hive's own zones, so `forge.` stops resolving. We # disable resolvconf and tell dhcpcd not to touch resolv.conf (without # disabling dhcpcd itself, so the veth still gets its address); then - # whoever wrote resolv.conf last owns it: the nixos-container host-copy - # in shared netns, or the oneshot in isolated mode. (Same "take + # the hyperhive-isolated-dns oneshot owns resolv.conf. (Same "take # resolvconf out of the loop" approach the matrix container uses.) networking.resolvconf.enable = false; networking.dhcpcd.extraConfig = "nohook resolv.conf"; @@ -1528,11 +1529,11 @@ in # 127.0.0.53) is unreachable from a private netns and isn't # authoritative for the hive's own zones (forge. etc.). The # bridge dnsmasq (gateway IP) is. hive-priv drops the marker - # `/etc/hyperhive-bridge-dns` (containing the gateway IP) only when - # isolation is on, so this oneshot is inert in shared-netns mode — the - # same shared container toplevel does the right thing in both modes. - # Ordered before the first DNS consumer (tea-login) and the network - # targets so name resolution works for the very first turn. + # `/etc/hyperhive-bridge-dns` (containing the gateway IP) since + # isolation is always on; the oneshot reads it and rewrites + # resolv.conf on every boot. Ordered before the first DNS consumer + # (tea-login) and the network targets so name resolution works for + # the very first turn. systemd.services.hyperhive-isolated-dns = { description = "point resolv.conf at the hive bridge resolver (isolated containers)"; wantedBy = [ "multi-user.target" ]; @@ -1729,13 +1730,13 @@ in RUST_LOG = "info"; } # Homeserver URL: by default the daemon inherits the host-forwarded - # HIVE_MATRIX_URL (set isolation-aware by hive-c0re: `matrix.` - # via the gateway under private-netns isolation, loopback otherwise), - # falling back to the daemon's built-in localhost default if the - # forward is absent. A per-agent `hyperhive.matrix.url` override - # (non-default) is set unit-level so it wins over the forwarded value; - # at the default we deliberately DON'T set it so the forwarded - # isolation-aware value isn't shadowed. + # HIVE_MATRIX_URL (set by hive-c0re to `matrix.` via the + # gateway, since agents run in private netns and can't reach host + # loopback directly), falling back to the daemon's built-in + # localhost default if the forward is absent. A per-agent + # `hyperhive.matrix.url` override (non-default) is set unit-level + # so it wins over the forwarded value; at the default we + # deliberately DON'T set it so the forwarded value isn't shadowed. // lib.optionalAttrs (config.hyperhive.matrix.url != matrixUrlDefault) { HIVE_MATRIX_URL = config.hyperhive.matrix.url; }