Browser automation is easy to start and hard to make realistic.

Stock Playwright and Puppeteer are excellent tools, but their default browser fingerprints can be obvious in environments that inspect automation signals.

CloakBrowser approaches that problem by wrapping a custom Chromium build rather than only injecting JavaScript patches.

It ships Python and JavaScript APIs, Docker support, humanized interaction helpers, and a CDP multiplexer for automation infrastructure.

This is a powerful dual-use category, so the framing matters. Use tools like this only for systems you own, are paid to test, or have explicit permission to automate. The interesting FOSS angle here is browser engineering, QA, agent browsing, and controlled fingerprint testing, not unauthorized access or abuse.

CloakBrowser is a Python and JavaScript wrapper around a custom Chromium binary designed for stealthier browser automation.

What is CloakBrowser?

CloakBrowser is a drop-in browser automation wrapper for Python and Node.js. The Python side wraps Playwright. The JavaScript side supports Playwright and Puppeteer. The core promise is that you can swap imports while keeping most of your existing automation code.

The difference is the browser binary. Instead of relying only on launch flags or page-level JavaScript patches, CloakBrowser distributes a patched Chromium build. The README describes source-level changes around canvas, WebGL, audio, fonts, GPU, screen values, WebRTC, network timing, automation signals, and CDP behavior.

That architecture makes it different from ordinary “stealth plugin” approaches. The wrapper is small; the browser binary is the important component.

Why This Project is Interesting

  • Familiar APIs: Python users get Playwright-style launch() helpers. Node.js users get Playwright and Puppeteer entrypoints.
  • Docker support: The root Dockerfile installs browser dependencies, builds the JS wrapper, pre-downloads the binary, and exposes a CDP workflow.
  • Humanized actions: Optional wrappers can make mouse, keyboard, and scroll behavior less robotic.
  • Persistent contexts: Profiles can keep cookies, localStorage, extensions, and cache across runs.
  • Binary management: The package includes install, info, update, and clear-cache commands.
  • Automation infrastructure: cloakserve can multiplex CDP connections and start separate browser processes per fingerprint seed.

A Licensing Detail You Should Not Miss

The GitHub repository source is MIT licensed, but the distributed Chromium binary is not simply MIT. BINARY-LICENSE.md applies to the compiled browser binary.

That binary license allows internal personal and commercial use, but it restricts redistribution, repackaging, modification, reverse engineering, and SaaS/OEM-style use without a separate license. It also contains acceptable-use restrictions.

That does not make the project bad. It makes the licensing precise. But if you plan to bake the binary into your own distributed product, container image, hosted browser service, or third-party automation platform, read the binary license first.

Tech Overview of CloakBrowser

The repository is mostly Python and TypeScript:

  • cloakbrowser/ contains the Python wrapper.
  • js/ contains the TypeScript package.
  • bin/cloakserve exposes a CDP multiplexer.
  • bin/cloaktest runs the container test helper.
  • Dockerfile builds a ready-to-run container.
  • examples/ includes Python and integration examples.
  • tests/ and js/tests/ cover launch behavior, proxy handling, GeoIP, Widevine, extensions, humanized behavior, and stealth regressions.

The cloned repo had 35 Python/TypeScript/MJS test files. That is a good sign for a wrapper project because many failures happen at integration edges: proxy credentials, browser paths, platform detection, persistent profiles, extension loading, and update behavior.

Python Usage

The basic Python API is intentionally small:

from cloakbrowser import launch

browser = launch()
page = browser.new_page()
page.goto("https://example.com")
print(page.title())
browser.close()

The wrapper resolves the browser binary, builds Chromium args, starts Playwright, and returns a normal Playwright Browser object.

For persistent profiles:

from cloakbrowser import launch_persistent_context

ctx = launch_persistent_context("./chrome-profile", headless=False)
page = ctx.new_page()
page.goto("https://example.com")
ctx.close()

That path is useful when you want a real profile folder with cookies, localStorage, extensions, cache, and browsing state. It is also the path where the project handles Widevine hint-file seeding when a Linux Widevine CDM is sideloaded.

JavaScript Usage

The JavaScript package exports Playwright helpers by default:

import { launch } from 'cloakbrowser';

const browser = await launch();
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
await browser.close();

For Puppeteer:

import { launch } from 'cloakbrowser/puppeteer';

The JS package also exposes utility functions such as ensureBinary, clearCache, binaryInfo, and checkForUpdate.

Running CloakBrowser with Docker

