← Browser Run / browser-run / cdp

Using with Puppeteer (CDP)

You can use Puppeteer ↗ to connect to Browser Run sessions from any Node.js environment and automate browser tasks programmatically via CDP. This is useful for scripts running on your local machine, CI/CD pipelines, or external servers.

Before you begin, create a custom API Token with Browser Rendering - Edit permission.

• Node.js installed on your machine
• A Cloudflare account with Browser Run enabled
• A Browser Run API token with Browser Rendering - Edit permissions

Install the puppeteer-core package (the version without bundled Chrome):

npm i puppeteer-core

The following script demonstrates how to connect to a Browser Run session, navigate to a page, extract the title, and take a screenshot.

Create a file named script.js:

const puppeteer = require("puppeteer-core");

const ACCOUNT_ID = process.env.CF_ACCOUNT_ID || "<ACCOUNT_ID>";
const API_TOKEN = process.env.CF_API_TOKEN || "<API_TOKEN>";

const browserWSEndpoint = `wss://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/browser-rendering/devtools/browser?keep_alive=600000`;

async function main() {
	const browser = await puppeteer.connect({
		browserWSEndpoint,
		headers: {
			Authorization: `Bearer ${API_TOKEN}`,
		},
	});

	const page = await browser.newPage();
	await page.goto("https://developers.cloudflare.com");

	const title = await page.title();
	console.log(`Page title: ${title}`);

	await page.screenshot({ path: "screenshot.png" });

	await browser.close();
}

main().catch(console.error);

Replace ACCOUNT_ID with your Cloudflare account ID and API_TOKEN with your Browser Run API token, or set them as environment variables:

export CF_ACCOUNT_ID="<ACCOUNT_ID>"
export CF_API_TOKEN="<API_TOKEN>"

node script.js

You should see the page title printed to the console and a screenshot saved as screenshot.png.

The script connects directly to Browser Run via WebSocket using the CDP protocol:

1. WebSocket endpoint - The browserWSEndpoint URL acquires a new browser session and connects to it via WebSocket
2. Authentication - The Authorization header with your API token authenticates the request
3. Keep-alive - The keep_alive parameter (in milliseconds) specifies how long the session stays active
4. Puppeteer API - Once connected, you use the standard Puppeteer API to control the browser

If you have questions or encounter an error, see the Browser Run FAQ and troubleshooting guide.