How to Use Proxies with Browserbase (2026 Guide)

By Nicholas St. Germain — February 1, 2026

Browserbase is a cloud browser platform designed for AI agents and browser automation. Instead of launching headless Chrome on your own infrastructure, you create a session through the Browserbase API and connect to it via CDP (Chrome DevTools Protocol). The browser runs in Browserbase's cloud, and you control it with Playwright, Puppeteer, or any CDP-compatible tool.

One of Browserbase's most useful features is built-in proxy support. You can route session traffic through managed residential proxies, specify geographic locations, bring your own custom proxies, or combine multiple proxies with domain-based routing rules - all configured at session creation time. No browser flags, no extensions, no system-level proxy settings.

This guide covers every proxy configuration pattern Browserbase supports, with complete code examples for Node.js and Python.

Why Use Proxies with Browserbase

If you're running browser automation at any scale, you've likely hit IP-based blocking. Websites detect and throttle datacenter IPs, flag repeated requests from the same address, and serve different content based on geographic location.

Browserbase sessions run on cloud infrastructure, which means the default IP is a datacenter IP - exactly the kind that anti-bot systems are built to detect. Adding a proxy layer solves this:

• Residential IP classification: Proxied sessions appear to originate from consumer ISPs rather than cloud providers
• Geographic targeting: Access region-specific content, pricing, or search results by routing through proxies in specific countries, states, or cities
• IP rotation across sessions: Each session can use a different proxy, distributing your traffic across many IPs
• Custom proxy integration: Bring your own proxy infrastructure for compliance, performance, or provider preference

The proxy is configured when you create the session - no code changes to your Playwright scripts beyond the session setup.

Prerequisites

Before starting, you'll need:

1. A Browserbase account (Developer plan or higher for proxy access)
2. Your BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID from the Browserbase dashboard
3. The Browserbase SDK installed:

# Node.js
npm install @browserbasehq/sdk playwright-core

# Python
pip install browserbase playwright

How Browserbase Sessions Work (Quick Primer)

If you're new to Browserbase, here's the basic pattern. You create a session through the SDK, which returns a connection URL. You then connect Playwright to that URL via CDP:

Node.js:

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

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

const session = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID,
});

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

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

await page.close();
await browser.close();

Python:

from playwright.sync_api import sync_playwright
from browserbase import Browserbase
import os

bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])

session = bb.sessions.create(
    project_id=os.environ["BROWSERBASE_PROJECT_ID"]
)

with sync_playwright() as pw:
    browser = pw.chromium.connect_over_cdp(session.connect_url)
    context = browser.contexts[0]
    page = context.pages[0]

    page.goto("https://example.com")
    print(page.title())

    page.close()
    browser.close()

All proxy configuration happens inside bb.sessions.create(). The rest of your Playwright code stays the same regardless of which proxy setup you use.

Built-in Proxies (Simplest Option)

The easiest way to proxy a Browserbase session is to set proxies: true. Browserbase routes traffic through its managed residential proxy network, defaulting to a US-based proxy.

Node.js:

const session = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID,
  proxies: true,
});

Python:

session = bb.sessions.create(
    project_id=os.environ["BROWSERBASE_PROJECT_ID"],
    proxies=True,
)

That's it. Every request in this session routes through a residential proxy. Your Playwright code doesn't change at all - connect to session.connectUrl and interact with pages as usual.

A few things to note about the built-in proxies:

• They default to US-based residential IPs
• If nearby US proxies are unavailable, Browserbase may route through nearby countries (like Canada)
• Proxy billing has a 1 MB minimum per session, with subsequent usage rounded to the nearest MB
• You need a Developer plan or higher for proxy access

Geolocation-Specific Proxies

When you need traffic to appear from a specific location - a particular country, US state, or city - pass a proxy configuration array with geolocation details instead of proxies: true.

Node.js:

const session = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID,
  proxies: [
    {
      type: "browserbase",
      geolocation: {
        city: "NEW_YORK",
        state: "NY",
        country: "US",
      },
    },
  ],
});

Python:

session = bb.sessions.create(
    project_id=os.environ["BROWSERBASE_PROJECT_ID"],
    proxies=[
        {
            "type": "browserbase",
            "geolocation": {
                "city": "NEW_YORK",
                "state": "NY",
                "country": "US",
            },
        },
    ],
)

Geolocation Rules

• Country: ISO 3166-1 alpha-2 code ("US", "GB", "JP", "BR", etc.). Browserbase supports over 200 countries.
• State: 2-character US state code ("NY", "CA", "TX"). Only valid when country is "US".
• City: Uppercase city name ("NEW_YORK", "LONDON", "TOKYO", "SAO_PAULO").
• All fields are case-insensitive.
• If no proxy is available in the exact specified location, Browserbase uses the closest available proxy.

Example: International Locations

