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

Component	What It Does
Camoufox	A custom build of Firefox with zero Chrome DevTools Protocol exposure. Bot detectors look for CDP signals — this browser simply doesn't have any.
Xvfb	Virtual framebuffer that lets the browser run with a full graphical display inside a container, no physical monitor needed. This matters because headless mode is another detection signal.
PyAutoGUI	Generates real OS-level mouse movements and keystrokes. The browser receives these as genuine user input — it has no idea it's being automated.
noVNC	Web-based VNC client so you can watch the browser in real time from your own browser. Great for debugging and seeing exactly what's happening.
Openbox	Lightweight window manager — adds title bars and resize handles to popup windows (OAuth dialogs, etc.) that would otherwise be too small to interact with. Zero stealth impact.
HTTP API	A JSON API on port 8080 that lets you control everything — navigate pages, click elements, type text, take screenshots, manage tabs, handle cookies, and more.
MCP Server	Model Context Protocol server at /mcp on the same port. AI agents (Claude, etc.) can drive the browser directly over MCP using Streamable HTTP.

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 by CSS selector (preferred — fast and reliable)
curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{"action": "click", "selector": "button#submit"}'

# Screenshot (last resort — prefer get_text; always resize to save tokens)
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.

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 NUM_REPLICAS). 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
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.

Script-only enforcement (v1.0.0+): When NUM_REPLICAS > 1, both the HTTP API and MCP server restrict to run_script only (plus ping and sleep). Individual actions are rejected to prevent stale content bugs from cross-instance routing. All actions remain available as steps inside run_script.

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

Examples

See .agents/.skills/stealthy-auto-browse/scripts/ for ready-to-use scripts:

• websearch.py — Multi-engine parallel web search (Brave, Google, Bing) with structured results and AI overview extraction. Outputs JSON with title, URL, and snippet for each result.

Configuration

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

Bot Detection Results

Service	Result	What They Check
CreepJS	Pass	Canvas/WebGL fingerprint consistency, lies detection, worker comparison
BrowserScan	Pass	WebDriver flag, CDP signals, navigator properties
Pixelscan	Pass	Fingerprint coherence, timezone/IP match, WebRTC leaks
Cloudflare	Pass	Challenge pages, Turnstile, bot management
SannySoft	Pass	Intoli + fingerprint scanner tests
Incolumitas	Pass	Modern detection techniques
Rebrowser	Pass	CDP leak detection, webdriver, viewport analysis
BrowserLeaks WebRTC	Pass	WebRTC IP leak detection
DeviceAndBrowserInfo	Pass	19 checks, all green, "You are human!"
IpHey	Pass	"Trustworthy" rating
Fingerprint.com	Pass	Identified as normal Firefox, no bot flags

Why it works: docs/stealth.md

Known Issues / TODO

• system_click reliability — OS-level mouse clicks can land in the wrong place if the window offset is stale. Needs a more robust coordinate mapping solution so it works reliably without manual calibrate calls.

License

WTFPL — Do What The Fuck You Want To Public License