stealthy-auto-browse

Stealth browser in Docker. Camoufox (custom Firefox) — zero CDP signals. OS-level mouse/keyboard via PyAutoGUI — undetectable. Passes Cloudflare, DataDome, PerimeterX, Akamai.

For installation, configuration, and container setup, see references/setup.md.

When To Use

• - Site has bot detection (Cloudflare, CAPTCHAs, DataDome)
• Another browser skill is getting 403s or blocked responses
• You need a logged-in session that won't get banned

When NOT To Use

• - No bot protection — use curl or INLINECODE1
• Only need static HTML — use INLINECODE2

Setup

The API should already be running. Set the base URL:

CODEBLOCK0

Verify: curl $STEALTHY_AUTO_BROWSE_URL/health returns ok.

HTTP API

All commands: POST $STEALTHY_AUTO_BROWSE_URL/ with JSON body {"action": "name", ...params}.

If AUTH_TOKEN is set on the server, include it on every request (except /health):

CODEBLOCK1

Or pass it as a query param: ?auth_token=<key> (useful for MCP clients that can't set headers).

In single-instance mode, requests are serialized automatically — only one runs at a time, the rest queue up.

Every response:

CODEBLOCK2

Two Input Modes

System Input — Undetectable

Uses PyAutoGUI for real OS-level events. The browser has no idea it's automated.

• - system_click — move mouse with human-like curve, then click (viewport x,y coords)
• INLINECODE11 — move mouse without clicking (hover menus, tooltips)
• INLINECODE12 — click at position or current location (no smooth movement)
• INLINECODE13 — type text character-by-character with randomized delays
• INLINECODE14 — press a key or combo (enter, tab, ctrl+a)
• INLINECODE18 — mouse wheel scroll (negative = down)

Get viewport coordinates from get_interactive_elements.

Playwright Input — Detectable But Convenient

Uses Playwright's DOM events. Faster, uses CSS selectors/XPath, but detectable.

• - click — click by selector
• INLINECODE21 — set input value instantly
• INLINECODE22 — type into element character-by-character

Which To Use

• - Bot detection? System input. Always.
• No detection? Playwright input is fine.
• Fill forms stealthily? system_click to focus, then system_type.

Typical Workflow

1. 1. goto → load the page
2. INLINECODE26 → read what's on the page
3. INLINECODE27 → find buttons/inputs with x,y coordinates
4. INLINECODE28 / system_type / send_key → interact
5. INLINECODE31 / wait_for_text → wait for results
6. INLINECODE33 → verify

Actions Reference

Navigation

CODEBLOCK3

INLINECODE34: "domcontentloaded" (default), "load", "networkidle".
referer: set HTTP Referer header (for sites that check referrer).

Response: INLINECODE39

System Input (Undetectable)

CODEBLOCK4

Playwright Input (Detectable)

CODEBLOCK5

Page Inspection

CODEBLOCK6

INLINECODE40 returns all buttons, links, inputs with x, y, w, h, text, selector, visible. Pass x, y directly to system_click.

INLINECODE51 returns visible page text (truncated to 10,000 chars). Call this first after navigating.

Screenshots

CODEBLOCK7

Resize params: whLargest=512 (recommended), width=800, height=300, width=400&height=400.

Via action (for script mode — returns base64 with output_id):

CODEBLOCK8

Wait Conditions

Use these instead of sleep.

CODEBLOCK9

INLINECODE58: "visible" (default), "hidden", "attached", "detached".

Tabs

CODEBLOCK10

Dialogs

Call handle_dialog BEFORE the action that triggers the dialog. Dialogs are auto-accepted by default.

CODEBLOCK11

Cookies

CODEBLOCK12

Storage

CODEBLOCK13

INLINECODE64: "local" (default) or "session".

Downloads & Uploads

CODEBLOCK14

Network Logging

CODEBLOCK15

Console Logging

Capture console.log, console.error, console.warn, etc. Each entry has type, text, location, timestamp.

CODEBLOCK16

Scrolling

CODEBLOCK17

INLINECODE74 uses JS (fast). scroll_to_bottom_humanized uses OS-level mouse wheel (undetectable).

Display

CODEBLOCK18

Call calibrate after fullscreen changes.

Multi-Step Scripts

Run multiple actions as one atomic request. Steps with output_id collect results.

CODEBLOCK19

Also accepts "yaml": "..." with the same YAML format used in script mode.

INLINECODE79: "stop" (default) or "continue".

Utility

CODEBLOCK20

State Endpoints (GET)

CODEBLOCK21

MCP Server

The browser exposes all actions as MCP tools via Streamable HTTP at /mcp/ on the same port as the HTTP API.

CODEBLOCK22

Connect any MCP-compatible client to that URL. All actions from the HTTP API are available as tools — goto, screenshot, system_click, system_type, eval_js, get_text, get_cookies, run_script (multi-step), browser_action (generic fallback for everything else), and more.

If AUTH_TOKEN is set, connect to http://localhost:8080/mcp/?auth_token=<key>.

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

Cluster Mode

Run multiple browser instances behind HAProxy with a request queue, sticky sessions, and Redis cookie sync. For setup see references/setup.md.

Entry point is http://localhost:8080 — same API. HAProxy queues requests when all instances are busy instead of returning errors.

Sticky sessions: HAProxy sets an INSTANCEID cookie. Send it back on subsequent requests to keep routing to the same browser instance. All browser state (tabs, DOM, JS, local storage) lives on that specific container — only cookies sync via Redis.

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

Script Mode

Pipe a YAML script via stdin, get JSON results on stdout, container exits. No HTTP server.

CODEBLOCK23

Script Format

CODEBLOCK24

Output

CODEBLOCK25

• - output_id on any step collects its result into outputs. Screenshots become base64 data URIs.
• ${env.VAR_NAME} substitutes environment variables.
• on_error: continue keeps going past failures. stop (default) halts.
• All HTTP API actions work as script steps.
• Logs go to stderr, stdout is clean JSON.
• Exit code 0 on success, 1 on failure.

Example: Screenshot + Extract

CODEBLOCK26

Page Loaders (URL-Triggered Automation)

Mount YAML files to /loaders. When goto hits a matching URL, the loader's steps execute instead of normal navigation. Works in both API and script mode.

CODEBLOCK27

In script mode:

CODEBLOCK28

Loader Format

CODEBLOCK29

Match fields are optional but at least one is required. All specified fields must match.

Example Scripts

Web Search (scripts/websearch.py)

Multi-engine parallel web search using the browser API. Searches Brave, Google, and Bing, extracts structured results (title, URL, snippet) and AI overviews when available.

CODEBLOCK30

Output is JSON: INLINECODE104

Env vars: STEALTHY_AUTO_BROWSE_URL, WEBSEARCH_ENGINES (default: brave,google,bing), AUTH_TOKEN, USER_AGENT.

In cluster mode, each engine gets its own browser instance for true parallelism. In single mode, requests serialize via the request lock.

Tips

1. 1. Always get_interactive_elements before clicking — don't guess coordinates
2. System input for stealth — system_click, system_type, INLINECODE113
3. get_text first, screenshots second — text is faster and smaller
4. Match TZ to IP location — timezone mismatch is a detection signal
5. Resize screenshots with ?whLargest=512 — full resolution is huge
6. Wait conditions over sleep — wait_for_element, wait_for_text, INLINECODE118
7. handle_dialog BEFORE the trigger — dialogs are auto-accepted otherwise
8. calibrate after fullscreen — coordinate mapping shifts