---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/observability/embed-a-live-browser
markdown_url: https://steel.dev/docs/observability/embed-a-live-browser.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Embed a live browser in your app
description: Show a running Steel session inside your product with an embedded live view, interactive or view-only.
summary: Show a running Steel session inside your product with an embedded live view, interactive or view-only.
type: how-to
reviewed: 2026-11-12
prerequisites: []
related:
  - https://steel.dev/docs/observability/debug-a-failed-session.md
  - https://steel.dev/docs/observability/live-view.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
---

# Embed a live browser in your app

An embedded live view shows a running session inside your own product, so that your users can watch the agent work or take over a step. Your server creates the session and sends its live view URL to the page, and the page shows it in a frame. After the session ends, the page can play the recording in the same place.

## Before you begin

Keep the API key on your server. The page in the user's browser needs only the live view URL, which works without a key.

Put your Steel API key in the `STEEL_API_KEY` environment variable on the server. Then install the Steel SDK and Playwright:

**TypeScript**

```sh
npm install steel-sdk playwright
```

**Python**

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

## 1. Get the embed URL

A session's `debugUrl` is the URL to embed. Your server creates the session, returns `debugUrl` to the page, and drives the browser.

This program stands in for your server. It creates a session, prints the URL, and drives the browser for one minute, so that you can watch it in the frame from the next step. Then it releases the session.

**TypeScript**

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

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

try {
  console.log(JSON.stringify({ sessionId: session.id, debugUrl: session.debugUrl }, null, 2));
  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");
  await page.waitForTimeout(60000);
  await browser.close();
} finally {
  await client.sessions.release(session.id);
}
```

**Python**

```python file=live.py
import json

from playwright.sync_api import sync_playwright
from steel import Steel

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

try:
    print(json.dumps({"sessionId": session.id, "debugUrl": session.debug_url}, indent=2))
    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")
        page.wait_for_timeout(60000)
        browser.close()
finally:
    client.sessions.release(session.id)
```

Run the program:

**TypeScript**

```sh
npx tsx live.mts
```

**Python**

```sh
python live.py
```

The program prints what your server would send to the page:

```json nocopy
{
  "sessionId": "12dc5345-a617-46dd-a32c-24d77feeccc3",
  "debugUrl": "https://api.steel.dev/v1/sessions/12dc5345-a617-46dd-a32c-24d77feeccc3/player/…"
}
```

Use `debugUrl` as the API returns it. It holds a token that lets the page open the live view without your API key. The token expires after the session ends, and [Live view](https://steel.dev/docs/observability/live-view#open-the-live-view) says when.

> **Warning**
>
> Anyone who has the `debugUrl` can watch the session, and can control it while the view is interactive. Send it only to users who may see that browser, after your app has checked who they are. Do not write it to logs or analytics.

## 2. Add the frame to your page

Show the URL in an `iframe`. Give the frame a fixed height. A height of at least 600 pixels leaves room to read and click.

```html file=index.html
<iframe
  src="DEBUG_URL"
  title="Browser session"
  style="width: 100%; height: 600px; border: 0"
></iframe>
```

In React, pass the URL that your server returned:

```tsx file=SessionView.tsx
export function SessionView({ debugUrl }: { debugUrl: string }) {
  return (
    <iframe
      src={debugUrl}
      title="Browser session"
      style={{ width: "100%", height: 600, border: 0 }}
    />
  );
}
```

Open the page while the program from the previous step runs. The frame shows the browser on `example.com`, and it stays live until the session ends.

Hiding or removing the frame does not end the session. Release the session from your server when the task is done or when the user leaves.

## 3. Choose interactive or view-only

By default, the person who sees the frame can click, scroll and type in the browser. Every input goes to the real session.

To make the live view view-only for everyone, set `debugConfig.interactive` to `false` when you create the session:

**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?;
```

To make one frame view-only while another frame stays interactive, add `interactive=false` to that frame's URL:

```ts
const viewer = new URL(session.debugUrl);
viewer.searchParams.set("interactive", "false");
```

