***

title: Live View
description: 'Embed a real-time, interactive view of a running browser runtime.'
--------------------------------------------------------------------------------

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

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

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

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

## Options

```ts
const { iframeUrl, token, expiresAt } = await runtime.live({
  interactive: true,
  showControls: true,
  viewerMode: "automation",
});
```

| Parameter      | Type                          | Required | Description                                                                                                                 |
| -------------- | ----------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| `interactive`  | `boolean`                     | No       | Allow mouse and keyboard interaction (default: `false`)                                                                     |
| `showControls` | `boolean`                     | No       | Show browser chrome — tab strip, URL bar, navigation buttons (default: `true`)                                              |
| `viewerMode`   | `'last_used' \| 'automation'` | No       | Which tab to follow — `last_used` tracks the tab the user last interacted with, `automation` tracks the tab being automated |

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

```ts
// View-only — for monitoring dashboards
const monitor = await runtime.live({ interactive: false });

// Interactive — for human-in-the-loop workflows
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:

```ts
async function keepAlive(runtime, iframe) {
  const { iframeUrl, expiresAt } = await runtime.live({ interactive: true });
  iframe.src = iframeUrl;

  // Refresh before expiry
  const expiresIn = new Date(expiresAt).getTime() - Date.now();
  setTimeout(() => keepAlive(runtime, iframe), expiresIn - 60_000);
}
```

## HTTP equivalent

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

```json
{
  "interactive": true,
  "showControls": true,
  "viewerMode": "automation"
}
```

Response:

```json
{
  "iframeUrl": "https://...",
  "token": "eyJ...",
  "expiresAt": "2025-01-15T12:00:00Z"
}
```