playwright-stealth-setup

Get the CloakBrowser stealth-browsing toolchain installed and verified on this machine, idempotently: probe what is present, then install only what is missing. CloakBrowser is a Chromium fork with fingerprint patches applied at the C++ source level, driven through Playwright — you install a pip wrapper, then download its patched browser binary separately.

Authorized use only. This toolchain is for automating properties you own or are authorized to test, and for lawful, privacy-respecting browsing. Respect Terms of Service and robots.txt; no fraud, credential abuse, mass account creation, or evading access controls you have no right to bypass. Full policy in references/toolchain.md.

When to use / when NOT to use

Use when the environment is missing or broken: cloakbrowser not importable, the binary not downloaded, a failing launch test, macOS refusing to open the app, a licence key to add, or "get the stealth env ready". Not for running a browsing task, creating an identity, or resuming a session — that is the playwright-stealth skill, which installs nothing.

Workflow

Run everything through the bundled script. It is the deterministic gate.

Probe first — no changes. See what already exists before touching anything:
```
python3 "${CLAUDE_SKILL_DIR}/scripts/setup_check.py"
```
Read the STATUS <component>: OK|MISSING|WARN|FAIL|SKIP lines and the final RESULT:. python, cloakbrowser_pkg, binary and launch are required; geoip_extra is advisory and never fails the run. --json gives machine-readable output. --quick gives a fast, fully offline component list but can never return RESULT: ok — it skips the launch test, and an unexecuted binary is not a verified install. Use the plain form for the gate.
Install what is missing. Only if step 1 reported RESULT: fail:
```
python3 "${CLAUDE_SKILL_DIR}/scripts/setup_check.py" --install
```
This runs pip install -U 'cloakbrowser[geoip]', then python -m cloakbrowser install (~200 MB on first run), then clears the macOS Gatekeeper quarantine, then re-probes. It skips anything already OK.
Add a licence key if the user wants a newer binary (optional — the toolchain works without one):
```
python3 -m cloakbrowser login          # GitHub sign-in for a free key, or paste a paid key
```
Or export CLOAKBROWSER_LICENSE_KEY in the shell. Never write the key into a file in the repository, and never pass it as a visible command-line argument. Re-run step 1 afterwards — the binary version and license.tier should change.
Verify and report. Re-run step 1 and require RESULT: ok. Report to the user: the wrapper version, the Chromium version that will actually launch, and the licence tier — all read from the live diagnostic, never from documentation. Do not launch a browsing session or create an identity here.

If a required step fails, read the FAIL/MISSING detail and fix the root cause using the troubleshooting table in references/toolchain.md. Never edit the script to get past the gate, and never report success from a RESULT: fail.

What "done" looks like

setup_check.py prints STATUS binary: OK chromium <version> (licence tier: <tier>), STATUS launch: OK, and RESULT: ok (exit 0).
You reported the resolved Chromium version and licence tier, and named the trust boundary below in one or two sentences.
No browser session was started and no .stealth/ identity was created.

Gotchas

cloakbrowser info exits 0 even when nothing is installed. binary.installed can be false on a successful exit. The script reads the JSON, not the exit code — so should you if you ever probe by hand.
The binary is licence-gated, the wrapper is not. MIT covers the Python wrapper only. Without a key you get the pinned public build for your platform, which on macOS trails current Chrome by several major versions. cloakbrowser login (free, GitHub sign-in) moves you to the latest Stable build.
The Chromium sandbox is disabled. --no-sandbox is part of the wrapper's default stealth args and cannot be removed without stealth_args=False, which would turn off every fingerprint patch. Combined with an old free-tier binary, a renderer exploit lands on the host. Say this to the user; do not bury it.
macOS quarantines the binary. It is ad-hoc signed, so the first launch fails with "app is damaged". --fix-quarantine clears it with xattr -cr scoped to ~/.cloakbrowser/, and only after cloakbrowser install has already verified the download against a pinned Ed25519 signature — the Gatekeeper flag is cleared on a file whose publisher is authenticated, not on an arbitrary download. This is also the usual cause of a launch: FAIL on a fresh Mac.
You do not need playwright install chromium. CloakBrowser downloads its own binary. On Linux you may still need playwright install-deps chromium.
Python ≥ 3.11 is required because the identity format is read with stdlib tomllib. Fix the interpreter; do not add a TOML backport.
Vendor benchmark claims are marketing. "Passes every bot detection test" and "0.9 reCAPTCHA v3" are unreproduced. Report what the diagnostic says, nothing more.
Binaries drift. After any wrapper or binary upgrade, the playwright-stealth canary will report fingerprint drift against its baseline — that is correct behaviour and needs a reviewed re-baseline, not a suppressed check.

References

references/toolchain.md — install matrix, the cloakbrowser info JSON contract, licence tiers, macOS Gatekeeper, the full trust boundary, version pinning and rollback, troubleshooting, cleanup, authorized use.