daijro/camoufox

⚠️ This project is under development. It may not be suitable for stable production use. ⚠️

View/Collapse All

Premium

	NodeMaven: The most efficient proxy provider for Web Scrapping and Automation with the Highest Quality IP on the market. Why NodeMaven? • 99.9% uptime • ZIP Targeting • IP filtering: all proxies have fraud score <97% • No KYC required • Unique free tools: Proxy Bandwidth Checker, Meta Tag Checker, IP Lookup and others! Special codes for Camoufox users: • CAMOUFOX35 - 35% off to Mobile and Residential Proxies • CAMOUFOX40 - 40% off to ISP (Static) Proxies
	Need proxies for Camoufox? Use Node Proxy — a provider of datacenter, residential and mobile proxies offering high speed, security and near-100% uptime. Fully tested and supported in Camoufox. What sets them apart from other providers • 90+ IP score • HTTP + SOCKS5 — multiprotocol support • Discounts for retail customers • Full B2B support • Ethically sourced IP addresses • Special terms for Enterprise clients Want to support Camoufox? Just use my promo code CAMOUFOX — it gets you a 30% discount and supports the developer at the same time. Get started at node-proxy.com →
	Byteful is a UK-based web data infrastructure platform that provides ethically sourced residential, mobile, static residential (ISP) and datacenter proxies alongside API-first tools for web scraping, data collection, and AI-driven automation. Processing tens of billions of requests per month for thousands of customers, Byteful powers browser-based AI agents, automation systems, and data workflows. It is a member of the Internet Watch Foundation and the Ethical Web Data Collection Initiative. Get 10% off Byteful Residential Bandwidth with the code: CAMOUFOX10
	Layer3 Intel | See your proxies the way anti-bots see them Camoufox hides your browser. Your proxy IP is the part it can't hide. Layer3 Intel is the residential proxy detection engine used to catch proxy traffic — check whether the IPs your provider sells you are clean, or already known and flagged. • 🔍 Live threat score for any IP • 🗂️ Proxy pool membership - identify IP resellers • 📡 70M+ residential, mobile & ISP proxy IPs tracked across 200+ providers • ⚡ <40ms API responses — vet IPs inline before your scraper uses them Check your IPs: https://layer3intel.com

Tools & Services

	Scrapfly is an enterprise-grade solution providing Web Scraping API that aims to simplify the scraping process by managing everything: real browser rendering, rotating proxies, and fingerprints (TLS, HTTP, browser) to bypass all major anti-bots. Scrapfly also unlocks the observability by providing an analytical dashboard and measuring the success rate/block rate in detail.
	Clover Labs is a Toronto based venture studio building AI agents for growth and distribution.
	SerpApi, a web search API to scrape Google and other search engines with a simple API.
	Web data that survives the anti-bots. Crawlbase gives developers and AI teams reliable data at scale: a 99% success-rate Crawler, Crawling API, Smart AI Proxies, and Web MCP Server that get through, so your scrapers and agents don't break. You build, we handle the infrastructure. Get 15% off your first 3 months with code CAMOUFOX → crawlbase.com
	Scrappey is a Web Scraping API that only charges successful scrapes with pay as you go - no subscriptions. Scrape complex sites. Residential proxies included, no hidden proxy fees, or expiring balances. One API for direct HTTP, full-browser rendering, JavaScript-heavy pages, screenshots, sessions, 30+ browser actions and 200+ concurrent sessions at a time - trusted by 1000+ developers and AI agents. Get 10% off with code CAMOUFOX.
	Cloro is a SERP and AI search API. Get structured results from Google, ChatGPT, Perplexity, Gemini, Copilot and Grok.

Proxy Providers

