camoufox-browser

A headless browser automation server designed for AI agents. Powered by Camoufox - a Firefox-based browser with C++ anti-detection that bypasses bot detection including Google captcha.

This is the same browser engine that powers askjo.ai's web scraping capabilities.

Perfect for: OpenClaw, Claude Code, LangChain agents, AutoGPT, and any AI system that needs to browse the web.

Motivation

AI agents need to browse the web, but current solutions have significant limitations:

• Playwright/Puppeteer + stealth plugins get detected and blocked by Google, Cloudflare, and most anti-bot systems. JavaScript-level evasion isn't enough.
• Headless Chrome is trivially fingerprinted. Sites check for hundreds of browser characteristics that reveal automation.
• API-based scrapers (Browserless, ScrapingBee) work but cost money per request and add latency.
• Raw HTTP requests can't handle JavaScript-rendered content or complex interactions.

Camoufox solves this with C++ level anti-detection baked into the Firefox source code itself - not a plugin that can be detected, but fundamental changes to how the browser reports its fingerprint. This is the same approach used by commercial anti-detect browsers.

This project wraps Camoufox in a simple REST API optimized for AI agents: accessibility snapshots instead of bloated HTML, stable element refs for reliable clicking, and search macros for common sites.

Features

• Anti-Detection - Camoufox engine (Firefox-based) with C++ fingerprint spoofing, bypasses Google captcha
• Element Refs - Stable e1, e2, e3 references for clicking/typing
• Session Isolation - Separate cookies/storage per user, tabs grouped by conversation
• Search Macros - 13 built-in URL macros (@google_search, @youtube_search, etc.)
• Token-Efficient - Accessibility snapshots instead of full HTML (90% smaller)
• Docker Ready - Production Dockerfile with pre-baked Camoufox binary

Quick Start

OpenClaw Plugin

Install as an OpenClaw plugin for agent tool access:

openclaw plugins install @askjo/camoufox-browser

Then start the server and configure:

# ~/.openclaw/openclaw.json
plugins:
  entries:
    camoufox-browser:
      enabled: true
      config:
        url: "http://localhost:9377"

The plugin provides these agent tools:

• camoufox_create_tab - Create a browser tab
• camoufox_snapshot - Get page snapshot with element refs
• camoufox_click - Click elements by ref
• camoufox_type - Type into elements
• camoufox_navigate - Navigate to URLs or use search macros
• camoufox_scroll - Scroll the page
• camoufox_screenshot - Take screenshots
• camoufox_close_tab - Close tabs
• camoufox_list_tabs - List open tabs

Standalone Server

# Clone and install
git clone https://github.com/jo-inc/camoufox-browser
cd camoufox-browser
npm install

# Start server (downloads Camoufox browser on first run)
npm start                    # Default port 3000
./run-camoufox.sh -p 3001    # Custom port

# Server runs on http://localhost:3000

API Overview

Create a Tab

curl -X POST http://localhost:3000/tabs \
  -H "Content-Type: application/json" \
  -d '{"userId": "user1", "sessionKey": "conv1", "url": "https://example.com"}'

Get Page Snapshot (with element refs)

curl "http://localhost:3000/tabs/TAB_ID/snapshot?userId=user1"

Response includes refs for interaction:

{
  "snapshot": "[button e1] Submit  [link e2] Learn more",
  "refs": {
    "e1": { "role": "button", "name": "Submit" },
    "e2": { "role": "link", "name": "Learn more" }
  },
  "url": "https://example.com"
}

Click an Element

curl -X POST http://localhost:3000/tabs/TAB_ID/click \
  -H "Content-Type: application/json" \
  -d '{"userId": "user1", "ref": "e1"}'

Search with Macros

curl -X POST http://localhost:3000/tabs/TAB_ID/navigate \
  -H "Content-Type: application/json" \
  -d '{"userId": "user1", "macro": "@google_search", "query": "best coffee beans"}'

All Endpoints

| Method | Path | Description | |--------|------|-------------| | GET | /health | Health check | | GET | /tabs?userId=X | List all tab groups for user | | POST | /tabs | Create new tab | | DELETE | /tabs/:tabId | Close tab | | POST | /tabs/:tabId/navigate | Navigate to URL or macro | | GET | /tabs/:tabId/snapshot | Get accessibility snapshot with refs | | POST | /tabs/:tabId/click | Click element by ref or selector | | POST | /tabs/:tabId/type | Type into element | | POST | /tabs/:tabId/scroll | Scroll page | | POST | /tabs/:tabId/back | Go back | | POST | /tabs/:tabId/forward | Go forward | | POST | /tabs/:tabId/refresh | Refresh page | | GET | /tabs/:tabId/links | Get all links | | GET | /tabs/:tabId/screenshot | Get screenshot | | DELETE | /sessions/:userId | Close all tabs for user |

Search Macros

Navigate supports these macros for common sites:

• @google_search - Google
• @youtube_search - YouTube
• @amazon_search - Amazon
• @reddit_search - Reddit
• @wikipedia_search - Wikipedia
• @twitter_search - Twitter/X
• @yelp_search - Yelp
• @spotify_search - Spotify
• @netflix_search - Netflix
• @linkedin_search - LinkedIn
• @instagram_search - Instagram
• @tiktok_search - TikTok
• @twitch_search - Twitch

Architecture

Browser Instance
└── User Session (BrowserContext) - isolated cookies/storage
    ├── Tab Group (sessionKey: "conv1") - conversation A
    │   ├── Tab (google.com)
    │   └── Tab (github.com)
    └── Tab Group (sessionKey: "conv2") - conversation B
        └── Tab (amazon.com)

• One browser instance shared across users
• Separate BrowserContext per user (isolated cookies/storage)
• Tabs grouped by sessionKey (conversation/task)
• 30-minute session timeout with automatic cleanup

Running Locally

# Start with default port (3000)
./run-camoufox.sh
# Or: npm start

# Start with custom port
./run-camoufox.sh -p 3001

First run downloads the Camoufox browser (~300MB).

Experimental

See experimental/ for alternative browser engines.

Docker Deployment

# Build with Camoufox (recommended)
docker build -f Dockerfile.camoufox -t camoufox-browser .

# Run
docker run -p 3000:3000 camoufox-browser

Fly.io Deployment

fly launch --no-deploy
fly deploy

Testing

npm test                 # Run all e2e tests
npm run test:live        # Run live Google tests (may hit captcha)
npm run test:debug       # Show server output for debugging

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | PORT | Server port | 3000 | | NODE_ENV | Environment | development |

Contributing

Contributions are welcome! Please open an issue or submit a PR.

Credits

• Camoufox - Firefox-based browser with C++ anti-detection
• Amp - AI coding agent

License

MIT