Playwright integration

Minimal path from REST API launch to Playwright over CDP. See API overview and the longer Automation API sample.

Pro required

Local API and api-key need active membership. Copy the port from the client API screen.

Flow

1. API base URL and key

1. Launch Virtual Browser with active Pro.
2. Open API and note http://localhost:{port} and api-key.

2. Launch a profile

POST http://localhost:{port}/api/launchBrowser
Content-Type: application/json
api-key: YOUR_API_KEY

{ "id": 1 }

See Launch browser. Use data.debuggingPort from the JSON response.

3. Python (sync)

import requests
from playwright.sync_api import sync_playwright

BASE = "http://localhost:9000"
HEADERS = {"Content-Type": "application/json", "api-key": "YOUR_API_KEY"}

r = requests.post(f"{BASE}/api/launchBrowser", headers=HEADERS, json={"id": 1}).json()
port = r["data"]["debuggingPort"]

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(f"http://127.0.0.1:{port}")
    page = browser.contexts[0].pages[0]
    page.goto("https://example.com")

requests.post(f"{BASE}/api/stopBrowser", headers=HEADERS, json={"id": 1})

Use connect_over_cdp with the returned port—do not call chromium.launch() or you lose the profile fingerprint and proxy.

4. Node.js

import { chromium } from 'playwright';

const res = await fetch('http://localhost:9000/api/launchBrowser', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'api-key': 'YOUR_API_KEY' },
  body: JSON.stringify({ id: 1 }),
}).then((r) => r.json());

const browser = await chromium.connectOverCDP(
  `http://127.0.0.1:${res.data.debuggingPort}`,
);
const page = browser.contexts()[0].pages()[0];
await page.goto('https://example.com');

5. Puppeteer

const browser = await puppeteer.connect({
  browserURL: `http://127.0.0.1:${debuggingPort}`,
});

6. Troubleshooting

Issue	Fix
401	Refresh api-key from the API screen
Connection refused	Wrong port or profile not launched
success: false	Invalid id or profile already running
Wrong fingerprint	You launched standalone Chromium instead of CDP attach
VIP only	Subscribe to Pro

Related

• Automation API
• CLI mode
• MCP protocol