camofox-browser

camofox-browser

Anti-detection browser server for AI agents, powered by Camoufox

Build License Camoufox Docker

Standing on the mighty shoulders of Camoufox - a Firefox fork with fingerprint spoofing at the C++ level.

The same engine behind Jo — an AI assistant that doesn't need you to babysit it. Runs half on your Mac, half on a dedicated cloud machine that only you use. Available on macOS, Telegram, and WhatsApp. Try the beta free →


```bash git clone https://github.com/jo-inc/camofox-browser && cd camofox-browser npm install && npm start # → http://localhost:9377 ``` --- ## Why AI agents need to browse the real web. Playwright gets blocked. Headless Chrome gets fingerprinted. Stealth plugins become the fingerprint. Camoufox patches Firefox at the **C++ implementation level** - `navigator.hardwareConcurrency`, WebGL renderers, AudioContext, screen geometry, WebRTC - all spoofed before JavaScript ever sees them. No shims, no wrappers, no tells. This project wraps that engine in a REST API built for agents: accessibility snapshots instead of bloated HTML, stable element refs for clicking, and search macros for common sites. ## Features - **C++ Anti-Detection** - bypasses Google, Cloudflare, and most bot detection - **Element Refs** - stable `e1`, `e2`, `e3` identifiers for reliable interaction - **Token-Efficient** - accessibility snapshots are ~90% smaller than raw HTML - **Runs on Anything** - lazy browser launch + idle shutdown keeps memory at ~40MB when idle. Designed to share a box with the rest of your stack — Raspberry Pi, $5 VPS, shared Railway infra. - **Session Isolation** - separate cookies/storage per user - **Cookie Import** - inject Netscape-format cookie files for authenticated browsing - **Proxy + GeoIP** - route traffic through residential proxies with automatic locale/timezone - **Structured Logging** - JSON log lines with request IDs for production observability - **YouTube Transcripts** - extract captions from any YouTube video via yt-dlp, no API key needed - **Search Macros** - `@google_search`, `@youtube_search`, `@amazon_search`, `@reddit_subreddit`, and 10 more - **Snapshot Screenshots** - include a base64 PNG screenshot alongside the accessibility snapshot - **Large Page Handling** - automatic snapshot truncation with offset-based pagination - **Download Capture** - capture browser downloads and fetch them via API (optional inline base64) - **DOM Image Extraction** - list `` src/alt and optionally return inline data URLs - **Deploy Anywhere** - Docker, Fly.io, Railway ## Optional Dependencies | Dependency | Purpose | Install | |-----------|---------|---------| | [yt-dlp](https://github.com/yt-dlp/yt-dlp) | YouTube transcript extraction (fast path) | `pip install yt-dlp` or `brew install yt-dlp` | The Docker image includes yt-dlp. For local dev, install it for the `/youtube/transcript` endpoint. Without it, the endpoint falls back to a slower browser-based method. ## Quick Start ### OpenClaw Plugin ```bash openclaw plugins install @askjo/camofox-browser ``` **Tools:** `camofox_create_tab` · `camofox_snapshot` · `camofox_click` · `camofox_type` · `camofox_navigate` · `camofox_scroll` · `camofox_screenshot` · `camofox_close_tab` · `camofox_list_tabs` · `camofox_import_cookies` ### Standalone ```bash git clone https://github.com/jo-inc/camofox-browser cd camofox-browser npm install npm start # downloads Camoufox on first run (~300MB) ``` Default port is `9377`. See [Environment Variables](#environment-variables) for all options. ### Docker The included `Makefile` auto-detects your CPU architecture and pre-downloads Camoufox + yt-dlp binaries outside the Docker build, so rebuilds are fast (~30s vs ~3min). ```bash # Build and start (auto-detects arch: aarch64 on M1/M2, x86_64 on Intel) make up # Stop and remove the container make down # Force a clean rebuild (e.g. after upgrading VERSION/RELEASE) make reset # Just download binaries (without building) make fetch # Override arch or version explicitly make up ARCH=x86_64 make up VERSION=135.0.1 RELEASE=beta.24 ``` Note: `make fetch` (or `make build`) must be run first — the Dockerfile expects pre-downloaded binaries in `dist/`. ### Fly.io / Railway `fly.toml` and `railway.toml` are included. Deploy with `fly deploy` or connect the repo to Railway. ## Usage ### Cookie Import Import cookies from your browser into Camoufox to skip interactive login on sites like LinkedIn, Amazon, etc. #### Setup **1. Generate a secret key:** ```bash # macOS / Linux openssl rand -hex 32 ``` **2. Set the environment variable before starting OpenClaw:** ```bash export CAMOFOX_API_KEY="your-generated-key" openclaw start ``` The same key is used by both the plugin (to authenticate requests) and the server (to verify them). Both run from the same environment — set it once. > **Why an env var?** The key is a secret. Plugin config in `openclaw.json` is stored in plaintext, so secrets don't belong there. Set `CAMOFOX_API_KEY` in your shell profile, systemd unit, Docker env, or Fly.io secrets. > **Cookie import is disabled by default.** If `CAMOFOX_API_KEY` is not set, the server rejects all cookie requests with 403. **3. Export cookies from your browser:** Install a browser extension that exports Netscape-format cookie files (e.g., "cookies.txt" for Chrome/Firefox). Export the cookies for the site you want to authenticate. **4. Place the cookie file:** ```bash mkdir -p ~/.camofox/cookies cp ~/Downloads/linkedin_cookies.txt ~/.camofox/cookies/linkedin.txt ``` The default directory is `~/.camofox/cookies/`. Override with `CAMOFOX_COOKIES_DIR`. **5. Ask your agent to import them:** > Import my LinkedIn cookies from linkedin.txt The agent calls `camofox_import_cookies` → reads the file → POSTs to the server with the Bearer token → cookies are injected into the browser session. Subsequent `camofox_create_tab` calls to linkedin.com will be authenticated. #### How it works ``` ~/.camofox/cookies/linkedin.txt (Netscape format, on disk) │ ▼ camofox_import_cookies tool (parses file, filters by domain) │ ▼ POST /sessions/:userId/cookies │ Authorization: Bearer │ Body: { cookies: [Playwright cookie objects] } ▼ camofox server (validates, sanitizes, injects) │ ▼ context.addCookies(...) │ Camoufox browser session (authenticated browsing) ``` - `cookiesPath` is resolved relative to the cookies directory — path traversal outside it is blocked - Max 500 cookies per request, 5MB file size limit - Cookie objects are sanitized to an allowlist of Playwright fields #### Standalone server usage ```bash curl -X POST http://localhost:9377/sessions/agent1/cookies \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_CAMOFOX_API_KEY' \ -d '{"cookies":[{"name":"foo","value":"bar","domain":"example.com","path":"/","expires":-1,"httpOnly":false,"secure":false}]}' ``` #### Docker / Fly.io ```bash docker run -p 9377:9377 \ -e CAMOFOX_API_KEY="your-generated-key" \ -v ~/.camofox/cookies:/home/node/.camofox/cookies:ro \ camofox-browser ``` For Fly.io: ```bash fly secrets set CAMOFOX_API_KEY="your-generated-key" ``` ### Proxy + GeoIP Route all browser traffic through a proxy with automatic locale, timezone, and geolocation derived from the proxy's IP address via Camoufox's built-in GeoIP. **Simple proxy (single endpoint):** ```bash export PROXY_HOST=166.88.179.132 export PROXY_PORT=46040 export PROXY_USERNAME=myuser export PROXY_PASSWORD=mypass npm start ``` **Backconnect proxy (rotating sticky sessions):** For providers like Decodo, Bright Data, or Oxylabs that offer a single gateway endpoint with session-based sticky IPs: ```bash export PROXY_STRATEGY=backconnect export PROXY_BACKCONNECT_HOST=gate.provider.com export PROXY_BACKCONNECT_PORT=7000 export PROXY_USERNAME=myuser export PROXY_PASSWORD=mypass npm start ``` Each browser context gets a unique sticky session, so different users get different IP addresses. Sessions rotate automatically on proxy errors or Google blocks. Or in Docker: ```bash docker run -p 9377:9377 \ -e PROXY_HOST=166.88.179.132 \ -e PROXY_PORT=46040 \ -e PROXY_USERNAME=myuser \ -e PROXY_PASSWORD=mypass \ camofox-browser ``` When a proxy is configured: - All traffic routes through the proxy - Camoufox's GeoIP automatically sets `locale`, `timezone`, and `geolocation` to match the proxy's exit IP - Browser fingerprint (language, timezone, coordinates) is consistent with the proxy location - Without a proxy, defaults to `en-US`, `America/Los_Angeles`, San Francisco coordinates ### Structured Logging All log output is JSON (one object per line) for easy parsing by log aggregators: ```json {"ts":"2026-02-11T23:45:01.234Z","level":"info","msg":"req","reqId":"a1b2c3d4","method":"POST","path":"/tabs","userId":"agent1"} {"ts":"2026-02-11T23:45:01.567Z","level":"info","msg":"res","reqId":"a1b2c3d4","status":200,"ms":333} ``` Health check requests (`/health`) are excluded from request logging to reduce noise. ### Basic Browsing ```bash # Create a tab curl -X POST http://localhost:9377/tabs \ -H 'Content-Type: application/json' \ -d '{"userId": "agent1", "sessionKey": "task1", "url": "https://example.com"}' # Get accessibility snapshot with element refs curl "http://localhost:9377/tabs/TAB_ID/snapshot?userId=agent1" # → { "snapshot": "[button e1] Submit [link e2] Learn more", ... } # Click by ref curl -X POST http://localhost:9377/tabs/TAB_ID/click \ -H 'Content-Type: application/json' \ -d '{"userId": "agent1", "ref": "e1"}' # Type into an element curl -X POST http://localhost:9377/tabs/TAB_ID/type \ -H 'Content-Type: application/json' \ -d '{"userId": "agent1", "ref": "e2", "text": "hello", "pressEnter": true}' # Navigate with a search macro curl -X POST http://localhost:9377/tabs/TAB_ID/navigate \ -H 'Content-Type: application/json' \ -d '{"userId": "agent1", "macro": "@google_search", "query": "best coffee beans"}' ``` ## API ### Tab Lifecycle | Method | Endpoint | Description | |--------|----------|-------------| | `POST` | `/tabs` | Create tab with initial URL | | `GET` | `/tabs?userId=X` | List open tabs | | `GET` | `/tabs/:id/stats` | Tab stats (tool calls, visited URLs) | | `DELETE` | `/tabs/:id` | Close tab | | `DELETE` | `/tabs/group/:groupId` | Close all tabs in a group | | `DELETE` | `/sessions/:userId` | Close all tabs for a user | ### Page Interaction | Method | Endpoint | Description | |--------|----------|-------------| | `GET` | `/tabs/:id/snapshot` | Accessibility snapshot with element refs. Query params: `includeScreenshot=true` (add base64 PNG), `offset=N` (paginate large snapshots) | | `POST` | `/tabs/:id/click` | Click element by ref or CSS selector | | `POST` | `/tabs/:id/type` | Type text into element | | `POST` | `/tabs/:id/press` | Press a keyboard key | | `POST` | `/tabs/:id/scroll` | Scroll page (up/down/left/right) | | `POST` | `/tabs/:id/navigate` | Navigate to URL or search macro | | `POST` | `/tabs/:id/wait` | Wait for selector or timeout | | `GET` | `/tabs/:id/links` | Extract all links on page | | `GET` | `/tabs/:id/images` | List `` elements. Query params: `includeData=true` (return inline data URLs), `maxBytes=N`, `limit=N` | | `GET` | `/tabs/:id/downloads` | List captured downloads. Query params: `includeData=true` (base64 file data), `consume=true` (clear after read), `maxBytes=N` | | `GET` | `/tabs/:id/screenshot` | Take screenshot | | `POST` | `/tabs/:id/back` | Go back | | `POST` | `/tabs/:id/forward` | Go forward | | `POST` | `/tabs/:id/refresh` | Refresh page | ### YouTube Transcript | Method | Endpoint | Description | |--------|----------|-------------| | `POST` | `/youtube/transcript` | Extract captions from a YouTube video | ```bash curl -X POST http://localhost:9377/youtube/transcript \ -H 'Content-Type: application/json' \ -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "languages": ["en"]}' # → { "status": "ok", "transcript": "[00:18] ♪ We're no strangers to love ♪\n...", "video_title": "...", "total_words": 548 } ``` Uses [yt-dlp](https://github.com/yt-dlp/yt-dlp) when available (fast, no browser needed). Falls back to a browser-based intercept method if yt-dlp is not installed — this is slower and less reliable due to YouTube ad pre-rolls. ### Server | Method | Endpoint | Description | |--------|----------|-------------| | `GET` | `/health` | Health check | | `POST` | `/start` | Start browser engine | | `POST` | `/stop` | Stop browser engine | ### Sessions | Method | Endpoint | Description | |--------|----------|-------------| | `POST` | `/sessions/:userId/cookies` | Add cookies to a user session (Playwright cookie objects) | ## Search Macros `@google_search` · `@youtube_search` · `@amazon_search` · `@reddit_search` · `@reddit_subreddit` · `@wikipedia_search` · `@twitter_search` · `@yelp_search` · `@spotify_search` · `@netflix_search` · `@linkedin_search` · `@instagram_search` · `@tiktok_search` · `@twitch_search` Reddit macros return JSON directly (no HTML parsing needed): - `@reddit_search` - search all of Reddit, returns JSON with 25 results - `@reddit_subreddit` - browse a subreddit (e.g., query `"programming"` → `/r/programming.json`) ## Environment Variables | Variable | Description | Default | |----------|-------------|---------| | `CAMOFOX_PORT` | Server port | `9377` | | `PORT` | Server port (fallback, for platforms like Fly.io) | `9377` | | `CAMOFOX_API_KEY` | Enable cookie import endpoint (disabled if unset) | - | | `CAMOFOX_ADMIN_KEY` | Required for `POST /stop` | - | | `CAMOFOX_COOKIES_DIR` | Directory for cookie files | `~/.camofox/cookies` | | `MAX_SESSIONS` | Max concurrent browser sessions | `50` | | `MAX_TABS_PER_SESSION` | Max tabs per session | `10` | | `SESSION_TIMEOUT_MS` | Session inactivity timeout | `1800000` (30min) | | `BROWSER_IDLE_TIMEOUT_MS` | Kill browser when idle (0 = never) | `300000` (5min) | | `HANDLER_TIMEOUT_MS` | Max time for any handler | `30000` (30s) | | `MAX_CONCURRENT_PER_USER` | Concurrent request cap per user | `3` | | `MAX_OLD_SPACE_SIZE` | Node.js V8 heap limit (MB) | `128` | | `PROXY_STRATEGY` | Proxy mode: `backconnect` (rotating sticky sessions) or blank (single endpoint) | - | | `PROXY_PROVIDER` | Provider name for session format (e.g. `decodo`) | `decodo` | | `PROXY_HOST` | Proxy hostname or IP (simple mode) | - | | `PROXY_PORT` | Proxy port (simple mode) | - | | `PROXY_USERNAME` | Proxy auth username | - | | `PROXY_PASSWORD` | Proxy auth password | - | | `PROXY_BACKCONNECT_HOST` | Backconnect gateway hostname | - | | `PROXY_BACKCONNECT_PORT` | Backconnect gateway port | `7000` | | `PROXY_COUNTRY` | Target country for proxy geo-targeting | - | | `PROXY_STATE` | Target state/region for proxy geo-targeting | - | | `TAB_INACTIVITY_MS` | Close tabs idle longer than this | `300000` (5min) | ## Architecture ``` Browser Instance (Camoufox) └── User Session (BrowserContext) - isolated cookies/storage ├── Tab Group (sessionKey: "conv1") │ ├── Tab (google.com) │ └── Tab (github.com) └── Tab Group (sessionKey: "conv2") └── Tab (amazon.com) ``` Sessions auto-expire after 30 minutes of inactivity. The browser itself shuts down after 5 minutes with no active sessions, and relaunches on the next request. When a session's tab limit is reached, the oldest/least-used tab is automatically recycled instead of returning an error — so long-running agent sessions don't hit dead ends. ## Testing ```bash npm test # all tests npm run test:e2e # e2e tests only npm run test:live # live site tests (Google, macros) npm run test:debug # with server output ``` ## npm ```bash npm install @askjo/camofox-browser ``` ## Credits - [Camoufox](https://camoufox.com) - Firefox-based browser with C++ anti-detection - [Donate to Camoufox's original creator daijro](https://camoufox.com/about/) - [OpenClaw](https://openclaw.ai) - Open-source AI agent framework ## Crypto Scam Warning Sketchy people are doing sketchy things with crypto tokens named "Camofox" now that this project is getting attention. **Camofox is not a crypto project and will never be one.** Any token, coin, or NFT using the Camofox name has nothing to do with us. ## License MIT