CamoFox Browser Server moves anti-detection out of JavaScript

Spoofing happens in the engine, not in injected JavaScript

The project wraps Camoufox, a Firefox fork that spoofs fingerprints at the C++ engine level, and exposes it as a TypeScript REST API. The argument it makes against Puppeteer, Playwright and Selenium is specific: those tools are easy for modern anti-bot systems to catch, and the JavaScript-level patches that try to hide a driver get bypassed quickly. Injection leaves traces in the page; an engine that reports a different platform, screen and font set does not have to.

Three consequences follow from that choice. Fingerprint spoofing is a property of the engine rather than something a caller can forget to enable. The output an agent receives is an accessibility snapshot rather than raw HTML or a screenshot, which the project counts as smaller and structured. And integration stops being an SDK question: anything that speaks HTTP can drive it, which is the point of the wrapper.

Fifty sessions, ten tabs, one Firefox profile each

Isolation is keyed on `userId`. Each one gets a concurrent, isolated browser context, and each context owns a dedicated Firefox profile whose cookies, localStorage and IndexedDB survive across sessions. Defaults are fixed in the project: at most 50 sessions and at most 10 tabs per session, so a runaway agent loop hits a wall instead of consuming the host.

Two related routes extend that model. Cookies can be imported into a session in Netscape or Playwright format, and bearer authentication is required for that route only when `CAMOFOX_API_KEY` is set, which leaves the import open by default. OpenClaw-compatible endpoints such as `/start`, `/tabs/open` and `/act` sit alongside the core API, and the repository ships `plugin.ts` plus an `openclaw.plugin.json` that register it as an extension.

The CLI is the same server from a terminal, with 50 or more commands, an AES-256-GCM Auth Vault for credential storage, and pipeline scripting that executes command files rather than single calls.

Extract without handing the agent arbitrary JavaScript

Structured Extract is the part worth knowing about if you are building an agent on top. Extraction is deterministic and schema-driven, and it runs the same way across the core API, the CLI and the OpenClaw plugin. There is no arbitrary JavaScript evaluated in the page, which removes an entire category of both prompt injection and sandbox escape from the design.

Around that sit three narrower mechanisms. Element Refs annotate accessibility snapshots with stable `eN` references, so a click targets an identifier the previous response handed out rather than a selector written from scratch. Snapshot Pagination windows large pages by offset instead of truncating them. An image listing route runs over the shared resource extractor with controls for selector, extension, lazy-load and blob resolution.

Console Capture and Playwright Tracing cover the debugging half. Console messages and uncaught errors can be captured and filtered, traces can be recorded and exported, and managed trace ZIPs can be listed, downloaded and deleted per user session. YouTube transcript extraction sits at the service level with a yt-dlp download and a browser fallback, and the project states plainly that no public API route is exposed for it yet.

Geo presets and two ways to resolve a proxy conflict

Region settings ship as eight built-in presets covering locale, timezone and geolocation, plus a custom presets file when none of the eight match your target. Proxy configuration is per session rather than global, and can point at a named profile or at raw credentials. The repository includes `proxy-profiles.test.json`, which suggests the named-profile form is the one exercised by tests.

When a session also has geo settings, the project names the conflict and resolves it in one of two modes. `explicit-wins` lets what you passed take precedence. `proxy-locked` lets the proxy decide. There is no implicit default stated in the docs, so a session configured both ways is a session you have to configure deliberately.

Fourteen search macros cover Google, YouTube, Amazon, Reddit with both search and subreddit JSON, Wikipedia, Twitter, Yelp, Spotify, Netflix, LinkedIn, Instagram, TikTok and Twitch. That list is long enough to read as an inventory, which is what it is: a fixed set of shortcuts, not a general search interface.

Preview status means the endpoint list can still move

The project labels itself Preview, Phase 1, and separates what that guarantees from what it does not. The REST API and CLI are described as usable for agent workflows today, with CamoFox MCP offered as a separate companion integration. The guarantees are an additive-only deprecation model and versioned local state formats with fail-closed integrity checks.

