| name | cloakbrowser |
| description | Stealth Chromium browser automation that bypasses bot detection. Use this skill whenever the user wants to scrape, screenshot, PDF, or automate a site that blocks normal headless browsers — Cloudflare Turnstile, reCAPTCHA v3, FingerprintJS, ShieldSquare, BrowserScan, "Access Denied" responses, suspicious 403/429s on plain `curl`, or any site where Playwright/Puppeteer get caught. Also use when the user mentions CloakBrowser, stealth Chromium, anti-bot bypass, "headless detection", "real Chrome fingerprint", or wants a one-off "what does this page actually render" check. Prefer this skill over raw `curl`/`fetch` for any site behind a CDN or bot-detection layer. |
| homepage | https://github.com/CloakHQ/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
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
$SK/fetch.py https://example.com --text
$SK/fetch.py https://example.com --selector "h1"
$SK/fetch.py https://protected.example --humanize
$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
$SK/serve.sh --port 9222
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).
