# camofox-browser

> Anti-detection headless browser server for AI agents, built on Camoufox (a Firefox fork with C++-level fingerprint spoofing) to bypass Cloudflare, bot detection, and anti-scraping systems.

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.

## Features
- C++-level fingerprint spoofing via Camoufox Firefox fork
- Bypasses Cloudflare, Google, and most bot detection systems
- REST API with accessibility snapshots (~90% smaller than raw HTML)
- Stable element refs (e1, e2, e3) for reliable agent interaction
- 14+ search macros (Google, YouTube, Amazon, Reddit, LinkedIn, etc.)
- Session isolation with per-user cookies and localStorage
- Cookie import from Netscape-format files
- Proxy + GeoIP with automatic locale/timezone alignment
- Backconnect proxy support with rotating sticky sessions
- YouTube transcript extraction via yt-dlp (no API key needed)
- Session tracing with Playwright Trace Viewer export
- VNC interactive login via noVNC
- Download capture with optional inline base64
- DOM image extraction
- Structured extract with JSON Schema
- Large page handling with offset-based pagination
- Session persistence across browser restarts
- OpenAPI docs auto-generated at /openapi.json and /docs
- Docker, Fly.io, and Railway deployment support
- OpenClaw plugin integration
- Anonymized crash/hang telemetry with self-hostable endpoint
- Structured JSON logging with request IDs

## Integrations
Camoufox (Firefox fork), Playwright, OpenClaw, yt-dlp, Docker, Fly.io, Railway, Cloudflare Workers, noVNC, uBlock Origin, Decodo proxy, Bright Data proxy, Oxylabs proxy

## Platforms
WINDOWS, MACOS, LINUX, WEB, API, CLI

## Pricing
Open Source

## Version
v1.15.0

## Links
- Website: https://github.com/jo-inc/camofox-browser
- Documentation: https://github.com/jo-inc/camofox-browser#readme
- Repository: https://github.com/jo-inc/camofox-browser
- EveryDev.ai: https://www.everydev.ai/tools/camofox-browser