Camoufox is intended to be used with rotating proxies (preferably residential IPs). Check out these providers:

	🚀 Camoufox × ProxyEmpire Running Camoufox? Your proxy layer decides whether you scale — or get blocked. ProxyEmpire delivers: • 🌍 30M+ Residential IPs (170+ countries) • 📱 4G/5G Mobile Proxies • 🔄 Rotating & Sticky Sessions • ⚡ Unlimited Concurrent Sessions • 🎯 Precise geo-targeting • HTTP, HTTPS & SOCKS5 Support Built for scraping, automation, and high-stealth workflows. 🔥 Exclusive Offer - Use code Camoufox30 Get 30% recurring discount (not just first month). Upgrade your proxies. Reduce bans. Scale properly
	RapidProxy - Power Your Data with Premium Proxies. 🎁 Try proxies for free + Use code RAPID10 for 10% OFF Why Choose RapidProxy? • 🌍 90M+ IPs in 200+ countries & regions • ♾️ No expiration on traffic — use anytime, no pressure • 🔥 Unlimited concurrency for maximum performance • 💰 Starting from just $0.65/GB — built for scale • 📍 City-level targeting for precise geo access • 🔄 Flexible session control tailored to your needs Don’t miss out — start your free trial today and experience fast, stable, and scalable proxy performance with RapidProxy.
	Swiftproxy - High-Performance Residential Proxies for Scalable Data Collection Built for developers who need reliable, anti-detection proxy infrastructure. Swiftproxy delivers stable connections, high success rates, and flexible control for large-scale scraping and automation. • 🌍 195+ locations with ethically sourced residential IPs • 🔄 Rotating & sticky sessions with precise geo-targeting • ⚡ Optimized for anti-ban & high success rate • 🔌 HTTP / HTTPS / SOCKS5 support • 🧪 Free 500MB trial for testing • 💸 Special discount code for Camoufox users: PROXY90 - 10% Best for: Web scraping, automation, multi-accounting, and large-scale data extraction
	MangoProxy is a Residential, ISP, Mobile and Datacenter proxy service designed for professional tasks where stability, speed, and anonymity matter. Use code DAIJRO for 8% OFF ISP Static Proxies
	Proxidize | Mobile and Residential Proxies for Camoufox Running Camoufox at scale? Your browser setup is only half the stack. Your proxy layer matters too. Proxidize provides mobile and residential proxies built for scraping, browser automation, SEO monitoring, AI agents, and data collection workflows. Why Proxidize? • Real 4G and 5G mobile proxies • Residential proxies in 195+ countries • Rotating and sticky sessions • City-level and carrier targeting • Unlimited concurrency • HTTP(S), SOCKS5, and UDP over SOCKS support • No hardware or DIY setup required Built for teams that need reliable proxy infrastructure without managing devices, servers, or proxy rotation themselves. Special offer for Camoufox users: Use code CAMOUFOX20 for 20% off. Start now: https://proxidize.com
	🔍 Camoufox × Thordata Real Residential IPs for Smarter AI Agents & Automation With 100M+ residential IPs, Thordata helps your scraper access the web through real user IPs across 195+ countries. Target specific locations with precision — including city, ISP, and ASN-level targeting — so your Camoufox automation runs with a more authentic network identity. • 🔄 Rotating & Sticky Sessions (up to 90 minutes) • ⚡ 99.99% uptime with unlimited concurrent sessions • 🌍 Global residential coverage for AI agents, scraping, and automation workflows 🎁 Exclusive for Camoufox users: Get free trial traffic after signup + use code Camoufox for 10% OFF. Start your free trial with Thordata
	Webshare gives you instant access to a proxy pool of 80M+ ethically-sourced IPs across 195+ countries, with rotating residential, static ISP, and datacenter options plus a full API. It includes a 100+ Gbps backbone, country/city/state/ZIP/ASN-level targeting, and requires no credit card to start. 🏷️ Get 20% OFF your first purchase with promo code CAMOUFOX20
	Roam — Residential & static residential proxies, pay-as-you-go per GB. Use code CAMOUFOX15 for 15% extra credit on your first top-up.

Camoufox is a Firefox build for web scraping and AI agents. Every launch gets a fresh, internally consistent device identity drawn from the real-world distribution of devices, and the browser reports it from C++, so a page sees native values rather than JavaScript overrides. Playwright drives it, through an automation layer the page cannot see.

pip install -U "camoufox[geoip]"
camoufox fetch

from camoufox.sync_api import Camoufox

with Camoufox(headless=True) as browser:
    page = browser.new_page()
    page.goto("https://example.com")

import asyncio
from camoufox.async_api import AsyncCamoufox

async def main():
    async with AsyncCamoufox(headless=True) as browser:
        page = await browser.new_page()
        await page.goto("https://example.com")

asyncio.run(main())

// npm install camoufox playwright-core && npx camoufox fetch
import { Camoufox } from "camoufox";

const browser = await Camoufox({ headless: true });
const page = await browser.newPage();
await page.goto("https://example.com");
await browser.close();

