Browser Cash

# browser-cash

Spin up unblocked browser sessions via Browser.cash for web automation. These sessions bypass common anti-bot protections (Cloudflare, DataDome, etc.), making them ideal for scraping, testing, and automation tasks that would otherwise get blocked.

When to use: Any browser automation task—scraping, form filling, testing, screenshots. Browser.cash sessions appear as real browsers and handle bot detection automatically.

Setup

API Key is stored in clawdbot config at `skills.entries.browser-cash.apiKey`.

If not configured, prompt the user: > Get your API key from https://dash.browser.cash and run: > ```bash > clawdbot config set skills.entries.browser-cash.apiKey "your_key_here" > ```

Reading the key: ```bash BROWSER_CASH_KEY=$(clawdbot config get skills.entries.browser-cash.apiKey) ```

Before first use, check and install Playwright if needed: ```bash if [ ! -d ~/clawd/node_modules/playwright ]; then cd ~/clawd && npm install playwright puppeteer-core fi ```

API Basics

```bash curl -X POST "https://api.browser.cash/v1/..." \ -H "Authorization: Bearer $BROWSER_CASH_KEY" \ -H "Content-Type: application/json" ```

Create a Browser Session

Basic session: ```bash curl -X POST "https://api.browser.cash/v1/browser/session" \ -H "Authorization: Bearer $BROWSER_CASH_KEY" \ -H "Content-Type: application/json" \ -d '{}' ```

Response: ```json { "sessionId": "abc123...", "status": "active", "servedBy": "node-id", "createdAt": "2025-01-20T01:51:25.000Z", "stoppedAt": null, "cdpUrl": "wss://gcp-usc1-1.browser.cash/v1/consumer/abc123.../devtools/browser/uuid" } ```

With options: ```bash curl -X POST "https://api.browser.cash/v1/browser/session" \ -H "Authorization: Bearer $BROWSER_CASH_KEY" \ -H "Content-Type: application/json" \ -d '{ "country": "US", "windowSize": "1920x1080", "profile": { "name": "my-profile", "persist": true } }' ```

Session Options

| Option | Type | Description | |--------|------|-------------| | `country` | string | 2-letter ISO code (e.g., "US", "DE", "GB") | | `windowSize` | string | Browser dimensions, e.g., "1920x1080" | | `proxyUrl` | string | SOCKS5 proxy URL (optional) | | `profile.name` | string | Named browser profile for session persistence | | `profile.persist` | boolean | Save cookies/storage after session ends |

Using Browser.cash with Clawdbot

Browser.cash returns a WebSocket CDP URL (`wss://...`). Use one of these approaches:

Option 1: Direct CDP via exec (Recommended)

Important: Before running Playwright/Puppeteer scripts, ensure dependencies are installed: ```bash [ -d ~/clawd/node_modules/playwright ] || (cd ~/clawd && npm install playwright puppeteer-core) ```

Use Playwright or Puppeteer in an exec block to connect directly to the CDP URL:

```bash # 1. Create session BROWSER_CASH_KEY=$(clawdbot config get skills.entries.browser-cash.apiKey) SESSION=$(curl -s -X POST "https://api.browser.cash/v1/browser/session" \ -H "Authorization: Bearer $BROWSER_CASH_KEY" \ -H "Content-Type: application/json" \ -d '{"country": "US", "windowSize": "1920x1080"}')

SESSION_ID=$(echo $SESSION | jq -r '.sessionId') CDP_URL=$(echo $SESSION | jq -r '.cdpUrl')

# 2. Use via Node.js exec (Playwright) node -e " const { chromium } = require('playwright'); (async () => { const browser = await chromium.connectOverCDP('$CDP_URL'); const context = browser.contexts()[0]; const page = context.pages()[0] || await context.newPage(); await page.goto('https://example.com'); console.log('Title:', await page.title()); await browser.close(); })(); "

# 3. Stop session when done curl -X DELETE "https://api.browser.cash/v1/browser/session?sessionId=$SESSION_ID" \ -H "Authorization: Bearer $BROWSER_CASH_KEY" ```

Option 2: Curl-based automation

For simple tasks, use curl to interact with pages via CDP commands:

```bash # Navigate and extract content using the CDP URL # (See CDP protocol docs for available methods) ```

Note on Clawdbot browser tool

Clawdbot's native `browser` tool expects HTTP control server URLs, not raw WebSocket CDP. The `gateway config.patch` approach works when Clawdbot's browser control server proxies the connection. For direct Browser.cash CDP, use the exec approach above.

