Remote Access

Control a Chrome browser on any machine from anywhere over the internet. No VPN, no firewall rules, no port forwarding.

The simplest way to give a remote agent access to your browser is the Remote control button (light-blue cloud) in the Playwriter toolbar. It requires no playwriter install on your machine, only the extension. The extension itself opens a secret tunnel. The agent sees every Playwriter tab and can open new ones.

Click the Remote control button and confirm that the agent may read and control your browser. Read more about security.
A prompt containing the secret URL is copied to your clipboard. Paste it to the agent.
The agent runs, on its own machine:

12playwriter session new --remote <id>
playwriter -s 1 -e "state.page = context.pages()[0]; console.log(await state.page.title())"

Open the Remote ON dropdown in any Playwriter tab and click Stop sharing anytime to revoke access. The URL dies instantly and is never reused. Tabs the agent opened are detached and left open.

Remote control is not a security sandbox. The agent gets the same access as a local Playwriter agent, so it must be fully trusted. A short denylist blocks only whole-profile cookie APIs and cache clears.

Watch and click from any browser

The same link is also a page. Open it and you get a live view of the tab where sharing started, streamed frame by frame, with a URL bar and a Take control button for clicking, scrolling, and typing.

That means you can share with a person, not only an agent, and no install is needed on either side.

