# How to connect Puppeteer to a remote browser Call `puppeteer.connect()` with the remote Chrome's DevTools address, in place of `puppeteer.launch()`. **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](/docs/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: ```bash no-run npm install puppeteer-core ``` ## Connect to a Runtime browser Create the browser, share its port 9222 as a private [preview](/docs/reference/previews), and connect with the preview's address and token. The Runtime calls are plain HTTPS, so they work from any language: ```js import 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`: ```bash no-run curl -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](/docs/browsers)). 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-playwright-in-the-cloud) - [How to run a Linux desktop in the browser](/how-to/run-a-linux-desktop-in-the-browser) - [What is VNC?](/glossary/vnc) - [How to run Puppeteer in a cloud sandbox](/integrations/puppeteer) - [What is a headless browser?](/glossary/headless-browser) ## Sources - [Puppeteer, connect](https://pptr.dev/api/puppeteer.puppeteernode.connect), checked 17 November 2026 - [Puppeteer, ConnectOptions](https://pptr.dev/api/puppeteer.connectoptions), checked 17 November 2026 - [Puppeteer, Browser.disconnect](https://pptr.dev/api/puppeteer.browser.disconnect), checked 17 November 2026 Facts on this page were checked on 17 November 2026.