AI
Browser Run
Run @cloudflare/puppeteer against a hosted browser such as Browserbase, or any Chrome DevTools Protocol endpoint.
Runs on Your own headless Chrome or a hosted browser, through its DevTools Protocol endpoint
- Works
@cloudflare/puppeteer1.x runs unchanged:launch(), pages, screenshots, andsessions()- Differs
- Sessions run on the browser in
ORANGE_BROWSER_CDP_URL.keep_alive,location, andrecordingare ignored, and session limits are not enforced. - Missing
- Rejoining a session with
puppeteer.connect()afterbrowser.disconnect() - Migration
- Not needed Sessions run on the browser you configure.
- Configure
browser- Checks
- 1 pass
On OpenOrange, the browser binding drives a browser that you choose through
its Chrome DevTools Protocol (CDP) endpoint: a hosted browser such as
Browserbase, or a Chromium that you run. Your
@cloudflare/puppeteer code runs unchanged.
Quickstart
You need a Browserbase API key, another hosted browser from
Choose a provider, or Chromium on your machine. Add
@cloudflare/puppeteer to your project’s dependencies.
-
Add the binding
Add the
browserbinding towrangler.jsonc.{ "name": "browser-rendering", "main": "src/index.ts", "compatibility_date": "2026-09-03", "compatibility_flags": ["nodejs_compat"], "browser": { "binding": "BROWSER" } } -
Point it at a browser
Put the browser’s CDP URL in
.dev.vars. For Browserbase, the URL carries your API key. For Chromium on your machine, see Run Chromium yourself.# .dev.vars ORANGE_BROWSER_CDP_URL="wss://connect.browserbase.com?apiKey=<your API key>" -
Open a page
Launch a browser from the binding with
@cloudflare/puppeteer, as on Cloudflare.import puppeteer from "@cloudflare/puppeteer"; export default { async fetch(request, env) { const browser = await puppeteer.launch(env.BROWSER); const page = await browser.newPage(); await page.goto("https://example.com"); const title = await page.title(); await browser.close(); return new Response(title); }, }; -
Run it
orange devshows the binding on Chrome DevTools.orange dev Binding Resource Runs on env.BROWSER Browser Rendering Chrome DevTools · ORANGE_BROWSER_CDP_URLRequest the Worker. It returns the page’s title.
curl localhost:8787
How it works
- Each
puppeteer.launch(env.BROWSER)opens a new DevTools connection to the browser inORANGE_BROWSER_CDP_URL, and OpenOrange passes every message through. - Browserbase starts a new browser for each session. A Chromium that you run is shared by every session.
- On a cluster, set the variable on the runner pool. The runner must be able to reach the browser.
AI context Compatibility, limits and details
Written for LLMs and coding agents: every edge case, measurement, and known deviation. You do not need it to use the feature.
Compatibility
OpenOrange answers the requests that @cloudflare/puppeteer 1.x sends to
Browser Rendering:
| Feature | Status | Notes |
|---|---|---|
launch() (POST /v1/devtools/browser) | Supported | Checks that the browser answers, then starts a session. |
The DevTools WebSocket (/v1/devtools/browser/<sessionId>) | Supported | Opens a CDP connection to the browser and passes every message through. |
sessions(), history(), limits() | Supported | List this runtime’s sessions. For the numbers limits() reports, see Limits. |
browser.close() | Supported | On a browser that you run, it closes only the pages that the session opened. See Run Chromium yourself. |
puppeteer.connect(env.BROWSER, sessionId) after browser.disconnect() | Not supported | Cannot rejoin. A session ends with its WebSocket. |
keep_alive, location, recording, and guardrails | Partial | Accepted and ignored. |
| Session limits | Partial | Not enforced. See Limits. |
Limits
OpenOrange does not limit the number of sessions. The limit of the browser or
service in ORANGE_BROWSER_CDP_URL applies.
| What | Limit | What happens over it |
|---|---|---|
| Concurrent sessions | The browser’s or the hosted service’s own limit. limits() reports 10, the number that @cloudflare/puppeteer expects, and OpenOrange does not enforce it. | The service refuses the DevTools WebSocket, and launch() throws. See Errors and the Browserbase measurements. |
history() | The last 100 sessions of this runtime | The oldest session drops out of the list. |
/json/version of an http:// or https:// endpoint | 10 seconds to answer | launch() throws the 503 under Errors. |
Choose a provider
Set ORANGE_BROWSER_CDP_URL to the provider’s CDP WebSocket URL:
| Provider | ORANGE_BROWSER_CDP_URL | Notes |
|---|---|---|
| Browserbase | wss://connect.browserbase.com?apiKey=<API key> | Each launch() starts a new browser. See Browserbase. |
| Browserless | wss://production-sfo.browserless.io?token=<API token> | Other regions: production-lon and production-ams. A private fleet uses its own host, such as chrome.browserless.io. |
| Steel | wss://connect.steel.dev?apiKey=<API key> | Without sessionId, Steel starts a new session for each connection. |
| Other hosted CDP service | Its CDP WebSocket URL | The URL must accept a new connection each time. See the note below. |
| Chromium that you run | http://127.0.0.1:9222 | See Run Chromium yourself. |
Each launch() opens a new connection to the same URL. A service that gives a
WebSocket URL only after you create a session with its API, such as
Hyperbrowser, does not fit one fixed URL.
Configuration
Value of ORANGE_BROWSER_CDP_URL | What OpenOrange does |
|---|---|
A ws:// or wss:// address, such as a hosted browser’s endpoint or ws://127.0.0.1:9222/devtools/browser/<id> | Connects to it |
An http:// or https:// address, such as http://127.0.0.1:9222 | Reads the browser’s WebSocket address from /json/version, then connects |
| Any other scheme | launch() fails with ORANGE_BROWSER_CDP_URL must start with ws://, wss://, http://, or https:// |
- From
/json/version, OpenOrange keeps the path ofwebSocketDebuggerUrland uses the configured host, because Chrome reports its own address, such as127.0.0.1inside a container. Anhttps://endpoint connects withwss://. - OpenOrange reads the variable from the shell environment,
.dev.vars, or.env, like the R2 S3 settings. A value from the shell wins. orange doctorreportsenv.BROWSER · <scheme>//<host>, without the credentials. Without the variable, it reportsenv.BROWSER has no Chrome DevTools endpoint, so its calls throwas an action.
Browserbase
Each launch() opens a new WebSocket to the endpoint, and Browserbase starts a
new browser for each one. So each session runs in its own browser.
When the session’s WebSocket closes, Browserbase ends that browser within about a second. Browserbase bills for the minutes that its browsers run.
Measured on a Browserbase project that allows 3 concurrent browsers:
| Case | Result |
|---|---|
launch() | About 2.2 to 2.5 seconds |
Open https://example.com, read its title, take a screenshot, and close | About 5 seconds in all |
| Two sessions at once | Worked |
| A fourth concurrent session | Failed. Browserbase answered 429, and launch() threw. |
| Browserbase ended a session | Puppeteer reported disconnected, the next call on the page threw, and sessions() no longer listed the session. |
| A wrong API key | launch() threw. Browserbase answered 401. |
Run Chromium yourself
Use this path if you do not want a hosted browser. Any headless Chrome or
Chromium works, such as a chromedp/headless-shell container.
chromium --headless --remote-debugging-port=9222 &
export ORANGE_BROWSER_CDP_URL=http://127.0.0.1:9222
orange devAll sessions share the one browser in ORANGE_BROWSER_CDP_URL. So that one
Worker cannot stop the browser for the others:
browser.close()closes only the pages that the session opened. The browser keeps running.- When a session’s WebSocket closes, its pages close too.
Sessions share the browser’s default context, so they share cookies and storage. For separate profiles, give each Worker its own browser.
Errors
| Situation | What the Worker sees |
|---|---|
ORANGE_BROWSER_CDP_URL is not set | Every call on env.BROWSER, such as fetch(), throws Browser Rendering binding "BROWSER" is not supported by OpenOrange. Set ORANGE_BROWSER_CDP_URL to a Chrome DevTools Protocol endpoint, such as wss://connect.browserbase.com?apiKey=<key> or http://127.0.0.1:9222 of a headless Chrome. |
| The browser does not answer | launch() throws Unable to create new browser: code: 503: message: Browser Rendering could not reach the browser at <endpoint> (ORANGE_BROWSER_CDP_URL): <cause>. The cause can be /json/version answered HTTP <status> or /json/version has no webSocketDebuggerUrl. |
| The browser refuses the DevTools WebSocket, such as a wrong key or a hosted service’s concurrency limit | launch() throws. The WebSocket request gets 502 with Browser Rendering could not open the DevTools WebSocket at <endpoint>: Unexpected server response: <status>. |
| An unknown or busy session | The WebSocket request gets 404 Browser Rendering session not found or 409 Browser Rendering session is already in use, and connect() throws. |
A request that @cloudflare/puppeteer does not send | 404 Browser Rendering on Orange has no route <method> <path> |
Errors that the Worker can read name the endpoint without its user info, query,
or fragment, so they do not show the API key. A value from those parts that a
library’s own message quotes shows as <redacted>.
Conformance
tests/cli/orange-browser.test.tsruns a Worker underorange devthat drives a real headless Chromium through@cloudflare/puppeteer, and checks that closing its browser closes only its own pages. It also checks the error without a browser endpoint, with the browser down, and when the endpoint refuses or does not answer, and that the error names the endpoint without its credentials.- The
browser-renderingprobe inpackages/cloudflare-conformance/probes/checks thatlaunch()opens a page in the configured browser, reads it, and takes a PNG screenshot; that two requests at once each read their own page; thatbrowser.close()ends the session and the next launch still works; and thatconnect()to a session that is in use is refused. tests/cli/doctor.test.tschecks theorange doctorsettings check of a Browser Rendering binding, with and withoutORANGE_BROWSER_CDP_URL.- No automated test calls a hosted browser, so the Browserbase measurements are not part of the conformance run.
- The binding’s type is not registered in the type-conformance checks.
Recorded results
Recorded results from the conformance run of 2026-11-10 (Orange ea40348), 1,670 of 1,851 tests passing across every area. Each check is works when every result passed and partial when some did. The full feature matrix is on the compatibility page.
Browser Rendering
| Check | Status | Results |
|---|---|---|
Browser Rendering (browser) | Works |
|