---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/observability/live-view
markdown_url: https://steel.dev/docs/observability/live-view.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Live view
description: Watch a running session in real time, let a person take control, or embed the view in your own app.
summary: Watch a running session in real time, let a person take control, or embed the view in your own app.
type: how-to
reviewed: 2026-11-12
prerequisites: []
related:
  - https://steel.dev/docs/observability/debug-a-failed-session.md
  - https://steel.dev/docs/observability/embed-a-live-browser.md
  - https://steel.dev/docs/observability/hand-control-to-a-human.md
  - https://steel.dev/docs/observability/recordings.md
  - https://steel.dev/docs/observability/logs.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# 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](https://steel.dev/docs/reference/sdks/typescript#install), [Python](https://steel.dev/docs/reference/sdks/python#install), [Go](https://steel.dev/docs/reference/sdks/go#install) or [Rust](https://steel.dev/docs/reference/sdks/rust#install).

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

**TypeScript**

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

**Python**

```python file=live_view.py
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)
```

**Go**

```go file=main.go
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
}
```

**Rust**

```rust file=src/main.rs
#[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:

**TypeScript**

```sh
npx tsx live-view.mts
```

**Python**

```sh
python live_view.py
```

**Go**

```sh
go run .
```

**Rust**

```sh
cargo run
```

```text nocopy
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.

> **Warning**
>
> Anyone who has the `debugUrl` can watch the session, and can control it unless the view is view-only. The view can show a signed-in account and its data. Give the URL only to the people who should see the session, and keep it out of logs and analytics.

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.

**TypeScript**

```ts
const session = await client.sessions.create({
  debugConfig: { interactive: false },
});
```

**Python**

```python
session = client.sessions.create(
    debug_config={"interactive": False},
)
```

**Go**

```go
session, err := client.Sessions.New(ctx, steel.SessionNewParams{
	DebugConfig: steel.F(steel.SessionNewParamsDebugConfig{
		Interactive: steel.F(false),
	}),
})
if err != nil {
	return err
}
```

**Rust**

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

```html
<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 app](https://steel.dev/docs/observability/embed-a-live-browser): Show a running session in your product.
- [Hand control to a human](https://steel.dev/docs/observability/hand-control-to-a-human): Pause 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](https://steel.dev/docs/observability/embed-a-live-browser#1-get-the-embed-url) 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

```json nocopy
{
  "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

- [Recordings](https://steel.dev/docs/observability/recordings): Watch the session after it ends, when the live view stops.
- [Agent traces](https://steel.dev/docs/observability/agent-traces): Find the exact action behind what you saw in the live view.
