Live View

The live view gives you an embeddable iframe that streams the browser in real time. Use it to watch automation as it happens, or let users interact with the browser directly.

Access via runtime.live().

Getting the embed URL

1
const { iframeUrl } = await runtime.live();

The returned iframeUrl is a fully authenticated, time-limited URL you can drop into an <iframe>.

1
<iframe src={iframeUrl} style="width: 100%; height: 600px; border: none;" />

Options

1
const { iframeUrl, token, expiresAt } = await runtime.live({
2
  interactive: true,
3
  showControls: true,
4
  viewerMode: "automation",
5
});

Returns { iframeUrl: string, token: string, expiresAt: string }

Viewer modes

• last_used — The viewer follows whichever tab was most recently interacted with. Best for human-facing dashboards where the user may switch tabs.
• automation — The viewer follows the tab currently being automated by the SDK. Best for observability — you always see what the agent sees.

Interactive vs view-only

When interactive: true, the embedded browser accepts mouse clicks, keyboard input, and tab management. The user can navigate, type, and click just like a local browser.

When interactive: false (default), the viewer is read-only — a live stream of what the browser is doing, but no input is forwarded.

1
// View-only — for monitoring dashboards
2
const monitor = await runtime.live({ interactive: false });
3
4
// Interactive — for human-in-the-loop workflows
5
const handoff = await runtime.live({ interactive: true, showControls: true });

Viewer features

The live viewer includes:

• Tab strip — See all open tabs, switch between them, create new tabs, close tabs (when interactive)
• URL bar — Shows the current page URL, allows direct navigation (when interactive)
• Navigation buttons — Back, forward, reload (when interactive)
• Follow-active toggle — Automatically follow the active tab or pin to a specific one
• Fullscreen — Expand the viewer to fill the screen

Token lifecycle

The embed URL contains a short-lived token. When it expires, the iframe will stop streaming. To keep a long-running embed alive, mint a new URL periodically:

1
async function keepAlive(runtime, iframe) {
2
  const { iframeUrl, expiresAt } = await runtime.live({ interactive: true });
3
  iframe.src = iframeUrl;
4
5
  // Refresh before expiry
6
  const expiresIn = new Date(expiresAt).getTime() - Date.now();
7
  setTimeout(() => keepAlive(runtime, iframe), expiresIn - 60_000);
8
}

HTTP equivalent

POST /v1/workspaces/{workspaceId}/runtimes/{alias}/embed/live

1
{
2
  "interactive": true,
3
  "showControls": true,
4
  "viewerMode": "automation"
5
}

Response:

1
{
2
  "iframeUrl": "https://...",
3
  "token": "eyJ...",
4
  "expiresAt": "2025-01-15T12:00:00Z"
5
}