# camofox-browser: a stealth Firefox server that AI agents drive over HTTP

> camofox-browser wraps the Camoufox anti-detection Firefox fork in a REST API with accessibility snapshots and stable element refs. It is aimed at agent builders who keep getting blocked, and it asks you to accept a 300MB binary download and a single maintainer's release cadence.

**jo-inc/camofox-browser** — Stealth headless browser for AI agents — bypass Cloudflare, bot detection, and anti-scraping. Drop-in Puppeteer/Playwright replacement.

- Repository: https://github.com/jo-inc/camofox-browser
- Website: https://github.com/jo-inc/camofox-browser#readme
- Stars: 11,285 · Forks: 1,118
- Language: JavaScript
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/jo-inc-camofox-browser

## The problem camofox-browser is built to solve

An agent that needs to read the live web usually starts with Playwright or Puppeteer, and the README is blunt about where that ends: "Playwright gets blocked. Headless Chrome gets fingerprinted. Stealth plugins become the fingerprint." The project's answer is to stop patching the browser from JavaScript and instead ship a browser that was never stock to begin with. Camoufox is a Firefox fork that spoofs navigator.hardwareConcurrency, WebGL renderers, AudioContext, screen geometry and WebRTC inside the C++ implementation, so the values are already wrong by the time any page script reads them. camofox-browser is the server around that engine.

The intended user is not a person clicking around a site. It is an AI agent, or the developer wiring one up, that needs a machine-readable view of a page and a way to act on it. That is why the API returns accessibility snapshots rather than raw HTML, and why elements carry stable refs like e1, e2 and e3. The README claims those snapshots are roughly 90% smaller than raw HTML, which matters when the snapshot is going into a model's context window rather than into a parser. If you are writing a scraper that extracts fields with CSS selectors and never calls a model, this project is solving a problem you may not have.

## How the server, sessions and element refs fit together

The process is a long-running HTTP server, not a library you import. server.js is the entry point, the default port is 9377, and the API is described by an auto-generated OpenAPI spec at /openapi.json with interactive docs at /docs. An agent opens a tab, reads a snapshot, then clicks or types against a ref from that snapshot. Sessions are isolated, so cookies and storage do not leak between users, and a session can be seeded by importing a Netscape-format cookie file when you need authenticated browsing.

Two design choices stand out. First, the browser is launched lazily and shut down when idle, which the README says keeps memory around 40MB while nothing is happening. That is what makes the project plausible on a Raspberry Pi or a small shared VPS, and it is also why the first request after an idle period is slower than the rest. Second, the refs are tied to a snapshot. If the page changes between the snapshot and the click, the ref may point at something else, so the workflow is read-then-act rather than hold-a-handle. There is a structured extract endpoint, POST /tabs/:tabId/extract, that takes a JSON Schema and maps properties to snapshot refs through an x-ref key, which is the tidiest way to get typed data out without parsing the snapshot yourself.

The optional pieces are where the project shows its scraper heritage: search macros such as @google_search and @youtube_search, YouTube transcript extraction through yt-dlp, download capture, DOM image extraction, proxy routing with automatic locale and timezone from GeoIP, and a VNC path for logging in visually and exporting storage state for later agent runs.

## Installing camofox-browser and taking a first snapshot

The npm path is the shortest. The first run downloads the Camoufox binary, which the README puts at about 300MB, so budget for that on a cold machine:

```bash
npx @askjo/camofox-browser
```

From source it is a clone, an install and a start. The server listens on port 9377 by default:

```bash
git clone https://github.com/jo-inc/camofox-browser
cd camofox-browser
npm install
npm start
```

One trap is documented in the README and worth repeating: the postinstall script unsets PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD for itself, because an exported PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 would otherwise silently skip the Camoufox download and the server would crash at runtime. If you genuinely want to skip the download, set CAMOUFOX_EXECUTABLE instead:

```bash
CAMOUFOX_EXECUTABLE=/path/to/camoufox-bin npm start
```

The executable has to come from a Camoufox bundle that includes properties.json, version.json and fontconfig/. NixOS users get a worked example in the README, pointing at a /nix/store path. For an air-gapped install the README offers two blunt options: npm install --ignore-scripts, which skips lifecycle scripts for every dependency, or npm install --omit=optional followed by a manual npx camoufox-js fetch against your mirror.

Docker is the other route, and the Makefile does the architecture detection for you. The Makefile defaults to VERSION 135.0.1 and RELEASE beta.24 while the Dockerfile pins CAMOUFOX_VERSION=152.0.4 and CAMOUFOX_RELEASE=beta.28, so check which one your build actually resolves before you assume a version.

```bash
make build
make up
```

The up target runs the container with --shm-size=2g on port 9377 and restarts it unless stopped. Once the server answers, open http://localhost:9377/docs and read the spec before writing client code. The OpenClaw plugin is the third entry point, installed with openclaw plugins install @askjo/camofox-browser, and it 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 package requires Node 22 or newer.

## Where camofox-browser stops being the right tool

The anti-detection story is the selling point, and it is also the part you cannot verify from the repository. The README says the engine bypasses Google, Cloudflare and most bot detection. There is no published detection-rate methodology, no test corpus of protected sites, and no statement about what happens when a bypass stops working. Treat the claim as a starting hypothesis to test against your own target list, not as a guarantee.