The URL parameter can turn input off, but not on. A user who reads the frame's URL can remove the parameter, so use `debugConfig.interactive` when nobody may control the session. When the session has `debugConfig.interactive` set to `false`, no frame can control it. Both settings change only the live view. They do not limit your own code, which controls the session over CDP (Chrome DevTools Protocol). [Live view](https://steel.dev/docs/observability/live-view#embed-the-live-view-in-your-app) lists the other URL parameters, such as `hideOverlay`, which lets you show your own loading screen.

If a user will take over a step, pause your agent first. [Hand control to a human](https://steel.dev/docs/observability/hand-control-to-a-human) shows the full handoff.

## 4. Show the replay after the session ends

When the session ends, the live view stops. To show what happened, play the recording. Steel records each session by default. A session that you create with `recording` set to `false` has no recording.

The recording is an HLS playlist at `GET /v1/sessions/{id}/hls`, and the request needs your API key. Add a route to your server that fetches the playlist and returns it to the page. The playlist links to the video files with signed URLs, so the page loads the video without your key.

**TypeScript**

```ts file=replay.mts
const apiKey = process.env.STEEL_API_KEY!;

export async function getReplayPlaylist(sessionId: string): Promise<string> {
  const response = await fetch(`https://api.steel.dev/v1/sessions/${sessionId}/hls`, {
    headers: { "steel-api-key": apiKey },
  });
  if (!response.ok) {
    throw new Error(`No recording for session ${sessionId}: ${response.status}`);
  }
  return response.text();
}
```

**Python**

```python file=replay.py
import os

import httpx

api_key = os.environ["STEEL_API_KEY"]


def get_replay_playlist(session_id: str) -> str:
    response = httpx.get(
        f"https://api.steel.dev/v1/sessions/{session_id}/hls",
        headers={"steel-api-key": api_key},
    )
    response.raise_for_status()
    return response.text
```

In Python, `httpx` comes with `steel-sdk`. Return the playlist with the content type `application/vnd.apple.mpegurl`. The signed URLs in it expire, as [Recordings](https://steel.dev/docs/observability/recordings#fetch-the-recording) explains, so fetch a new playlist each time the page asks for one.

> **Warning**
>
> The route uses your API key, so it can return the recording of any session in your organization to anyone who changes the session ID in its URL. Before you return a playlist, check that the signed-in user may see that session.

On the page, replace the frame with a video player that plays HLS. This example uses the hls.js library, and `/replays/SESSION_ID.m3u8` is the route on your server:

```html file=replay.html
<video id="replay" controls playsinline style="width: 100%"></video>
<script type="module">
  import Hls from "https://cdn.jsdelivr.net/npm/hls.js@^1.5.0/dist/hls.mjs";

  const video = document.getElementById("replay");
  const playlist = "/replays/SESSION_ID.m3u8";
  if (Hls.isSupported()) {
    const hls = new Hls();
    hls.loadSource(playlist);
    hls.attachMedia(video);
  } else if (video.canPlayType("application/vnd.apple.mpegurl")) {
    video.src = playlist;
  }
</script>
```

The video plays the session as the browser showed it. Steel keeps recordings for your plan's data retention period. See [Limits](https://steel.dev/docs/platform/limits). [Recordings](https://steel.dev/docs/observability/recordings) has the other ways to fetch and replay a recording.

## Check that it worked

Keep your page open while the program from [1. Get the embed URL](https://steel.dev/docs/observability/embed-a-live-browser#1-get-the-embed-url) runs. The frame shows `example.com` for one minute, and the live view stops when the program releases the session. A few seconds later, the playlist is ready. Load your replay page: the video shows the same browser on `example.com`.

## Next steps

- [Hand control to a human](https://steel.dev/docs/observability/hand-control-to-a-human): Pause your agent while a person finishes a step in the embedded view.
- [Live view](https://steel.dev/docs/observability/live-view): See every parameter that the live view URL takes.
