cloakbrowser

CloakBrowser

A patched-source Chromium plus a Playwright-shaped Python wrapper. Fingerprints are modified at the C++ level (canvas, WebGL, audio, fonts, WebRTC, TLS, CDP input, navigator.webdriver, plugin list, window.chrome, …) so detection services see a real browser because it is a real browser — no JS shim that breaks on the next Chrome upgrade.

Install state on this VPS

Already installed:

• cloakbrowser CLI lives at /home/node/.local/bin/cloakbrowser in the stable OpenClaw container image.
• Stealth Chromium binary lives at /home/node/.cloakbrowser/chromium-<version>/chrome.
• Wrapper Python is exposed through /usr/local/bin/cloakbrowser-python; the bundled scripts use this stable wrapper so they work even when Codex sets HOME to an isolated session directory.

If a fresh checkout or a new machine needs setting up:

uv tool install cloakbrowser
cloakbrowser install        # downloads the ~206 MB Chromium binary

The cloakbrowser CLI only manages the binary (install, info, update, clear-cache). It is not a scraper — for that, use the scripts in this skill or write inline Python.

Decision tree — pick the right tool

Always reach for a bundled script first. They use argparse, take --humanize, --proxy, --geoip, --wait, etc. — most needs are covered.

Bundled scripts

All scripts are executable (#! already points at the right Python). Invoke them by absolute path:

The pattern is consistent: positional URL (and OUTPUT where relevant), then optional flags --humanize, --proxy, --geoip, --wait, --timeout.

Inline Python — for everything the scripts don't cover

For multi-step flows (login, fill a form, click through, conditional waits), write a one-off script. Use the uv tool venv's interpreter:

The API is identical to Playwright's sync API — anything in the Playwright docs works here. The only differences:

• from cloakbrowser import launch (not from playwright.sync_api)
• Skip sync_playwright().start() — launch() is a top-level function
• All stealth flags (humanize, proxy, geoip, auto_update) go on launch(), not the page

For persistent sessions, use launch_persistent_context(user_data_dir).

When to load references/stealth-knobs.md

Read it when:

• A target blocks despite stealth (covers humanize / proxy / persistent profile escalation order).
• The user asks about proxies, residential vs datacentre, geo matching.
• You need to share one browser across many tool calls (CDP server mode).

For routine "fetch this URL" / "screenshot this page" work, the table and script examples above are enough — don't load the reference.

Anti-patterns

• Don't pip install cloakbrowser system-wide. PEP 668 blocks it on this VPS. Use uv tool install cloakbrowser (already done).
• Don't run playwright install — CloakBrowser ships its own Chromium and doesn't use Playwright's bundled binaries.
• Don't import cloakbrowser from the system Python — it lives in the uv tool venv only. Use the venv's Python, or the bundled scripts.
• Don't enable humanize=True for plain scraping of unprotected sites — it adds latency with no win.
• Don't keep serve.sh running for a one-shot fetch. The CDP server is for shared, long-lived sessions; fetch.py is faster for one URL.

Troubleshooting

• Binary not found / first-run hang → cloakbrowser install.
• ModuleNotFoundError: cloakbrowser → you're on the wrong Python. Use /usr/local/bin/cloakbrowser-python or the bundled scripts (their shebang already points there).
• Slow startup → the binary checks for updates on launch. Pass auto_update=False to launch() (or set CLOAKBROWSER_AUTO_UPDATE=0) to skip.
• Still blocked → see references/stealth-knobs.md for the escalation order (humanize → residential proxy + geoip → persistent profile).