The launch-options table documents i_know_what_im_doing as silencing the option warnings, but custom_fonts_only raised its LeakWarning without the flag in both launchers, so it always printed and never named the flag. Ref #1069
camoufox (TypeScript)
The Node.js launcher for the Camoufox anti-detect browser.
camoufox drives the Camoufox browser through playwright-core. On every
launch it draws a complete device identity from
fpgen-js, the TypeScript port of
scrapfly's fpgen, checks that the
parts agree with each other, and hands it to the browser, which spoofs it in
C++. With a proxy and geoip: true it also matches timezone, locale,
geolocation and the WebRTC IP to the proxy's exit IP.
It is a port of the Python package (python/) and does not call
Python. Both launchers read the same properties.json, write the same
CAMOU_CONFIG, share one browser install directory, and draw the same
identities: a pinned identity looks the same from either language. Notes for
AI coding agents are in AGENTS.md.
Install
npm install camoufox playwright-core
npx camoufox fetch
| Requirement | Value |
|---|---|
| Node.js | 22.15 or newer |
playwright-core |
peer dependency, below 1.63 |
| GeoIP | built in; the GeoIP All-in-One database downloads on first use |
camoufox fetch installs the browser build this release is paired with.
Without it, the first launch downloads it.
It reads the build's release with one GitHub API call and exits non-zero
when it installs nothing. On a shared CI runner, set GITHUB_TOKEN to raise
GitHub's API rate limit.
Usage
Camoufox() returns a Playwright Browser (or a BrowserContext for a
persistent profile), so existing Playwright code works once the launch is
changed.
import { Camoufox } from "camoufox";
const browser = await Camoufox({ headless: true });
const page = await browser.newPage();
await page.goto("https://example.com");
await browser.close();
Playwright-Python has a sync and an async API, so the Python package has both.
playwright-core has one, so here every function returns a promise.
AsyncCamoufox, AsyncNewBrowser and AsyncNewContext are aliases kept for
parity with Python.
Proxy with a matching location
import { Camoufox } from "camoufox";
const browser = await Camoufox({
proxy: { server: "http://proxy.example.com:8080", username: "user", password: "pass" },
geoip: true,
});
geoip: true looks up the exit IP through the proxy, then sets timezone,
locale, geolocation and the WebRTC IP from it. Pass an IP string instead to
skip the lookup.
Without a proxy, sites can reach this machine over IPv6. IPv6 stays on when the
machine's IPv6 address geolocates where the IPv4 identity does. Otherwise, the
browser behaves as on an IPv4-only network, and a LeakWarning says why.
Persistent profile
import { Camoufox } from "camoufox";
const context = await Camoufox({ persistent_context: true, user_data_dir: "./profiles/alice" });
const page = await context.newPage();
await page.goto("https://example.com");
await context.close();
One browser, many identities
NewContext() gives each context its own identity (navigator, screen, WebGL,
fonts, voices, timezone, WebRTC IP), applied through
addInitScript before any page script runs.
import { Camoufox, NewContext } from "camoufox";
const browser = await Camoufox({ headless: true, canvas_noise: true });
const alice = await NewContext(browser, { os: "windows" });
const bob = await NewContext(browser, {
os: "macos",
proxy: { server: "http://proxy.example.com:8080", username: "user", password: "pass" },
});
await (await alice.newPage()).goto("https://example.com");
await (await bob.newPage()).goto("https://example.com");
await browser.close();
NewContext option |
Effect |
|---|---|
preset |
Use this fingerprint preset object instead of an fpgen draw. |
os |
"windows", "macos" or "linux" for the drawn identity. On a browser without canvas noise, the host's OS, and anything else throws ValueError. |
ff_version |
Firefox major version claimed in the User-Agent. Defaults to the browser's own. |
webrtc_ip |
IPv4 or IPv6 address WebRTC reports. |
proxy |
Per-context proxy, in Playwright's format. The context is placed where the proxy exits: webrtc_ip, timezoneId, locale and geolocation each default to the exit IP's, looked up through the proxy unless all four are given, and InvalidIP is thrown if the lookup fails. |
geolocation |
{ latitude, longitude }; also grants the geolocation permission. |
| anything else | Passed to Playwright's browser.newContext() (camelCase, e.g. timezoneId), overriding the generated value. |
Canvas noise belongs to the browser, not the context (see
The canvas on another OS). On a browser without it,
every context claims the host's OS and GPU too, since its canvas renders there.
Contexts with other OSes, like the ones above, need canvas_noise: true.
The browser's own OS also decides some things for all its contexts. A browser
launched as Windows on a Linux or macOS host (os: "windows", or drawn so)
computes Math as the Windows CRT does and uses Windows' keyboard shortcuts
(on a Linux host; on macOS only the editor caret style), middle-click and
scrollbars (docs/HOST-PARITY.md).
Those are browser settings, so a macOS context on it has them too, and a
Windows context on a browser launched as another OS has the host's. NewContext
does not refuse the mix. Pass os at launch for the OS whose behaviour matters,
or use one browser per OS.
The canvas on another OS
A page can draw a canvas or a WebGL scene and read the pixels back. Those pixels come from the real OS, driver and GPU, whatever the identity claims.
- On the host's OS, the launcher starts the browser once, unspoofed and with
the same display, reads the GPU Firefox reports, and the identity claims it.
The pixels then agree with the identity. A host that renders in software (no
working GPU driver, as on most servers) claims its software renderer, such as
llvmpipeon Linux. Firefox reads the name and the pixels from one GL context, so a machine with a broken driver reports the software renderer too, and a GPU name over software pixels never happens on a real machine. - On another OS, or with another GPU (
webgl_config, a preset's GPU, or a host GPU fpgen never recorded), the pixels would show the real one. Camoufox then turns on the canvas protection ofprivacy.resistFingerprinting, and only that: canvas and WebGL readback return random data, as in LibreWolf, Tor Browser and Mullvad Browser. Stock Firefox does not do this, so the launch emits aLeakWarning; the browser reads as a privacy-hardened Firefox rather than a stock one.
canvas_noise: true turns the protection on for any OS, canvas_noise: false
never.
WebGPU follows the same rule. navigator.gpu exists only where Firefox on the
claimed device has it (Windows and Apple Silicon Macs), and the adapter is the
host's only when the identity claims the host's GPU. Otherwise
requestAdapter() returns null, as Firefox does for a blocked or software GPU.
Headless modes
headless: |
What runs | Notes |
|---|---|---|
false (default) |
A normal window | Needs a display. |
true |
Firefox headless | Camoufox patches the headless tells it knows about. |
"virtual" |
A headed browser on a private Xvfb display | Linux only, needs Xvfb and setpriv (util-linux). Handled by Camoufox(), NewBrowser() and launchServer(). The display is 1x1 unless CAMOUFOX_VIRTUAL_DISPLAY_SIZE (e.g. 1920x1080x24) says otherwise. Xvfb has no GPU: canvas and WebGL render in software. |
"virtual-gpu" |
A headed browser on a private, headless Xorg server bound to one GPU | Linux only, needs Xorg and the card's driver. Canvas and WebGL render on the card. Handled like "virtual". |
import { Camoufox } from "camoufox";
const browser = await Camoufox({ headless: "virtual-gpu", gpu: "0000:01:00.0", os: "linux" });
The card is named by gpu or CAMOUFOX_GPU, never guessed. Without root,
set the machine up once per card. This installs Xorg and its setuid wrapper,
lets the wrapper start Xorg for any user and installs the card's config. A
launch that fails for want of it ends its error with this command:
npx camoufox gpu-setup 0000:01:00.0 | sudo sh
The launch checks that the browser renders on the card, and the identity claims that card. The Python README explains the selectors, the checks and the errors: The GPU display.
Remote server
import { launchServer } from "camoufox";
const server = await launchServer({ headless: true, port: 1234, ws_path: "camoufox" });
console.log(server.wsEndpoint());
Connect from any Playwright client with firefox.connect(endpoint). A
persistent context cannot be served.
Your own Playwright instance
NewBrowser() launches on a BrowserType you pass, and launchOptions()
returns the options for firefox.launch():
import { firefox } from "playwright-core";
import { NewBrowser, launchOptions } from "camoufox";
const browser = await NewBrowser(firefox, { os: "linux", headless: true });
await browser.close();
const plain = await firefox.launch(await launchOptions({ os: "linux", headless: true }));
await plain.close();
Prefer NewBrowser(): it also defaults new pages to no viewport when the
window size is spoofed, and to the host's own color scheme and motion settings.
launchOptions() returns Playwright's camelCase keys (executablePath,
firefoxUserPrefs), and does not handle headless: "virtual" or "virtual-gpu".
Launch options
Camoufox(), NewBrowser(), launchServer() and launchOptions() take one
options object. Camoufox's own options keep the Python package's snake_case
names. Any other key is passed to Playwright's firefox.launch() (or
launchPersistentContext()), in Playwright's camelCase.
| Option | Type | Default | Effect |
|---|---|---|---|
os |
string | string[] |
fpgen's real-world mix | "windows", "macos", "linux", or a list to pick from. |
headless |
boolean | "virtual" | "virtual-gpu" |
false |
See Headless modes. |
gpu |
string | number |
CAMOUFOX_GPU, or the only GPU |
The card for headless: "virtual-gpu". Not taken by launchOptions(). |
require_gpu |
boolean |
true |
With headless: "virtual-gpu", fail the launch when the browser does not render on the card; false warns. Not taken by launchOptions(). |
proxy |
{ server, username?, password?, bypass? } |
none | Playwright proxy. A socks5:// proxy can have a username and password too (RFC 1929), which Playwright alone refuses; the same holds for NewContext() and newContext(). |
geoip |
boolean | string |
none | true finds the public IP (through proxy if set); a string uses that IP. Sets timezone, locale, geolocation and the WebRTC IP. Without a proxy, also decides whether IPv6 stays on. |
geoip_db |
string |
the camoufox set --geoip choice |
GeoIP database name, e.g. "GeoIP AIO by daijro". |
locale |
string | string[] |
from geoip, else the drawn identity's |
Locale(s), e.g. "en-US". The first is used for Intl. |
humanize |
boolean | number |
off | Human cursor movement. A number caps one movement at that many seconds (default cap 1.5). |
screen |
Screen | { max_width?, max_height?, min_width?, min_height? } |
the real display when headed | Bounds the generated screen. |
window |
[number, number] |
generated | Fixed outer window size. |
fonts |
string[] |
none | Extra font families on top of the OS's own. |
custom_fonts_only |
boolean |
false |
Use only fonts, not the OS fonts. Warns: the font set no longer matches the OS. |
addons |
string[] |
none | Paths to extracted Firefox addons (folders with a manifest.json). |
exclude_addons |
("UBO")[] |
none | Default addons to leave out. |
block_images |
boolean |
false |
Block image loading. Warns: some WAFs detect it. |
block_webrtc |
boolean |
false |
Disable WebRTC entirely. |
block_webgl |
boolean |
false |
Disable WebGL. Warns: many WAFs check for it. |
webgl_config |
[vendor, renderer] |
drawn | Use one GPU fpgen has recorded for Firefox on os; any other pair throws. Needs os. |
cpu |
{ arch?: "x86" | "arm", manufacturer?: string } |
follows the GPU and cores, else x86 drawn | The CPU the identity computes as: canvas, Web Audio, Opus, relaxed-SIMD wasm and NaN signs differ between x86-64 and ARM64, and canvas and Opus between Intel and AMD. A manufacturer alone implies its arch. Per OS: macos x86 intel, arm apple; windows x86 intel/amd, arm qualcomm; linux x86 intel/amd, arm apple, qualcomm, broadcom, nvidia, ampere, rockchip, mediatek, amlogic, allwinner. A pair no machine on the OS has, or one the GPU contradicts, throws ValueError; without os, the OS is drawn among those with a recorded GPU for the CPU. By default an Apple GPU is Apple ARM, an Intel iGPU or Intel Mac Intel, a Radeon iGPU AMD, and 10, 14, 18, 22 or 28 logical cores Intel; otherwise x86, 81% Intel. ARM64 is emulated on an x86-64 host, and Intel or AMD x86-64 on an ARM64 host. |
canvas_noise |
boolean |
on for another OS or GPU | Random canvas and WebGL readback, as in LibreWolf. Warns. See The canvas on another OS. |
disable_coop |
boolean |
false |
Turn off Cross-Origin-Opener-Policy so elements in cross-origin iframes (such as the Turnstile checkbox) can be clicked. Warns. |
main_world_eval |
boolean |
false |
Allow page.evaluate("mw:...") and mw: init scripts to run in the page's own world. |
allow_addon_new_tab |
boolean |
false |
Let addons open tabs. |
enable_cache |
boolean |
false |
Keep Firefox's page and request caches. Uses more memory. |
pin_cpu_cores |
boolean |
false |
Linux and Windows: pin the browser to as many cores as navigator.hardwareConcurrency claims. Costs CPU and serializes concurrent launches. |
fingerprint |
fpgen fingerprint object | drawn | Use this fpgen fingerprint instead of drawing one. Warns. |
fingerprint_preset |
boolean | object |
undefined |
Opt into a recorded real-device preset instead of fpgen: true picks a random bundled one, an object uses that one. |
ff_version |
number |
the browser's own | Firefox version to claim. Warns: a mismatch with the engine is detectable. |
config |
object |
none | Raw Camoufox properties (properties.json). Overrides the generated identity; manual identity keys warn. A value you set is always used; one no real machine with the rest of the identity reports prints a LeakWarning naming it, which i_know_what_im_doing does not silence. |
firefox_user_prefs |
object |
none | Extra Firefox prefs. |
args |
string[] |
none | Extra browser command-line arguments. |
env |
object |
a copy of process.env |
Environment variables for the browser. |
executable_path |
string |
the installed build | Use this binary. CAMOUFOX_EXECUTABLE_PATH sets it too. Raises with browser. |
browser |
string |
the paired build | Launch another installed build: "official/beta.20", "beta.20" or "134.0.2-beta.20". Never downloads; warns like camoufox set. |
virtual_display |
string |
none | Use an existing X display, e.g. ":99". |
i_know_what_im_doing |
boolean |
false |
Silence the leak warnings above. |
debug |
boolean |
false |
Print the config sent to the browser. |
Camoufox() and NewBrowser() also take persistent_context, user_data_dir
and from_options (an object from launchOptions() to use as is).
launchServer() also takes port and ws_path.
CLI
npx camoufox <command>. The commands match the Python package's.
| Command | Options | What it does |
|---|---|---|
fetch [version] |
Install the paired build (or, after set, the latest in the chosen channel), or version without making it active. A named or paired build is read from its own release; anything else syncs first. Exits non-zero when nothing is installed. |
|
sync |
--spoof-os auto|mac|win|lin, --spoof-arch auto|x86_64|i686|arm64 |
Refresh the list of available builds. |
set [specifier] |
--geoip, --release |
Pin a build (official/stable/134.0.2-beta.20) or follow a channel (official/stable). No specifier opens a picker. --geoip picks the GeoIP database instead; --release goes back to the paired build. |
active |
Print the active build. A build that is chosen but not downloaded is marked (not fetched). |
|
list [installed|all] |
--path |
List installed builds, or every available one. |
remove [version] |
--select, -y/--yes |
Remove one build, pick one interactively, or (with no argument) everything. |
version |
Package versions, the active build, the GeoIP database, and storage paths and sizes. | |
path |
Print the data directory (~/.cache/camoufox on Linux). |
|
test [url] |
--executable-path <path> |
Open a headed browser with the Playwright inspector. |
server |
Start a Playwright server and print its websocket endpoint. | |
gpu-setup [gpu] |
Print the root script that sets this machine up for headless: "virtual-gpu" on the card gpu names (or CAMOUFOX_GPU). Run it with | sudo sh. |
|
gpu-xorg-config [gpu] |
Print the Xorg config headless: "virtual-gpu" needs for the card gpu names (or CAMOUFOX_GPU). |
Each release is paired with the one browser build it was built and tested with,
the same build as the Python release of the same version, and every launch uses
it until camoufox set chooses another. The Python README explains the rules:
Which browser build is used.
Development
The tests compare this package's output with the Python package's, so they need
a Python with python/ installed: the repository's .venv, or
CAMOUFOX_PYTHON.
python3.14 -m venv .venv # repo root
.venv/bin/pip install -r ci/requirements.txt -e python
.venv/bin/python python/scripts/pin-fpgen-model.py
cd typescript
pnpm install
pnpm build # tsc -> dist/, then copy the Python package's data files into dist/data-files
pnpm test # records the golden fixtures from python/, then runs vitest
pnpm check # biome lint and format
pnpm typecheck # tsc --noEmit
The data files (presets, fonts, voices, territoryInfo.xml, ...) have one copy,
in python/src/camoufox/. DATA_FILES in src/paths.ts lists them, and the
build copies them into the package.
Parity. Before the suite runs, tests/golden-setup.ts runs the scripts in
scripts/golden/, which record the Python package's output over fixed inputs
into tests/fixtures/ (git-ignored). The TypeScript tests must reproduce it
exactly, launch_options() byte for byte including the CAMOU_CONFIG blob. A
Python change that is not mirrored here fails pnpm test. Use Python 3.14:
pySum() follows its sum(), and that test skips on 3.12 and 3.13.
The end-to-end suite launches a real browser through both launchers and compares what a page sees:
CAMOUFOX_E2E=1 CAMOUFOX_EXECUTABLE=/path/to/camoufox-bin pnpm test tests/e2e.test.ts
Releases. The npm and PyPI packages are released together by
release.yml, at the same version
(ci/README.md). scripts/check-pack.mjs checks
that the tarball carries every data file and installs into an empty project.
npm uploads use trusted publishing; no token is stored.
Licence
MIT (LICENSE).
The browser itself is MPL-2.0. The package contains a port of NumPy's pairwise
summation; its notice is in
THIRD_PARTY_NOTICES.md.
It depends on fpgen-js (Apache-2.0) and
python-random, a bit-exact port
of CPython's random, so seeded draws match the Python launcher.