camoufox-stealth-browser

Category: Tools & Productivity | Uploader: kesslerio | Downloads: 0 | Version: v1.0（Latest）

Stealth browser automation with Camoufox for hostile sites that block standard Playwright or Selenium flows. Browser workflows prefer camoufox-nixos on NixOS hosts and fall back to distrobox plus pybox on compatible Linux setups. Use when Cloudflare, Datadome, Airbnb, Yelp, or similar anti-bot targets require persistent login and session reuse. Browser lane only; API helpers are secondary.

Changelog: Source: GitHub https://github.com/kesslerio/camoufox-stealth-browser-clawhub-skill

Directory Structure

Current level: tree/main/

📁 docs/
- 📁 plans/
  - 📄 2026-04-19-001-refactor-stealth-browser-skillcraft-followup-plan.md 16.6 KB
📁 references/
- 📄 fingerprint-checks.md 6.4 KB
- 📄 gotchas.md 2.3 KB
- 📄 proxy-setup.md 3.9 KB
📁 scripts/
- 📄 camoufox-fetch.py 8.2 KB
- 📄 camoufox-session.py 14.9 KB
- 📄 curl-api.py 5.1 KB
- 📄 lint-skill.sh 1.7 KB
- 📄 runtime_support.py 5.1 KB
- 📄 setup.sh 2.3 KB
- 📄 test-discovery.sh 1.6 KB
📁 tests/
- 📁 fixtures/
  - 📄 fake_camoufox_nixos.py 2.7 KB
  - 📄 fake_distrobox.sh 593 B
- 📄 camoufox-fetch-adapter.sh 1.6 KB
- 📄 camoufox-session-adapter.sh 2.2 KB
- 📄 discovery-cases.txt 379 B
- 📄 runtime-selection.sh 1008 B
📄 .gitignore 36 B
📄 LICENSE 10.5 KB
📄 README.md 2.6 KB
📄 SKILL.md 7.3 KB
📄 VERSION 6 B

SKILL.md

---
name: camoufox-stealth-browser
homepage: https://github.com/kesslerio/camoufox-stealth-browser-clawhub-skill
description: Stealth browser automation with Camoufox for hostile sites that block standard Playwright or Selenium flows. Browser workflows prefer camoufox-nixos on NixOS hosts and fall back to distrobox plus pybox on compatible Linux setups. Use when Cloudflare, Datadome, Airbnb, Yelp, or similar anti-bot targets require persistent login and session reuse. Browser lane only; API helpers are secondary.
metadata:
  openclaw:
    emoji: "🦊"
    requires:
      bins: []
      env: []
---

# Camoufox Stealth Browser 🦊

Camoufox is the hostile-site browser lane. Use it when standard Playwright or Selenium flows get blocked and you need a real stealth browser session rather than generic automation.

## Why Camoufox

| Approach | Patch level | Typical weakness |
|----------|-------------|------------------|
| **Camoufox** | Browser/runtime | Harder to fingerprint with timing and JS consistency checks |
| undetected-chromedriver | JS/runtime glue | Timing and environment mismatches |
| puppeteer-stealth | JS injection | Patches land after page startup |
| playwright-stealth | JS injection | Same class of weakness |

## Runtime Selection

The skill now uses this order for **browser** workflows:

1. `camoufox-nixos`
2. `distrobox` with `pybox`
3. clear setup failure if neither exists

The repo still carries a separate `curl_cffi` helper, but it is not the primary routing target for this skill.

## Quick Start

### Browser workflows

The browser scripts self-detect runtime. Use them directly:

```bash
./scripts/camoufox-fetch.py "https://example.com" --headless

./scripts/camoufox-session.py \
  --profile economist \
  --status "https://www.economist.com"
```

Do not frame browser execution as "importing Camoufox into system Python" or "switching to the proper runtime." Run the wrapper scripts directly and let them choose the runtime.

## Runtime Failure Reporting

When browser execution fails, report the observed runtime failure first.

- If `camoufox-nixos` times out or exits before navigation, say it failed before page navigation and treat it as a host runtime launch issue until proven otherwise.
- Do not turn a wrapper startup failure into a target-site blocking diagnosis.
- Do not claim a "legacy Python path worked" unless you actually ran that exact path and verified success.
- If you suggest the distrobox fallback, present it as an alternate documented browser lane, not proof that system Python imports are the real problem.

### Optional fallback/API setup

If `camoufox-nixos` is missing, or if you need the `curl_cffi` lane, run:

```bash
bash scripts/setup.sh
```

