From 747277d91420b268d9aaadfdcd0fb300a54c05ce Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Fri, 16 Jan 2026 01:59:14 +0000 Subject: [PATCH] fix: document macOS remote tunnels (#960) (thanks @kkarimi) --- CHANGELOG.md | 2 +- docs/platforms/macos.md | 26 ++++++++++++++++++++++++++ 2 files changed, 27 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ee5593a07..3fa630625 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -106,7 +106,7 @@ - macOS: format ConnectionsStore config to satisfy SwiftFormat lint. (#852) — thanks @mneves75. - macOS: pass auth token/password to dashboard URL for authenticated access. (#918) — thanks @rahthakor. - macOS: reuse launchd gateway auth and skip wizard when gateway config already exists. (#917) -- macOS: prefer the default bridge tunnel port in remote mode for node bridge connectivity; document SSH tunnel/bridge ports. (#960, fixes #865) — thanks @kkarimi. +- macOS: prefer the default bridge tunnel port in remote mode for node bridge connectivity; document macOS remote control + bridge tunnels. (#960, fixes #865) — thanks @kkarimi. - Apps: use canonical main session keys from gateway defaults across macOS/iOS/Android to avoid creating bare `main` sessions. - macOS: fix cron preview/testing payload to use `channel` key. (#867) — thanks @wes-davis. - Telegram: honor `channels.telegram.timeoutSeconds` for grammY API requests. (#863) — thanks @Snaver. diff --git a/docs/platforms/macos.md b/docs/platforms/macos.md index b6dc46e4e..111f9bcc7 100644 --- a/docs/platforms/macos.md +++ b/docs/platforms/macos.md @@ -110,6 +110,32 @@ Tip: compare against `pnpm clawdbot gateway discover --json` to see whether the macOS app’s discovery pipeline (NWBrowser + tailnet DNS‑SD fallback) differs from the Node CLI’s `dns-sd` based discovery. +## Remote connection plumbing (SSH tunnels) + +When the macOS app runs in **Remote** mode, it opens SSH tunnels so local UI +components can talk to a remote Gateway as if it were on localhost. There are +two independent tunnels: + +### Control tunnel (Gateway control/WebSocket port) +- **Purpose:** health checks, status, Web Chat, config, and other control-plane calls. +- **Local port:** the Gateway port (default `18789`), always stable. +- **Remote port:** the same Gateway port on the remote host. +- **Behavior:** no random local port; the app reuses an existing healthy tunnel + or restarts it if needed. +- **SSH shape:** `ssh -N -L :127.0.0.1:` with BatchMode + + ExitOnForwardFailure + keepalive options. + +### Node bridge tunnel (macOS node mode) +- **Purpose:** connect the macOS node to the Gateway **Bridge** protocol (TCP JSONL). +- **Remote port:** `gatewayPort + 1` (default `18790`), derived from the Gateway port. +- **Local port preference:** `CLAWDBOT_BRIDGE_PORT` or the default `18790`. +- **Behavior:** prefer the default bridge port for consistency; fall back to a + random local port if the preferred one is busy. The node then connects to the + resolved local port. + +For setup steps, see [macOS remote access](/platforms/mac/remote). For protocol +details, see [Bridge protocol](/gateway/bridge-protocol). + ## Related docs - [Gateway runbook](/gateway)