Connect Playwright or Puppeteer to a cloud browser over CDP.

How do I run Playwright in the cloud?

1. Start a browser. POST /v1/agents (or create_agent() in the SDK) starts a Chromium in Browsa's cloud and returns its id, its cdp_http address and a live_url you can open to watch it.
2. Connect. Replace chromium.launch() with chromium.connect_over_cdp(cdp_http, headers={"X-API-Key": API_KEY}), or puppeteer.launch() with puppeteer.connect({ browserURL, headers }). The browser already has a context and an open page: use it.
3. Clean up. Call destroy_agent() when you are done, or let the browser shut down when its TTL ends. You keep 1 credit per started 12 minutes it ran; the rest of what it reserved comes back.

You need a Browsa API key (it starts with agt_live_). Sign up for 100 free credits once you verify your email, no card. There is no Chrome to install on your machine or in your Docker image.

Connect your client

pip install browsa playwright

import os

from browsa import Client
from playwright.sync_api import sync_playwright

API_KEY = os.environ["BROWSA_API_KEY"]
client = Client(api_key=API_KEY)
agent = client.create_agent(ttl="10m")  # a cloud Chromium, up to 10 minutes

try:
    with sync_playwright() as p:
        browser = p.chromium.connect_over_cdp(
            agent["cdp_http"], headers={"X-API-Key": API_KEY}
        )
        context = browser.contexts[0]
        page = context.pages[0] if context.pages else context.new_page()
        page.goto("https://example.com")
        print(page.title())
        # the rest is plain Playwright
finally:
    client.destroy_agent(agent["id"])

npm i browsa playwright

import { Client } from "browsa";
import { chromium } from "playwright";

const apiKey = process.env.BROWSA_API_KEY!;
const client = new Client({ apiKey });
const agent = await client.createAgent({ ttl: "10m" });

try {
  const browser = await chromium.connectOverCDP(agent.cdp_http, {
    headers: { "X-API-Key": apiKey },
  });
  const context = browser.contexts()[0];
  const page = context.pages()[0] ?? (await context.newPage());
  await page.goto("https://example.com");
  console.log(await page.title());
} finally {
  await client.destroyAgent(agent.id);
}

npm i browsa puppeteer-core

import { Client } from "browsa";
import puppeteer from "puppeteer-core";

const apiKey = process.env.BROWSA_API_KEY!;
const client = new Client({ apiKey });
const agent = await client.createAgent({ ttl: "5m" });

try {
  const browser = await puppeteer.connect({
    browserURL: agent.cdp_http,
    headers: { "X-API-Key": apiKey },
  });
  const [page] = await browser.pages();
  await page.goto("https://example.com");
  console.log(await page.title());
  await browser.disconnect();
} finally {
  await client.destroyAgent(agent.id);
}

curl https://browsa.io/v1/agents \
  -H "X-API-Key: $BROWSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttl": "10m", "initial_url": "https://example.com"}'

# -> { "id": "agt_…", "status": "running", "cdp_http": "https://browsa.io/api/v1/cdp/…",
#      "cdp_url": "wss://browsa.io/api/v1/cdp/…/ws/page/…", "live_url": "…", "cost_credits": 5 }

What works differently from a local browser?

How do I reconnect after a dropped connection?

Closing your Playwright or Puppeteer connection does not stop the browser. It keeps running until its TTL ends, so another process can attach to it. Get its address again with GET /v1/agents/{id}/cdp (or get_agent(agent_id) in Python, getAgent(agentId) in TypeScript) and connect with the same X-API-Key header. The endpoint returns 409 when the browser is no longer running.

How do I download a file?

Fetch it from inside the page and return the bytes:

import base64

b64 = page.evaluate("""async (url) => {
  const buf = new Uint8Array(await (await fetch(url)).arrayBuffer());
  let s = ""; for (const b of buf) s += String.fromCharCode(b);
  return btoa(s);
}""", "https://example.com/report.pdf")
open("report.pdf", "wb").write(base64.b64decode(b64))

How do I use my own proxy?

Add a proxy object when you start the browser. The browser then uses the proxy's IP address, and with country set, its timezone and language follow that country. Proxy traffic costs nothing extra on Browsa.

curl https://browsa.io/v1/agents \
  -H "X-API-Key: $BROWSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ttl": "10m",
    "proxy": {"type": "http", "host": "proxy.example.com", "port": 8080,
              "username": "your-proxy-user", "password": "your-proxy-password"},
    "country": "de"
  }'

A raw browser starts even when the proxy is unreachable, so check it first. A saved proxy has a check endpoint and can be passed as proxy_id.

How do I keep logins between runs?

Use a persistent identity instead of a burner. It keeps its cookies, local storage and fingerprint between sessions. Create it once with "mode": "persistent", then open a session whenever a script needs it: POST /v1/agents/{id}/sessions returns the same shape as a new browser, including cdp_http, and you connect to it exactly as above. An identity costs 50 credits every 30 days and each session costs 1 credit. See Open a session.

What does it cost?

One credit is $0.10 on the $20 Starter pack and less on larger packs. Credits never expire. Full pricing.

Troubleshooting

Questions

Next steps