Camofox Browser

CamoFox Browser Server

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

[](LICENSE) [](tsconfig.json) [](package.json) [](https://www.npmjs.com/package/camofox-browser)

Table of Contents

• [Why CamoFox?](#why-camofox)
• [Features](#features)
• [Preview Status](#preview-status)
• [Quick Start](#quick-start)
• [CLI](#cli)
• [Console Capture](#console-capture)
• [Playwright Tracing](#playwright-tracing)
• [Security](#security)
• [Usage with AI Agents](#usage-with-ai-agents)
• [Architecture](#architecture)
• [API Reference](#api-reference)
• [Structured Extract](#structured-extract)
• [Search Macros](#search-macros)
• [Geo Presets](#geo-presets)
• [Environment Variables](#environment-variables)
• [Deployment](#deployment)
• [Used With](#used-with)
• [Project Structure](#project-structure)
• [Contributing](#contributing)
• [Credits](#credits)
• [License](#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.

| Feature | Puppeteer/Playwright | CamoFox Browser Server | |---------|---------------------|------------------------| | Anti-detection | JavaScript patches (fragile) | C++ engine-level (robust) | | Fingerprint spoofing | Limited | Full (engine-level) | | Token efficiency | Raw HTML / screenshots | Accessibility snapshots (smaller + structured) | | Integration | Direct SDK | REST API for any language / AI agent | | AI agent support | Varies | MCP + OpenClaw compatible |

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](#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](#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](#cli) for the complete command reference.

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

services:
  camofox-browser:
    build: .
    ports:
      - "9377:9377"
    environment:
      CAMOFOX_HOST: "0.0.0.0"
      CAMOFOX_PORT: "9377"
      # auto requires CAMOFOX_API_KEY when CAMOFOX_HOST is non-loopback
      CAMOFOX_AUTH_MODE: "auto"
      CAMOFOX_API_KEY: "change-me"
      # CAMOFOX_ADMIN_KEY: "change-me"
      # Optional: proxy routing (also enables Camoufox geoip mode)
      # PROXY_HOST: ""
      # PROXY_PORT: ""
      # PROXY_USERNAME: ""
      # PROXY_PASSWORD: ""

Verify

curl http://localhost:9377/health
# {"ok":true,"engine":"camoufox","browserConnected":true}

CLI

CamoFox Browser includes a powerful CLI for browser automation directly from the terminal. The CLI auto-starts the server when needed.

Installation

# Global install (recommended)
npm install -g camofox-browser

# Or use npx (no install needed)
npx camofox-browser open https://example.com

Quick Start

camofox open https://example.com       # Open a page in anti-detection browser
camofox snapshot                       # Get accessibility tree with element refs
camofox click e5                       # Click element [e5]
camofox type e3 "hello world"         # Type into element [e3]
camofox screenshot --output page.png   # Save screenshot
camofox close                          # Close the tab

Core Commands

# Browser lifecycle
camofox open                      # Open URL in new tab
camofox close [tabId]                  # Close tab
camofox navigate                  # Navigate current tab to URL

# Inspection
camofox snapshot                       # Get accessibility tree with [eN] refs
camofox screenshot [--output file]     # Take screenshot (saves to file)
camofox annotate                       # Screenshot + element ref overlay
camofox get-url                        # Get current page URL
camofox get-text                       # Get page text content
camofox get-links                      # Get all links on page
camofox get-tabs                       # List open tabs
camofox extract-structured @schema.json # Extract deterministic JSON from a schema

# Interaction
camofox click                     # Click element by ref
camofox type                # Type text into element
camofox fill '[e1]="user" [e2]="pw"'  # Fill multiple fields at once
camofox scroll              # Scroll up/down/left/right
camofox select             # Select dropdown option
camofox hover                     # Hover over element
camofox press                     # Press keyboard key
camofox drag                 # Drag element to target

# Navigation
camofox go-back                        # Browser back
camofox go-forward                     # Browser forward
camofox search "query" --engine google # Search (14 engines supported)
camofox eval "document.title"          # Execute JavaScript
camofox wait  [--timeout ms] # Wait for element

> Text input: CamoFox has no character limit for typed or filled text. Short text stays humanized for anti-detection, while long text automatically switches to bulk DOM insertion so large inputs do not truncate.

Session Management

camofox session save             # Save current browser state
camofox session load             # Restore browser state
camofox session list                   # List saved sessions
camofox session delete           # Delete saved session

Cookie Management

camofox cookie export            # Export cookies to JSON file
camofox cookie import            # Import cookies from JSON file

Auth Vault

Securely store credentials locally with AES-256-GCM encryption. Credentials are never output to stdout — safe for LLM agent automation.

camofox auth save  [--url URL]  # Save credentials (prompts for master password)
camofox auth load               # Show profile info (username only)
camofox auth list                        # List saved profiles (no secrets shown)
camofox auth delete             # Delete a profile
camofox auth change-password    # Change master password

# Inject credentials into a browser tab (LLM-safe)
camofox snapshot                         # Get element refs first
camofox auth load gmail --inject --username-ref e5 --password-ref e12

> Security: Master passwords use Argon2id KDF (with PBKDF2 fallback). Vault files are stored with 0600 permissions. The --inject flag sends credentials directly to the browser — the LLM agent never sees the password.

Pipeline Scripting

Execute multiple commands from a file for automation workflows:

# Create a script
cat > login-flow.txt ` | `CAMOFOX_USER` | User/profile ID | `cli-default` |
| `--port ` | `PORT` | Server port | `9377` |
| `--format ` | — | Output: `json`, `text`, `plain` | `text` |
| `-V, --version` | — | Show version | — |
| `-h, --help` | — | Show help | — |

### Output Formats

```bash
camofox get-url --format json          # {"url":"https://example.com"}
camofox get-url --format text          # URL: https://example.com
camofox get-url --format plain         # https://example.com

> Tip: Use --format json for programmatic parsing and LLM agent integration.

Security

Anti-Detection

CamoFox uses Camoufox, a Firefox fork with C++ level fingerprint spoofing. Unlike Chromium-based tools, CamoFox passes bot detection on Google, Cloudflare, and other anti-bot services.

Auth Vault

• AES-256-GCM encryption with Argon2id key derivation (PBKDF2 fallback)
• Credentials never appear in stdout (safe for LLM agent pipelines)
• Vault files stored with 0600 permissions
• Master password required for all vault operations

LLM Agent Safety

• The --inject flag sends credentials directly to the browser — the LLM agent orchestrating the CLI never sees raw passwords
• Output formats are designed for safe parsing without credential exposure
• Pipeline scripts can reference auth profiles without embedding secrets

Usage with AI Agents

CamoFox works seamlessly with AI coding agents and LLM-powered automation:

AI Coding Assistants (Recommended)

Add CamoFox skills to your AI coding assistant for full browser automation context:

npx skills add redf0x1/camofox-browser

This works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Goose, OpenCode, Windsurf, and 40+ other agents.

Available skills:

| Skill | Focus | Best For | |-------|-------|----------| | camofox-browser | Full coverage (CLI + API + OpenClaw) | Complete reference | | camofox-cli | CLI-only (50+ commands) | Terminal-first workflows | | dogfood | QA testing workflow | Systematic web app testing | | gemini-image | Gemini image generation | AI image automation | | reddit | Reddit automation | Reddit posting/commenting |

The installer will prompt you to choose which skills and which agents to configure.

Claude Code

npx skills add redf0x1/camofox-browser
# Installs to .claude/skills/camofox-browser/SKILL.md

Cursor / GitHub Copilot / Codex

npx skills add redf0x1/camofox-browser
# Installs to .agents/skills/ directory

> Tip: Skills are symlinked from the repo, so they stay up to date. Do not manually copy SKILL.md files.

MCP Integration (Recommended)

Use CamoFox MCP for direct integration with Claude, Cursor, Windsurf, and other MCP-compatible agents. See [Used With](#used-with).

CLI Integration

AI agents can use the CLI with --format json for structured output:

camofox open https://example.com       # Open page
camofox snapshot --format json         # Get structured element tree
camofox click e5                       # Interact with elements
camofox auth load gmail --inject --username-ref e5 --password-ref e12  # Safe credential injection

Pipeline Automation

Create reusable

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: redf0x1
• Source: redf0x1/camofox-browser
• License: MIT

Install and usage instructions live in the source repository linked above.