patchright-cli

Patchright-powered browser control for AI agents.

patchright-cli gives agents a simple command-line interface for driving a real Google Chrome browser. It is designed for agent workflows that need to inspect pages, click controls, fill forms, capture screenshots, evaluate page state, and keep named browser sessions alive across commands.

The CLI supports many of the same day-to-day browser operations that agents use from Playwright-style tools, but routes browser automation through Patchright and system Google Chrome. That matters on sites that detect and block the stock Playwright/CDP automation shape. Agents can keep using a familiar CLI workflow while the browser presents less like a default automation harness.

Highlights

• Real Google Chrome with Patchright as the browser driver.
• Headful sessions by default, even in containers through Xvfb.
• Playwright-style CLI commands for navigation, snapshots, clicks, typing, screenshots, tracing, storage state, video, request controls, and custom page code.
• Named browser sessions that survive across agent commands.
• Per-session CDP metadata for advanced diagnostics when the CLI surface is not enough.
• A focused runtime that can run in a container or directly on a Linux sandbox with pinned browser/runtime versions and blocked browser-install escape hatches.

Quick Start

Once an agent has shell access inside the runtime environment, it drives the browser directly:

patchright-cli -s=demo open https://example.com

patchright-cli -s=demo snapshot

patchright-cli -s=demo click e3

patchright-cli -s=demo close

Why This Exists

AI agents need browser control that is both ergonomic and resilient:

• A real Google Chrome browser, not Chrome-for-Testing or generic Chromium.
• Headful browser sessions by default, with Xvfb providing the display inside containers.
• Playwright-style commands for snapshots, clicks, typing, navigation, screenshots, storage state, tracing, videos, network controls, and custom page code.
• Named sessions so an agent can open a browser once and keep interacting with it.
• A local CDP port recorded per session for lower-level inspection when the CLI surface is not enough.
• Browser install and browser-selection paths disabled so agents stay on the known-good Patchright plus Chrome runtime.

The project is intentionally focused on the CLI runtime and its container image. It does not include platform orchestration, plugins, or application-specific agent infrastructure.

Use Cases

• Agent browser sessions that need to inspect and operate real websites.
• Sites where stock Playwright/CDP automation is blocked or unreliable.
• Browser QA and debugging from a CLI-first agent workflow.
• Long-lived named sessions for multi-step web tasks.
• Containerized or Linux-sandbox browser control where Chrome still runs headful.
• Advanced browser diagnostics through the recorded local CDP port.

Setup Model

patchright-cli can be used in two ways:

• Container runtime: build the image from this repo and run the agent inside that container. The image installs Google Chrome, Node, Patchright, Playwright, Xvfb, the CLI wrappers, and the runtime environment variables.
• Direct Linux runtime: install the same pinned components on an Ubuntu/Debian-style machine or sandbox, install the scripts from runtime/bin into /usr/local/bin, install runtime/lib/patchright-cli into /usr/local/lib/patchright-cli, and run commands through entrypoint or an equivalent Xvfb/env bootstrap.

The container is the canonical, reproducible setup. Direct Linux installs should mirror the Containerfile: system Google Chrome, Xvfb, Node, Patchright, Playwright, the CLI wrappers, and the PLAYWRIGHT_* / XDG_* environment.

Runtime Pins

• Base OS: Debian 13 trixie
• Node: 24.16.0
• Playwright: 1.59.1
• Patchright: 1.59.4
• Google Chrome: 149.0.7827.155

Chrome is installed from Google's stable .deb at /opt/google/chrome/chrome and then version-checked during image build.

Repository Layout

• runtime/bin/patchright-cli: Patchright CLI wrapper and command guardrails.
• runtime/bin/playwright-cli: Compatibility wrapper for agents that already call playwright-cli.
• runtime/bin/xvfb-runner: Display lifecycle helper for headed Chrome in containers.
• runtime/lib/patchright-cli: CLI daemon and browser tools.
• skills/patchright-cli: Agent-facing instructions for Patchright-first browser control.
• skills/playwright-cli: Agent-facing command reference for the Playwright-style CLI surface.
• Containerfile: Minimal browser runtime image.
• scripts/smoke-container.sh: Container smoke test for Chrome, Xvfb, CLI commands, sessions, and CDP.

Build And Test

For local development of this repo:

mise run test

That builds localhost/patchright-cli:dev and runs a container smoke test that verifies:

• Node, Playwright, Patchright, and Chrome versions
• Xvfb startup
• patchright-cli --help
• playwright-cli --help
• install commands are blocked
• patchright-cli open about:blank
• the session JSON contains a CDP port
• Chrome responds on that CDP port

Use a different image name with:

PATCHRIGHT_CLI_IMAGE=ghcr.io/gvkhna/patchright-cli:dev mise run test

Run

The important interface is the CLI available inside the runtime shell:

patchright-cli --help
playwright-cli --help

Open a page in a named, headful browser session:

patchright-cli -s=demo open https://example.com

Inspect and operate the page:

patchright-cli -s=demo snapshot
patchright-cli -s=demo click e3
patchright-cli -s=demo type "search query"
patchright-cli -s=demo close

playwright-cli exposes the same command workflow for agents that are already prompted around Playwright-style browser commands:

playwright-cli -s=demo open https://example.com
playwright-cli -s=demo snapshot
playwright-cli -s=demo click e3
playwright-cli -s=demo close

To try the container manually, build it and open an interactive shell. For example, with Docker:

docker build -f Containerfile -t patchright-cli:dev .
docker run --rm -it patchright-cli:dev bash

Podman works the same way with podman build and podman run.

CDP Session Details

Patchright CLI is the primary agent interface, but each browser session also records Chrome's local CDP port. That gives advanced agents an escape hatch for diagnostics and lower-level browser inspection without making stock CDP automation the normal control path.

Session metadata is stored under:

$PLAYWRIGHT_DAEMON_SESSION_DIR/<workspace-hash>/<session>.session

The default path in the image is:

/var/tmp/patchright-cli-cache/ms-playwright/daemon

Each session file includes:

{
  "browser": {
    "launchOptions": {
      "cdpPort": 12345
    }
  }
}

Agents can read that port and connect to Chrome at:

http://127.0.0.1:<cdpPort>/json/version

Important Env Vars

• PLAYWRIGHT_BROWSERS_PATH=/opt/patchright-cli/.playwright
• PLAYWRIGHT_MCP_BROWSER=chrome
• PLAYWRIGHT_MCP_EXECUTABLE_PATH=/opt/google/chrome/chrome
• PLAYWRIGHT_DAEMON_SESSION_DIR=/var/tmp/patchright-cli-cache/ms-playwright/daemon
• PATCHRIGHT_CLI_CACHE_DIR=/var/tmp/patchright-cli-cache
• XDG_CACHE_HOME, XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME
• XDG_RUNTIME_DIR=/run/patchright-cli/xdg-runtime
• NODE_PATH=/usr/local/lib/node_modules:/usr/local/lib/node_modules/patchright/node_modules
• DISPLAY=:99.0

xvfb-runner owns the display lifecycle in the container entrypoint.

Star History

If this project helps your agent browser workflows, starring the repo helps other developers find it.