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

Task	Use
Get the HTML or visible text of a page	scripts/fetch.py
Save a PNG of a page or element	scripts/screenshot.py
Render a page to PDF	scripts/pdf.py
Run a JS expression against a page and get JSON back	scripts/eval-js.py
Confirm stealth is working	scripts/check-stealth.py
Long-lived browser shared across many tool calls / skills	scripts/serve.sh + CDP
Multi-step interactive flow (login, click, type, conditional)	Inline Python — see below

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:

SK=/root/.openclaw/skills/cloakbrowser/scripts

$SK/fetch.py https://example.com                       # full HTML on stdout
$SK/fetch.py https://example.com --text                # visible text only
$SK/fetch.py https://example.com --selector "h1"       # scoped to a selector
$SK/fetch.py https://protected.example --humanize      # behavioural stealth
$SK/fetch.py https://geo.example --proxy socks5://u:p@host:1080 --geoip

$SK/screenshot.py https://example.com /tmp/out.png --full
$SK/screenshot.py https://example.com /tmp/hero.png --selector ".hero"
$SK/screenshot.py https://example.com /tmp/m.png --viewport 390x844

$SK/pdf.py https://example.com /tmp/page.pdf --format A4
$SK/pdf.py https://example.com /tmp/wide.pdf --landscape

$SK/eval-js.py https://news.example "Array.from(document.querySelectorAll('h2')).map(h=>h.innerText)"
$SK/eval-js.py https://example.com  "({ua: navigator.userAgent, w: innerWidth})"

$SK/check-stealth.py        # JSON report + exit 0 if all 4 stealth tells pass

$SK/serve.sh --port 9222    # starts cloakserve in background; logs /tmp/cloakserve.log

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:

CB_PY=/usr/local/bin/cloakbrowser-python

"$CB_PY" - <<'PY'
from cloakbrowser import launch
b = launch(headless=True, humanize=True)
p = b.new_page()
p.goto("https://example.com/login", wait_until="domcontentloaded")
p.fill("#email", "me@example.com")
p.fill("#password", "…")
p.click("button[type=submit]")
p.wait_for_url("**/dashboard**")
print(p.title())
b.close()
PY

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).