Live view
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:
| Field | What it opens | Share it with |
|---|---|---|
sessionViewerUrl | The 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. |
debugUrl | The 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.
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);
}from steel import Steel
client = Steel()
session = client.sessions.create()
try:
print(session.debug_url)
input("Press Enter to release the session.")
finally:
client.sessions.release(session.id)package main
import (
"context"
"fmt"
"log"
"github.com/steel-dev/sdk/go"
)
func main() {
if err := run(context.Background()); err != nil {
log.Fatal(err)
}
}
func run(ctx context.Context) error {
client := steel.NewClient()
session, err := client.Sessions.New(ctx, steel.SessionNewParams{})
if err != nil {
return err
}
defer func() {
if _, err := client.Sessions.Release(ctx, session.ID); err != nil {
log.Print(err)
}
}()
fmt.Println(session.DebugURL)
fmt.Print("Press Enter to release the session.")
fmt.Scanln()
return nil
}#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = steel_rs::Client::new();
let session = client
.sessions()
.create(steel_rs::SessionCreateParams::default())
.await?;
let result: Result<(), Box<dyn std::error::Error>> = async {
println!("{}", session.debug_url);
println!("Press Enter to release the session.");
std::io::stdin().read_line(&mut String::new())?;
Ok(())
}
.await;
client.sessions().release(&session.id).await?;
result
}Run the program:
npx tsx live-view.mtspython live_view.pygo run .cargo runhttps://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.interactivetofalsewhen you create the session. No viewer can send input, whatever URL they open. - Add
interactive=falseto thedebugUrlfor one viewer. Other viewers keep their input.
const session = await client.sessions.create({
debugConfig: { interactive: false },
});session = client.sessions.create(
debug_config={"interactive": False},
)session, err := client.Sessions.New(ctx, steel.SessionNewParams{
DebugConfig: steel.F(steel.SessionNewParamsDebugConfig{
Interactive: steel.F(false),
}),
})
if err != nil {
return err
}let session = client
.sessions()
.create(steel_rs::SessionCreateParams {
debug_config: Some(steel_rs::SessionCreateParamsDebugConfig {
interactive: Some(false),
..Default::default()
}),
..Default::default()
})
.await?;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:
| Parameter | Default | Session | What it does |
|---|---|---|---|
interactive | true | Headful and headless | false makes the view view-only. |
hideInteractionDialog | false | Headful | true skips the "Click to interact" prompt, so the view takes input at once. |
hideOverlay | false | Headful | true 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. |
theme | dark | Headless | The view's colors: dark or light. |
showControls | true | Headless | false hides the navigation controls. |
pageId | None | Headless | Shows the tab with this ID. |
pageIndex | None | Headless | Shows the tab at this position. |
These guides show each task from start to finish:
- Embed a live browser in your appShow a running session in your product.
- Hand control to a humanPause your agent, let a person act, then continue.
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.