From 7f6a288bd31fd6c2c54f3098ecc36c877683f3a7 Mon Sep 17 00:00:00 2001 From: Benjamin Jesuiter Date: Thu, 15 Jan 2026 18:08:20 +0100 Subject: [PATCH] docs: clarify multi-gateway rescue bot guidance --- docs/cli/gateway.md | 2 +- docs/gateway/configuration.md | 2 +- docs/gateway/discovery.md | 2 +- docs/gateway/gateway-lock.md | 2 +- docs/gateway/index.md | 4 ++- docs/gateway/multiple-gateways.md | 34 ++++++++++++++++++++++++- docs/gateway/remote.md | 2 +- docs/index.md | 2 +- docs/start/faq.md | 2 +- src/cli/daemon-cli/status.print.ts | 2 +- src/commands/doctor-gateway-services.ts | 2 +- src/commands/gateway-status.ts | 2 +- 12 files changed, 46 insertions(+), 12 deletions(-) diff --git a/docs/cli/gateway.md b/docs/cli/gateway.md index b7140c4c6..5971491e7 100644 --- a/docs/cli/gateway.md +++ b/docs/cli/gateway.md @@ -78,7 +78,7 @@ clawdbot gateway health --url ws://127.0.0.1:18789 - your configured remote gateway (if set), and - localhost (loopback) **even if remote is configured**. -If multiple gateways are reachable, it prints all of them. Multiple gateways are supported when you use profiles for redundancy, but most installs still run a single gateway. +If multiple gateways are reachable, it prints all of them. Multiple gateways are supported when you use isolated profiles/ports (e.g., a rescue bot), but most installs still run a single gateway. ```bash clawdbot gateway status diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md index 72fad3653..5e3d280ed 100644 --- a/docs/gateway/configuration.md +++ b/docs/gateway/configuration.md @@ -2512,7 +2512,7 @@ Requires full Gateway restart: ### Multi-instance isolation -To run multiple gateways on one host, isolate per-instance state + config and use unique ports: +To run multiple gateways on one host (for redundancy or a rescue bot), isolate per-instance state + config and use unique ports: - `CLAWDBOT_CONFIG_PATH` (per-instance config) - `CLAWDBOT_STATE_DIR` (sessions/creds) - `agents.defaults.workspace` (memories) diff --git a/docs/gateway/discovery.md b/docs/gateway/discovery.md index 7ae5baf37..ebfc1d630 100644 --- a/docs/gateway/discovery.md +++ b/docs/gateway/discovery.md @@ -16,7 +16,7 @@ The design goal is to keep all network discovery/advertising in the **Node Gatew ## Terms -- **Gateway**: the single, long-running gateway process that owns state (sessions, pairing, node registry) and runs channels. +- **Gateway**: a single long-running gateway process that owns state (sessions, pairing, node registry) and runs channels. Most setups use one per host; isolated multi-gateway setups are possible. - **Gateway WS (loopback)**: the existing gateway WebSocket control endpoint on `127.0.0.1:18789`. - **Bridge (direct transport)**: a LAN/tailnet-facing endpoint owned by the gateway that allows authenticated clients/nodes to call a scoped subset of gateway methods. The bridge exists so the gateway can remain loopback-only. - **SSH transport (fallback)**: remote control by forwarding `127.0.0.1:18789` over SSH. diff --git a/docs/gateway/gateway-lock.md b/docs/gateway/gateway-lock.md index af3bf9e0c..a8af6afc5 100644 --- a/docs/gateway/gateway-lock.md +++ b/docs/gateway/gateway-lock.md @@ -9,7 +9,7 @@ read_when: Last updated: 2025-12-11 ## Why -- Ensure only one gateway instance runs per host. +- Ensure only one gateway instance runs per base port on the same host; additional gateways must use isolated profiles and unique ports. - Survive crashes/SIGKILL without leaving stale lock files. - Fail fast with a clear error when the control port is already occupied. diff --git a/docs/gateway/index.md b/docs/gateway/index.md index 29fbb6a72..1f60db40b 100644 --- a/docs/gateway/index.md +++ b/docs/gateway/index.md @@ -63,6 +63,8 @@ Install metadata is embedded in the service config: - `CLAWDBOT_SERVICE_KIND=gateway` - `CLAWDBOT_SERVICE_VERSION=` +Rescue-Bot Pattern: keep a second Gateway isolated with its own profile, state dir, workspace, and base port spacing. Full guide: [Rescue-bot guide](/gateway/multiple-gateways#rescue-bot-guide). + ### Dev profile (`--dev`) Fast path: run a fully-isolated dev instance (config/state/workspace) without touching your primary setup. @@ -205,7 +207,7 @@ Notes: - `daemon status` includes the last gateway error line when the service looks running but the port is closed. - `logs` tails the Gateway file log via RPC (no manual `tail`/`grep` needed). - If other gateway-like services are detected, the CLI warns unless they are Clawdbot profile services. - We still recommend **one gateway per machine** unless you need redundant profiles. + We still recommend **one gateway per machine** for most setups; use isolated profiles/ports for redundancy or a rescue bot. See [Multiple gateways](/gateway/multiple-gateways). - Cleanup: `clawdbot daemon uninstall` (current service) and `clawdbot doctor` (legacy migrations). - `daemon install` is a no-op when already installed; use `clawdbot daemon install --force` to reinstall (profile/env/path changes). diff --git a/docs/gateway/multiple-gateways.md b/docs/gateway/multiple-gateways.md index 27f596250..ffb72a639 100644 --- a/docs/gateway/multiple-gateways.md +++ b/docs/gateway/multiple-gateways.md @@ -6,7 +6,7 @@ read_when: --- # Multiple Gateways (same host) -Most setups should use one Gateway because a single Gateway can handle multiple messaging connections and agents. If you need stronger isolation or redundancy, run separate Gateways. Both are supported. +Most setups should use one Gateway because a single Gateway can handle multiple messaging connections and agents. If you need stronger isolation or redundancy (e.g., a rescue bot), run separate Gateways with isolated profiles/ports. ## Isolation checklist (required) - `CLAWDBOT_CONFIG_PATH` — per-instance config file @@ -37,6 +37,38 @@ clawdbot --profile main daemon install clawdbot --profile rescue daemon install ``` +## Rescue-bot guide + +Run a second Gateway on the same host with its own: +- profile/config +- state dir +- workspace +- base port (plus derived ports) + +This keeps the rescue bot isolated from the main bot so it can debug or apply config changes if the primary bot is down. + +Port spacing: leave at least 20 ports between base ports so the derived bridge/browser/canvas/CDP ports never collide. + +### How to install (rescue bot) + +```bash +# Main bot (existing or fresh, without --profile param) +# Runs on port 18789 + Chrome CDC/Canvas/... Ports +clawdbot onboard +clawdbot daemon install + +# Rescue bot (isolated profile + ports) +clawdbot --profile rescue onboard +# Notes: +# - workspace name will be postfixed with -rescue per default +# - Port should be at least 18789 + 20 Ports, +# better choose completely different base port, like 19789, +# - rest of the onboarding is the same as normal + +# To install the daemon (if not happened automatically during onboarding) +clawdbot --profile rescue daemon install +``` + ## Port mapping (derived) Base port = `gateway.port` (or `CLAWDBOT_GATEWAY_PORT` / `--port`). diff --git a/docs/gateway/remote.md b/docs/gateway/remote.md index 93f64ccb3..c549abd68 100644 --- a/docs/gateway/remote.md +++ b/docs/gateway/remote.md @@ -26,7 +26,7 @@ Flow example (Telegram → node): - Node returns the result; Gateway replies back out to Telegram. Notes: -- **Nodes do not run the gateway daemon.** Only one gateway should run per host. +- **Nodes do not run the gateway daemon.** Only one gateway should run per host unless you intentionally run isolated profiles (see [Multiple gateways](/gateway/multiple-gateways)). - macOS app “node mode” is just a node client over the Bridge. ## SSH tunnel (CLI + tools) diff --git a/docs/index.md b/docs/index.md index f2e7c8b2e..cf991bb0b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -66,7 +66,7 @@ Most operations flow through the **Gateway** (`clawdbot gateway`), a single long ## Network model -- **One Gateway per host**: it is the only process allowed to own the WhatsApp Web session. +- **One Gateway per host (recommended)**: it is the only process allowed to own the WhatsApp Web session. If you need a rescue bot or strict isolation, run multiple gateways with isolated profiles and ports; see [Multiple gateways](/gateway/multiple-gateways). - **Loopback-first**: Gateway WS defaults to `ws://127.0.0.1:18789`. - The wizard now generates a gateway token by default (even for loopback). - For Tailnet access, run `clawdbot gateway --bind tailnet --token ...` (token is required for non-loopback binds). diff --git a/docs/start/faq.md b/docs/start/faq.md index d92daf367..c92a2c236 100644 --- a/docs/start/faq.md +++ b/docs/start/faq.md @@ -665,7 +665,7 @@ Nodes don’t see inbound provider traffic; they only receive bridge RPC calls. ### Do nodes run a gateway daemon? -No. Only **one gateway** should run per host. Nodes are peripherals that connect +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 to the gateway (iOS/Android nodes, or macOS “node mode” in the menubar app). A full restart is required for `gateway`, `bridge`, `discovery`, and `canvasHost` changes. diff --git a/src/cli/daemon-cli/status.print.ts b/src/cli/daemon-cli/status.print.ts index 687b9a9ad..832d02e58 100644 --- a/src/cli/daemon-cli/status.print.ts +++ b/src/cli/daemon-cli/status.print.ts @@ -267,7 +267,7 @@ export function printDaemonStatus(status: DaemonStatus, opts: { json: boolean }) ); defaultRuntime.error( errorText( - "If you need multiple gateways (e.g., a recovery bot on the same host), isolate ports + config/state (see docs: /gateway#multiple-gateways-same-host).", + "If you need multiple gateways (e.g., a rescue bot on the same host), isolate ports + config/state (see docs: /gateway#multiple-gateways-same-host).", ), ); spacer(); diff --git a/src/commands/doctor-gateway-services.ts b/src/commands/doctor-gateway-services.ts index bf9c93747..db9610055 100644 --- a/src/commands/doctor-gateway-services.ts +++ b/src/commands/doctor-gateway-services.ts @@ -282,7 +282,7 @@ export async function maybeScanExtraGatewayServices(options: DoctorOptions) { [ "Recommendation: run a single gateway per machine for most setups.", "One gateway supports multiple agents.", - "If you need multiple gateways (e.g., a recovery bot on the same host), isolate ports + config/state (see docs: /gateway#multiple-gateways-same-host).", + "If you need multiple gateways (e.g., a rescue bot on the same host), isolate ports + config/state (see docs: /gateway#multiple-gateways-same-host).", ].join("\n"), "Gateway recommendation", ); diff --git a/src/commands/gateway-status.ts b/src/commands/gateway-status.ts index a36347b67..fede2a836 100644 --- a/src/commands/gateway-status.ts +++ b/src/commands/gateway-status.ts @@ -183,7 +183,7 @@ export async function gatewayStatusCommand( warnings.push({ code: "multiple_gateways", message: - "Unconventional setup: multiple reachable gateways detected. Usually one gateway per network is recommended unless you intentionally run isolated profiles, like a recovery bot (see docs: /gateway#multiple-gateways-same-host).", + "Unconventional setup: multiple reachable gateways detected. Usually one gateway per network is recommended unless you intentionally run isolated profiles, like a rescue bot (see docs: /gateway#multiple-gateways-same-host).", targetIds: reachable.map((p) => p.target.id), }); }