Connect Puppeteer to Steel
Puppeteer drives a Steel session over the Chrome DevTools Protocol (CDP). You replace puppeteer.launch() with puppeteer.connect() and pass the session's WebSocket URL. The rest of your Puppeteer code runs against a browser in Steel's cloud. Proxies, CAPTCHA solving and the live view come from the session, not from Puppeteer. Puppeteer is a Node.js library, so this page has TypeScript only.
In this guide, you run a first Puppeteer program on Steel, and watch the browser in the dashboard while it runs. After the run, you replay it. Then you move your own Puppeteer code over.
Before you begin
- A Steel API key in the
STEEL_API_KEYenvironment variable. See API keys. - Node.js 22.12 or later.
Make a folder for the project, and install the Steel SDK and puppeteer-core in it. Use puppeteer-core, not puppeteer. It has the same API, and it does not download a local Chromium, which you do not need.
mkdir steel-puppeteer
cd steel-puppeteer
npm install steel-sdk puppeteer-core1. Write the program
This program creates a session, prints its session viewer URL, and waits for you to press Enter. Then it connects Puppeteer to the session, opens a page and prints its title. In finally, it disconnects and releases the session, even when a step fails.
import { createInterface } from "node:readline/promises";
import Steel from "steel-sdk";
import puppeteer, { type Browser } from "puppeteer-core";
const client = new Steel();
const session = await client.sessions.create();
let browser: Browser | undefined;
console.log("Session viewer:", session.sessionViewerUrl);
try {
if (process.stdin.isTTY) {
const prompt = createInterface({ input: process.stdin, output: process.stdout });
await prompt.question("Open the session viewer, then press Enter.");
prompt.close();
}
browser = await puppeteer.connect({
browserWSEndpoint: session.websocketUrl,
});
const pages = await browser.pages();
const page = pages[0] ?? (await browser.newPage());
await page.goto("https://example.com");
console.log(await page.title());
} finally {
await browser?.disconnect();
await client.sessions.release(session.id);
}2. Run it and watch it live
Run the program:
npx tsx puppeteer.mtsIt prints the URL of the session viewer, the session's page in the Steel dashboard, and waits:
Session viewer: https://app.steel.dev/sessions/dd7a3e48-77f3-4d5f-b0f3-dbe4bef99390
Open the session viewer, then press Enter.Open the URL in a browser where you are signed in to Steel, and you see the session's browser, live. Press Enter in the terminal. Puppeteer opens example.com in the viewer, and the program prints the title:
Example Domain3. Replay the run
After the release, the session viewer at the same URL plays the session's recording. Its logs and agent traces sit next to the video, and the traces list the load of example.com. To fetch or embed the video, see Recordings.
4. Move your own Puppeteer code
To run Puppeteer code that you already have, create a session, and replace puppeteer.launch() with puppeteer.connect() and the session's websocketUrl, as the program does. The URL is the same for every CDP client, and CDP explains it. Then check these parts of your code.
Use the session's pages
A session starts with a page open, and browser.pages() returns it. Use the first page, or a new page if there is none, as the program does. browser.newPage() opens a new tab in the same session. The live view shows a blank tab until that page navigates.
Do not call browser.createBrowserContext(). A new context starts empty, without the cookies that a profile or a session context loads into the session. See CDP.
Disconnect and release the session
browser.disconnect() ends Puppeteer's connection to the session. It does not end the session. The browser keeps running, and keeps costing browser time, until you call client.sessions.release() or the session times out. Disconnect first, then release the session, as the program does.
If the connection drops while the session still runs, call puppeteer.connect() again with the session's websocketUrl. If you no longer have the URL, client.sessions.retrieve() returns it. The pages and browser state are still there.
Features that change with a remote browser
- Launch options do not apply. Options such as
headless,executablePathorargsbelong topuppeteer.launch(), which you no longer call. Set the matching options when you create the session, for exampleuseProxyfor a Steel proxy orsolveCaptchafor CAPTCHA solving. See Session configuration. - Downloads stay in the session. A file that the browser downloads is saved in the session, not on your machine. Get it with the Files API. See Files.
- The viewport follows the session.
puppeteer.connect()sets an 800 by 600 viewport by default, and Steel replaces it with the session's screen size. To get another size, setdimensionswhen you create the session. See Session configuration.
Next steps
- Stay signed in across sessionsKeep a site's login in a profile, so that the next session starts signed in.
- Get past bot detectionFind out what blocked a page, then add a proxy, CAPTCHA solving or a mobile device.
- Run sessions at scaleRun many Puppeteer tasks at once, and release every session.
- Puppeteer documentationThe library and its API.
- Cookbook starterA TypeScript project that extracts stories from Hacker News.