rechrome — Remote Chrome

CLI proxy for running Playwright commands on a shared remote browser. Run a server on a machine with a browser, then send commands from any client.

Built on top of playwright-multi-tab — a patched Playwright fork with multi-tab and multi-session browser automation.

Features

• Session isolation — clients are automatically namespaced by git repo or hostname
• File transfer — screenshots and PDFs are automatically downloaded to the client
• Hot-reload config — .env.local changes are picked up without restart
• Security — bearer auth, path traversal protection, env allowlisting for child processes

Prerequisites

• Bun ≥ 1.0
• playwright-cli (works out of the box)

💡 Recommended: For full multi-tab and multi-session support, install playwright-multi-tab and set PLAYWRIGHT_CLI=playwright-cli-multi-tab in your .env.local.

Install

# From npm
bunx rechrome --help

# Or clone and link globally
git clone https://github.com/snomiao/rechrome.git
cd rechrome
bun install
bun link

Now rechrome (or rech) is available globally.

Quick start

1. Start the server

On the machine with a browser:

rechrome serve

This auto-generates a connection URL in .env.local (with an auth key).

2. Run commands from a client

Copy the RECHROME_URL from the server's .env.local to the client's project .env.local:

# .env.local in your project directory
RECHROME_URL=http://YOUR_KEY@server-host:13775

# Open a URL
rech open https://example.com

# Take a screenshot
rech screenshot

# List open tabs
rech tab-list

# Any playwright-cli command works
rech --help

rechrome walks up from the current working directory to find .env.local, so each project can have its own connection URL, Chrome profile, and extension token.

Configuration

Copy .env.example to .env.local and edit:

cp .env.example .env.local

| Variable | Description | Default | | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------- | | RECHROME_URL | Connection URL (auto-generated by rech serve). Also accepts ?extension_id=, ?token=, ?profile= query params | — | | PLAYWRIGHT_CLI | Path to playwright-cli binary (recommended: playwright-cli-multi-tab for full multi-tab support) | playwright-cli | | RECH_HOST | Server bind address | 127.0.0.1 | | PLAYWRIGHT_MCP_EXTENSION_ID | Chrome extension ID (client overrides server) | — | | PLAYWRIGHT_MCP_EXTENSION_TOKEN | Chrome extension token — profile-specific, get it from the extension's status page (client overrides server) | — | | PLAYWRIGHT_MCP_USER_DATA_DIR | Chrome user data directory — use to pin connections to a specific Chrome install (client overrides server) | — | | PLAYWRIGHT_MCP_PROFILE_DIRECTORY | Chrome profile — accepts directory name (Profile 2), display name (Snowstar), or email ([email protected]) (client overrides server) | — |

Multi-profile tip: Each project's .env.local can specify a different Chrome profile via the ?profile= query param in RECHROME_URL. The server resolves display names and email addresses to the actual Chrome profile directory automatically (reads ~/Library/Application Support/Google/Chrome/Local State).

# .env.local for a work project
RECHROME_URL="http://KEY@server:13775?token=TOKEN&extension_id=EXT_ID&profile=taku%40company.com"

Shell-set PLAYWRIGHT_MCP_* variables take priority over .env.local, so you can always override per-command without editing files.

Remote access

By default the server binds to 127.0.0.1 (localhost only). For remote access, either:

• Use an SSH tunnel: ssh -L 13775:localhost:13775 server-host
• Or set RECH_HOST=0.0.0.0 (⚠️ ensure network is trusted — traffic is plain HTTP)

Session namespacing

Each client gets an isolated browser session based on:

1. Git repo URL + branch (if in a git repo)
2. Hostname + working directory (fallback)

Clients can also pass -s=name to create named sub-sessions within their namespace.

Development

bun install
bun test

Why we fork playwright

rechrome depends on playwright-multi-tab, which is a fork of microsoft/playwright. We maintain it because the upstream does not yet support several features required for rechrome's use case:

| Feature | Our change | Status | |---------|-----------|--------| | Multi-tab control | playwright-multi-tab fork adds tab-new, tab-list, tab-select, tab-close commands and a persistent session daemon | Not in upstream | | PLAYWRIGHT_MCP_EXTENSION_ID | Lets you specify a custom extension ID instead of the hardcoded default | Not in upstream | | PLAYWRIGHT_MCP_PROFILE_DIRECTORY | Passes --profile-directory to Chrome so the correct system profile is used; auto-detects the Chrome user data dir by OS | Not in upstream |

We also fork playwright-mcp (inside playwright-multi-tab/lib/playwright-mcp) to support the custom extension ID and multi-tab session routing.

PRs upstream are welcome. Once these features land in the official packages we will drop the forks.

Related

• playwright-multi-tab — the underlying Playwright fork powering rechrome's multi-tab and multi-session browser control
• microsoft/playwright — upstream

License

MIT