That script configures the distrobox fallback when `pybox` is available and tells you what is missing when it is not.

## When To Use

- Standard Playwright or Selenium gets blocked
- The site shows Cloudflare challenge loops
- You need persistent authenticated browsing for hostile or paywalled sites
- You need actual stealth rather than generic browser automation
- You need login/session reuse on a host that already has `camoufox-nixos`

Do **not** use this skill for ordinary browsing or generic site testing. Use your normal browser automation tool for that.

## Workflow Summary

### Protected-page fetch

```bash
./scripts/camoufox-fetch.py \
  "https://www.yelp.com/biz/example" \
  --headless \
  --wait 8 \
  --screenshot yelp.png \
  --output yelp.html
```

### Persistent session

```bash
# Interactive login
./scripts/camoufox-session.py \
  --profile airbnb \
  --login "https://www.airbnb.com/account-settings"

# Reuse saved session
./scripts/camoufox-session.py \
  --profile airbnb \
  --headless "https://www.airbnb.com/trips"

# Check session status
./scripts/camoufox-session.py \
  --profile airbnb \
  --status "https://www.airbnb.com"
```

## State Ownership

This skill owns **no durable state of its own**. Browser profile state belongs to the selected runtime:

- **Host-native (`camoufox-nixos`)**: `~/.cache/camoufox-nixos`
- **Legacy distrobox fallback**: `~/.stealth-browser/profiles/<name>/`

Implications:

- Persistent session reuse still works in both lanes because the runtimes own their own profile/cache locations.
- `--import-cookies` is a legacy fallback feature. If you ask for it without the distrobox lane, the script fails clearly instead of pretending parity.
- `--export-cookies` continues to work.

## Gotchas

See [references/gotchas.md](references/gotchas.md) for the non-obvious footguns: runtime-framing mistakes, browser lane vs API helper confusion, headed-login expectations, Linux-only fallback assumptions, and host-native state-path differences.

## Secondary API Helper

`curl_cffi` remains in this repo as a secondary API-only helper. It is useful when:

- there is no browser interaction requirement
- you already know the API endpoint
- browser overhead would be wasted

It is not the primary skill contract. Current repo guidance for it is still the legacy distrobox path:

```bash
distrobox enter pybox -- python3.14 scripts/curl-api.py "https://api.example.com"
```

## Non-NixOS And Missing Runtime

- **NixOS hosts with `camoufox-nixos`**: browser lane is host-native by default
- **Other Linux hosts**: use the distrobox fallback
- **macOS / Windows**: `camoufox-nixos` is not the portability story; the repo’s portable browser guidance is still the distrobox fallback where available

This skill does **not** try to teach every machine how to recreate `camoufox-nixos`. That wrapper is host-specific, and the distrobox lane is the compatibility path where available.

## Proxy Reminder

For Airbnb, Yelp, Datadome, and similar targets:

- datacenter IPs often get blocked immediately
- residential or mobile proxies are usually required
- sticky sessions matter more than rotating every request

See [references/proxy-setup.md](references/proxy-setup.md).

## Remote / Headed Login Notes

Interactive login still needs a visible browser window regardless of runtime. If you are remote, use a display-capable setup such as:

- local desktop session
- SSH with display forwarding where supported
- VNC or similar remote desktop

## Troubleshooting

| Problem | Meaning | What to do |
|---------|---------|------------|
| `No supported browser runtime found` | Neither `camoufox-nixos` nor valid distrobox fallback was detected | Install the host wrapper or configure distrobox plus pybox |
| `camoufox-nixos` times out before navigation | Browser wrapper failed to launch cleanly on the host | Report it as a host runtime launch issue first; only discuss site blocking after the browser actually reaches the target |
| `--import-cookies requires the legacy distrobox fallback` | Host-native lane cannot honestly reproduce that legacy import flow | Use the fallback lane for that operation |
| Browser lane works but `curl-api.py` does not | `curl_cffi` lane is still legacy-path setup in this repo | Run `bash scripts/setup.sh` |
| Immediate block or challenge loop | Proxy quality or behavior issue | Use residential/mobile proxy and increase wait time |

## References

- [README.md](README.md) — repo overview
- [references/gotchas.md](references/gotchas.md) — recurring footguns and local assumptions
- [references/proxy-setup.md](references/proxy-setup.md) — proxy guidance
- [references/fingerprint-checks.md](references/fingerprint-checks.md) — anti-bot fingerprint categories

Comments 0

Latest | Hot

Please login before commenting.

Loading comments...

camoufox-stealth-browser

Directory Structure

SKILL.md

Report

Notice