---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/integrations/puppeteer
markdown_url: https://steel.dev/docs/integrations/puppeteer.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Connect Puppeteer to Steel
description: Run a Puppeteer program on a Steel cloud browser, watch it live, replay the run, and move your own Puppeteer code over to Steel.
summary: Run a Puppeteer program on a Steel cloud browser, watch it live, replay the run, and move your own Puppeteer code over to Steel.
type: integration-guide
reviewed: 2026-11-17
prerequisites: []
related:
  - https://steel.dev/docs/integrations/playwright.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# 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_KEY` environment variable. See [API keys](https://steel.dev/docs/account/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.

```sh
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.

```ts file=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:

```sh
npx tsx puppeteer.mts
```

It prints the URL of the [session viewer](https://steel.dev/docs/observability/live-view#open-the-live-view), the session's page in the Steel dashboard, and waits:

```text nocopy
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:

```text nocopy
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](https://steel.dev/docs/observability/agent-traces) sit next to the video, and the traces list the load of `example.com`. To fetch or embed the video, see [Recordings](https://steel.dev/docs/observability/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](https://steel.dev/docs/control/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](https://steel.dev/docs/logins/profiles) or a [session context](https://steel.dev/docs/logins/session-context) loads into the session. See [CDP](https://steel.dev/docs/control/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](https://steel.dev/docs/stealth/proxies) or `solveCaptcha` for [CAPTCHA solving](https://steel.dev/docs/stealth/captcha-solving). See [Session configuration](https://steel.dev/docs/sessions/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](https://steel.dev/docs/sessions/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](https://steel.dev/docs/sessions/configuration).

## Next steps

- [Stay signed in across sessions](https://steel.dev/docs/logins/stay-signed-in): Keep a site's login in a profile, so that the next session starts signed in.
- [Get past bot detection](https://steel.dev/docs/stealth/get-past-bot-detection): Find out what blocked a page, then add a proxy, CAPTCHA solving or a mobile device.
- [Run sessions at scale](https://steel.dev/docs/production/run-sessions-at-scale): Run many Puppeteer tasks at once, and release every session.
- [Puppeteer documentation](https://pptr.dev): The library and its API.
- [Cookbook starter](https://github.com/steel-dev/steel-cookbook/tree/main/examples/puppeteer-ts): A TypeScript project that extracts stories from Hacker News.
