<!-- llms.txt: https://workos.com/llms.txt -->
<!-- feedback.md: https://workos.com/docs/feedback.md -->

# Self-hosted browser

By default, WorkOS creates and runs the browser behind every Space, in the cloud. With a self-hosted browser, a Space runs in a browser you already operate instead, such as one from a browser integration you already use. Agent Vault still stores the saved logins, signs in, and limits what the agent can do. Only the browser is yours.

> **Note:** Self-hosted browsers are in preview. They are off until an administrator selects Self-hosted in
> the Browser provider setting for the environment and allows the origin of your
> browser.

## When to use a self-hosted browser

Use a self-hosted browser when the browser has to be yours:

- **Your network.** Websites see requests from an address you control, such as an office or a fixed egress address the website already trusts.
- **Your browser fleet.** You already run browsers, on your own machines or with a cloud browser provider, and want agents to use them.
- **Your configuration.** The work needs a browser version, extension, or setting that you manage.

## How self-hosted browsers work

Chromium-based browsers can be driven over the Chrome DevTools Protocol (CDP). A browser that accepts CDP connections has a WebSocket URL, its CDP URL.

1. Your server passes the browser's CDP URL when it creates a Space.
2. WorkOS connects to the browser and opens its own browser contexts in it. A browser context is a separate profile: it shares no cookies or storage with the browser's other windows.
3. The agent uses the Space through the same grants and MCP tools as any other Space.
4. When the Space is closed, WorkOS disconnects and its contexts are discarded. The browser keeps running.

Sign-ins for the Space run in the same browser, so the website sees one browser from sign-in to the agent's last click.

## Browser requirements

- **A Chromium-based browser** that accepts CDP connections, such as Chrome or Chromium started with remote debugging on.
- **A secure WebSocket URL on the public internet.** The CDP URL must use `wss:`. WorkOS refuses a host that is, or resolves to, an address inside a private network.
- **An allowed origin.** The Allowed origins list of each environment lists the origins WorkOS may connect to. The scheme, host, and port of the CDP URL have to match one of them.
- **An open window.** A browser with no window open accepts the connection but can't be driven, and the request fails.
- **No credentials in the URL's user part and no fragment.** A token in the query string is fine. The URL can be at most 1,800 characters.

> Treat the CDP URL as a secret. Anyone who holds it controls the browser. Send it only from your server, and prefer URLs that are scoped to one browser session and expire.

WorkOS keeps the URL while the Space is open so that it can reconnect to the browser.

## Create a Space in your browser

### Select Self-hosted

