---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/control/cdp
markdown_url: https://steel.dev/docs/control/cdp.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: CDP
description: Connect Playwright, Puppeteer, or any Chrome DevTools Protocol client to a Steel session over one WebSocket URL.
summary: Connect Playwright, Puppeteer, or any Chrome DevTools Protocol client to a Steel session over one WebSocket URL.
type: how-to
reviewed: 2026-11-12
prerequisites:
  - https://steel.dev/docs/control.md
  - https://steel.dev/docs/control/snapshots-and-refs.md
related:
  - https://steel.dev/docs/control/skills.md
  - https://steel.dev/docs/control/mcp-server.md
  - https://steel.dev/docs/control/commands.md
  - https://steel.dev/docs/control/computer-actions.md
  - https://steel.dev/docs/control/scrape.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# CDP

Every session has a Chrome DevTools Protocol (CDP) endpoint. Playwright, Puppeteer and other CDP clients connect to it over a WebSocket and drive the browser as if it ran on your machine. Use CDP for scripts that need full control of the browser, such as network interception. For an agent that reads the page as text and acts on elements over HTTP, use [Commands](https://steel.dev/docs/control/commands). Both can drive the same session.

## Connect a client

Connect the client to the session's `websocketUrl`. The URL holds a token that lets a client connect to that session, and to no other, until the session ends, so the client needs no API key. You can connect again with the same URL.

`sessions.create` and `sessions.retrieve` return the URL with its token. `sessions.list` returns it without the token, so retrieve a session from the list before you connect to it.

This program creates a session, connects Playwright, prints a page's title, and releases the session.

**TypeScript**

```ts file=cdp.mts
import Steel from "steel-sdk";
import { chromium } from "playwright";

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

try {
  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=cdp.py
from playwright.sync_api import sync_playwright
from steel import Steel

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

try:
    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)
```

Install the Steel SDK and Playwright, then run the program. Playwright connects to a remote browser, so you do not need to install one.

**TypeScript**

```sh
npm install steel-sdk playwright
npx tsx cdp.mts
```

**Python**

```sh
python3 -m venv .venv
source .venv/bin/activate
pip install steel-sdk playwright
python cdp.py
```

The program prints the page's title:

```text nocopy
Example Domain
```

Puppeteer connects to the same URL with `puppeteer.connect({ browserWSEndpoint })`. Use `puppeteer-core`, which does not download a browser. The integration guides have complete programs:

- [Connect Playwright to Steel](https://steel.dev/docs/integrations/playwright)
- [Connect Puppeteer to Steel](https://steel.dev/docs/integrations/puppeteer)

> **Warning**
>
> Anyone with the `websocketUrl` can control the session until it ends. Do not log it, and give it only to code that you trust.

## Use the default context

A session's browser starts with one context, and one page in it. Use that context and its first page, or a new page if it has none, as the program above does. Open new pages in that context when the task needs another tab.

A context that you create with `browser.newContext()` starts empty. Steel loads a [profile](https://steel.dev/docs/logins/profiles) or a [session context](https://steel.dev/docs/logins/session-context) into the default context, so their cookies are not in a new context.

## Release the session

Closing the client does not end the session. `browser.close()` in Playwright and `browser.disconnect()` in Puppeteer close the connection, but the browser keeps running, and keeps costing browser time, until its timeout. If the browser itself exits, for example after a client sends the CDP method `Browser.close`, Steel releases the session. Release the session in `finally`, as the program above does. In Go, release it in a `defer`. In Rust, release it after the `async` block:

**TypeScript**

```ts
await client.sessions.release(session.id);
```

**Python**

```python
client.sessions.release(session.id)
```

**Go**

```go
defer func() {
	if _, err := client.Sessions.Release(ctx, session.ID); err != nil {
		log.Print(err)
	}
}()
```

**Rust**

```rust
client.sessions().release(&session.id).await?;
```

While the session runs, you can connect to it again with the same URL. The page and its state are where the last client left them. If you set `inactivityTimeout`, a session that gets no activity for that long ends. A CDP message counts as activity. [Release idle sessions](https://steel.dev/docs/sessions/timeouts#release-idle-sessions) lists the other kinds of activity.

## Check that it worked

The program prints `Example Domain`, the title of the page that Playwright loaded in the session. To check that the session ended, pass its `id` to `client.sessions.retrieve` after the program exits. The session's `status` is `released`, and its `releaseReason` (`release_reason` in Python) is `user_requested`.

## CDP methods that Steel restricts

Steel passes most CDP messages to the browser unchanged. It blocks or changes a few, to protect the machine that runs the browser:

| CDP method | What Steel does |
| - | - |
| `SystemInfo.getInfo`, `SystemInfo.getProcessInfo`, `Target.exposeDevToolsProtocol`, `Tracing.start` | Blocks the call. |
| `DOM.setFileInputFiles`, `Input.dispatchDragEvent` with files, `Extensions.loadUnpacked` | Blocks the call when a file path is outside the session's `/files` folder. |
| `Browser.setDownloadBehavior`, `Page.setDownloadBehavior` | Saves downloads in the session's `/files` folder, whatever path you pass. |
| `Emulation.setDeviceMetricsOverride` with Puppeteer's default viewport of 800 by 600 (`width` 800, `height` 600, `deviceScaleFactor` 1, `mobile` false) | Uses the session's screen size instead of 800 by 600. |

A blocked call returns a CDP error, such as:

```json nocopy
{
  "id": 12,
  "error": {
    "code": -32601,
    "message": "CDP method 'Tracing.start' is not permitted in this environment"
  }
}
```

A blocked file path returns the code `-32602` and the message `CDP method 'DOM.setFileInputFiles' was blocked: file path is outside the permitted directory`. To give a page a file, upload it to the session first. See [Files](https://steel.dev/docs/sessions/files).

## Troubleshooting

### `401 Unauthorized`

```json nocopy
{"error":"Unauthorized","message":"A valid API key or session connect token is required for this WebSocket."}
```

Some connections answer `{"error":"unauthorized"}` instead.

**Cause:** The URL has no valid token. A URL from `sessions.list` has no token, and a token works only for its own session.

**Fix:** Connect to the `websocketUrl` that `sessions.create` or `sessions.retrieve` returns, as it is.

**Verify:** The client connects, and the program prints the page's title.

### `404 Not Found`

```json nocopy
{"error":"Not Found","message":"The requested browser session is not running or does not belong to this organization."}
```

Some connections answer `{"error":"session not found"}` instead.

**Cause:** The session was released, or it reached its timeout. A released session cannot run again.

**Fix:** Create a new session and connect to its `websocketUrl`.

**Verify:** The client connects to the new session.

### `503 Service Unavailable`

```json nocopy
{"error":"session not ready"}
```

**Cause:** Steel cannot reach a live session's browser. The browser may still be starting.

**Fix:** Wait a few seconds and connect again. If the error continues, release the session and create a new one.

**Verify:** The client connects, and the program prints the page's title.

### The connection closes while the program runs

**Cause:** The session ended. It reached its timeout or inactivity timeout, or another program released it.

**Fix:** Retrieve the session with `client.sessions.retrieve` and check its `status`. If it is `released`, create a new session, and set a longer `timeout` if the task needs more time. See [Set timeouts](https://steel.dev/docs/sessions/timeouts).

**Verify:** The program runs to the end, and the session is released in `finally`.

## Next steps

- [Live view](https://steel.dev/docs/observability/live-view): Watch the browser while your code drives it.
