# 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. **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](/docs/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](/integrations/playwright). 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](/docs/reference/previews). 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: ```ts check import { 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](/docs/browsers#connect-to-the-browser)). ## 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()` | ## Related - [How to connect Puppeteer to a remote browser](/how-to/connect-puppeteer-to-a-remote-browser) - [How to run a Linux desktop in the browser](/how-to/run-a-linux-desktop-in-the-browser) - [What is VNC?](/glossary/vnc) - [What is a headless browser?](/glossary/headless-browser) - [How to run Playwright in a cloud sandbox](/integrations/playwright) ## Sources - [Playwright, BrowserType.connectOverCDP](https://playwright.dev/docs/api/class-browsertype#browser-type-connect-over-cdp), checked 17 November 2026 - [Playwright, Browser.close](https://playwright.dev/docs/api/class-browser#browser-close), checked 17 November 2026 Facts on this page were checked on 17 November 2026.