How to Manage Browserbase Sessions with the bb CLI

Use the bb sessions subcommands to create, monitor, modify, and terminate remote Chromium instances via the Browserbase cloud platform, utilizing the returned connectUrl as a Chrome DevTools Protocol (CDP) endpoint for tool integration.

The bb CLI, maintained in the browserbase/skills repository, provides a command-line interface to the Browserbase platform API. It allows you to manage short-lived, fully-featured Chromium sessions running in the cloud, complete with configurable proxies, stealth modes, and persistent storage contexts.

Creating a New Session

Run bb sessions create to provision a remote browser instance. According to skills/browserbase-cli/SKILL.md (lines 81-84), this command sends a POST request to the /sessions endpoint and returns JSON containing an id and a connectUrl. The connectUrl serves as a CDP endpoint that automation tools like Playwright, Puppeteer, or the browser skill can attach to.

# Create a session with proxy, stealth, and keep-alive enabled

SESSION_ID=$(bb sessions create \
  --proxies \
  --advanced-stealth \
  --region us-east-1 \
  --keep-alive \
  --timeout 600 \
  --output - | jq -r '.id')

echo "Created session: $SESSION_ID"

Session Configuration Flags

As documented in skills/browserbase-cli/REFERENCE.md (lines 36-49), the create command accepts several flags to customize the browser environment:

• --proxies – Enables Browserbase-managed IP rotation and geo-masking for the session.
• --advanced-stealth – Activates additional anti-bot evasion techniques including user-agent randomization and canvas spoofing.
• --solve-captchas / --no-solve-captchas – Toggles automatic CAPTCHA solving on or off.
• --region <region> – Specifies the data-center location (e.g., us-east-1, eu-central-1).
• --keep-alive – Maintains the session active after client disconnect, useful for background processing.
• --timeout <seconds> – Sets automatic session expiration after the specified duration.
• --persist – Saves cookies and localStorage changes to a Browserbase context for later reuse.
• --context-id <id> – Attaches the session to an existing persistent context rather than creating isolated storage.

Inspecting Session Status

To retrieve a JSON snapshot of a running or completed session, use bb sessions get <session_id>. As noted in skills/browserbase-cli/REFERENCE.md (lines 15-19), the response includes the session status (RUNNING, COMPLETED, etc.), proxy configuration, viewport dimensions, and any associated persisted context data.

bb sessions get "$SESSION_ID"

Updating and Controlling Sessions

You can modify an active session's configuration or request a graceful shutdown using bb sessions update. The CLI merges supplied flags with the existing session body, as implemented in REFERENCE.md (lines 52-55). To terminate a session and release cloud resources, update the status to REQUEST_RELEASE.

# Gracefully shut down a session

bb sessions update "$SESSION_ID" --status REQUEST_RELEASE

For interactive debugging, bb sessions debug opens the DevTools UI for the specified session while it runs.

Connecting External Tools via CDP

The connectUrl returned upon creation enables direct attachment via the Chrome DevTools Protocol. You can pass this endpoint to Playwright using chromium.connectOverCDP(), or use it with the browse sub-command (bb browse env remote), as referenced in SKILL.md (lines 60-62).

import { chromium } from 'playwright';
import { readFileSync } from 'fs';

const session = JSON.parse(readFileSync('session.json'));
const browser = await chromium.connectOverCDP(session.connectUrl);
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
await browser.close();

First generate the session file:

bb sessions get "$SESSION_ID" > session.json
node attach.mjs

Persisting State Across Sessions

To maintain cookies and localStorage between automation runs, combine the --persist flag with a --context-id. This saves session state to a named Browserbase context that subsequent sessions can attach to, eliminating the need to re-authenticate or reconfigure browser state.

# Create a session attached to an existing persistent context

bb sessions create \
  --context-id ctx_12345 \
  --persist \
  --proxies \
  --region eu-central-1

Retrieving Artifacts and Logs

After a session completes, download captured files, logs, or screenshot archives using bb sessions downloads get. As documented in REFERENCE.md (lines 26-28), this command retrieves artifacts generated during the session lifecycle.

bb sessions downloads get "$SESSION_ID" --output session-artifacts.zip

Summary

• Create sessions with bb sessions create, capturing the connectUrl for CDP-based tool integration.
• Configure stealth, proxies, regions, and persistence using flags defined in skills/browserbase-cli/REFERENCE.md.
• Monitor session health and metadata via bb sessions get <id>.
• Update session parameters or trigger graceful termination with bb sessions update --status REQUEST_RELEASE.
• Persist authentication state across runs using --persist and --context-id.
• Download session artifacts after termination using bb sessions downloads get.

Frequently Asked Questions

How do I keep a Browserbase session alive after my script disconnects?

Use the --keep-alive flag when creating the session. This prevents the cloud infrastructure from terminating the Chromium instance when your local client disconnects, allowing background tasks to continue or enabling reconnection via the connectUrl later.

Can I reuse cookies and login state between different bb CLI sessions?

Yes. Create a session with both --persist and --context-id <id> flags. The --persist flag saves cookies and localStorage to the specified context ID, which you can reference in subsequent bb sessions create commands to restore that browser state.

What is the connectUrl used for in the bb sessions create response?

The connectUrl is a WebSocket endpoint implementing the Chrome DevTools Protocol (CDP). You pass this URL to automation libraries like Playwright (chromium.connectOverCDP()), Puppeteer, or Selenium to control the remote browser directly as if it were a local instance.

How do I gracefully terminate a session and download its artifacts?

First, update the session status to REQUEST_RELEASE using bb sessions update <id> --status REQUEST_RELEASE. Once the session status changes to COMPLETED, retrieve any generated files using bb sessions downloads get <id> --output <filename>.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}