Using with Puppeteer (CDP)

Last updated Sep 26, 2026 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.

Prerequisites

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

Install Puppeteer

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

npmyarnpnpmbun

npm i puppeteer-core

yarn add puppeteer-core

pnpm add puppeteer-core

bun add puppeteer-core

Connect to Browser Run

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-run/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>"

Run the script

node script.js

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

How it works

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

Troubleshooting

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

Was this helpful?

YesNo

On this page

Using with Puppeteer (CDP) - 图1Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/browser-run/cdp/puppeteer/#page","headline":"Using with Puppeteer (CDP)","description":"Connect Puppeteer to Browser Run sessions from any Node.js environment to automate browser tasks using the Chrome DevTools Protocol.","url":"https://developers.cloudflare.com/browser-run/cdp/puppeteer/","inLanguage":"en","image":"https://developers.cloudflare.com/browser-run/cdp/puppeteer/og.png?v=77807ac77a02a009","dateModified":"2026-09-26","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Manage browser sessions and tabs using HTTP endpoints, including creating sessions, listing targets, and opening the Chrome DevTools UI. title: Session management (HTTP) image: https://developers.cloudflare.com/browser-run/cdp/session-management/og.png?v=65bb6114563a9b7c

Skip to content

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/browser-run/llms.txt
Use this file to discover all available pages before exploring further.