CamoFox Browser Server
An anti-detection browser server for AI agents: wraps the Camoufox engine's C++-level fingerprint spoofing behind a REST API, CLI, MCP companion, and OpenClaw plugin endpoints.
Good least-privilege defaults (loopback default bind, mandatory API key on non-loopback, private-network/metadata blocking by default) and strong credential handling (AES-256-GCM, Argon2id, 0600 perms, no stdout exposure). Deducted for: no user-confirmation mechanism; the tool's purpose itself is evading anti-bot systems (third-party ToS circumvention); source code not available in scope to statically verify the claimed defaults. Rollback is documented but requires manual state clearing.
Release workflow enforces tag/plugin/CHANGELOG version identity, CI covers two OSes and Node versions, tests assert specific error codes (400/403/404/408/429/409) with documented actionable recovery messages. Deducted for: postinstall uses `|| true` to swallow Camoufox engine download failures, allowing silent degradation on first run.
Audience (risk-aware agents) and scenarios are well described; environment fit is broad (Docker, Windows portable, Linux Xvfb). Deducted for: legacy aliases (listItemId, OpenClaw /act routing) reduce endpoint trigger precision — an agent can hit unintended paths; boundary claims are asserted rather than statically verifiable.
Information architecture, install notes, known limitations (Preview non-goals), license (MIT with copyrighted-font exclusion noted), and versioning/changelog (enforced at release) are thorough. Deducted for: maintenance responsibility is unclear — a single unverified author ('Jo, Inc'/redf0x1) with no governance or response commitment; no FAQ; naming stability rests on an unenforceable compatibility promise.
Output usability is strong (multi-format output, accessibility snapshots, eN element refs, token-efficiency design). Deducted for: marginal value depends on upstream Camoufox core capabilities — the increment here is mainly REST/CLI wrapping; cost-benefit is unquantified during Preview and the API surface may change between minor versions.
Most claims trace to in-repo artifacts (config flags, CI, test files). Deducted for: the core anti-detection claim ('passes Google/Cloudflare detection') rests on upstream with no corroboration; publisher identity unverified and single-source; marketing language (robust/full) is not separated from checkable facts.
- The tool's designed purpose is evading anti-bot detection; assess legal and target-site ToS compliance risks before deployment.
- The `|| true` in postinstall masks Camoufox engine download failures; verify engine readiness via /health on first run.
- During Preview the API may change between minor versions; upgrades/rollbacks may require manually clearing local state files.
- Publisher identity is unverified; audit the source and pin revisions before production adoption.
- With non-loopback binds plus a proxy, private-target validation is incomplete until CAMOFOX_ALLOW_PRIVATE_NETWORK is explicitly opted into.
What does this agent do, and when should you use it?
CamoFox Browser Server (redf0x1/camofox-browser) is a strict-mode TypeScript Express server that wraps Camoufox — a Firefox fork whose fingerprint spoofing happens at the C++ engine level — into an HTTP service on port 9377 by default. It exposes roughly 42 core REST endpoints plus about 7 OpenClaw-compatible aliases covering tab creation, navigation, accessibility snapshots with stable eN element refs, click/type/scroll interactions, screenshots, cookie import/export, download tracking, and Playwright tracing. Each userId gets its own persistent Firefox profile directory, so cookies, localStorage, and IndexedDB survive across sessions, with idle contexts evicted via LRU. Built-ins include 14 search macros (Google, YouTube, Reddit, and more), 8 geo presets, and session-level proxy/geo overrides backed by named proxy profiles. A 50+-command CLI, an AES-256-GCM credential vault that never prints secrets to stdout (LLM-safe), schema-driven structured extraction, console capture, and deployment paths for Docker, Fly.io, Railway, and Render round out the package. The project is in Preview (Phase 1) with an additive-only deprecation model.
It runs an Express/TypeScript server (via the camofox-browser command or npm start) wrapping the Camoufox anti-detect Firefox engine. Clients drive the browser through REST calls — POST /tabs to create tabs, POST /tabs/:tabId/navigate to navigate or expand macros like @google_search, GET /tabs/:tabId/snapshot for an accessibility tree annotated with eN element refs, POST /tabs/:tabId/click|type|press|scroll for interaction, GET /tabs/:tabId/screenshot for PNG bytes — or via OpenClaw-compatible endpoints /start, /tabs/open, and /act. POST /tabs/:tabId/extract-structured returns deterministic JSON from a DOM schema without arbitrary JavaScript. The CLI offers camofox open/snapshot/click/type/session/cookie/auth/trace commands plus pipeline scripts via camofox run; auth save/load uses an AES-256-GCM + Argon2id vault, and --inject sends credentials straight to the page so the orchestrating LLM never sees them. The server manages persistent per-userId browser contexts (defaults: 50 sessions, 10 tabs each) with 8 built-in geo presets, a custom presets file (CAMOFOX_PRESETS_FILE), named proxy profiles (CAMOFOX_PROXY_PROFILES_FILE), and explicit-wins / proxy-locked geo modes; display mode toggles between headless, headed, and Linux-only virtual (Xvfb + noVNC, 2-minute auto-stop by default). A Docker image is published at ghcr.io/redf0x1/camofox-browser, with binding and auth controlled via CAMOFOX_HOST, CAMOFOX_AUTH_MODE, and CAMOFOX_API_KEY.
- AI agent developers who need to scrape or automate sites protected by Cloudflare, Google, and similar anti-bot systems, preferring engine-level fingerprint spoofing over fragile JS-injection patches.
- Engineers building LLM automation pipelines who want language-agnostic HTTP endpoints to open tabs, click by eN refs, take snapshots, and get JSON back.
- Teams running multiple accounts/identities that need logins to persist: each userId's persistent Firefox profile keeps cookies, localStorage, and IndexedDB.
- Data-collection jobs that must appear region-consistent (e.g., japan or uk presets) or lock timezone/locale to a proxy exit, using geo presets and proxy-locked mode.
- Users who want coding assistants like Claude Code or Cursor to drive a browser, via npx skills add redf0x1/camofox-browser or the external CamoFox MCP server.
- Automation flows that must log in without exposing passwords to an LLM: the auth vault stores credentials with AES-256-GCM and --inject fills them directly into the page.
What are this agent's strengths and limitations?
- Anti-detection happens at the Camoufox C++ engine level rather than via JS injection; the README reports passing bot detection on Google, Cloudflare, and other anti-bot services — more robust than Puppeteer/Playwright JS patches.
- Complete agent-facing surface: REST API, OpenClaw-compatible endpoints, an external CamoFox MCP server, installable skills for Claude Code/Cursor and 40+ other agents, and a JSON-output CLI.
- Accessibility snapshots with stable eN element refs are smaller and more token-efficient than raw HTML or screenshots; extract-structured yields deterministic JSON without arbitrary JavaScript.
- Strong operational detail: persistent profiles, LRU context eviction, two-stage idle cleanup, health probing, Playwright tracing, AES-256-GCM credential vault, and versioned local state with fail-closed integrity checks.
- The project is in Preview (Phase 1): the API surface is not frozen — endpoint behavior and response shapes may change between minor versions — and incompatible local-state upgrades require manual deletion of profiles/registries.
- Heavy runtime footprint: browser plus contexts need 2GB+ RAM, one persistent Firefox process per userId (defaults: 50 sessions, 10 tabs per session); Linux is recommended for production.
- Platform constraints: Windows x64 supports headless=true only; Xvfb/VNC virtual displays are Linux-only, and VNC sessions auto-stop after 2 minutes by default.
- Deep upstream dependencies: it requires the Camoufox engine (the Windows portable build even excludes upstream fonts due to licensing), and YouTube transcript extraction additionally depends on yt-dlp.
How do you install or deploy this agent?
Pick one of three routes.
1) From source: git clone https://github.com/redf0x1/camofox-browser.git && cd camofox-browser && npm install && npm run build && npm start (requires Node.js 20+; 2GB+ RAM recommended).
2) npm: npm install -g camofox-browser, then run camofox-browser to start the server, or use the camofox CLI directly (the CLI auto-starts the server when needed).
3) Docker: docker run -d --name camofox-browser -p 9377:9377 -p 6080:6080 -e CAMOFOX_HOST=0.0.0.0 -e CAMOFOX_AUTH_MODE=auto -e CAMOFOX_API_KEY=change-me -v ~/.camofox:/home/node/.camofox ghcr.io/redf0x1/camofox-browser. A Windows x64 portable ZIP (bundles Node.js and the Camoufox engine; headless=true only) and Fly.io/Railway/Render configs are also provided.
How do you use this agent?
After starting, verify with curl http://localhost:9377/health (expect {"ok":true,"engine":"camoufox","browserConnected":true}). REST: create a tab with POST /tabs and {"userId":"agent1","sessionKey":"task1","url":"https://example.com","preset":"japan"}; run a search macro via POST /tabs/:tabId/navigate with {"macro":"@google_search","query":"..."}; GET /tabs/:tabId/snapshot?userId=agent1 for the eN-referenced accessibility tree; POST /tabs/:tabId/click with {"userId":"agent1","ref":"e12"} to interact. CLI: camofox open https://example.com → camofox snapshot → camofox click e5 → camofox screenshot --output page.png → camofox close; add --format for machine-parseable output for agents. Credential injection: camofox auth save gmail once, then camofox auth load gmail --inject --username-ref e5 --password-ref e12. Multi-step flows go in a script file run with camofox run flow.txt. Security notes: CAMOFOX_HOST defaults to 127.0.0.1; non-loopback binds require CAMOFOX_API_KEY under auto mode, and navigation to loopback/private/metadata targets is blocked by default.
How does this agent compare with similar options?
The README directly compares it with Puppeteer/Playwright: those rely on fragile JavaScript-level patches with limited fingerprint spoofing, whereas CamoFox uses Camoufox's C++ engine-level spoofing and exposes a REST API plus accessibility snapshots for language-agnostic, token-efficient integration by any language or AI agent. The underlying engine is daijro's Camoufox, and a companion CamoFox MCP server serves MCP clients like Claude, Cursor, and VS Code.