BrowserBase — Cloud Browser Infrastructure for AI Agents

Overview

Browserbase is a hosted service that starts isolated Chromium sessions on demand. You create a session through the REST API or the Node SDK (@browserbasehq/sdk), receive a WebSocket connectUrl, and drive the browser with Playwright, Puppeteer or Selenium over CDP. The service adds proxies, CAPTCHA solving, session recording and logs, live view, and persistent contexts. Stagehand, Browserbase's open-source SDK with act, extract and observe primitives, uses it as its cloud browser. It is a paid, account-based service; this skill was checked against the public documentation only, not against a live account.

Instructions

Install and authenticate

npm install @browserbasehq/sdk playwright-core
export BROWSERBASE_API_KEY=...        # from the Browserbase dashboard, never hard-code
export BROWSERBASE_PROJECT_ID=...     # Settings page; optional, the API key can infer it

The REST API authenticates with the X-BB-API-Key header; the SDK sets it from apiKey.

Create a session and connect

import Browserbase from "@browserbasehq/sdk";
import { chromium } from "playwright-core";

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

const session = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID!,
  browserSettings: {
    viewport: { width: 1280, height: 720 },
    blockAds: true,            // default false
    solveCaptchas: true,       // default true
    recordSession: true,       // default true
  },
  proxies: true,               // Browserbase-managed proxies
  region: "us-east-1",         // us-west-2 | us-east-1 | eu-central-1 | ap-southeast-1
  timeout: 300,                // seconds, allowed range 60-21600
  keepAlive: false,            // true needs the Hobby plan or above
});

const browser = await chromium.connectOverCDP(session.connectUrl);
const page = browser.contexts()[0].pages()[0];
await page.goto("https://news.ycombinator.com");
console.log(await page.title());
await browser.close();

console.log(`Replay: https://browserbase.com/sessions/${session.id}`);

Other useful browserSettings: os, allowedDomains, verified (Verified Browser mode, plan dependent), ignoreCertificateErrors. Use userMetadata on the session to tag runs for later filtering.

Persistent contexts (keep logins)

const ctx = await bb.contexts.create({ name: "shop-admin" });

// First run: log in, then close the session so the state is saved
const first = await bb.sessions.create({
  browserSettings: { context: { id: ctx.id, persist: true } },
});

// Later run: already authenticated; persist: false = read the state, do not change it
const later = await bb.sessions.create({
  browserSettings: { context: { id: ctx.id, persist: false } },
});

Wait a few seconds after closing a persist: true session before reusing the context, and do not run two sessions on one context at once, or the site may log you out.

Parallel runs

async function titles(urls: string[], concurrency = 5) {
  const out: { url: string; title?: string; error?: string }[] = [];
  for (let i = 0; i < urls.length; i += concurrency) {
    const batch = urls.slice(i, i + concurrency);
    const settled = await Promise.allSettled(batch.map(async (url) => {
      const s = await bb.sessions.create({ projectId: process.env.BROWSERBASE_PROJECT_ID! });
      const b = await chromium.connectOverCDP(s.connectUrl);
      try {
        const p = b.contexts()[0].pages()[0];
        await p.goto(url, { waitUntil: "domcontentloaded" });
        return { url, title: await p.title() };
      } finally {
        await b.close();
      }
    }));
    settled.forEach((r, j) =>
      out.push(r.status === "fulfilled" ? r.value : { url: batch[j], error: String(r.reason) }));
  }
  return out;
}

Stagehand

Stagehand is installed separately (@browserbasehq/stagehand, which also needs zod). Its constructor changed between major versions, so follow the README of the version you install rather than copying older snippets; the primitives (act, extract, observe) stay the same.

Examples

Example 1: Scrape a page that blocks datacenter IPs

User prompt: "Grab the product titles from this retailer, it blocks my server's IP."

The agent creates a session with proxies: true and a nearby region, connects with chromium.connectOverCDP, extracts titles with page.$$eval, closes the browser, and prints the replay URL. Result: a JSON list of titles; if the run is blocked, the replay shows where.

Example 2: Reuse a logged-in session

User prompt: "Log into our supplier portal once and let nightly jobs reuse it."

The agent creates a context named supplier-portal, runs one interactive login with persist: true, stores the context id in SUPPLIER_CONTEXT_ID, and has nightly jobs create sessions with that context. When the portal expires the cookie, the job reports "login required" instead of retrying blindly.

Guidelines

• Credentials come from environment variables; never commit API keys or put them in page scripts.
• Always close the browser in finally; sessions otherwise run until timeout and count against your concurrency limit.
• Stay within your plan's concurrent-session limit; batch with Promise.allSettled.
• Proxies, CAPTCHA solving and recordings do not make scraping permitted: respect the target's terms and robots rules.
• A recorded session can contain typed passwords or personal data; set recordSession: false for sensitive logins.
• keepAlive, regions and some stealth options depend on the plan; check the dashboard if the API rejects a field.
• For a local one-off script, plain Playwright is simpler and free; use Browserbase when you need scale, proxies or observability.