Skip to content
AI / Browser Run

AI

Browser Run

Run @cloudflare/puppeteer against a hosted browser such as Browserbase, or any Chrome DevTools Protocol endpoint.

Pluggable

Runs on Your own headless Chrome or a hosted browser, through its DevTools Protocol endpoint

Works
@cloudflare/puppeteer 1.x runs unchanged: launch(), pages, screenshots, and sessions()
Differs
Sessions run on the browser in ORANGE_BROWSER_CDP_URL. keep_alive, location, and recording are ignored, and session limits are not enforced.
Missing
Rejoining a session with puppeteer.connect() after browser.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.

  1. Add the binding

    Add the browser binding to wrangler.jsonc.

    {
      "name": "browser-rendering",
      "main": "src/index.ts",
      "compatibility_date": "2026-09-03",
      "compatibility_flags": ["nodejs_compat"],
      "browser": { "binding": "BROWSER" }
    }
  2. 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>"
  3. 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);
      },
    };
  4. Run it

    orange dev shows the binding on Chrome DevTools.

    orange dev
      Binding       Resource            Runs on
      env.BROWSER   Browser Rendering   Chrome DevTools · ORANGE_BROWSER_CDP_URL

    Request 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 in ORANGE_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:

FeatureStatusNotes
launch() (POST /v1/devtools/browser)SupportedChecks that the browser answers, then starts a session.
The DevTools WebSocket (/v1/devtools/browser/<sessionId>)SupportedOpens a CDP connection to the browser and passes every message through.
sessions(), history(), limits()SupportedList this runtime’s sessions. For the numbers limits() reports, see Limits.
browser.close()SupportedOn 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 supportedCannot rejoin. A session ends with its WebSocket.
keep_alive, location, recording, and guardrailsPartialAccepted and ignored.
Session limitsPartialNot 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.

WhatLimitWhat happens over it
Concurrent sessionsThe 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 runtimeThe oldest session drops out of the list.
/json/version of an http:// or https:// endpoint10 seconds to answerlaunch() throws the 503 under Errors.

Choose a provider

Set ORANGE_BROWSER_CDP_URL to the provider’s CDP WebSocket URL:

ProviderORANGE_BROWSER_CDP_URLNotes
Browserbasewss://connect.browserbase.com?apiKey=<API key>Each launch() starts a new browser. See Browserbase.
Browserlesswss://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.
Steelwss://connect.steel.dev?apiKey=<API key>Without sessionId, Steel starts a new session for each connection.
Other hosted CDP serviceIts CDP WebSocket URLThe URL must accept a new connection each time. See the note below.
Chromium that you runhttp://127.0.0.1:9222See 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_URLWhat 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:9222Reads the browser’s WebSocket address from /json/version, then connects
Any other schemelaunch() fails with ORANGE_BROWSER_CDP_URL must start with ws://, wss://, http://, or https://
  • From /json/version, OpenOrange keeps the path of webSocketDebuggerUrl and uses the configured host, because Chrome reports its own address, such as 127.0.0.1 inside a container. An https:// endpoint connects with wss://.
  • OpenOrange reads the variable from the shell environment, .dev.vars, or .env, like the R2 S3 settings. A value from the shell wins.
  • orange doctor reports env.BROWSER · <scheme>//<host>, without the credentials. Without the variable, it reports env.BROWSER has no Chrome DevTools endpoint, so its calls throw as 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:

CaseResult
launch()About 2.2 to 2.5 seconds
Open https://example.com, read its title, take a screenshot, and closeAbout 5 seconds in all
Two sessions at onceWorked
A fourth concurrent sessionFailed. Browserbase answered 429, and launch() threw.
Browserbase ended a sessionPuppeteer reported disconnected, the next call on the page threw, and sessions() no longer listed the session.
A wrong API keylaunch() 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 dev

All 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

SituationWhat the Worker sees
ORANGE_BROWSER_CDP_URL is not setEvery 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 answerlaunch() 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 limitlaunch() 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 sessionThe 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 send404 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.ts runs a Worker under orange dev that 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-rendering probe in packages/cloudflare-conformance/probes/ checks that launch() opens a page in the configured browser, reads it, and takes a PNG screenshot; that two requests at once each read their own page; that browser.close() ends the session and the next launch still works; and that connect() to a session that is in use is refused.
  • tests/cli/doctor.test.ts checks the orange doctor settings check of a Browser Rendering binding, with and without ORANGE_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
  • Pass: browser-rendering: launch() opens a page in the configured browser, reads it, and takes a PNG screenshot
  • Pass: browser-rendering: two requests at once each read their own page
  • Pass: browser-rendering: browser.close() ends the session, and the next launch still works
  • Pass: browser-rendering: connect() to a session that is in use is refused