CamoFox Browser Server

Anti-detection browser server for AI agents — TypeScript REST API wrapping the Camoufox stealth browser engine

Table of Contents

• Why CamoFox?
• Features
• Preview Status
• Quick Start
• Windows x64 Portable
• CLI
• Console Capture
• Playwright Tracing
• Security
• Usage with AI Agents
• Architecture
• API Reference
• Structured Extract
• Search Macros
• Geo Presets
• Environment Variables
• Deployment
• Used With
• Project Structure
• Contributing
• Credits
• License

Why CamoFox?

The Problem: Standard browser automation (Puppeteer, Playwright, Selenium) is easily detected by modern anti-bot systems. JavaScript-level patches are fragile and get bypassed quickly.

The Solution: CamoFox Browser Server wraps Camoufox, a Firefox fork with C++ engine-level fingerprint spoofing. No JavaScript injection — anti-detection happens at the browser engine level.

Features

• C++ Anti-Detection — fingerprint spoofing at the Camoufox engine level (not JS injection)
• REST API — language-agnostic HTTP endpoints for browser automation and AI agent integration
• Multi-Session — concurrent isolated browser contexts per userId (defaults: max 50 sessions, max 10 tabs/session)
• Persistent Browser Profiles — Each user gets a dedicated Firefox profile. Cookies, localStorage, IndexedDB, and all browser storage persist across sessions automatically.
• Geo Presets — 8 built-in region presets (locale/timezone/geolocation) + custom presets file
• Session-Level Proxy/Geo Overrides — per-session proxy configuration via named profiles or raw credentials, with hybrid geo modes (explicit-wins or proxy-locked)
• 14 Search Macros — Google, YouTube, Amazon, Reddit (search + subreddit JSON), Wikipedia, Twitter, Yelp, Spotify, Netflix, LinkedIn, Instagram, TikTok, Twitch
• Element Refs — accessibility snapshots annotated with stable eN element references for precise interaction
• Cookie Persistence — import Netscape/Playwright-style cookies into a session (bearer auth required only when CAMOFOX_API_KEY is set)
• OpenClaw Plugin — OpenClaw-compatible endpoints (/start, /tabs/open, /act, etc.)
• TypeScript — strict mode, typed request shapes, modular Express routes
• YouTube Transcript Extraction — yt-dlp + browser fallback (service-level; no public API route currently exposed)
• Snapshot Pagination — offset-based windowing for large page snapshots
• Image Listing Route — image-only extraction over the shared resource extractor with selector, extension, lazy-load, and blob-resolution controls
• Structured Extract — deterministic schema-driven JSON extraction across core API, CLI, and OpenClaw without arbitrary JavaScript
• Browser Health Monitoring — health probe with recovery/degraded state tracking
• 🖥️ CLI Mode — 50+ commands for terminal-based browser automation
• 🔐 Auth Vault — AES-256-GCM encrypted credential storage (LLM-safe)
• 📜 Pipeline Scripting — Execute command scripts from files
• 🔍 Console Capture — capture and filter browser console messages and uncaught errors
• 📼 Playwright Tracing — record and export Playwright traces for debugging
• 🗂️ Trace Artifact Management — list, download, and delete managed trace ZIPs per user session

Preview Status

CamoFox Browser Server is in Preview (Phase 1). Preview releases are functional for browser automation and agent integration, but carry specific compatibility commitments and explicit non-goals.

What Preview Means

• The REST API and CLI are usable for agent workflows today; CamoFox MCP is available as an external companion integration
• New features may be added between minor versions
• Backward-compatible aliases are maintained for renamed or moved endpoints (see Compatibility Policy)
• Local state (profiles, registries, sessions) uses versioned formats with fail-closed integrity checks

What Preview Does NOT Guarantee

• Frozen API surface — endpoint behavior, request shapes, or response formats may change between minor versions
• Automatic local-state migration — browser profiles, download registries, and session files use versioned sidecar formats; incompatible upgrades require manual reset (see Local State Recovery)
• Downgrade safety — rolling back to an older version may require clearing local state
• Fixed GA timeline — promotion to GA requires meeting evidence-based exit criteria, not a calendar date

Compatibility Policy

During Preview, CamoFox follows an additive-only deprecation model:

• Legacy aliases (e.g., listItemId accepted alongside sessionKey, OpenClaw /act routing to core endpoints) continue to work alongside their replacements
• Deprecated fields are accepted silently; no removal until GA or a documented migration window with advance notice in CHANGELOG
• No existing endpoint is removed in a minor version — removals happen only in major versions with prior CHANGELOG notice

Local State Recovery

Browser profiles, download registries, and CLI session files use versioned sidecar formats. When upgrading CamoFox:

• Compatible versions: State loads normally
• Incompatible or corrupt state: The server refuses to load incompatible profiles and download registries; the CLI rejects incompatible saved-session files. Both log an actionable error with the specific recovery path.
• Recovery: Delete the affected profile directory, session file, or download registry as indicated in the error message. Clean state is recreated on next use.

Supported sidecars include limited forward-migration paths (e.g., fingerprint v0 → v1); when no migration path exists for a given version, the server refuses to load the file and logs an actionable recovery message. There is no silent repair or downgrade path — this fail-closed default prevents data corruption at the cost of manual intervention on unsupported version jumps.

Quick Start

From Source

git clone https://github.com/redf0x1/camofox-browser.git
cd camofox-browser
npm install
npm run build
npm start

Using npm (CLI)

npm install -g camofox-browser

# Start the server
camofox-browser

# Or use the CLI for browser automation
camofox open https://example.com
camofox snapshot
camofox click e5

See CLI for the complete command reference.

Windows x64 Portable

Windows x64 is supported as a headless-first portable distribution. Release ZIPs are named camofox-browser-<version>-windows-x64.zip and contain the Node.js runtime, application runtime, and the pinned Camoufox Windows x64 engine, so a global Node.js installation is not required.

Extract the ZIP to a writable directory and run the bundled launchers from PowerShell or Command Prompt:

.\camofox.cmd --version
.\camofox.cmd server start --background
.\camofox.cmd server status
.\camofox.cmd server stop

Portable runtime state stays under data\home inside the extracted directory. This includes camofox-browser's .camofox profiles/logs and the bundled Camoufox cache, so the portable distribution does not use the normal Windows user profile for its application state.

The portable ZIP intentionally excludes Camoufox's upstream bundled fonts/ directory because the exact upstream source explicitly does not permit redistribution of those copyrighted Windows/macOS fonts. On Windows, CamoFox uses fonts installed on the host system instead.

The supported Windows x64 display contract is headless=true. headless=false and headless="virtual" are rejected with a clear error before any Linux-only display process is attempted. Xvfb/VNC virtual display mode remains Linux-only, and native headed Windows mode is not part of the verified support contract.

The release workflow verifies the ZIP after extracting it into a path containing spaces, starts the CLI using bundled Node.js with global Node removed from PATH, checks /health, runs a local create → navigate → snapshot → close browser flow, and confirms server shutdown and portable-state placement.

Using Docker

Docker image: ghcr.io/redf0x1/camofox-browser

docker build -t camofox-browser .
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 \
  camofox-browser

To persist browser profiles (cookies, localStorage, IndexedDB, etc.) across container restarts, keep the volume mount shown above.

Using Docker Compose

servi