# CloakBrowser

> Stealth Chromium browser with source-level C++ fingerprint patches that passes bot detection tests — a drop-in Playwright/Puppeteer replacement for Python and JavaScript.

CloakBrowser is an open-source stealth Chromium browser built by CloakHQ that modifies browser fingerprints at the C++ source level rather than through JavaScript injection or config flags. It ships as a thin Python and JavaScript wrapper around a custom-compiled Chromium binary, making it a drop-in replacement for Playwright and Puppeteer with the same API. The project is MIT-licensed (wrapper code) and freely available on GitHub and PyPI/npm.

## What It Is

CloakBrowser is a browser automation tool in the anti-detect / stealth browser category. Its core job is to make automated Chromium sessions indistinguishable from real human browser sessions, preventing bot detection systems from blocking or challenging automated scripts. Unlike tools such as `playwright-stealth` or `undetected-chromedriver` that inject JavaScript or tweak launch flags, CloakBrowser patches Chromium's C++ source code directly — meaning fingerprint modifications are compiled into the binary itself. The project's README states it passes tests against Cloudflare Turnstile, FingerprintJS, BrowserScan, ShieldSquare, and reCAPTCHA v3 (scoring 0.9, described as human-level).

## How the Source-Level Patching Works

The binary ships with 57 fingerprint patches (as of Chromium 146) covering canvas, WebGL, audio, fonts, GPU, screen properties, WebRTC, network timing, hardware reporting, automation signal removal, and CDP input behavior. Key behaviors:

- **No JavaScript injection** — patches are compiled into the binary, not applied at runtime
- **Auto-generated fingerprint seed** — every launch produces a fresh, coherent random identity with no configuration required
- **`humanize=True` flag** — replaces all Playwright/Puppeteer mouse, keyboard, and scroll calls with Bézier-curve movements, per-character typing timing, and realistic scroll patterns
- **Native SOCKS5 proxy support** — `proxy="socks5://user:pass@host:port"` works directly in all launch functions
- **GeoIP auto-detection** — `geoip=True` resolves timezone and locale from the proxy exit IP

The binary auto-downloads on first run (~200MB, cached locally) and is verified with SHA-256 checksums. Background update checks keep it current.

## Platform and Deployment Support

CloakBrowser supports Linux x86_64, Linux arm64, macOS arm64 (Apple Silicon), macOS x86_64 (Intel), and Windows x86_64. It can be used locally, in Docker, or on a VPS with identical behavior across environments. A pre-built Docker image (`cloakhq/cloakbrowser`) is available on Docker Hub with required fonts pre-installed. The `cloakserve` CDP multiplexer mode allows running a persistent stealth browser container that accepts remote connections with per-connection fingerprint seeds via query parameters.

## Framework Integrations

CloakBrowser is designed to integrate with the broader browser automation and AI agent ecosystem. The README lists integration examples for:

- **browser-use**, **Crawl4AI**, **Scrapling**, **Crawlee** (Python AI/scraping frameworks)
- **Stagehand**, **LangChain** (TypeScript/Python AI agent frameworks)
- **Selenium**, **undetected-chromedriver** (legacy automation)
- **AWS Lambda** (serverless deployment via container image)

Both Playwright (recommended) and Puppeteer backends are supported, with the README noting that Playwright is preferred for reCAPTCHA Enterprise due to lower CDP protocol leakage.

## Update: v0.3.26 (Chromium 146.0.7680.177.4)

The latest release, published April 28, 2026, upgrades the Chromium base from 145 to 146 and expands the patch count from 49 to 57. Notable additions in recent releases include:

- `launch_context_async()` — async counterpart to `launch_context()`
- Native SOCKS5 proxy support with QUIC/HTTP3 tunneling via UDP ASSOCIATE
- WebRTC IP spoofing via `--fingerprint-webrtc-ip=auto`
- Proxy signal removal (DNS/connect/SSL timing zeroed, proxy cache headers stripped)
- `cloakserve` CDP multiplexer rewritten as a multi-connection proxy with per-connection fingerprint seeds
- Patchright backend option for suppressing additional CDP automation signals

The GitHub repository shows 8,209 stars and 600 forks as reported by the project's own About page, with active maintenance and community contributions.

## Features
- 49–57 source-level C++ patches on Chromium binary
- Drop-in Playwright and Puppeteer replacement (Python + JavaScript)
- humanize=True flag for human-like mouse, keyboard, and scroll behavior
- Auto-generated random fingerprint seed per launch
- Native HTTP and SOCKS5 proxy support
- GeoIP auto-detection for timezone and locale from proxy exit IP
- WebRTC IP spoofing
- Persistent browser profiles with cookie/localStorage persistence
- cloakserve CDP multiplexer for multi-connection stealth browser server
- Per-connection fingerprint seeds via CDP query parameters
- Auto-downloading and auto-updating stealth Chromium binary
- SHA-256 checksum verification for binary downloads
- Docker image with pre-installed fonts
- CLI for binary management (install, update, info, clear-cache)
- Patchright backend option for additional CDP signal suppression
- reCAPTCHA v3 score 0.9 (human-level, server-verified)
- Passes Cloudflare Turnstile, FingerprintJS, BrowserScan
- Fingerprint flags for GPU, screen, hardware, fonts, storage quota
- AWS Lambda deployment support
- Browser Profile Manager (self-hosted, separate Docker image)

## Integrations
Playwright, Puppeteer, browser-use, Crawl4AI, Crawlee, Scrapling, Stagehand, LangChain, Selenium, undetected-chromedriver, Docker, AWS Lambda, Patchright, Chrome DevTools Protocol (CDP)

## Platforms
WINDOWS, MACOS, LINUX, WEB, API, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Version
chromium-v146.0.7680.177.4

## Links
- Website: https://cloakbrowser.dev/
- Documentation: https://github.com/CloakHQ/CloakBrowser
- Repository: https://github.com/CloakHQ/CloakBrowser
- EveryDev.ai: https://www.everydev.ai/tools/cloakbrowser