Browserbase browsers

Browserbase runs hosted Chromium sessions you drive over the Chrome DevTools Protocol. @mayurajs/browser-browserbase plugs Browserbase into mayura/browser, so agents get Browserbase sessions through the same createBrowsers limits, origins and tools as the Chrome installed on your machine. It creates and releases sessions over Browserbase's sessions API with fetch and drives them over CDP: no Browserbase SDK, no other dependencies, and it runs on every runtime Mayura runs on.

#Install

npm install mayura @mayurajs/browser-browserbase

#Credentials

Create an API key in the Browserbase dashboard under Settings. The package sends it as the x-bb-api-key header. It reads nothing from the environment: pass the key in yourself, for example from BROWSERBASE_API_KEY. Sessions go to the key's own project unless you pass projectId.

#Use it

import { browserPerRun, browserTools, createBrowsers } from 'mayura/browser';
import { browserbaseBrowsers } from '@mayurajs/browser-browserbase';

const browsers = createBrowsers(browserbaseBrowsers({ apiKey: process.env.BROWSERBASE_API_KEY ?? '' }), {
  maxBrowsers: 3,
  maxLifetimeMs: 30 * 60_000,
  origins: ['https://example.com', 'https://*.example.com'],
});

const browser = await browsers.open({ lifetimeMs: 10 * 60_000, labels: { team: 'research' } });
try {
  console.log(browser.liveViewUrl); // Browserbase's debugger view: treat it as a secret
  await browser.goto('https://example.com/');
  console.log((await browser.snapshot()).text);
} finally {
  await browser.release();
}

// Or give each run a browser as tools. A run grants tool:web.<tool> for each tool it calls, effect:read and
// browser:web:read; actions such as web.click also need effect:write and browser:web:act.
const perRun = browserPerRun(browsers);
const tools = browserTools(perRun.source, { name: 'web', act: true });

createBrowsers enforces your limits (how many browsers, how long each lives, which origins pages may load from) before Browserbase is called. See Browsers for per-run browsers, every method and every tool.

#Options

#Sessions

• Each browser is one Browserbase session, created when you open it with your viewport and labels (as the session's userMetadata).
• Sessions are not kept alive (keepAlive: false): a session also ends when its connection does.
• The browser's lifetime becomes the session's timeout, rounded up to whole seconds and kept between 1 minute and 6 hours, so Browserbase ends the session even if a release never comes.
• release() asks Browserbase to end the session (REQUEST_RELEASE). If that is refused, the package asks for the session's status: one that is gone or has ended (COMPLETED, TIMED_OUT or ERROR) counts as released.
• Captcha solving, recording and session logs are off, though Browserbase turns them on by default. No proxy is configured.

#Live view and CDP

liveViewUrl is Browserbase's fullscreen debugger view of the session, valid for the browser's lifetime. Anyone with it can watch and use the browser: treat it as a secret, or turn it off with liveView: false. If the package cannot get the view, it releases the session and the open fails.

The CDP endpoint is Browserbase's connect URL. It must be wss:// (plain ws:// only on this machine). Treat it as a secret: Browserbase does not say what it carries, and Mayura never logs it. Each session is yours alone, so browser.cdp is there for another client, such as Stagehand, to drive it alongside.

#Origins

Origins are enforced inside the browser: Mayura intercepts every request the session makes over CDP and blocks those to origins you did not allow, as the guide describes. Should a connection not allow that interception, opening the browser fails rather than running unchecked.

#Errors

Failures reach you as a BrowserError with a reason, mapped from Browserbase's HTTP status. Nothing Browserbase wrote reaches the message.

Configuration mistakes, such as an unknown region or a lifetime under a minute or over 6 hours, fail with INVALID_CONFIG when you call browserbaseBrowsers(), before anything is sent.

#How it is tested

• Unit tests run the package against a fake Browserbase sessions API that checks every request: the session body with captchas, recording and logs off, the timeout bounds, the release, and failures mapped without Browserbase's text.
• The browser conformance suite runs against sessions served by the Chrome or Edge installed on the test machine behind that fake API.
• scripts/live/browser-browserbase.mjs runs the suite's public-page checks on a real Browserbase session (live view, opening and snapshotting a page, origins enforced, following a link and a screenshot): all passed on October 6, 2026.

#Related

• Browsers: limits, origins, per-run browsers and tools.
• Stagehand tools: natural-language tools on a Browserbase browser.
• Live browser viewer: a live view for any browser, local ones included.