Get Session Status

```bash curl "https://api.browser.cash/v1/browser/session?sessionId=YOUR_SESSION_ID" \ -H "Authorization: Bearer $BROWSER_CASH_KEY" ```

Statuses: `starting`, `active`, `completed`, `error`

Stop a Session

```bash curl -X DELETE "https://api.browser.cash/v1/browser/session?sessionId=YOUR_SESSION_ID" \ -H "Authorization: Bearer $BROWSER_CASH_KEY" ```

List Sessions

```bash curl "https://api.browser.cash/v1/browser/sessions?page=1&pageSize=20" \ -H "Authorization: Bearer $BROWSER_CASH_KEY" ```

Browser Profiles

Profiles persist cookies, localStorage, and session data across sessions—useful for staying logged in or maintaining state.

List profiles: ```bash curl "https://api.browser.cash/v1/browser/profiles" \ -H "Authorization: Bearer $BROWSER_CASH_KEY" ```

Delete profile: ```bash curl -X DELETE "https://api.browser.cash/v1/browser/profile?profileName=my-profile" \ -H "Authorization: Bearer $BROWSER_CASH_KEY" ```

Connecting via CDP

The `cdpUrl` is a WebSocket endpoint for Chrome DevTools Protocol. Use it with any CDP-compatible library.

Playwright: ```javascript const { chromium } = require('playwright'); const browser = await chromium.connectOverCDP(cdpUrl); const context = browser.contexts()[0]; const page = context.pages()[0] || await context.newPage(); await page.goto('https://example.com'); ```

Puppeteer: ```javascript const puppeteer = require('puppeteer-core'); const browser = await puppeteer.connect({ browserWSEndpoint: cdpUrl }); const pages = await browser.pages(); const page = pages[0] || await browser.newPage(); await page.goto('https://example.com'); ```

Full Workflow Example

```bash # 0. Ensure Playwright is installed [ -d ~/clawd/node_modules/playwright ] || (cd ~/clawd && npm install playwright puppeteer-core)

# 1. Create session BROWSER_CASH_KEY=$(clawdbot config get skills.entries.browser-cash.apiKey) SESSION=$(curl -s -X POST "https://api.browser.cash/v1/browser/session" \ -H "Authorization: Bearer $BROWSER_CASH_KEY" \ -H "Content-Type: application/json" \ -d '{"country": "US", "windowSize": "1920x1080"}')

SESSION_ID=$(echo $SESSION | jq -r '.sessionId') CDP_URL=$(echo $SESSION | jq -r '.cdpUrl')

# 2. Connect with Playwright/Puppeteer using $CDP_URL...

# 3. Stop session when done curl -X DELETE "https://api.browser.cash/v1/browser/session?sessionId=$SESSION_ID" \ -H "Authorization: Bearer $BROWSER_CASH_KEY" ```

Scraping Tips

When extracting data from pages with lazy-loading or infinite scroll:

```javascript // Scroll to load all products async function scrollToBottom(page) { let previousHeight = 0; while (true) { const currentHeight = await page.evaluate(() => document.body.scrollHeight); if (currentHeight === previousHeight) break; previousHeight = currentHeight; await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight)); await page.waitForTimeout(1500); // Wait for content to load } }

// Wait for specific elements await page.waitForSelector('.product-card', { timeout: 10000 });

// Handle "Load More" buttons const loadMore = await page.$('button.load-more'); if (loadMore) { await loadMore.click(); await page.waitForTimeout(2000); } ```

• Common patterns:
• Always scroll to trigger lazy-loaded content
• Wait for network idle: `await page.waitForLoadState('networkidle')`
• Use `page.waitForSelector()` before extracting elements
• Add delays between actions to avoid rate limiting

Why Browser.cash for Automation

• Unblocked: Sessions bypass Cloudflare, DataDome, PerimeterX, and other bot protections
• Real browser fingerprint: Appears as a genuine Chrome browser, not headless
• CDP native: Direct WebSocket connection for Playwright, Puppeteer, or raw CDP
• Geographic targeting: Spin up sessions in specific countries
• Persistent profiles: Maintain login state across sessions

Notes

• Sessions auto-terminate after extended inactivity
• Always stop sessions when done to avoid unnecessary usage
• Use profiles when you need to maintain logged-in state
• SOCKS5 is the only supported proxy type
• Clawdbot runs scripts from `~/clawd/` - install npm dependencies there
• For full page scraping, always scroll to trigger lazy-loaded content