Self-hosted browser
Run a Space in a browser you operate by giving Agent Vault its CDP URL.
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.
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.
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.
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.
- Your server passes the browser’s CDP URL when it creates a Space.
- 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.
- The agent uses the Space through the same grants and MCP tools as any other Space.
- 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.
- 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.
WorkOS keeps the URL while the Space is open so that it can reconnect to the browser.
In the WorkOS Dashboard, 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.
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:
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.
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.
Add cdp_url to the request that creates a Space.
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.
From here, the Space works like any other. Create an MCP grant bound to it and connect the agent.
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.
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:
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:
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:
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.
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.
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.
- 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.