> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Chrome Bridge environment setup

Chrome Bridge enables Node.js scripts to control your desktop Chrome browser through the Midscene Chrome extension, allowing you to reuse existing login sessions, cookies, and browser extensions. The Node.js process runs the Bridge Server and handles AI model calls, while the Chrome extension connects to that server and executes operations on browser tabs.

![Chrome Bridge](/images/midscene-bridge-mode.png)

## Installation and permissions

1. Install the [Midscene Chrome extension](https://chromewebstore.google.com/detail/midscene/gbldofcpkknbggpkmbdaefngejllnief). Once installed, it automatically listens for local connection requests in the background.
2. (Optional) If your script needs to upload local files, open `chrome://extensions`, go to the Midscene extension details, and enable **Allow access to file URLs**. Switch back to your target `http(s)://` tab before connecting.

## Validate model calls and page interactions in Playground

In [Get started](/get-started.md?platform=web\&scene=playground), choose Web and Playground to save your model settings in the extension, run an `aiAct` action and an `aiAssert` assertion in TodoMVC, and inspect the steps and screenshots.

The extension Playground controls the current page without a Node.js Bridge Server. After trying it, run the connection check below to verify that a script process can control Chrome through the extension.

[](#)
## Verify the connection {#verify-connection}

The minimal script below verifies the connection between your Node.js environment and the Chrome extension. It does not invoke any AI methods, so no model configuration is required.

### 1. Install dependencies

Install Node.js (`^20.19.0 || ^22.12.0 || >=24.0.0`), install pnpm, and run `pnpm init` in your project directory (skip if `package.json` already exists). Then install the dependencies:

```sh [npm]
npm install @midscene/web tsx --save-dev
```

```sh [yarn]
yarn add @midscene/web tsx --save-dev
```

```sh [pnpm]
pnpm add @midscene/web tsx --save-dev
```

```sh [bun]
bun add @midscene/web tsx --save-dev
```

```sh [deno]
deno add npm:@midscene/web npm:tsx --save-dev
```

### 2. Write the code

Save the following code as `bridge-check.ts`:

```typescript title="bridge-check.ts"
import { AgentOverChromeBridge } from '@midscene/web/bridge-mode';

async function main() {
  const agent = new AgentOverChromeBridge();
  try {
    await agent.connectNewTabWithUrl('https://example.com');
    console.log('Chrome Bridge connected');
    console.log(await agent.getBrowserTabList());
  } finally {
    await agent.destroy();
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});
```

### 3. Run and authorize

```bash
pnpm exec tsx bridge-check.ts
```

When prompted by the Chrome extension, click **Allow** to approve the connection (choose **Always Allow** to automatically approve future connections; you can reset this anytime in the extension's Bridge Mode panel).

Once connected, Chrome opens `example.com` in a new tab, and the terminal prints `Chrome Bridge connected` followed by the current tab list. The script then finishes and disconnects, leaving the newly opened tab in Chrome. On the extension icon badge, a yellow dot indicates that it is listening for connections, while a green dot indicates an active connection (because this check script disconnects immediately after completion, the badge will briefly turn green and then return to yellow).

![Chrome Bridge connection](/images/bridge_in_extension.png)

## Next steps

After validating the environment and Playground, choose how to continue:

- **Write YAML tests**: create a project, run cases, and inspect reports with [Midscene Test](/midscene-test/use.md).
- **Write automation workflows**: follow [Standalone automation scripts](/sdk/standalone.md) and select the Chrome Bridge example.
- **Look up platform APIs**: see the [Chrome Bridge SDK API reference](/sdk/chrome-bridge.md) for constructor options, platform methods, and cleanup.

Model settings saved in Playground are not automatically shared with test or script processes. Copy the validated settings into your project’s `.env` and load them as described in the integration guide. Keep the device connection tools, services, and permissions available.

The Midscene Test Web template uses Playwright by default. To use Bridge, adapt [the project configuration](/midscene-test/configuration.md) to connect and destroy an `AgentOverChromeBridge` and register it with `createMidsceneNodes()`. Replace the template’s Playwright page initialization.

Chrome Bridge does not expose a Playwright `Page`. To integrate with Playwright Test, follow [Web environment setup](/platforms/web.md).

## Remote access configuration {#remote-access-configuration}

By default, the Bridge Server binds to `127.0.0.1` and only accepts connections from a Chrome extension on the same machine. For cross-machine setups (for example, running the script on Machine A and Chrome on Machine B), enable remote access on both sides:

**1. Server side (Node.js script)**

```typescript
// Option 1: Listen on all network interfaces (0.0.0.0:3766)
const agent = new AgentOverChromeBridge({
  allowRemoteAccess: true,
});

// Option 2: Bind to a specific network interface IP
const agent = new AgentOverChromeBridge({
  host: '192.168.1.100',
  port: 3766,
});
```

**2. Client side (Chrome extension)**

1. Open the Chrome extension side panel and switch to **Bridge Mode**.
2. Enter the server address in the **Bridge Server URL** field:
   - Local connection: `ws://localhost:3766` (default)
   - Remote connection: `ws://192.168.1.100:3766` (replace with the IP address of the machine running the script)
3. Run your script and click **Allow** in the extension's confirmation dialog.

![bridge remote config](/images/bridge_remote_config.png)

:::warning Security Notice

Enabling remote access exposes the Bridge Server over the network. Make sure to:

- Use it only within trusted private networks;
- Restrict incoming connections with firewall rules;
- Never expose the Bridge Server port to the public internet.

:::

## Troubleshooting {#faq}

### The extension fails to connect

Verify that Chrome is open, the Midscene extension is enabled, and the **Bridge Server URL** in the extension's Bridge Mode panel matches the address and port your script is listening on (local default: `ws://127.0.0.1:3766`). For remote connections, also verify that the script has `allowRemoteAccess: true` or the appropriate `host` configured, and that the port is reachable through your firewall.

### How do I re-prompt for connection authorization?

Reset the saved permissions in the extension's Bridge Mode panel, then rerun the script to trigger the confirmation dialog again.

### Where should I configure model credentials?

When calling AI methods such as `aiAct` or `aiAssert`, [configure your model credentials](/model-api-setup.md) in the Node.js environment running the script. Model settings entered in the extension's Playground apply only to the Playground itself and are not shared with Node.js scripts. Also note that passing the connection check above only verifies bridge communication, not your model configuration.