spb/claude-remote

1# Network architecture23```4 iPhone / iPad / desktop browser5          │  HTTPS + WSS (TLS 1.3, certificate issued automatically by Caddy)6          ▼7 claude.spboucher.ai ── DNS A ──> BHS64 (OVH)  ── Caddy reverse proxy (WebSocket-capable)8          │                                       │9          │                       WireGuard tunnel (UDP 443, outbound from the LAN)10          ▼                                       ▼11                                   M5M36  wg1 ──> apps/server  0.0.0.0:8620   (Fastify)12                                                     │  unix socket, mode 0600, bearer token13                                                     ▼14                                                  apps/runtime  (no TCP listener)15                                                     │16                                                  tmux server ── claude / shell processes17                                                     │18                                            LAN (1 GbE) ── agentd (telemetry, read-only)19                                                        ── other nodes over SSH (only if allow-listed)20                                   PostgreSQL 17 on 127.0.0.1:5432 (local only)21```2223## Exposure2425- The only public entry point is Caddy on BHS64 (ports 80/443). The home LAN accepts **no inbound connections**: nodes26  dial out to the gateway over WireGuard. There is no port-forward on the home router.27- Caddy terminates TLS and forwards to M5M36:8620 over the tunnel. The server trusts `X-Forwarded-For` only from the28  tunnel gateway address and loopback.29- Port 8620 on M5M36 is also reachable from the LAN (the application firewall is not managed by this project). Every30  route requires authentication regardless of where the request comes from; the session cookie is `Secure` and bound to31  the public origin, so the LAN path offers no shortcut.32- The runtime (the only component able to spawn processes) has no network listener at all.33- PostgreSQL listens on loopback only.3435## Why not a VPN-only design3637The specification prefers a private-access architecture. The stated goal is access from any phone or browser without38installing a client, and the cluster's SSH between nodes over Tailscale is blocked by ACL anyway. The chosen compromise:39public HTTPS, but access requires a password **and** a second factor (passkey or TOTP), with brute-force lockouts, strict40CSP, CSRF protection and Origin-checked WebSockets (see security.md). Putting Caddy basic-auth or an IP allowlist in front41is possible later without code changes.4243## Outbound4445- api.anthropic.com / claude.ai (Claude Code itself), package registries, git remotes (`gitsrv` on the LAN).46- agentd on the LAN for cluster telemetry (bearer token stored server-side only).47- SSH to other nodes only for hosts listed in `CR_EXEC_HOSTS` (empty by default — see cluster-integration.md).48