diff --git a/docs/cli/gateway.md b/docs/cli/gateway.md index 253130780..017718745 100644 --- a/docs/cli/gateway.md +++ b/docs/cli/gateway.md @@ -122,7 +122,7 @@ clawdbot gateway probe --ssh user@gateway-host Options: - `--ssh `: `user@host` or `user@host:port` (port defaults to `22`). - `--ssh-identity `: identity file. -- `--ssh-auto`: pick the first discovered bridge host as SSH target (LAN/WAB only). +- `--ssh-auto`: pick the first discovered gateway host as SSH target (LAN/WAB only). Config (optional, used as defaults): - `gateway.remote.sshTarget` diff --git a/docs/cli/index.md b/docs/cli/index.md index 1166d7508..6625fdf54 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -293,7 +293,7 @@ Options: - `--reset` (reset config + credentials + sessions + workspace before wizard) - `--non-interactive` - `--mode ` -- `--flow ` +- `--flow ` (manual is an alias for advanced) - `--auth-choice ` - `--token-provider ` (non-interactive; used with `--auth-choice token`) - `--token ` (non-interactive; used with `--auth-choice token`) @@ -791,11 +791,10 @@ All `cron` commands accept `--url`, `--token`, `--timeout`, `--expect-final`. [`clawdbot node`](/cli/node). Subcommands: -- `node run --host --port 18790` +- `node run --host --port 18789` - `node status` - `node install [--host ] [--port ] [--tls] [--tls-fingerprint ] [--node-id ] [--display-name ] [--runtime ] [--force]` - `node uninstall` -- `node run` - `node stop` - `node restart` diff --git a/docs/cli/node.md b/docs/cli/node.md index ee9893f87..72f8786b2 100644 --- a/docs/cli/node.md +++ b/docs/cli/node.md @@ -7,7 +7,7 @@ read_when: # `clawdbot node` -Run a **headless node host** that connects to the Gateway bridge and exposes +Run a **headless node host** that connects to the Gateway WebSocket and exposes `system.run` / `system.which` on this machine. ## Why use a node host? @@ -26,14 +26,14 @@ node host, so you can keep command access scoped and explicit. ## Run (foreground) ```bash -clawdbot node run --host --port 18790 +clawdbot node run --host --port 18789 ``` Options: -- `--host `: Gateway bridge host (default: `127.0.0.1`) -- `--port `: Gateway bridge port (default: `18790`) -- `--tls`: Use TLS for the bridge connection -- `--tls-fingerprint `: Pin the bridge certificate fingerprint +- `--host `: Gateway WebSocket host (default: `127.0.0.1`) +- `--port `: Gateway WebSocket port (default: `18789`) +- `--tls`: Use TLS for the gateway connection +- `--tls-fingerprint `: Expected TLS certificate fingerprint (sha256) - `--node-id `: Override node id (clears pairing token) - `--display-name `: Override the node display name @@ -42,14 +42,14 @@ Options: Install a headless node host as a user service. ```bash -clawdbot node install --host --port 18790 +clawdbot node install --host --port 18789 ``` Options: -- `--host `: Gateway bridge host (default: `127.0.0.1`) -- `--port `: Gateway bridge port (default: `18790`) -- `--tls`: Use TLS for the bridge connection -- `--tls-fingerprint `: Pin the bridge certificate fingerprint +- `--host `: Gateway WebSocket host (default: `127.0.0.1`) +- `--port `: Gateway WebSocket port (default: `18789`) +- `--tls`: Use TLS for the gateway connection +- `--tls-fingerprint `: Expected TLS certificate fingerprint (sha256) - `--node-id `: Override node id (clears pairing token) - `--display-name `: Override the node display name - `--runtime `: Service runtime (`node` or `bun`) @@ -65,6 +65,8 @@ clawdbot node restart clawdbot node uninstall ``` +Service commands accept `--json` for machine-readable output. + ## Pairing The first connection creates a pending node pair request on the Gateway. @@ -75,7 +77,8 @@ clawdbot nodes pending clawdbot nodes approve ``` -The node host stores its node id + token in `~/.clawdbot/node.json`. +The node host stores its node id, token, display name, and gateway connection info in +`~/.clawdbot/node.json`. ## Exec approvals diff --git a/docs/cli/nodes.md b/docs/cli/nodes.md index 4064006ee..11d149a53 100644 --- a/docs/cli/nodes.md +++ b/docs/cli/nodes.md @@ -14,6 +14,9 @@ Related: - Camera: [Camera nodes](/nodes/camera) - Images: [Image nodes](/nodes/images) +Common options: +- `--url`, `--token`, `--timeout`, `--json` + ## Common commands ```bash @@ -40,6 +43,11 @@ clawdbot nodes run --raw "git status" clawdbot nodes run --agent main --node --raw "git status" ``` +Invoke flags: +- `--params `: JSON object string (default `{}`). +- `--invoke-timeout `: node invoke timeout (default `15000`). +- `--idempotency-key `: optional idempotency key. + ### Exec-style defaults `nodes run` mirrors the model’s exec behavior (defaults + approvals): @@ -47,8 +55,14 @@ clawdbot nodes run --agent main --node --raw "git status" - Reads `tools.exec.*` (plus `agents.list[].tools.exec.*` overrides). - Uses exec approvals (`exec.approval.request`) before invoking `system.run`. - `--node` can be omitted when `tools.exec.node` is set. +- Requires a node that advertises `system.run` (macOS companion app or headless node host). Flags: +- `--cwd `: working directory. +- `--env `: env override (repeatable). +- `--command-timeout `: command timeout. +- `--invoke-timeout `: node invoke timeout (default `30000`). +- `--needs-screen-recording`: require screen recording permission. - `--raw `: run a shell string (`/bin/sh -lc` or `cmd.exe /c`). - `--agent `: agent-scoped approvals/allowlists (defaults to configured agent). - `--ask `, `--security `: overrides. diff --git a/docs/concepts/presence.md b/docs/concepts/presence.md index 4a1694657..83e71bf71 100644 --- a/docs/concepts/presence.md +++ b/docs/concepts/presence.md @@ -53,7 +53,6 @@ Clients can send richer periodic beacons via the `system-event` method. The mac app uses this to report host name, IP, and `lastInputSeconds`. ### 4) Node connects (role: node) - When a node connects over the Gateway WebSocket with `role: node`, the Gateway upserts a presence entry for that node (same flow as other WS clients). diff --git a/docs/concepts/session-tool.md b/docs/concepts/session-tool.md index c60187638..50281357b 100644 --- a/docs/concepts/session-tool.md +++ b/docs/concepts/session-tool.md @@ -19,7 +19,7 @@ Goal: small, hard-to-misuse tool set so agents can list sessions, fetch history, - Group chats use `agent:::group:` or `agent:::channel:` (pass the full key). - Cron jobs use `cron:`. - Hooks use `hook:` unless explicitly set. -- Node bridge uses `node-` unless explicitly set. +- Node sessions use `node-` unless explicitly set. `global` and `unknown` are reserved values and are never listed. If `session.scope = "global"`, we alias it to `main` for all tools so callers never see `global`. diff --git a/docs/concepts/session.md b/docs/concepts/session.md index 48c85af09..92f846135 100644 --- a/docs/concepts/session.md +++ b/docs/concepts/session.md @@ -52,7 +52,7 @@ the workspace is writable. See [Memory](/concepts/memory) and - Other sources: - Cron jobs: `cron:` - Webhooks: `hook:` (unless explicitly set by the hook) - - Node bridge runs: `node-` + - Node runs: `node-` ## Lifecycle - Reset policy: sessions are reused until they expire, and expiry is evaluated on the next inbound message. diff --git a/docs/concepts/typebox.md b/docs/concepts/typebox.md index 1aa9e54f2..1350d983b 100644 --- a/docs/concepts/typebox.md +++ b/docs/concepts/typebox.md @@ -46,7 +46,7 @@ Common methods + events: | Messaging | `send`, `poll`, `agent`, `agent.wait` | side-effects need `idempotencyKey` | | Chat | `chat.history`, `chat.send`, `chat.abort`, `chat.inject` | WebChat uses these | | Sessions | `sessions.list`, `sessions.patch`, `sessions.delete` | session admin | -| Nodes | `node.list`, `node.invoke`, `node.pair.*` | bridge + node actions | +| Nodes | `node.list`, `node.invoke`, `node.pair.*` | Gateway WS + node actions | | Events | `tick`, `presence`, `agent`, `chat`, `health`, `shutdown` | server push | Authoritative list lives in `src/gateway/server.ts` (`METHODS`, `EVENTS`). diff --git a/docs/debugging.md b/docs/debugging.md index b7f94d276..713b4acab 100644 --- a/docs/debugging.md +++ b/docs/debugging.md @@ -70,7 +70,7 @@ What this does: - `CLAWDBOT_PROFILE=dev` - `CLAWDBOT_STATE_DIR=~/.clawdbot-dev` - `CLAWDBOT_CONFIG_PATH=~/.clawdbot-dev/clawdbot.json` - - `CLAWDBOT_GATEWAY_PORT=19001` (bridge/canvas/browser shift accordingly) + - `CLAWDBOT_GATEWAY_PORT=19001` (browser/canvas shift accordingly) 2) **Dev bootstrap** (`gateway --dev`) - Writes a minimal config if missing (`gateway.mode=local`, bind loopback). diff --git a/docs/gateway/bonjour.md b/docs/gateway/bonjour.md index bb2c6de98..4b63eb0d2 100644 --- a/docs/gateway/bonjour.md +++ b/docs/gateway/bonjour.md @@ -7,7 +7,7 @@ read_when: # Bonjour / mDNS discovery Clawdbot uses Bonjour (mDNS / DNS‑SD) as a **LAN‑only convenience** to discover -an active Gateway bridge. It is best‑effort and does **not** replace SSH or +an active Gateway (WebSocket endpoint). It is best‑effort and does **not** replace SSH or Tailnet-based connectivity. ## Wide‑area Bonjour (Unicast DNS‑SD) over Tailscale @@ -31,7 +31,7 @@ browse both `local.` and `clawdbot.internal.` automatically. ```json5 { - bridge: { bind: "tailnet" }, // tailnet-only (recommended) + gateway: { bind: "tailnet" }, // tailnet-only (recommended) discovery: { wideArea: { enabled: true } } // enables clawdbot.internal DNS-SD publishing } ``` @@ -63,13 +63,13 @@ In the Tailscale admin console: Once clients accept tailnet DNS, iOS nodes can browse `_clawdbot-gw._tcp` in `clawdbot.internal.` without multicast. -### Bridge listener security (recommended) +### Gateway listener security (recommended) -The bridge port (default `18790`) is a plain TCP service. By default it binds to -`0.0.0.0`, which makes it reachable from any interface on the gateway host. +The Gateway WS port (default `18789`) binds to loopback by default. For LAN/tailnet +access, bind explicitly and keep auth enabled. For tailnet‑only setups: -- Set `bridge.bind: "tailnet"` in `~/.clawdbot/clawdbot.json`. +- Set `gateway.bind: "tailnet"` in `~/.clawdbot/clawdbot.json`. - Restart the Gateway (or restart the macOS menubar app). ## What advertises @@ -87,11 +87,12 @@ The Gateway advertises small non‑secret hints to make UI flows convenient: - `role=gateway` - `displayName=` - `lanHost=.local` -- `gatewayPort=` (informational; Gateway WS is usually loopback‑only) -- `bridgePort=` (only when bridge is enabled) +- `gatewayPort=` (Gateway WS + HTTP) +- `gatewayTls=1` (only when TLS is enabled) +- `gatewayTlsSha256=` (only when TLS is enabled and fingerprint is available) - `canvasPort=` (only when the canvas host is enabled; default `18793`) - `sshPort=` (defaults to 22 when not overridden) -- `transport=bridge` +- `transport=gateway` - `cliPath=` (optional; absolute path to a runnable `clawdbot` entrypoint) - `tailnetDns=` (optional hint when Tailnet is available) @@ -125,8 +126,8 @@ The Gateway writes a rolling log file (printed on startup as The iOS node uses `NWBrowser` to discover `_clawdbot-gw._tcp`. To capture logs: -- Settings → Bridge → Advanced → **Discovery Debug Logs** -- Settings → Bridge → Advanced → **Discovery Logs** → reproduce → **Copy** +- Settings → Gateway → Advanced → **Discovery Debug Logs** +- Settings → Gateway → Advanced → **Discovery Logs** → reproduce → **Copy** The log includes browser state transitions and result‑set changes. @@ -136,7 +137,7 @@ The log includes browser state transitions and result‑set changes. - **Multicast blocked**: some Wi‑Fi networks disable mDNS. - **Sleep / interface churn**: macOS may temporarily drop mDNS results; retry. - **Browse works but resolve fails**: keep machine names simple (avoid emojis or - punctuation), then restart the Gateway. The bridge instance name derives from + punctuation), then restart the Gateway. The service instance name derives from the host name, so overly complex names can confuse some resolvers. ## Escaped instance names (`\032`) @@ -150,9 +151,7 @@ sequences (e.g. spaces become `\032`). ## Disabling / configuration - `CLAWDBOT_DISABLE_BONJOUR=1` disables advertising. -- `CLAWDBOT_BRIDGE_ENABLED=0` disables the bridge listener (and the bridge beacon). -- `bridge.bind` / `bridge.port` in `~/.clawdbot/clawdbot.json` control bridge bind/port. -- `CLAWDBOT_BRIDGE_HOST` / `CLAWDBOT_BRIDGE_PORT` still work as back‑compat overrides. +- `gateway.bind` in `~/.clawdbot/clawdbot.json` controls the Gateway bind mode. - `CLAWDBOT_SSH_PORT` overrides the SSH port advertised in TXT. - `CLAWDBOT_TAILNET_DNS` publishes a MagicDNS hint in TXT. - `CLAWDBOT_CLI_PATH` overrides the advertised CLI path. diff --git a/docs/gateway/bridge-protocol.md b/docs/gateway/bridge-protocol.md index 47ff09b4d..a86155f87 100644 --- a/docs/gateway/bridge-protocol.md +++ b/docs/gateway/bridge-protocol.md @@ -14,6 +14,9 @@ should use the unified Gateway WebSocket protocol instead. If you are building an operator or node client, use the [Gateway protocol](/gateway/protocol). +**Note:** Current Clawdbot builds no longer ship the TCP bridge listener; this document is kept for historical reference. +Legacy `bridge.*` config keys are no longer part of the config schema. + ## Why we have both - **Security boundary**: the bridge exposes a small allowlist instead of the @@ -28,7 +31,7 @@ If you are building an operator or node client, use the - TCP, one JSON object per line (JSONL). - Optional TLS (when `bridge.tls.enabled` is true). -- Gateway owns the listener (default `18790`). +- Legacy default listener port was `18790` (current builds do not start a TCP bridge). When TLS is enabled, discovery TXT records include `bridgeTls=1` plus `bridgeTlsSha256` so nodes can pin the certificate. @@ -54,7 +57,7 @@ Gateway → Client: - `event`: chat updates for subscribed sessions - `ping` / `pong`: keepalive -Exact allowlist is enforced in `src/gateway/server-bridge.ts`. +Legacy allowlist enforcement lived in `src/gateway/server-bridge.ts` (removed). ## Exec lifecycle events diff --git a/docs/gateway/configuration-examples.md b/docs/gateway/configuration-examples.md index 91b40beac..a9bacccbf 100644 --- a/docs/gateway/configuration-examples.md +++ b/docs/gateway/configuration-examples.md @@ -568,5 +568,5 @@ Save to `~/.clawdbot/clawdbot.json` and you can DM the bot from that number. - If you set `dmPolicy: "open"`, the matching `allowFrom` list must include `"*"`. - Provider IDs differ (phone numbers, user IDs, channel IDs). Use the provider docs to confirm the format. -- Optional sections to add later: `web`, `browser`, `ui`, `bridge`, `discovery`, `canvasHost`, `talk`, `signal`, `imessage`. +- Optional sections to add later: `web`, `browser`, `ui`, `discovery`, `canvasHost`, `talk`, `signal`, `imessage`. - See [Providers](/channels/whatsapp) and [Troubleshooting](/gateway/troubleshooting) for deeper setup notes. diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md index a6e190d9e..a1a14298f 100644 --- a/docs/gateway/configuration.md +++ b/docs/gateway/configuration.md @@ -1690,7 +1690,7 @@ auto-compaction, instructing the model to store durable memories on disk (e.g. `memory/YYYY-MM-DD.md`). It triggers when the session token estimate crosses a soft threshold below the compaction limit. -Defaults: +Legacy defaults: - `memoryFlush.enabled`: `true` - `memoryFlush.softThresholdTokens`: `4000` - `memoryFlush.prompt` / `memoryFlush.systemPrompt`: built-in defaults with `NO_REPLY` @@ -2784,7 +2784,7 @@ Hot-applied (no full gateway restart): Requires full Gateway restart: - `gateway` (port/bind/auth/control UI/tailscale) -- `bridge` +- `bridge` (legacy) - `discovery` - `canvasHost` - `plugins` @@ -2802,7 +2802,7 @@ Convenience flags (CLI): - `clawdbot --dev …` → uses `~/.clawdbot-dev` + shifts ports from base `19001` - `clawdbot --profile …` → uses `~/.clawdbot-` (port via config/env/flags) -See [Gateway runbook](/gateway) for the derived port mapping (gateway/bridge/browser/canvas). +See [Gateway runbook](/gateway) for the derived port mapping (gateway/browser/canvas). See [Multiple gateways](/gateway/multiple-gateways) for browser/CDP port isolation details. Example: @@ -2921,7 +2921,7 @@ The Gateway serves a directory of HTML/CSS/JS over HTTP so iOS/Android nodes can Default root: `~/clawd/canvas` Default port: `18793` (chosen to avoid the clawd browser CDP port `18792`) -The server listens on the **bridge bind host** (LAN or Tailnet) so nodes can reach it. +The server listens on the **gateway bind host** (LAN or Tailnet) so nodes can reach it. The server: - serves files under `canvasHost.root` @@ -2950,9 +2950,13 @@ Disable with: - config: `canvasHost: { enabled: false }` - env: `CLAWDBOT_SKIP_CANVAS_HOST=1` -### `bridge` (node bridge server) +### `bridge` (legacy TCP bridge, removed) -The Gateway can expose a simple TCP bridge for nodes (iOS/Android), typically on port `18790`. +Current builds no longer include the TCP bridge listener; `bridge.*` config keys are ignored. +Nodes connect over the Gateway WebSocket. This section is kept for historical reference. + +Legacy behavior: +- The Gateway could expose a simple TCP bridge for nodes (iOS/Android), typically on port `18790`. Defaults: - enabled: `true` diff --git a/docs/gateway/discovery.md b/docs/gateway/discovery.md index 400107d2f..83f09c170 100644 --- a/docs/gateway/discovery.md +++ b/docs/gateway/discovery.md @@ -3,7 +3,7 @@ summary: "Node discovery and transports (Bonjour, Tailscale, SSH) for finding th read_when: - Implementing or changing Bonjour discovery/advertising - Adjusting remote connection modes (direct vs SSH) - - Designing bridge + pairing for remote nodes + - Designing node discovery + pairing for remote nodes --- # Discovery & transports @@ -17,17 +17,18 @@ The design goal is to keep all network discovery/advertising in the **Node Gatew ## Terms - **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. +- **Gateway WS (control plane)**: the WebSocket endpoint on `127.0.0.1:18789` by default; can be bound to LAN/tailnet via `gateway.bind`. +- **Direct WS transport**: a LAN/tailnet-facing Gateway WS endpoint (no SSH). - **SSH transport (fallback)**: remote control by forwarding `127.0.0.1:18789` over SSH. +- **Legacy TCP bridge (deprecated/removed)**: older node transport (see [Bridge protocol](/gateway/bridge-protocol)); no longer advertised for discovery. Protocol details: - [Gateway protocol](/gateway/protocol) -- [Bridge protocol](/gateway/bridge-protocol) +- [Bridge protocol (legacy)](/gateway/bridge-protocol) ## Why we keep both “direct” and SSH -- **Direct bridge** is the best UX on the same network and within a tailnet: +- **Direct WS** is the best UX on the same network and within a tailnet: - auto-discovery on LAN via Bonjour - pairing tokens + ACLs owned by the gateway - no shell access required; protocol surface can stay tight and auditable @@ -43,7 +44,7 @@ Protocol details: Bonjour is best-effort and does not cross networks. It is only used for “same LAN” convenience. Target direction: -- The **gateway** advertises its bridge via Bonjour. +- The **gateway** advertises its WS endpoint via Bonjour. - Clients browse and show a “pick a gateway” list, then store the chosen endpoint. Troubleshooting and beacon details: [Bonjour](/gateway/bonjour). @@ -56,19 +57,19 @@ Troubleshooting and beacon details: [Bonjour](/gateway/bonjour). - `role=gateway` - `lanHost=.local` - `sshPort=22` (or whatever is advertised) - - `gatewayPort=18789` (loopback WS port; informational) - - `bridgePort=18790` (when bridge is enabled) + - `gatewayPort=18789` (Gateway WS + HTTP) + - `gatewayTls=1` (only when TLS is enabled) + - `gatewayTlsSha256=` (only when TLS is enabled and fingerprint is available) - `canvasPort=18793` (default canvas host port; serves `/__clawdbot__/canvas/`) - `cliPath=` (optional; absolute path to a runnable `clawdbot` entrypoint or binary) - `tailnetDns=` (optional hint; auto-detected when Tailscale is available) Disable/override: - `CLAWDBOT_DISABLE_BONJOUR=1` disables advertising. -- `CLAWDBOT_BRIDGE_ENABLED=0` disables the bridge listener. -- `bridge.bind` / `bridge.port` in `~/.clawdbot/clawdbot.json` control bridge bind/port (preferred). -- `CLAWDBOT_BRIDGE_HOST` / `CLAWDBOT_BRIDGE_PORT` still work as a back-compat override when `bridge.bind` / `bridge.port` are not set. -- `CLAWDBOT_SSH_PORT` overrides the SSH port advertised in the bridge beacon (defaults to 22). -- `CLAWDBOT_TAILNET_DNS` publishes a `tailnetDns` hint (MagicDNS) in the bridge beacon (auto-detected if unset). +- `gateway.bind` in `~/.clawdbot/clawdbot.json` controls the Gateway bind mode. +- `CLAWDBOT_SSH_PORT` overrides the SSH port advertised in TXT (defaults to 22). +- `CLAWDBOT_TAILNET_DNS` publishes a `tailnetDns` hint (MagicDNS). +- `CLAWDBOT_CLI_PATH` overrides the advertised CLI path. ### 2) Tailnet (cross-network) @@ -97,13 +98,13 @@ Recommended client behavior: The gateway is the source of truth for node/client admission. - Pairing requests are created/approved/rejected in the gateway (see [Gateway pairing](/gateway/pairing)). -- The bridge enforces: +- The gateway enforces: - auth (token / keypair) - - scopes/ACLs (bridge is not a raw proxy to every gateway method) + - scopes/ACLs (the gateway is not a raw proxy to every method) - rate limits ## Responsibilities by component -- **Gateway**: advertises discovery beacons, owns pairing decisions, runs the bridge listener. +- **Gateway**: advertises discovery beacons, owns pairing decisions, and hosts the WS endpoint. - **macOS app**: helps you pick a gateway, shows pairing prompts, and uses SSH only as a fallback. -- **iOS/Android nodes**: browse Bonjour as a convenience and connect via the paired bridge. +- **iOS/Android nodes**: browse Bonjour as a convenience and connect to the paired Gateway WS. diff --git a/docs/gateway/index.md b/docs/gateway/index.md index 50552bcc5..0725210e8 100644 --- a/docs/gateway/index.md +++ b/docs/gateway/index.md @@ -82,14 +82,12 @@ Defaults (can be overridden via env/flags/config): - `CLAWDBOT_STATE_DIR=~/.clawdbot-dev` - `CLAWDBOT_CONFIG_PATH=~/.clawdbot-dev/clawdbot.json` - `CLAWDBOT_GATEWAY_PORT=19001` (Gateway WS + HTTP) -- `bridge.port=19002` (derived: `gateway.port+1`) - `browser.controlUrl=http://127.0.0.1:19003` (derived: `gateway.port+2`) - `canvasHost.port=19005` (derived: `gateway.port+4`) - `agents.defaults.workspace` default becomes `~/clawd-dev` when you run `setup`/`onboard` under `--dev`. Derived ports (rules of thumb): - Base port = `gateway.port` (or `CLAWDBOT_GATEWAY_PORT` / `--port`) -- `bridge.port = base + 1` (or `CLAWDBOT_BRIDGE_PORT` / config override) - `browser.controlUrl port = base + 2` (or `CLAWDBOT_BROWSER_CONTROL_URL` / config override) - `canvasHost.port = base + 4` (or `CLAWDBOT_CANVAS_HOST_PORT` / config override) - Browser profile CDP ports auto-allocate from `browser.controlPort + 9 .. + 108` (persisted per profile). @@ -114,7 +112,7 @@ CLAWDBOT_CONFIG_PATH=~/.clawdbot/b.json CLAWDBOT_STATE_DIR=~/.clawdbot-b clawdbo ``` ## Protocol (operator view) -- Full docs: [Gateway protocol](/gateway/protocol) and [Bridge protocol](/gateway/bridge-protocol). +- Full docs: [Gateway protocol](/gateway/protocol) and [Bridge protocol (legacy)](/gateway/bridge-protocol). - Mandatory first frame from client: `req {type:"req", id, method:"connect", params:{minProtocol,maxProtocol,client:{id,displayName?,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). - After handshake: @@ -130,7 +128,7 @@ CLAWDBOT_CONFIG_PATH=~/.clawdbot/b.json CLAWDBOT_STATE_DIR=~/.clawdbot-b clawdbo - `system-event` — post a presence/system note (structured). - `send` — send a message via the active channel(s). - `agent` — run an agent turn (streams events back on same connection). -- `node.list` — list paired + currently-connected bridge nodes (includes `caps`, `deviceFamily`, `modelIdentifier`, `paired`, `connected`, and advertised `commands`). +- `node.list` — list paired + currently-connected nodes (includes `caps`, `deviceFamily`, `modelIdentifier`, `paired`, `connected`, and advertised `commands`). - `node.describe` — describe a node (capabilities + supported `node.invoke` commands; works for paired nodes and for currently-connected unpaired nodes). - `node.invoke` — invoke a command on a node (e.g. `canvas.*`, `camera.*`). - `node.pair.*` — pairing lifecycle (`request`, `list`, `approve`, `reject`, `verify`). diff --git a/docs/gateway/multiple-gateways.md b/docs/gateway/multiple-gateways.md index b1bbd7d04..b444290f6 100644 --- a/docs/gateway/multiple-gateways.md +++ b/docs/gateway/multiple-gateways.md @@ -13,7 +13,7 @@ Most setups should use one Gateway because a single Gateway can handle multiple - `CLAWDBOT_STATE_DIR` — per-instance sessions, creds, caches - `agents.defaults.workspace` — per-instance workspace root - `gateway.port` (or `--port`) — unique per instance -- Derived ports (bridge/browser/canvas) must not overlap +- Derived ports (browser/canvas) must not overlap If these are shared, you will hit config races and port conflicts. @@ -47,7 +47,7 @@ Run a second Gateway on the same host with its own: 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. +Port spacing: leave at least 20 ports between base ports so the derived browser/canvas/CDP ports never collide. ### How to install (rescue bot) @@ -73,7 +73,6 @@ clawdbot --profile rescue gateway install Base port = `gateway.port` (or `CLAWDBOT_GATEWAY_PORT` / `--port`). -- `bridge.port = base + 1` - `browser.controlUrl port = base + 2` - `canvasHost.port = base + 4` - Browser profile CDP ports auto-allocate from `browser.controlPort + 9 .. + 108` diff --git a/docs/gateway/pairing.md b/docs/gateway/pairing.md index 2d9626418..5a5e553b3 100644 --- a/docs/gateway/pairing.md +++ b/docs/gateway/pairing.md @@ -19,12 +19,12 @@ Only clients that explicitly call `node.pair.*` use this flow. - **Pending request**: a node asked to join; requires approval. - **Paired node**: approved node with an issued auth token. -- **Bridge**: transport endpoint only; it forwards requests but does not decide - membership. +- **Transport**: the Gateway WS endpoint forwards requests but does not decide + membership. (Legacy TCP bridge support is deprecated/removed.) ## How pairing works -1. A node connects to the bridge and requests pairing. +1. A node connects to the Gateway WS and requests pairing. 2. The Gateway stores a **pending request** and emits `node.pair.requested`. 3. You approve or reject the request (CLI or UI). 4. On approval, the Gateway issues a **new token** (tokens are rotated on re‑pair). @@ -85,9 +85,8 @@ Security notes: - Tokens are secrets; treat `paired.json` as sensitive. - Rotating a token requires re-approval (or deleting the node entry). -## Bridge behavior +## Transport behavior -- The bridge is **transport only**; it does not store membership. +- The transport is **stateless**; it does not store membership. - If the Gateway is offline or pairing is disabled, nodes cannot pair. -- If the bridge is running but the Gateway is in remote mode, pairing still - happens against the remote Gateway’s store. +- If the Gateway is in remote mode, pairing still happens against the remote Gateway’s store. diff --git a/docs/gateway/tailscale.md b/docs/gateway/tailscale.md index 10477f90c..b7e657acc 100644 --- a/docs/gateway/tailscale.md +++ b/docs/gateway/tailscale.md @@ -94,8 +94,9 @@ clawdbot gateway --tailscale funnel --auth password or `tailscale funnel` configuration on shutdown. - `gateway.bind: "tailnet"` is a direct Tailnet bind (no HTTPS, no Serve/Funnel). - `gateway.bind: "auto"` prefers loopback; use `tailnet` if you want Tailnet-only. -- Serve/Funnel only expose the **Gateway control UI + WS**. Node **bridge** traffic - uses the separate bridge port (default `18790`) and is **not** proxied by Serve. +- Serve/Funnel only expose the **Gateway control UI + WS**. Nodes connect over + the same Gateway WS endpoint, so Serve can work for node access. (Legacy TCP + bridge traffic is not proxied by Serve.) ## Browser control server (remote Gateway + local browser) diff --git a/docs/index.md b/docs/index.md index 088522bfa..00a8841fb 100644 --- a/docs/index.md +++ b/docs/index.md @@ -49,7 +49,7 @@ WhatsApp / Telegram / Discord ▼ ┌───────────────────────────┐ │ Gateway │ ws://127.0.0.1:18789 (loopback-only) - │ (single source) │ tcp://0.0.0.0:18790 (Bridge) + │ (single source) │ │ │ http://:18793 │ │ /__clawdbot__/canvas/ (Canvas host) └───────────┬───────────────┘ @@ -58,8 +58,8 @@ WhatsApp / Telegram / Discord ├─ CLI (clawdbot …) ├─ Chat UI (SwiftUI) ├─ macOS app (Clawdbot.app) - ├─ iOS node via Bridge + pairing - └─ Android node via Bridge + pairing + ├─ iOS node via Gateway WS + pairing + └─ Android node via Gateway WS + pairing ``` Most operations flow through the **Gateway** (`clawdbot gateway`), a single long-running process that owns channel connections and the WebSocket control plane. @@ -70,7 +70,7 @@ Most operations flow through the **Gateway** (`clawdbot gateway`), a single long - **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). -- **Bridge for nodes**: optional LAN/tailnet-facing bridge on `tcp://0.0.0.0:18790` for paired nodes (Bonjour-discoverable). +- **Nodes**: connect to the Gateway WebSocket (LAN/tailnet/SSH as needed); legacy TCP bridge is deprecated/removed. - **Canvas host**: HTTP file server on `canvasHost.port` (default `18793`), serving `/__clawdbot__/canvas/` for node WebViews; see [Gateway configuration](/gateway/configuration) (`canvasHost`). - **Remote use**: SSH tunnel or tailnet/VPN; see [Remote access](/gateway/remote) and [Discovery](/gateway/discovery). diff --git a/docs/network.md b/docs/network.md index 94e43e85d..155727667 100644 --- a/docs/network.md +++ b/docs/network.md @@ -36,7 +36,7 @@ Local trust: - [Remote access (SSH)](/gateway/remote) - [Tailscale](/gateway/tailscale) -## Nodes + bridge +## Nodes + transports - [Nodes overview](/nodes) - [Bridge protocol (legacy nodes)](/gateway/bridge-protocol) diff --git a/docs/nodes/camera.md b/docs/nodes/camera.md index 37d61f0fa..6b0f408d3 100644 --- a/docs/nodes/camera.md +++ b/docs/nodes/camera.md @@ -138,7 +138,7 @@ Notes: ## Safety + practical limits - Camera and microphone access trigger the usual OS permission prompts (and require usage strings in Info.plist). -- Video clips are capped (currently `<= 60s`) to avoid oversized bridge payloads (base64 overhead + message limits). +- Video clips are capped (currently `<= 60s`) to avoid oversized node payloads (base64 overhead + message limits). ## macOS screen video (OS-level) diff --git a/docs/nodes/index.md b/docs/nodes/index.md index 80e1015fc..0f3055567 100644 --- a/docs/nodes/index.md +++ b/docs/nodes/index.md @@ -10,7 +10,7 @@ read_when: A **node** is a companion device (macOS/iOS/Android/headless) that connects to the Gateway **WebSocket** (same port as operators) with `role: "node"` and exposes a command surface (e.g. `canvas.*`, `camera.*`, `system.*`) via `node.invoke`. Protocol details: [Gateway protocol](/gateway/protocol). -Legacy transport: [Bridge protocol](/gateway/bridge-protocol) (TCP JSONL; for older node clients only). +Legacy transport: [Bridge protocol](/gateway/bridge-protocol) (TCP JSONL; deprecated/removed for current nodes). macOS can also run in **node mode**: the menubar app connects to the Gateway’s WS server and exposes its local canvas/camera commands as a node (so `clawdbot nodes …` works against this Mac). @@ -61,7 +61,7 @@ clawdbot node run --host --port 18789 --display-name "Build Node" ```bash clawdbot node install --host --port 18789 --display-name "Build Node" -clawdbot node start +clawdbot node restart ``` ### Pair + name @@ -243,6 +243,7 @@ Notes: - `system.notify` respects notification permission state on the macOS app. - `system.run` supports `--cwd`, `--env KEY=VAL`, `--command-timeout`, and `--needs-screen-recording`. - `system.notify` supports `--priority ` and `--delivery `. +- macOS nodes drop `PATH` overrides; headless node hosts only accept `PATH` when it prepends the node host PATH. - On macOS node mode, `system.run` is gated by exec approvals in the macOS app (Settings → Exec approvals). Ask/allowlist/full behave the same as the headless node host; denied prompts return `SYSTEM_RUN_DENIED`. - On headless node host, `system.run` is gated by exec approvals (`~/.clawdbot/exec-approvals.json`). @@ -285,20 +286,34 @@ or for running a minimal node alongside a server. Start it: ```bash -clawdbot node run --host --port 18790 +clawdbot node run --host --port 18789 ``` Notes: - Pairing is still required (the Gateway will show a node approval prompt). -- The node host stores its node id + pairing token in `~/.clawdbot/node.json`. +- The node host stores its node id, token, display name, and gateway connection info in `~/.clawdbot/node.json`. - Exec approvals are enforced locally via `~/.clawdbot/exec-approvals.json` (see [Exec approvals](/tools/exec-approvals)). - On macOS, the headless node host prefers the companion app exec host when reachable and falls back to local execution if the app is unavailable. Set `CLAWDBOT_NODE_EXEC_HOST=app` to require the app, or `CLAWDBOT_NODE_EXEC_FALLBACK=0` to disable fallback. +<<<<<<< HEAD - Add `--tls` / `--tls-fingerprint` when the Gateway WS uses TLS. +||||||| parent of 2ab821adc (docs: align node transport with gateway ws) +- Add `--tls` / `--tls-fingerprint` when the bridge requires TLS. +======= +- Add `--tls` / `--tls-fingerprint` when the gateway requires TLS. +>>>>>>> 2ab821adc (docs: align node transport with gateway ws) ## Mac node mode +<<<<<<< HEAD - The macOS menubar app connects to the Gateway WS server as a node (so `clawdbot nodes …` works against this Mac). - In remote mode, the app opens an SSH tunnel for the Gateway port and connects to `localhost`. +||||||| parent of 2ab821adc (docs: align node transport with gateway ws) +- The macOS menubar app connects to the Gateway bridge as a node (so `clawdbot nodes …` works against this Mac). +- In remote mode, the app opens an SSH tunnel for the bridge port and connects to `localhost`. +======= +- The macOS menubar app connects to the Gateway WebSocket as a node (so `clawdbot nodes …` works against this Mac). +- In remote mode, the app opens an SSH tunnel for the gateway port and connects to `localhost`. +>>>>>>> 2ab821adc (docs: align node transport with gateway ws) diff --git a/docs/nodes/voicewake.md b/docs/nodes/voicewake.md index 49a19b111..224e3b8b9 100644 --- a/docs/nodes/voicewake.md +++ b/docs/nodes/voicewake.md @@ -41,7 +41,7 @@ Notes: Who receives it: - All WebSocket clients (macOS app, WebChat, etc.) -- All connected bridge nodes (iOS/Android), and also on node connect as an initial “current state” push. +- All connected nodes (iOS/Android), and also on node connect as an initial “current state” push. ## Client behavior @@ -53,9 +53,9 @@ Who receives it: ### iOS node - Uses the global list for `VoiceWakeManager` trigger detection. -- Editing Wake Words in Settings calls `voicewake.set` (over the bridge) and also keeps local wake-word detection responsive. +- Editing Wake Words in Settings calls `voicewake.set` (over the Gateway WS) and also keeps local wake-word detection responsive. ### Android node - Exposes a Wake Words editor in Settings. -- Calls `voicewake.set` over the bridge so edits sync everywhere. +- Calls `voicewake.set` over the Gateway WS so edits sync everywhere. diff --git a/docs/platforms/hetzner.md b/docs/platforms/hetzner.md index 8f9de7bc0..1a3c2f836 100644 --- a/docs/platforms/hetzner.md +++ b/docs/platforms/hetzner.md @@ -129,7 +129,6 @@ CLAWDBOT_IMAGE=clawdbot:latest CLAWDBOT_GATEWAY_TOKEN=change-me-now CLAWDBOT_GATEWAY_BIND=lan CLAWDBOT_GATEWAY_PORT=18789 -CLAWDBOT_BRIDGE_PORT=18790 CLAWDBOT_CONFIG_DIR=/root/.clawdbot CLAWDBOT_WORKSPACE_DIR=/root/clawd @@ -166,7 +165,6 @@ services: - TERM=xterm-256color - CLAWDBOT_GATEWAY_BIND=${CLAWDBOT_GATEWAY_BIND} - CLAWDBOT_GATEWAY_PORT=${CLAWDBOT_GATEWAY_PORT} - - CLAWDBOT_BRIDGE_PORT=${CLAWDBOT_BRIDGE_PORT} - CLAWDBOT_GATEWAY_TOKEN=${CLAWDBOT_GATEWAY_TOKEN} - GOG_KEYRING_PASSWORD=${GOG_KEYRING_PASSWORD} - XDG_CONFIG_HOME=${XDG_CONFIG_HOME} @@ -179,9 +177,8 @@ services: # To expose it publicly, remove the `127.0.0.1:` prefix and firewall accordingly. - "127.0.0.1:${CLAWDBOT_GATEWAY_PORT}:18789" - # Optional: only if you run iOS/Android nodes against this VPS. - # If you expose these publicly, read /gateway/security and firewall accordingly. - # - "${CLAWDBOT_BRIDGE_PORT}:18790" + # Optional: only if you run iOS/Android nodes against this VPS and need Canvas host. + # If you expose this publicly, read /gateway/security and firewall accordingly. # - "18793:18793" command: [ diff --git a/docs/platforms/mac/canvas.md b/docs/platforms/mac/canvas.md index f706292b8..0e9d52b64 100644 --- a/docs/platforms/mac/canvas.md +++ b/docs/platforms/mac/canvas.md @@ -40,7 +40,7 @@ node commands return `CANVAS_DISABLED`. ## Agent API surface -Canvas is exposed via the **node bridge**, so the agent can: +Canvas is exposed via the **Gateway WebSocket**, so the agent can: - show/hide the panel - navigate to a path or URL diff --git a/docs/platforms/mac/menu-bar.md b/docs/platforms/mac/menu-bar.md index 351d2819c..36b39f535 100644 --- a/docs/platforms/mac/menu-bar.md +++ b/docs/platforms/mac/menu-bar.md @@ -8,7 +8,7 @@ read_when: ## What is shown - We surface the current agent work state in the menu bar icon and in the first status row of the menu. - Health status is hidden while work is active; it returns when all sessions are idle. -- The “Nodes” block in the menu lists **devices** only (gateway bridge nodes via `node.list`), not client/presence entries. +- The “Nodes” block in the menu lists **devices** only (paired nodes via `node.list`), not client/presence entries. - A “Usage” section appears under Context when provider usage snapshots are available. ## State model diff --git a/docs/platforms/mac/xpc.md b/docs/platforms/mac/xpc.md index 4beaf6fa4..fa3ca208b 100644 --- a/docs/platforms/mac/xpc.md +++ b/docs/platforms/mac/xpc.md @@ -1,5 +1,5 @@ --- -summary: "macOS IPC architecture for Clawdbot app, gateway node bridge, and PeekabooBridge" +summary: "macOS IPC architecture for Clawdbot app, gateway node transport, and PeekabooBridge" read_when: - Editing IPC contracts or menu bar app IPC --- @@ -13,21 +13,21 @@ read_when: - Predictable permissions: always the same signed bundle ID, launched by launchd, so TCC grants stick. ## How it works -### Gateway + node bridge +### Gateway + node transport - The app runs the Gateway (local mode) and connects to it as a node. - Agent actions are performed via `node.invoke` (e.g. `system.run`, `system.notify`, `canvas.*`). ### Node service + app IPC -- A headless node host service connects to the Gateway bridge. +- A headless node host service connects to the Gateway WebSocket. - `system.run` requests are forwarded to the macOS app over a local Unix socket. - The app performs the exec in UI context, prompts if needed, and returns output. Diagram (SCI): ``` -Agent -> Gateway -> Bridge -> Node Service (TS) - | IPC (UDS + token + HMAC + TTL) - v - Mac App (UI + TCC + system.run) +Agent -> Gateway -> Node Service (WS) + | IPC (UDS + token + HMAC + TTL) + v + Mac App (UI + TCC + system.run) ``` ### PeekabooBridge (UI automation) diff --git a/docs/platforms/macos.md b/docs/platforms/macos.md index b1540def8..e27e10e56 100644 --- a/docs/platforms/macos.md +++ b/docs/platforms/macos.md @@ -62,7 +62,7 @@ Node service + app IPC: Diagram (SCI): ``` -Gateway -> Bridge -> Node Service (TS) +Gateway -> Node Service (WS) | IPC (UDS + token + HMAC + TTL) v Mac App (UI + TCC + system.run) @@ -99,7 +99,7 @@ Example: ``` Notes: -- `allowlist` entries are JSON-encoded argv arrays. +- `allowlist` entries are glob patterns for resolved binary paths. - Choosing “Always Allow” in the prompt adds that command to the allowlist. - `system.run` environment overrides are filtered (drops `PATH`, `DYLD_*`, `LD_*`, `NODE_OPTIONS`, `PYTHON*`, `PERL*`, `RUBYOPT`) and then merged with the app’s environment. diff --git a/docs/start/faq.md b/docs/start/faq.md index 286662cb6..d12859020 100644 --- a/docs/start/faq.md +++ b/docs/start/faq.md @@ -719,11 +719,11 @@ See the full config examples in [Browser](/tools/browser#use-brave-or-another-ch ### How do commands propagate between Telegram, the gateway, and nodes? Telegram messages are handled by the **gateway**. The gateway runs the agent and -only then calls nodes over the **Bridge** when a node tool is needed: +only then calls nodes over the **Gateway WebSocket** when a node tool is needed: Telegram → Gateway → Agent → `node.*` → Node → Gateway → Telegram -Nodes don’t see inbound provider traffic; they only receive bridge RPC calls. +Nodes don’t see inbound provider traffic; they only receive node RPC calls. ### How can my agent access my computer if the Gateway is hosted remotely? @@ -733,29 +733,28 @@ call `node.*` tools (screen, camera, system) on your local machine over the Brid 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. +3) Ensure the Gateway WS is reachable (tailnet bind or SSH tunnel). +4) Open the macOS app locally and connect in **Remote over SSH** mode (or direct tailnet) + so it can register as a node. 5) Approve the node on the Gateway: ```bash clawdbot nodes pending clawdbot nodes approve ``` +No separate TCP bridge is required; nodes connect over the Gateway WebSocket. + 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). +Docs: [Nodes](/nodes), [Gateway protocol](/gateway/protocol), [macOS remote mode](/platforms/mac/remote), [Security](/gateway/security). ### Do nodes run a gateway service? 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. +A full restart is required for `gateway`, `discovery`, and `canvasHost` changes. ### Is there an API / RPC way to apply config? @@ -797,26 +796,19 @@ This keeps the gateway bound to loopback and exposes HTTPS via Tailscale. See [T ### How do I connect a Mac node to a remote Gateway (Tailscale Serve)? -Serve only exposes the **Gateway Control UI**. Nodes use the **bridge port**. +Serve exposes the **Gateway Control UI + WS**. Nodes connect over the same Gateway WS endpoint. Recommended setup: -1) **Enable the bridge on the gateway host**: - ```json5 - { - bridge: { enabled: true, bind: "auto" } - } - ``` - `auto` prefers a tailnet IP when Tailscale is present. -2) **Make sure the VPS + Mac are on the same tailnet**. -3) **Use the macOS app in Remote mode** (SSH target can be the tailnet hostname). - The app will tunnel the bridge port and connect as a node. -4) **Approve the node** on the gateway: +1) **Make sure the VPS + Mac are on the same tailnet**. +2) **Use the macOS app in Remote mode** (SSH target can be the tailnet hostname). + The app will tunnel the Gateway port and connect as a node. +3) **Approve the node** on the gateway: ```bash clawdbot nodes pending clawdbot nodes approve ``` -Docs: [Bridge protocol](/gateway/bridge-protocol), [Discovery](/gateway/discovery), [macOS remote mode](/platforms/mac/remote). +Docs: [Gateway protocol](/gateway/protocol), [Discovery](/gateway/discovery), [macOS remote mode](/platforms/mac/remote). ## Env vars and .env loading diff --git a/docs/tools/exec-approvals.md b/docs/tools/exec-approvals.md index 59ac7d119..6857970f6 100644 --- a/docs/tools/exec-approvals.md +++ b/docs/tools/exec-approvals.md @@ -22,7 +22,7 @@ Exec approvals are enforced locally on the execution host: - **gateway host** → `clawdbot` process on the gateway machine - **node host** → node runner (macOS companion app or headless node host) -Planned macOS split: +macOS split: - **node host service** forwards `system.run` to the **macOS app** over local IPC. - **macOS app** enforces approvals + executes the command in UI context. @@ -103,8 +103,8 @@ Each allowlist entry tracks: ## Auto-allow skill CLIs When **Auto-allow skill CLIs** is enabled, executables referenced by known skills -are treated as allowlisted on nodes (macOS node or headless node host). This uses the Bridge RPC to ask the -gateway for the skill bin list. Disable this if you want strict manual allowlists. +are treated as allowlisted on nodes (macOS node or headless node host). This uses +`skills.bins` over the Gateway RPC to fetch the skill bin list. Disable this if you want strict manual allowlists. ## Safe bins (stdin-only) @@ -151,12 +151,12 @@ Actions: - **Always allow** → add to allowlist + run - **Deny** → block -### macOS IPC flow (planned) +### macOS IPC flow ``` -Gateway -> Bridge -> Node Service (TS) - | IPC (UDS + token + HMAC + TTL) - v - Mac App (UI + approvals + system.run) +Gateway -> Node Service (WS) + | IPC (UDS + token + HMAC + TTL) + v + Mac App (UI + approvals + system.run) ``` Security notes: diff --git a/docs/tools/exec.md b/docs/tools/exec.md index b5c53593c..068be74ee 100644 --- a/docs/tools/exec.md +++ b/docs/tools/exec.md @@ -66,8 +66,8 @@ Example: - `host=sandbox`: runs `sh -lc` (login shell) inside the container, so `/etc/profile` may reset `PATH`. Clawdbot prepends `env.PATH` after profile sourcing; `tools.exec.pathPrepend` applies here too. - `host=node`: only env overrides you pass are sent to the node. `tools.exec.pathPrepend` only applies - if the exec call already sets `env.PATH`. Node PATH overrides are accepted only when they prepend - the node host PATH (no replacement). + if the exec call already sets `env.PATH`. Headless node hosts accept `PATH` only when it prepends + the node host PATH (no replacement). macOS nodes drop `PATH` overrides entirely. Per-agent node binding (use the agent list index in config):