Skip to content

CDP

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 →

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

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);
}

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

npm install steel-sdk playwright
npx tsx cdp.mts

The program prints the page's title:

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:

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 or a 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:

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

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 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 methodWhat Steel does
SystemInfo.getInfo, SystemInfo.getProcessInfo, Target.exposeDevToolsProtocol, Tracing.startBlocks the call.
DOM.setFileInputFiles, Input.dispatchDragEvent with files, Extensions.loadUnpackedBlocks the call when a file path is outside the session's /files folder.
Browser.setDownloadBehavior, Page.setDownloadBehaviorSaves 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:

{
  "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.

Troubleshooting

401 Unauthorized

{"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

{"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

{"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.

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

Next steps

  • Live view: Watch the browser while your code drives it.