Browser Automation with CDP

pai relay bridges your local Chrome browser to an agent running on Pai using the Chrome DevTools Protocol (CDP). This lets the agent control a real browser on your machine — navigating pages, filling forms, taking screenshots, and running JavaScript — without exposing your Chrome directly to the internet.

How it works

1. You launch Chrome on your machine with remote debugging enabled.
2. You run pai relay <agent-name>, which opens a WebSocket tunnel to the agent's CDP relay endpoint.
3. The agent (running inside Pai) connects back through that tunnel and drives your Chrome as if it were local.

Step 1: Install the Pai CLI

curl -Lo pai https://pairun.dev/download/pai-macos-arm64
chmod +x pai
sudo mv pai /usr/local/bin/pai

Verify:

pai version

Step 2: Log in

pai login https://api.pairun.dev --token <your-token>

Example:

pai login https://api.pairun.dev --token pai_tok_6xpq0CdR7vEI7HSXauIGSyAgC4Aut1MO

This stores your credentials in ~/.pai/config.json. All subsequent pai commands use this context automatically.

Step 3: Launch Chrome with remote debugging

Open a new terminal and run:

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --remote-allow-origins=http://localhost \
  --user-data-dir=/tmp/chrome-debug

Chrome starts with a fresh profile at /tmp/chrome-debug and listens for CDP connections on port 9222. The --remote-allow-origins flag is required so that the relay's local WebSocket handshake is accepted.

note

Keep this Chrome window open for the duration of your session. Closing it drops all active CDP sessions.

Step 4: Start the relay

pai relay <agent-name> --token <cdp-relay-token>

Replace <agent-name> with the name of your running agent workload and <cdp-relay-token> with the token configured in the agent's spec.cdpRelay.token field.

Example:

pai relay my-browser-agent --token my-secret-token

You should see:

Connecting to wss://a7x3k9.pairun.dev/pai/cdp-relay/bridge...
Ready. Waiting for agent to request Chrome...

The relay stays open until you press Ctrl+C. If the agent restarts, the relay automatically reconnects for up to 10 minutes.

What happens next

Once the relay is running, the agent can use any CDP-based browser automation library (Puppeteer, Playwright, etc.) and its requests are transparently forwarded to your local Chrome instance. You will see the browser navigate, click, and interact in real time.

Flags

Flag	Default	Description
--token <tok>	(empty)	Auth token matching spec.cdpRelay.token on the agent
--chrome-port <n>	9222	Local Chrome remote-debugging port

Troubleshooting

Error: agent 'my-agent' has no public URL yet — the agent is still starting. Wait for pai status my-agent to show Running.

Chrome refuses the connection — confirm Chrome was started with --remote-debugging-port=9222 and --remote-allow-origins=http://localhost. Check that nothing else is using port 9222 (lsof -i :9222).

Relay disconnects immediately — verify the --token value matches what is configured on the agent. Token mismatches result in an immediate close from the server.