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:
npm install steel-sdk playwrightpython3 -m venv .venv
source .venv/bin/activate
pip install steel-sdk playwright1. 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.
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);
}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:
npx tsx live.mtspython live.pyThe program prints what your server would send to the page:
{
"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 says when.
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.
<iframe
src="DEBUG_URL"
title="Browser session"
style="width: 100%; height: 600px; border: 0"
></iframe>In React, pass the URL that your server returned:
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:
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?;To make one frame view-only while another frame stays interactive, add interactive=false to that frame's URL:
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 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 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.
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();
}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.textIn 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 explains, so fetch a new playlist each time the page asks for one.
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:
<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. 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 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.