What you get back is a normal Playwright Browser. Behind a proxy, add proxy=... and geoip=True so timezone, locale, geolocation and the WebRTC IP match the exit IP. For many identities in one browser, use NewContext().

flowchart TB
    YOU(["Your Playwright code"])

    subgraph L["Launcher: python/ or typescript/"]
        FP["fpgen<br/>draws a real device"] --> CO["coherence.py<br/>rejects impossible combinations"]
        CO --> ID[["Identity"]]
        GEO["geoip<br/>timezone, locale, WebRTC IP"] --> ID
    end

    subgraph B["Patched Firefox: browser/"]
        MC["MaskConfig<br/>reads CAMOU_CONFIG"] --> API["Web APIs answered in C++<br/>navigator, screen, WebGL,<br/>fonts, audio, WebRTC"]
        SET["Per-context setters<br/>sealed before page script"] --> API
        JG["Juggler<br/>isolated world"]
    end

    PAGE(["The web page"])

    YOU -- "1 launch options" --> L
    ID == "2 CAMOU_CONFIG + prefs" ==> MC
    ID -- "3 NewContext()" --> SET
    YOU <-- "4 Juggler protocol" --> JG
    API -- "native values" --> PAGE
    JG -. "trusted input, DOM reads;<br/>no code in the page" .-> PAGE

    classDef you fill:#eef2f6,stroke:#57606a,color:#1f2328
    classDef launcher fill:#ddf4ff,stroke:#0969da,color:#0a3069
    classDef browser fill:#fff1e5,stroke:#bc4c00,color:#4a1c00
    classDef page fill:#dafbe1,stroke:#1a7f37,color:#0f3d1c
    class YOU you
    class FP,CO,ID,GEO launcher
    class MC,API,SET,JG browser
    class PAGE page
    style L fill:none,stroke:#0969da,stroke-dasharray:4 3,color:#0969da
    style B fill:none,stroke:#bc4c00,stroke-dasharray:4 3,color:#bc4c00

1. The launcher draws a device from fpgen (a model of real traffic), then adds fonts, voices, a GPU and media devices seeded by that identity. coherence.py rejects combinations no real machine produces.
2. The identity goes to the browser as the CAMOU_CONFIG environment variable (keys declared in browser/settings/properties.json). The patches read it through MaskConfig and answer from C++.
3. NewContext() gives one context its own identity through setters that the per-context patches add to window. They are sealed before page script runs.
4. Playwright talks to Juggler. Camoufox's Juggler runs its page agent in an isolated world, so the page never sees automation code.

Each row says where it is implemented. A patch is a file in browser/patches/; Juggler is browser/additions/juggler/; the launcher is the Python and TypeScript packages.

The goal is a browser that behaves exactly like stock Firefox, except that it reports a different machine. A value is spoofed when it identifies the host machine or the network. Anything else stays as Firefox has it, because something stock Firefox never does, such as noise, is a fingerprint in its own right.

Left as stock Firefox has it, on purpose:

Each context of one browser can carry its own identity: docs/per-context-patches.md.

Canvas and WebGL pixels come from the real OS, driver and GPU, whatever the identity claims. The launcher chooses the canvas behaviour from two facts: does the identity claim the host's OS, and does the host render on a GPU?

That is the default. These options override it:

Noise is set per browser, not per context. Without it, every NewContext() claims the host's OS. Details are in the canvas on another OS.

The full option list is in the Python README.

Playwright drives Chromium over CDP but Firefox over Juggler, a protocol that is a separate module inside Firefox. That makes it possible to give Juggler its own copy of the page: Playwright reads and edits that copy, and the real page never sees a getter fire or a listener appear. Input goes through Firefox's own input handlers, so it is handled as a user's would be.

Camoufox can still be detected. Thousands of values must agree with each other, and anti-bot vendors look for the one that does not. File a detection report when you find one.

Each dot is a mousemove event the page received from six page.mouse.move() calls with humanize=True, shown at the speed it arrived; close dots mean the hand slowed down. browser/scripts/cursor-demo.py regenerates the figure.

Camoufox does not compute its cursor paths. It picks one of Cursory's 2356 recorded human movements that suits the move, morphs it onto the start and end points, and replays it with the recording's own timing, including pauses and overshoots. It ships cursory-js, a TypeScript port that reproduces the Python original exactly, at browser/additions/juggler/input/cursory/. Cursory is LGPLv3-or-later, not MPL-2.0 like the rest of the browser; see NOTICE.

