docker-stealthy-auto-browse

Stealth browser automation that actually works. Runs Camoufox (custom Firefox) in Docker with zero Chrome DevTools Protocol exposure, real OS-level mouse and keyboard input via PyAutoGUI, and a JSON HTTP API + MCP server to control it all remotely. Watch it live via noVNC. Run a single instance or spin up a cluster behind HAProxy with Redis cookie sync, request queuing, and sticky sessions. Drive it with curl, pipe YAML scripts through stdin, send multi-step scripts via the API, use page loaders to auto-handle popups and paywalls, or connect AI agents directly via MCP. Optional Bearer token auth via AUTH_TOKEN.

Passes Cloudflare, CreepJS, BrowserScan, Pixelscan, and every other bot detector we've thrown at it. While Chromium-based tools are getting caught by the first line of defense, this thing walks through the front door unnoticed.

Table of Contents

• What's Inside
• Quick Start
• Two Input Modes
• MCP Server
• Script Mode
• Page Loaders
• Cluster Mode
• Authentication
• Configuration
• Bot Detection Results
• License

What's Inside

Pre-installed extensions: uBlock Origin (ads/trackers), LocalCDN (prevents CDN tracking), ClearURLs (strips tracking params), Consent-O-Matic (auto-handles cookie popups).

Quick Start

docker run -d --name browser \
  -p 8080:8080 \
  -p 5900:5900 \
  psyb0t/stealthy-auto-browse

Port 8080 is the HTTP API, port 5900 is the VNC viewer (http://localhost:5900/).

# Navigate
curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{"action": "goto", "url": "https://example.com"}'

# Get page text
curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{"action": "get_text"}'

# Click with real OS-level mouse movement (undetectable)
curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{"action": "system_click", "x": 500, "y": 300}'

# Screenshot
curl "http://localhost:8080/screenshot/browser?whLargest=512" -o screenshot.png

Run multi-step scripts in one request:

curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{
    "action": "run_script",
    "steps": [
      {"action": "goto", "url": "https://example.com", "wait_until": "domcontentloaded"},
      {"action": "sleep", "duration": 2},
      {"action": "get_text", "output_id": "text"},
      {"action": "eval", "expression": "document.title", "output_id": "title"}
    ]
  }'

Also accepts "yaml": "..." with the same YAML format used in script mode. In single-instance mode, requests are serialized automatically — send multiple scripts in parallel and they queue up.

See docs/api.md for all actions and the full API reference.

Two Input Modes

There are two ways to interact with pages. System input uses PyAutoGUI to generate real OS-level mouse and keyboard events — the browser cannot tell these apart from a real human. Playwright input uses CSS selectors and DOM event injection — easier, but theoretically detectable by behavioral analysis. Use system input on any site with bot protection.

Full breakdown and usage guide: docs/stealth.md

MCP Server

AI agents can control the browser over the Model Context Protocol via Streamable HTTP at /mcp on the same port 8080. All browser actions are exposed as MCP tools — navigation, screenshots, clicking, typing, JavaScript evaluation, cookies, and more.

Connect any MCP-compatible client (Claude Desktop, Claude Code, custom agents) to http://localhost:8080/mcp/ and start browsing.

Works in both standalone and cluster mode — HAProxy routes MCP traffic with the same sticky sessions as the HTTP API.

Script Mode

Pipe a YAML script into the container, get JSON results on stdout, container exits. No HTTP server. Good for CI, cron jobs, one-shot scraping.

cat my-script.yaml | docker run --rm -i \
  -e TARGET_URL=https://example.com \
  psyb0t/stealthy-auto-browse --script > results.json

Full docs: docs/script-mode.md

Page Loaders

Define URL patterns + action sequences in YAML files. Mount them at /loaders. Whenever goto matches a pattern, the loader runs automatically — removes popups, waits for content, cleans up the page. Greasemonkey for the HTTP API.

Full docs: docs/page-loaders.md

Cluster Mode

Run multiple browser instances behind HAProxy with a request queue, sticky sessions, and Redis cookie sync (default 10, configurable via MAX_CONCURRENT). Download the compose file and HAProxy config, then start:

curl -LO https://raw.githubusercontent.com/psyb0t/docker-stealthy-auto-browse/main/docker-compose.cluster.yml
curl -LO https://raw.githubusercontent.com/psyb0t/docker-stealthy-auto-browse/main/haproxy.cfg.template
docker compose -f docker-compose.cluster.yml up -d

Cookies set on any instance propagate to all others instantly via Redis PubSub. Log in once, the whole fleet is authenticated.

Full docs: docs/cluster-mode.md

Authentication

Set AUTH_TOKEN to require a Bearer token on all requests (except /health):

docker run -d -p 8080:8080 -e AUTH_TOKEN=mysecretkey psyb0t/stealthy-auto-browse

Pass the token via header or query param:

# Header
curl -H "Authorization: Bearer mysecretkey" http://localhost:8080 ...

# Query param (useful for MCP clients that can't set headers)
# MCP endpoint: http://localhost:8080/mcp/?auth_token=mysecretkey

Configuration

Full environment variables table, proxy setup, persistent profiles, browser extensions, and VNC access: docs/configuration.md

Bot Detection Results

Why it works: docs/stealth.md

License

WTFPL — Do What The Fuck You Want To Public License