Browser extensions

Augment your browser sessions with your own Chrome extensions.

You can load your own Chrome extensions into Browserbase sessions.

Sample extension

Here’s a simple example extension that modifies page titles. It consists of two files:

manifest.json

{
  "manifest_version": 3,
  "version": "1.0",
  "name": "My Test Extension",
  "description": "Test of a simple browser extension",
  "content_scripts": [
    {
      "matches": ["https://www.sfmoma.org/*"],
      "js": ["content-script.js"]
    }
  ]
}

You can download this sample extension here. The extension must be in a .zip file format with a manifest.json at the root. The file must be less than or equal to 100 MB.

Upload your extension

Once you have your extension files zipped up, you can upload it using the SDK:

Node.js

Node.js

import { Browserbase } from "@browserbasehq/sdk";
import fs from "fs";

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

const file = fs.createReadStream("extension.zip");
const extension = await bb.extensions.create({ file });

const extensionId = extension.id;
console.log(`Extension uploaded with ID: ${extensionId}`);

Python

Python

from browserbase import Browserbase
import os

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

with open("extension.zip", "rb") as f:
    extension = bb.extensions.create(file=f)

extension_id = extension.id
print(f"Extension uploaded with ID: {extension_id}")

Create a session with your extension

To use your extension, create a new session with the extension enabled:

Node.js

Node.js

import { Browserbase } from "@browserbasehq/sdk";

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

const session = await bb.sessions.create({
  extensionId: "your-extension-id",
});

console.log(`Session created with ID: ${session.id}`);

Python

Python

from browserbase import Browserbase
import os

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

session = bb.sessions.create(extension_id="your-extension-id")

print(f"Session created with ID: {session.id}")

Starting a new session with an extension can increase the session creation time. The browser must be restarted to load the extension, which itself has nonzero load time.

Verify the extension

To verify your extension is working:

1. Connect to your session using Playwright or Selenium
2. Navigate to a page where your extension should be active
3. Check for the expected modifications or behaviors

For the sample extension above, navigate to https://www.sfmoma.org and verify that the page title has been modified with the additional text.

Related guides

Browser contexts

Reuse cookies and browser state across sessions.

Create a browser session

Start a browser session and connect your automation tools.