camofox-browser: a REST wrapper around the Camoufox stealth engine, still in Preview
Anti-detection browser server for AI agents — REST API wrapping Camoufox engine with OpenClaw plugin support
At a glance
- What is it?
- camofox-browser puts the Camoufox Firefox fork behind an Express REST API and a 50-plus-command CLI so agents can drive a browser over HTTP. It is usable now, but its own README labels it Preview and warns that local state will not migrate automatically between versions.
- Who is it for?
- Adopt camofox-browser if you need an HTTP-shaped browser service rather than a Node SDK, and if your agent stack already speaks REST or the OpenClaw endpoints. Do not adopt it if you need a frozen API surface or automatic state migration; the README states plainly that neither is guaranteed during Preview.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 34 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The detection problem camofox-browser is built to move
The README frames the problem in one line: standard automation stacks (Puppeteer, Playwright, Selenium) are detected by modern anti-bot systems, and the JavaScript-level patches used to hide them are described as fragile and quickly bypassed. camofox-browser is the author's answer to that, and the answer is architectural rather than clever. It does not patch page JavaScript. It wraps Camoufox, a Firefox fork whose fingerprint spoofing happens in the C++ engine, and exposes that engine as an HTTP service. The project's own comparison table puts anti-detection at the engine level against JavaScript patches, and fingerprint spoofing as full rather than limited.
The audience is narrow and specific. This is for people building AI agents or scraping pipelines that need a browser they can call over HTTP, in any language, rather than a Node library they must import. The README lists MCP and OpenClaw compatibility as integration points, and the repository ships an OpenClaw plugin with its own endpoints. If you are writing a Python agent, a Go worker, or a shell pipeline, the REST surface is the point. If you are already inside a Node process and happy with Playwright's API, the wrapper adds a network hop and a session model you did not ask for.
How the session, profile and snapshot layers fit together
The mechanism visible in the README is a multi-session server. Each userId gets concurrent isolated browser contexts, with documented defaults of 50 sessions and 10 tabs per session. On top of that sits persistence: every user gets a dedicated Firefox profile, and cookies, localStorage, IndexedDB and other browser storage carry across sessions automatically. That combination is what makes it usable for agents that need to log in once and keep acting, rather than re-authenticating on every request.
Page content reaches the agent as an accessibility snapshot annotated with stable eN element references, which the README contrasts with raw HTML or screenshots on token efficiency. The claim is that snapshots are smaller and structured. Large pages are handled by offset-based snapshot pagination, so a caller can window through a big document instead of pulling all of it. There is a separate image listing route that reuses a shared resource extractor, with controls for selector, extension, lazy-loading and blob resolution. Console capture and Playwright tracing are available for debugging, and trace ZIPs are managed per user session with list, download and delete operations.
Around the browser sits configuration that matters for scraping work. There are 8 built-in geo presets covering locale, timezone and geolocation, plus a custom presets file. Proxy and geo can be overridden per session, either through named profiles or raw credentials, with two hybrid geo modes named explicit-wins and proxy-locked. The README does not explain what those two modes do in detail, which is a gap worth flagging: the names imply a precedence rule between explicit geo settings and proxy-derived location, but the resolution order is not spelled out in the material available here.
Getting it running: install, CLI, and the environment variables that matter
The README documents an npm package and a Node 20 or later requirement, with TypeScript in strict mode. The package is published as camofox-browser, and the README carries an npm version badge pointing at that name. A Docker deployment path is listed among the topics and in the deployment section, and there is a separate section for a Windows x64 portable build, which suggests the maintainer expects the engine to be awkward to build from source on that platform.
The CLI is the part you can exercise without writing an HTTP client. The README describes it as 50-plus commands for terminal-based browser automation, and it also supports pipeline scripting, meaning command scripts can be executed from files rather than typed one at a time. That is a reasonable way to check whether the engine actually launches in your environment before you wire an agent to it.
Two configuration details are worth calling out because they change behaviour rather than just tuning it. First, cookie import accepts Netscape-style and Playwright-style cookies, and the README notes that bearer auth is required only when CAMOFOX_API_KEY is set. That means an unset key leaves the server open, which is a deployment decision you have to make deliberately rather than by default. Second, credentials can be stored in an Auth Vault using AES-256-GCM encryption, described as LLM-safe. The vault is the reason the project can be handed to an agent that might otherwise see raw passwords in a prompt or a log.
Preview status is the real constraint, not the feature list
The README devotes a whole section to what Preview means, and it is unusually candid. The REST API and CLI are described as usable for agent workflows today, but the document explicitly does not guarantee a frozen API surface: endpoint behaviour, request shapes and response formats may change between minor versions. It also does not guarantee automatic local-state migration. Browser profiles, download registries and CLI session files use versioned sidecar formats with fail-closed integrity checks. When state is incompatible or corrupt, the server refuses to load the profile or registry, and the CLI rejects the saved session file, logging an error with a recovery path. The recovery path is deletion. Clean state is recreated on next use.
Downgrade safety is called out as another non-guarantee: rolling back to an older version may require clearing local state. For a scraper that has accumulated logged-in profiles, that is a real cost. The compatibility policy softens the API side by promising additive-only deprecation during Preview, with legacy aliases such as listItemId accepted alongside sessionKey, deprecated fields accepted silently, and no endpoint removed in a minor version. But the policy governs the wire format, not your stored profiles. An operator can have a stable API contract and still lose a week of accumulated session state on an upgrade.
The other honest limitation is scope. YouTube transcript extraction is documented as a service-level capability with yt-dlp plus a browser fallback, and the README states there is no public API route exposed for it currently. So a feature can exist in the codebase and still be unreachable from the surface you are integrating against.
Where a plain Playwright service is the better choice
The obvious alternative is running Playwright yourself behind a small HTTP layer, or using one of the existing browser-service projects in that ecosystem. The difference in approach is where the spoofing happens. Playwright drives real Chromium and relies on JavaScript-level patches and launch flags to look less automated, which the README characterises as fragile. camofox-browser instead delegates to Camoufox, a Firefox fork with engine-level fingerprint spoofing, and adds its own session, profile and snapshot layers on top.
That trade cuts both ways. Choosing camofox-browser means accepting a Firefox fork rather than Chromium, which changes rendering behaviour, extension support and the debugging tools you already know. It also means your page content arrives as an accessibility snapshot with eN references by default, which is excellent for agent token budgets but is not the same as having the DOM. Teams with existing Playwright test suites, Chromium-specific selectors or Chrome DevTools Protocol tooling will find the wrapper gets in the way rather than helping. The right question is not which is more stealthy in the abstract, but whether your targets actually fingerprint at the engine level. If they mostly rate-limit and check headers, a plain Playwright service with a proxy pool is simpler and has no Preview caveats attached.
Maintenance, licence and the upgrade bill
The project is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and licence text are preserved. That is the permissive end of the spectrum, and the README carries an MIT badge linking to the LICENSE file. Nothing in the supplied material suggests any additional restriction, but the licence text itself is the authority, not the badge.
Maintenance cost shows up in three places. First, the engine: camofox-browser is a wrapper, so Camoufox releases are upstream work you inherit whether or not the wrapper changes. Second, the state formats: versioned sidecars mean an upgrade can invalidate profiles, download registries and CLI session files, and the documented remedy is deletion rather than migration. Third, the release cadence visible in the supplied material shows v2.4.5 in May, v2.4.6 in June, and v2.4.7 in August, so roughly monthly minor releases. Under the additive-only policy that is safe for your HTTP client, but each of those bumps is a chance for a state-format change. Pinning a version and testing the upgrade on a throwaway profile directory is cheaper than discovering the fail-closed behaviour in production.
Structured extract, search macros and the OpenClaw surface
Two features deserve separate attention because they shape what you build on top. Structured Extract is described as deterministic schema-driven JSON extraction available across the core API, CLI and OpenClaw, and the README is explicit that it does not execute arbitrary JavaScript. That is a deliberate constraint: you get predictable output shapes and no remote code execution surface, at the cost of being unable to express extraction logic the schema language does not cover. If your scraping needs custom traversal, you will be doing it in your own process against the snapshot rather than inside the browser.
The 14 search macros cover Google, YouTube, Amazon, Reddit (including subreddit JSON), Wikipedia, Twitter, Yelp, Spotify, Netflix, LinkedIn, Instagram, TikTok and Twitch. These are convenience wrappers, not a general search abstraction, and the list is a fair signal of what the maintainer actually targets. The OpenClaw plugin exposes its own endpoint set, with /start, /tabs/open and /act named in the README, and the compatibility policy notes that OpenClaw /act routing maps onto core endpoints. If you are not in the OpenClaw ecosystem, that surface is irrelevant and the core REST API is what you integrate against.
What to check before you commit a production agent to it
The material supports a fairly clean decision boundary. Take it if you want a language-agnostic browser service, you value accessibility snapshots over raw HTML for token economy, and you are comfortable tracking a Preview project whose state formats can break on upgrade. Skip it if you need a frozen API contract for a long-lived integration, if you depend on Chromium-specific behaviour, or if losing accumulated login state on a version bump is unacceptable for your workload.
The verification order that follows from the README: confirm the Camoufox engine launches on your target platform, since the existence of a dedicated Windows x64 portable section implies the build is not trivial everywhere. Then confirm your concurrency fits the documented defaults of 50 sessions and 10 tabs per session, and decide whether to raise them. Then decide whether CAMOFOX_API_KEY is set in your deployment, because leaving it unset means the server accepts unauthenticated requests. Finally, treat profile directories, download registries and CLI session files as disposable artifacts in your runbooks, because that is exactly how the project treats them on an incompatible upgrade.
Editorial conclusion
Adopt camofox-browser if you need an HTTP-shaped browser service rather than a Node SDK, and if your agent stack already speaks REST or the OpenClaw endpoints. Do not adopt it if you need a frozen API surface or automatic state migration; the README states plainly that neither is guaranteed during Preview. Before committing, verify three things against your own deployment: that the Camoufox engine builds on your target platform, that your session and tab ceilings fit under the documented defaults of 50 sessions and 10 tabs per session, and that you can accept deleting profile directories and download registries on an incompatible upgrade, since that is the documented recovery path rather than a migration.
Community notes