camofox-browser: a Camoufox-backed browser server for AI agents

The problem: agents that read HTML and get blocked

Two failures tend to arrive together in agent scraping. The first is detection: the README states plainly that Playwright gets blocked and headless Chrome gets fingerprinted, and it adds a sharper observation, that stealth plugins become the fingerprint themselves. The second is token cost. A raw DOM dump is large, noisy and full of markup an agent does not need in order to decide where to click. camofox-browser addresses both at once by pairing the Camoufox engine with an API that returns accessibility snapshots rather than HTML. The audience is narrow and identifiable: people building AI agents that need to read and act on real pages, not people writing conventional end-to-end tests. The project is explicit that it was built by the team behind jo, a personal AI agent, so the API shape reflects the needs of an agent loop rather than the needs of a test runner.

What Camoufox changes, and what the wrapper adds

Camoufox is a Firefox fork that the README describes as spoofing fingerprints at the C++ implementation level, naming navigator.hardwareConcurrency, WebGL renderers, AudioContext, screen geometry and WebRTC. The claimed consequence is that these values are set before JavaScript ever sees them, so there are no shims or wrappers for a detector to spot. That is an architectural distinction worth taking seriously: patching values from JavaScript leaves a trace in the function's own source, while patching below the JS layer does not. camofox-browser does not itself implement any of this. It is a server around the engine, and its own contribution is the interface: accessibility snapshots for reading, stable element refs such as e1, e2 and e3 for acting, and search macros for common sites. The ref scheme is the part that matters most for agents, because a ref that survives across calls lets a model plan a click in one turn and execute it in the next without re-deriving a selector.

Running it: npm start, port 9377, and the binary download

The README gives a three-line start. Clone the repository, run npm install, then npm start, and the server comes up on http://localhost:9377. The first run downloads the Camoufox binary, roughly 300MB, which is the main setup cost. There is also a standalone npm path, npx @askjo/camofox-browser, and an OpenClaw plugin install, openclaw plugins install @askjo/camofox-browser, which exposes tools named camofox_create_tab, camofox_snapshot, camofox_click, camofox_type, camofox_navigate, camofox_scroll, camofox_screenshot, camofox_close_tab, camofox_list_tabs and camofox_import_cookies. The documentation is served by the process itself: an OpenAPI spec at /openapi.json and interactive docs at /docs. One setup trap is documented in detail. The postinstall script unsets PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD for itself, because an exported PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1, common when Playwright is pointed at a system Chrome, would otherwise skip the Camoufox download and crash the server at runtime. If you need to skip the download deliberately, the README points at CAMOUFOX_EXECUTABLE with a path to a Camoufox bundle containing properties.json, version.json and fontconfig, with CAMOUFOX_EXECUTABLE_PATH and CAMOFOX_EXECUTABLE_PATH as compatibility aliases. For air-gapped installs it suggests npm install --ignore-scripts, which it admits is the bluntest option because it skips lifecycle scripts for every dependency, or the more surgical npm install --omit=optional followed by npx camoufox-js fetch against a mirror. The README also notes that yt-dlp is optional and only affects the YouTube transcript endpoint, which falls back to a slower browser-based method without it.

Sessions, cookies and the endpoints that carry real weight

The feature list is long, but a few items decide whether the project fits. Session isolation gives separate cookies and storage per user, which is the difference between a single-user tool and something you can put behind a shared endpoint. Cookie import accepts Netscape-format cookie files, and there is a VNC interactive login path via noVNC that lets a human log in visually and then export storage state for the agent to reuse. That combination is the honest answer to authenticated scraping: automate the repeat visits, do the login by hand once. Structured extract, POST /tabs/:tabId/extract, takes a JSON Schema and maps properties to snapshot refs through an x-ref key, which moves output shaping into the request rather than into post-processing. The server also handles the unglamorous parts that break agent loops in practice: automatic snapshot truncation with offset-based pagination for large pages, download capture, DOM image extraction, file upload from a configured directory, and proxy routing with GeoIP-derived locale and timezone. Optional per-session Playwright tracing records screenshots, DOM snapshots and network activity, with endpoints to list, fetch and delete the trace zips, which is the debugging tool you want when a specific site fails and you cannot reproduce it interactively.

Telemetry is on by default, and that is a decision you make once

