docs: document gateway port configuration
This commit is contained in:
Peter Steinberger
@@ -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
|
||||
|
||||
|
||||
@@ -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).
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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?
|
||||
|
||||
@@ -23,6 +23,7 @@ pnpm clawdis gateway --force
|
||||
pnpm gateway:watch
|
||||
```
|
||||
- Binds WebSocket control plane to `127.0.0.1:<port>` (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://<gateway-host>: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 <value>` 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).
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user