The tunnel id starts in the URL fragment (#xxx), so the initial viewer-page request and Referer omit it. The viewer JavaScript then uses the id to connect to the tunnel hostname, which the tunnel service and Cloudflare necessarily process.

The stream keeps running when the sharer switches tabs. Playwriter holds a debugger attachment on the shared tab, which stops Chrome from backgrounding it, so frames keep arriving at the same rate.

The URL grants broad browser automation access. A malicious recipient may use CDP capabilities beyond the visible page. Never share it with anyone you do not fully trust, and never post it in public channels. Revoke it with the button when the agent is done. The link also dies when you close your browser.

Remote traffic can include screenshots, page content, URLs, input events, network data, cookies, authentication data, and browser storage. Payloads are routed in memory and are not stored by Playwriter. Read the privacy policy for the complete disclosure.

Typical use case: you are logged into a website and want an agent (Devin, a cloud bot, a teammate's CLI agent) to do work in your authenticated session without ever sharing a password.

The rest of this page covers the full-relay setup: exposing your entire relay server with playwriter serve + traforo, which gives a remote machine access to all controlled tabs and requires playwriter installed on the host.

How it works

Playwriter's relay server runs on the host machine alongside Chrome. A traforo tunnel exposes it to the internet through Cloudflare, giving you a secure public URL. The remote machine connects through this URL to control Chrome.

┌────────────────────────────────────────────────────────────────────────────────────────┐
│  HOST MACHINE (has Chrome)                                                             │
│                                                                                        │
│  Chrome + Extension <────── local WS ──────> Relay Server :19988                       │
│                                                    ^                                   │
│                                                    │ local                             │
│                                                    v                                   │
│                                               Traforo Client                           │
│                                                    │                                   │
└────────────────────────────────────────────────────┼───────────────────────────────────┘
                                                     │ outbound WS
                                                     v
                                            ┌─────────────────┐
                                            │   Cloudflare    │
                                            │   Durable Object│
                                            │                 │
                                            │   https://{id}- │
                                            │   tunnel.       │
                                            │   traforo.dev   │
                                            └────────┬────────┘
                                                     │
                                                     v
┌────────────────────────────────────────────────────────────────────────────────────────┐
│  REMOTE MACHINE (CLI or MCP)                                                           │
│                                                                                        │
│  playwriter -s 1 -e "await state.page.goto(url)"                                       │
│                                                                                        │
│  PLAYWRITER_HOST=https://{id}-tunnel.traforo.dev                                       │
│  PLAYWRITER_TOKEN=&lt;secret&gt;                                                       │
└────────────────────────────────────────────────────────────────────────────────────────┘

Traforo proxies both HTTP and WebSocket connections, which is critical because playwriter uses WebSockets for real-time CDP communication.

Host machine setup

The host machine runs Chrome with the playwriter extension installed.

Install Playwriter from the Chrome Web Store
Click the extension icon on any tab you want to make controllable
Start the relay server with a tunnel:

1npx -y traforo -p 19988 -t my-machine -- npx -y playwriter serve --token MY_SECRET_TOKEN

This starts playwriter serve on port 19988 with token auth, and creates a traforo tunnel at https://my-machine-tunnel.traforo.dev. Keep this terminal running, or use tmux for persistent operation:

123tmux new-session -d -s playwriter-remote
tmux send-keys -t playwriter-remote \
  "npx -y traforo -p 19988 -t my-machine -- npx -y playwriter serve --token MY_SECRET_TOKEN" Enter

The -t flag sets the tunnel ID, which becomes the URL subdomain. If omitted, a random UUID is generated. Tunnel IDs are not reserved; if someone else connects with the same ID, they replace your connection.

Remote machine setup

Set the two environment variables and use playwriter normally:

12export PLAYWRITER_HOST=https://my-machine-tunnel.traforo.dev
export PLAYWRITER_TOKEN=MY_SECRET_TOKEN

The CLI with the skill is the recommended approach. The skill file (playwriter skill) documents all available APIs. Use playwriter exactly as you would locally:

123playwriter session new          # outputs: 1
playwriter -s 1 -e "state.page = await context.newPage(); await state.page.goto('https://example.com')"
playwriter -s 1 -e "console.log(await snapshot({ page: state.page }))"

Alternatively, pass host and token as flags instead of env vars:

1playwriter --host https://my-machine-tunnel.traforo.dev --token MY_SECRET_TOKEN -s 1 -e "..."

MCP configuration

If you prefer using the MCP server over the CLI (e.g. for AI assistants that don't support the skill), set the env vars in your MCP client config:

123456789101112{
  "mcpServers": {
    "playwriter": {
      "command": "npx",
      "args": ["-y", "playwriter@latest"],
      "env": {
        "PLAYWRITER_HOST": "https://my-machine-tunnel.traforo.dev",
        "PLAYWRITER_TOKEN": "MY_SECRET_TOKEN"
      }
    }
  }
}

The env vars tell the MCP to skip starting a local relay and connect to the remote one instead.

Playwright API (programmatic)

12345678import { chromium } from 'playwright-core'

const browser = await chromium.connectOverCDP(
  'wss://my-machine-tunnel.traforo.dev/cdp/session1?token=MY_SECRET_TOKEN',
)
const page = await browser.contexts()[0].newPage()
await page.goto('https://example.com')
// Don't call browser.close() - it would close the user's Chrome

Use cases

Control a remote Mac mini. Run Chrome on a headless machine and control it from your laptop. The Mac mini runs the tunnel persistently via tmux. Automate browser tasks, run tests against real Chrome, or manage web apps from anywhere.

Fix issues for a user remotely. The user starts the tunnel, shares the URL + token with you, and you can see exactly what they see: navigate their tabs, inspect elements, take screenshots. The user sees Chrome's automation banner so they always know when their browser is being controlled, and can revoke access instantly by closing the terminal.

Control many machines at once. Each machine runs its own tunnel with a unique -t ID and the same token. From a control machine, loop over the tunnel URLs to run commands across the fleet:

12345for machine in machine-a machine-b machine-c; do
  PLAYWRITER_HOST="https://${machine}-tunnel.traforo.dev" \
  PLAYWRITER_TOKEN=shared-secret \
  playwriter -s 1 -e "console.log(await Promise.all(context.pages().map((p) => p.title())))"
done

Development from a VM or devcontainer. Your code runs in a VM or devcontainer but Chrome runs on the host. The tunnel bridges the gap without needing host networking or port forwarding. See the Docker section below.

Docker / devcontainer setup

The relay server must run on the same machine as Chrome. The Chrome extension connects to the relay via localhost WebSocket, and the /extension endpoint only accepts connections from 127.0.0.1. This means playwriter serve always runs on the host, never inside the container.

From Docker, set PLAYWRITER_HOST and PLAYWRITER_TOKEN to reach the host relay.

┌────────────────────────────────────────────────────────────────────────────────────────┐
│  HOST MACHINE                                                                          │
│                                                                                        │
│  Chrome + Extension <────── local WS ──────> playwriter serve :19988                   │
└────────────────────────────────────────────────────────^───────────────────────────────┘
                                                         │
                                            host.docker.internal:19988
                                                         │
┌────────────────────────────────────────────────────────┴───────────────────────────────┐
│  DOCKER CONTAINER                                                                      │
│                                                                                        │
│  PLAYWRITER_HOST=host.docker.internal + PLAYWRITER_TOKEN                               │
│                                                                                        │
│  playwriter -s 1 -e "await state.page.goto(url)"                                       │
└────────────────────────────────────────────────────────────────────────────────────────┘

Step 1: Host. Start the relay server on the host machine (where Chrome is running):

1playwriter serve --host 0.0.0.0 --token MY_SECRET_TOKEN

Docker reaches the host through a non-loopback interface, so the relay must bind to 0.0.0.0. A token is required because this exposes the relay to the host network.

Step 2: Docker. Pass the host and the same token into your container:

1234docker run \
  -e PLAYWRITER_HOST=host.docker.internal \
  -e PLAYWRITER_TOKEN=MY_SECRET_TOKEN \
  myimage

Then use playwriter normally inside the container:

12playwriter session new
playwriter -s 1 -e "state.page = await context.newPage(); await state.page.goto('https://example.com')"

Platform support for `host.docker.internal`

Platform	Works out of the box?	Notes
macOS (Docker Desktop)	Yes	Supported since Docker Desktop 18.03
Windows (Docker Desktop)	Yes	Supported since Docker Desktop 18.03
Linux (Docker Engine)	No	Requires `--add-host` or `extra_hosts` (see below)

On Linux, host.docker.internal is not provided automatically by Docker Engine. You must add it explicitly:

12345docker run \
  --add-host=host.docker.internal:host-gateway \
  -e PLAYWRITER_HOST=host.docker.internal \
  -e PLAYWRITER_TOKEN=MY_SECRET_TOKEN \
  myimage

Or in Docker Compose:

12345678services:
  app:
    build: .
    environment:
      - PLAYWRITER_HOST=host.docker.internal
      - PLAYWRITER_TOKEN=MY_SECRET_TOKEN
    extra_hosts:
      - "host.docker.internal:host-gateway"

The host-gateway special value (available since Docker Engine 20.10) resolves to the host's gateway IP.

Common mistake: running playwriter serve inside the container. This won't work because the Chrome extension can only connect to the relay via localhost, and localhost inside Docker is isolated from the host. The relay must be on the same machine as Chrome.

MCP from Docker

If your AI assistant or MCP client runs inside Docker:

123456789101112{
  "mcpServers": {
    "playwriter": {
      "command": "npx",
      "args": ["-y", "playwriter@latest"],
      "env": {
        "PLAYWRITER_HOST": "host.docker.internal",
        "PLAYWRITER_TOKEN": "MY_SECRET_TOKEN"
      }
    }
  }
}

On Linux, make sure the container has --add-host=host.docker.internal:host-gateway.

Security

Traforo URLs are non-guessable. Each tunnel gets a unique ID (random UUID by default). Nobody can discover your tunnel by scanning.

Token authentication is required. When playwriter serve binds to 0.0.0.0, it refuses to start without a --token. Every privileged HTTP request (/cli/*, /recording/*) needs Authorization: Bearer <token> or ?token=<token>, and every /cdp WebSocket connection needs ?token=<token>. Without the correct token, the relay returns 401.

Extension endpoint is localhost-only. The /extension WebSocket endpoint only accepts connections from 127.0.0.1 or ::1. A remote attacker cannot impersonate the extension even with the token.

No open ports. Traforo uses an outbound WebSocket to Cloudflare. The host machine needs no inbound ports open. Works behind NATs, firewalls, and corporate networks.

Visible automation. Chrome shows an automation banner on controlled tabs.

Instant revocation. Closing the terminal immediately disconnects the tunnel.

Environment variables

Variable	Description
`PLAYWRITER_HOST`	Remote relay URL (e.g. `https://x-tunnel.traforo.dev`) or IP (e.g. `192.168.1.10`)
`PLAYWRITER_TOKEN`	Authentication token for the relay server
`PLAYWRITER_PORT`	Override relay port (default: `19988`, not needed with traforo)

Recommendations

Generate a strong random token: openssl rand -hex 16
Omit -t in traforo to get a random tunnel ID for maximum security
Don't share tunnel URLs in public channels
Kill the tunnel when you're done

Without traforo (LAN only)

If both machines are on the same network, skip traforo and connect directly:

1234567# Host
npx -y playwriter serve --token MY_SECRET_TOKEN

# Remote (same LAN)
export PLAYWRITER_HOST=192.168.1.10
export PLAYWRITER_TOKEN=MY_SECRET_TOKEN
playwriter session new