mirror of
https://github.com/clawdbot/clawdbot.git
synced 2026-01-31 19:37:45 +01:00
refactor: route browser control via gateway/node
This commit is contained in:
Peter Steinberger
@@ -2759,7 +2759,7 @@ Example:
|
||||
|
||||
### `browser` (clawd-managed browser)
|
||||
|
||||
Clawdbot can start a **dedicated, isolated** Chrome/Brave/Edge/Chromium instance for clawd and expose a small loopback control server.
|
||||
Clawdbot can start a **dedicated, isolated** Chrome/Brave/Edge/Chromium instance for clawd and expose a small loopback control service.
|
||||
Profiles can point at a **remote** Chromium-based browser via `profiles.<name>.cdpUrl`. Remote
|
||||
profiles are attach-only (start/stop/reset are disabled).
|
||||
|
||||
@@ -2768,8 +2768,8 @@ scheme/host for profiles that only set `cdpPort`.
|
||||
|
||||
Defaults:
|
||||
- enabled: `true`
|
||||
- control URL: `http://127.0.0.1:18791` (CDP uses `18792`)
|
||||
- CDP URL: `http://127.0.0.1:18792` (control URL + 1, legacy single-profile)
|
||||
- control service: loopback only (port derived from `gateway.port`, default `18791`)
|
||||
- CDP URL: `http://127.0.0.1:18792` (control service + 1, legacy single-profile)
|
||||
- profile color: `#FF4500` (lobster-orange)
|
||||
- Note: the control server is started by the running gateway (Clawdbot.app menubar, or `clawdbot gateway`).
|
||||
- Auto-detect order: default browser if Chromium-based; otherwise Chrome → Brave → Edge → Chromium → Chrome Canary.
|
||||
@@ -2778,7 +2778,6 @@ Defaults:
|
||||
{
|
||||
browser: {
|
||||
enabled: true,
|
||||
controlUrl: "http://127.0.0.1:18791",
|
||||
// cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override
|
||||
defaultProfile: "chrome",
|
||||
profiles: {
|
||||
|
||||
@@ -83,13 +83,13 @@ 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)
|
||||
- `browser.controlUrl=http://127.0.0.1:19003` (derived: `gateway.port+2`)
|
||||
- browser control service port = `19003` (derived: `gateway.port+2`, loopback only)
|
||||
- `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`)
|
||||
- `browser.controlUrl port = base + 2` (or `CLAWDBOT_BROWSER_CONTROL_URL` / config override)
|
||||
- browser control service port = base + 2 (loopback only)
|
||||
- `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).
|
||||
|
||||
|
||||
@@ -73,7 +73,7 @@ clawdbot --profile rescue gateway install
|
||||
|
||||
Base port = `gateway.port` (or `CLAWDBOT_GATEWAY_PORT` / `--port`).
|
||||
|
||||
- `browser.controlUrl port = base + 2`
|
||||
- browser control service port = base + 2 (loopback only)
|
||||
- `canvasHost.port = base + 4`
|
||||
- Browser profile CDP ports auto-allocate from `browser.controlPort + 9 .. + 108`
|
||||
|
||||
@@ -81,8 +81,8 @@ If you override any of these in config or env, you must keep them unique per ins
|
||||
|
||||
## Browser/CDP notes (common footgun)
|
||||
|
||||
- Do **not** pin `browser.controlUrl` or `browser.cdpUrl` to the same values on multiple instances.
|
||||
- Each instance needs its own browser control port and CDP range.
|
||||
- Do **not** pin `browser.cdpUrl` to the same values on multiple instances.
|
||||
- Each instance needs its own browser control port and CDP range (derived from its gateway port).
|
||||
- If you need explicit CDP ports, set `browser.profiles.<name>.cdpPort` per instance.
|
||||
- Remote Chrome: use `browser.profiles.<name>.cdpUrl` (per profile, per instance).
|
||||
|
||||
|
||||
@@ -117,6 +117,6 @@ Short version: **keep the Gateway loopback-only** unless you’re sure you need
|
||||
- `gateway.remote.tlsFingerprint` pins the remote TLS cert when using `wss://`.
|
||||
- **Tailscale Serve** can authenticate via identity headers when `gateway.auth.allowTailscale: true`.
|
||||
Set it to `false` if you want tokens/passwords instead.
|
||||
- Treat `browser.controlUrl` like an admin API: tailnet-only + token auth.
|
||||
- Treat browser control like operator access: tailnet-only + deliberate node pairing.
|
||||
|
||||
Deep dive: [Security](/gateway/security).
|
||||
|
||||
@@ -36,7 +36,7 @@ Start with the smallest access that still works, then widen it as you gain confi
|
||||
- **Inbound access** (DM policies, group policies, allowlists): can strangers trigger the bot?
|
||||
- **Tool blast radius** (elevated tools + open rooms): could prompt injection turn into shell/file/network actions?
|
||||
- **Network exposure** (Gateway bind/auth, Tailscale Serve/Funnel).
|
||||
- **Browser control exposure** (remote controlUrl without token, HTTP, token reuse).
|
||||
- **Browser control exposure** (remote nodes, relay ports, remote CDP endpoints).
|
||||
- **Local disk hygiene** (permissions, symlinks, config includes, “synced folder” paths).
|
||||
- **Plugins** (extensions exist without an explicit allowlist).
|
||||
- **Model hygiene** (warn when configured models look legacy; not a hard block).
|
||||
@@ -61,7 +61,7 @@ When the audit prints findings, treat this as a priority order:
|
||||
|
||||
1. **Anything “open” + tools enabled**: lock down DMs/groups first (pairing/allowlists), then tighten tool policy/sandboxing.
|
||||
2. **Public network exposure** (LAN bind, Funnel, missing auth): fix immediately.
|
||||
3. **Browser control remote exposure**: treat it like a remote admin API (token required; HTTPS/tailnet-only).
|
||||
3. **Browser control remote exposure**: treat it like operator access (tailnet-only, pair nodes deliberately, avoid public exposure).
|
||||
4. **Permissions**: make sure state/config/credentials/auth are not group/world-readable.
|
||||
5. **Plugins/extensions**: only load what you explicitly trust.
|
||||
6. **Model choice**: prefer modern, instruction-hardened models for any bot with tools.
|
||||
@@ -277,7 +277,7 @@ Assume “compromised” means: someone got into a room that can trigger the bot
|
||||
- Lock down inbound surfaces (DM policy, group allowlists, mention gating).
|
||||
2. **Rotate secrets**
|
||||
- Rotate `gateway.auth` token/password.
|
||||
- Rotate `browser.controlToken` and `hooks.token` (if used).
|
||||
- Rotate `hooks.token` (if used) and revoke any suspicious node pairings.
|
||||
- Revoke/rotate model provider credentials (API keys / OAuth).
|
||||
3. **Review artifacts**
|
||||
- Check Gateway logs and recent sessions/transcripts for unexpected tool calls.
|
||||
@@ -430,26 +430,19 @@ Trusted proxies:
|
||||
|
||||
See [Tailscale](/gateway/tailscale) and [Web overview](/web).
|
||||
|
||||
### 0.6.1) Browser control server over Tailscale (recommended)
|
||||
### 0.6.1) Browser control via node host (recommended)
|
||||
|
||||
If your Gateway is remote but the browser runs on another machine, you’ll often run a **separate browser control server**
|
||||
on the browser machine (see [Browser tool](/tools/browser)). Treat this like an admin API.
|
||||
If your Gateway is remote but the browser runs on another machine, run a **node host**
|
||||
on the browser machine and let the Gateway proxy browser actions (see [Browser tool](/tools/browser)).
|
||||
Treat node pairing like admin access.
|
||||
|
||||
Recommended pattern:
|
||||
|
||||
```bash
|
||||
# on the machine that runs Chrome
|
||||
clawdbot browser serve --bind 127.0.0.1 --port 18791 --token <token>
|
||||
tailscale serve https / http://127.0.0.1:18791
|
||||
```
|
||||
|
||||
Then on the Gateway, set:
|
||||
- `browser.controlUrl` to the `https://…` Serve URL (MagicDNS/ts.net)
|
||||
- and authenticate with the same token (`CLAWDBOT_BROWSER_CONTROL_TOKEN` env preferred)
|
||||
- Keep the Gateway and node host on the same tailnet (Tailscale).
|
||||
- Pair the node intentionally; disable browser proxy routing if you don’t need it.
|
||||
|
||||
Avoid:
|
||||
- `--bind 0.0.0.0` (LAN-visible surface)
|
||||
- Tailscale Funnel for browser control endpoints (public exposure)
|
||||
- Exposing relay/control ports over LAN or public Internet.
|
||||
- Tailscale Funnel for browser control endpoints (public exposure).
|
||||
|
||||
### 0.7) Secrets on disk (what’s sensitive)
|
||||
|
||||
@@ -581,9 +574,8 @@ access those accounts and data. Treat browser profiles as **sensitive state**:
|
||||
- Treat browser downloads as untrusted input; prefer an isolated downloads directory.
|
||||
- Disable browser sync/password managers in the agent profile if possible (reduces blast radius).
|
||||
- For remote gateways, assume “browser control” is equivalent to “operator access” to whatever that profile can reach.
|
||||
- Treat `browser.controlUrl` endpoints as an admin API: tailnet-only + token auth. Prefer Tailscale Serve over LAN binds.
|
||||
- Keep `browser.controlToken` separate from `gateway.auth.token` (you can reuse it, but that increases blast radius).
|
||||
- Prefer env vars for the token (`CLAWDBOT_BROWSER_CONTROL_TOKEN`) instead of storing it in config on disk.
|
||||
- Keep the Gateway and node hosts tailnet-only; avoid exposing relay/control ports to LAN or public Internet.
|
||||
- Disable browser proxy routing when you don’t need it (`gateway.nodes.browser.mode="off"`).
|
||||
- Chrome extension relay mode is **not** “safer”; it can take over your existing Chrome tabs. Assume it can act as you in whatever that tab/profile can reach.
|
||||
|
||||
## Per-agent access profiles (multi-agent)
|
||||
|
||||
@@ -100,35 +100,13 @@ clawdbot gateway --tailscale funnel --auth password
|
||||
- Serve/Funnel only expose the **Gateway control UI + WS**. Nodes connect over
|
||||
the same Gateway WS endpoint, so Serve can work for node access.
|
||||
|
||||
## Browser control server (remote Gateway + local browser)
|
||||
## Browser control (remote Gateway + local browser)
|
||||
|
||||
If you run the Gateway on one machine but want to drive a browser on another machine, use a **separate browser control server**
|
||||
and publish it through Tailscale **Serve** (tailnet-only):
|
||||
If you run the Gateway on one machine but want to drive a browser on another machine,
|
||||
run a **node host** on the browser machine and keep both on the same tailnet.
|
||||
The Gateway will proxy browser actions to the node; no separate control server or Serve URL needed.
|
||||
|
||||
```bash
|
||||
# on the machine that runs Chrome
|
||||
clawdbot browser serve --bind 127.0.0.1 --port 18791 --token <token>
|
||||
tailscale serve https / http://127.0.0.1:18791
|
||||
```
|
||||
|
||||
Then point the Gateway config at the HTTPS URL:
|
||||
|
||||
```json5
|
||||
{
|
||||
browser: {
|
||||
enabled: true,
|
||||
controlUrl: "https://<magicdns>/"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
And authenticate from the Gateway with the same token (prefer env):
|
||||
|
||||
```bash
|
||||
export CLAWDBOT_BROWSER_CONTROL_TOKEN="<token>"
|
||||
```
|
||||
|
||||
Avoid Funnel for browser control endpoints unless you explicitly want public exposure.
|
||||
Avoid Funnel for browser control; treat node pairing like operator access.
|
||||
|
||||
## Tailscale prerequisites + limits
|
||||
|
||||
|
||||
Reference in New Issue
Block a user