How daijro/camoufox works
Purpose and Entry Points
Camoufox is a patched Firefox distribution for stealth web automation, scraping, and AI agents. It combines native browser fingerprint controls with a Playwright-compatible Python launcher. Primary user entry points are pythonlib/camoufox/sync_api.py, pythonlib/camoufox/async_api.py, and the CLI module pythonlib/camoufox/__main__.py. Browser distribution builds are driven by multibuild.py, Makefile, and Dockerfile.
Browser Fork and Patch Layer
The repository does not contain Firefox source directly; it fetches an upstream tree, applies this repo’s patch set, then builds/packages the resulting browser. The architecture-defining customization boundary is patches/, including native fingerprint and stealth patches such as patches/fingerprint-injection.patch, patches/navigator-spoofing.patch, and patches/webgl-spoofing.patch. Debloating, privacy, and automation behavior are also encoded as patches, so maintaining Firefox-version compatibility is principally a patch-rebase concern.
Native Configuration and Fingerprint Runtime
Camoufox applies spoofing in Firefox implementation layers rather than page-visible JavaScript. The in-tree configuration component is additions/camoucfg/MaskConfig.hpp, with configuration schema/default inputs in settings/camoucfg.jvv and settings/properties.json. This boundary receives identity properties—such as device, locale, screen, WebGL, media, and network characteristics—and makes browser APIs and request behavior conform to them. Native mouse trajectory support is represented by additions/camoucfg/MouseTrajectories.hpp.
Automation Protocol Isolation
A customized Firefox Juggler implementation is the browser-side automation service used by Playwright. Protocol dispatch begins in additions/juggler/protocol/Dispatcher.js and additions/juggler/protocol/Protocol.js, with browser/page command handlers in additions/juggler/protocol/BrowserHandler.js and additions/juggler/protocol/PageHandler.js. Content-side execution and page interaction are separated into additions/juggler/content/PageAgent.js and additions/juggler/content/Runtime.js. This isolation is central to preventing automation artifacts from appearing in the real page’s JavaScript scope. Native pipe and screencast services bridge external automation to Firefox through additions/juggler/pipe/nsRemoteDebuggingPipe.cpp and additions/juggler/screencast/nsScreencastService.cpp.
Python Launch, Identity Assembly, and Remote Control
The Python package wraps Playwright startup and prepares each browser session. pythonlib/camoufox/fingerprints.py selects/generates fingerprints from bundled preset data; pythonlib/camoufox/geolocation.py, pythonlib/camoufox/ip.py, and pythonlib/camoufox/locales.py align regional identity fields. pythonlib/camoufox/pkgman.py manages browser package acquisition/versioning, while pythonlib/camoufox/display.py and pythonlib/camoufox/virtdisplay.py support headful execution on headless hosts. pythonlib/camoufox/server.py plus pythonlib/camoufox/launchServer.js provide a remote Playwright-serving boundary for non-Python clients.
Distribution Inputs and Build Pipeline
Build flow is: obtain Firefox source, materialize patches/additions, bootstrap Mozilla tooling, compile per target, stage assets, and package portable artifacts. Core orchestration resides in multibuild.py, scripts/bootstrap.py, scripts/patch.py, and scripts/package.py. Platform mozconfigs are assets/linux.mozconfig, assets/macos.mozconfig, and assets/windows.mozconfig. Deterministic visual/font identity depends on bundled platform font sets and fontconfig files under bundle/fonts/ and bundle/fontconfig/. CI builds, lints, and publishes the Python package through .github/workflows/build.yml and .github/workflows/publish-pypi.yml.
External Dependencies and Boundaries
Material runtimes are Python, Node.js (launch server/build tester), Firefox/Mozilla build tooling, Rust, and C++/JavaScript within the browser fork. Docker offers a reproducible build environment via Dockerfile. BrowserForge is the external fingerprint-data source conceptually consumed by the Python layer, while end-user proxy services are external network infrastructure configured by callers rather than owned by this repository. Firefox upstream is the foundational external source; Playwright is the client automation API that communicates with the patched Juggler runtime.
Main entry points: patch.py Patch materializer · fingerprints.py Identity assembly · pkgman.py Browser package manager · MaskConfig.hpp Native mask configuration
Components 21
Python launcher
Session setup and user-facing automation APIs.
- Sync API
pythonlib/camoufox/sync_api.py - Async API
pythonlib/camoufox/async_api.py - CLI
pythonlib/camoufox/__main__.py - Identity assembly · Generates fingerprints and aligns locale, IP, and geolocation.
pythonlib/camoufox/fingerprints.py - Browser package manager
pythonlib/camoufox/pkgman.py - Remote launch server · Serves Playwright-compatible remote clients.
pythonlib/camoufox/server.py - Headful display support
pythonlib/camoufox/virtdisplay.py
Patched Firefox runtime
Native identity controls and isolated Juggler automation.
- Native mask configuration · Applies identity properties inside Firefox implementation layers.
additions/camoucfg/MaskConfig.hpp - Mouse trajectories
additions/camoucfg/MouseTrajectories.hpp - Juggler protocol dispatch · Routes external commands to browser and page handlers.
additions/juggler/protocol/Dispatcher.js - Browser and page handlers
additions/juggler/protocol/BrowserHandler.js - Content page agent · Executes page interactions outside the page-visible automation scope.
additions/juggler/content/PageAgent.js - Remote debugging pipe
additions/juggler/pipe/nsRemoteDebuggingPipe.cpp - Screencast service
additions/juggler/screencast/nsScreencastService.cpp
Build and distribution
Fetches, patches, builds, and packages Firefox.
- Firefox patch set · Defines fingerprint, stealth, privacy, and automation changes.
- Multi-platform build
multibuild.py - Patch materializer
scripts/patch.py - Browser packager · Stages portable browser artifacts and bundled assets.
scripts/package.py - Bundled fonts
Other components
- Upstream Firefox · Fetched Mozilla source tree.
- Playwright clients
Connections 22
- Sync API → Identity assembly: prepares session identity
- Async API → Identity assembly: prepares session identity
- CLI → Sync API: invokes launcher
- Identity assembly → Browser package manager: launches installed browser
- Browser package manager → Native mask configuration: starts packaged Firefox
- Identity assembly → Native mask configuration: passes identity properties
- Headful display support → Browser package manager: provides headful display
- Native mask configuration → Mouse trajectories: configures behavior
- Remote launch server → Remote debugging pipe: connects remote clients
- Playwright clients → Remote launch server: remote automation
- Remote debugging pipe → Juggler protocol dispatch: carries commands
- Juggler protocol dispatch → Browser and page handlers: dispatches commands
- Browser and page handlers → Content page agent: delegates page execution
- Browser and page handlers → Screencast service: controls capture
- Multi-platform build → Upstream Firefox: fetches source
- Multi-platform build → Patch materializer: materializes customization
- Patch materializer → Firefox patch set: applies
- Patch materializer → Native mask configuration: adds native runtime
- Patch materializer → Juggler protocol dispatch: adds automation runtime
- Multi-platform build → Browser packager: builds then packages
- Bundled fonts → Browser packager: staged into artifacts
- Browser packager → Browser package manager: publishes browser artifacts