Skip to content

How-to guides

How to connect Puppeteer to a remote browser

Call puppeteer.connect() with the remote Chrome's DevTools address, in place of puppeteer.launch().

Updated · Facts checked · By Runtime Cloud

4 min read

Read as Markdown

On Runtime (withruntime.com), the remote Chrome is a browser product: Chromium in a Firecracker microVM, behind a private HTTPS address that needs a token. puppeteer-core is all your side installs, because no browser is downloaded. A machine at its default size, 2 vCPU and 4 GiB, costs $0.035 an hour while it waits on the network and $0.09 with both CPUs busy (pricing).

launch and connect

puppeteer.launch() starts a Chrome process on the same machine as your code. puppeteer.connect() attaches to a Chrome that is already running, wherever it is, over the Chrome DevTools Protocol. Everything after that line is the same Puppeteer API: newPage(), goto(), pdf(), screenshot().

You pass What it is Puppeteer then
browserURL The HTTP address of Chrome's DevTools port Reads /json/version and connects
browserWSEndpoint The webSocketDebuggerUrl that address returns Connects to the WebSocket directly
headers Extra HTTP headers for the connection Sends them, for example an auth token

Install the package without a bundled browser:

Terminalnpm install puppeteer-core

Connect to a Runtime browser

Create the browser, share its port 9222 as a private preview, and connect with the preview's address and token. The Runtime calls are plain HTTPS, so they work from any language:

JavaScriptimport puppeteer from "puppeteer-core";const api = "https://api.withruntime.com/v2";const auth = {  Authorization: `Bearer ${process.env.RUNTIME_API_KEY}`,  "Content-Type": "application/json",};async function call(method, path, body) {  const res = await fetch(`${api}${path}`, { method, headers: auth, body: 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 headers = { "x-runtime-preview-token": preview.token };  for (let i = 0; i < 40; i++) {    if ((await fetch(`${preview.url}json/version`, { headers })).ok) break;    await new Promise((r) => setTimeout(r, 250));  }  const browser = await puppeteer.connect({ browserURL: preview.url, headers });  const page = await browser.newPage();  await page.goto("https://example.com");  console.log(await page.title()); // Example Domain  await page.pdf({ path: "example.pdf", format: "A4" });  await browser.disconnect(); // Chrome keeps running} finally {  await call("DELETE", `/browsers/${machine.id}`);}

The same calls from a terminal, with curl:

Terminalcurl -s -X POST https://api.withruntime.com/v2/browsers \  -H "Authorization: Bearer $RUNTIME_API_KEY" -H "Content-Type: application/json" -d '{}'curl -s -X POST https://api.withruntime.com/v2/sandboxes/BROWSER_ID/previews \  -H "Authorization: Bearer $RUNTIME_API_KEY" -H "Content-Type: application/json" -d '{ "port": 9222 }'

The second call returns the url to pass as browserURL and the token for the header. To connect by WebSocket instead, read webSocketDebuggerUrl from ${url}json/version and pass it as browserWSEndpoint with the same headers.

disconnect or close

The two calls end a session differently, and on a remote browser the difference matters:

  • browser.disconnect() drops your connection and leaves Chrome running with its pages. A later connect() finds them with browser.pages(). Use it between an agent's turns.
  • browser.close() ends Chrome itself, with every page. Use it only when the browser is finished, and then delete the machine so it stops billing.

A Runtime browser that nothing talks to pauses with its memory kept, and the next connection resumes it (browsers guide). While it is paused it bills no CPU, only its saved state, at $0.18 per decimal GB a month.

Keep the address private

Whoever holds the DevTools address can drive the browser: read its cookies, open pages and run scripts in them. Leave the preview private, which is the default, and keep the token on the server that runs Puppeteer. A token stops at the preview's tokenExpiresAt; the preview's sign call returns a fresh one. Never share port 9222 as a public preview.

Common errors

Error Cause and fix
Failed to fetch browser webSocket URL on the first try Chrome was still starting: wait for /json/version to answer 200, as the sample does
Failed to fetch browser webSocket URL every time The token header is missing or expired: pass headers, and sign a new token when it has passed
An executablePath or channel must be specified puppeteer-core was given launch(); a remote browser takes connect()
connect() fails after an earlier run worked That run called close(), which ended Chrome: create a new browser, and disconnect() between runs

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