Skip to main content

​
playwriter serve

Start the relay server on this machine (must be the same host where Chrome is running). Remote clients (Docker, other machines) connect via PLAYWRITER_HOST. 
playwriter serve
playwriter serve --host localhost
playwriter serve --host 0.0.0.0 --token your-secret-token

​
Options

​
--host
string
default:"0.0.0.0"
Host to bind to:
  • localhost - For Docker access via host.docker.internal (no token needed)
  • 0.0.0.0 - For LAN/internet access (requires --token)
​
--token
string
Authentication token, required when --host is 0.0.0.0 (or use PLAYWRITER_TOKEN env var)
​
--replace
boolean
Kill existing server if running on the same port

​
Server Details

The relay server:
  • Runs on port 19988 (hardcoded)
  • Logs to ~/.playwriter/relay.log
  • CDP logs to ~/.playwriter/cdp.jsonl
  • Sets process title to playwriter-serve

​
Returns

Prints server status to stdout: 
Playwriter CDP relay server started
  Host: 0.0.0.0
  Port: 19988
  Token: (configured)
  Logs: /Users/you/.playwriter/relay.log
  CDP Logs: /Users/you/.playwriter/cdp.jsonl

CDP endpoint: http://0.0.0.0:19988?token=<token>

Press Ctrl+C to stop.

​
Exit Codes

  • 0 - Server stopped cleanly (Ctrl+C)
  • 1 - Error:
    • Token required for public host
    • Port already in use (without --replace)
    • Uncaught exception
    • Unhandled rejection

​
Examples

playwriter serve

​
Security Notes

  • When --host is 0.0.0.0 or ::, a token is required
  • The token authenticates all connections via Authorization: Bearer <token> header
  • For Docker on the same machine, use --host localhost (no token needed)
  • Never expose the relay server publicly without authentication

​
Error Messages

​
Missing token for public host

Error: Authentication token is required when binding to a public host.
Provide --token <token> or set PLAYWRITER_TOKEN environment variable.

​
Port already in use

Playwriter server is already running on port 19988
Tip: Use --replace to kill the existing server and start a new one.

​
Signal Handling

The server handles shutdown signals gracefully:
  • SIGINT (Ctrl+C) - Closes server and exits
  • SIGTERM - Closes server and exits

Build docs developers (and LLMs) love

Get started for freeTalk to us