Claude-skill-registry browserbase

Cloud browser infrastructure for AI agents - create sessions, persist contexts, and automate browsers

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/browserbase" ~/.claude/skills/majiayu000-claude-skill-registry-browserbase && rm -rf "$T"

manifest: skills/data/browserbase/SKILL.md

Browserbase

Cloud browser infrastructure for AI agents and automation. Create browser sessions, persist authentication with contexts, debug live sessions, and retrieve session recordings.

Official docs: https://docs.browserbase.com/

When to Use

Use this skill when you need to:

Create cloud browser sessions for Playwright/Puppeteer automation
Persist login state and cookies across sessions using Contexts
Debug browser sessions in real-time with live URLs
Retrieve session recordings and logs for debugging
Manage browser sessions programmatically (list, get, update)
Run browser automation with proxy and stealth support

Prerequisites

Create an account at https://www.browserbase.com/
Get your API Key from the dashboard Settings page
Get your Project ID from the dashboard Settings page

Set environment variables:

export BROWSERBASE_API_KEY="your-api-key-here"
export BROWSERBASE_PROJECT_ID="your-project-id-here"

Note: Free plans have a concurrent session limit of 1. You'll receive a 429 error if you exceed this limit. Check your plan details in the Browserbase dashboard.

Important: When using
$VAR
in a command that pipes to another command, wrap the command containing
$VAR
in
bash -c '...'
. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.
bash -c 'curl -s "https://api.example.com" --header "X-BB-API-Key: $BROWSERBASE_API_KEY"'

How to Use

1. Create a Session

Create a new browser session:

Write

/tmp/request.json

{
  "projectId": "<your-project-id>"
}

bash -c 'curl -s -X POST "https://api.browserbase.com/v1/sessions" --header "Content-Type: application/json" --header "X-BB-API-Key: $BROWSERBASE_API_KEY" -d @/tmp/request.json'

With timeout and keepAlive:

Write

/tmp/request.json

{
  "projectId": "<your-project-id>",
  "timeout": 300,
  "keepAlive": true
}

bash -c 'curl -s -X POST "https://api.browserbase.com/v1/sessions" --header "Content-Type: application/json" --header "X-BB-API-Key: $BROWSERBASE_API_KEY" -d @/tmp/request.json'

With proxy enabled (requires paid plan):

Write

/tmp/request.json

{
  "projectId": "<your-project-id>",
  "proxies": true
}

bash -c 'curl -s -X POST "https://api.browserbase.com/v1/sessions" --header "Content-Type: application/json" --header "X-BB-API-Key: $BROWSERBASE_API_KEY" -d @/tmp/request.json'

Note: Proxies are not available on the free plan. You'll receive a 402 error if you try to use this feature without upgrading.

With specific region (us-west-2, us-east-1, eu-central-1, ap-southeast-1):

Write

/tmp/request.json

{
  "projectId": "<your-project-id>",
  "region": "us-west-2"
}

bash -c 'curl -s -X POST "https://api.browserbase.com/v1/sessions" --header "Content-Type: application/json" --header "X-BB-API-Key: $BROWSERBASE_API_KEY" -d @/tmp/request.json'

Response includes:

```
id
```
- Session ID to use for connections
```
connectUrl
```
- WebSocket URL for Playwright/Puppeteer
```
seleniumRemoteUrl
```
- URL for Selenium connections
```
signingKey
```
- Key for HTTP connections

2. List Sessions

List all sessions with optional filters:

bash -c 'curl -s -X GET "https://api.browserbase.com/v1/sessions" --header "X-BB-API-Key: $BROWSERBASE_API_KEY"'

Filter by status (RUNNING, ERROR, TIMED_OUT, COMPLETED):

bash -c 'curl -s -X GET "https://api.browserbase.com/v1/sessions?status=RUNNING" --header "X-BB-API-Key: $BROWSERBASE_API_KEY"'

Query by user metadata:

Note: The query syntax for user metadata filtering uses single quotes:
user_metadata['key']:'value'
. To avoid complex shell escaping, write the query to a file and use
--data-urlencode "q@filename"
.

Write

/tmp/query.txt

with content:

user_metadata['test']:'true'

Then query sessions:

bash -c 'curl -s -X GET -G "https://api.browserbase.com/v1/sessions" --data-urlencode "q@/tmp/query.txt" --header "X-BB-API-Key: $BROWSERBASE_API_KEY"'

More examples:

Query by stagehand metadata - write

/tmp/query.txt

user_metadata['stagehand']:'true'

Query by environment - write

/tmp/query.txt

user_metadata['env']:'production'

Then run:

bash -c 'curl -s -X GET -G "https://api.browserbase.com/v1/sessions" --data-urlencode "q@/tmp/query.txt" --header "X-BB-API-Key: $BROWSERBASE_API_KEY"'

3. Get Session Details

Get details of a specific session. Replace

<your-session-id>

with the actual session ID:

bash -c 'curl -s -X GET "https://api.browserbase.com/v1/sessions/<your-session-id>" --header "X-BB-API-Key: $BROWSERBASE_API_KEY"'

4. Update Session (Release)

Request to release a session before its timeout to avoid additional charges. Replace

<your-session-id>

with the actual session ID:

Write

/tmp/request.json

{
  "status": "REQUEST_RELEASE"
}

bash -c 'curl -s -X POST "https://api.browserbase.com/v1/sessions/<your-session-id>" --header "Content-Type: application/json" --header "X-BB-API-Key: $BROWSERBASE_API_KEY" -d @/tmp/request.json'

The session status will change to

COMPLETED

and

endedAt

timestamp will be set.

5. Get Debug/Live URLs

Get live debugging URLs for a running session. Replace

<your-session-id>

with the actual session ID:

