# daijro/camoufox architecture

> Architecture diagram of the GitHub repository daijro/camoufox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/daijro/camoufox
- Repository: https://github.com/daijro/camoufox

## Overview

#### 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: [`scripts/patch.py`](https://github.com/daijro/camoufox/blob/main/scripts/patch.py) (Patch materializer), [`pythonlib/camoufox/fingerprints.py`](https://github.com/daijro/camoufox/blob/main/pythonlib/camoufox/fingerprints.py) (Identity assembly), [`pythonlib/camoufox/pkgman.py`](https://github.com/daijro/camoufox/blob/main/pythonlib/camoufox/pkgman.py) (Browser package manager), [`additions/camoucfg/MaskConfig.hpp`](https://github.com/daijro/camoufox/blob/main/additions/camoucfg/MaskConfig.hpp) (Native mask configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python launcher"]
  node_sync_api["Sync API<br/>Python entry point<br/>[sync_api.py]"]
  node_async_api["Async API<br/>Python entry point<br/>[async_api.py]"]
  node_cli["CLI<br/>Python entry point<br/>[__main__.py]"]
  node_identity["Identity assembly<br/>Python session config<br/>[fingerprints.py]"]
  node_package_manager["Browser package manager<br/>Python distribution client<br/>[pkgman.py]"]
  node_remote_server["Remote launch server<br/>Python and Node service<br/>[server.py]"]
  node_display["Headful display support<br/>Python display runtime<br/>[virtdisplay.py]"]
end

subgraph group_browser["Patched Firefox runtime"]
  node_mask_config["Native mask configuration<br/>C++ identity runtime<br/>[MaskConfig.hpp]"]
  node_mouse["Mouse trajectories<br/>C++ behavior runtime"]
  node_juggler_protocol["Juggler protocol dispatch<br/>Browser automation protocol<br/>[Dispatcher.js]"]
  node_juggler_handlers["Browser and page handlers<br/>Juggler command handlers<br/>[BrowserHandler.js]"]
  node_content_agent["Content page agent<br/>Isolated content runtime<br/>[PageAgent.js]"]
  node_pipe["Remote debugging pipe<br/>C++ transport"]
  node_screencast["Screencast service<br/>C++ browser service"]
end

subgraph group_build["Build and distribution"]
  node_patches["Firefox patch set<br/>Patch layer"]
  node_orchestrator["Multi-platform build<br/>Build orchestrator<br/>[multibuild.py]"]
  node_patch_materializer["Patch materializer<br/>Build stage<br/>[patch.py]"]
  node_packager["Browser packager<br/>Build stage<br/>[package.py]"]
  node_fonts["Bundled fonts<br/>Visual identity assets"]
end

node_firefox_upstream["Upstream Firefox<br/>External source"]
node_playwright["Playwright clients<br/>External automation API"]

node_sync_api -->|"prepares session identity"| node_identity
node_async_api -->|"prepares session identity"| node_identity
node_cli -->|"invokes launcher"| node_sync_api
node_identity -->|"launches installed browser"| node_package_manager
node_package_manager -->|"starts packaged Firefox"| node_mask_config
node_identity -->|"passes identity properties"| node_mask_config
node_display -->|"provides headful display"| node_package_manager
node_mask_config -->|"configures behavior"| node_mouse
node_remote_server -->|"connects remote clients"| node_pipe
node_playwright -->|"remote automation"| node_remote_server
node_pipe -->|"carries commands"| node_juggler_protocol
node_juggler_protocol -->|"dispatches commands"| node_juggler_handlers
node_juggler_handlers -->|"delegates page execution"| node_content_agent
node_juggler_handlers -->|"controls capture"| node_screencast
node_orchestrator -->|"fetches source"| node_firefox_upstream
node_orchestrator -->|"materializes customization"| node_patch_materializer
node_patch_materializer -->|"applies"| node_patches
node_patch_materializer -->|"adds native runtime"| node_mask_config
node_patch_materializer -->|"adds automation runtime"| node_juggler_protocol
node_orchestrator -->|"builds then packages"| node_packager
node_fonts -->|"staged into artifacts"| node_packager
node_packager -->|"publishes browser artifacts"| node_package_manager

