Skip to content

Connect Playwright 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 →

Playwright drives a Steel session over the Chrome DevTools Protocol (CDP). You replace chromium.launch() with chromium.connectOverCDP(), and the rest of your Playwright code runs against a browser in Steel's cloud. Proxies, CAPTCHA solving and the live view come from the session, not from Playwright. Because the browser runs in Steel, you do not run playwright install or install Chrome on your machine.

In this guide, you run a first Playwright program on Steel and watch its browser live. After the run, you replay it in the dashboard. Then you move your own Playwright code over.

Before you begin

  • A Steel API key in the STEEL_API_KEY environment variable. See API keys.
  • Node.js 20 or later, or Python 3.10 or later.

Make a folder for the project, and install the Steel SDK and Playwright in it:

mkdir steel-playwright
cd steel-playwright
npm install steel-sdk playwright

1. Write the program

This program creates a session and prints its session viewer URL. It waits for you to press Enter, so that you can open the URL first. Then it connects Playwright to the session, opens a page and prints the page's title. It releases the session in finally, even when a step fails.

playwright.mts
import { createInterface } from "node:readline/promises";
import Steel from "steel-sdk";
import { chromium } from "playwright";

const client = new Steel();
const session = await client.sessions.create();

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();
  }
  const browser = await chromium.connectOverCDP(session.websocketUrl);
  const context = browser.contexts()[0];
  const page = context.pages()[0] ?? (await context.newPage());
  await page.goto("https://example.com");
  console.log(await page.title());
  await browser.close();
} finally {
  await client.sessions.release(session.id);
}

The Python file is not named playwright.py, because that name would hide the playwright package from the import.

2. Run it and watch it live

Run the program:

npx tsx playwright.mts

The program prints the URL of the session viewer, the session's page in the Steel dashboard, and waits:

Session viewer: https://app.steel.dev/sessions/b57916d8-5a9f-44ce-853e-4c382fe23106
Open the session viewer, then press Enter.

Open the URL in a browser where you are signed in to Steel. The viewer shows the session's browser, live. Press Enter in the terminal. In the viewer, the browser opens example.com, and the program prints the page's title:

Example Domain

3. Replay the run

The program released the session, so the session has ended. Open the same session viewer URL again. It now plays the session's recording, next to its logs and agent traces, which list the page load. Recordings shows how to fetch or embed the video.

4. Move your own Playwright code

To run Playwright code that you already have, make the same change as the program. Create a session, and replace chromium.launch() with chromium.connectOverCDP() and the session's websocketUrl. The URL is the same for every CDP client, and CDP explains it. Then check these parts of your code.

Use the session's context

A session starts with one browser context, and that context already has a page open. Use browser.contexts()[0] (browser.contexts[0] in Python) and its first page, or a new page if it has none, as the program does. To open another tab, call newPage() on that same context.

Do not call browser.newContext(). A new context starts empty, without the cookies that a profile or a session context loads into the session. See CDP.

Close the connection and release the session

browser.close() ends Playwright'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. Close the browser first, then release the session, as the program does.

If the connection drops while the session still runs, connect again to 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, proxy or args belong to chromium.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.

Next steps