> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Chrome Extension

# Chrome extension (browser relay)

The WednesdayAI Chrome extension lets the agent control your **existing Chrome tabs** (your normal Chrome window) instead of launching a separate openclaw-managed Chrome profile.

Attach/detach happens via a **single Chrome toolbar button**.

## What it is (concept)

There are three parts:

* **Browser control service** (Gateway or node): the API the agent/tool calls (via the Gateway)
* **Local relay server** (loopback CDP): bridges between the control server and the extension (`http://127.0.0.1:18792` by default)
* **Chrome MV3 extension**: attaches to the active tab using `chrome.debugger` and pipes CDP messages to the relay

WednesdayAI then controls the attached tab through the normal `browser` tool surface (selecting the right profile).

## Install / load (unpacked)

1. Install the extension to a stable local path:

```bash theme={"dark"}
wednesdayai browser extension install
```

2. Print the installed extension directory path:

```bash theme={"dark"}
wednesdayai browser extension path
```

3. Chrome → `chrome://extensions`

* Enable “Developer mode”
* “Load unpacked” → select the directory printed above

4. Pin the extension.

## Updates (no build step)

The extension ships inside the WednesdayAI release (npm package) as static files. There is no separate "build" step.

After upgrading WednesdayAI:

* Re-run `wednesdayai browser extension install` to refresh the installed files under your WednesdayAI state directory.
* Chrome → `chrome://extensions` → click “Reload” on the extension.

## Use it (pair the extension)

WednesdayAI ships with a built-in browser profile named `chrome` that targets the extension relay on the default port.

### Local pairing (same machine)

Before first attach, open extension Options and set:

* `Port` (default `18792`)
* `Gateway token` (must match `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN`)

Or generate a pairing string from the CLI:

```bash theme={"dark"}
wednesdayai browser extension pair
```

Paste the printed string into the extension popup's pairing field.

### Remote pairing (gateway on another machine)

If the Gateway runs on a different machine, pair the extension directly over `wss://` — no node host required:

```bash theme={"dark"}
wednesdayai browser extension pair --gateway-url wss://gateway-host:18789
```

This prints a pairing string like:

```
wss://gateway-host:18789/browser/extension#a1b2c3...64-hex-token
```

Paste this string into the extension popup's pairing field. The extension connects to the Gateway's `/browser/extension` WebSocket route, which proxies to the local relay on the gateway machine.

**Requirements:**

* The Gateway must be reachable over `wss://` (TLS). Plain `ws://` is only accepted for loopback hosts.
* `gateway.auth.token` must be configured on the Gateway (the pairing string embeds a derived token).
* The extension's `host_permissions` must include the Gateway host (shown in the CLI output).

**Rate limiting:** the Gateway rate-limits `/browser/extension` connections to 20 attempts per 60-second window per client IP, with a 60-second lockout after exhaustion. Loopback IPs are not exempt.

Use it:

* CLI: `wednesdayai browser --browser-profile chrome tabs`
* Agent tool: `browser` with `profile="chrome"`

If you want a different name or a different relay port, create your own profile:

```bash theme={"dark"}
wednesdayai browser create-profile \
  --name my-chrome \
  --driver extension \
  --cdp-url http://127.0.0.1:18792 \
  --color "#00AA00"
```

### Custom Gateway ports

If you're using a custom gateway port, the extension relay port is automatically derived:

**Extension Relay Port = Gateway Port + 3**

Example: if `gateway.port: 19001`, then:

* Extension relay port: `19004` (gateway + 3)

Configure the extension to use the derived relay port in the extension Options page.

## Attach / detach (toolbar button)

* Open the tab you want WednesdayAI to control.
* Click the extension icon.
  * Badge shows `ON` when attached.
* Click again to detach.

## Which tab does it control?

* It does **not** automatically control “whatever tab you’re looking at”.
* It controls **only the tab(s) you explicitly attached** by clicking the toolbar button.
* To switch: open the other tab and click the extension icon there.

## Badge + common errors

* `ON`: attached; WednesdayAI can drive that tab.
* `…`: connecting to the local relay.
* `!`: relay not reachable/authenticated (most common: relay server not running, or gateway token missing/wrong).

If you see `!`:

