Skip to content
Back to search

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/psyb0t/docker-stealthy-auto-browse with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/psyb0t/docker-stealthy-auto-browse'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/psyb0t--docker-stealthy-auto-browse/badge.svg)](/listings/psyb0t--docker-stealthy-auto-browse)

HTML

<a href="/listings/psyb0t--docker-stealthy-auto-browse"><img src="/api/listings/psyb0t--docker-stealthy-auto-browse/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 184 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # stealthy-auto-browse
  2. [![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)
  3. [![version](https://raw.githubusercontent.com/psyb0t/docker-stealthy-auto-browse/badges/version.svg)](https://github.com/psyb0t/docker-stealthy-auto-browse/releases)
  4. [![license](https://raw.githubusercontent.com/psyb0t/docker-stealthy-auto-browse/badges/license.svg)](LICENSE)
  5. [![Docker Pulls](https://img.shields.io/docker/pulls/psyb0t/stealthy-auto-browse?style=flat-square)](https://hub.docker.com/r/psyb0t/stealthy-auto-browse)
  6. Stealth browser automation that actually works. One Docker container runs Camoufox on a graphical display, accepts JSON HTTP and MCP commands, sends real OS-level mouse and keyboard input, and exposes a live noVNC viewer. It supports single-browser sessions, atomic scripts, page loaders, recording, virtual media, CAPTCHA detection, optional CAPTCHA solver providers, and clustered browsers with Redis cookie sync.
  7. The image avoids Chromium CDP signals and keeps its generated Linux font and WebGL fingerprints internally consistent. Detection results still depend on the site, network exit, timezone, browser build, and test date.
  8. ## Contents
  9. - [Quick start](#quick-start)
  10. - [How it works](#how-it-works)
  11. - [HTTP API](#http-api)
  12. - [MCP and agent integrations](#mcp-and-agent-integrations)
  13. - [Optional features](#optional-features)
  14. - [Cluster mode](#cluster-mode)
  15. - [Configuration and security](#configuration-and-security)
  16. - [Development](#development)
  17. - [Detection testing](#detection-testing)
  18. - [Documentation](#documentation)
  19. - [Sponsor](#sponsor)
  20. - [License](#license)
  21. ## Quick start
  22. ```bash
  23. docker run -d --name browser \
  24. -p 127.0.0.1:8080:8080 \
  25. -p 127.0.0.1:5900:5900 \
  26. psyb0t/stealthy-auto-browse
  27. ```
  28. Open `http://localhost:5900/` to watch the browser. Port 8080 serves the HTTP API and MCP server.
  29. ```bash
  30. # Navigate
  31. curl -X POST http://localhost:8080 \
  32. -H "Content-Type: application/json" \
  33. -d '{"action":"goto","url":"https://example.com"}'
  34. # Read the page
  35. curl -X POST http://localhost:8080 \
  36. -H "Content-Type: application/json" \
  37. -d '{"action":"get_text"}'
  38. # Click with OS-level input
  39. curl -X POST http://localhost:8080 \
  40. -H "Content-Type: application/json" \
  41. -d '{"action":"system_click","selector":"button#submit"}'
  42. # Capture a token-sized screenshot
  43. curl "http://localhost:8080/screenshot/browser?whLargest=512" -o screenshot.png
  44. ```
  45. Run several actions atomically with `run_script`:
  46. ```bash
  47. curl -X POST http://localhost:8080 \
  48. -H "Content-Type: application/json" \
  49. -d '{
  50. "action": "run_script",
  51. "steps": [
  52. {"action": "goto", "url": "https://example.com"},
  53. {"action": "get_text", "output_id": "text"},
  54. {"action": "eval", "expression": "document.title", "output_id": "title"}
  55. ]
  56. }'
  57. ```
  58. The server serializes requests in single-instance mode. Navigation has bounded retries and timeouts. See the [HTTP API reference](https://psyb0t.github.io/docker-stealthy-auto-browse/api/) for every action and parameter.
  59. ## How it works
  60. | Component | Purpose |
  61. | --- | --- |
  62. | Camoufox | Patched Firefox with no Chrome DevTools Protocol and an isolated automation world. |
  63. | Xvfb and Openbox | Full graphical display and window management without a physical monitor. |
  64. | PyAutoGUI and XTest | Trusted OS-level mouse, keyboard, and wheel events with humanized timing. |
  65. | HTTP API and MCP | Remote browser control on port 8080. |
  66. | noVNC | Live browser view on port 5900, with the automated pointer visible by default. |
  67. | ffmpeg | MP4 recording from the X11 display. |
  68. The desktop, VNC, the HTTP and MCP server, script mode, recording, the clipboard and the humanized input come from [auto-linux-desk](https://github.com/psyb0t/docker-auto-linux-desk), the base image; this image adds the browser as its plugin. The base's desktop actions, such as window control and keyboard shortcuts, work here too. Its `run_command` and `launch_app` are off unless `DESK_EXEC_ENABLED=true`.
  69. The image includes uBlock Origin, LocalCDN, ClearURLs, and Consent-O-Matic. Optional CAPTCHA solver integrations are disabled unless configured.
  70. Two input modes are available. Playwright actions such as `click` and `fill` are fast DOM operations. System actions such as `system_click`, `system_type`, `mouse_move`, and `scroll` send OS-level input with paths and timing fitted to published human input data. `human_pause` represents visible reading, review, or composition time without continuously jiggling the pointer. Use the system actions when trusted input or behavior matters. See [Stealth and detection evasion](https://psyb0t.github.io/docker-stealthy-auto-browse/stealth/) and [Humanized input](https://psyb0t.github.io/docker-stealthy-auto-browse/api/#humanized-input).
  71. ## HTTP API
  72. Send `POST /` with an `action` and its parameters. The API covers navigation, iframe and open-shadow DOM targeting, accessibility lookup, stable element references, DOM and system pointer input, human handoff, tabs and windows, browser events, permissions, network interception and HAR, rich clipboard access, PNG capture, recording, virtual media, challenge detection, waits, logs, and JavaScript evaluation.
  73. Useful read endpoints:
  74. - `GET /health`
  75. - `GET /state`
  76. - `GET /events`
  77. - `GET /screenshot/browser`
  78. - `GET /screenshot/desktop`
  79. `detect_challenge` reports bounded evidence for known challenge widgets without clicking or solving them. Set `scroll_into_view: true` to bring the first visible match into the viewport for a noVNC handoff. See [Challenge detection](https://psyb0t.github.io/docker-stealthy-auto-browse/api/#challenge-detection).
  80. ## MCP and agent integrations
  81. The Streamable HTTP MCP server lives at `http://localhost:8080/mcp/`. It exposes dedicated tools for common actions plus `browser_action` and `run_script` for the complete API.
  82. Published integrations are available for Claude Code, Codex, and OpenClaw. See [MCP and agent integrations](https://psyb0t.github.io/docker-stealthy-auto-browse/agents/) for installation, authentication, dedicated tools, and cluster behavior.
  83. The source skill is under [`.agents/skills/stealthy-auto-browse`](.agents/skills/stealthy-auto-browse). Set `STEALTHY_AUTO_BROWSE_URL` and `AUTH_TOKEN` where the client integration requires them.
  84. ## Optional features
  85. - **Script mode:** Pipe YAML to `docker run --rm -i ... --script` and receive JSON on stdout. Conditions, branches, bounded loops, and output references are supported. See [Script mode](https://psyb0t.github.io/docker-stealthy-auto-browse/script-mode/).
  86. - **Page loaders:** Run URL-matched YAML actions after navigation to handle repeated page cleanup. See [Page loaders](https://psyb0t.github.io/docker-stealthy-auto-browse/page-loaders/).
  87. - **Clipboard:** `set_clipboard` and `get_clipboard` use the real X11 clipboard shared by Camoufox and noVNC. They support UTF-8 text, HTML, PNG, and file URI lists. People paste far more than they type, so enter text with `paste_text`, which sets the clipboard, clicks the field and presses `ctrl+a`, `backspace` and `ctrl+v` with human timing; keep `system_type` for a few characters. See [Clipboard](https://psyb0t.github.io/docker-stealthy-auto-browse/api/#clipboard).
  88. - **Virtual camera and microphone:** Mount media under `/media` and configure static or dynamic sources for `getUserMedia()` tests. See [Virtual camera and microphone](https://psyb0t.github.io/docker-stealthy-auto-browse/api/#virtual-camera-and-microphone) and [Configuration](https://psyb0t.github.io/docker-stealthy-auto-browse/configuration/).
  89. - **Recording:** `start_recording` and `stop_recording` write collision-safe MP4 files to a mounted `/recordings` directory. See [Screen recording](https://psyb0t.github.io/docker-stealthy-auto-browse/api/#screen-recording).
  90. - **CAPTCHA solver providers:** Configure one supported provider through environment variables. Official Firefox extensions are checksum-verified before use. Anti-Captcha uses its official HTTP API. No provider is installed or contacted by default. See [CAPTCHA solver providers](https://psyb0t.github.io/docker-stealthy-auto-browse/configuration/#captcha-solver-providers).
  91. ## Cluster mode
  92. `docker-compose.cluster.yml` runs several browsers behind HAProxy with request queuing, sticky sessions, and Redis cookie sync. The default is five browser replicas with a 5 GB memory limit each. When `NUM_REPLICAS > 1`, MCP exposes only `run_script`; HTTP also permits `ping` and `sleep`. Each script keeps its sequence on one browser.
  93. See [Cluster mode](https://psyb0t.github.io/docker-stealthy-auto-browse/cluster-mode/) for setup, scaling, health checks, and resource controls.
  94. ## Configuration and security
  95. Set `AUTH_TOKEN` to require a Bearer token on HTTP and MCP endpoints except `/health`. This does not authenticate noVNC:
  96. ```bash
  97. docker run -d \
  98. -p 127.0.0.1:8080:8080 \
  99. -p 127.0.0.1:5900:5900 \
  100. -e AUTH_TOKEN=your-token-here \
  101. psyb0t/stealthy-auto-browse
  102. ```
  103. Keep the API and noVNC ports on loopback unless a trusted network or authenticated reverse proxy protects them. Match `TZ` to the proxy exit location. Persist `/userdata` when browser identity and session state must survive restarts.
  104. The [configuration reference](https://psyb0t.github.io/docker-stealthy-auto-browse/configuration/) covers every environment variable, proxies, persistent profiles, extensions, virtual media, VNC, and solver providers.
  105. ## Development
  106. Docker is the only development dependency. The Makefile runs tooling in the project dev image.
  107. ```bash
  108. make build
  109. make lint
  110. make test-unit
  111. make test
  112. make test-real
  113. make sec
  114. ```
  115. `make test-real` is opt-in because it calls public detector sites. Use `make help` for all targets.
  116. ## Detection testing
  117. Observed results are not a promise for every site or future detector version. Test the exact image, proxy, timezone, and target flow you plan to use.
  118. The live suite checks fingerprint consistency on [liarjs.dev](https://liarjs.dev/) and compares humanized system input against Playwright, synthetic DOM, and raw PyAutoGUI controls on DeviceAndBrowserInfo and FCaptcha. The deterministic suite also runs open-source behavioral detectors with robotic controls that must be caught. Current methods and observed results are in [Stealth and detection evasion](https://psyb0t.github.io/docker-stealthy-auto-browse/stealth/).
  119. ## Documentation
  120. [Full documentation](https://psyb0t.github.io/docker-stealthy-auto-browse/) covers installation, the complete action reference, agent integrations, configuration, workflows, clusters, testing, and troubleshooting.
  121. - [HTTP API reference](https://psyb0t.github.io/docker-stealthy-auto-browse/api/)
  122. - [Configuration](https://psyb0t.github.io/docker-stealthy-auto-browse/configuration/)
  123. - [Script mode](https://psyb0t.github.io/docker-stealthy-auto-browse/script-mode/)
  124. - [Page loaders](https://psyb0t.github.io/docker-stealthy-auto-browse/page-loaders/)
  125. - [Cluster mode](https://psyb0t.github.io/docker-stealthy-auto-browse/cluster-mode/)
  126. - [Stealth and input behavior](https://psyb0t.github.io/docker-stealthy-auto-browse/stealth/)
  127. - [Changelog](CHANGELOG.md)
  128. ## Sponsor
  129. <a href="https://www.buymeacoffee.com/psyb0t"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-blue.png" alt="Buy Me a Coffee" height="60" width="217"></a>
  130. ## License
  131. **WTFPL** (Do What The Fuck You Want To Public License)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.