How agnays/camoufox works
Project Type & Purpose
• Camoufox is an open-source, stealthy custom build of Firefox for web scraping and anti-bot evasion.
• It comprises two main “phases”:
a. Build time: fetch Firefox source, apply patches/additions, produce portable browser bundles.
b. Run time: expose the custom browser via a Python API (Playwright-style) or legacy CLI launcher, plus extensive tests and helper scripts.
A. External Dependencies
• Firefox Source (upstream)
• System Fonts (Windows, macOS, Linux)
• Default Add-ons (uBlock Origin, BPC)
B. Camoufox Repository
1. patches/ ← C++ & JS patches for fingerprint masking, debloat, stealth
2. additions/ ← Branding, Juggler (Playwright backend), browser components
3. assets/ ← Mozconfig files, search config, uBO assets
4. bundle/ ← Bundled fonts & font-config overrides
5. settings/ ← camoufox.cfg, defaults, distribution policies
6. legacy/ ← Deprecated Go-based launcher & loaders
7. pythonlib/ ← Camoufox Python package (sync & async API)
8. jsonvv/ ← JSON-based validator library
9. scripts/ ← Build helpers, packaging, developer UI, examples
10. tests/ ← Pytest suite, test assets, local test server
C. Build System
• Makefile & multibuild.py
• Dockerfile for containerized build
• CI workflow (GitHub Actions)
D. Distribution
• dist/ (outputs of make package-*)
• Portable bundles for Linux, Windows, macOS
E. Run-Time Interfaces
1. Python Interface
– camoufox.server.js ← spawns the browser
– camoufox.sync_api / async_api ← Playwright-style wrappers
– JSON config in memory
2. Legacy CLI Launcher
– launcher executable (Go binary)
– --config, --addons flags
3. Juggler / Playwright Protocol
– WebSocket or Pipe communication
– Dispatcher, Handlers (Page, Browser, Runtime)
F. Tests & Examples
• tests/ driven via pytest
• scripts/examples serve demo pages
• tests spin up testserver.py
Relationships & Data Flows
• Build Flow:
Firefox Source + patches/ + additions/ + bundle/ + assets/ → (Make/multibuild.py or Docker) → Portable browser bundles.
• Packaging Flow:
scripts/package.py & Make targets → dist/
• Runtime Flow:
Python API or CLI launcher → spawns Camoufox executable → applies settings from camoufox.cfg → Juggler bridges to Playwright client code → User scripts or tests drive pages.
• Test Flow:
tests/ → import Python API → launch browser → testassets served by tests/server.py → assertions.
Architectural Patterns
• Layered architecture:
• “External → Build → Package → Runtime → Client/Test”
• Modular separation:
• Patches, Additions, Assets are orthogonal concerns.
• Python wrapper decouples control logic from browser binary.
• CI/CD integration (GitHub Actions for build & test).