From 719981396942dce0d940edcba9981317c4974094 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 3 Jan 2026 11:46:58 +0100 Subject: [PATCH] docs: document gateway port configuration --- CHANGELOG.md | 1 + docs/clawdis-mac.md | 1 + docs/configuration.md | 19 +++++++++++++++++++ docs/faq.md | 5 +++-- docs/gateway.md | 19 +++++++++++++++++++ docs/index.md | 8 ++++++++ docs/remote.md | 4 +++- 7 files changed, 54 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 129af1420..361be2528 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ ### Docs - Skills: add Sheets/Docs examples to gog skill (#128) — thanks @mbelinky. - Skills: clarify bear-notes token + callback usage (#120) — thanks @tylerwince. +- Gateway: document port configuration + multi-instance isolation. ## 2.0.0-beta5 — 2026-01-03 diff --git a/docs/clawdis-mac.md b/docs/clawdis-mac.md index ec4285329..6117c35fa 100644 --- a/docs/clawdis-mac.md +++ b/docs/clawdis-mac.md @@ -28,6 +28,7 @@ Author: steipete · Status: draft spec · Date: 2025-12-20 ## Gateway + node bridge - The mac app runs the Gateway in **local** mode (unless configured remote). +- The gateway port is configurable via `gateway.port` or `CLAWDIS_GATEWAY_PORT` (default 18789). The mac app reads that value for launchd, probes, and remote SSH tunnels. - The mac app connects to the bridge as a **node** and advertises capabilities/commands. - Agent‑facing actions are exposed via `node.invoke` (no local control socket). diff --git a/docs/configuration.md b/docs/configuration.md index 40e932c82..c2d1186bc 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -615,11 +615,13 @@ Use `gateway.mode` to explicitly declare whether this machine should run the Gat Defaults: - mode: **unset** (treated as “do not auto-start”) - bind: `loopback` +- port: `18789` (single port for WS + HTTP) ```json5 { gateway: { mode: "local", // or "remote" + port: 18789, // WS + HTTP multiplex bind: "loopback", // controlUi: { enabled: true } // auth: { mode: "token", token: "your-token" } // token is for multi-machine CLI access @@ -630,6 +632,8 @@ Defaults: Notes: - `clawdis gateway` refuses to start unless `gateway.mode` is set to `local` (or you pass the override flag). +- `gateway.port` controls the single multiplexed port used for WebSocket + HTTP (control UI, hooks, A2UI). +- Precedence: `--port` > `CLAWDIS_GATEWAY_PORT` > `gateway.port` > default `18789`. Auth and Tailscale: - `gateway.auth.mode` sets the handshake requirements (`token` or `password`). @@ -659,6 +663,21 @@ Remote client defaults (CLI): } ``` +### Multi-instance isolation + +To run multiple gateways on one host, isolate per-instance state + config and use unique ports: +- `CLAWDIS_CONFIG_PATH` (per-instance config) +- `CLAWDIS_STATE_DIR` (sessions/creds/logs) +- `agent.workspace` (memories) +- `gateway.port` (unique per instance) + +Example: +```bash +CLAWDIS_CONFIG_PATH=~/.clawdis/a.json \ +CLAWDIS_STATE_DIR=~/.clawdis-a \ +clawdis gateway --port 19001 +``` + ### `hooks` (Gateway webhooks) Enable a simple HTTP webhook surface on the Gateway HTTP server. diff --git a/docs/faq.md b/docs/faq.md index 32334ba1f..2c0ff0b77 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -246,8 +246,9 @@ The intended design is **one Clawd, one identity**. Rather than running separate Why? A unified assistant knows your whole context. Your fitness coach knows when you've had a stressful work week. If you truly need full separation (different users, privacy boundaries), you'd need: -- Separate config directories -- Separate gateway ports +- Separate config + state directories (`CLAWDIS_CONFIG_PATH`, `CLAWDIS_STATE_DIR`) +- Separate agent workspaces (`agent.workspace`) +- Separate gateway ports (`gateway.port` / `--port`) - Separate phone numbers for WhatsApp (one number = one account) ### Can I have separate "threads" for different topics? diff --git a/docs/gateway.md b/docs/gateway.md index 88fac52aa..1f09e3c23 100644 --- a/docs/gateway.md +++ b/docs/gateway.md @@ -23,6 +23,7 @@ pnpm clawdis gateway --force pnpm gateway:watch ``` - Binds WebSocket control plane to `127.0.0.1:` (default 18789). +- The same port also serves HTTP (control UI, hooks, A2UI). Single-port multiplex. - Starts a Canvas file server by default on `canvasHost.port` (default `18793`), serving `http://:18793/__clawdis__/canvas/` from `~/clawd/canvas`. Disable with `canvasHost.enabled=false` or `CLAWDIS_SKIP_CANVAS_HOST=1`. - Logs to stdout; use launchd/systemd to keep it alive and rotate logs. - Pass `--verbose` to mirror debug logging (handshakes, req/res, events) from the log file into stdio when troubleshooting. @@ -30,6 +31,7 @@ pnpm gateway:watch - If you run under a supervisor (launchd/systemd/mac app child-process mode), a stop/restart typically sends **SIGTERM**; older builds may surface this as `pnpm` `ELIFECYCLE` exit code **143** (SIGTERM), which is a normal shutdown, not a crash. - **SIGUSR1** triggers an in-process restart (no external supervisor required). This is what the `clawdis_gateway` agent tool uses. - Optional shared secret: pass `--token ` or set `CLAWDIS_GATEWAY_TOKEN` to require clients to send `connect.params.auth.token`. +- Port precedence: `--port` > `CLAWDIS_GATEWAY_PORT` > `gateway.port` > default `18789`. ## Remote access - Tailscale/VPN preferred; otherwise SSH tunnel: @@ -39,6 +41,23 @@ pnpm gateway:watch - Clients then connect to `ws://127.0.0.1:18789` through the tunnel. - If a token is configured, clients must include it in `connect.params.auth.token` even over the tunnel. +## Multiple gateways (same host) + +Supported if you isolate state + config and use unique ports. + +Checklist per instance: +- unique `gateway.port` +- unique `CLAWDIS_CONFIG_PATH` +- unique `CLAWDIS_STATE_DIR` +- unique `agent.workspace` +- separate WhatsApp numbers (if using WA) + +Example: +```bash +CLAWDIS_CONFIG_PATH=~/.clawdis/a.json CLAWDIS_STATE_DIR=~/.clawdis-a clawdis gateway --port 19001 +CLAWDIS_CONFIG_PATH=~/.clawdis/b.json CLAWDIS_STATE_DIR=~/.clawdis-b clawdis gateway --port 19002 +``` + ## Protocol (operator view) - Mandatory first frame from client: `req {type:"req", id, method:"connect", params:{minProtocol,maxProtocol,client:{name,version,platform,deviceFamily?,modelIdentifier?,mode,instanceId}, caps, auth?, locale?, userAgent? } }`. - Gateway replies `res {type:"res", id, ok:true, payload:hello-ok }` (or `ok:false` with an error, then closes). diff --git a/docs/index.md b/docs/index.md index 81749e3bb..b7a9fd833 100644 --- a/docs/index.md +++ b/docs/index.md @@ -89,6 +89,14 @@ clawdis login clawdis gateway --port 18789 ``` +Multi-instance quickstart (optional): + +```bash +CLAWDIS_CONFIG_PATH=~/.clawdis/a.json \ +CLAWDIS_STATE_DIR=~/.clawdis-a \ +clawdis gateway --port 19001 +``` + Send a test message (requires a running Gateway): ```bash diff --git a/docs/remote.md b/docs/remote.md index 394c3e4dc..ec3ecb0c7 100644 --- a/docs/remote.md +++ b/docs/remote.md @@ -12,7 +12,7 @@ This repo supports “remote over SSH” by keeping a single Gateway (the master ## The core idea -- The Gateway WebSocket binds to **loopback**: `ws://127.0.0.1:18789`. +- 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). ## SSH tunnel (CLI + tools) @@ -27,6 +27,8 @@ With the tunnel up: - `clawdis health` and `clawdis status --deep` now reach the remote gateway via `ws://127.0.0.1:18789`. - `clawdis gateway {status,health,send,agent,call}` can also target the forwarded URL via `--url` when needed. +Note: replace `18789` with your configured `gateway.port` (or `--port`/`CLAWDIS_GATEWAY_PORT`). + ## CLI remote defaults You can persist a remote target so CLI commands use it by default: