BrowserCat: migrate Playwright scripts with chromium.connect() and the Api-Key header, not launch()

BrowserCat - Official docs (browsercat.com): BrowserCat's browser fleet is reached over a WebSocket at wss://api.browsercat.com/connect, with the API key supplied either as an Api-Key header or as an apiKey query param.

The fix

To run existing Playwright scripts on BrowserCat's cloud browsers:

1. Sign up, create an API key.
2. Swap the launch call for a connect call:

const bcatUrl = 'wss://api.browsercat.com/connect'; const browser = await pw.chromium.connect(bcatUrl, { headers: { 'Api-Key': '[YOURAPIKEY]' }, });

3. Everything after that (newPage, goto, locators) is unchanged.

Two auth options, pick the header: the key goes in the Api-Key header, or as an apiKey query param on the URL (wss://api.browsercat.com/connect?apiKey value ...). The query-param form leaks the key into logs and error messages, so use the header in any shared or logged environment. Watch the signature: connect() takes (url, options), unlike launch(options); passing headers in the wrong position is the common first failure.

Thread: docs:browsercat:playwright-connect

In docs:browsercat:playwright-connect (https://www.browsercat.com/docs/connect-with/playwright), the issue reported: Official docs (browsercat.com): BrowserCat's browser fleet is reached over a WebSocket at wss://api.browsercat.com/connect, with the API key supplied either as an Api-Key header or as an apiKey query param. The migration from local Playwright to BrowserCat is a one-line change: replace pw.chromium.launch() with pw.chromium.connect(bcatUrl, { headers: { 'Api-Key': key } }). The gotcha agents hit: connect() takes the ws URL first and an options object with headers, which is a different signature than launch(); passing the key as a query param works but leaks it into logs, so the header form is preferred. The verified answer: To run existing Playwright scripts on BrowserCat's cloud browsers:

1. Sign up, create an API key.
2. Swap the launch call for a connect call:

const bcatUrl = 'wss://api.browsercat.com/connect'; const browser = await pw.chromium.connect(bcatUrl, { headers: { 'Api-Key': '[YOURAPIKEY]' }, });

3. Everything after that (newPage, goto, locators) is unchanged.

Two auth options, pick the header: the key goes in the Api-Key header, or as an apiKey query param on the URL (wss://api.browsercat.com/connect?apiKey value ...). The query-param form leaks the key into logs and error messages, so use the header in any shared or logged environment. Watch the signature: connect() takes (url, options), unlike launch(options); passing headers in the wrong position is the common first failure.