bash -c 'curl -s -X GET "https://api.browserbase.com/v1/sessions/<your-session-id>/debug" --header "X-BB-API-Key: $BROWSERBASE_API_KEY"'

Note: Debug URLs may only be available after a browser client has connected to the session via WebSocket.

Response includes:

```
debuggerUrl
```
- Chrome DevTools debugger URL
```
debuggerFullscreenUrl
```
- Fullscreen debugger view
```
wsUrl
```
- WebSocket URL
```
pages
```
- Array of open pages with their debugger URLs

6. Get Session Logs

Retrieve logs from a session. Replace

<your-session-id>

with the actual session ID:

bash -c 'curl -s -X GET "https://api.browserbase.com/v1/sessions/<your-session-id>/logs" --header "X-BB-API-Key: $BROWSERBASE_API_KEY"'

7. Get Session Recording

Get the rrweb recording of a session. Replace

<your-session-id>

with the actual session ID:

bash -c 'curl -s -X GET "https://api.browserbase.com/v1/sessions/<your-session-id>/recording" --header "X-BB-API-Key: $BROWSERBASE_API_KEY"'

8. Get Session Downloads

Retrieve files downloaded during a session (returns ZIP file). Replace

<your-session-id>

with the actual session ID:

bash -c 'curl -s -X GET "https://api.browserbase.com/v1/sessions/<your-session-id>/downloads" --header "X-BB-API-Key: $BROWSERBASE_API_KEY"' --output downloads.zip

9. Upload Files to Session

Upload files to use in a browser session. Replace

<your-session-id>

with the actual session ID:

bash -c 'curl -s -X POST "https://api.browserbase.com/v1/sessions/<your-session-id>/uploads" --header "X-BB-API-Key: $BROWSERBASE_API_KEY" -F "file=@/path/to/file.pdf"'

Contexts API

Contexts allow you to persist cookies, cache, and session storage across multiple browser sessions.

Create a Context

Write

/tmp/request.json

{
  "projectId": "<your-project-id>"
}

bash -c 'curl -s -X POST "https://api.browserbase.com/v1/contexts" --header "Content-Type: application/json" --header "X-BB-API-Key: $BROWSERBASE_API_KEY" -d @/tmp/request.json'

Save the returned

id

to use in sessions.

Get Context Details

Retrieve details of a specific context. Replace

<your-context-id>

with the actual context ID:

bash -c 'curl -s -X GET "https://api.browserbase.com/v1/contexts/<your-context-id>" --header "X-BB-API-Key: $BROWSERBASE_API_KEY"'

Response includes:

```
id
```
- Context identifier
```
createdAt
```
- Creation timestamp
```
updatedAt
```
- Last update timestamp
```
projectId
```
- The Project ID linked to the context

Create Session with Context

Use an existing context to restore cookies and login state. Replace

<your-context-id>

with the actual context ID:

Write

/tmp/request.json

{
  "projectId": "<your-project-id>",
  "browserSettings": {
    "context": {
      "id": "<your-context-id>",
      "persist": true
    }
  }
}

bash -c 'curl -s -X POST "https://api.browserbase.com/v1/sessions" --header "Content-Type: application/json" --header "X-BB-API-Key: $BROWSERBASE_API_KEY" -d @/tmp/request.json'

Set

persist: true

to save updates back to the context after the session ends.

Delete Context

Delete a context when it's no longer needed. Replace

<your-context-id>

with the actual context ID:

bash -c 'curl -s -X DELETE "https://api.browserbase.com/v1/contexts/<your-context-id>" --header "X-BB-API-Key: $BROWSERBASE_API_KEY" -w "\nHTTP Status: %{http_code}"'

Successful deletion returns HTTP 204 (No Content).

Projects API

Get Project Usage

Retrieve project-wide usage statistics (browser minutes and proxy bytes). Replace

<your-project-id>

with your actual project ID:

bash -c 'curl -s -X GET "https://api.browserbase.com/v1/projects/<your-project-id>/usage" --header "X-BB-API-Key: $BROWSERBASE_API_KEY"'

API Endpoints Reference

Endpoint	Method	Description
`/v1/sessions`	POST	Create a new browser session
`/v1/sessions`	GET	List all sessions
`/v1/sessions/{id}`	GET	Get session details (returns array)
`/v1/sessions/{id}`	POST	Update session (release)
`/v1/sessions/{id}/debug`	GET	Get live debug URLs
`/v1/sessions/{id}/logs`	GET	Get session logs
`/v1/sessions/{id}/recording`	GET	Get session recording (rrweb)
`/v1/sessions/{id}/downloads`	GET	Get downloaded files (ZIP)
`/v1/sessions/{id}/uploads`	POST	Upload files to session
`/v1/contexts`	POST	Create a new context
`/v1/contexts/{id}`	GET	Get context details
`/v1/contexts/{id}`	DELETE	Delete a context
`/v1/projects/{id}/usage`	GET	Get project usage stats

Session Status Values

Status	Description
`RUNNING`	Session is currently active
`COMPLETED`	Session ended successfully
`ERROR`	Session ended with an error
`TIMED_OUT`	Session exceeded timeout
`REQUEST_RELEASE`	Request to end session

Guidelines

Session Lifecycle: Sessions auto-terminate after timeout (default 5 minutes). Use
```
keepAlive: true
```
for longer sessions.
Contexts: Use contexts to persist login state and avoid repeated authentication.
Proxies: Enable proxies for geo-restricted content or to avoid rate limiting.
Regions: Choose a region close to your target websites for better performance.
Debug URLs: Use debug URLs for real-time human-in-the-loop debugging.
Recordings: Session replays use rrweb DOM reconstruction, not video files.
Rate Limits: Check your plan limits in the Browserbase dashboard.