// London, UK
proxies: [{ type: "browserbase", geolocation: { city: "LONDON", country: "GB" } }]

// Tokyo, Japan
proxies: [{ type: "browserbase", geolocation: { city: "TOKYO", country: "JP" } }]

// São Paulo, Brazil
proxies: [{ type: "browserbase", geolocation: { city: "SAO_PAULO", country: "BR" } }]

// Country-level only (any city in Germany)
proxies: [{ type: "browserbase", geolocation: { country: "DE" } }]

Geolocation proxies are essential for testing localized content, verifying geo-targeted ads, scraping region-specific pricing, or any workflow where the IP's geographic origin matters.

Custom (External) Proxies

If you have your own proxy infrastructure - or use a dedicated proxy provider like Stat Proxies - you can route Browserbase sessions through your own proxies instead of the built-in ones.

Node.js:

const session = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID,
  proxies: [
    {
      type: "external",
      server: "http://us.statproxies.com:3128",
      username: "your_user",
      password: "your_pass",
    },
  ],
});

Python:

session = bb.sessions.create(
    project_id=os.environ["BROWSERBASE_PROJECT_ID"],
    proxies=[
        {
            "type": "external",
            "server": "http://us.statproxies.com:3128",
            "username": "your_user",
            "password": "your_pass",
        },
    ],
)

Why Use Custom Proxies?

• ISP proxy quality: Browserbase's built-in proxies are residential, but you may want static ISP proxies for session persistence across multiple Browserbase sessions. With a Stat Proxies ISP proxy, the same IP is used every time you create a session with that proxy - useful for account management workflows where IP consistency matters.
• Compliance: Your organization may require traffic to route through approved infrastructure.
• Performance: A proxy closer to your target site or with lower latency than the built-in option.
• Provider preference: You already have a proxy provider you trust and want to use it with Browserbase's browser infrastructure.

Validation

Browserbase validates the proxy connection at session creation time. If it can't connect to your proxy server, the session creation fails with an error. Make sure your proxy is accessible from Browserbase's infrastructure and that the credentials are correct before creating the session.

You can verify your proxy works independently with cURL first:

curl -x http://your_user:your_pass@us.statproxies.com:3128 https://ipinfo.io

For more on proxy testing, see our cURL proxy testing guide.

Domain-Based Proxy Routing

Browserbase's most powerful proxy feature is domain-based routing - you can configure multiple proxies and route traffic to specific proxies based on URL patterns. The first matching rule wins, and you can include a fallback browserbase proxy for unmatched traffic.

Node.js:

const session = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID,
  proxies: [
    {
      type: "external",
      server: "http://us.statproxies.com:3128",
      username: "your_user",
      password: "your_pass",
      domainPattern: "amazon\\.com",
    },
    {
      type: "external",
      server: "http://eu.statproxies.com:3128",
      username: "your_user",
      password: "your_pass",
      domainPattern: ".*\\.co\\.uk",
    },
    {
      type: "browserbase",
    },
  ],
});

Python:

session = bb.sessions.create(
    project_id=os.environ["BROWSERBASE_PROJECT_ID"],
    proxies=[
        {
            "type": "external",
            "server": "http://us.statproxies.com:3128",
            "username": "your_user",
            "password": "your_pass",
            "domainPattern": "amazon\\.com",
        },
        {
            "type": "external",
            "server": "http://eu.statproxies.com:3128",
            "username": "your_user",
            "password": "your_pass",
            "domainPattern": ".*\\.co\\.uk",
        },
        {
            "type": "browserbase",
        },
    ],
)

In this configuration:

• Requests to amazon.com route through the US Stat Proxies ISP proxy
• Requests to any .co.uk domain route through the EU proxy
• All other requests fall back to Browserbase's built-in residential proxy

Routing Rules

• domainPattern is a regex pattern matched against the request domain
• Rules are evaluated in order - the first match wins
• A browserbase type entry without a domainPattern acts as the catch-all fallback
• If no rule matches and there's no fallback, the request goes directly without a proxy

This is useful for workflows where different targets need different proxy types. For example, you might route a heavily-protected e-commerce site through a high-quality ISP proxy while letting less-protected API calls go through the built-in residential proxy.

Combining Proxies with Other Browserbase Features

Proxy configuration works alongside other Browserbase session options. Here's a more complete session setup combining proxies with other commonly used features:

const session = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID,
  proxies: [
    {
      type: "external",
      server: "http://us.statproxies.com:3128",
      username: "your_user",
      password: "your_pass",
    },
  ],
  browserSettings: {
    fingerprint: {
      browsers: ["chrome"],
      operatingSystems: ["macos"],
    },
  },
  keepAlive: true,
});

The keepAlive option is particularly relevant when using proxies - it prevents the session from timing out, allowing you to reconnect to the same session (and same proxy) later. Useful for multi-step workflows where you need to maintain session state and IP consistency.

