# Camofox Browser

> Anti-detection browser server for AI agents — REST API wrapping Camoufox engine with OpenClaw plugin support

- **Type:** MCP server
- **Install:** `agentstack add mcp-redf0x1-camofox-browser`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [redf0x1](https://agentstack.voostack.com/s/redf0x1)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [redf0x1](https://github.com/redf0x1)
- **Source:** https://github.com/redf0x1/camofox-browser

## Install

```sh
agentstack add mcp-redf0x1-camofox-browser
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# CamoFox Browser Server

> Anti-detection browser server for AI agents — TypeScript REST API wrapping the [Camoufox](https://github.com/daijro/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](https://github.com/daijro/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](https://github.com/redf0x1/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

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

### Using npm (CLI)

```bash
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`

```bash
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

```yaml
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

```bash
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

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

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

### Quick Start

```bash
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

```bash
# 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

```bash
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

```bash
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.

```bash
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:

```bash
# 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](https://github.com/daijro/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:

```bash
npx skills add redf0x1/camofox-browser
```

This works with **Claude Code**, **Codex**, **Cursor**, **Gemini CLI**, **GitHub Copilot**, **Goose**, **OpenCode**, **Windsurf**, and [40+ other agents](https://github.com/vercel-labs/skills#supported-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

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

#### Cursor / GitHub Copilot / Codex

```bash
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](https://github.com/redf0x1/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:

```bash
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](https://github.com/redf0x1)
- **Source:** [redf0x1/camofox-browser](https://github.com/redf0x1/camofox-browser)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-redf0x1-camofox-browser
- Seller: https://agentstack.voostack.com/s/redf0x1
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.