patchright-docker

General-purpose stealth browser in Docker. Patchright (undetected Playwright) + xvfb. No Chrome window popups.

Use it as a stealth curl replacement for Cloudflare-protected pages, or mount custom scripts for complex automation.

Quick Start

# Fetch page text
docker run --rm ghcr.io/borski/patchright-docker "https://example.com"

# Fetch a specific element
docker run --rm ghcr.io/borski/patchright-docker "https://example.com" --selector "table"

# Bypass Cloudflare (visit homepage first)
docker run --rm ghcr.io/borski/patchright-docker "https://protected-site.com/data" --warmup "https://protected-site.com"

# JSON output
docker run --rm ghcr.io/borski/patchright-docker "https://example.com" --json

# Run a custom Python script
docker run --rm -v ./my_script.py:/scripts/my_script.py \
  ghcr.io/borski/patchright-docker script /scripts/my_script.py --arg1 val1

Why

Some sites block curl, headless browsers, and even standard Playwright. Patchright patches Chromium's fingerprint to bypass detection. Running inside Docker with xvfb means no browser window pops up on your machine.

Usage

Fetch mode (default)

docker run --rm ghcr.io/borski/patchright-docker URL [OPTIONS]

Option	Description
--selector SEL	CSS selector to extract (repeatable). Default: body
--html	Return HTML instead of text
--json	JSON output with title, url, content
--screenshot PATH	Save screenshot (mount a volume for output)
--full-page	Full page screenshot
--wait MS	Wait after page load, milliseconds (default: 5000)
--timeout MS	Navigation timeout (default: 30000)
--warmup URL	Visit this URL first to establish session (Cloudflare bypass)
--js EXPR	Execute JavaScript and return result
--click SEL	Click selector before extracting (repeatable)
--fill SEL VALUE	Fill input before extracting (repeatable)
--user-agent STR	Override user agent

Script mode

Mount any Python script that uses Patchright. The container has Patchright and Chromium pre-installed.

docker run --rm -v ./my_script.py:/scripts/my_script.py \
  ghcr.io/borski/patchright-docker script /scripts/my_script.py [args...]

Your script can from patchright.sync_api import sync_playwright and use the full Patchright API. xvfb is already running.

Examples

# Scrape a Cloudflare-protected table
docker run --rm ghcr.io/borski/patchright-docker \
  "https://seats.aero/tools/releases?source=aeroplan" \
  --warmup "https://seats.aero" \
  --selector "table"

# Click a button then extract results
docker run --rm ghcr.io/borski/patchright-docker \
  "https://example.com/search" \
  --fill "#query" "test" \
  --click "#search-btn" \
  --wait 3000 \
  --selector ".results"

# Execute JavaScript
docker run --rm ghcr.io/borski/patchright-docker \
  "https://example.com" \
  --js "JSON.stringify(performance.timing)"

# Take a screenshot
docker run --rm -v ./output:/output ghcr.io/borski/patchright-docker \
  "https://example.com" \
  --screenshot /output/page.png --full-page

AI Agent Skill

This repo includes an agent skill at skills/patchright-docker/SKILL.md for use with OpenCode, Claude Code, or any tool that supports markdown skills.

Install the skill

OpenCode (global):

cp -r skills/patchright-docker ~/.config/opencode/skills/patchright-docker

Claude Code (global):

cp -r skills/patchright-docker ~/.claude/skills/patchright-docker

Per-project (either tool):

# OpenCode
cp -r skills/patchright-docker .opencode/skills/patchright-docker

# Claude Code
cp -r skills/patchright-docker .claude/skills/patchright-docker

The skill teaches the agent when and how to use patchright-docker: Cloudflare bypass patterns, selector extraction, JSON pipelines, screenshots, and script mode.

Build

docker build -t patchright-docker .

How It Works

1. Starts xvfb (virtual display) inside the container
2. Launches Patchright Chromium in "headed" mode against the virtual display
3. Optionally visits a warmup URL first (establishes cookies, bypasses Cloudflare challenges)
4. Navigates to the target URL
5. Waits for the page to load and any Cloudflare challenges to resolve
6. Extracts content based on options (text, HTML, screenshot, JS)
7. Outputs to stdout

Patchright patches Chromium to avoid detection of: Runtime.enable leak, Console.enable leak, command flag leaks, headless detection, and other common bot fingerprints.

License

MIT