From dbf8829283e4f7c10270936be0d645f89169a6ee Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 17 Jan 2026 02:19:12 +0000 Subject: [PATCH] docs: clarify remote access setups --- docs/gateway/remote.md | 46 +++++++++++++++++++++++++++++++++++ docs/platforms/mac/remote.md | 7 +++++- docs/start/faq.md | 25 +++++++++++++++++++ docs/start/getting-started.md | 1 + 4 files changed, 78 insertions(+), 1 deletion(-) diff --git a/docs/gateway/remote.md b/docs/gateway/remote.md index c549abd68..4301ddfde 100644 --- 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). diff --git a/docs/platforms/mac/remote.md b/docs/platforms/mac/remote.md index e8b17dca3..7ff86d0bb 100644 --- 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. diff --git a/docs/start/faq.md b/docs/start/faq.md index c6633ee7f..0986b816b 100644 --- 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 + ``` + +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 diff --git a/docs/start/getting-started.md b/docs/start/getting-started.md index 2007b0604..4077eecac 100644 --- 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)