The README states that anonymized crash and hang telemetry is sent automatically through GitHub Issues, with the stated goal of identifying which sites cause failures and what the common failure patterns are. It also states the mitigations: private domains are HMAC-hashed, paths and parameters are stripped, and tokens and IPs are redacted. Opting out is a single environment variable, CAMOFOX_CRASH_REPORT_ENABLED=false. This is a defensible design for a scraping tool, since site-specific breakage is exactly the kind of information a maintainer cannot gather alone, and the redaction scheme is described rather than asserted. It is still the first thing to check if your targets are internal or customer-specific, because you are relying on the described hashing and stripping rather than on an independent audit. The reporter implementation is linked in the README at lib/reporter.js, so the claim is checkable in the repository.

Where it stops being the right tool

The README says the engine bypasses Google, Cloudflare and most bot detection. That is a claim from the project, not a measured result, and no benchmark, success rate or test corpus appears in the material. Treat detection bypass as a moving target rather than a property of the software: whatever works in one release can stop working after a site changes its checks, and the release history here shows frequent Camoufox backup builds, which suggests the underlying engine is updated often and the wrapper tracks it. There is also a real cost profile. Memory sits at roughly 40MB when idle because of lazy launch and idle shutdown, but that is the idle figure, and the README does not state what a live browser session costs. The first install pulls about 300MB, which is awkward on constrained hosts even though the project advertises Raspberry Pi and small VPS deployment. And if you need a typed SDK rather than HTTP, this is the wrong shape: the interfaces here are REST endpoints, an OpenAPI spec and an OpenClaw plugin, not a language-native client. Finally, the README excerpt does not describe rate limiting, authentication or multi-tenant hardening for the server itself, so exposing port 9377 beyond localhost is something you would need to solve yourself.

The alternative: driving Camoufox directly with Playwright

The most direct comparison is not another stealth browser but using Camoufox through Playwright directly, which the README itself points at when it calls this project a drop-in Puppeteer and Playwright replacement. The difference is where the work sits. Driving Playwright yourself means you own browser lifecycle, session storage, snapshot formatting, ref assignment, truncation for large pages, download handling and the transcript extraction path, and you get full control over each of those in return. camofox-browser makes those choices for you and exposes them over HTTP, which is the right trade when several agents or several machines need to share one browser process and you would rather not run a browser inside every agent. It is the wrong trade when you have one process and want fine-grained control over the page object. The other common alternative is a hosted scraping or browser API, which removes the operational burden of the Camoufox download and the idle process entirely, at the cost of sending your target URLs and session cookies to a third party and accepting whatever engine that vendor runs. That is a data-handling decision more than a technical one.

Maintenance, licensing and upgrade cost

The licence is MIT, which is permissive and imposes no copyleft obligation on your own code. That covers camofox-browser itself. Camoufox is a separate project and a Firefox fork, so its own licensing and redistribution terms apply to the binary the postinstall script fetches, and that is worth confirming before you ship the browser inside a container image rather than downloading it at build time. On maintenance, the repository is active rather than archived, with a push in September 2026 and a v1.14.0 release in August 2026 titled See the browser when you need to. The release list also includes Camoufox backup builds, v152.0.4-beta.29 and beta.30, which indicates the wrapper is tracking a beta upstream engine and re-vendoring it periodically. That has a practical consequence: expect to rebuild and re-test on a regular cadence, because an engine that is still on a beta version line will change under you. The environment variable surface is another upgrade cost. CAMOUFOX_EXECUTABLE and its two aliases, CAMOFOX_CRASH_REPORT_ENABLED, the Playwright download override and the optional yt-dlp dependency all need to be pinned deliberately in your deployment, and the README's own note about the sanitized postinstall environment shows that the install path has already changed behaviour once.

Editorial conclusion

Adopt camofox-browser if your agent already speaks HTTP and you are willing to own a long-running Node process plus a roughly 300MB Camoufox download, and if the accessibility-snapshot model matches how your agent already reads pages. Do not adopt it if you need a typed SDK, a managed service, or a hard guarantee about which sites will work, because the README names Google and Cloudflare as targets rather than as verified results. Before committing, run npm start, open http://localhost:9377/docs, and check whether the snapshot output for your two or three hardest target pages is something your model can actually act on. Also decide up front whether CAMOFOX_CRASH_REPORT_ENABLED stays at its default, since that choice is easier to make before the server is in production than after.

Official sources

1. jo-inc/camofox-browser on GitHub
2. License: MIT
3. Project website
4. README
5. Releases