docs: clarify remote access setups

docs/gateway/remote.md

@@ -15,6 +15,39 @@ This repo supports “remote over SSH” by keeping a single Gateway (the master
 - The Gateway WebSocket binds to **loopback** on your configured port (defaults to 18789).
 - For remote use, you forward that loopback port over SSH (or use a tailnet/VPN and tunnel less).
 
+## Common VPN/tailnet setups (where the agent lives)
+
+Think of the **Gateway host** as “where the agent lives.” It owns sessions, auth profiles, channels, and state.
+Your laptop/desktop (and nodes) connect to that host.
+
+### 1) Always-on Gateway in your tailnet (VPS or home server)
+
+Run the Gateway on a persistent host and reach it via **Tailscale** or SSH.
+
+- **Best UX:** keep `gateway.bind: "loopback"` and use **Tailscale Serve** for the Control UI.
+- **Fallback:** keep loopback + SSH tunnel from any machine that needs access.
+- **Examples:** [exe.dev](/platforms/exe-dev) (easy VM) or [Hetzner](/platforms/hetzner) (production VPS).
+
+This is ideal when your laptop sleeps often but you want the agent always-on.
+
+### 2) Home desktop runs the Gateway, laptop is remote control
+
+The laptop does **not** run the agent. It connects remotely:
+
+- Use the macOS app’s **Remote over SSH** mode (Settings → General → “Clawdbot runs”).
+- The app opens and manages the tunnel, so WebChat + health checks “just work.”
+
+Runbook: [macOS remote access](/platforms/mac/remote).
+
+### 3) Laptop runs the Gateway, remote access from other machines
+
+Keep the Gateway local but expose it safely:
+
+- SSH tunnel to the laptop from other machines, or
+- Tailscale Serve the Control UI and keep the Gateway loopback-only.
+
+Guide: [Tailscale](/gateway/tailscale) and [Web overview](/web).
+
 ## Command flow (what runs where)
 
 One gateway daemon owns state + channels. Nodes are peripherals.
@@ -73,3 +106,16 @@ WebChat no longer uses a separate HTTP port. The SwiftUI chat UI connects direct
 The macOS menu bar app can drive the same setup end-to-end (remote status checks, WebChat, and Voice Wake forwarding).
 
 Runbook: [macOS remote access](/platforms/mac/remote).
+
+## Security rules (remote/VPN)
+
+Short version: **keep the Gateway loopback-only** unless you’re sure you need a bind.
+
+- **Loopback + SSH/Tailscale Serve** is the safest default (no public exposure).
+- **Non-loopback binds** (`lan`/`tailnet`/`auto`) must use auth tokens/passwords.
+- `gateway.remote.token` is **only** for remote CLI calls — it does **not** enable local auth.
+- **Tailscale Serve** can authenticate via identity headers when `gateway.auth.allowTailscale: true`.
+  Set it to `false` if you want tokens/passwords instead.
+- Treat `browser.controlUrl` like an admin API: tailnet-only + token auth.
+
+Deep dive: [Security](/gateway/security).