Browserbase Sessions Skill

Manage persistent cloud browser sessions via Browserbase. This skill creates browser sessions that preserve authentication (cookies, local storage) across interactions, automatically solve CAPTCHAs, and record sessions for later review.

First-Time Setup

Step 1 — Get your Browserbase credentials

1. 1. Sign up at browserbase.com if you haven't already.
2. Go to Settings → API Keys and copy your API key (starts with bb_live_).
3. Go to Settings → Project and copy your Project ID (a UUID).

Step 2 — Install dependencies

CODEBLOCK0

Or with uv:

CODEBLOCK1

Step 3 — Set environment variables

CODEBLOCK2

Or configure via OpenClaw's skills.entries.browserbase-sessions.env in ~/.openclaw/openclaw.json.

Step 4 — Run the setup test

This validates everything end-to-end (credentials, SDK, Playwright, API connection, and a live smoke test):

CODEBLOCK3

You should see "status": "success" with all steps passing. If any step fails, the error message tells you exactly what to fix.

Defaults

Every session is created with these defaults to support research workflows:

• - Captcha solving: ON — Browserbase automatically solves CAPTCHAs so login flows and protected pages work without manual intervention. Disable with --no-solve-captchas.
• Session recording: ON — Every session is recorded as a video you can download later for review or sharing. Disable with --no-record.
• Auth persistence — Use contexts with --persist to stay logged in across sessions.

Available Commands

All commands are run via the manager script:

CODEBLOCK4

Setup & Validation

Run the full setup test:
CODEBLOCK5

Context Management (for authentication persistence)

Create a named context to store login state:
CODEBLOCK6

List all saved contexts:
CODEBLOCK7

Delete a context (by name or ID):
CODEBLOCK8

Session Lifecycle

Create a new session (captcha solving and recording enabled by default):
CODEBLOCK9

List all sessions:
CODEBLOCK10

Get session details:
CODEBLOCK11

Terminate a session:
CODEBLOCK12

Browser Automation

Navigate to a URL:
CODEBLOCK13

Take a screenshot of the current page (without navigating):
CODEBLOCK14

Execute JavaScript:
CODEBLOCK15

Get cookies:
CODEBLOCK16

Recordings, Logs & Debug

Download a session recording video (session must be terminated first):
CODEBLOCK17

Get session logs:
CODEBLOCK18

Get the live debug URL (for visual inspection of a running session):
CODEBLOCK19

Common Workflows

Workflow 1: Multi-session research with persistent login

CODEBLOCK20

Workflow 2: Screenshot documentation

CODEBLOCK21

Workflow 3: Record and share a walkthrough

CODEBLOCK22

Important Notes

• - Captcha solving is ON by default. Browserbase handles CAPTCHAs automatically during login flows and page loads. Use --no-solve-captchas to disable.
• Recording is ON by default. Every session is recorded. Download with get-recording after termination. Use --no-record to disable.
• Connection timeout: 5 minutes to connect after creation before auto-termination.
• Keep-alive sessions survive disconnections and must be explicitly terminated.
• Context persistence: Wait a few seconds after terminate-session --persist before creating a new session with the same context.
• Named contexts: Use --name with create-context to save friendly names (e.g. github, slack). Use the name anywhere a context ID is expected.
• One context per site: Use separate contexts for different authenticated sites.
• Avoid concurrent sessions on the same context.
• Regions: us-west-2 (default), us-east-1, eu-central-1, ap-southeast-1.
• Session timeout: 60–21600 seconds (max 6 hours).

Error Handling

All commands return JSON output. On error, the output includes an "error" key. Common errors:

• - APIConnectionError: Browserbase API unreachable
• INLINECODE17: Too many concurrent sessions for your plan
• INLINECODE18: Invalid parameters or authentication failure
• Missing env vars: Set BROWSERBASE_API_KEY and INLINECODE20

Reference

For full API details, read {baseDir}/references/api-quick-ref.md.