patchright-cli 0.8.0__tar.gz → 0.9.0__tar.gz

{patchright_cli-0.8.0 → patchright_cli-0.9.0}/.claude-plugin/marketplace.json

@@ -5,7 +5,7 @@
   },
   "metadata": {
     "description": "Anti-detect browser automation CLI & Skills for AI agents, powered by Patchright",
-    "version": "0.8.0"
+    "version": "0.9.0"
   },
   "plugins": [
     {

patchright_cli-0.9.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: docker
+    directory: /
+    schedule:
+      interval: weekly
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly

patchright_cli-0.9.0/.github/workflows/ci.yml

@@ -0,0 +1,86 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: ">=0.7,<0.8"
+          python-version: "3.12"
+      - run: uv venv && uv pip install -e ".[dev]"
+      - run: uv run pre-commit run --all-files
+
+  test:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.12"]
+        include:
+          - os: macos-latest
+            python-version: "3.12"
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: ">=0.7,<0.8"
+          python-version: ${{ matrix.python-version }}
+      - run: uv venv && uv pip install -e ".[dev]"
+      - run: uv run pytest tests/ -v --ignore=tests/test_e2e.py
+
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: docker build -t patchright-cli:ci .
+      - run: docker run --rm patchright-cli:ci --help
+      - name: Browser session inside the container
+        run: |
+          docker run -d --name cli --entrypoint sleep patchright-cli:ci infinity
+          docker exec cli uv run patchright-cli open https://example.com --headless
+          docker exec cli uv run patchright-cli eval document.title | tee title.txt
+          grep -q "Example Domain" title.txt
+          docker exec cli uv run patchright-cli close
+      - name: MCP over HTTP with a token
+        run: |
+          docker run -d --name mcp -p 9090:9090 -e PATCHRIGHT_CLI_MODE=mcp-http -e PATCHRIGHT_CLI_MCP_TOKEN=ci-token patchright-cli:ci
+          for _ in $(seq 30); do curl -s -o /dev/null http://localhost:9090/mcp && break; sleep 1; done
+          init='{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"ci","version":"0"}}}'
+          headers=(-H "Content-Type: application/json" -H "Accept: application/json, text/event-stream")
+          test "$(curl -s -o /dev/null -w '%{http_code}' "${headers[@]}" -d "$init" http://localhost:9090/mcp)" = 401
+          test "$(curl -s -o /dev/null -w '%{http_code}' "${headers[@]}" -H "Authorization: Bearer ci-token" -d "$init" http://localhost:9090/mcp)" = 200
+          # Host/Origin checks are off by default, so any Host is accepted
+          test "$(curl -s -o /dev/null -w '%{http_code}' "${headers[@]}" -H "Authorization: Bearer ci-token" -H "Host: other.example:9090" -d "$init" http://localhost:9090/mcp)" = 200
+      - name: MCP over HTTP without a token, Host/Origin checks on
+        run: |
+          docker run -d --name mcp-open -p 9091:9090 -e PATCHRIGHT_CLI_MODE=mcp-http -e FASTMCP_HTTP_HOST_ORIGIN_PROTECTION=true -e FASTMCP_HTTP_ALLOWED_HOSTS='["patchright-mcp"]' patchright-cli:ci
+          for _ in $(seq 30); do curl -s -o /dev/null http://localhost:9091/mcp && break; sleep 1; done
+          init='{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"ci","version":"0"}}}'
+          headers=(-H "Content-Type: application/json" -H "Accept: application/json, text/event-stream")
+          test "$(curl -s -o /dev/null -w '%{http_code}' "${headers[@]}" -d "$init" http://localhost:9091/mcp)" = 200
+          test "$(curl -s -o /dev/null -w '%{http_code}' "${headers[@]}" -H "Host: evil.example:9091" -d "$init" http://localhost:9091/mcp)" = 421
+          test "$(curl -s -o /dev/null -w '%{http_code}' "${headers[@]}" -H "Origin: http://evil.example" -d "$init" http://localhost:9091/mcp)" = 403
+          test "$(curl -s -o /dev/null -w '%{http_code}' "${headers[@]}" -H "Host: patchright-mcp:9090" -d "$init" http://localhost:9091/mcp)" = 200
+      - name: MCP over HTTP refuses to start with neither a token nor a Host/Origin choice
+        run: |
+          status=0
+          timeout 120 docker run --name mcp-unprotected -e PATCHRIGHT_CLI_MODE=mcp-http patchright-cli:ci > unprotected.log 2>&1 || status=$?
+          cat unprotected.log
+          test "$status" -ne 0
+          grep -q "refusing to start \`mcp --http\`" unprotected.log
+      - name: compose.yml works without a token
+        run: docker compose config -q
+      - if: failure()
+        run: |
+          docker logs cli || true
+          docker logs mcp || true
+          docker logs mcp-open || true
+          docker logs mcp-unprotected || true

patchright_cli-0.9.0/.github/workflows/publish-docker.yml

@@ -0,0 +1,65 @@
+name: docker-publish
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Docker image tag to publish"
+        required: true
+        type: string
+      publish_docker:
+        description: "Publish docker image"
+        required: true
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    name: docker-publish
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Set Docker image tags
+        id: tags
+        shell: bash
+        env:
+          VERSION_TAG: ${{ inputs.tag }}
+        run: |
+          REPOSITORY="$(echo '${{ github.repository }}' | tr '[:upper:]' '[:lower:]')"
+          IMAGE_NAME="ghcr.io/${REPOSITORY}"
+
+          {
+            echo "tags<<EOF"
+            echo "${IMAGE_NAME}:${VERSION_TAG}"
+            echo "${IMAGE_NAME}:latest"
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Authenticate with GHCR
+        if: ${{ inputs.publish_docker }}
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build Docker image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./Dockerfile
+          push: ${{ inputs.publish_docker }}
+          tags: ${{ steps.tags.outputs.tags }}
+          # Attestations need the docker-container driver that setup-buildx-action creates above.
+          provenance: mode=max
+          sbom: true

{patchright_cli-0.8.0 → patchright_cli-0.9.0}/CLAUDE.md

@@ -58,8 +58,8 @@ CLI (cli.py) --TCP:9321--> Daemon (daemon.py) --Patchright--> Chrome
 - Always uses persistent browser context (`launch_persistent_context`) with real Chrome (`channel="chrome"`), not Chromium
 - Headed by default (headless is more detectable)
 - Default daemon port: 9321, profiles stored at `~/.patchright-cli/profiles/<profile-name>`; a session's profile defaults to its session name (`--profile=<name>` overrides, a value with `/` or `\` is a directory). One session per profile at a time
-- CLI-daemon protocol: length-prefixed (4-byte big-endian `!I`) JSON over TCP
-- CLI parses argv manually in `main()` — click is only used for `click.echo()`, not subcommands. New commands must be added to both `COMMANDS_HELP` dict and the `handle_command()` if/elif chain in daemon.py
+- CLI-daemon protocol: length-prefixed (4-byte big-endian `!I`) JSON over TCP; every message carries a `token` field read from `~/.patchright-cli/daemon-<port>.token` (written 0600 by the daemon before it listens), and the daemon rejects messages without the right one
+- CLI parses argv manually in `main()` — click is only used for `click.echo()`, not subcommands. New commands need a `COMMANDS_HELP` entry and a `@register("<name>")` handler in daemon.py; only session and lifecycle commands (open, attach, close, kill-all, ...) live in `handle_command()` itself
 - Version must be updated in `pyproject.toml`, `src/patchright_cli/__init__.py` and `.claude-plugin/marketplace.json` (then run `uv lock` to sync the lock file; `tests/test_packaging.py` checks they match)
 - `python -m patchright_cli` works via `__main__.py`
 - Uses hatchling as build backend, ruff for linting (line-length=120, target py310)

patchright_cli-0.9.0/Dockerfile

@@ -0,0 +1,37 @@
+# Base images are pinned by multi-arch index digest; Dependabot (.github/dependabot.yml) bumps them.
+# uv is a named stage because Dependabot only reads image references on FROM lines.
+FROM ghcr.io/astral-sh/uv:latest@sha256:32a7bb39b496babbd997b0a39a4d66c126bdaf5661b302bf6f06abda8deca6ff AS uv
+
+FROM python:3.12-slim@sha256:5b8b1421ccb6a525860a77863c049eab5847076cda34e030c75a80c58faf3f3c
+
+ENV PYTHONUNBUFFERED=1 \
+    UV_LINK_MODE=copy \
+    UV_NO_SYNC=1 \
+    PATCHRIGHT_CLI_MCP_HEADLESS=1 \
+    PATCHRIGHT_CLI_MCP_ROOT=/patchright
+
+WORKDIR /app
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends ffmpeg \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=uv /uv /uvx /bin/
+
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-install-project --extra mcp --no-dev
+
+RUN uv run --no-sync python -m patchright install --with-deps chrome \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY README.md LICENSE ./
+COPY src ./src
+COPY skills ./skills
+RUN uv sync --frozen --extra mcp --no-dev
+
+RUN mkdir -p /patchright/output /root/.patchright-cli
+
+EXPOSE 9090
+
+ENTRYPOINT ["sh", "-c", "case \"$PATCHRIGHT_CLI_MODE\" in mcp-http) exec uv run patchright-cli mcp --http --host=0.0.0.0 --port=\"${PATCHRIGHT_CLI_MCP_PORT:-9090}\" ;; mcp-stdio) exec uv run patchright-cli mcp ;; \"\"|standalone) exec uv run patchright-cli \"$@\" ;; *) echo \"Unknown PATCHRIGHT_CLI_MODE: $PATCHRIGHT_CLI_MODE\" >&2; exit 2 ;; esac", "--"]
+CMD ["--help"]

{patchright_cli-0.8.0 → patchright_cli-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: patchright-cli
-Version: 0.8.0
+Version: 0.9.0
 Summary: Anti-detect browser automation CLI using Patchright (undetected Playwright fork)
 Project-URL: Homepage, https://github.com/AhaiMk01/patchright-cli
 Project-URL: Repository, https://github.com/AhaiMk01/patchright-cli
@@ -24,14 +24,15 @@ Requires-Python: >=3.10
 Requires-Dist: aiohttp>=3.9
 Requires-Dist: click
 Requires-Dist: patchright
+Requires-Dist: pywin32>=306; sys_platform == 'win32'
 Requires-Dist: pyyaml
 Provides-Extra: dev
-Requires-Dist: fastmcp<5,>=3.0; extra == 'dev'
+Requires-Dist: fastmcp<5,>=3.4.3; extra == 'dev'
 Requires-Dist: pre-commit; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Provides-Extra: mcp
-Requires-Dist: fastmcp<5,>=3.0; extra == 'mcp'
+Requires-Dist: fastmcp<5,>=3.4.3; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 # patchright-cli
@@ -115,6 +116,78 @@ python -m patchright install chromium
 
 </details>
 
+### Docker
+
+A prebuilt image is available from GHCR:
+
+```bash
+docker pull ghcr.io/ahaimk01/patchright-cli:latest
+```
+
+By default the container runs `patchright-cli` directly, so it can be used for normal CLI commands:
+
+```bash
+docker run --rm ghcr.io/ahaimk01/patchright-cli:latest --help
+docker run --rm ghcr.io/ahaimk01/patchright-cli:latest profile-list
+```
+
+Browser sessions live inside the container, so for a sequence of standalone CLI commands keep the same container running:
+
+```bash
+docker run --rm -it \
+  --name patchright-cli \
+  -v patchright-profiles:/root/.patchright-cli \
+  --entrypoint /bin/sh \
+  ghcr.io/ahaimk01/patchright-cli:latest
+
+uv run patchright-cli open https://example.com --headless
+uv run patchright-cli snapshot
+uv run patchright-cli close
+```
+
+For MCP over stdio, set `PATCHRIGHT_CLI_MODE=mcp-stdio` and keep stdin attached. The volumes keep logins and output after the container exits:
+
+```bash
+docker run --rm -i \
+  -e PATCHRIGHT_CLI_MODE=mcp-stdio \
+  -v ./patchright:/patchright \
+  -v patchright-profiles:/root/.patchright-cli \
+  ghcr.io/ahaimk01/patchright-cli:latest
+```
+
+For a long-running MCP server over Streamable HTTP, set `PATCHRIGHT_CLI_MODE=mcp-http`:
+
+```bash
+docker run -d \
+  --name patchright-mcp \
+  -p 127.0.0.1:9090:9090 \
+  -e PATCHRIGHT_CLI_MODE=mcp-http \
+  -e PATCHRIGHT_CLI_MCP_TOKEN=replace-with-a-long-random-token \
+  -v ./patchright:/patchright \
+  -v patchright-profiles:/root/.patchright-cli \
+  ghcr.io/ahaimk01/patchright-cli:latest
+```
+
+The HTTP MCP endpoint is then available at `http://localhost:9090/mcp`. The MCP server defaults to headless mode in the image and uses `/patchright` as its filesystem root. CLI commands inside the container still need `--headless`, since there is no display.
+
+An example `compose.yml` is included in the repository:
+
+```bash
+PATCHRIGHT_CLI_MCP_TOKEN=replace-with-a-long-random-token docker compose up -d
+```
+
+Both examples publish the port on `127.0.0.1` only, but that alone doesn't stop a web page in your browser from reaching the server through DNS rebinding, so `mcp-http` refuses to start unless you pick one of three defences (see [MCP Server](#mcp-server) for details): set `PATCHRIGHT_CLI_MCP_TOKEN`; set `-e FASTMCP_HTTP_HOST_ORIGIN_PROTECTION=true` so requests must be addressed to `localhost`, `127.0.0.1` or `::1`, listing any other hostname or IP (a LAN address, a Compose service name) as a JSON array, for example `-e FASTMCP_HTTP_ALLOWED_HOSTS='["patchright-mcp", "192.168.1.20"]'`; or set `-e FASTMCP_HTTP_HOST_ORIGIN_PROTECTION=false` on purpose. A plain `docker run -e PATCHRIGHT_CLI_MODE=mcp-http` with neither variable exits with an error. The example `compose.yml` sets `FASTMCP_HTTP_HOST_ORIGIN_PROTECTION: "false"` so reverse-proxy and MCP hub setups keep working, which makes the token optional there: leave it out if your MCP client can't send an `Authorization` header. A reverse proxy with auth or an IP allowlist can stand in for the token. If you publish the port beyond loopback, protect it one of these ways: the endpoint gives full control of the browser and its saved logins.
+
+### Chrome sandbox
+
+Patchright starts Chrome with `--no-sandbox`, so by default no Chrome process is sandboxed (`chrome://sandbox` lists every one as "Not Sandboxed", on Windows too). Set `PATCHRIGHT_CLI_CHROME_SANDBOX=1` to launch Chrome with its sandbox instead. It is off by default.
+
+The variable is read by the daemon, not by each CLI command. The CLI passes its environment on when it starts the daemon, so set it before the first `open`; a daemon that is already running keeps the setting it started with until you restart it (`patchright-cli kill-all`).
+
+In Docker the image runs as root, and Chrome will not start as root with its sandbox on, so the switch also needs a non-root user (`docker run --user ...` with a writable `HOME`). Even then, Docker's default seccomp profile blocks the namespaces Chrome's Linux sandbox needs: measured on a GitHub Actions runner, as uid 1000 with the switch on, Chrome exits at launch ("Failed to move to new namespace ... Operation not permitted"). Leave the switch off in Docker; the image runs Chrome without its sandbox.
+
+How the sandbox affects bot detection has not been measured.
+
 ---
 
 ## Quick Start
@@ -154,6 +227,15 @@ graph LR
 | **CLI** (`cli.py`) | Thin client — connects, sends command, prints result, disconnects. Browser stays open. |
 | **Snapshot** (`snapshot.py`) | Playwright `aria_snapshot()` accessibility tree, annotated with sequential `[ref=eN]` handles for element targeting. |
 
+### Daemon token
+
+The daemon only listens on `127.0.0.1`, but any local process can reach that port, so every message must carry a secret token. On startup the daemon writes a fresh random token to `~/.patchright-cli/daemon-<port>.token` (one file per port, so daemons on different ports coexist), before it starts listening, and deletes the file on a clean shutdown. The CLI (and the MCP server, which runs the CLI) reads the file for its `--port` and sends the token with each command; a message with a missing or wrong token is rejected and nothing runs.
+
+- On Linux/macOS the file is created with mode `0600`. On Windows, POSIX modes do not apply, so the file is created with its own protected ACL: one full-access entry for your user account and nothing inherited from `~/.patchright-cli`, whatever that directory grants. If the daemon cannot create the file that way it does not start.
+- A daemon holds `~/.patchright-cli/daemon-<port>.lock` while it runs, so only one daemon per port ever writes that port's token; a second daemon started on the same port exits without touching it. The lock file stays after shutdown and is harmless (the OS releases the lock when the process exits).
+- Run the CLI as the same user, with the same home directory, as the daemon. In Docker the MCP server and daemon share a user and `HOME`, so this holds.
+- An older CLI talking to a newer daemon gets an error saying the daemon requires an auth token: upgrade, or stop the daemon (`patchright-cli kill-all` from the newer install, or end the process). A newer CLI talking to an older daemon finds no token file and sends none, which the older daemon accepts.
+
 ---
 
 <details>
@@ -385,15 +467,27 @@ pip install 'patchright-cli[mcp]'
 # stdio (default)
 patchright-cli mcp
 
-# Streamable HTTP
-patchright-cli mcp --http --host=127.0.0.1 --port=8000
+# Streamable HTTP (needs a token or an explicit Host/Origin choice, see below)
+PATCHRIGHT_CLI_MCP_TOKEN=replace-with-a-long-random-token patchright-cli mcp --http --host=127.0.0.1 --port=8000
 ```
 
 ![How a remote MCP call reaches Chrome](docs/mcp-architecture.svg)
 
 The HTTP endpoint is `/mcp`. Set `PATCHRIGHT_CLI_MCP_TOKEN` to require `Authorization: Bearer <token>` on every request, and always set it before binding to `0.0.0.0`.
 
-File paths passed to MCP tools (uploads, state and cookie files, screenshot/PDF/snapshot output, profile directories) must be absolute and beneath the MCP root, so a client cannot reach arbitrary host files. Outputs without a path land in `<root>/output/`, which `browser_delete_output` can clean up. `patchright_eval` and `patchright_run_code` still run arbitrary JavaScript in the page, so protect HTTP deployments regardless.
+FastMCP's Host and Origin checks are off by default, so binding to `127.0.0.1` alone does not stop a web page from reaching a server without a token through DNS rebinding. `patchright-cli mcp --http` therefore refuses to start, whatever the bind host, unless `PATCHRIGHT_CLI_MCP_TOKEN` is set or `FASTMCP_HTTP_HOST_ORIGIN_PROTECTION` is set to a value FastMCP accepts (an empty value counts as unset). Pick one:
+
+- Set `PATCHRIGHT_CLI_MCP_TOKEN`.
+- Set `FASTMCP_HTTP_HOST_ORIGIN_PROTECTION=true` to accept only requests addressed to `localhost`, `127.0.0.1` or `::1` (421 otherwise) and reject foreign `Origin` headers (403). To allow another hostname or IP, list it as a JSON array, for example `FASTMCP_HTTP_ALLOWED_HOSTS='["mcp.lan"]'`.
+- Set `FASTMCP_HTTP_HOST_ORIGIN_PROTECTION=false` on purpose, for example behind a reverse proxy with auth or an IP allowlist.
+
+A reverse proxy with auth or an IP allowlist can stand in for the token. The stdio transport needs none of this.
+
+One token covers one trust domain. Any client holding it can open, read or close any session by name, and `patchright_kill_all` closes them all. Clients that must not reach each other's browsers need separate servers, each with its own token. Two servers on one host share the daemon unless their `PATCHRIGHT_CLI_MCP_DAEMON_PORT` values differ, and they always share saved profiles in `~/.patchright-cli/profiles`. For full separation, run each server in its own container or as a different OS user.
+
+File paths passed to MCP tools (uploads, state and cookie files, screenshot/PDF/snapshot output, profile directories) must be absolute and beneath the MCP root, so a client cannot reach arbitrary host files. Outputs without a path land in `<root>/output/`, which `browser_delete_output` can clean up. `patchright_eval` and `patchright_run_code` still run arbitrary JavaScript in the page, so protect HTTP deployments regardless. The MCP server never loads a `.patchright-cli/config.json`, since clients can write files beneath the root; tool arguments carry every option.
+
+URLs passed to `patchright_open`, `patchright_goto` and `patchright_tab_new` must be `http`, `https` or `about:blank`, so the browser cannot read local files through `file://` (allowed again with `PATCHRIGHT_CLI_MCP_UNRESTRICTED_FILESYSTEM=1`). The server sends `--web-only` with every call, so the daemon holds the navigations it starts itself to the same rule (a link `patchright_click` follows, `patchright_go_back`, `patchright_go_forward`), also in a session you opened with the plain CLI, whose own commands stay unrestricted. A client can still read whatever such a session already shows, a `file://` page included, so to keep your own CLI sessions out of reach give the server its own daemon with `PATCHRIGHT_CLI_MCP_DAEMON_PORT`. Sessions the server opens keep the option, and the daemon sends a frame in them that still lands on another scheme back to `about:blank`. The browser also stays off `169.254.0.0/16` and `fe80::/10`, where cloud metadata services hand out credentials: `patchright_open`, `patchright_goto`, `patchright_tab_new` and `patchright_attach` refuse those hosts (the proxy too), and a frame that still lands there through a redirect or a script is sent back to `about:blank`. Set `PATCHRIGHT_CLI_MCP_BLOCK_NETWORKS=private` to refuse every address that is not globally routable as well (loopback, RFC 1918, CGNAT, unique local), or `none` to turn the check off. It never intercepts requests, so the HTTP cache stays on, and in `attach --context=host` sessions it only checks URLs before navigating, leaving the Host's other pages alone. That also means it is not a hard boundary: images, `fetch()` and WebSockets are not checked (CORS still hides their responses from the page), and a DNS server that answers differently each time can get past it. For that, restrict the container's or host's outbound traffic.
 
 | Variable | Default | Effect |
 |---|---|---|
@@ -402,6 +496,9 @@ File paths passed to MCP tools (uploads, state and cookie files, screenshot/PDF/
 | `PATCHRIGHT_CLI_MCP_UNRESTRICTED_FILESYSTEM` | unset | `1` drops the path check and enables `patchright_install_skills` |
 | `PATCHRIGHT_CLI_MCP_HEADLESS` | unset (headed) | `1` makes `patchright_open` default to headless, for hosts without a display |
 | `PATCHRIGHT_CLI_MCP_DAEMON_PORT` | `9321` | Daemon port the tools talk to |
+| `PATCHRIGHT_CLI_MCP_BLOCK_NETWORKS` | `link-local` | Address ranges the browser may not reach: `link-local`, `private` or `none` |
+| `FASTMCP_HTTP_HOST_ORIGIN_PROTECTION` | unset (off) | `true` rejects requests whose Host is not loopback or allowed, and foreign Origins; without a token, HTTP mode needs it set to `true` or `false` |
+| `FASTMCP_HTTP_ALLOWED_HOSTS` | unset | JSON array of extra hostnames the Host check accepts |
 
 ### Skill docs
 

{patchright_cli-0.8.0 → patchright_cli-0.9.0}/README.md

@@ -79,6 +79,78 @@ python -m patchright install chromium
 
 </details>
 
+### Docker
+
+A prebuilt image is available from GHCR:
+
+```bash
+docker pull ghcr.io/ahaimk01/patchright-cli:latest
+```
+
+By default the container runs `patchright-cli` directly, so it can be used for normal CLI commands:
+
+```bash
+docker run --rm ghcr.io/ahaimk01/patchright-cli:latest --help
+docker run --rm ghcr.io/ahaimk01/patchright-cli:latest profile-list
+```
+
+Browser sessions live inside the container, so for a sequence of standalone CLI commands keep the same container running:
+
+```bash
+docker run --rm -it \
+  --name patchright-cli \
+  -v patchright-profiles:/root/.patchright-cli \
+  --entrypoint /bin/sh \
+  ghcr.io/ahaimk01/patchright-cli:latest
+
+uv run patchright-cli open https://example.com --headless
+uv run patchright-cli snapshot
+uv run patchright-cli close
+```
+
+For MCP over stdio, set `PATCHRIGHT_CLI_MODE=mcp-stdio` and keep stdin attached. The volumes keep logins and output after the container exits:
+
+```bash
+docker run --rm -i \
+  -e PATCHRIGHT_CLI_MODE=mcp-stdio \
+  -v ./patchright:/patchright \
+  -v patchright-profiles:/root/.patchright-cli \
+  ghcr.io/ahaimk01/patchright-cli:latest
+```
+
+For a long-running MCP server over Streamable HTTP, set `PATCHRIGHT_CLI_MODE=mcp-http`:
+
+```bash
+docker run -d \
+  --name patchright-mcp \
+  -p 127.0.0.1:9090:9090 \
+  -e PATCHRIGHT_CLI_MODE=mcp-http \
+  -e PATCHRIGHT_CLI_MCP_TOKEN=replace-with-a-long-random-token \
+  -v ./patchright:/patchright \
+  -v patchright-profiles:/root/.patchright-cli \
+  ghcr.io/ahaimk01/patchright-cli:latest
+```
+
+The HTTP MCP endpoint is then available at `http://localhost:9090/mcp`. The MCP server defaults to headless mode in the image and uses `/patchright` as its filesystem root. CLI commands inside the container still need `--headless`, since there is no display.
+
+An example `compose.yml` is included in the repository:
+
+```bash
+PATCHRIGHT_CLI_MCP_TOKEN=replace-with-a-long-random-token docker compose up -d
+```
+
+Both examples publish the port on `127.0.0.1` only, but that alone doesn't stop a web page in your browser from reaching the server through DNS rebinding, so `mcp-http` refuses to start unless you pick one of three defences (see [MCP Server](#mcp-server) for details): set `PATCHRIGHT_CLI_MCP_TOKEN`; set `-e FASTMCP_HTTP_HOST_ORIGIN_PROTECTION=true` so requests must be addressed to `localhost`, `127.0.0.1` or `::1`, listing any other hostname or IP (a LAN address, a Compose service name) as a JSON array, for example `-e FASTMCP_HTTP_ALLOWED_HOSTS='["patchright-mcp", "192.168.1.20"]'`; or set `-e FASTMCP_HTTP_HOST_ORIGIN_PROTECTION=false` on purpose. A plain `docker run -e PATCHRIGHT_CLI_MODE=mcp-http` with neither variable exits with an error. The example `compose.yml` sets `FASTMCP_HTTP_HOST_ORIGIN_PROTECTION: "false"` so reverse-proxy and MCP hub setups keep working, which makes the token optional there: leave it out if your MCP client can't send an `Authorization` header. A reverse proxy with auth or an IP allowlist can stand in for the token. If you publish the port beyond loopback, protect it one of these ways: the endpoint gives full control of the browser and its saved logins.
+
+### Chrome sandbox
+
+Patchright starts Chrome with `--no-sandbox`, so by default no Chrome process is sandboxed (`chrome://sandbox` lists every one as "Not Sandboxed", on Windows too). Set `PATCHRIGHT_CLI_CHROME_SANDBOX=1` to launch Chrome with its sandbox instead. It is off by default.
+
+The variable is read by the daemon, not by each CLI command. The CLI passes its environment on when it starts the daemon, so set it before the first `open`; a daemon that is already running keeps the setting it started with until you restart it (`patchright-cli kill-all`).
+
+In Docker the image runs as root, and Chrome will not start as root with its sandbox on, so the switch also needs a non-root user (`docker run --user ...` with a writable `HOME`). Even then, Docker's default seccomp profile blocks the namespaces Chrome's Linux sandbox needs: measured on a GitHub Actions runner, as uid 1000 with the switch on, Chrome exits at launch ("Failed to move to new namespace ... Operation not permitted"). Leave the switch off in Docker; the image runs Chrome without its sandbox.
+
+How the sandbox affects bot detection has not been measured.
+
 ---
 
 ## Quick Start
@@ -118,6 +190,15 @@ graph LR
 | **CLI** (`cli.py`) | Thin client — connects, sends command, prints result, disconnects. Browser stays open. |
 | **Snapshot** (`snapshot.py`) | Playwright `aria_snapshot()` accessibility tree, annotated with sequential `[ref=eN]` handles for element targeting. |
 
+### Daemon token
+
+The daemon only listens on `127.0.0.1`, but any local process can reach that port, so every message must carry a secret token. On startup the daemon writes a fresh random token to `~/.patchright-cli/daemon-<port>.token` (one file per port, so daemons on different ports coexist), before it starts listening, and deletes the file on a clean shutdown. The CLI (and the MCP server, which runs the CLI) reads the file for its `--port` and sends the token with each command; a message with a missing or wrong token is rejected and nothing runs.
+
+- On Linux/macOS the file is created with mode `0600`. On Windows, POSIX modes do not apply, so the file is created with its own protected ACL: one full-access entry for your user account and nothing inherited from `~/.patchright-cli`, whatever that directory grants. If the daemon cannot create the file that way it does not start.
+- A daemon holds `~/.patchright-cli/daemon-<port>.lock` while it runs, so only one daemon per port ever writes that port's token; a second daemon started on the same port exits without touching it. The lock file stays after shutdown and is harmless (the OS releases the lock when the process exits).
+- Run the CLI as the same user, with the same home directory, as the daemon. In Docker the MCP server and daemon share a user and `HOME`, so this holds.
+- An older CLI talking to a newer daemon gets an error saying the daemon requires an auth token: upgrade, or stop the daemon (`patchright-cli kill-all` from the newer install, or end the process). A newer CLI talking to an older daemon finds no token file and sends none, which the older daemon accepts.
+
 ---
 
 <details>
@@ -349,15 +430,27 @@ pip install 'patchright-cli[mcp]'
 # stdio (default)
 patchright-cli mcp
 
-# Streamable HTTP
-patchright-cli mcp --http --host=127.0.0.1 --port=8000
+# Streamable HTTP (needs a token or an explicit Host/Origin choice, see below)
+PATCHRIGHT_CLI_MCP_TOKEN=replace-with-a-long-random-token patchright-cli mcp --http --host=127.0.0.1 --port=8000
 ```
 
 ![How a remote MCP call reaches Chrome](docs/mcp-architecture.svg)
 
 The HTTP endpoint is `/mcp`. Set `PATCHRIGHT_CLI_MCP_TOKEN` to require `Authorization: Bearer <token>` on every request, and always set it before binding to `0.0.0.0`.
 
-File paths passed to MCP tools (uploads, state and cookie files, screenshot/PDF/snapshot output, profile directories) must be absolute and beneath the MCP root, so a client cannot reach arbitrary host files. Outputs without a path land in `<root>/output/`, which `browser_delete_output` can clean up. `patchright_eval` and `patchright_run_code` still run arbitrary JavaScript in the page, so protect HTTP deployments regardless.
+FastMCP's Host and Origin checks are off by default, so binding to `127.0.0.1` alone does not stop a web page from reaching a server without a token through DNS rebinding. `patchright-cli mcp --http` therefore refuses to start, whatever the bind host, unless `PATCHRIGHT_CLI_MCP_TOKEN` is set or `FASTMCP_HTTP_HOST_ORIGIN_PROTECTION` is set to a value FastMCP accepts (an empty value counts as unset). Pick one:
+
+- Set `PATCHRIGHT_CLI_MCP_TOKEN`.
+- Set `FASTMCP_HTTP_HOST_ORIGIN_PROTECTION=true` to accept only requests addressed to `localhost`, `127.0.0.1` or `::1` (421 otherwise) and reject foreign `Origin` headers (403). To allow another hostname or IP, list it as a JSON array, for example `FASTMCP_HTTP_ALLOWED_HOSTS='["mcp.lan"]'`.
+- Set `FASTMCP_HTTP_HOST_ORIGIN_PROTECTION=false` on purpose, for example behind a reverse proxy with auth or an IP allowlist.
+
+A reverse proxy with auth or an IP allowlist can stand in for the token. The stdio transport needs none of this.
+
+One token covers one trust domain. Any client holding it can open, read or close any session by name, and `patchright_kill_all` closes them all. Clients that must not reach each other's browsers need separate servers, each with its own token. Two servers on one host share the daemon unless their `PATCHRIGHT_CLI_MCP_DAEMON_PORT` values differ, and they always share saved profiles in `~/.patchright-cli/profiles`. For full separation, run each server in its own container or as a different OS user.
+
+File paths passed to MCP tools (uploads, state and cookie files, screenshot/PDF/snapshot output, profile directories) must be absolute and beneath the MCP root, so a client cannot reach arbitrary host files. Outputs without a path land in `<root>/output/`, which `browser_delete_output` can clean up. `patchright_eval` and `patchright_run_code` still run arbitrary JavaScript in the page, so protect HTTP deployments regardless. The MCP server never loads a `.patchright-cli/config.json`, since clients can write files beneath the root; tool arguments carry every option.
+
+URLs passed to `patchright_open`, `patchright_goto` and `patchright_tab_new` must be `http`, `https` or `about:blank`, so the browser cannot read local files through `file://` (allowed again with `PATCHRIGHT_CLI_MCP_UNRESTRICTED_FILESYSTEM=1`). The server sends `--web-only` with every call, so the daemon holds the navigations it starts itself to the same rule (a link `patchright_click` follows, `patchright_go_back`, `patchright_go_forward`), also in a session you opened with the plain CLI, whose own commands stay unrestricted. A client can still read whatever such a session already shows, a `file://` page included, so to keep your own CLI sessions out of reach give the server its own daemon with `PATCHRIGHT_CLI_MCP_DAEMON_PORT`. Sessions the server opens keep the option, and the daemon sends a frame in them that still lands on another scheme back to `about:blank`. The browser also stays off `169.254.0.0/16` and `fe80::/10`, where cloud metadata services hand out credentials: `patchright_open`, `patchright_goto`, `patchright_tab_new` and `patchright_attach` refuse those hosts (the proxy too), and a frame that still lands there through a redirect or a script is sent back to `about:blank`. Set `PATCHRIGHT_CLI_MCP_BLOCK_NETWORKS=private` to refuse every address that is not globally routable as well (loopback, RFC 1918, CGNAT, unique local), or `none` to turn the check off. It never intercepts requests, so the HTTP cache stays on, and in `attach --context=host` sessions it only checks URLs before navigating, leaving the Host's other pages alone. That also means it is not a hard boundary: images, `fetch()` and WebSockets are not checked (CORS still hides their responses from the page), and a DNS server that answers differently each time can get past it. For that, restrict the container's or host's outbound traffic.
 
 | Variable | Default | Effect |
 |---|---|---|
@@ -366,6 +459,9 @@ File paths passed to MCP tools (uploads, state and cookie files, screenshot/PDF/
 | `PATCHRIGHT_CLI_MCP_UNRESTRICTED_FILESYSTEM` | unset | `1` drops the path check and enables `patchright_install_skills` |
 | `PATCHRIGHT_CLI_MCP_HEADLESS` | unset (headed) | `1` makes `patchright_open` default to headless, for hosts without a display |
 | `PATCHRIGHT_CLI_MCP_DAEMON_PORT` | `9321` | Daemon port the tools talk to |
+| `PATCHRIGHT_CLI_MCP_BLOCK_NETWORKS` | `link-local` | Address ranges the browser may not reach: `link-local`, `private` or `none` |
+| `FASTMCP_HTTP_HOST_ORIGIN_PROTECTION` | unset (off) | `true` rejects requests whose Host is not loopback or allowed, and foreign Origins; without a token, HTTP mode needs it set to `true` or `false` |
+| `FASTMCP_HTTP_ALLOWED_HOSTS` | unset | JSON array of extra hostnames the Host check accepts |
 
 ### Skill docs
 

patchright_cli-0.9.0/compose.yml

@@ -0,0 +1,34 @@
+services:
+  patchright-mcp:
+    image: ghcr.io/ahaimk01/patchright-cli:latest
+    container_name: patchright-mcp
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:9090:9090"
+    environment:
+      PATCHRIGHT_CLI_MODE: mcp-http
+      PATCHRIGHT_CLI_MCP_HEADLESS: "1"
+      PATCHRIGHT_CLI_MCP_ROOT: /patchright
+      # HTTP mode refuses to start unless you pick a defence against DNS rebinding:
+      # (a) set PATCHRIGHT_CLI_MCP_TOKEN (clients send an Authorization header);
+      # (b) set FASTMCP_HTTP_HOST_ORIGIN_PROTECTION to "true", so only requests
+      #     addressed to localhost, 127.0.0.1 or ::1 are accepted, and list any other
+      #     name or IP (such as this service's name) in FASTMCP_HTTP_ALLOWED_HOSTS; or
+      # (c) leave it "false" on purpose. This file does (c) so reverse-proxy and MCP
+      #     hub setups keep working: a reverse proxy with auth or an IP allowlist can
+      #     stand in for the token. Leave the token unset if your client can't send one.
+      PATCHRIGHT_CLI_MCP_TOKEN: ${PATCHRIGHT_CLI_MCP_TOKEN:-}
+      FASTMCP_HTTP_HOST_ORIGIN_PROTECTION: "false"
+      # FASTMCP_HTTP_ALLOWED_HOSTS: '["patchright-mcp", "192.168.1.20"]'
+      # Set to 1 only if you intentionally want MCP tools to access paths
+      # outside PATCHRIGHT_CLI_MCP_ROOT.
+      # PATCHRIGHT_CLI_MCP_UNRESTRICTED_FILESYSTEM: "1"
+      # PATCHRIGHT_CLI_MCP_PORT: "9090"
+    volumes:
+      # Files made available to MCP tools, plus generated output under ./patchright/output.
+      - ./patchright:/patchright
+      # Persist named browser profiles and login state across container updates.
+      - patchright-profiles:/root/.patchright-cli
+
+volumes:
+  patchright-profiles:

{patchright_cli-0.8.0 → patchright_cli-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "patchright-cli"
-version = "0.8.0"
+version = "0.9.0"
 description = "Anti-detect browser automation CLI using Patchright (undetected Playwright fork)"
 license = "Apache-2.0"
 requires-python = ">=3.10"
@@ -27,6 +27,8 @@ dependencies = [
     "pyyaml",
     "click",
     "aiohttp>=3.9",
+    # Windows ACL for the daemon token file
+    "pywin32>=306; sys_platform == 'win32'",
 ]
 
 [project.urls]
@@ -55,20 +57,20 @@ markers = [
 
 [project.optional-dependencies]
 mcp = [
-    "fastmcp>=3.0,<5",
+    "fastmcp>=3.4.3,<5",
 ]
 dev = [
     "pytest>=8.0",
     "pytest-asyncio>=0.23",
     "pre-commit",
-    "fastmcp>=3.0,<5",
+    "fastmcp>=3.4.3,<5",
 ]
 
 [dependency-groups]
 dev = [
     "pytest>=8.0",
     "pytest-asyncio>=0.23",
-    "fastmcp>=3.0,<5",
+    "fastmcp>=3.4.3,<5",
 ]
 
 [tool.ruff]

{patchright_cli-0.8.0 → patchright_cli-0.9.0}/src/patchright_cli/__init__.py

@@ -1,3 +1,3 @@
 """patchright-cli — Undetected browser automation CLI using Patchright."""
 
-__version__ = "0.8.0"
+__version__ = "0.9.0"