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
- Start low — Always try Rung 1 first
- Cache results — Don't re-fetch unnecessarily
- Batch requests — One browser session for multiple pages
- 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.
