docs: clarify remote access setups

2026-01-17 02:19:12 +00:00
parent d5332ae29a
commit dbf8829283
4 changed files with 78 additions and 1 deletions
--- a/docs/gateway/remote.md
+++ b/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).
--- a/docs/platforms/mac/remote.md
+++ b/docs/platforms/mac/remote.md
@@ -6,7 +6,7 @@ read_when:
 # Remote Clawdbot (macOS ⇄ remote host)


-This flow lets the macOS app act as a full remote control for a Clawdbot gateway running on another host (desktop/server). All features—health checks, Voice Wake forwarding, and Web Chat—reuse the same remote SSH configuration from *Settings → General*.
+This flow lets the macOS app act as a full remote control for a Clawdbot gateway running on another host (desktop/server). It’s the app’s **Remote over SSH** (remote run) feature. All features—health checks, Voice Wake forwarding, and Web Chat—reuse the same remote SSH configuration from *Settings → General*.

 ## Modes
 - **Local (this Mac)**: Everything runs on the laptop. No SSH involved.
@@ -36,6 +36,11 @@ This flow lets the macOS app act as a full remote control for a Clawdbot gateway
 - The remote host needs the same TCC approvals as local (Automation, Accessibility, Screen Recording, Microphone, Speech Recognition, Notifications). Run onboarding on that machine to grant them once.
 - Nodes advertise their permission state via `node.list` / `node.describe` so agents know what’s available.

+## Security notes
+- Prefer loopback binds on the remote host and connect via SSH or Tailscale.
+- If you bind the Gateway to a non-loopback interface, require token/password auth.
+- See [Security](/gateway/security) and [Tailscale](/gateway/tailscale).
+
 ## WhatsApp login flow (remote)
 - Run `clawdbot channels login --verbose` **on the remote host**. Scan the QR with WhatsApp on your phone.
 - Re-run login on that host if auth expires. Health check will surface link problems.
--- a/docs/start/faq.md
+++ b/docs/start/faq.md
@@ -710,6 +710,31 @@ Telegram → Gateway → Agent → `node.*` → Node → Gateway → Telegram

 Nodes don’t see inbound provider traffic; they only receive bridge RPC calls.

+### How can my agent access my computer if the Gateway is hosted remotely?
+
+Short answer: **pair your computer as a node**. The Gateway runs elsewhere, but it can
+call `node.*` tools (screen, camera, system) on your local machine over the Bridge.
+
+Typical setup:
+1) Run the Gateway on the always‑on host (VPS/home server).
+2) Put the Gateway host + your computer on the same tailnet.
+3) Enable the bridge on the Gateway host:
+   ```json5
+   { bridge: { enabled: true, bind: "auto" } }
+   ```
+4) Open the macOS app locally and connect in **Remote over SSH** mode so it can tunnel
+   the bridge port and register as a node.
+5) Approve the node on the Gateway:
+   ```bash
+   clawdbot nodes pending
+   clawdbot nodes approve <requestId>
+   ```
+
+Security reminder: pairing a macOS node allows `system.run` on that machine. Only
+pair devices you trust, and review [Security](/gateway/security).
+
+Docs: [Nodes](/nodes), [Bridge protocol](/gateway/bridge-protocol), [macOS remote mode](/platforms/mac/remote), [Security](/gateway/security).
+
 ### Do nodes run a gateway daemon?

 No. Only **one gateway** should run per host unless you intentionally run isolated profiles (see [Multiple gateways](/gateway/multiple-gateways)). Nodes are peripherals that connect
--- a/docs/start/getting-started.md
+++ b/docs/start/getting-started.md
@@ -187,3 +187,4 @@ Health probes: `clawdbot health` (or `clawdbot status --deep`) asks the running
 - macOS menu bar app + voice wake: [macOS app](/platforms/macos)
 - iOS/Android nodes (Canvas/camera/voice): [Nodes](/nodes)
 - Remote access (SSH tunnel / Tailscale Serve): [Remote access](/gateway/remote) and [Tailscale](/gateway/tailscale)
+- Always-on / VPN setups: [Remote access](/gateway/remote), [exe.dev](/platforms/exe-dev), [Hetzner](/platforms/hetzner), [macOS remote](/platforms/mac/remote)