Skip to content

Live view

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 →

Live view shows a running session's browser in real time. Use it to watch an agent work, to debug a step that fails, or to let a person click and type in the browser, for example to sign in or to solve a CAPTCHA.

A headful session, the default, streams its screen as video over WebRTC, at 20 frames per second in H.264. A headless session shows an older view, made from screen captures of the page.

Before you begin

Put your Steel API key in the STEEL_API_KEY environment variable, and install the Steel SDK for your language: TypeScript, Python, Go or Rust.

Open the live view

Every session object has two URLs that open the live view:

FieldWhat it opensShare it with
sessionViewerUrlThe session viewer, the session's page in the Steel dashboard. It shows the live view while the session runs, and the recording, logs and agent traces after it ends.Members of your organization.
debugUrlThe live view alone, without the dashboard. Open it in a browser tab, or embed it in your app.Anyone who should see the browser.

This program creates a session, prints its debugUrl, and waits. Open the URL in your browser to watch the session. Press Enter to release it.

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

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

try {
  console.log(session.debugUrl);
  const prompt = createInterface({ input: process.stdin, output: process.stdout });
  await prompt.question("Press Enter to release the session.");
  prompt.close();
} finally {
  await client.sessions.release(session.id);
}

Run the program:

npx tsx live-view.mts
https://api.steel.dev/v1/sessions/d59e5571-8560-4c3f-b098-bc8d12c4b886/player/…
Press Enter to release the session.

The debugUrl holds a viewer token, so it works without an API key. The token expires 24 hours after the time at which the timeout would end the session, even if the session ends earlier. Use the URL as Steel returns it. You can add query parameters, but do not build the URL from the session ID.

To list a live session's open tabs, with each tab's URL and title, call sessions.liveDetails (sessions.live_details in Python, Sessions.LiveDetails in Go and sessions().live_details in Rust).

Turn off input in the live view

A live view accepts mouse and keyboard input by default. To make it view-only, do one of these:

  • Set debugConfig.interactive to false when you create the session. No viewer can send input, whatever URL they open.
  • Add interactive=false to the debugUrl for one viewer. Other viewers keep their input.
const session = await client.sessions.create({
  debugConfig: { interactive: false },
});

The URL parameter can only take input away. If the session has debugConfig.interactive set to false, interactive=true in the URL does not give it back. A viewer who has the debugUrl can remove interactive=false from it. To stop input for every viewer, use debugConfig.interactive.

A view-only live view still shows everything on the screen. It does not replace access control in your app.

debugConfig.systemCursor sets whether the video shows the mouse cursor. It is true by default, and it does not change whether the view accepts input.

Embed the live view in your app

To show the live view in your own app, put the debugUrl in an iframe. Create the session on your server, and send only the debugUrl to the page, never the API key.

<iframe
  src="DEBUG_URL?interactive=false"
  style="width: 100%; height: 600px; border: none;"
></iframe>

Replace DEBUG_URL with the session's debugUrl. Add the parameters with URL.searchParams in TypeScript, or urllib.parse in Python, so that you keep any parameter that the URL already has. In Go, use the net/url package. In Rust, use the url crate.

The live view reads these parameters. Some work only in a headful or only in a headless session:

ParameterDefaultSessionWhat it does
interactivetrueHeadful and headlessfalse makes the view view-only.
hideInteractionDialogfalseHeadfultrue skips the "Click to interact" prompt, so the view takes input at once.
hideOverlayfalseHeadfultrue hides the view's loading and error screens, so that you can show your own. The frame still reports its state to your page with postMessage events, such as steel:ready.
themedarkHeadlessThe view's colors: dark or light.
showControlstrueHeadlessfalse hides the navigation controls.
pageIdNoneHeadlessShows the tab with this ID.
pageIndexNoneHeadlessShows the tab at this position.

These guides show each task from start to finish:

Check that it worked

Open the debugUrl that the program prints in a browser tab, before you press Enter. The live view loads and shows the session's browser. When you press Enter, the program releases the session, and the live view stops. To watch the view follow your code, open the debugUrl that the program in Embed a live browser in your app prints: the view shows the browser opening example.com.

Troubleshooting

The live view stays blank

Cause: The session has ended, the browser cannot play H.264 video, or the frame that holds the view has no size.

Fix: Retrieve the session and check that its status is live. If the session ended, create a new one. Open the view in a browser that plays H.264 video. Give the iframe a fixed width and height.

Verify: The view shows the page that the browser has open.

Session not found

{
  "error": "Not Found",
  "message": "Session not found. It may have ended, expired, or belong to a different organization. Check the session id, or list your sessions to confirm it exists.",
  "linkToDocs": "https://docs.steel.dev/overview/sessions-api/session-lifecycle"
}

Cause: The live view did not accept the URL. The URL has no viewer token or a wrong one, because it was built from the session ID or cut short. Or the token has expired, 24 hours after the time at which the timeout would end the session.

Fix: Use the debugUrl exactly as the session object returns it, and add parameters to it with URL.searchParams. For an old session, retrieve it again and use its debugUrl.

Verify: Open the URL in a browser tab. The live view loads.

Next steps