Skip to main content
If you are working with Node.js, the official @browserbasehq/sdk package is the easiest way to connect and act upon headless browsers running on Browserbase.

​
Installation

npm install -S @browserbasehq/sdk

​
Basic usage

Here is an example using the Browserbase Node.js SDK to create and connect to a session using Playwright: 
import { chromium } from "playwright-core";
import Browserbase from "@browserbasehq/sdk";

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

// Create a new session
const session = await bb.sessions.create();

// Connect to the session
const browser = await chromium.connectOverCDP(session.connectUrl);

// Getting the default context to ensure the sessions are recorded
const defaultContext = browser.contexts()[0];
const page = defaultContext.pages()[0];

await page.goto("https://news.ycombinator.com/");
await page.close();
await browser.close();

console.log(`Session complete! View replay at https://browserbase.com/sessions/${session.id}`);

​
Session Configuration

When creating a session, you can pass various configuration options to customize the browser behavior.

​
All Configuration Options

const session = await bb.sessions.create({
  // Project ID (optional - inferred from API key if not provided)
  projectId: "your-project-id",

  // Proxy configuration
  proxies: true, // Use default proxy

  // Region where the session runs
  region: "us-west-2",

  // Keep session alive after disconnection
  keepAlive: true,

  // Session timeout in seconds (60-21600)
  timeout: 3600,

  // Extension ID (uploaded via Upload Extension API)
  extensionId: "ext_abc123",

  // Browser settings
  browserSettings: {
    // Toggle features
    blockAds: true,
    solveCaptchas: true,
    recordSession: true,
    logSession: true,
    advancedStealth: true,

    // Operating system (only available with advancedStealth)
    // Controls user agent and environment signals
    os: "windows",

    // Context for session persistence
    context: {
      id: "my-context-id",
      persist: true,
    },

    // Viewport configuration (ignored when advancedStealth is enabled)
    viewport: {
      width: 1920,
      height: 1080,
    },

    // Custom captcha selectors
    captchaImageSelector: "#captcha-image",
    captchaInputSelector: "#captcha-input",
  },

  // Custom metadata for the session
  userMetadata: {
    userId: "user_123",
    taskName: "scraping-job",
  },
});

​
Proxy Configuration

You can configure proxies as a boolean or as an array for more control: 
// Using Browserbase managed proxy with geolocation
const session = await bb.sessions.create({
  proxies: [
    {
      type: "browserbase",
      geolocation: {
        country: "US",
        state: "CA",
        city: "San Francisco",
      },
    },
  ],
});

// Using external proxy
const session = await bb.sessions.create({
  proxies: [
    {
      type: "external",
      server: "http://proxy.example.com:8080",
      username: "user",
      password: "pass",
      domainPattern: "*.example.com",
    },
  ],
});

// Multiple proxies with domain patterns
const session = await bb.sessions.create({
  proxies: [
    {
      type: "browserbase",
      geolocation: { country: "US" },
      domainPattern: "*.google.com",
    },
    {
      type: "external",
      server: "http://proxy.example.com:8080",
      domainPattern: "*.example.com",
    },
  ],
});

​
Common Configuration Examples

// Stealth mode with proxy
const session = await bb.sessions.create({
  proxies: true,
  browserSettings: {
    advancedStealth: true,
    os: "windows",
  },
});

// Long-running session with keep-alive
const session = await bb.sessions.create({
  timeout: 21600, // 6 hours
  keepAlive: true,
});

// Session with context persistence
const session = await bb.sessions.create({
  browserSettings: {
    context: {
      id: "user-session-context",
      persist: true,
    },
  },
});

// Custom viewport and ad blocking
const session = await bb.sessions.create({
  browserSettings: {
    viewport: { width: 1440, height: 900 },
    blockAds: true,
  },
});

// Mobile viewport
const session = await bb.sessions.create({
  browserSettings: {
    viewport: { width: 390, height: 844 },
  },
});

// Session in specific region with metadata
const session = await bb.sessions.create({
  region: "eu-central-1",
  userMetadata: {
    jobId: "job_456",
    environment: "production",
  },
});

Examples

Quickstart examples using captcha solving, proxies, extensions, and more

NPM Package

View the package on NPM

SDK Reference

View the complete SDK reference documentation