CloakHQ/CloakBrowser

Maintainer? Show your league in your README

Card: your league's emblem, from Copper to Legendary

[![bestofgithub](https://bestofgithub.dev/badge/CloakHQ/CloakBrowser.svg?style=card)](https://bestofgithub.dev/repo/CloakHQ/CloakBrowser)

Flat: fits beside your other badges

[![bestofgithub](https://bestofgithub.dev/badge/CloakHQ/CloakBrowser.svg)](https://bestofgithub.dev/repo/CloakHQ/CloakBrowser)

Loading README…

Detection Service	Stock Playwright	CloakBrowser	Notes
reCAPTCHA v3	0.1 (bot)	0.9 (human)	Pro/current build; server-side verified
Cloudflare Turnstile (non-interactive)	FAIL	PASS	Auto-resolve
Cloudflare Turnstile (managed)	FAIL	PASS	Single click
ShieldSquare	BLOCKED	PASS	Production site
FingerprintJS bot detection	DETECTED	PASS	Pro/current build; demo.fingerprint.com
BrowserScan bot detection	DETECTED	NORMAL (4/4)	browserscan.net
bot.incolumitas.com	13 fails	1 fail	WEBDRIVER spec only
deviceandbrowserinfo.com	6 true flags	0 true flags	`isBot: false`
`navigator.webdriver`	`true`	`false`	Source-level patch
`navigator.plugins.length`	0	5	Real plugin list
`window.chrome`	`undefined`	`object`	Present like real Chrome
UA string	`HeadlessChrome`	`Chrome/151.0.0.0`	No headless leak
CDP detection	Detected	Not detected	`isAutomatedWithCDP: false`
TLS fingerprint	Mismatch	Identical to Chrome	ja3n/ja4/akamai match
		Tested against 50+ detection sites

Feature	Playwright	playwright-stealth	undetected-chromedriver	CloakBrowser
reCAPTCHA v3 score (Pro/current)	0.1	0.3-0.5	0.3-0.7	0.9
Cloudflare Turnstile	Fail	Sometimes	Sometimes	Pass
Headless / Docker detection	Flagged	Flagged	Flagged	Passes
Patch level	None	JS injection	Config patches	C++ (Chromium)
Survives Chrome updates	N/A	Breaks often	Breaks often	Yes
Maintained	Yes	Stale	Stale	Active
Browser engine	Chromium	Chromium	Chrome	Chromium
Playwright API	Native	Native	No (Selenium)	Native

Interaction	Default	With `humanize=True`
Mouse movement	Instant teleport	Bézier curve with easing and slight overshoot
Clicks	Instant	Realistic aim point + hold duration
Keyboard	Instant fill	Per-character timing, thinking pauses, occasional typos with self-correction
Scroll	Jump	Accelerate → cruise → decelerate micro-steps
`fill()`	Instant value set	Clears existing content, types character by character

Env Variable	Default	Description
`CLOAKBROWSER_BINARY_PATH`	—	Skip download, use a local Chromium binary
`CLOAKBROWSER_CACHE_DIR`	`~/.cloakbrowser`	Binary cache directory
`CLOAKBROWSER_DOWNLOAD_URL`	`cloakbrowser.dev`	Custom download URL for binary
`CLOAKBROWSER_AUTO_UPDATE`	`true`	Set to `false` to disable background update checks
`CLOAKBROWSER_SKIP_CHECKSUM`	`false`	Only applies to a custom `CLOAKBROWSER_DOWNLOAD_URL`: set to `true` to skip its checksum check. Signature verification on the official download path is mandatory and cannot be skipped.
`CLOAKBROWSER_GEOIP_TIMEOUT_SECONDS`	`5`	Max seconds for GeoIP resolution before continuing without it
`CLOAKBROWSER_WIDEVINE_CDM`	—	Path to a sideloaded `WidevineCdm` directory (overrides auto-detection next to the binary). See Widevine / DRM
`CLOAKBROWSER_WIDEVINE`	`1`	Set to `0` to disable automatic Widevine hint-file seeding for persistent contexts
`CLOAKBROWSER_FETCH_WIDEVINE`	`0`	Docker only: set to `1` to auto-fetch the Widevine CDM on container start (Linux x86-64 only). See Widevine / DRM
`CLOAKBROWSER_VERSION`	—	Pin to an exact Chromium version for rollback (e.g. `154.0.8037.57.1`). Paid Pro key only
`CLOAKBROWSER_RELEASE_CHANNEL`	`stable`	Set to `preview` to opt into the Preview binary channel

Scenario	What happens
No flags	Random seed auto-generated at startup. GPU, screen, hardware specs, and all noise patches are spoofed automatically. Fresh identity each launch.
`--fingerprint=seed`	Deterministic identity from the seed. Same seed = same fingerprint across launches. Use this for session persistence (returning visitor).
`--fingerprint=seed` + explicit flags	Explicit flags override individual auto-generated values. The seed fills in everything else.

Flag	Linux/Windows Default	macOS Default	Controls
`--fingerprint`	Random (10000–99999)	Random (10000–99999)	Master seed for canvas, WebGL, audio, fonts
`--fingerprint-platform`	`windows`	`macos`	`navigator.platform`, User-Agent OS, GPU pool selection

Flag	Controls
`--fingerprint-gpu-vendor`	Switch the GPU family — `NVIDIA` or `Intel`. The binary reports the matching Chrome vendor value, `Google Inc. (NVIDIA)` or `Google Inc. (Intel)`. Auto-generated from seed + platform when unset
`--fingerprint-hardware-concurrency`	`navigator.hardwareConcurrency` (auto-generated: `8`)
`--fingerprint-device-memory`	`navigator.deviceMemory` in GB (auto-generated: `8`)
`--fingerprint-screen-width`	Screen width (auto-generated: `1920` Win/Linux, `1440` macOS)
`--fingerprint-screen-height`	Screen height (auto-generated: `1080` Win/Linux, `900` macOS)
`--fingerprint-brand`	Browser brand: `Chrome`, `Edge`, `Opera`, `Vivaldi`
`--fingerprint-brand-version`	Brand version (UA + Client Hints)
`--fingerprint-platform-version`	Client Hints platform version
`--fingerprint-timezone`	Timezone (e.g. `America/New_York`)
`--fingerprint-locale`	Locale (e.g. `en-US`)
`--fingerprint-storage-quota`	Override storage quota in MB — affects `storage.estimate()`, `storageBuckets`, and legacy webkit APIs. Auto-normalized when `--fingerprint` is set
`--fingerprint-taskbar-height`	Override taskbar height (binary defaults: Win=48, Mac=95, Linux=0)
`--fingerprint-windows-font-metrics`	Chromium 148+ binary only (no-op on earlier builds). Align font metrics with the Windows platform when spoofing Windows on Linux — used in the FingerprintJS config. Requires Windows fonts installed (see Font Setup on Linux); no effect without them. On `154.0.8037.57.2` and newer this is on by default when the Windows fonts are installed, so the flag is no longer needed
`--fingerprint-webrtc-ip`	WebRTC ICE candidate IP replacement. Use `auto` to resolve from proxy exit IP (makes an HTTP call through the proxy), or pass an explicit IP. Auto-injected when `geoip=True`
`--fingerprint-noise=false`	Disable noise injection (canvas, WebGL, audio) while keeping the deterministic fingerprint seed active
`--fingerprint=off`	Chromium 148+ binary only. Pass-through debug mode — turns spoofing off and presents the machine's real native fingerprint (keeps only the baseline any Chrome needs). The binary strips the injected seed and `--fingerprint-platform`, so there's no mixed OS profile. Most useful on a genuine Windows machine to check whether an issue is our spoofing or the environment. Accepts `off`/`false`/`0`/`disable`/`disabled`. For a pure pass-through don't combine it with `geoip=True` / explicit timezone / locale — those stay applied.
`--fingerprint-allow-3p-cookies`	Chromium 148+ binary only. Re-enable third-party cookies for embedded flows that need them (reCAPTCHA v3, SSO, some payment challenges). Off by default; turn on only where a login/payment/embedded challenge loads but never finishes.
`--fingerprint-sapi-voices=false`	Chromium 150+ binary only. Opt out of the Windows speech-voice tables when spoofing Windows. On by default (the voice set matches a real Chrome install); turn off only if a target reacts badly to the Windows voice list.
`--license-route=auto\|direct\|proxy`	Chromium 154.0.8037.57.2+ on Linux, 155+ on all platforms. How the Pro license and session calls leave the browser. `auto` (default): direct to cloakbrowser.dev first, and one retry through your `--proxy-server` if direct can't reach it. `direct`: never through the proxy. `proxy`: only through the proxy (needs `--proxy-server`).
`--license-through-proxy`	Chromium 148+ binary only (all platforms). Route the Pro license/session calls through your `--proxy-server` instead of direct to cloakbrowser.dev. Off by default (these calls go direct, so they never spend proxy bandwidth or touch your scraping session). On `154.0.8037.57.2` and newer, use `--license-route=proxy`; this older spelling still works.
`--fingerprint-transparent-proxy`	Chromium 151+ binary only. A stronger way of connecting through your `--proxy-server`, for sites and providers that block every proxy you try. Off by default; enable it alongside `--proxy-server`.
`--fingerprint-transparent-proxy-dns=<url>\|local`	Chromium 155.0.8059.39.1+ binary only, Linux and Windows. DNS for `--fingerprint-transparent-proxy` mode. By default sites are resolved with Cloudflare's DNS over HTTPS, sent through your proxy. Pass your own DNS over HTTPS address, or `local` to resolve on your own machine as before.
`--fingerprint-portable-cookies`	Chromium 151+ binary only. Encrypt cookies with a machine-independent key so a copied profile keeps its logins across machines. Turn it on from the first launch — it changes how cookies are written, so a cookie is only portable if this was set when it was saved.
`--enable-blink-features=FakeShadowRoot`	Access closed shadow DOM elements

Framework	Stars	Language	Example
browser-use	70K	Python	`browser_use_example.py`
Crawl4AI	58K	Python	`crawl4ai_example.py`
Crawlee	8.6K	Python	`crawlee_example.py`
Scrapling	21K	Python	`scrapling_example.py`
Stagehand	21K	TypeScript	`stagehand.ts`
LangChain	100K+	Python	`langchain_loader.py`
Selenium	—	Python	`selenium_example.py`
undetected-chromedriver	12K	Python	`undetected_chromedriver.py`
agent-browser	—	Shell	`agent_browser.sh`

Platform	Free	Pro	Status
Linux x86_64	Chromium 146 (58 patches)	Chromium 155 (87 patches)	✅
Linux arm64 (RPi, Graviton)	Chromium 146 (58 patches)	Chromium 155 (87 patches)	✅
macOS arm64 (Apple Silicon)	Chromium 145 (26 patches)	Chromium 155 (87 patches)	✅
macOS x86_64 (Intel)	Chromium 145 (26 patches)	Chromium 155 (87 patches)	✅
Windows x86_64	Chromium 146 (58 patches)	Chromium 155 (87 patches)	✅

Detection	Cause	Fix
`nodriver` / bad bot	Stale binary/wrapper, missing current FPJS patches, or poor proxy IP reputation	Upgrade to the latest Pro binary for your platform, use a residential proxy with `geoip=True`, and use the config below.
Browser tampering	Noise injection detected by ML	`--fingerprint-noise=false`
Browser tampering (fonts)	Font metrics don't match the spoofed Windows platform	`--fingerprint-windows-font-metrics` (Chromium 148+ binary; requires Windows fonts installed)
Virtual machine	Screen dimensions don't match viewport	`--fingerprint-screen-width/height` matching viewport

Stealth Chromium that passes every bot detection test.

Install

Latest: v0.6.4 — 87 source-level stealth patches (Chromium 155.0.8059.39.1)

Why CloakBrowser?

CloakBrowser Pro

CloakBrowser Manager

Test Results

Proof

Comparison

How It Works

API

launch()

launch_async()

launch_context()

launch_context_async()

launch_persistent_context()

Widevine / DRM

CLI

Utility Functions

JavaScript / Node.js API

Playwright (default)

Puppeteer

Utility Functions (JS)

Human Behavior

Configuration

Fingerprint Management

Default Fingerprint

Additional Flags

Font Setup on Linux

Examples

Examples

Framework Integrations

Deployment Integrations

Platforms

Docker

Quick test

Run a script

CDP server mode

Docker Compose

Extend with your own image

Troubleshooting

Still getting blocked on aggressive sites (DataDome, Turnstile)?

Recommended config for anti-bot sites

Detected by FingerprintJS?

Blocked on Kasada / Akamai sites despite correct config?

Sites challenge fresh sessions but work after first visit

Something not working? Make sure you're on the latest version

Preview release channel

New update broke something? Roll back

macOS: "App is damaged" or Gatekeeper blocks launch

"playwright install" vs CloakBrowser binary

Site detects incognito / private browsing mode

reCAPTCHA v3 scores are low (0.1–0.3)

FAQ

Links

Security

License

Contributing

Contributors

Star History

`launch()`

`launch_async()`

`launch_context()`

`launch_context_async()`

`launch_persistent_context()`