Who camofox-browser is for#
Web-Browsing AI Agents
AI agent pipelines that need to navigate authentication flows, fill forms, and extract structured data from pages that block standard headless browsers. The accessibility snapshot API returns compact, agent-readable output that integrates with any REST-capable agent framework, keeping token costs low across high-volume sessions.
Skip if:
Your agent only accesses public APIs or statically cached data that does not require a real browser session.
Authenticated Session Scraping
Workflows that require logging into sites like LinkedIn or Amazon before extracting data. Cookie import from Netscape-format files and VNC-based interactive login let agents operate in authenticated sessions without storing credentials in code. Persisted browser profiles mean the login survives across server restarts.
Skip if:
Your target sites do not require authentication and serve content to unauthenticated requests without bot detection.
Cost-Sensitive Browser Automation at Scale
Teams running high volumes of browser interactions who need to avoid per-session pricing from managed cloud browser providers. Self-hosting on existing compute brings the marginal cost of additional sessions down to infrastructure cost alone, with no surprise billing spikes when agent workload increases.
Skip if:
You need a fully managed SLA with vendor support contracts, in which case a commercial managed browser provider is more appropriate.
The problem it solves#
AI agents that need to access live web pages face a persistent challenge: standard headless browsers like Playwright's Chromium are rapidly identified and blocked by commercial bot detection systems such as Cloudflare, PerimeterX, and Akamai. JavaScript-level stealth patches (the approach taken by libraries like puppeteer-extra-plugin-stealth) are increasingly fingerprinted, because the patches themselves create detectable patterns in the browser's behavior profile. Managed browser services solve the detection pain but introduce per-session pricing and external infrastructure dependencies that become expensive and unpredictable as agent workload grows. There is no widely available self-hosted alternative that operates at the same fingerprint-spoofing depth as commercial offerings, which forces many teams to accept either high blocking rates or ongoing subscription costs to providers they cannot audit or modify.
How it solves it#
C++ Fingerprint Spoofing
Camofox-browser builds on Camoufox, a Firefox fork that patches fingerprint vectors at the C++ level. Properties including navigator.hardwareConcurrency, WebGL renderers, AudioContext, screen geometry, and WebRTC are spoofed before JavaScript execution, leaving no shim artifacts for bot detection systems to find. Cloudflare, Google, and most commercial anti-bot stacks identify the browser as a legitimate Firefox instance.
Token-Efficient Accessibility Snapshots
Instead of returning raw HTML to agents, the REST API returns accessibility snapshots: structured representations of a page's interactive elements. These snapshots are roughly 90% smaller than equivalent HTML, which reduces token consumption and latency for every page interaction. Large pages are handled through automatic truncation with offset-based pagination.
Stable Element References
Every interactive element in the accessibility snapshot receives a short, stable reference identifier such as e1, e2, or e3. Agents use these identifiers for click, type, scroll, and form-fill actions without re-scraping the page between interactions. This makes multi-step form flows and authenticated login sequences reliable across page loads.
Session Isolation and Profile Persistence
Each user or agent session gets its own cookie storage and localStorage, preventing cross-session data leakage in multi-tenant pipelines. Browser profiles persist across restarts by default, so authenticated sessions survive server reboots. Cookie files in Netscape format can be imported directly, enabling pre-authenticated browsing for sites like LinkedIn or Amazon without an interactive login flow.
Proxy and GeoIP Routing
Configuring a proxy endpoint routes all browser traffic through it, and Camoufox's built-in GeoIP module automatically derives locale, timezone, and geolocation from the proxy's exit IP. The browser fingerprint stays consistent with the proxy location. Backconnect strategies for rotating providers like Bright Data or Oxylabs are supported, with per-session sticky IPs and automatic rotation on proxy errors.
Search Macros and YouTube Transcripts
Named macros such as @google_search, @youtube_search, @amazon_search, and @reddit_subreddit let agents issue structured queries to more than ten common sites without building page-specific parsers. YouTube transcript extraction works via yt-dlp without requiring a YouTube API key, with a browser-based fallback when yt-dlp is not installed.
Strengths and trade-offs#
Strengths
- Self-Hosted with No Per-Session CostsUnder the MIT license, every component of camofox-browser can be inspected, modified, and deployed without usage fees. There are no per-session charges, bandwidth billing, or vendor lock-in, making costs predictable as agent workload grows. Teams can run it on existing infrastructure alongside their other services without a separate managed browser budget.
- Minimal Hardware RequirementsLazy browser launch and idle session shutdown keep memory consumption around 40MB when no session is active. The server is explicitly designed to share a machine with the rest of your stack, and runs correctly on a Raspberry Pi or a $5 VPS. The Docker image bundles all binaries including Camoufox and yt-dlp, so deployment is consistent across environments.
- Drop-In for Playwright and Puppeteer WorkflowsCamofox-browser is designed as a drop-in Puppeteer and Playwright replacement, exposing a REST API that agent frameworks can target without rewriting browser interaction logic. An auto-generated OpenAPI spec is browsable at /docs on any running instance, and the VNC interactive login endpoint lets teams authenticate sessions visually before handing control to an agent.
Trade-offs
- -Initial Binary Download of Approximately 300MBThe first run downloads the Camoufox browser binary, which is approximately 300MB. In air-gapped environments or on slow connections this adds meaningful setup time. Docker builds require running make up rather than docker build directly, because the Makefile pre-downloads binaries before the build step; running docker build alone will fail.
- -Opt-Out Telemetry Enabled by DefaultThe server sends anonymized crash and hang reports to a Cloudflare Worker endpoint by default. Private domain names are HMAC-hashed and URLs are stripped, but teams with strict data governance policies need to explicitly disable this by setting CAMOFOX_CRASH_REPORT_ENABLED=false before starting the server. Telemetry cannot be disabled selectively per session.
camofox-browser vs alternatives#
Camofox-browser vs Browserbase
Browserbase is a managed cloud browser service that handles infrastructure and anti-detection at the vendor level, with per-session or monthly subscription pricing. Teams that prefer not to provision or maintain servers find it convenient. Camofox-browser is MIT licensed and self-hosted: it runs on any Node.js or Docker-compatible host at no per-session cost. For high-volume agent workloads the billing difference is substantial. Browserbase provides a support contract and managed uptime guarantees; camofox-browser provides full infrastructure control, source auditability, and predictable cost tied only to your own hardware.
Camofox-browser vs Bright Data Scraping Browser
Bright Data's Scraping Browser pairs a managed anti-detection browser with Bright Data's residential and datacenter proxy network, billed per gigabyte of traffic. Camofox-browser's backconnect proxy configuration is designed to work with Bright Data as an upstream proxy provider while you self-host the browser layer. Teams that already pay for Bright Data proxies can route camofox-browser sessions through them using the backconnect strategy, keeping the managed proxy network while eliminating the managed browser markup.
Camofox-browser vs Scrapeless
Scrapeless is a cloud API that returns structured data from target URLs without exposing a full browser session to the caller. Camofox-browser provides a complete browser: tab lifecycle management, cookie injection from Netscape files, form filling, VNC-based interactive login, and per-session Playwright trace capture. Scrapeless is simpler to operate for pure data extraction from static or known page structures. Camofox-browser is the appropriate choice when the workload requires navigating authenticated multi-step flows or interacting with dynamic application state.
Camofox-browser vs Oxylabs Headless Browser
Oxylabs Headless Browser is a managed cloud browser service with per-request pricing and an enterprise support tier. Camofox-browser uses the same C++ level fingerprint-spoofing approach in a self-hosted server, which eliminates per-request costs for teams with existing compute capacity. Oxylabs is the better fit when managed availability and a vendor SLA take priority over cost control and infrastructure ownership.
Install and self-host#
Clone the repository and install dependencies to run the browser server locally, or deploy with Docker using the included Makefile.
```bash
git clone https://github.com/jo-inc/camofox-browser
npm install
npm start
```What it's built on#
- Languages
- JavaScriptTypeScript
- Frameworks
- Express
- Runtimes
- Node.js
- Tooling
- PlaywrightPuppeteer
FAQ#
Does camofox-browser actually bypass Cloudflare?
The README states that C++ level fingerprint spoofing bypasses Cloudflare and most commercial bot detection. Camoufox patches fingerprint vectors before JavaScript runs, so there are no JavaScript shim artifacts for detection scripts to find. That said, bot detection systems evolve continuously and no bypass is guaranteed indefinitely; the project tracks failure patterns through its opt-out telemetry to prioritize fixes.
What is the difference between camofox-browser and puppeteer-extra-plugin-stealth?
Stealth plugins for Puppeteer and Playwright work at the JavaScript layer, patching browser properties after the browser has already exposed them. Detection systems can identify these patches because the patches themselves create detectable behavioral signatures. Camoufox, which camofox-browser is built on, patches the same properties at the C++ implementation level before JavaScript ever sees them, leaving no patch artifacts for detection scripts to find.
Does camofox-browser integrate with Playwright and Puppeteer?
Camofox-browser is designed as a drop-in Puppeteer and Playwright replacement. It exposes a REST API that any agent framework can call, with an auto-generated OpenAPI spec browsable at /docs on any running instance. It also installs as an OpenClaw plugin with tools for tab management, clicking, typing, navigation, scrolling, and cookie import.
Can I disable the telemetry?
Yes. Set the environment variable CAMOFOX_CRASH_REPORT_ENABLED=false before starting the server. Telemetry is opt-out by default. When enabled, it sends anonymized crash and hang data to a Cloudflare Worker; private domain names are HMAC-hashed and request paths and parameters are stripped before transmission. No secrets are included in reports.
What are the minimum hardware requirements?
The server keeps idle memory at roughly 40MB through lazy browser launch and idle session shutdown. It is designed to run alongside other services on minimal hardware, including a Raspberry Pi or a $5 VPS. The first run requires downloading the Camoufox browser binary, which is approximately 300MB; subsequent starts use the cached binary.
Similar open-source tools#
browser
Headless browser for AI agents: 9x faster than Chrome, built in Zig
ego-lite
AI agent browser with shared Chrome state, zero cost
JellyBoxPlayer
Native Jellyfin and Emby music player for every platform
stremio-web
Open source web UI for media streaming, powered by community addons.
FckSignups
Open-source tools that work instantly, no signup required
fmt
Fast, type-safe C++ formatting that replaces printf and iostreams