jo-inc/camofox-browser

camofox‑browser – an anti‑detection browser server for AI agents

What it is – A tiny Node.js server that runs a specially‑patched Firefox build (Camoufox) and exposes a REST API for AI agents to browse the real web without being flagged as a bot. The browser’s fingerprint is spoofed at the C++ level, so sites see a normal‑looking Firefox instead of a headless or instrumented browser.

Why it matters for agents – Modern web‑scraping tools (Playwright, headless Chrome) are increasingly blocked by Cloudflare, Google, and other bot‑detection services. Camoufox‑browser solves this by:

• Spoofing low‑level properties (CPU cores, WebGL, AudioContext, screen size, WebRTC, etc.) before any JavaScript runs.
• Providing accessibility snapshots (a compact, screen‑reader‑friendly representation of the page) that are ~90 % smaller than raw HTML, saving token budget for LLM‑driven agents.
• Offering stable element references (e1, e2, …) so an agent can reliably click or type without brittle CSS/XPath selectors.

Key features (as described in the README)

Feature	What it does
C++ anti‑detection	Bypasses Google, Cloudflare, and most bot‑detectors by patching Firefox at the binary level.
Element refs	Returns stable short IDs for interactive elements, making agent commands deterministic.
Token‑efficient snapshots	Sends an accessibility tree instead of full HTML, dramatically reducing payload size.
Low resource footprint	Lazy launch and idle shutdown keep memory around ~40 MiB; can run on a cheap VPS or Raspberry Pi.
Session isolation & persistence	Separate cookie/storage per user; optional persistence to ~/.camofox/profiles/.
Cookie import	Accepts Netscape‑format cookie files so agents can reuse existing logins (e.g., LinkedIn, Amazon).
File upload	Allows agents to attach files from a configured directory without a native OS dialog.
Proxy + GeoIP	Routes traffic through residential proxies; automatically aligns locale, timezone, and geolocation with the proxy IP.
YouTube transcripts	Pulls captions via yt‑dlp (no API key needed).
Search macros	Built‑in shortcuts like @google_search, @youtube_search, @amazon_search, etc.
Snapshot screenshots	Returns a base‑64 PNG alongside the accessibility snapshot.
Large‑page handling	Truncates snapshots with offset‑based pagination to keep responses manageable.
Download capture	Captures files the browser downloads and makes them available via the API (inline base64 optional).
DOM image extraction	Lists <img> sources/alt text and can return data‑URL versions.
Deploy anywhere	Docker, Fly.io, Railway, or direct npm start.
VNC interactive login	NoVNC UI lets a human log in visually; the resulting storage state can be reused by the agent.
OpenAPI docs	Auto‑generated spec at /openapi.json and interactive Swagger UI at /docs.
Structured extract	POST /tabs/:tabId/extract with a JSON schema that maps fields to snapshot refs (x‑ref).
Session tracing	Optional Playwright trace (screenshots, DOM, network) per session, downloadable as a zip.
Telemetry	Anonymous crash/hang reports are posted to a Cloudflare Worker that creates GitHub issues; can be disabled.

How to get it running

1. Clone & install

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

2. Optional – Docker (recommended for production)

   make up            # builds image, downloads binaries, starts container
   # stop/remove
   make down
   

   The Makefile auto‑detects CPU architecture (x86_64 or aarch64) and pre‑downloads Camoufox + yt‑dlp so builds are fast.
3. Configure – Most behaviour is controlled by environment variables, e.g.:
   • CAMOFOX_API_KEY – secret token required for privileged endpoints (cookie import, VNC login).
   • PROXY_HOST, PROXY_PORT, PROXY_USERNAME, PROXY_PASSWORD – enable proxy routing.
   • CAMOFOX_CRASH_REPORT_ENABLED=false – turn off telemetry.
   • CAMOUFOX_EXECUTABLE – point to a pre‑downloaded Camoufox binary if you manage it yourself.

Typical agent workflow

1. Create a tab – POST /tabs with {userId, sessionKey, url} returns a tabId.
2. Take a snapshot – GET /tabs/:tabId/snapshot returns an accessibility tree and a base‑64 PNG.
3. Interact – Use POST /tabs/:tabId/click, .../type, .../scroll, etc., referencing elements by the stable IDs (e1, e2).
4. Extract structured data – Define a JSON schema that maps desired fields to x‑ref IDs and POST to /tabs/:tabId/extract.
5. Close – DELETE /tabs/:tabId (or close the whole session) to free resources and optionally write a trace.

Integration points

• OpenClaw plugin – The README mentions an openclaw plugin (@askjo/camofox-browser) that wraps the HTTP calls into convenient CLI commands (camofox_create_tab, camofox_click, …). This is useful for developers who already use the OpenClaw agent framework.
• Standalone CLI – npx @askjo/camofox-browser runs the server without cloning the repo.
• OpenAPI – The generated spec lets you generate client libraries in any language, making it easy to embed the service in custom LLM‑orchestrators.

Who built it – The project is maintained by the team behind Jo, a personal AI assistant that runs partly on a user’s Mac and partly on a cloud machine. The same team created Camoufox, the underlying fingerprint‑spoofing Firefox fork.

---

TL;DR

• camofox‑browser = a lightweight REST wrapper around a fingerprint‑spoofed Firefox (Camoufox).
• Designed for AI agents that need to browse the open web without being blocked.
• Provides tiny, structured snapshots, stable element IDs, cookie import, proxy support, and optional tracing.
• Install with npm install && npm start or via Docker/Make; configure via env vars.