The Connect API is available both as:

  • a WebSocket endpoint: wss://connect.browserbase.com
  • an HTTP endpoint: http://connect.browserbase.com/webdriver

Puppeteer and Playwright connect over the WebSocket API while Selenium relies on the HTTP API.

Puppeteer and Playwright: Connect over WebSocket

Authentication

The Connect WebSocket API authentication relies on the apiKey query parameter as follows:

import { chromium } from "playwright-core";

(async () => {
  const browser = await chromium.connectOverCDP(
    `wss://connect.browserbase.com?apiKey=${process.env.BROWSERBASE_API_KEY}`,
  );

  // ...
})();

Available query parameters

On top of the apiKey query parameter, the wss://connect.browserbase.com endpoints offers the following optional parameters:

sessionId
string

You can pass the ID of an already created Session.

enableProxy
boolean
default: "false"

Enable proxy by passing &enableProxy=true. Learn more about Proxying.

Selenium: Connect over HTTP

Custom HTTP Agent and Authentication

Selenium Node.js and Python do not yet support connecting over a WebSocket. Instead, you’ll need a provide a custom HTTP Agent that provide the required authentication header (x-bb-api-key) to connect to the http://connect.browserbase.com/webdriver endpoint as follows:

import http from "http";
import webdriver from "selenium-webdriver";
import chrome from "selenium-webdriver/chrome";

async function createSession() {
  const response = await fetch(`https://www.browserbase.com/v1/sessions`, {
    method: "POST",
    headers: {
      "x-bb-api-key": process.env.BROWSERBASE_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ projectId: process.env.BROWSERBASE_PROJECT_ID }),
  });
  return await response.json();
}

(async () => {
  const session = await createSession();

  const customHttpAgent = new http.Agent({});
  (customHttpAgent as any).addRequest = (req: any, options: any) => {
    // Session ID needs to be set here
    req.setHeader("session-id", session.id);
    req.setHeader("x-bb-api-key", process.env.BROWSERBASE_API_KEY);
    (http.Agent.prototype as any).addRequest.call(
      customHttpAgent,
      req,
      options,
    );
  };

  // We set a debuggerAddress so the server-side WebDriver can connect.
  const options = new chrome.Options();
  options.debuggerAddress("localhost:9223");

  const driver = new webdriver.Builder()
    .forBrowser("chrome")
    .setChromeOptions(options)
    .usingHttpAgent(customHttpAgent)
    .usingServer(
      `http://connect.browserbase.com/webdriver`, // Selenium only supports HTTP
    )
    .build();

  await driver.get("https://www.browserbase.com");

  // Make sure to quit the driver so your session is ended!
  await driver.quit();
})().catch((error) => console.error(error.message));

Available headers parameters

session-id
string
required

The Session ID created via the HTTP API.

enable-proxy
string
default: "false"

Enable proxy by passing the enable-proxy header. Learn more about Proxying.