Connect over CDP

The box browser is a real Chromium, and you can drive it with the tools you already use. cdpUrl() returns an authenticated Chrome DevTools Protocol WebSocket URL that Playwright, Puppeteer, or Stagehand can connect to directly. There is no browser to install and nothing to manage. For a single no-LLM step without wiring up a CDP client, replaying an observed action with act(action) is often enough. Reach for CDP when you want fully scripted, multi-step control.

const cdpUrl = await box.browser.cdpUrl()
// wss://…?token=…

cdp_url = box.browser.cdp_url()
# wss://…?token=…

Like live view URLs, the CDP URL carries its auth token in the URL. Anyone who has it gets full control of the browser, so treat it as a secret.

Playwright

playwright-core is enough here, since you connect to the box’s Chromium instead of launching one locally:

import { chromium } from "playwright-core"

const browser = await chromium.connectOverCDP(cdpUrl)

const context = browser.contexts()[0] ?? (await browser.newContext())
const page = context.pages()[0] ?? (await context.newPage())

await page.goto("https://upstash.com")
console.log(await page.title())

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(cdp_url)
    context = browser.contexts[0] if browser.contexts else browser.new_context()
    page = context.pages[0] if context.pages else context.new_page()
    page.goto("https://upstash.com")
    print(page.title())

Puppeteer

scrape.ts

import puppeteer from "puppeteer-core"

const browser = await puppeteer.connect({ browserWSEndpoint: cdpUrl })

const page = (await browser.pages())[0] ?? (await browser.newPage())
await page.goto("https://upstash.com")

Stagehand

Stagehand can use the box browser as its local browser:

agent.ts

import { Stagehand } from "@browserbasehq/stagehand"

const stagehand = new Stagehand({
  env: "LOCAL",
  localBrowserLaunchOptions: { cdpUrl },
})

await stagehand.init()
await stagehand.act("click the first link")

Mixing CDP and SDK control

CDP clients and the SDK drive the same browser and the same tabs. A page opened by Playwright shows up in box.browser.listTabs(), and a tab created by the SDK is visible to Playwright. You can script the predictable steps like login and pagination with Playwright, hand the tab to act for the steps that are easier to describe in natural language, and watch either through Live View. As a rule of thumb: replay a cached act(action) for a single no-LLM step, reach for CDP when you want precise, repeatable multi-step scripting with no LLM in the loop, and use AI Actions when describing the task is easier than scripting it.

Introduction

Basics

Lifecycle

Security

Browser

Guides

Playwright

Puppeteer

Stagehand

Mixing CDP and SDK control

​Playwright

​Puppeteer

​Stagehand

​Mixing CDP and SDK control

Playwright

Puppeteer

Stagehand

Mixing CDP and SDK control