browser-ladder

Browser Ladder 🪜

Climb from free to paid only when you need to.

Quick Setup

Run the setup script after installation:

./skills/browser-ladder/scripts/setup.sh

Or manually add to your .env:

# Optional - only needed for Rungs 3-4
BROWSERCAT_API_KEY=your-key    # Free: https://browsercat.com
BROWSERLESS_TOKEN=your-token   # Paid: https://browserless.io

The Ladder

┌─────────────────────────────────────────────┐
│  🪜 Rung 4: Browserless.io (Cloud Paid)     │
│  • CAPTCHA solving, bot detection bypass    │
│  • Cost: $10+/mo                            │
│  • Requires: BROWSERLESS_TOKEN              │
├─────────────────────────────────────────────┤
│  🪜 Rung 3: BrowserCat (Cloud Free)         │
│  • When local Docker fails                  │
│  • Cost: FREE (limited)                     │
│  • Requires: BROWSERCAT_API_KEY             │
├─────────────────────────────────────────────┤
│  🪜 Rung 2: Playwright Docker (Local)       │
│  • JavaScript rendering, screenshots        │
│  • Cost: FREE (CPU only)                    │
│  • Requires: Docker installed               │
├─────────────────────────────────────────────┤
│  🪜 Rung 1: web_fetch (No browser)          │
│  • Static pages, APIs, simple HTML          │
│  • Cost: FREE                               │
│  • Requires: Nothing                        │
└─────────────────────────────────────────────┘

Start at the bottom. Climb only when needed.

When to Climb

Situation	Rung	Why
Static HTML, APIs	1	No JS needed
React/Vue/SPA apps	2	JS rendering
Docker unavailable	3	Cloud fallback
CAPTCHA/Cloudflare	4	Bot bypass needed
OAuth/MFA flows	4	Complex auth

Decision Flow

Need to access a URL
         │
         ▼
    Static content? ──YES──▶ Rung 1 (web_fetch)
         │ NO
         ▼
    JS rendering only? ──YES──▶ Rung 2 (Playwright Docker)
         │ NO                        │
         │                     Success? ──NO──▶ Rung 3
         ▼                           │ YES
    CAPTCHA/bot detection? ────────────────────▶ DONE
         │ YES
         ▼
    Rung 4 (Browserless.io) ──▶ DONE

Usage Examples

Rung 1: Static content

// Built into Clawdbot
const content = await web_fetch("https://example.com");

Rung 2: JS-rendered page

docker run --rm -v /tmp:/output mcr.microsoft.com/playwright:v1.58.0-jammy \
  npx playwright screenshot https://spa-app.com /output/shot.png

Rung 3: Cloud browser (BrowserCat)

const { chromium } = require('playwright');
const browser = await chromium.connect('wss://api.browsercat.com/connect', {
  headers: { 'Api-Key': process.env.BROWSERCAT_API_KEY }
});

Rung 4: CAPTCHA bypass (Browserless)

const { chromium } = require('playwright');
const browser = await chromium.connectOverCDP(
  `wss://production-sfo.browserless.io?token=${process.env.BROWSERLESS_TOKEN}`
);
// CAPTCHA handled automatically

Cost Optimization

1. Start low — Always try Rung 1 first
2. Cache results — Don't re-fetch unnecessarily
3. Batch requests — One browser session for multiple pages
4. Check success — Only climb if lower rung fails

Get Your Keys

Service	Cost	Sign Up
BrowserCat	Free tier	https://browsercat.com
Browserless.io	$10+/mo	https://browserless.io

Both are optional — Rungs 1-2 work without any API keys.