* Make sure the Gateway is running locally (default setup), or run a node host on this machine if the Gateway runs elsewhere.
* Open the extension Options page; it validates relay reachability + gateway-token auth.

## Remote Gateway

There are two ways to use the extension with a Gateway on a different machine:

### Option A: Direct pairing (recommended)

Pair the extension directly to the remote Gateway over `wss://` — no node host needed. The Gateway proxies the connection to the local relay on its own machine.

```bash theme={"dark"}
wednesdayai browser extension pair --gateway-url wss://gateway-host:18789
```

Paste the pairing string into the extension popup. See [Remote pairing](#remote-pairing-gateway-on-another-machine) above for details.

**When to use:** you control the Gateway machine and it has Chrome (or the relay) running locally.

### Option B: Node host (legacy)

Run a node host on the machine that runs Chrome. The Gateway proxies browser actions to that node; the extension + relay stay local to the browser machine.

If multiple nodes are connected, pin one with `gateway.nodes.browser.node` or set `gateway.nodes.browser.mode`.

**When to use:** the Gateway machine does not have Chrome, or you need the relay on a different machine than the Gateway.

### Local Gateway (same machine as Chrome) — usually **no extra steps**

If the Gateway runs on the same machine as Chrome, it starts the browser control service on loopback
and auto-starts the relay server. The extension talks to the local relay; the CLI/tool calls go to the Gateway.

## Sandboxing (tool containers)

If your agent session is sandboxed (`agents.defaults.sandbox.mode != "off"`), the `browser` tool can be restricted:

* By default, sandboxed sessions often target the **sandbox browser** (`target="sandbox"`), not your host Chrome.
* Chrome extension relay takeover requires controlling the **host** browser control server.

Options:

* Easiest: use the extension from a **non-sandboxed** session/agent.
* Or allow host browser control for sandboxed sessions:

```json5 theme={"dark"}
{
  agents: {
    defaults: {
      sandbox: {
        browser: {
          allowHostControl: true,
        },
      },
    },
  },
}
```

Then ensure the tool isn’t denied by tool policy, and (if needed) call `browser` with `target="host"`.

Debugging: `wednesdayai sandbox explain`

## Remote access tips

* Keep the Gateway and node host on the same tailnet; avoid exposing relay ports to LAN or public Internet.
* Pair nodes intentionally; disable browser proxy routing if you don’t want remote control (`gateway.nodes.browser.mode="off"`).

## How “extension path” works

`wednesdayai browser extension path` prints the **installed** on-disk directory containing the extension files.

The CLI intentionally does **not** print a `node_modules` path. Always run `wednesdayai browser extension install` first to copy the extension to a stable location under your WednesdayAI state directory.

If you move or delete that install directory, Chrome will mark the extension as broken until you reload it from a valid path.

## Security implications (read this)

This is powerful and risky. Treat it like giving the model “hands on your browser”.

* The extension uses Chrome’s debugger API (`chrome.debugger`). When attached, the model can:
  * click/type/navigate in that tab
  * read page content
  * access whatever the tab’s logged-in session can access
* **This is not isolated** like the dedicated openclaw-managed profile.
  * If you attach to your daily-driver profile/tab, you’re granting access to that account state.

Recommendations:

* Prefer a dedicated Chrome profile (separate from your personal browsing) for extension relay usage.
* Keep the Gateway and any node hosts tailnet-only; rely on Gateway auth + node pairing.
* Avoid exposing relay ports over LAN (`0.0.0.0`) and avoid Funnel (public).
* The relay blocks non-extension origins and requires gateway-token auth for both `/cdp` and `/extension`.
* The Gateway's `/browser/extension` WebSocket route validates origin (`chrome-extension://` only), authenticates via subprotocol token, and rate-limits connection attempts (20 per 60s per IP, 60s lockout).
* Remote pairing (`wss://`) sends the derived token in the WebSocket subprotocol header — TLS is required for non-loopback hosts. Plain `ws://` is rejected for remote gateways.

Related:

* Browser tool overview: [Browser](https://docs.wednesdayai.dev/next/users/tools/browser.md)
* Security audit: [Security](https://docs.wednesdayai.dev/next/admin/gateway/security.md)
* Tailscale setup: [Tailscale](https://docs.wednesdayai.dev/next/admin/gateway/tailscale.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.