camofox-browser

camofox-browser is an open-source, MIT-licensed stealth headless browser server built by Jo, Inc. and maintained on GitHub. It wraps Camoufox — a Firefox fork that patches fingerprinting at the C++ level — in a REST API designed specifically for AI agents that need to browse the real web without getting blocked. The project has accumulated over 10,900 GitHub stars and 1,080 forks since its creation in January 2026.

What It Is

camofox-browser sits between an AI agent and the open web, providing a browser automation layer that defeats common bot-detection systems. Unlike Playwright with stealth plugins or headless Chrome, Camoufox patches navigator.hardwareConcurrency, WebGL renderers, AudioContext, screen geometry, and WebRTC at the C++ implementation level — before JavaScript ever sees them. The REST API layer adds agent-friendly primitives: accessibility snapshots instead of raw HTML, stable element refs (e1, e2, e3) for reliable clicking, and search macros for common sites.

How the Anti-Detection Architecture Works

The core engine is Camoufox, a Firefox fork maintained by the Camoufox project (credited as daijro). camofox-browser wraps it with:

• C++-level spoofing — no JavaScript shims or wrappers that themselves become fingerprints
• Proxy + GeoIP integration — routes traffic through residential proxies and automatically aligns locale, timezone, and geolocation to the proxy's exit IP
• Session isolation — separate cookies and localStorage per user, persisted to ~/.camofox/profiles/ across browser restarts
• Cookie import — inject Netscape-format cookie files for authenticated browsing on sites like LinkedIn or Amazon
• VNC interactive login — log into sites visually via noVNC, then export storage state for agent reuse

Agent-Optimized API Surface

The REST API is built around what agents actually need rather than what a human browser user needs:

• Accessibility snapshots — the README states these are ~90% smaller than raw HTML, with stable element refs for clicking and typing
• 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
• YouTube transcripts — extract captions via yt-dlp without an API key, with a browser-based fallback
• Structured extract — POST /tabs/:tabId/extract with a JSON Schema that maps properties to snapshot refs
• Session tracing — opt-in Playwright trace capture (screenshots, DOM snapshots, network) exportable as .zip for the Playwright Trace Viewer
• Download capture — capture browser downloads and fetch them via API with optional inline base64

Deployment Model

The server is designed to run alongside the rest of an agent's stack on minimal hardware — the README notes lazy browser launch and idle shutdown keeps memory at ~40MB when idle, targeting Raspberry Pi, $5 VPS, or shared infrastructure. Deployment options include:

• npm / npx — npx @askjo/camofox-browser or install as @askjo/camofox-browser
• OpenClaw plugin — openclaw plugins install @askjo/camofox-browser
• Docker — included Makefile auto-detects CPU architecture and pre-downloads Camoufox + yt-dlp binaries
• Fly.io — uses Dockerfile.ci which downloads binaries at build time
• Railway — railway.toml included, uses Dockerfile.ci
• Windows — build.ps1 PowerShell script replaces make for Docker builds

Update: v1.15.0 — Fewer Surprises When a Page Fights Back

The latest release is v1.15.0, published on September 10, 2026, titled "Fewer surprises when a page fights back." The repository was last pushed on September 10, 2026, indicating active maintenance. Recent feature additions visible in the README include session tracing, DOM image extraction, download capture, structured extract with JSON Schema, large page handling with offset-based pagination, and a self-hostable telemetry endpoint backed by a Cloudflare Worker whose source is auditable in the repo.

Security and Telemetry Model

The project ships zero embedded secrets. Cookie import is disabled by default and gated behind CAMOFOX_API_KEY. Global bearer token auth (CAMOFOX_ACCESS_KEY) is available for any deployment beyond localhost. Anonymized crash and hang telemetry is sent to a Cloudflare Worker endpoint whose source lives in the repo at workers/crash-reporter/index.ts; a /source endpoint on the worker returns the deployed commit hash and sha256 for independent verification. Telemetry can be disabled with CAMOFOX_CRASH_REPORT_ENABLED=false or redirected to a self-hosted endpoint.