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-coreConnect 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 laterconnect()finds them withbrowser.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 |
Related
- How to run Playwright in the cloud
- How to run a Linux desktop in the browser
- What is VNC?
- How to run Puppeteer in a cloud sandbox
- What is a headless browser?
Sources
- Puppeteer, connect, checked 17 November 2026
- Puppeteer, ConnectOptions, checked 17 November 2026
- Puppeteer, Browser.disconnect, checked 17 November 2026
Facts on this page were checked on 17 November 2026.