jo-inc/camofox-browser

camofox-browser – Anti‑detection browser server for AI agents

What it is – A Node‑JS service that runs a patched Firefox binary (Camoufox) and exposes a REST API so autonomous AI agents can browse the web without being fingerprinted or blocked. The browser is modified at the C++ level to spoof hardware, WebGL, WebRTC, screen size, etc., before any JavaScript runs. The server returns lightweight accessibility snapshots (a compact representation of the page’s UI tree) together with optional screenshots, and provides stable element references (e1, e2 …) for reliable clicking, typing, scrolling, etc.

Why it matters for AI – Large‑language‑model agents often need to fetch real‑world information from websites. Conventional headless browsers (Playwright, Chrome) are easily detected and blocked by anti‑bot services (Google, Cloudflare). camofox‑browser solves this by:

• Using Camoufox’s low‑level fingerprint spoofing, making the session look like a normal desktop Firefox.
• Offering a token‑efficient API (snapshots are ~90 % smaller than raw HTML), which reduces LLM token usage.
• Supporting session isolation, cookie import, proxy/GeoIP handling, and VNC‑based manual login, enabling agents to maintain authenticated sessions across tasks.

Key features

• C++ anti‑detection – hardware concurrency, WebGL, AudioContext, screen geometry, WebRTC, etc., spoofed before JS sees them.
• Element refs – stable identifiers (e1, e2) for deterministic actions.
• Accessibility snapshots – compact JSON UI tree; optional base64 PNG screenshot.
• Session management – per‑user storage, cookie import (Netscape format), persistent profiles, optional IndexedDB persistence.
• Proxy & GeoIP – residential proxy support with automatic locale/timezone matching.
• Search macros – built‑in shortcuts for Google, YouTube, Amazon, Reddit, etc.
• YouTube transcripts – via yt‑dlp (no API key).
• Large‑page handling – pagination of snapshots, download capture, image extraction.
• Tracing – optional Playwright trace (screenshots, DOM, network) per session, downloadable as a zip.
• Deployability – Docker, Fly.io, Railway, Raspberry Pi; low idle memory (~40 MiB).
• Telemetry – anonymized crash/health reports sent to a Cloudflare Worker that creates GitHub issues; opt‑out possible.

How to get started

1. Clone and install:

   git clone https://github.com/jo-inc/camofox-browser && cd camofox-browser
   npm install   # downloads Camoufox (~300 MiB) on first run
   npm start     # server listens on 9377
   

2. Call the API (example creates a tab):

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

   The response contains a tabId and an accessibility snapshot.
3. Use the provided OpenClaw plugin commands (camofox_click, camofox_type, …) or direct HTTP endpoints to interact with the page.
4. For authenticated sites, import cookies:

   export CAMOFOX_API_KEY=$(openssl rand -hex 32)
   # place Netscape‑format cookie file in ~/.camofox/cookies/
   camofox_import_cookies linkedin.txt
   

5. Deploy with Docker (or Fly.io/Railway) using the supplied Makefile/build.ps1 – the scripts pre‑download binaries for fast builds.

Typical use‑case – An LLM‑based personal assistant (e.g., jo) receives a request like “Find the latest reviews for the 2024 Tesla Model Y on Reddit and summarize them.” The agent calls camofox_browser to open Reddit, runs a search macro, extracts the UI tree via an accessibility snapshot, parses the relevant elements, and then composes a response—all while the underlying browser remains undetectable to Reddit’s anti‑bot measures.

Limitations / considerations

• Requires the Camoufox binary (≈300 MiB) and optionally yt‑dlp for YouTube transcripts.
• Telemetry is enabled by default; disable with CAMOFOX_CRASH_REPORT_ENABLED=false if privacy is a concern.
• Tracing can only be enabled when the session is created; it cannot be toggled later.
• The service is a wrapper around Playwright‑controlled Firefox, so any site that blocks browsers at the network level (e.g., IP bans) still needs a reliable proxy.

License – MIT.