Browserbase wrapper

If you use the Browserbase SDK today, point it at ${BANANA_PEEL_BASE}/api with your bp_live_… key and keep the rest of your code: Banana Peel exposes a Browserbase-compatible sessions API at /api/v1/sessions (note: not /api/wrappers/browserbase — that path 404s). Sessions are proxied to a real Browserbase account, so CDP and Playwright keep working. A CDP session is inherently one concrete browser, so sessions always run on Browserbase — smart routing across runners applies to agent tasks via POST /api/v1/responses. A session is a live browser you hold open and drive yourself; it is not a routed run — see Runs vs. sessions.

Why wrap vs call Responses directly

Use the Browserbase wrapper when you already have Browserbase client code and want the smallest diff: same method names / request shapes, Banana Peel key + base URL, optional routing. Use POST /api/v1/responses for new work — one API for smart routing, benchmarks, MFA input, and run inspection. Wrappers are a migration bridge, not the long-term product surface.

Install

Keep npm install @browserbasehq/sdk and only change constructor options, or
Path-install the helper: npm install ./packages/wrappers/browserbase (@bananapeel/browserbase) for browserbaseSdkOptions() + a thin sessions client

Before → after

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

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

const session = await bb.sessions.create({ projectId: "your_project_id" });
const browser = await chromium.connectOverCDP(session.connectUrl);

Auth & base URL

Agents: npx -y @banana-peel/cli init --agent --json (see /docs/agents). Humans who already have an account can copy a key from the keys console: bp_live_… (or bp_test_…).

Env: BANANA_PEEL_API_KEY, optional BANANA_PEEL_BASE (defaults to the production Cloud Run URL)
Headers: Authorization: Bearer …, x-api-key, or vendor-shaped X-BB-API-Key
HTTP base for this wrapper: ${BANANA_PEEL_BASE}/api

The official SDK sends X-BB-API-Key; Banana Peel also accepts Bearer bp_live_…. Base URL must end at /apiso the SDK's /v1/sessions path resolves to /api/v1/sessions.

API mapping

Browserbase	Banana Peel
sessions.create	POST /api/v1/sessions
sessions.retrieve / list	GET /api/v1/sessions[/:id]
projectId	Stripped server-side (cross-account); optional in create
connectUrl / CDP	Proxied real Browserbase endpoint
Agent task (Stagehand and similar)	Prefer `POST /api/v1/responses` — `routing: "smart"` by default, or pin `"browserbase"` for parity

Limits / gaps

Not every Browserbase sub-resource is guaranteed (extensions, some debug edges) — session create/list/get/CDP is the supported core.
Your Browserbase project billing moves behind Banana Peel's upstream account when proxied.
Optional Deck-routed sessions via headers / userMetadata — see sessions docs; different from a pure BB proxy create.

Legacy URL /docs/browserbase redirects here.