cloakbrowser/SKILL.md

---
name: cloakbrowser
description: Stealth browser automation with CloakBrowser — bypasses bot detection (Cloudflare, reCAPTCHA, FingerprintJS). Use for web scraping, screenshot capture, site testing, and anti-detect browsing.
---

# CloakBrowser — Stealth Browser Automation

CloakBrowser is a patched Chromium binary with 58 C++ source-level fingerprint patches. Drop-in Playwright replacement that passes Cloudflare Turnstile, reCAPTCHA v3 (0.9 score), FingerprintJS, BrowserScan, and 30+ detection sites.

## Install

```bash
uv pip install --python /opt/hermes/.venv/bin/python3 /opt/data/workspace/github/cloakbrowser
```

Binary auto-downloads to `~/.cloakbrowser/` on first use.

## Quick Usage (Python)

```python
from cloakbrowser import launch

browser = launch(headless=True, humanize=True)
page = browser.new_page()
page.goto("https://protected-site.com")
print(page.title())
browser.close()
```

## CLI Wrapper

Located at: `/opt/data/workspace/github/cloakbrowser/tools/cloak_browse.py`

```bash
# Fetch page text
python3 /opt/data/workspace/github/cloakbrowser/tools/cloak_browse.py fetch https://example.com

# Screenshot
python3 /opt/data/workspace/github/cloakbrowser/tools/cloak_browse.py screenshot https://example.com -o /tmp/shot.png --viewport 1920x1080

# Extract structured content (title, links, meta, text)
python3 /opt/data/workspace/github/cloakbrowser/tools/cloak_browse.py extract https://example.com

# Execute JS on page
python3 /opt/data/workspace/github/cloakbrowser/tools/cloak_browse.py js https://example.com "document.title"

# Run stealth fingerprint test
python3 /opt/data/workspace/github/cloakbrowser/tools/cloak_browse.py stealth-test

# Show binary info
python3 /opt/data/workspace/github/cloakbrowser/tools/cloak_browse.py info
```

## Key Launch Options

```python
browser = launch(
    headless=True,          # Headless mode (default True)
    humanize=True,          # Human-like mouse/keyboard/scroll
    proxy="http://user:pass@proxy:port",  # Residential proxy
    geoip=True,             # Auto-detect timezone from proxy IP
    args=["--remote-debugging-port=9242"],  # Extra Chrome args
    extension_paths=["/path/to/ext"],       # Load Chrome extensions
)
```

## Integration Patterns

### With Crawl4AI
```python
from cloakbrowser import launch_async
cb = await launch_async(headless=True, args=["--remote-debugging-port=9243"])
# Connect Crawl4AI via CDP: http://127.0.0.1:9243
```

### With browser-use (AI agent)
```python
from cloakbrowser import launch_async
cb = await launch_async(headless=True, args=["--remote-debugging-port=9242"])
# Connect browser-use via CDP: http://127.0.0.1:9242
```

### Persistent context (cookies survive restart)
```python
from cloakbrowser import launch_persistent_context
ctx = launch_persistent_context("./my-profile", headless=False)
page = ctx.new_page()
page.goto("https://site.com")
ctx.close()  # Cookies saved to ./my-profile
```

## Stealth Verified

- navigator.webdriver: False
- Real plugins (5), languages, platform
- WebGL: Google Inc. (NVIDIA) — real GPU vendor
- Canvas fingerprint: unique per session (random seed)
- Passes bot.incolumitas.com, BrowserScan, Cloudflare Turnstile

## Hermes Integration (Default Browser)

CloakBrowser is configured as the default browser for Hermes via `agent-browser` CLI.

**Config file:** `/opt/data/.env`
```
AGENT_BROWSER_EXECUTABLE_PATH=/opt/data/home/.cloakbrowser/chromium-146.0.7680.177.5/chrome
AGENT_BROWSER_ARGS=--no-sandbox,--fingerprint-platform=windows
AGENT_BROWSER_ENGINE=chrome
```

**How it works:**
- Hermes browser tools (`browser_navigate`, `browser_click`, etc.) use `agent-browser` CLI
- `agent-browser` launches Chromium — `AGENT_BROWSER_EXECUTABLE_PATH` points it to CloakBrowser's stealth binary
- `AGENT_BROWSER_ARGS` passes fingerprint spoofing flags
- Result: all Hermes browser automation runs through stealth Chromium

**Verify integration:**
```bash
# Check agent-browser uses CloakBrowser
export AGENT_BROWSER_EXECUTABLE_PATH=/opt/data/home/.cloakbrowser/chromium-146.0.7680.177.5/chrome
agent-browser --engine chrome --session test open "https://example.com"
agent-browser --session test eval "navigator.webdriver"  # Should be false
agent-browser --session test close
```

**Update binary path after CloakBrowser update:**
```bash
python3 -c "from cloakbrowser.config import get_binary_path; print(get_binary_path())"
# Update AGENT_BROWSER_EXECUTABLE_PATH in /opt/data/.env with new path
```

## Pitfalls

1. **Headless detection**: Some sites detect headless even with patches. Use `headless=False` for stubborn sites.
2. **Datacenter IPs**: Residential proxy needed for sites that check IP reputation.
3. **First run downloads ~120MB binary** to `~/.cloakbrowser/`. Subsequent runs use cache.
4. **No pip**: Use `uv pip install --python /opt/hermes/.venv/bin/python3` instead of bare `pip`.
5. **Playwright API**: CloakBrowser returns standard Playwright Browser/Context objects — same API.

## Environment Variables

- `CLOAKBROWSER_BINARY_PATH` — Use custom binary (skip download)
- `CLOAKBROWSER_CACHE_DIR` — Custom cache directory
- `CLOAKBROWSER_AUTO_UPDATE=false` — Disable auto-update checks
- `CLOAKBROWSER_DOWNLOAD_URL` — Custom download mirror