This repository is not the Firefox source. It fetches Firefox, copies in browser/additions/, applies browser/patches/ and builds. The build runs on Linux; the Windows and macOS binaries are cross-compiled. WSL does not work.

flowchart TB
    subgraph IN["From this repository"]
        direction LR
        UP["upstream.sh<br/>Firefox version"]
        ADD["additions/ + settings/<br/>files copied in"]
        PAT["patches/<br/>diffs applied"]
    end

    S1["<b>1. make dir</b><br/>download Firefox, copy additions,<br/>apply every patch"]
    S2["<b>2. make bootstrap</b><br/>toolchains, once per machine"]
    S3["<b>3. make build</b><br/>./mach build"]
    S4["<b>4. make package-linux</b><br/>or package-macos, package-windows"]
    FONTS["font bundle + fontconfig"]
    OUT[("Release archive")]

    IN --> S1 --> S2 --> S3 --> S4 --> OUT
    FONTS --> S4

    classDef input fill:#ddf4ff,stroke:#0969da,color:#0a3069
    classDef step fill:#fff1e5,stroke:#bc4c00,color:#4a1c00
    classDef out fill:#dafbe1,stroke:#1a7f37,color:#0f3d1c
    class UP,ADD,PAT,FONTS input
    class S1,S2,S3,S4 step
    class OUT out
    style IN fill:none,stroke:#0969da,stroke-dasharray:4 3,color:#0969da

git clone --depth 1 https://github.com/daijro/camoufox
cd camoufox/browser
make dir                        # fetch Firefox, copy additions, apply every patch
make bootstrap                  # one time: host packages and mach bootstrap
make build                      # ./mach build
make run                        # run the build
make package-linux arch=x86_64  # or package-macos / package-windows

make help lists every target. Install ccache: a cold build takes about 40 minutes and an incremental one about 5.

To build and package several targets in one go:

python3 multibuild.py --target linux windows macos --arch x86_64 arm64

Artifacts are written to browser/dist/.

cd browser
docker build -t camoufox-builder .
docker run -v "$(pwd)/dist:/app/dist" camoufox-builder --target linux --arch x86_64

The container takes the multibuild.py flags. Add -v "$HOME/.mozbuild":/root/.mozbuild:rw,z to reuse the host's toolchains.

A way to find what a site detects without deobfuscating its JavaScript: start from stock Firefox and add Camoufox's changes back until the site flags.

flowchart TD
    START(["A site flags Camoufox"]) --> Q1{"Does it flag<br/>stock Firefox?"}
    Q1 -- yes --> NB["Not the browser:<br/>a bad IP or rate limiting"]
    Q1 -- no --> BASE["Build the debug baseline<br/>make ff-dbg (1), make build (2)"]
    BASE --> Q2{"Does it flag the<br/>baseline headless (4)?"}

    Q2 -- yes --> Q3{"Headed (3)<br/>as well?"}
    Q3 -- yes --> NB
    Q3 -- no --> Q4{"Still flagged with<br/>privacy.resistFingerprinting (6)?"}
    Q4 -- no --> FPP["Enable FPP and drop overrides<br/>until the leak returns"]
    Q4 -- yes --> DEOB["Deobfuscate the site's script<br/>to see what it tests"]

    Q2 -- no --> CFG["Apply config.patch (5)<br/>and rebuild (2)"]
    CFG --> Q5{"Still passes (3)?"}
    Q5 -- no --> PREFS["Remove prefs from camoufox.cfg (6)<br/>until it passes"]
    Q5 -- yes --> PW["Apply playwright/0-playwright.patch (5)<br/>and rebuild (2)"]
    PW --> Q6{"Still passes (3)?"}
    Q6 -- no --> JUG["Debug Juggler"]
    Q6 -- yes --> REST["Apply the other patches one at a time<br/>until it flags"]
    JUG -. "if Juggler looks clean" .-> DEOB

    classDef start fill:#eef2f6,stroke:#57606a,color:#1f2328
    classDef ask fill:#ddf4ff,stroke:#0969da,color:#0a3069
    classDef step fill:#fff1e5,stroke:#bc4c00,color:#4a1c00
    classDef found fill:#dafbe1,stroke:#1a7f37,color:#0f3d1c
    class START start
    class Q1,Q2,Q3,Q4,Q5,Q6 ask
    class BASE,CFG,PW step
    class NB,FPP,DEOB,PREFS,JUG,REST found