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.

Agent Checklist (Be Proactive)

• - If BROWSERBASE_API_KEY or BROWSERBASE_PROJECT_ID is missing, ask the user for them (and tell them where to find them). Do not run Browserbase commands until both are configured.
• If commands fail due to missing Python deps (ImportError for browserbase / playwright), run:

• - Ask the user what they want to persist and how they want to organize it:

• - Workspaces persist:

• - Prefer workspace commands (create-workspace, start-workspace, resume-workspace, stop-workspace) over raw session commands when the user wants the browser to stay open across chat turns.
• Prefer direct interaction commands (list-tabs, new-tab, switch-tab, close-tab, click, type, press, wait-for, go-back, go-forward, reload, read-page) before falling back to execute-js.
• If a workspace/session has a pending_handoff, check it first before doing anything else:

• - Whenever a browser is opened (start-workspace, resume-workspace, or create-session), immediately share the human remote-control link:

• - When you need the user to perform a manual step (SSO/MFA/captcha/consent screens), use a handoff with a completion check:

• - When closing, use stop-workspace (not terminate-session) so tabs are snapshotted and auth state is persisted.

Prompt-Optimized Response Patterns

Use short, consistent responses so users always know next actions.

When credentials are missing:
CODEBLOCK0

When browser is opened (session/workspace):
CODEBLOCK1

When resuming an existing workspace:
CODEBLOCK2

When a human step is required (SSO/MFA/consent screens):
CODEBLOCK3

When live URL is temporarily unavailable:
CODEBLOCK4

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).

If you have the API key but aren’t sure which Project ID to use, you can list projects:

CODEBLOCK5

Step 2 — Install dependencies

Install Python deps and Playwright Chromium (recommended):

CODEBLOCK6

Manual alternative (pip/uv):

CODEBLOCK7

Step 3 — Set environment variables

CODEBLOCK8

Or configure via OpenClaw's skills.entries["browserbase-sessions"].env in ~/.openclaw/openclaw.json (JSON5). Because this skill sets primaryEnv: BROWSERBASE_API_KEY, you can also use skills.entries["browserbase-sessions"].apiKey for the API key:

CODEBLOCK9

Step 4 — Run the setup test

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

CODEBLOCK10

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 — Browserbase records sessions (video in the Dashboard; rrweb events retrievable via API). Disable with --no-record.
• Session logging: ON — Browserbase captures session logs retrievable via API. Disable with --no-logs.
• Auth persistence — If you use a Context (or Workspace), auth state is persisted by default. Disable persistence with --no-persist.

Capabilities & Limitations (Be Explicit)

The agent can:

• - Create/inspect/terminate Browserbase sessions and contexts.
• Keep a browser “open” across chat turns using workspaces (keep-alive sessions + restore tabs).
• Persist login state across sessions via Browserbase Contexts (persist=true).
• Restore your place by reopening the last saved set of open tabs (URL + title snapshot).
• Provide a live debugger URL so the user can browse manually while the agent continues working.
• Use interactive browser controls: list/open/switch/close tabs, click/type/press keys, wait for selectors/text/url states, go back/forward/reload, and read page text/html/links.
• Take screenshots, run JavaScript, read cookies, fetch logs, and fetch rrweb recording events.

The agent cannot:

• - Keep sessions running indefinitely (Browserbase enforces timeouts; max is 6 hours).
• Restore full back/forward browser history (only open URLs are restored).
• Passively “watch” what the user is doing in the live debugger. To detect human actions, the agent must reconnect and check for specific completion conditions (selector/text/url/cookie/storage) using handoff or wait-for.
• Bypass MFA/SSO without user participation.
• Download the Dashboard video via API (the API returns rrweb events, not a video file).

Available Commands

All commands are run via the manager script:

CODEBLOCK11

Setup & Validation

Install deps (only needed once per environment):
CODEBLOCK12

Run the full setup test:
CODEBLOCK13

Workspaces (Recommended)

Workspaces are the recommended way to keep a browser "open" while chatting and then pick up later. A workspace combines:

• - A Browserbase Context (persists cookies + local/session storage, so you stay logged in)
• A local tab snapshot (URLs + titles) so tabs can be restored into the next session (note: this restores open URLs, not full back/forward browser history)
• The current active session id so the agent can reconnect

Task workspaces (multi-site flows)

