redf0x1/camofox-browser

CamoFox Browser Server

What it is – A TypeScript‑based server that wraps the Camoufox stealth‑Firefox engine (a fork of Firefox with C++‑level fingerprint spoofing). It exposes a language‑agnostic REST API and a powerful CLI, letting AI agents or any program control a browser that is far harder for anti‑bot systems to detect than standard automation tools like Puppeteer or Playwright.

Why it matters for AI agents – Modern bot‑detection services look for the tell‑tale fingerprints left by headless Chromium browsers. CamoFox moves the spoofing down to the browser engine itself, so the resulting sessions appear like a regular user’s Firefox. The server returns structured accessibility snapshots (tiny JSON trees with stable eN element references) instead of raw HTML or screenshots, which makes it cheap for LLM‑driven agents to parse and act on.

Key capabilities

• Engine‑level anti‑detection – C++ fingerprint spoofing (locale, timezone, canvas, WebGL, etc.)
• REST API – HTTP endpoints for opening pages, clicking, typing, taking screenshots, extracting structured data, etc.; usable from any language.
• CLI – 50+ commands (camofox open, snapshot, click e5, type e3 "text", trace start, …) that auto‑start the server when needed.
• Multi‑session & profiles – Up to 50 concurrent user sessions, each with its own persistent Firefox profile (cookies, localStorage, IndexedDB survive restarts).
• Geo & proxy presets – 8 built‑in region presets and per‑session proxy configuration, with hybrid “explicit‑wins” or “proxy‑locked” modes.
• Search macros – One‑line searches on Google, YouTube, Amazon, Reddit, Wikipedia, Twitter, etc.
• Auth vault – AES‑256‑GCM encrypted credential store (Argon2id‑derived keys) that can inject credentials directly into the browser without ever exposing them to the calling LLM.
• Playwright tracing – Record and export traces for debugging complex interactions.
• Structured extraction – Deterministic JSON output based on a user‑supplied schema, avoiding arbitrary JavaScript execution.
• Docker & portable Windows builds – Official Docker image (ghcr.io/redf0x1/camofox-browser) and a headless‑first Windows‑x64 ZIP that bundles Node.js and the Camoufox binary.

Typical workflow for an LLM‑driven agent

1. Start the server (camofox or via Docker).
2. Open a page – camofox open https://example.com.
3. Snapshot – camofox snapshot --format json → JSON tree with stable eN refs.
4. Interact – camofox click e5, camofox type e3 "hello".
5. Extract data – camofox extract-structured @schema.json or use the /extract API endpoint.
6. Persist state – camofox session save login-flow for later reuse.
7. Securely log in – store credentials in the vault (camofox auth save gmail) and inject them (camofox auth load gmail --inject --username-ref e5 --password-ref e12).

Maturity – Currently in Preview (Phase 1). The API works, but endpoint signatures may still change between minor releases, and local state migrations require manual reset on incompatible upgrades.

Getting started

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

# Or install the CLI globally
npm install -g camofox-browser
camofox open https://example.com
camofox snapshot --format json

Where it fits – A front‑end for AI agents that need reliable, low‑profile web interaction (web‑search, form‑filling, data extraction, testing) without the detection pitfalls of typical headless browsers.