docker-stealthy-auto-browse

# docker-stealthy-auto-browse

[![CI](https://github.com/psyb0t/docker-stealthy-auto-browse/actions/workflows/pipeline.yml/badge.svg?branch=main)](https://github.com/psyb0t/docker-stealthy-auto-browse/actions/workflows/pipeline.yml)
[![version](https://raw.githubusercontent.com/psyb0t/docker-stealthy-auto-browse/badges/version.svg)](https://github.com/psyb0t/docker-stealthy-auto-browse/releases)
[![license](https://raw.githubusercontent.com/psyb0t/docker-stealthy-auto-browse/badges/license.svg)](LICENSE)
[![Docker Pulls](https://img.shields.io/docker/pulls/psyb0t/stealthy-auto-browse?style=flat-square)](https://hub.docker.com/r/psyb0t/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`.

The image avoids Chromium CDP signals and keeps its generated Linux font and
WebGL surfaces internally consistent. Detection results still depend on the
site, network exit, timezone, browser build, and test date.

## Table of Contents

- [What's Inside](#whats-inside)
- [Quick Start](#quick-start)
- [Two Input Modes](#two-input-modes)
- [Virtual Camera & Microphone](#virtual-camera--microphone)
- [MCP Server](#mcp-server)
- [Agent integrations](#agent-integrations)
- [Script Mode](#script-mode)
- [Page Loaders](#page-loaders)
- [Screen Recording](#screen-recording)
- [Cluster Mode](#cluster-mode)
- [Authentication](#authentication)
- [Configuration](#configuration)
- [Development](#development)
- [Bot Detection Results](#bot-detection-results)
- [License](#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](https://modelcontextprotocol.io/) server at `/mcp` on the same port. AI agents (Claude, etc.) can drive the browser directly over MCP using Streamable HTTP.       |
| **ffmpeg**     | `x11grab` against Xvfb for screen recording. Captures actual rendered pixels including the OS-level mouse cursor — see [Screen Recording](#screen-recording).                               |

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

## Quick Start

```bash
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/`).

```bash
# 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:**

```bash
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](docs/api.md) for all actions and the full API reference.

Navigation uses app-owned controls, not a hidden browser-library timeout: each attempt gets 30 seconds by default, one timeout retry, and a one-second retry delay. Pass `timeout`, `retry_count`, and `retry_delay` with `goto`, `refresh`, or `new_tab` when a workflow needs different bounds. `retry_count: 0` disables retries. See [navigation controls](docs/api.md#navigation) for the limits and retry behavior.

## 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](docs/stealth.md)

## Virtual Camera & Microphone

Mount test media read-only at `/media` and set `VIRTUAL_CAMERA_FILE` and/or `VIRTUAL_MICROPHONE_FILE`. Pages that call `navigator.mediaDevices.getUserMedia()` receive tracks captured from those files, so camera and microphone checks can run without host hardware.

```bash
docker run -d -p 8080:8080 \
  -v ./media:/media:ro \
  -e VIRTUAL_CAMERA_FILE=camera.webm \
  -e VIRTUAL_MICROPHONE_FILE=microphone.wav \
  psyb0t/stealthy-auto-browse
```

Sources must remain inside `/media`; restart the browser after changing them. A request for a kind without a configured virtual source fails with `NotFoundError` rather than falling back to hardware. Virtual tracks use the source file's native format, so pages must not require incompatible exact media constraints. This virtualizes `getUserMedia()` only, not `enumerateDevices()`.

To switch sources during an authorized test without replacing an already acquired camera or microphone track, enable `VIRTUAL_MEDIA_DYNAMIC=true`. Dynamic mode is disabled by default. Use `set_virtual_media_source` to choose an existing relative file name under `VIRTUAL_MEDIA_DIR`, or `upload_virtual_media` to add bounded base64 content and optionally activate it. An upload filename is only a safe, type-matching media name; the service generates a collision-safe stored basename, returns it, and never overwrites an existing named source. Before storage or activation, the decoded upload is checked with `ffprobe` for a stream matching the requested camera or microphone kind. The media directory must be writable for uploads; `VIRTUAL_MEDIA_UPLOAD_MAX_BYTES` defaults to 50 MiB. Existing page streams keep their track identities while the source changes.

Dynamic mode accepts files from the configured media directory only. It does not accept arbitrary host paths, remote URLs, WebSocket streams, or other live ingress. Both actions use the normal API authentication: when `AUTH_TOKEN` is set, send the usual `Authorization: Bearer <token>` header. See [docs/api.md#virtual-camera-and-microphone](docs/api.md#virtual-camera-and-microphone) and [docs/configuration.md](docs/configuration.md) for the action contract and writable-volume setup.

## MCP Server

AI agents can control the browser over the [Model Context Protocol](https://modelcontextprotocol.io/) 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.

For authorised test flows that need a human review when a verification widget appears, use `detect_challenge`. It is read-only: it reports a best-effort `absent`, `present`, or `unknown` status with bounded vendor/location evidence, but never clicks, enters a frame, or solves a challenge. Pass `scroll_into_view: true` to bring the first visible detected frame or widget into the viewport for VNC handoff; it still never clicks or focuses it. In cluster mode, include it as a `run_script` step. See [the API reference](docs/api.md#challenge-detection).

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

Wor