--- id: remote-browser title: "Remote browser services" sidebar_label: "Remote browsers" description: Connect Crawlee crawlers to remote browser services like Browser Use, Browserbase, Browserless, or Steel. --- import ApiLink from '@site/src/components/ApiLink'; import CodeBlock from '@theme/CodeBlock'; import RemoteBrowserConfigSource from '!!raw-loader!./remote-browser-config.ts'; import RemoteBrowserProviderSource from '!!raw-loader!./remote-browser-provider.ts'; import RemoteBrowserPuppeteerSource from '!!raw-loader!./remote-browser-puppeteer.ts'; Instead of launching a local browser, Crawlee can connect to a remote browser service like [Browser Use](https://browser-use.com/), [Browserbase](https://browserbase.com/), [Browserless](https://browserless.io/), [Steel](https://steel.dev/), or any service that exposes a WebSocket/CDP endpoint. The crawler manages session rotation and the request lifecycle the same way it does locally — only the browser itself runs elsewhere. Use this when you need IPs in specific regions, want to offload CPU/memory from your runner, or need stealth features the service provides. ## How it works Set the crawler's `remoteBrowser` option with the connection details. The crawler builds its regular `BrowserPool` around a remote variant of its own browser plugin (`RemotePlaywrightPlugin` or `RemotePuppeteerPlugin`), so the connection is always for the matching browser — there's no plugin to construct and no way to mismatch the pool with the crawler. The plugin owns everything remote: resolving the endpoint per launch, connecting with the library's `connect()`, and releasing the session when the browser disconnects. ## Basic usage The simplest form is a static connection URL. Use this when the service exposes a single endpoint and doesn't need per-session setup. {RemoteBrowserConfigSource} `endpoint` can also be a function returning `{ url, context }`, called once per browser launch. Pair it with a `release` callback (it receives the `context`) to clean up sessions on the service side when the browser closes, crashes, or the pool is destroyed. `maxOpenBrowsers` caps the number of concurrent remote browsers — set it to the service's concurrent-session limit to avoid 429 errors. The pool enforces it inside `newPage()`, which waits for a free slot rather than overshooting. ### Self-hosted Some services ship a Docker image you can run locally or on your own infrastructure. For example, [Browserless](https://www.browserless.io/) has an open-source Chromium image: ```bash docker run -p 3000:3000 -e CONCURRENT=4 ghcr.io/browserless/chromium ``` Point the pool at the local endpoint with `endpoint: 'ws://localhost:3000'`. ## Custom provider For services with a session-create / session-release lifecycle, extend `RemoteBrowserProvider` and pass the instance as the `endpoint`. `connect()` runs once per browser launch and returns the connection URL plus an optional `context` object passed back to `release()`. `maxOpenBrowsers` set on the provider is adopted by the crawler's pool. {RemoteBrowserProviderSource} ## Puppeteer `PuppeteerCrawler` accepts the same `remoteBrowser` option. Puppeteer connects over CDP: {RemoteBrowserPuppeteerSource} For Playwright you can choose the protocol via the `remoteBrowser.protocol` option: `'cdp'` (default, `connectOverCDP()`) or `'playwright'` (`connect()`, Playwright's own WebSocket protocol). ## Tuning or sharing the pool `remoteBrowser` builds a pool the crawler owns and tears down. To tune the pool, or to share one across multiple crawlers, pass the same `remoteBrowser` to the pool factory for your crawler (`playwrightBrowserPool()`, `puppeteerBrowserPool()`) and hand the result over as `browserPool` instead — a pool supplied that way is never destroyed by the crawler, so you control its lifecycle. Use `remoteBrowser` *or* `browserPool`, not both. Declare it with `await using` and the browsers (and their remote sessions) are released once you are done with the pool: ```ts import { PlaywrightCrawler, playwrightBrowserPool } from 'crawlee'; await using browserPool = playwrightBrowserPool({ remoteBrowser: { endpoint: 'wss://production-sfo.browserless.io?token=xxx', maxOpenBrowsers: 2 }, maxOpenPagesPerBrowser: 5, }); await new PlaywrightCrawler({ browserPool, requestHandler: async () => { /* ... */ } }).run(['https://crawlee.dev']); await new PlaywrightCrawler({ browserPool, requestHandler: async () => { /* ... */ } }).run(['https://apify.com']); ``` Building the pool from `@crawlee/browser-pool` directly works too, and lets you rotate between several services — the pool round-robins over its plugins: ```ts import { BrowserPool, RemotePlaywrightPlugin } from '@crawlee/browser-pool'; import playwright from 'playwright'; const browserPool = new BrowserPool({ browserPlugins: [ new RemotePlaywrightPlugin(playwright.chromium, { endpoint: 'wss://production-sfo.browserless.io?token=xxx' }), new RemotePlaywrightPlugin(playwright.chromium, { endpoint: 'wss://connect.browserbase.com?apiKey=xxx' }), new RemotePlaywrightPlugin(playwright.chromium, { endpoint: 'wss://connect.browser-use.com?apiKey=xxx' }), ], }); ``` :::note Requires Node.js 24 The `await using` syntax needs Node.js 24 or later. On Node.js 22 call `destroy()` yourself instead — it is what the disposal hook calls anyway. ::: ## Limitations - **`headless` and `launchOptions` don't apply.** The remote service controls headless mode and browser flags; configure them on the service side. - **`useIncognitoPages` is forced to `true`** for Playwright remote connections — `connect()` / `connectOverCDP()` don't accept persistent contexts. For state shared across requests, use the `SessionPool`. - **`userDataDir` has no effect** — there's no local profile when the browser runs remotely. Use the service's persistence API (e.g. Browserbase Contexts, Steel Profiles). ## Further reading - `RemotePlaywrightPlugin` / `RemotePuppeteerPlugin` API reference - `RemoteBrowserProvider` API reference