# Network architecture

 iPhone / iPad / desktop browser
          │  HTTPS + WSS (TLS 1.3, certificate issued automatically by Caddy)
          ▼
 claude.spboucher.ai ── DNS A ──> BHS64 (OVH)  ── Caddy reverse proxy (WebSocket-capable)
          │                                       │
          │                       WireGuard tunnel (UDP 443, outbound from the LAN)
          ▼                                       ▼
                                   M5M36  wg1 ──> apps/server  0.0.0.0:8620   (Fastify)
                                                     │  unix socket, mode 0600, bearer token
                                                     ▼
                                                  apps/runtime  (no TCP listener)
                                                     │
                                                  tmux server ── claude / shell processes
                                                     │
                                            LAN (1 GbE) ── agentd (telemetry, read-only)
                                                        ── other nodes over SSH (only if allow-listed)
                                   PostgreSQL 17 on 127.0.0.1:5432 (local only)

# Exposure

• The only public entry point is Caddy on BHS64 (ports 80/443). The home LAN accepts no inbound connections: nodes dial out to the gateway over WireGuard. There is no port-forward on the home router.
• Caddy terminates TLS and forwards to M5M36:8620 over the tunnel. The server trusts X-Forwarded-For only from the tunnel gateway address and loopback.
• Port 8620 on M5M36 is also reachable from the LAN (the application firewall is not managed by this project). Every route requires authentication regardless of where the request comes from; the session cookie is Secure and bound to the public origin, so the LAN path offers no shortcut.
• The runtime (the only component able to spawn processes) has no network listener at all.
• PostgreSQL listens on loopback only.

# Why not a VPN-only design

The specification prefers a private-access architecture. The stated goal is access from any phone or browser without installing a client, and the cluster's SSH between nodes over Tailscale is blocked by ACL anyway. The chosen compromise: public HTTPS, but access requires a password and a second factor (passkey or TOTP), with brute-force lockouts, strict CSP, CSRF protection and Origin-checked WebSockets (see security.md). Putting Caddy basic-auth or an IP allowlist in front is possible later without code changes.

# Outbound

• api.anthropic.com / claude.ai (Claude Code itself), package registries, git remotes (gitsrv on the LAN).
• agentd on the LAN for cluster telemetry (bearer token stored server-side only).
• SSH to other nodes only for hosts listed in CR_EXEC_HOSTS (empty by default — see cluster-integration.md).