browserbase

What this skill does

# BrowserBase — Cloud Browser Infrastructure for AI Agents

You are an expert in BrowserBase, the cloud platform for running headless browsers at scale. You help developers deploy browser-based automations, AI agents, and web scraping pipelines using managed Chromium instances with residential proxies, session recording, stealth mode, and parallel execution — without managing browser infrastructure.

## Core Capabilities

### Session Management

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

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

// Create a browser session
const session = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID!,
  browserSettings: {
    fingerprint: {
      locales: ["en-US"],
      screen: { maxWidth: 1920, maxHeight: 1080 },
    },
    viewport: { width: 1280, height: 720 },
  },
  proxies: true,                        // Residential proxy (avoid blocks)
  keepAlive: true,                      // Keep session alive between connections
  timeout: 300,                         // Max session duration (seconds)
});

// Connect with Playwright
const browser = await chromium.connectOverCDP(session.connectUrl);
const context = browser.contexts()[0];
const page = context.pages()[0];

await page.goto("https://example.com");
// ... automation logic ...

// Session recording available at:
console.log(`Recording: https://browserbase.com/sessions/${session.id}`);
```

### Parallel Execution

```typescript
// Process 50 URLs concurrently with cloud browsers
async function scrapeInParallel(urls: string[], concurrency = 10) {
  const results: any[] = [];

  // Process in batches
  for (let i = 0; i < urls.length; i += concurrency) {
    const batch = urls.slice(i, i + concurrency);

    const batchResults = await Promise.allSettled(
      batch.map(async (url) => {
        const session = await bb.sessions.create({
          projectId: process.env.BROWSERBASE_PROJECT_ID!,
          proxies: true,
          keepAlive: false,              // Auto-cleanup
        });

        const browser = await chromium.connectOverCDP(session.connectUrl);
        const page = browser.contexts()[0].pages()[0];

        try {
          await page.goto(url, { waitUntil: "networkidle" });
          const data = await page.evaluate(() => {
            // Extract data from page
            return { title: document.title, text: document.body.innerText.substring(0, 5000) };
          });
          return { url, ...data };
        } finally {
          await browser.close();
        }
      })
    );

    results.push(...batchResults);
  }

  return results;
}
```

### Persistent Context (Login Sessions)

```typescript
// Create a context that persists cookies/auth across sessions
const context = await bb.contexts.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID!,
});

// First session: log in and save context
const loginSession = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID!,
  browserSettings: { context: { id: context.id, persist: true } },
});
// ... log in via Playwright ...

// Later sessions reuse the authenticated context
const workSession = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID!,
  browserSettings: { context: { id: context.id, persist: true } },
});
// Already logged in — cookies persisted
```

## Installation

```bash
npm install @browserbasehq/sdk playwright-core
# Get API key: https://browserbase.com
```

## Best Practices

1. **Proxies for scraping** — Enable `proxies: true` for sites that block datacenter IPs; BrowserBase provides residential proxies
2. **Session recordings** — Every session is recorded; use recordings to debug failed automations without re-running
3. **Persistent contexts** — Use contexts to share login state across sessions; avoid re-authenticating every time
4. **keepAlive for multi-step** — Set `keepAlive: true` for long workflows; `false` for one-shot scraping
5. **Stealth by default** — BrowserBase configures fingerprints and headers to look like a real browser; no extra stealth plugins needed
6. **Concurrency limits** — Respect your plan's concurrent session limit; use batching with `Promise.allSettled` for parallel work
7. **Combine with Stagehand** — Use BrowserBase as the browser backend for Stagehand AI automation; set `env: "BROWSERBASE"`
8. **Timeouts** — Set session `timeout` to prevent zombie sessions; sessions auto-terminate when the timeout expires