Guide · Open source
How to use CloakBrowser: install and run it with Playwright
Updated · written with AI from the project's own documentation and checked against our catalogue data
CloakBrowser is an open-source build of Chromium with browser fingerprint details changed at the source-code level, so sites are less likely to flag it as automated. It is designed to be used through the Playwright or Puppeteer API, so existing automation code needs only a small import change. This guide shows you how to install it, run a first script, and add proxy and humanize settings for sites with bot protection.
CloakBrowserCloakHQ/CloakBrowser · ★ 32.7k · MIT Install options & downloads Quick start
- 1Install the package. Run pip install cloakbrowser in your Python environment. The package is on PyPI.
- 2Let the binary download. On first run, the stealth Chromium binary downloads automatically (about 200MB) and is cached locally.
- 3Run a basic launch. Import launch from cloakbrowser, open a page, navigate to a URL, and close the browser.
- 4Swap in your existing code. If you use Playwright, replace the Playwright launch lines with launch() and keep the rest of your script.
- 5Add a residential proxy. Pass your own residential proxy URL to launch with the proxy argument, since rotation is not built in.
- 6Enable humanize and geoip. Set humanize=True for human-like input and geoip=True to match timezone and locale to the proxy IP.
What you need before you install CloakBrowser
CloakBrowser is a Python and JavaScript package, so you need to be comfortable writing code in one of those languages. The README requires Python but does not state a minimum Python version, so check the project page before you start.
The README says you must bring your own proxies, and it does not include CAPTCHA solving. It is not a no-code tool.
- Python (the README does not state a version)
- Basic comfort with Playwright or Puppeteer, or willingness to learn it
- Optional: a residential proxy for sites with anti-bot protection
Install CloakBrowser with pip
Install the Python package with pip. On first run, the stealth Chromium binary is downloaded automatically (about 200MB) and cached locally, so you do not need to configure a browser separately.
If you want the timezone and locale to be detected automatically from your proxy IP, install the optional geoip extra.
- JavaScript users can run npm install cloakbrowser playwright-core, or npm install cloakbrowser puppeteer-core for Puppeteer.
- The README also lists a community-maintained .NET client, dotnet add package CloakBrowser.
pip install cloakbrowserRun your first script
The Python example launches the browser, opens a page, and closes it. The API mirrors Playwright, so you call new_page() and goto() as you normally would.
To try the tool without installing anything, the README shows a Docker command that runs a built-in test.
from cloakbrowser import launch
browser = launch()
page = browser.new_page()
page.goto("https://example.com")
browser.close()Switch an existing Playwright script to CloakBrowser
If you already use Playwright, the README describes a one-line change. You replace the Playwright launch code with the CloakBrowser launch call, and the rest of your code is meant to work unchanged.
- Replace the sync_playwright() setup and pw.chromium.launch() with launch() from cloakbrowser.
- Keep your page.goto() and other calls as they are.
- from playwright.sync_api import sync_playwright
- pw = sync_playwright().start()
- browser = pw.chromium.launch()
+ from cloakbrowser import launch
+ browser = launch()
page = browser.new_page()
page.goto("https://example.com")Add proxy, geoip, and humanize settings for protected sites
For sites with anti-bot protection, the README suggests adding a residential proxy and several flags. The proxy should be a residential IP rather than a datacenter IP. The geoip flag matches timezone and locale to the proxy IP. The README notes that some sites detect headless mode even with the C++ patches, so it sets headless to False. The humanize flag adds human-like mouse, keyboard, and scroll behavior.
The README also says that SOCKS5 proxies work directly with proxy="socks5://..." in the launch functions.
- proxy: your own residential proxy URL, since CloakBrowser has no built-in proxy rotation
- geoip: True to match timezone and locale to the proxy IP (requires the geoip extra for auto-detection)
- headless: False, because some sites detect headless mode
- humanize: True for human-like mouse curves, keyboard timing, and scrolling
browser = launch(
proxy="http://user:pass@residential-proxy:port", # residential IP, not datacenter
geoip=True, # match timezone + locale to proxy IP
headless=False, # some sites detect headless even with C++ patches
humanize=True, # human-like mouse, keyboard, scroll
)Use CloakBrowser with Puppeteer
The README says CloakBrowser also works with Puppeteer. You import launch from the puppeteer path of the JavaScript package. The README links to a details section for this setup, which this guide does not reproduce.
import { launch } from 'cloakbrowser/puppeteer'Know what CloakBrowser does not do
CloakBrowser does not solve CAPTCHAs. The README says it prevents them from appearing and does not include solving services. It also has no built-in proxy rotation, so you must supply your own proxies. If you need either of these, plan for a separate tool.
The README compares CloakBrowser with playwright-stealth, undetected-chromedriver, and puppeteer-extra, which it describes as injecting JavaScript or tweaking flags. It argues that source-level patches are harder for antibot systems to detect, but this is the project's own claim.
- No CAPTCHA solving services included
- No built-in proxy rotation
- Requires writing Python or JavaScript
What people use it for
- Web scraping on sites protected by Cloudflare Turnstile or similar anti-bot systems, paired with a residential proxy
- Browser automation for Python or JavaScript projects already built on Playwright
- AI agents that drive a real browser and run into bot detection
- Passing bot checks such as FingerprintJS and BrowserScan, according to the README's test claims
Frequently asked questions
Is CloakBrowser free?
The README describes a free build and a paid CloakBrowser Pro tier, which includes the latest Stable build and license-key setup. The project is MIT licensed. Check the project page for current licence and plan details before you rely on a specific tier.
How do I install CloakBrowser?
For Python, run pip install cloakbrowser. The stealth Chromium binary downloads automatically on first run, about 200MB, and is cached locally.
Does CloakBrowser solve CAPTCHAs?
No. The README says CloakBrowser prevents CAPTCHAs from appearing and does not include CAPTCHA-solving services.
Does CloakBrowser include proxy rotation?
No. The README says you must bring your own proxies. It recommends residential proxies for sites with anti-bot protection.
Is CloakBrowser an alternative to playwright-stealth or undetected-chromedriver?
Yes, it is an alternative for the same goal of avoiding bot detection. The README argues that config-level tools like playwright-stealth, undetected-chromedriver, and puppeteer-extra break on Chrome updates, while CloakBrowser patches Chromium source code. That comparison comes from the project itself, so test it on your target sites.
Can I use CloakBrowser without writing code?
No. The README says it requires writing Python or JavaScript, so it is not a no-code tool.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
CloakBrowser suits Python or JavaScript developers who already use Playwright or Puppeteer and need automation that gets past bot checks, especially when paired with a residential proxy. It is a poor fit for people who need automatic CAPTCHA solving, built-in proxy rotation, or a no-code tool, since the README says it offers none of these.
Install options & downloads