Practical Example: Verifying Your Proxy Setup

Here's a complete script that creates a proxied session, navigates to an IP check service, and confirms the proxy is working:

Node.js:

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

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

async function verifyProxy() {
  // Create session with custom proxy
  const session = await bb.sessions.create({
    projectId: process.env.BROWSERBASE_PROJECT_ID,
    proxies: [
      {
        type: "external",
        server: "http://us.statproxies.com:3128",
        username: "your_user",
        password: "your_pass",
      },
    ],
  });

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

  // Check IP
  await page.goto("https://ipinfo.io/json");
  const ipInfo = await page.evaluate(() => document.body.innerText);
  console.log("IP Info:", JSON.parse(ipInfo));

  // Check for WebRTC leaks
  await page.goto("https://browserleaks.com/webrtc");
  await page.waitForTimeout(3000);
  const title = await page.title();
  console.log("WebRTC check page loaded:", title);

  await page.close();
  await browser.close();

  console.log(
    "Session replay:",
    `https://browserbase.com/sessions/${session.id}`
  );
}

verifyProxy();

Python:

from playwright.sync_api import sync_playwright
from browserbase import Browserbase
import json
import os

bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])

def verify_proxy():
    session = bb.sessions.create(
        project_id=os.environ["BROWSERBASE_PROJECT_ID"],
        proxies=[
            {
                "type": "external",
                "server": "http://us.statproxies.com:3128",
                "username": "your_user",
                "password": "your_pass",
            },
        ],
    )

    with sync_playwright() as pw:
        browser = pw.chromium.connect_over_cdp(session.connect_url)
        context = browser.contexts[0]
        page = context.pages[0]

        page.goto("https://ipinfo.io/json")
        ip_info = json.loads(page.evaluate("document.body.innerText"))
        print("IP Info:", ip_info)

        page.close()
        browser.close()

    print(f"Session replay: https://browserbase.com/sessions/{session.id}")

verify_proxy()

When the proxy is working correctly, the ipinfo.io response should show your proxy's IP, a residential ISP name (if using ISP proxies), and the proxy's geographic location - not the Browserbase datacenter's IP.

Choosing the Right Proxy Type for Browserbase

For account management and AI agent use cases where IP consistency matters across sessions, ISP proxies from a provider like Stat Proxies are the best fit. The static IP means every Browserbase session using that proxy exits from the same address, building long-term IP reputation with target sites. For more on how AI agents benefit from static ISP proxies, see our guide to building proxy infrastructure for AI agents.

Troubleshooting

Session Creation Fails with Proxy Error

Browserbase validates the proxy connection when creating the session. Common causes:

• Wrong proxy URL format: The server field should be a full URL including protocol and port (e.g., http://proxy.example.com:3128)
• Invalid credentials: Double-check username and password
• Proxy not reachable: Browserbase's infrastructure needs to reach your proxy. If your proxy is behind a firewall with IP whitelisting, you may need to whitelist Browserbase's IP ranges
• Unsupported proxy provider: Browserbase notes that not all proxy providers are supported with external proxies. Test with a simple HTTP proxy first

Getting the Wrong IP / Proxy Not Applied

Navigate to https://ipinfo.io/json in your session and check the response. If you see a datacenter IP instead of your proxy:

• Verify your session was created with the proxies parameter (it defaults to false)
• Check domain routing rules - your target domain may not match any domainPattern, causing direct connection

Slow Proxied Sessions

All proxied traffic adds a hop, which increases latency. To minimize impact:

• Use a proxy geographically close to the Browserbase session and your target site
• For external proxies, ensure your proxy server has adequate bandwidth
• Consider whether you need a proxy for every request - domain-based routing lets you proxy only the requests that need it

Proxy Works in cURL but Not in Browserbase

Some proxy providers have restrictions on the types of clients or connection patterns they support. Browserbase connects to your proxy from its own cloud infrastructure, not from your local machine. Ensure your proxy provider doesn't restrict connections by source IP or require specific headers.

For additional proxy debugging, use Browserbase's session replay feature - view the full session recording at https://browserbase.com/sessions/{session_id} to see exactly what happened, including network requests and timing. For general proxy testing tips, see our cURL proxy testing guide.

Summary

Browserbase makes proxy configuration a session-level concern rather than a browser configuration headache. No extensions, no OS settings, no launch flags - just pass the proxy config when creating a session and your Playwright code handles the rest.

The three main patterns:

1. proxies: true for quick residential proxy coverage
2. Geo-targeted browserbase proxies for location-specific access
3. External proxies for ISP-quality IPs, compliance, or provider preference

For domain-specific routing, combine multiple proxies in the array with domainPattern regex rules.

If you need static ISP proxies that provide consistent IP identity across Browserbase sessions, check out Stat Proxies ISP plans - unlimited bandwidth, Tier 1 ISP classification, and they work out of the box as external proxies in Browserbase.