* Firefox 159: stock parity for a driven browser A page driven through Camoufox should read like stock Firefox in a person's hands. This brings the Firefox 159 port up to that. Stock defaults - Remote Settings, Safe Browsing, region detection, Push, connectivity checks and the new tab keep Firefox's defaults; Nimbus is tied to Normandy so the new tab starts without it. - No policies.json: any policy file puts Firefox in enterprise mode, which a page can see (DNS over HTTPS stands down). - Firefox's 100% release rollouts are default prefs; stock's search engines are back. - WebGL, devicePixelRatio and worker getters cost what stock's do; Linux builds use --enable-stdcxx-compat, as Mozilla's do. Juggler - Driver code defines no interfaces on the page's window, isolated and main-world evaluates included. - Input arrives as a person's: click hold, hover dwell and double-click gap; fill() and insert_text() type key by key; the wheel turns notches; moves coalesce per frame; drags behave as a GTK drag session. Input waits for Firefox's user-input gate. - Focus, Fission and bfcache stay Firefox's unless a driver needs them. - Screenshots and document.fonts.ready leave the page alone. Humanize - One engine per channel (mouse, keyboard, scroll) behind one seam in Juggler, a seed for repeatable input, and custom(fn) engines run in the caller's process (Python). The build lists its engines in humanize-engines.json. Network - A SOCKS5 proxy with a username and password works for the launch and per context. - The User-Agent header follows the context's identity. - WebRTC UDP goes through a SOCKS5 proxy's UDP ASSOCIATE relay (webrtc-socks5-udp.patch), so a page's STUN server sees the exit and the srflx is real. Nothing goes around the proxy: a page with no HTTP-loaded document behind it counts as proxied, a proxy that carries no UDP gets none, and a relay address inside the proxy's own NAT is replaced by the proxy's public one. Identity - Bundled fonts and speech voices follow the drawn identity. - The window holds the identity's size and position through startup, and on a virtual display a window outside the root is neither occluded nor refused focus. CI runs every new guard. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BLGoGNeymhNcr3EAQX5hJE * Paste inserted text; draw input delays from one normal helper fill() and keyboard.insert_text() typed the text key by key, a quarter of a second per character, which ran past Playwright's timeouts and is not how a person enters a whole string. They now paste: the paste shortcut (Ctrl+V, Cmd+V for a Mac platform) goes down, Firefox's own paste runs with the text through nsIEditor.pasteTransferable (a trusted paste event with the text as clipboardData, then beforeinput/input insertFromPaste), and the shortcut comes up. The shortcut's keypress, where Firefox would read the system clipboard, is cancelled in the system group, which content cannot observe; the system clipboard is never used. A page that cancels the paste or the shortcut gets nothing, and the call fails saying so. input/HumanDelay.js holds normalDelay(mean, sd, min, max), the one draw for the delays between a person's input events: the click hold (normal around 110 ms, SD 30, never under 50 ms, with no ceiling), the double-click gap, the hover dwell, the paste key's hold, and the Shift and paste modifiers' lead and trail. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BLGoGNeymhNcr3EAQX5hJE * Fix driven input and headless parity * Headless with a display uses that display's GL A headless probe that failed to load EGL still recorded TEST_TYPE EGL, so Firefox refused GLX and every headless WebGL context died. Probe EGL only when there is no display, and only claim it when that probe initialized. Move spacing starts when the move is sent, so a steps path stays a 125 Hz mouse instead of one move per frame. * Fix focus, humanize-off, and WebRTC proxy parity - A stock identity mirror adds no humanize keys when humanize is off. - Keep the real focus and run the upstream focus tests. - Add the per-context WebRTC proxy flag; do not fabricate a srflx behind a proxy. - Refresh the Python/TypeScript parity tests, skiplist and docs. - Install Mesa DRI so the software WebGL guards can run. * Fix TypeScript humanize float encoding Encode humanize option values as PyFloat so a duration serializes as 1.0, matching Python, and apply Biome's import formatting. * Close a relay overflow, stop inventing srflx, and fix driven input gaps WebRTC: - A SOCKS5 relay read larger than the caller's buffer overran the stack buffer. A page-named STUN server could send one. Drop the datagram. - Remove the fabricated srflx candidate; a srflx now only comes from a STUN answer, and the guards run against a server that answers. - Juggler records each proxy it sets, so a caller's own new_context(proxy=...) cannot gather around it. This replaces the launcher's webrtc:proxied key and its page-visible setter. - Headless GL probes use the surfaceless platform without launcher plumbing. Input: - A wheel without a scroll engine takes the activation slot per notch, so a long scroll no longer stalls input in every other context. - Paste and fill work inside an iframe. - Python fill honours the caller's timeout. TypeScript humanize matches Python: off, seeds, duplicate options and the scroll warning. Guards with a missing prerequisite fail rather than pass. Add navigation-preconnect-proxied. Move the tweened click test to a skiplist pattern entry, since whether it passes depends on machine speed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Check the tweened click entry with its guard, not the audit Whether test_click_with_tweened_mouse_movement passes depends on machine speed: 0 of 20 runs on all cores here, 3 of 15 on two, and it passed on CI. The audit cannot demand a failure from it, and a pattern entry would leave its reason unchecked. A skiplist entry's checked_by now names the patch guard that checks the reason, here driven-move-coalescing. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Ask the display-less GL probe for a pbuffer config Mesa's surfaceless platform has only pbuffer configs. The probe asked for the default window surface type, so eglChooseConfig matched nothing and eglCreateContext got an uninitialized config. With no GPU, a display-less headless launch then had an empty gfxInfo: no WebGL and no WebRTC H264. A host where NVIDIA's EGL answers first never reaches Mesa here, so the guards only failed on machines without a GPU. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Open about:blank for a driver and run first-page init scripts after PageAgent A headed persistent launch opened about:home once the start page prefs went back to stock. browser.startup.page now becomes 0 only when a driver attaches, so a browser nobody drives keeps Firefox's start page. Init scripts on a page's initial document ran before PageAgent existed, so their binding calls and console messages had no listener and were lost. They now run after PageAgent has reported the page's execution contexts. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Warm up the crash growth test past Firefox 159's timed startup work The parent holds up to 400 MB more for a while at fixed times after launch, in stock Firefox 159 as well. Two RSS readings taken across one of those peaks read as growth or shrinkage, and pushed the test over its limit with no leak. Warm up by time instead of by context count. The metric and limit are unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Close WebRTC paths around a proxy, stop background traffic, fix driven input WebRTC behind a proxy no longer shows the host's address: ICE uses the proxy's SOCKS5 UDP relay when it has one, and UDP is dropped otherwise. A page on the bypass list behind a forced proxy is blocked on UDP and ICE TCP. A proxy hanging up straight after CONNECT no longer crashes the parent process. Remote Settings stops polling, with the page-visible lists bundled as a snapshot pinned by scripts/remote_settings.py, and Push connects on demand. fill clicks an unfocused text field and types when a page blocks paste. Click throughput across contexts is restored. The TypeScript launcher gains custom humanize engines and driver defaults, in step with Python, and caps WebGL2 MAX_UNIFORM_BLOCK_SIZE at Firefox 159's 64 KiB. docs/input-dispatch.md records a person's wheel on macOS, which is one line a notch where the driven wheel sends three. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Leave the humanize engine system for its own pull request Per-channel engines, seeded streams, custom() and the keyboard and scroll-into-view plans are a separate feature. humanize keeps main's meaning here: a human cursor move, on or off, with an optional duration cap, planned by CursorTrajectory.js and paced by Pacer.js. The five per-channel config keys were declared on this branch, so they stay declared as removed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Warn, not raise, on a browser that cannot read voices:speechd A new package has to launch an older build (#835, and the install gate launches the last release). A Linux identity there reports no voices, so it warns and the warning cannot be silenced. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Give a macOS identity macOS's wheel A person's notched mouse on macOS sends one line for a slow notch, with no native tick, and accelerates a faster turn from there. Driven input sent Linux's three ticked lines. A macOS identity now sends lines at 16 px each, starting at one and growing, and stock's per-OS system scroll override follows the identity. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Install the tracking lists where a clean build's reader looks A relative wildcard keeps its directory under recursive make and drops it under faster make. The clean build nested the attachments one directory too deep, so the classifier had no tables. An incremental objdir hid this with old links. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Make two guards deterministic: the wheel's OS and a dropped relay A launch without `os` draws one, and a macOS draw now gets macOS's wheel, so the guards asserting three notches failed by the draw. They assert Linux's now. The browser flushes queued datagrams when UDP ASSOCIATE is granted, so a relay closed just after the grant could forward one, and the STUN server heard the proxy's own relay port as if it had gone around the proxy. It closes first now. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>
20 KiB
camoufox (Python)
The Python launcher for the Camoufox anti-detect browser.
camoufox drives the Camoufox browser through Playwright. On every launch it
draws a complete device identity from fpgen,
a model of real-world traffic, 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.
The TypeScript package (typescript/) is a port of this one
with the same options. Notes for AI coding agents are in
AGENTS.md.
Install
pip install -U "camoufox[geoip]"
camoufox fetch
| Requirement | Value |
|---|---|
| Python | 3.10 or newer |
| Playwright | below 1.63 (installed as a dependency) |
geoip extra |
needed for geoip=; downloads the GeoIP All-in-One database, refreshed once it is a week old |
camoufox fetch installs the browser build this release is paired with, and
fpgen's model, pinned by sha256. Without it, the first launch downloads both.
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.
Run fetch as the user that owns the Python environment if the browser will
run as someone else, for example while building a Docker image.
camoufox remove deletes everything that was downloaded.
Usage
Camoufox returns ordinary Playwright objects, so existing Playwright code works once the launch is changed.
Sync and async
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())
Proxy with a matching location
from camoufox.sync_api import Camoufox
with Camoufox(
proxy={"server": "http://proxy.example.com:8080", "username": "user", "password": "pass"},
geoip=True,
) as browser:
page = browser.new_page()
page.goto("https://example.com")
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
from camoufox.sync_api import Camoufox
with Camoufox(persistent_context=True, user_data_dir="profiles/alice") as context:
page = context.new_page()
page.goto("https://example.com")
With persistent_context=True the context manager yields a BrowserContext,
not a Browser.
One browser, many identities
NewContext() gives each context its own identity (navigator, screen, WebGL,
fonts, voices, timezone, WebRTC IP), applied through
add_init_script before any page script runs.
from camoufox.sync_api import Camoufox, NewContext
with Camoufox(headless=True, canvas_noise=True) as browser:
alice = NewContext(browser, os="windows")
bob = NewContext(
browser,
os="macos",
proxy={"server": "http://proxy.example.com:8080", "username": "user", "password": "pass"},
)
alice.new_page().goto("https://example.com")
bob.new_page().goto("https://example.com")
NewContext argument |
Effect |
|---|---|
preset |
Use this fingerprint preset dict 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 raises 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. Unless webrtc_ip and timezone_id are both given, they are looked up from the proxy's exit IP, and InvalidIP is raised if the lookup fails. |
geolocation |
{"latitude": ..., "longitude": ...}; also grants the geolocation permission. |
| anything else | Passed to Playwright's new_context(), overriding the generated value. |
AsyncNewContext() is the async twin.
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 GPU driver, as on most servers) keeps a drawn GPU: it reads as a machine whose driver failed to load.
- 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 prints 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, AsyncCamoufox, NewBrowser and launch_server. 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". See The GPU display. |
The GPU display
from camoufox.sync_api import Camoufox
with Camoufox(headless="virtual-gpu", gpu="0000:01:00.0", os="linux") as browser:
page = browser.new_page()
- The card is named, never guessed.
gpu=(orCAMOUFOX_GPU) takes a PCI address, which is the stable choice, or an index in PCI address order, a render or card node (renderD128,/dev/dri/card1),vendor:deviceids (10de:2c02) or a vendor name (nvidia). With several GPUs and no selector the launch raisesAmbiguousGpuSelection;GpuNotFoundandNoGpuFoundmean what they say.python -m camoufox gpu-xorg-configlists the GPUs when the choice is ambiguous. - Without root, set the machine up once per card. Xorg then runs through
the setuid
Xorg.wrap, which takes a config only from/etc/X11and needsallowed_users=anybodyandneeds_root_rights=yesin/etc/X11/Xwrapper.config. Stock Debian and Ubuntu shipallowed_users=console, which refuses a launch from ssh, systemd or a container. One command installs Xorg and the wrapper (withapt-get; elsewhere it says what to install), sets those two lines and installs the card's config. It is safe to run again:A launch that fails for want of any of this ends its error with that command. The settings let any local user start a root X server.python -m camoufox gpu-setup 0000:01:00.0 | sudo shgpu-xorg-configprints just the card's config. As root, nothing is installed: a temporary config is used instead. - It leaves your desktop alone. The server drives no monitor, shares the
current VT and exits when the browser closes. If the active VT changes while
it starts, the launch switches back, stops the server and raises
GpuVtTakeover. - The launch checks the browser renders on the card. A page draws WebGL
and the launch waits up to 30 s (
CAMOUFOX_GPU_WAIT_S) for the kernel to account GPU work to the browser. If it never does, the browser is closed andGpuSoftwareFallbackis raised;require_gpu=Falsewarns instead. There is no fallback to Xvfb. - The identity claims that card. On the host's OS the identity claims the GPU Firefox reports, read on this display, so it is the card's and not the desktop's (see The canvas on another OS).
- The browser gets
DISPLAYand the X11 backend, and nothing that chooses a GL driver. These prefs default on, andfirefox_user_prefswins:gfx.webrender.all,layers.acceleration.force-enabled,gfx.x11-egl.enabled,gfx.canvas.acceleratedandgfx.canvas.accelerated.force-enabled.
Every error here is a VirtualDisplayError.
Remote server
Run Camoufox in one process and connect from any language Playwright supports:
from camoufox.server import launch_server
launch_server(headless=True, geoip=True, port=1234, ws_path="camoufox")
It prints the websocket endpoint. Connect with
playwright.firefox.connect("ws://localhost:1234/camoufox"). A persistent
context cannot be served.
Your own Playwright instance
NewBrowser() launches on a Playwright instance you already have, and
launch_options() returns the keyword arguments for
playwright.firefox.launch():
from playwright.sync_api import sync_playwright
from camoufox import NewBrowser, launch_options
with sync_playwright() as playwright:
browser = NewBrowser(playwright, os="linux", headless=True)
browser.close()
browser = playwright.firefox.launch(**launch_options(os="linux", headless=True))
browser.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.
Launch options
Camoufox, AsyncCamoufox, NewBrowser, AsyncNewBrowser, launch_server
and launch_options all take these keyword arguments. Any other keyword is
passed to Playwright's firefox.launch() (or launch_persistent_context()).
| Option | Type | Default | Effect |
|---|---|---|---|
os |
str or list[str] |
fpgen's real-world mix | "windows", "macos", "linux", or a list to pick from. |
headless |
bool, "virtual" or "virtual-gpu" |
False |
See Headless modes. |
gpu |
str or int |
CAMOUFOX_GPU, or the only GPU |
The card for headless="virtual-gpu". See The GPU display. Not taken by launch_options. |
require_gpu |
bool |
True |
With headless="virtual-gpu", fail the launch when the browser does not render on the card; False warns. Not taken by launch_options. |
proxy |
dict |
none | Playwright proxy: server, username, password, bypass. A socks5:// proxy can have a username and password too (RFC 1929), which Playwright alone refuses; the same holds for NewContext() and new_context(). |
geoip |
bool or str |
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. Needs the geoip extra. |
geoip_db |
str |
the camoufox set --geoip choice |
GeoIP database name, e.g. "GeoIP AIO by daijro". |
locale |
str or list[str] |
from geoip, else the drawn identity's |
Locale(s), e.g. "en-US" or ["fr-FR", "en-US"]. The first is used for Intl. |
humanize |
bool or float |
off | Human cursor movement. A number caps one movement at that many seconds (default cap 1.5). |
screen |
camoufox.fingerprints.Screen |
the real display when headed | Bounds the generated screen: Screen(max_width=1920, max_height=1080). |
window |
(int, int) |
generated | Fixed outer window size. |
fonts |
list[str] |
none | Extra font families on top of the OS's own. |
custom_fonts_only |
bool |
False |
Use only fonts, not the OS fonts. Warns: the font set no longer matches the OS. |
addons |
list[str] |
none | Paths to extracted Firefox addons (folders with a manifest.json). |
exclude_addons |
list[DefaultAddons] |
none | Default addons to leave out, e.g. [DefaultAddons.UBO]. |
block_images |
bool |
False |
Block image loading. Warns: some WAFs detect it. |
block_webrtc |
bool |
False |
Disable WebRTC entirely. |
block_webgl |
bool |
False |
Disable WebGL. Warns: many WAFs check for it. |
webgl_config |
(vendor, renderer) |
drawn | Use one GPU fpgen has recorded for Firefox on os (see camoufox.webgl.firefox_gpus); any other pair raises ValueError. Needs os. |
canvas_noise |
bool |
on for another OS or GPU | Random canvas and WebGL readback, as in LibreWolf. Warns. See The canvas on another OS. |
disable_coop |
bool |
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 |
bool |
False |
Allow page.evaluate("mw:...") and mw: init scripts to run in the page's own world. |
allow_addon_new_tab |
bool |
False |
Let addons open tabs. |
enable_cache |
bool |
False |
Keep Firefox's page and request caches. Uses more memory. |
pin_cpu_cores |
bool |
False |
Linux and Windows: pin the browser to as many cores as navigator.hardwareConcurrency claims, so a page timing parallel workers measures the same number. Costs CPU and serializes concurrent launches. |
fingerprint |
fpgen fingerprint dict |
drawn | Use this fpgen fingerprint instead of drawing one. Warns. |
fingerprint_preset |
bool or dict |
None |
Opt into a recorded real-device preset instead of fpgen: True picks a random bundled one, a dict uses that one. |
ff_version |
int |
the browser's own | Firefox version to claim. Warns: a mismatch with the engine is detectable. |
config |
dict |
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 |
dict |
none | Extra Firefox prefs. |
args |
list[str] |
none | Extra browser command-line arguments. |
env |
dict |
a copy of the environment | Environment variables for the browser. |
executable_path |
str or Path |
the installed build | Use this binary. CAMOUFOX_EXECUTABLE_PATH sets it too. Raises with browser. |
browser |
str |
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 |
str |
none | Use an existing X display, e.g. ":99". |
i_know_what_im_doing |
bool |
False |
Silence the leak warnings above. |
debug |
bool |
False |
Print the config sent to the browser. |
NewBrowser and AsyncNewBrowser also take persistent_context and
from_options (a dict from launch_options() to use as is).
CLI
camoufox <command>, or python -m camoufox <command>.
| 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 from every repository. |
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, as a tree. |
remove [VERSION] |
--select, -y/--yes |
Remove one build, pick one interactively, or (with no argument) the whole data directory. |
version |
Package versions (Camoufox, fpgen, Playwright), the active build and whether it is the latest in its channel, 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 with default options 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). |
set and fetch read builds from these repositories (repos.yml):
| Name | Repository |
|---|---|
| Official | daijro/camoufox |
| CoryKing | coryking/camoufox |
| JWriter20 | JWriter20/camoufox |
https://github.com/user-attachments/assets/992b1830-6b21-4024-9165-728854df1473
Which browser build is used
Each release of this package is paired with the one browser build it was built
and tested with. camoufox fetch installs that build and every launch uses it,
even when other builds are installed and even when the paired build is a
prerelease. A launch with the paired build missing downloads it first, so
upgrading the package never runs a browser it was not tested with.
camoufox set overrides the pairing. The choice is kept, and each launch warns
that the build differs from the paired one. camoufox set --release goes back.
The browser launch option overrides it for one launch, the same way: the named
build must already be installed, and nothing is downloaded.
Every browser release declares the interface it speaks, and the package refuses
one it cannot drive: sync leaves it out, fetch refuses it, and a launch
fails, each saying which package upgrade is needed. Once a sync has seen such a
build, every launch warns that the package needs upgrading.
A development checkout (installed from the repository, not from PyPI) is
paired with nothing and follows its channel, official/stable by default.
Development
From the repository root:
python3 -m venv .venv
.venv/bin/pip install -r ci/requirements.txt -e 'python[geoip]'
.venv/bin/python python/scripts/pin-fpgen-model.py
.venv/bin/python -m ci.run_pythonlib
ci.run_pythonlib runs python/tests/, the same job CI runs. Which suite covers
which change is in AGENTS.md.
Licence
MIT (LICENSE). The browser itself is MPL-2.0.