daijro/camoufox🦊 متصفح مضاد للكشف
<img src="https://camoufox.com/static/banner.svg" align="center">
<h1 align="center">Camoufox</h1>
<h4 align="center">Camoufox is an open source anti-detect browser built for webscraping & AI agents. 🦊</h4>
<div align="center">
<a href="https://trendshift.io/repositories/12224" target="_blank">
<img src="https://trendshift.io/api/badge/repositories/12224" alt="daijro%2Fcamoufox | Trendshift" width="250" height="55"/>
</a><br>
<a href="https://pepy.tech/projects/camoufox"><img src="https://static.pepy.tech/personalized-badge/camoufox?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads" alt="Total Downloads"</a>
<a href="https://pepy.tech/projects/camoufox"><img src="https://static.pepy.tech/personalized-badge/camoufox?period=monthly&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads/month" alt="Monthly Downloads"></a>
<a href="https://pepy.tech/projects/camoufox"><img src="https://static.pepy.tech/personalized-badge/camoufox?period=weekly&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads/week" alt="Weekly Downloads"></a>
<h4>⚠️ This project is under development. It may not be suitable for stable production use. ⚠️</h4>
</div>
---
> [!NOTE]
> **All of the latest documentation is available at [camoufox.com](https://camoufox.com).**
---
# Sponsors
<details open id="sponsors">
<summary>View/Collapse All</summary>
## Premium
<table>
<tr>
<td width="25%" align="center" valign="middle">
<a href="https://go.nodemaven.com/camoufoxreadmeoctober" target="_blank">
<img width="380" alt="nodemaven" src="https://assets.kitploit.com/production/public/readmes/41473/c9dc98de9fbc66bb561311a90b3ed553271e79b7e5d08a94a0ee71e1afe90da5/fc71d82e04f5dc303d21f905310e811885d8a6a57ddffe892b4164bf12547371-display-v1.webp"/>
</a>
</td>
<td valign="middle">
<a href="https://go.nodemaven.com/camoufoxreadmeoctober">NodeMaven</a>: The most efficient proxy provider for Web Scrapping and Automation with the Highest Quality IP on the market.<br>
<strong>Why <a href="https://go.nodemaven.com/camoufoxreadmeoctober">NodeMaven</a>?</strong><br>
• 99.9% uptime<br>
• ZIP Targeting<br>
• IP filtering: all proxies have fraud score <97%<br>
• No KYC required<br>
• Unique free tools: Proxy Bandwidth Checker, Meta Tag Checker, IP Lookup and others!<br>
<strong>Special codes for Camoufox users:</strong><br>
• <code>CAMOUFOX35</code> - 35% off to Mobile and Residential Proxies<br>
• <code>CAMOUFOX40</code> - 40% off to ISP (Static) Proxies<br>
</td>
</tr>
<tr>
<td width="25%" align="center" valign="middle">
<a href="https://node-proxy.com/?c=6P8Z23" target="_blank">
<img width="380" alt="nodeproxy" src="https://assets.kitploit.com/production/public/readmes/41473/a30db54d1548db2a4ef2f51ef3cede90846976c1d5a70feb93ee9c663540b8e0/0282f11bcf3bb4b7bf120d3c25ae9fead9d14dea492a705b9063b5d3a38c62a9-display-v1.webp" />
</a>
</td>
<td valign="middle">
<strong>Need proxies for Camoufox?</strong><br>
Use <strong><a href="https://node-proxy.com/?c=6P8Z23">Node Proxy</a></strong> — a provider of <strong>datacenter, residential and mobile proxies</strong> offering high speed, security and near-100% uptime. <strong>Fully tested and supported in Camoufox.</strong><br>
<strong>What sets them apart from other providers</strong><br>
• 90+ IP score<br>
• HTTP + SOCKS5 — multiprotocol support<br>
• Discounts for retail customers<br>
• Full B2B support<br>
• Ethically sourced IP addresses<br>
• Special terms for Enterprise clients<br>
<strong>Want to support Camoufox?</strong><br>
Just use my promo code <strong><code>CAMOUFOX</code></strong> — it gets you a <strong>30% discount</strong> and supports the developer at the same time.<br>
<strong><a href="https://node-proxy.com/?c=6P8Z23">Get started at node-proxy.com →</a></strong>
</td>
</tr>
<tr>
<td width="25%" align="center" valign="middle">
<a href="https://byteful.com/?utm_source=github&utm_medium=github-sponsor&utm_campaign=camoufox_github_website_sponsor" target="_blank">
<img width="380" alt="byteful" src="https://assets.kitploit.com/production/public/readmes/41473/f02858f68a8c9a504f80ae17ed3fbfa425d2b6da2d3ec12d040d6ad5019c8436/ba17b85cdb4ff8848b6eb701c0e57bc760e29ee901fd7f572c15c77556d65b8e-display-v1.webp"/>
</a>
</td>
<td valign="middle">
<a href="https://byteful.com/?utm_source=github&utm_medium=github-sponsor&utm_campaign=camoufox_github_website_sponsor">Byteful</a> 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
</td>
</tr>
<tr>
<td width="25%" align="center" valign="middle">
<a href="https://layer3intel.com/?utm_source=github&utm_medium=sponsoring&utm_campaign=camoufox" target="_blank">
<img width="380" alt="layer3" src="https://assets.kitploit.com/production/public/readmes/41473/8fdd0874164aa28ee5406de3aadfc8df8dc67bbb230fc8d144647e33bf618741/17bdad743dfc9b5bb6ce8980380cedfe53b49a8391b3db9c5efdcb48b2ec7f87-display-v1.webp"/>
</a>
</td>
<td valign="middle">
<strong><a href="https://layer3intel.com/?utm_source=github&utm_medium=sponsoring&utm_campaign=camoufox">Layer3 Intel</a> | See your proxies the way anti-bots see them</strong><br>
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.<br>
• 🔍 Live threat score for any IP<br>
• 🗂️ Proxy pool membership - identify IP resellers<br>
• 📡 70M+ residential, mobile & ISP proxy IPs tracked across 200+ providers<br>
• ⚡ <40ms API responses — vet IPs inline before your scraper uses them<br>
Check your IPs: <a href="https://layer3intel.com/?utm_source=github&utm_medium=sponsoring&utm_campaign=camoufox">https://layer3intel.com</a>
</td>
</tr>
</table>
## Tools & Services
<table>
<tr>
<td width="25%" align="center" valign="middle">
<a href="https://scrapfly.io/?utm_source=github&utm_medium=sponsoring&utm_campaign=camoufox" target="_blank">
Scrapfly.io
</a>
</td>
<td valign="middle">
<a href="https://scrapfly.io/?utm_source=github&utm_medium=sponsoring&utm_campaign=camoufox">Scrapfly</a> 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.
</td>
</tr>
<tr>
<td width="25%" align="center" valign="middle">
<a href="https://cloverlabs.ai/?utm_source=github&utm_medium=sponsoring&utm_campaign=camoufox" target="_blank">
<img src="https://assets.kitploit.com/production/public/readmes/41473/07965d63c1bc08c25f1f074c192d0a2b49313c3a8d054816db1bbbc4e861a6e8.jpg" alt="cloverlabs.ai" width="300">
</a>
</td>
<td valign="middle">
<a href="https://cloverlabs.ai/?utm_source=github&utm_medium=sponsoring&utm_campaign=camoufox">Clover Labs</a> is a Toronto based venture studio building AI agents for growth and distribution.
</td>
</tr>
<tr>
<td width="25%" align="center" valign="middle" height="100">
<a href="https://serpapi.com/use-cases/web-search-api?utm_source=camoufox" target="_blank">
<img width="350" alt="color horizontal" src="https://assets.kitploit.com/production/public/readmes/41473/a8af8b266340afc54d5300cf53ce73c5fb337bb47d659bc365a568b5ea9152ff.png"/>
</a>
</td>
<td valign="middle">
<a href="https://serpapi.com/use-cases/web-search-api?utm_source=camoufox">SerpApi, a web search API</a> to scrape Google and other search engines with a simple API.
</td>
</tr>
<tr>
<td width="25%" align="center" valign="middle" height="100">
<a href="https://crawlbase.com/?utm_source=github&utm_medium=sponsorship&utm_campaign=camoufox" target="_blank">
<img width="350" alt="color horizontal" src="https://assets.kitploit.com/production/public/readmes/41473/020e7132e9b09a934bf14724693e4dc08c2ff874036a9834ae24375d350f6116.png"/>
</a>
</td>
<td valign="middle">
<strong>Web data that survives the anti-bots.</strong><br>
<a href="https://crawlbase.com/?utm_source=github&utm_medium=sponsorship&utm_campaign=camoufox">Crawlbase</a> 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.
<strong>Get 15% off your first 3 months with code CAMOUFOX</strong> → <a href="https://crawlbase.com/?utm_source=github&utm_medium=sponsorship&utm_campaign=camoufox">crawlbase.com</a>
</td>
</tr>
<tr>
<td width="25%" align="center" valign="middle">
<a href="https://scrappey.com/?utm_source=camoufox&utm_medium=sponsorship&utm_campaign=camoufox_sponsorship" target="_blank">
<img width="380" alt="scrappey" src="https://assets.kitploit.com/production/public/readmes/41473/8c99b2aa71f5ecc64080cfeb3148c82ab2bb8e48cb39fbedaf17f88bc9f81d28.png"/>
</a>
</td>
<td valign="middle">
<a href="https://scrappey.com/?utm_source=camoufox&utm_medium=sponsorship&utm_campaign=camoufox_sponsorship">Scrappey</a> 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.
</td>
</tr>
<tr>
<td width="25%" align="center" valign="middle">
<a href="https://cloro.dev/?utm_source=referral&utm_medium=camoufox" target="_blank">
<img width="380" alt="Cloro" src="https://assets.kitploit.com/production/public/readmes/41473/ab67c349e7cca2a9c46709e1ed9ce76b9904f7107ac6905ed10b4f31cdb6a9d6/1605ee481c88f5708078b8d20b21e85a11abfafef49762e43a264be849432bfc-display-v1.webp" />
</a>
</td>
<td valign="middle">
<a href="https://cloro.dev/?utm_source=referral&utm_medium=camoufox">Cloro</a> is a SERP and AI search API. Get structured results from Google, ChatGPT, Perplexity, Gemini, Copilot and Grok.
</td>
</tr>
</table>
## Proxy Providers
Camoufox is intended to be used with rotating proxies (preferably residential IPs). Check out these providers:
<table>
<tr>
<td width="25%" align="center" valign="middle">
<a href="https://proxyempire.io/?ref=camoufox&utm_source=github&utm_medium=paid_referral&utm_campaign=open_source_sponsorship&utm_content=camoufox" target="_blank">
<img width="380" alt="proxyempire" src="https://assets.kitploit.com/production/public/readmes/41473/92b2725ccb0fcf098cecc9fcc0e7042971b4f772051861f723569460460d3664.png"/>
</a>
</td>
<td valign="middle">
<b>🚀 Camoufox × ProxyEmpire</b><br>
Running Camoufox? Your proxy layer decides whether you scale — or get blocked.<br>
<a href="https://proxyempire.io/?ref=camoufox&utm_source=github&utm_medium=paid_referral&utm_campaign=open_source_sponsorship&utm_content=camoufox">ProxyEmpire</a> delivers:<br>
• 🌍 30M+ Residential IPs (170+ countries)<br>
• 📱 4G/5G Mobile Proxies<br>
• 🔄 Rotating & Sticky Sessions<br>
• ⚡ Unlimited Concurrent Sessions<br>
• 🎯 Precise geo-targeting<br>
• HTTP, HTTPS & SOCKS5 Support<br>
Built for scraping, automation, and high-stealth workflows.<br>
<b>🔥 Exclusive Offer</b> - Use code <b>Camoufox30</b><br>
Get <b>30% recurring discount</b> (not just first month). Upgrade your proxies. Reduce bans. Scale properly
</td>
</tr>
<tr>
<td width="25%" align="center" valign="middle">
<a href="https://www.rapidproxy.io/?ref=daijro" target="_blank">
<img width="380" alt="rapidproxy" src="https://assets.kitploit.com/production/public/readmes/41473/1f26966f5a352e9647f168957db44215336f362493ee6f3a93c63078998bcbe9.png"/>
</a>
</td>
<td valign="middle">
<a href="https://www.rapidproxy.io/?ref=daijro">RapidProxy</a> - Power Your Data with Premium Proxies.<br>
🎁 Try proxies for free + Use code <strong>RAPID10</strong> for <strong>10% OFF</strong>
<br>
<strong>Why Choose RapidProxy?</strong><br>
• 🌍 90M+ IPs in 200+ countries & regions<br>
• ♾️ No expiration on traffic — use anytime, no pressure<br>
• 🔥 Unlimited concurrency for maximum performance<br>
• 💰 Starting from just $0.65/GB — built for scale<br>
• 📍 City-level targeting for precise geo access<br>
• 🔄 Flexible session control tailored to your needs<br>
Don’t miss out — start your free trial today and experience fast, stable, and scalable proxy performance with <a href="https://www.rapidproxy.io/?ref=daijro">RapidProxy</a>.
</td>
</tr>
<tr>
<td width="25%" align="center" valign="middle">
<a href="https://www.swiftproxy.net/?ref=daijro" target="_blank">
<img width="380" alt="swiftproxy" src="https://assets.kitploit.com/production/public/readmes/41473/1a18b940d4fea66bac01493e4d72e93fcbb1687aec1048bb122e5c87c4600a48.png"/>
</a>
</td>
<td valign="middle">
<a href="https://www.swiftproxy.net/?ref=daijro">Swiftproxy</a> - <strong>High-Performance Residential Proxies for Scalable Data Collection</strong><br>
Built for developers who need <strong>reliable</strong>, anti-detection proxy infrastructure. Swiftproxy delivers stable connections, high success rates, and flexible control for large-scale scraping and automation.<br>
• 🌍 195+ locations with ethically sourced residential IPs<br>
• 🔄 <strong>Rotating</strong> & <strong>sticky</strong> sessions with precise geo-targeting<br>
• ⚡ Optimized for <strong>anti-ban</strong> & <strong>high success rate</strong><br>
• 🔌 HTTP / HTTPS / SOCKS5 support<br>
• 🧪 <strong>Free 500MB trial</strong> for testing<br>
• 💸 <strong>Special discount</strong> code for Camoufox users: <strong>PROXY90 - 10%</strong><br>
Best for: Web scraping, automation, multi-accounting, and large-scale data extraction
</td>
</tr>
<tr>
<td width="25%" align="center" valign="middle">
<a href="https://mangoproxy.com/?utm_source=github&utm_medium=partner&utm_campaign=daijro" target="_blank">
<img width="380" alt="mangoproxy" src="https://assets.kitploit.com/production/public/readmes/41473/898057e8214bb43af4d5bc4a73135c7d73594eabe3e1d8f5b98faccdc2f6411b.png"/>
</a>
</td>
<td valign="middle">
<a href="https://mangoproxy.com/?utm_source=github&utm_medium=partner&utm_campaign=daijro">MangoProxy</a> is a Residential, ISP, Mobile and Datacenter proxy service designed for professional tasks where stability, speed, and anonymity matter.<br>
Use code DAIJRO for 8% OFF ISP Static Proxies
</td>
</tr>
<tr>
<td width="25%" align="center" valign="middle">
<a href="https://proxidize.com/?utm_source=github&utm_medium=sponsorship&utm_campaign=camoufox&utm_content=daijro" target="_blank">
<img width="380" alt="proxidize" src="https://assets.kitploit.com/production/public/readmes/41473/15806cd5e1cc1c4b797d11014036e8d99b457563cc7cce6b75cd87f66c0812c0.webp"/>
</a>
</td>
<td valign="middle">
<strong><a href="https://proxidize.com/?utm_source=github&utm_medium=sponsorship&utm_campaign=camoufox&utm_content=daijro">Proxidize</a> | Mobile and Residential Proxies for Camoufox</strong><br>
Running Camoufox at scale? Your browser setup is only half the stack. Your proxy layer matters too.<br>
Proxidize provides mobile and residential proxies built for scraping, browser automation, SEO monitoring, AI agents, and data collection workflows.<br>
<strong>Why Proxidize?</strong><br>
• Real 4G and 5G mobile proxies<br>
• Residential proxies in 195+ countries<br>
• Rotating and sticky sessions<br>
• City-level and carrier targeting<br>
• Unlimited concurrency<br>
• HTTP(S), SOCKS5, and UDP over SOCKS support<br>
• No hardware or DIY setup required<br>
Built for teams that need reliable proxy infrastructure without managing devices, servers, or proxy rotation themselves.<br>
<strong>Special offer for Camoufox users</strong>: Use code <strong>CAMOUFOX20</strong> for <strong>20% off</strong>.<br>
Start now: <a href="https://proxidize.com/?utm_source=github&utm_medium=sponsorship&utm_campaign=camoufox&utm_content=daijro">https://proxidize.com</a>
</td>
</tr>
<tr>
<td width="25%" align="center" valign="middle">
<a href="https://www.thordata.com/?ls=dcx&lk=dcx" target="_blank">
<img width="380" alt="Thordata" src="https://assets.kitploit.com/production/public/readmes/41473/291187faafac0c50ac12c7222e8959aa4cb5d4a6881fb484613e77d2971e792c/c779fb3768d4f0af595988d891fb7b9bce6eef1bbfdb095545f9d99dc4016742-display-v1.webp"/>
</a>
</td>
<td valign="middle">
<b>🔍 Camoufox × Thordata</b><br>
<b>Real Residential IPs for Smarter AI Agents & Automation</b><br>
With <strong>100M+ residential IPs</strong>, Thordata helps your scraper access the web through real user IPs across <strong>195+ countries</strong>.<br>
Target specific locations with precision — including <strong>city, ISP, and ASN-level targeting</strong> — so your Camoufox automation runs with a more authentic network identity.<br>
• 🔄 <strong>Rotating & Sticky Sessions</strong> (up to 90 minutes)<br>
• ⚡ <strong>99.99% uptime</strong> with unlimited concurrent sessions<br>
• 🌍 <strong>Global residential coverage</strong> for AI agents, scraping, and automation workflows<br>
🎁 <strong>Exclusive for Camoufox users:</strong><br>
Get free trial traffic after signup + use code <strong>Camoufox</strong> for <strong>10% OFF</strong>.<br>
<a href="https://www.thordata.com/?ls=dcx&lk=dcx" target="_blank">Start your free trial with Thordata</a>
</tr>
<tr>
<td width="25%" align="center" valign="middle">
<a href="https://www.webshare.io/" target="_blank">
<img width="380" alt="Webshare" src="https://assets.kitploit.com/production/public/readmes/41473/9fd3f6daa65388ab632e38371744c05c6abde7593ac7d547ea8cd4323deefe5c/14bfb9687dccb317caf06cd5094f8689881ca20b1f7904f8f9f9672bcec68766-display-v1.webp"/>
</a>
</td>
<td valign="middle">
<strong><a href="https://www.webshare.io/">Webshare</a></strong> 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.<br>
🏷️ Get <strong>20% OFF your first purchase</strong> with promo code <strong><code>CAMOUFOX20</code></strong>
</tr>
<tr>
<td width="25%" align="center" valign="middle">
<a href="https://roamproxy.com" target="_blank">
<img width="380" alt="Roamproxy" src="https://assets.kitploit.com/production/public/readmes/41473/2895240a36b28a070ab255144347f95ec9a109aac84859d969636bb4a188c445/69be8cb7166b34ff3fc20f5c14bb1beaafe3ed1da29224e3ae61d9aab2bf684a-display-v1.webp"/>
</a>
</td>
<td valign="middle">
<strong><a href="https://roamproxy.com">Roam</a></strong> — Residential & static residential proxies, pay-as-you-go per GB. Use code CAMOUFOX15 for 15% extra credit on your first top-up.
</tr>
</table>
</details>
---
# Introduction
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.
| Package | Install | Docs |
|---|---|---|
| Python | `pip install -U "camoufox[geoip]"` | [`python/README.md`](https://github.com/daijro/camoufox/blob/main/python/README.md) |
| TypeScript / Node.js | `npm install camoufox playwright-core` | [`typescript/README.md`](https://github.com/daijro/camoufox/blob/main/typescript/README.md) |
| AI coding agents | | [`AGENTS.md`](https://github.com/daijro/camoufox/blob/main/AGENTS.md#using-camoufox) |
## Quick start
```bash
pip install -U "camoufox[geoip]"
camoufox fetch
```
```python
from camoufox.sync_api import Camoufox
with Camoufox(headless=True) as browser:
page = browser.new_page()
page.goto("https://example.com")
```
```python
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())
```
```javascript
// 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()`.
## How it fits together
```mermaid
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](https://github.com/scrapfly/fingerprint-generator)
(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`](https://github.com/daijro/camoufox/blob/main/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.
# Features
Each row says where it is implemented. A **patch** is a file in
[`browser/patches/`](https://github.com/daijro/camoufox/blob/main/browser/patches); **Juggler** is
[`browser/additions/juggler/`](https://github.com/daijro/camoufox/blob/main/browser/additions/juggler); the **launcher** is
the Python and TypeScript packages.
### Fingerprint spoofing
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.
| Trait | What a page sees | Why it is spoofed | Where |
|---|---|---|---|
| Navigator: User-Agent, platform, oscpu, hardware concurrency, language, appVersion | The drawn device's values, per launch or per context, in workers too | They name the OS and hardware directly, and every other value is checked against them | `navigator-spoofing`, `fingerprint-injection` patches |
| HTTP headers: User-Agent, Accept-Language | The navigator values | Servers compare the headers with what script reports | `network-patches` patch |
| Screen and window sizes, color depth, CSS media features | The drawn device's display, the same in JS and CSS | Screen size is among the most identifying values, and CSS media queries read it without script | `screen-spoofing`, `fingerprint-injection` patches |
| WebGL and WebGL2: vendor, renderer, parameters, extensions, shader precision, context attributes | One GPU fpgen recorded for Firefox on that OS. Values Firefox decides rather than the GPU follow the shipped Firefox ([`webgl-browser-owned-values-follow-firefox`](https://github.com/daijro/camoufox/blob/main/ci/tribal-rules.yml)) | The renderer string names the host's GPU, and its limits must agree with it | `webgl-spoofing` patch, `webgl.py` |
| WebGPU: `navigator.gpu` and its adapter | `navigator.gpu` only where Firefox on the claimed device has it: Windows and Apple Silicon Macs. The adapter is the host's only when the identity claims the host's GPU; otherwise `requestAdapter()` returns `null`, as for a blocked or software GPU | The adapter's limits and features come from the real GPU | launcher, `host_rendering.py` |
| Audio: sample rate, output latency, max channels, and the audio fingerprint | The identity's values, seeded per identity | Audio output varies with hardware and drivers, so identities sharing one could be linked | `audio-context-spoofing`, `audio-fingerprint-manager` patches |
| Fonts: installed list, `system-ui`, CSS2 system fonts | The claimed OS's fonts, from a bundled set; see [docs/FONTS.md](https://github.com/daijro/camoufox/blob/main/docs/FONTS.md) | Installed fonts reveal the OS and the software on it | `font-list-spoofing`, `font-hijacker`, `system-ui-font-spoofing` patches |
| Speech voices | The claimed OS's voices, which actually speak | The voice list is specific to each OS, and a voice that cannot speak is a tell | `voice-spoofing`, `speech-voices-spoofing` patches |
| Microphones, cameras, speakers | OS-style labels and groups; see [docs/MEDIA-DEVICES.md](https://github.com/daijro/camoufox/blob/main/docs/MEDIA-DEVICES.md) | Device count and labels differ per machine and per OS | `media-device-spoofing` patch |
| Media codecs (`canPlayType`, `isTypeSupported`) | Not the host's codec libraries | On Linux the answer depends on the host's installed codec libraries | `media-codec-spoofing` patch |
| Timezone, locale and `Intl` | The identity's, per realm, workers included | They must agree with the IP's country | `timezone-spoofing`, `locale-spoofing` patches |
| Geolocation | Coordinates from GeoIP, permission granted | They must agree with the IP | `geolocation-spoofing` patch, launcher |
| WebRTC IP | ICE candidates, SDP and `getStats()` rewritten to the proxy IP | WebRTC otherwise reveals the real IP behind a proxy | `webrtc-ip-spoofing` patch |
| Touchscreen | A touchscreen laptop, not a phone | Touch points and pointer media must agree with the claimed device | `touchscreen-fingerprint-spoofing`, `force-default-pointer` patches |
Left as stock Firefox has it, on purpose:
| Trait | What a page sees | Why it is not spoofed |
|---|---|---|
| Canvas pixels | What the GPU and fonts produce. As in stock Firefox, each context's PNG exports (`toDataURL`, `toBlob`) carry a per-session `deBG` chunk; the pixels themselves are untouched. On the host's OS the identity claims the host's GPU, so the pixels agree with it; on another OS readback returns random data, as `privacy.resistFingerprinting` does in LibreWolf ([the canvas on another OS](https://github.com/daijro/camoufox/blob/main/python/README.md#the-canvas-on-another-os)) | Stock Firefox does not perturb pixels in its default configuration, so noise would only mark the browser as a spoofer ([`canvas-is-not-noised`](https://github.com/daijro/camoufox/blob/main/ci/tribal-rules.yml)) |
| Text widths | What the font really measures | The same font on the same OS measures the same everywhere; widths no real machine produces are a fingerprint ([`no-glyph-spacing-noise`](https://github.com/daijro/camoufox/blob/main/ci/tribal-rules.yml)) |
Each context of one browser can carry its own identity:
[docs/per-context-patches.md](https://github.com/daijro/camoufox/blob/main/docs/per-context-patches.md).
### Canvas
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?
| | Identity on the host's OS | Identity on another OS |
|---|---|---|
| **GPU rendering** | 🟢 <ins><b>Most stealthy</b></ins><br/> ✅ No canvas noise: looks like stock Firefox<br/> ✅ The claimed GPU is the host's, so the pixels agree with it<br/> ⛔ Every identity on this machine claims the same GPU, so there is less fingerprint diversity | 🟡 <ins><b>Less stealthy</b></ins><br/> ✅ Readback is random, so the real OS does not show<br/> ✅ A GPU is drawn per identity, so identities differ<br/> ⛔ Canvas noise: looks like LibreWolf, Tor Browser or Mullvad Browser, which are rarer than stock Firefox |
| **Software rendering**<br/>(no GPU driver, as on most servers) | 🟢 <ins><b>Stealthy</b></ins><br/> ✅ No canvas noise: looks like stock Firefox<br/> ✅ A GPU is drawn per identity, so identities differ<br/> ⛔ Looks like a GPU falling back to software rendering, which is rarer than a working GPU | 🟡 <ins><b>Less stealthy</b></ins><br/> ✅ Readback is random, so the real OS does not show<br/> ✅ A GPU is drawn per identity, so identities differ<br/> ⛔ Canvas noise: looks like LibreWolf, Tor Browser or Mullvad Browser, which are rarer than stock Firefox |
That is the default. These options override it:
| Override | Result |
|---|---|
| `canvas_noise=False` on another OS | 🔴 Stock Firefox, but the pixels show the real OS |
| `canvas_noise=True` on the host's OS | 🟡 Looks like LibreWolf with no need to |
| `webgl_config` naming a GPU other than the host's | 🟡 Canvas noise is turned on, as on another OS; with `canvas_noise=False`, 🔴 WebGL reports one GPU while the pixels come from another |
Noise is set per browser, not per context. Without it, every `NewContext()`
---
[Read more](https://github.com/daijro/camoufox)