> Agent-readable docs index: /llms.txt. Download /docs.zip to grep all markdown files locally.

---
title: Configuration, Environment Variables, and MCP Setup Options
sidebarTitle: Configuration
description: All Playwriter environment variables, CLI flags, MCP server configuration examples for Claude, Cursor, and OpenCode, and remote connection options.
icon: lucide:settings
---

Playwriter is configured through **CLI flags** and **environment variables**. No config files needed.

## Environment variables

| Variable             | Description                       | Default                |
| -------------------- | --------------------------------- | ---------------------- |
| `PLAYWRITER_HOST`    | Remote relay server URL           | `ws://localhost:19988` |
| `PLAYWRITER_TOKEN`   | Auth token for remote connections | -                      |
| `PLAYWRITER_DIRECT`  | CDP connection mode (see below)   | -                      |
| `PLAYWRITER_API_KEY` | API key for cloud browsers        | -                      |

### PLAYWRITER\_DIRECT

Connect directly to Chrome's DevTools Protocol, bypassing the extension:

| Value                     | Behavior                              |
| ------------------------- | ------------------------------------- |
| `1`                       | Auto-discover Chrome on port 9222     |
| `ws://...` or `wss://...` | Explicit WebSocket endpoint           |
| `host:port`               | Resolves via HTTP probe to ws\:// URL |

```bash
# Auto-discover local Chrome
PLAYWRITER_DIRECT=1 playwriter session new

# Cloud browser provider
PLAYWRITER_DIRECT=wss://xxx.cdp.browser-use.com playwriter session new
```

### PLAYWRITER\_HOST and PLAYWRITER\_TOKEN

For [remote access](/docs/remote-access), point to a relay server running on another machine:

```bash
export PLAYWRITER_HOST=https://my-tunnel.traforo.dev
export PLAYWRITER_TOKEN=MY_SECRET
playwriter session new
```

## CLI global flags

| Flag                 | Description                                 |
| -------------------- | ------------------------------------------- |
| `-s, --session <id>` | Session ID (required for `-e`, `-f`)        |
| `-e <code>`          | Execute JavaScript code inline              |
| `-f <path>`          | Execute JavaScript from a file              |
| `--host <host>`      | Remote relay server host                    |
| `--token <token>`    | Auth token for remote connections           |
| `--timeout <ms>`     | Execution timeout (default: 10000)          |
| `--patchright`       | Use @playwriter/patchright-core for stealth |

## Session new flags

| Flag                                     | Description                                                    |
| ---------------------------------------- | -------------------------------------------------------------- |
| `--browser <key>`                        | Browser type: extension ID, `headless`, `cloud`, `direct:port` |
| `--direct [endpoint]`                    | Direct CDP: auto-discover or explicit endpoint                 |
| `--proxy <region>`                       | Cloud proxy region (us, de, jp, etc.)                          |
| `--custom-proxy <url>`                   | Custom proxy (host:port or user:pass\@host:port)               |
| `--timeout <minutes>`                    | Cloud browser timeout (1-240, default 60)                      |
| `--disable-proxy-bandwidth-acceleration` | Load images/video with proxy                                   |

## Browser start flags

| Flag                    | Description                  |
| ----------------------- | ---------------------------- |
| `--user-data-dir <dir>` | Persistent profile directory |
| `--headless`            | Headless mode                |
| `--headed`              | Show browser window          |
| `--disable-sandbox`     | Disable Chrome sandbox       |

## Serve flags

| Flag              | Description                            |
| ----------------- | -------------------------------------- |
| `--host [host]`   | Bind host (default: `0.0.0.0`)         |
| `--token <token>` | Auth token (required for public hosts) |
| `--replace`       | Kill existing server on the port       |

## MCP configuration examples

### Basic (extension mode)

```json
{
  "mcpServers": {
    "playwriter": {
      "command": "npx",
      "args": ["-y", "playwriter@latest"]
    }
  }
}
```

### Direct CDP

```json
{
  "mcpServers": {
    "playwriter": {
      "command": "npx",
      "args": ["-y", "playwriter@latest"],
      "env": {
        "PLAYWRITER_DIRECT": "1"
      }
    }
  }
}
```

### Cloud browser provider

```json
{
  "mcpServers": {
    "playwriter": {
      "command": "npx",
      "args": ["-y", "playwriter@latest"],
      "env": {
        "PLAYWRITER_DIRECT": "wss://xxx.cdp.browser-use.com"
      }
    }
  }
}
```

### Remote relay

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

## Debugging configuration

Playwriter logs to files for debugging:

```bash
# Get log file paths
playwriter logfile
# typically: ~/.playwriter/relay-server.log

# CDP JSONL log for protocol debugging
jq -r '.direction + "\t" + (.message.method // "response")' ~/.playwriter/cdp.jsonl | uniq -c
```

Both files are recreated every time the relay server starts.