Skip to content

How-to guides

How to run Playwright in the cloud

Run Chromium on a remote machine and call chromium.connectOverCDP() with its DevTools address. Your script stays where it is.

Updated · Facts checked · By Runtime Cloud

4 min read

Read as Markdown

On Runtime (withruntime.com), a browser is Chromium in a Firecracker microVM of its own, reached over the Chrome DevTools Protocol at a private HTTPS address. Playwright connects with the address and a token header. Nothing is installed on your machine except Playwright itself. The browser pauses with its memory kept when nothing happens, and the next connection resumes it. At its default size, 2 vCPU and 4 GiB, it costs $0.035 an hour while it waits on the network (pricing).

Two ways to put Playwright in the cloud

There are two ways to split the work. Either the whole script moves to a cloud machine, or only the browser does.

Way Where your code runs Where Chromium runs Use it when
chromium.launch() remotely The cloud machine The cloud machine You ship a whole job, such as a test suite, to run unattended
chromium.connectOverCDP() Your app or laptop The cloud machine An app or an agent keeps its own process and needs a browser

The first way is a machine with Node.js and Playwright installed, as in Playwright in a cloud sandbox. This page covers the second: your code keeps running where it is, and the browser lives elsewhere. Each browser has its own cookies, cache and kernel, so a crash or a hostile page never reaches your process.

Connect to a Runtime browser

Create a browser with POST /v2/browsers, then share its port 9222 as a private preview. The preview's address answers Chromium's /json/version, and connectOverCDP takes that address with the preview's token in the x-runtime-preview-token header:

TypeScriptimport { chromium } from "playwright";const api = "https://api.withruntime.com/v2";const headers = {  Authorization: `Bearer ${process.env.RUNTIME_API_KEY}`,  "Content-Type": "application/json",};async function call(method: string, path: string, body?: unknown) {  const res = await fetch(`${api}${path}`, { method, headers, body: JSON.stringify(body) });  if (!res.ok) throw new Error(`${method} ${path}: ${res.status} ${await res.text()}`);  return res.status === 204 ? null : res.json();}const machine = await call("POST", "/browsers", {});try {  const preview = await call("POST", `/sandboxes/${machine.id}/previews`, { port: 9222 });  const token = { "x-runtime-preview-token": preview.token };  // Chromium answers a moment after the machine starts.  for (let i = 0; i < 40; i++) {    if ((await fetch(`${preview.url}json/version`, { headers: token })).ok) break;    await new Promise((r) => setTimeout(r, 250));  }  const browser = await chromium.connectOverCDP(preview.url, { headers: token });  const context = browser.contexts()[0] ?? (await browser.newContext());  const page = await context.newPage();  await page.goto("https://example.com");  console.log(await page.title()); // Example Domain  await page.screenshot({ path: "example.png" });  await browser.close(); // disconnects; the machine keeps running} finally {  await call("DELETE", `/browsers/${machine.id}`);}

browser.close() on a browser you connected to disconnects Playwright and closes the contexts the script created. Chromium itself keeps running until the machine is deleted, so a later script can connect again. The browser's own page as an image, and clicks and keys without Playwright, are two more calls on the same machine (browsers guide).

What changes over CDP

Playwright's own documentation describes a CDP connection as lower fidelity than its own protocol. In practice:

  • Chromium only. CDP is Chrome's protocol, so Firefox and WebKit need launch() on the machine instead.
  • The default context is the browser's. browser.contexts()[0] is the profile Chromium started with, cookies included. browser.newContext() gives a clean one beside it.
  • Pages outlive the connection. A page opened in the default context is still there when a script connects again, so an agent can pick up where the last step left it. page.screenshot({ path }) still writes on your side, because Playwright receives the image's bytes.
  • Latency adds up. Each Playwright call is a round trip over the network. A script of many small steps runs faster with fewer, larger ones, such as one page.evaluate() in place of many textContent() calls.

Keep the address private

A browser's DevTools address controls the whole browser: it can read every cookie and open any page. Keep the preview private, which is the default, and pass its token only to the code that drives the browser. Never share port 9222 as a public preview. The token stops working at the preview's tokenExpiresAt; ask for a new one with the preview's sign call, and give it a shorter life with ttlSeconds.

Common errors

Symptom Cause and fix
connectOverCDP answers 401 or 403 The x-runtime-preview-token header is missing or expired: pass headers on the connect call
connectOverCDP times out on the first try Chromium was still starting: wait for /json/version to answer 200, as the sample does
browserType.launch: Executable doesn't exist The script called launch() locally; a remote browser needs connectOverCDP()
A Firefox or WebKit test fails to connect CDP serves Chromium only; run that suite on the machine with launch()

Sources

Facts on this page were checked on 17 November 2026.

Cut your cloud billby 66%.

7 days of Pro for $0, and no card to sign up. Billed by the second after.

Start your free trial