In the [WorkOS Dashboard](https://dashboard.workos.com/), open *Agent Vault*, then *Settings*. Under *Browser provider*, select *Self-hosted* and save. Then add the origin of each place your browsers run, such as `wss://browsers.example.com`.

An origin is the scheme, host, and port of the CDP URL, without a path. Changing the setting needs permission to update the environment.

### Get the browser's CDP URL

If you use a cloud browser provider, create a session with the provider's API. The session's connect URL is the CDP URL.

If you run the browser yourself, start it with a debugging port and a profile directory of its own:

```bash title="Start Chrome with remote debugging"
google-chrome \
  --remote-debugging-port=9222 \
  --disable-blink-features=AutomationControlled \
  --user-data-dir=/var/lib/agent-vault-browser
```

A Chrome started with a debugging port tells websites that it is automated. The `--disable-blink-features=AutomationControlled` flag turns that signal off.

Then read the browser's debugging endpoint on that machine. The `webSocketDebuggerUrl` field holds the path of the CDP URL.

```bash title="Read the CDP URL"
curl http://127.0.0.1:9222/json/version
```

```json title="Response"
{
  "Browser": "Chrome/142.0.0.0",
  "webSocketDebuggerUrl": "ws://127.0.0.1:9222/devtools/browser/0b0f3f4e-8d6c-4f0e-9a51-6f1f0c9d2b7a"
}
```

Chrome only listens on the local machine. Put the debugging port behind an endpoint that terminates TLS and that WorkOS can reach, and use that endpoint's host in the URL you send: `wss://browsers.example.com/devtools/browser/0b0f3f4e-8d6c-4f0e-9a51-6f1f0c9d2b7a`. Restrict who can reach the endpoint, because the debugging port itself has no authentication.

### Pass the URL when you create the Space

Add `cdp_url` to the request that [creates a Space](https://workos.com/docs/reference/agent-vault/space/create).

```bash title="Create a Space in your browser"
curl --request POST \
  --url https://api.workos.com/agent-vault/spaces \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  --data '{
    "user_id": "user_01E4ZCR3C56J083X43JQXF3JK5",
    "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
    "name": "Shipping workspace",
    "cdp_url": "wss://browsers.example.com/devtools/browser/0b0f3f4e-8d6c-4f0e-9a51-6f1f0c9d2b7a"
  }'
```

WorkOS connects to the browser before it responds. A `ready` Space means the connection worked.

An agent that holds an MCP grant without a Space can do the same with the `browser_create` tool, which also accepts `cdp_url`. Prefer creating the Space from your server, so the URL never reaches the model.

### Use the Space

From here, the Space works like any other. [Create an MCP grant](https://workos.com/docs/agent-vault/quick-start#create-a-grant-for-the-agent) bound to it and connect the agent.

## Verify connections from WorkOS

WorkOS signs each CDP connection to your self-hosted browser. Verify the signature at your browser's gateway before accepting the connection, much like [verifying a webhook](https://workos.com/docs/events/data-syncing/webhooks).

In the WorkOS Dashboard, select the environment, then open **Agent Vault → Settings**. With **Self-hosted** selected, find **Signing secret** below **Allowed origins**. Click **Reveal**, then click the secret to copy it. This requires environment update permission. Store the secret securely on your server; do not put it in client-side code or your CDP URL.

Each connection includes this header:

```plain title="Signature header"
WorkOS-Signature: t=<unix milliseconds>, v1=<hex HMAC-SHA256 digest>
```

The exact signed string is `<t>.<path+query>`: the timestamp as it appears in the header, a `.` character, and the CDP URL's path followed by its query string, including the leading `?` when present. The scheme, host, port, and fragment are not signed. Preserve the encoded path, query parameter order, and query values without decoding or rewriting them.

For example, for `wss://browsers.example.com/devtools/browser/123?token=abc` at timestamp `1700000000123`, the signed string is:

```plain title="Signed string"
1700000000123./devtools/browser/123?token=abc
```

Compute HMAC-SHA256 over that `UTF-8` string, using the environment's signing secret as the key. Compare the digest with `v1` using a timing-safe comparison. Reject timestamps older than five minutes to limit replay attacks. The following Node.js example also rejects timestamps more than five minutes in the future:

```js title="Verify a CDP connection"
import { createHmac, timingSafeEqual } from 'node:crypto';

function verifyConnection(header, pathAndQuery, secret) {
  if (typeof header !== 'string' || typeof secret !== 'string' || !secret) {
    return false;
  }
  const parts = /^t=(\d+),\s*v1=([a-f0-9]{64})$/.exec(header);
  if (!parts) return false;

  const timestamp = Number(parts[1]);
  if (!Number.isSafeInteger(timestamp) || Math.abs(Date.now() - timestamp) > 5 * 60 * 1000) {
    return false;
  }

  const expected = createHmac('sha256', secret)
    .update(`${parts[1]}.${pathAndQuery}`, 'utf8')
    .digest();
  const received = Buffer.from(parts[2], 'hex');
  return received.length === expected.length && timingSafeEqual(received, expected);
}

// In your Node HTTP server's upgrade handler, before forwarding the connection:
const valid = verifyConnection(
  request.headers['workos-signature'],
  request.url ?? '/', // Original path and query, before any gateway rewrites.
  process.env.SELF_HOSTED_SIGNING_SECRET,
);
```

Reject the upgrade unless `valid` is `true`. Signature verification supplements your gateway's existing access controls; it does not replace them.

To rotate the secret, click **Rotate** in Settings and confirm. Rotation takes effect immediately for new connections, with no overlap period: WorkOS signs with the new secret, so gateways using the old secret stop accepting connections. Reveal and copy the new secret, then update your gateway. Existing open connections are not disconnected by rotation.

## Sign-ins in your browser

A sign-in the agent starts with `browser_login` runs in the Space's browser.

When Self-hosted is selected, configure a **Login browser URL** in Agent Vault settings to create logins outside a Space. Use the full `ws://` or `wss://` CDP WebSocket URL, at an Allowed origin. WorkOS uses that browser for *Add login*, manual sign-in, takeover, and retries or replacements of Self-hosted-pinned logins. Connections include `WorkOS-Signature`, like other Self-hosted CDP connections. Clear the URL before removing its Allowed origin.

Alternatively, open *Add login* in a widget bound to a Space created with `cdp_url`. Sign-in uses that Space's browser instead of the configured login browser. New logins are pinned to Self-hosted. Without either a Login browser URL or a connected self-hosted Space, creating, retrying, or replacing a Self-hosted-pinned login is unavailable. Existing WorkOS-pinned logins keep their provider.

Existing saved logins keep their pinned browser provider. A login saved with WorkOS can still be retried, replaced, or switched to manual sign-in in the widget while Self-hosted is selected. These sign-ins run in a browser that WorkOS creates and runs, not in yours.

When a sign-in needs the person, they still see the page. WorkOS streams it from your browser to the sign-in view, so the person's device never connects to your browser.

## Troubleshooting

A request to create a Space with `cdp_url` responds with `403 Forbidden` when Self-hosted is not selected for the environment, or when the URL is not at one of its allowed origins. The error message says which.

The request responds with `503 Service Unavailable` when WorkOS can't use the browser. Check that:

- The URL meets the [browser requirements](#browser-requirements).
- The browser is running and reachable from WorkOS.
- The browser has at least one window open. On macOS, Chrome keeps running after its last window closes.
- The URL has not expired, if your provider issues short-lived URLs.

When Self-hosted is selected, every new Space requires `cdp_url`. WorkOS does not start a managed browser as a fallback. Existing Spaces and saved logins keep their pinned browser provider when you change the selection.