click node_sync_api "https://github.com/daijro/camoufox/blob/main/pythonlib/camoufox/sync_api.py"
click node_async_api "https://github.com/daijro/camoufox/blob/main/pythonlib/camoufox/async_api.py"
click node_cli "https://github.com/daijro/camoufox/blob/main/pythonlib/camoufox/__main__.py"
click node_identity "https://github.com/daijro/camoufox/blob/main/pythonlib/camoufox/fingerprints.py"
click node_package_manager "https://github.com/daijro/camoufox/blob/main/pythonlib/camoufox/pkgman.py"
click node_remote_server "https://github.com/daijro/camoufox/blob/main/pythonlib/camoufox/server.py"
click node_display "https://github.com/daijro/camoufox/blob/main/pythonlib/camoufox/virtdisplay.py"
click node_mask_config "https://github.com/daijro/camoufox/blob/main/additions/camoucfg/MaskConfig.hpp"
click node_mouse "https://github.com/daijro/camoufox/blob/main/additions/camoucfg/MouseTrajectories.hpp"
click node_juggler_protocol "https://github.com/daijro/camoufox/blob/main/additions/juggler/protocol/Dispatcher.js"
click node_juggler_handlers "https://github.com/daijro/camoufox/blob/main/additions/juggler/protocol/BrowserHandler.js"
click node_content_agent "https://github.com/daijro/camoufox/blob/main/additions/juggler/content/PageAgent.js"
click node_pipe "https://github.com/daijro/camoufox/blob/main/additions/juggler/pipe/nsRemoteDebuggingPipe.cpp"
click node_screencast "https://github.com/daijro/camoufox/blob/main/additions/juggler/screencast/nsScreencastService.cpp"
click node_orchestrator "https://github.com/daijro/camoufox/blob/main/multibuild.py"
click node_patch_materializer "https://github.com/daijro/camoufox/blob/main/scripts/patch.py"
click node_packager "https://github.com/daijro/camoufox/blob/main/scripts/package.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sync_api,node_async_api,node_cli,node_identity,node_package_manager,node_remote_server,node_display toneBlue
class node_mask_config,node_mouse,node_juggler_protocol,node_juggler_handlers,node_content_agent,node_pipe,node_screencast toneAmber
class node_patches,node_orchestrator,node_patch_materializer,node_packager,node_fonts toneMint
class node_firefox_upstream,node_playwright toneNeutral
```

## Components

### Python launcher

Session setup and user-facing automation APIs.

- [Sync API](https://github.com/daijro/camoufox/blob/main/pythonlib/camoufox/sync_api.py): Python entry point · `pythonlib/camoufox/sync_api.py`
- [Async API](https://github.com/daijro/camoufox/blob/main/pythonlib/camoufox/async_api.py): Python entry point · `pythonlib/camoufox/async_api.py`
- [CLI](https://github.com/daijro/camoufox/blob/main/pythonlib/camoufox/__main__.py): Python entry point · `pythonlib/camoufox/__main__.py`
- [Identity assembly](https://github.com/daijro/camoufox/blob/main/pythonlib/camoufox/fingerprints.py): Python session config · Generates fingerprints and aligns locale, IP, and geolocation. · `pythonlib/camoufox/fingerprints.py`
- [Browser package manager](https://github.com/daijro/camoufox/blob/main/pythonlib/camoufox/pkgman.py): Python distribution client · `pythonlib/camoufox/pkgman.py`
- [Remote launch server](https://github.com/daijro/camoufox/blob/main/pythonlib/camoufox/server.py): Python and Node service · Serves Playwright-compatible remote clients. · `pythonlib/camoufox/server.py`
- [Headful display support](https://github.com/daijro/camoufox/blob/main/pythonlib/camoufox/virtdisplay.py): Python display runtime · `pythonlib/camoufox/virtdisplay.py`

### Patched Firefox runtime

Native identity controls and isolated Juggler automation.

- [Native mask configuration](https://github.com/daijro/camoufox/blob/main/additions/camoucfg/MaskConfig.hpp): C++ identity runtime · Applies identity properties inside Firefox implementation layers. · `additions/camoucfg/MaskConfig.hpp`
- [Mouse trajectories](https://github.com/daijro/camoufox/blob/main/additions/camoucfg/MouseTrajectories.hpp): C++ behavior runtime · `additions/camoucfg/MouseTrajectories.hpp`
- [Juggler protocol dispatch](https://github.com/daijro/camoufox/blob/main/additions/juggler/protocol/Dispatcher.js): Browser automation protocol · Routes external commands to browser and page handlers. · `additions/juggler/protocol/Dispatcher.js`
- [Browser and page handlers](https://github.com/daijro/camoufox/blob/main/additions/juggler/protocol/BrowserHandler.js): Juggler command handlers · `additions/juggler/protocol/BrowserHandler.js`
- [Content page agent](https://github.com/daijro/camoufox/blob/main/additions/juggler/content/PageAgent.js): Isolated content runtime · Executes page interactions outside the page-visible automation scope. · `additions/juggler/content/PageAgent.js`
- [Remote debugging pipe](https://github.com/daijro/camoufox/blob/main/additions/juggler/pipe/nsRemoteDebuggingPipe.cpp): C++ transport · `additions/juggler/pipe/nsRemoteDebuggingPipe.cpp`
- [Screencast service](https://github.com/daijro/camoufox/blob/main/additions/juggler/screencast/nsScreencastService.cpp): C++ browser service · `additions/juggler/screencast/nsScreencastService.cpp`

### Build and distribution

Fetches, patches, builds, and packages Firefox.

- **Firefox patch set**: Patch layer · Defines fingerprint, stealth, privacy, and automation changes.
- [Multi-platform build](https://github.com/daijro/camoufox/blob/main/multibuild.py): Build orchestrator · `multibuild.py`
- [Patch materializer](https://github.com/daijro/camoufox/blob/main/scripts/patch.py): Build stage · `scripts/patch.py`
- [Browser packager](https://github.com/daijro/camoufox/blob/main/scripts/package.py): Build stage · Stages portable browser artifacts and bundled assets. · `scripts/package.py`
- **Bundled fonts**: Visual identity assets

### Other components

- **Upstream Firefox**: External source · Fetched Mozilla source tree.
- **Playwright clients**: External automation API

## Connections

- 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