A single Browserbase Context is a browser profile, so it can keep you logged into multiple sites at once. For workflows like “do something on Site A, then do something on Site B”, create a task workspace and keep both sites open as tabs:

CODEBLOCK14

If you need account/cookie isolation (different logins, fewer cross-site side effects), use separate workspaces per app/site instead.

Create and start a workspace:
CODEBLOCK15

Note: start-workspace performs a short “warm connect” via Playwright so the session doesn’t die from the 5-minute connect requirement, even if the user hasn’t opened the live debugger yet.

While the user is browsing in the live debugger, the agent can keep working. To resume later:
CODEBLOCK16

For long-running sessions (especially when the user is opening/closing tabs manually), take snapshots periodically:
CODEBLOCK17

To persist login + tabs when you are done, always stop via the workspace command:
CODEBLOCK18

To inspect what a workspace has saved (context id, active session id, tabs, history):
CODEBLOCK19

Most commands accept --workspace <name> instead of --session-id:
CODEBLOCK20

Context Management (for authentication persistence)

Create a named context to store login state:
CODEBLOCK21

List all saved contexts:
CODEBLOCK22

Delete a context (by name or ID):
CODEBLOCK23

Session Lifecycle

Create a new session (captcha solving, recording, and logging enabled by default):
CODEBLOCK24

List all sessions:
CODEBLOCK25

Get session details:
CODEBLOCK26

Terminate a session:
CODEBLOCK27

Browser Automation

Navigate to a URL:
CODEBLOCK28

Manage tabs:
CODEBLOCK29

Interact with the page:
CODEBLOCK30

Control navigation state:
CODEBLOCK31

Read the current page:
CODEBLOCK32

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

Execute JavaScript:
CODEBLOCK34

Get cookies:
CODEBLOCK35

All of the commands above also support --workspace <name> so the active workspace session is used automatically.

Recordings, Logs & Debug

Fetch rrweb recording events (session must be terminated first):
CODEBLOCK36

Download files saved during the session (archive):
CODEBLOCK37

Get session logs:
CODEBLOCK38

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

Human Handoff (Manual Steps)

Use handoff when the user must do something manually (SSO/MFA/consent screens) and you want to detect completion and resume automatically.

Completion checks (pick the most reliable signal you can):

• - Prefer --url-contains for post-login destinations (e.g. /dashboard, /app, /settings).
• Use --selector when the URL doesn’t change (SPAs).
• Use --cookie-name, --local-storage-key, --session-storage-key only when you know a stable auth indicator.

Combining checks:

• - Default is --match all (AND): all provided checks must be true.
• Use --match any (OR) when you want multiple fallback signals (e.g., URL contains /dashboard OR selector .dashboard-ready).

Set a handoff (store the instructions + completion check):
CODEBLOCK40

Fallback example (any-of):
CODEBLOCK41

Tip: handoff --action set returns suggested_user_message.text / suggested_user_message.markdown so you can paste a consistent “hey human do this” message (with the live debugger URL) to the user.

Later, verify once:
CODEBLOCK42

Or wait up to 5 minutes (default) for completion:
CODEBLOCK43

Common Workflows

Workflow 1: Multi-session research with persistent login

CODEBLOCK44

Workflow 1b: Task workflow across multiple sites (persist tabs + logins)

CODEBLOCK45

Workflow 2: Screenshot documentation

CODEBLOCK46

Workflow 3: Record and share a walkthrough

CODEBLOCK47

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. Video is available in the Browserbase Dashboard; get-recording fetches rrweb events (primary tab) for programmatic replay. Use --no-record to disable.
• Logging is ON by default. Use get-logs to retrieve logs; disable with --no-logs.
• Connection timeout: 5 minutes to connect after creation before auto-termination.
• Keep-alive sessions survive disconnections and must be explicitly terminated.
• Context persistence: When a session was created with a context using persist=true (default), wait a few seconds after termination 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.
• Workspace state: Workspaces are stored locally under ~/.browserbase/workspaces/<name>.json (or BROWSERBASE_CONFIG_DIR/workspaces). They include the context id, active session id, and the last saved tab snapshot.
• 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).
• Costs/limits: Your Browserbase plan has limits (browser hours, proxy data, concurrency). Keep-alive sessions consume hours while running; terminate sessions and set reasonable --timeout values to control cost. Check your Browserbase dashboard for current quotas.

Error Handling

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

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

Reference

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