CloakBrowser is not a classic self-hosted web app, but it does have a useful container workflow.

The project’s Dockerfile:

  • Starts from Python 3.12 slim.
  • Installs Chromium system libraries and Node.js.
  • Installs the Python wrapper with serve and geoip extras.
  • Builds the TypeScript package.
  • Pre-downloads the stealth Chromium binary.
  • Adds cloaktest and cloakserve.
  • Uses Xvfb for headed browser support.
  • Exposes port 9222.

For a quick controlled test:

docker run --rm cloakhq/cloakbrowser cloaktest

For CDP-style infrastructure, cloakserve exposes a browser control endpoint. Treat that endpoint like a privileged control plane. Keep it on localhost or behind private network controls; do not expose CDP publicly.

Docker Security Notes

CDP can control browser sessions. If an attacker can reach an exposed CDP endpoint, they may be able to drive the browser, inspect pages, or interact with internal services reachable from the container.

Use private networking, firewall rules, authentication at the outer layer, and isolated profiles. Do not bind this directly to the public internet.

Humanized Interaction Layer

One notable feature is humanize=True. When enabled, CloakBrowser patches interaction methods so automation does not behave like instant machine input.

The README describes:

  • Mouse curves and easing.
  • Realistic click aim points and hold duration.
  • Per-character typing delays.
  • Scroll acceleration and deceleration.
  • Optional presets like default and careful.

This is one of those areas where the legitimate use case is controlled testing. It can help you understand how your own detection stack, QA environment, or browser-agent workflow behaves when input is less synthetic. It should not be used to abuse systems or bypass protections where you do not have authorization.

Configuration and Binary Cache

The Python config layer supports environment variables such as:

  • CLOAKBROWSER_BINARY_PATH to use a local Chromium binary instead of downloading one.
  • CLOAKBROWSER_CACHE_DIR to change the binary cache path.
  • CLOAKBROWSER_DOWNLOAD_URL to use a custom download source.
  • CLOAKBROWSER_AUTO_UPDATE to control update checks.
  • CLOAKBROWSER_SKIP_CHECKSUM to skip checksum verification.
  • CLOAKBROWSER_WIDEVINE_CDM and CLOAKBROWSER_WIDEVINE for Widevine behavior.

The default cache location is ~/.cloakbrowser/. On first run, the binary download is large enough that you should account for it in CI, Docker builds, and ephemeral runners.

Where I Would Use It

Reasonable use cases:

  • Testing your own bot-detection and browser-fingerprinting assumptions.
  • QA for your own applications when stock automation creates false positives.
  • Agent-browser experiments in controlled environments.
  • Internal automation where you have permission and need realistic browser behavior.
  • Comparing browser fingerprints across environments.

Risky or inappropriate use cases:

  • Credential stuffing.
  • Automated account creation without authorization.
  • Circumventing authentication or access controls.
  • Collecting data from systems where automation is prohibited.
  • Offering the binary as part of a hosted third-party browser service without checking the binary license.

Conclusion

CloakBrowser is an interesting FOSS-adjacent browser automation project because it does more than wrap Playwright.

It combines a patched Chromium binary, Python and TypeScript APIs, binary management, Docker workflows, humanized actions, persistent profiles, and CDP serving.

If you only need reliable rendered-page automation, authenticated sessions, screenshots, or DOM capture, start with the plain Playwright workflow . CloakBrowser becomes relevant when the browser runtime and fingerprint behavior are the actual problem you are studying in an authorized environment.

The two things to remember are practical. First, this is a dual-use tool, so use it only in authorized contexts. Second, the source wrapper and the distributed browser binary do not have the same license terms.

If you are building internal QA, browser-agent experiments, or fingerprint testing infrastructure, CloakBrowser is worth studying. If you plan to redistribute or serve the binary to customers, read the binary license before you build around it.

FAQ

Is CloakBrowser self-hosted?
Not in the usual app-server sense. It is a browser automation runtime. You can run it in Docker and expose CDP internally, but it is not a web app like Nextcloud or Gitea.
Is the whole project MIT licensed?
No. The wrapper source code is MIT licensed, but the compiled Chromium binary has a separate CloakBrowser Binary License with redistribution and SaaS/OEM restrictions.
Does CloakBrowser solve CAPTCHAs?

The project says it does NOT solve CAPTCHAs.

Its goal is to make the browser environment look less like stock automation. Use it for authorized testing and internal automation, not for abusing third-party services.