The telemetry is the second thing to weigh. The README states that crash and hang telemetry is sent automatically through GitHub Issues, that private domains are HMAC-hashed, that paths and parameters are stripped, and that tokens and IPs are redacted. It also gives the opt-out, CAMOFOX_CRASH_REPORT_ENABLED=false, and points at lib/reporter.js for the implementation. Automatic reporting that identifies which sites cause failures is useful for the maintainers and unusual for a scraping tool. If your targets are confidential, read that file before you ship, because the default is on.

There are operational limits too. The lazy launch and idle shutdown that keep memory low mean a latency spike on the first request after a pause, which is awkward for anything latency-sensitive. The browser download is large enough to be a real cost in CI. And the project is a wrapper around a Firefox fork, so a Camoufox release problem becomes your problem; the release list shows Camoufox backup builds being published alongside the project's own v1.14.0, which tells you how tightly the two are coupled. Finally, the licence is MIT for this repository, but the Camoufox binary is a separate download from a different project, and nothing in the README states its terms. Check that yourself before commercial use.

## camofox-browser versus driving Playwright directly

The obvious alternative is plain Playwright against Chromium or Firefox, which is what most teams already have. The difference is where the stealth lives. Playwright gives you a real automation API, a large ecosystem and a browser you can install in seconds; its fingerprint is whatever the stock browser reports. camofox-browser pushes the spoofing down into the browser implementation and then puts an HTTP server in front, so you give up the in-process API and the debugging ergonomics of a local Playwright script in exchange for a browser whose reported hardware and rendering values were never real.

A second alternative is a hosted scraping API that handles the anti-bot layer for you. That removes the 300MB download and the container, and it also removes your ability to inspect what the browser did. camofox-browser keeps the browser on your machine, which is why session tracing exists: opt-in per-session Playwright traces with screenshots, DOM snapshots and network activity, plus endpoints to list, fetch and delete the trace zips. If you need to prove why a run failed, that is a capability a hosted API will not hand you.

The third comparison is against stealth plugins for Playwright. The README's argument is that those plugins are themselves detectable, because they modify the environment from JavaScript after the page has started watching. Whether that argument holds for your targets is an empirical question. The cheap test is to run both against the same protected page and compare what each one gets back.

## Maintenance, releases and what the licence does not cover

The repository is not archived, and the last push was on 2026-09-09, eight days before this writing. That is recent enough that the project is being worked on now, but it is a single-repository effort published under the Jo Inc organisation, and the README's own framing ties the project to the team's commercial agent product. There is no published support policy, no LTS branch and no compatibility matrix for the API beyond the OpenClaw plugin's declared pluginApi floor of >=2026.3.24-beta.2.

Upgrade cost concentrates in the Camoufox binary rather than in the JavaScript. The Dockerfile pins a Camoufox version and release with build arguments, and the Makefile carries its own defaults, so a rebuild can move you to a different browser without any change to server.js. The Dockerfile also documents a concrete platform hazard: it uses node:22-trixie-slim rather than bookworm because better-sqlite3 ships an arm64 prebuild linked against GLIBC_2.38, which loads on bookworm and then dies at runtime with "version `GLIBC_2.38' not found" the first time a tab is opened, while amd64 is unaffected. If you build your own image from a different base, that failure is waiting for you on arm64.

The licence for this repository is MIT, which is permissive and places few conditions on redistribution. That does not automatically extend to the Camoufox browser binary, which is fetched from a separate upstream project, and the README here says nothing about its terms. Nothing in this article is legal advice; if you are shipping a commercial product, verify the licence of both the server and the browser binary you distribute.

## Conclusion

Adopt camofox-browser if you are building an agent or scraping pipeline that keeps getting fingerprinted and you can run Node 22 or the Docker image on a box with a few hundred megabytes to spare. Do not adopt it if you need a permissively licensed, multi-maintainer project with a documented support policy, or if your targets are internal pages where no anti-bot layer exists. Before committing, verify the Camoufox download completes behind your proxy, confirm that CAMOFOX_CRASH_REPORT_ENABLED=false actually stops the reporter in your build, and read lib/reporter.js to decide whether its redaction matches your own data-handling rules.

## FAQ

### What is camofox-browser used for?

It is an anti-detection browser server for AI agents, built on the Camoufox Firefox fork. Agents use it to open tabs, read accessibility snapshots with stable element refs, and click or type against those refs without getting fingerprinted the way stock Playwright or headless Chrome would be.

### How do I install camofox-browser?

Run npx @askjo/camofox-browser, or clone the repository and run npm install followed by npm start, which downloads the Camoufox binary on first run and serves on port 9377. Docker is also supported through the included Makefile, with make build followed by make up.

### What is camofox-browser?

It is a Node.js HTTP server that wraps Camoufox, a Firefox fork with fingerprint spoofing implemented at the C++ level, and exposes it as a REST API for agents. The package is published as @askjo/camofox-browser and also ships as an OpenClaw plugin.

## Sources

- [jo-inc/camofox-browser on GitHub](https://github.com/jo-inc/camofox-browser)
- [License: MIT](https://github.com/jo-inc/camofox-browser/blob/master/LICENSE)
- [Project website](https://github.com/jo-inc/camofox-browser#readme)
- [README](https://github.com/jo-inc/camofox-browser/blob/master/README.md)
- [Releases](https://github.com/jo-inc/camofox-browser/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jo-inc-camofox-browser