Skip to content

Connect Puppeteer to Steel

Set up your agent

Give your coding agent a Steel browser and the Steel skills, so that it browses and writes Steel code the right way. Learn more

Install the Steel CLI. It signs you in and installs the skills for your coding agents.

curl -fsS https://setup.steel.dev | sh

Or send this prompt to your coding agent, and it does the same:

Read https://setup.steel.dev/install.md and follow it to set up Steel for this coding client.
Then continue my requested task using the installed Steel skill.

Set up your agent →

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_KEY environment 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-core

1. 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.

puppeteer.mts
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.mts

It 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 Domain

3. 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, executablePath or args belong to puppeteer.launch(), which you no longer call. Set the matching options when you create the session, for example useProxy for a Steel proxy or solveCaptcha for 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, set dimensions when you create the session. See Session configuration.

Next steps