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

# Connect Playwright to Steel

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](https://steel.dev/docs/account/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:

**TypeScript**

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

**Python**

```sh
mkdir steel-playwright
cd steel-playwright
python3 -m venv .venv
source .venv/bin/activate
pip 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.

**TypeScript**

```ts file=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);
}
```

**Python**

```python file=playwright_steel.py
import sys

from playwright.sync_api import sync_playwright
from steel import Steel

client = Steel()
session = client.sessions.create()

print("Session viewer:", session.session_viewer_url)

try:
    if sys.stdin.isatty():
        input("Open the session viewer, then press Enter.")
    with sync_playwright() as playwright:
        browser = playwright.chromium.connect_over_cdp(session.websocket_url)
        context = browser.contexts[0]
        page = context.pages[0] if context.pages else context.new_page()
        page.goto("https://example.com")
        print(page.title())
        browser.close()
finally:
    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:

**TypeScript**

```sh
npx tsx playwright.mts
```

**Python**

```sh
python playwright_steel.py
```

The program 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/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:

```text nocopy
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](https://steel.dev/docs/observability/agent-traces), which list the page load. [Recordings](https://steel.dev/docs/observability/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](https://steel.dev/docs/control/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](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).

### 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](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).

## Next steps

- [Stay signed in across sessions](https://steel.dev/docs/logins/stay-signed-in): Sign in once with Playwright, and start the next session signed in.
- [Get past bot detection](https://steel.dev/docs/stealth/get-past-bot-detection): Find out what blocked a page, and add a proxy or CAPTCHA solving.
- [Run sessions at scale](https://steel.dev/docs/production/run-sessions-at-scale): Run many Playwright tasks at once, within your plan's limit.
- [Playwright documentation](https://playwright.dev): The library and its API, for TypeScript and for Python.
- Cookbook starters: [TypeScript](https://github.com/steel-dev/steel-cookbook/tree/main/examples/playwright-ts), [Python](https://github.com/steel-dev/steel-cookbook/tree/main/examples/playwright-py) and [Go](https://github.com/steel-dev/steel-cookbook/tree/main/examples/playwright-go).