The guarantees that are absent matter more. Endpoint behaviour, request shapes and response formats may change between minor versions. Local state is not migrated automatically, and rolling back to an older version can require clearing state. Promotion out of Preview depends on evidence-based exit criteria rather than a date, so nobody can tell you when the surface freezes.

The deprecation model itself is narrower and more useful. Legacy aliases keep working next to their replacements, with `listItemId` still accepted alongside `sessionKey` and OpenClaw `/act` still routing to the core endpoints. Deprecated fields are accepted silently, no endpoint disappears in a minor version, and removals wait for a major version with prior notice in CHANGELOG. Client code written against an old alias keeps running, and code written against the current shape may still need to change.

Incompatible state is refused, and the fix is a delete

Browser profiles, download registries and CLI session files all use versioned sidecar formats. Compatible versions load normally. Anything else fails loudly: the server refuses to load incompatible profiles and download registries, the CLI rejects incompatible saved-session files, and both log an actionable error naming the specific recovery path.

That recovery path is deletion. Remove the profile directory, session file or download registry the error message points at, and clean state is recreated on next use. Forward migration is supported only where a path exists, and the one the project names is fingerprint v0 to v1. Where no path exists there is no silent repair and no downgrade path. A developer who upgrades across two breaking state versions loses the affected profiles, which in practice means losing stored cookies and site logins rather than losing work.

The same fail-closed logic covers a corrupt file, which reads as the right default for a tool holding credentials. It is also the reason the version numbers in CHANGELOG deserve reading before every upgrade.

Node 20 on your machine, node:22-slim in a container

The runtime floor is Node 20. `package.json` declares `node: >=20`, ships two binaries named `camofox-browser` and `camofox`, and compiles with tsc from `dist/src/server.js`. Local development and local tests come from the script set rather than a separate toolchain:

"dev": "tsx watch src/server.ts",
"build": "tsc",
"start": "node dist/src/server.js",
"lint": "tsc --noEmit",
"test": "jest --runInBand --detectOpenHandles"

The container path builds the same code from node:22-slim, installs the Firefox runtime libraries Camoufox needs, clones noVNC for a web view and downloads a pinned yt-dlp at version 2026.02.21. The Compose service publishes two ports, 9377 for the API and 6080 for the VNC web client, and maps `~/.camofox` to `/home/node/.camofox` so profiles, downloads and cookies survive a container rebuild. `CAMOFOX_PROFILES_DIR` is set to `/home/node/.camofox/profiles` in the image. A `fly.toml` at the repository root points at a deployment path, though what it configures is not visible from the files here.

The visible documentation stops before the API reference

The README page available for this project is cut off inside the Local State Recovery section, mid-sentence. Everything after that point is unverified: the API reference with its endpoint list and request shapes, the Console Capture and Playwright Tracing sections, the full macro list with parameters, the geo preset table, the environment variable list, the deployment notes and the project structure.

What is verifiable is still substantial. Feature names, the session and tab limits, the geo and proxy modes, the compatibility policy and the state recovery behaviour are all stated in the visible part, and the published package metadata agrees with them on version and licence. The last three tags are v2.4.6 on 2026-06-17, v2.4.7 on 2026-08-13 and v2.4.8 on 2026-09-22, the last push landing on the same day as v2.4.8.

Before adopting, read the API reference in the repository rather than the summary. Endpoint names are the part this project reserves the right to change, and the aliases that protect you are only useful if you know which one you called.

Editorial conclusion

Take CamoFox Browser Server if your agent needs a browser that survives anti-bot checks and you would rather call HTTP than drive a local SDK, and accept that you are committing to Firefox rather than Chromium. Skip it if you need a stable endpoint surface or automatic state upgrades: Preview status means request shapes can change between minor versions, and a bad upgrade costs you a profile directory. Verify first that the Camoufox engine launches on your host, then read the Local State Recovery section, because the recovery path is a delete, not a repair.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. redf0x1/camofox-browser on GitHub
5. Releases