---
title: Stream a Vercel Sandbox Desktop to Your Browser
product: vercel
url: /docs/sandbox/examples/desktop-streaming
canonical_url: "https://vercel.com/docs/sandbox/examples/desktop-streaming"
last_updated: 2018-10-20
type: how-to
prerequisites:
  - /docs/sandbox/examples
  - /docs/sandbox
related:
  - /docs/sandbox/pricing
  - /docs/sandbox/quickstart
  - /docs/sandbox/concepts/images
  - /docs/sandbox/examples/expose-a-port
  - /docs/sandbox/cli-reference
summary: Stream the desktop of a Vercel Sandbox to your browser with screen-relay, and control its applications from your browser or from an agent.
install_vercel_plugin: npx plugins add vercel/vercel-plugin
search_with_vercel_cli: npx vercel@latest docs search "<query>"
---

# Stream a Vercel Sandbox Desktop to Your Browser

A sandbox can run graphical applications such as a browser, an image editor, or Blender, but it has no screen. [screen-relay](https://github.com/vercel-labs/screen-relay), an open-source tool from Vercel Labs, gives it one. It starts a Linux desktop inside the sandbox and streams that desktop to your browser as live video.

- **Sandbox to your browser**: screen-relay sends video of the sandbox's desktop to a viewer page, so anything that appears on its screen is streamed, whether you interact with it or only watch. Nothing on your own computer is captured or shared.
- **Your browser to the sandbox**: when you take control in the viewer, your mouse and keyboard input is replayed on the sandbox's desktop, so you control its applications in real time.
- **Agents**: an agent controls the same desktop with commands in place of video. It clicks or types, then takes a screenshot to see the result. screen-relay applies each command in milliseconds, and you can watch the agent work in the viewer.

> **💡 Note:** Anyone with a session's viewer link can view and control its desktop. Keep
> viewer links and tokens out of recordings, repositories, and model-visible
> messages.

## Prerequisites

- A Vercel account. [Sandbox pricing and limits](/docs/sandbox/pricing) apply while the desktop runs.
- Node.js and npm on your computer, to install the Sandbox CLI. This guide needs Sandbox CLI 4.12.0 or newer. The Python SDK doesn't need Node.js, but the CLI commands in this guide do.
- To start the desktop from the SDK: a project with the [Sandbox SDK](/docs/sandbox/quickstart) installed, on Node.js 22 or newer for TypeScript, or Python 3.11 or newer for Python.
- A current version of Chrome, Edge, or Safari to open the viewer.

The examples start from the default [Vercel Managed Image](/docs/sandbox/concepts/images#vercel-managed-images), so you don't need a custom image.

## Start a desktop

Use the Sandbox CLI or the Sandbox SDK. Both create a sandbox named `desktop` that [publishes port `8080`](/docs/sandbox/examples/expose-a-port), then install and start screen-relay in it.

`screen-relay` is a command-line tool that you install from npm inside the sandbox. Its `up` command starts the desktop.

### With the Sandbox CLI

Install the [Sandbox CLI](/docs/sandbox/cli-reference#installation) and sign in with your Vercel account:

```bash filename="Terminal"
npm install -g sandbox
sandbox login
```

Then create the sandbox and start the desktop. You can paste these commands as they are:

```bash filename="Terminal"
sandbox create --name desktop --timeout 30m -p 8080
sandbox exec desktop -- npm install -g screen-relay
sandbox exec desktop -- screen-relay up -d --yes --public $(sandbox domain desktop 8080)
```

`sandbox domain desktop 8080` prints the sandbox's public URL, so you don't need to copy it by hand.

On the first run, the last command prints a few hundred lines of installation output before the viewer link. To print only the link, run this in place of the last command:

```bash filename="Terminal"
sandbox exec desktop -- screen-relay up -d --yes \
  --public $(sandbox domain desktop 8080) 2>/dev/null
```

Copy the link from your terminal into your browser. `2>/dev/null` hides errors too. If no link appears after a few minutes, run the command without it.

### With the Sandbox SDK

In a project set up with the [quickstart](/docs/sandbox/quickstart), run this script:

**index.ts**

```ts filename="index.ts"
import { Sandbox } from '@vercel/sandbox';

const sandbox = await Sandbox.getOrCreate({
  name: 'desktop',
  ports: [8080],
  timeout: 30 * 60 * 1000,
});
const publicUrl = sandbox.domain(8080);

// Capture the output instead of streaming it to your terminal.
const result = await sandbox.runCommand({
  cmd: 'sh',
  args: [
    '-c',
    `npm install -g screen-relay >&2 && screen-relay up -d --yes --public ${publicUrl}`,
  ],
});
if (result.exitCode !== 0) {
  throw new Error('screen-relay did not start. Run `screen-relay logs` in the sandbox.');
}

// Print only the viewer link, after checking that it points at this sandbox.
const link = (await result.stdout()).trim().split('\n').at(-1) ?? '';
const viewer = URL.canParse(link) ? new URL(link) : null;
if (
  !viewer ||
  viewer.origin !== new URL(publicUrl).origin ||
  !viewer.hash.startsWith('#token=')
) {
  throw new Error('screen-relay printed an unexpected viewer link.');
}
console.log(viewer.href);
```

**main.py**

```py filename="main.py"
import asyncio
from urllib.parse import urlsplit

from vercel import sandbox


async def main() -> None:
    box, _ = await sandbox.get_or_create_sandbox(
        name="desktop",
        ports=[8080],
        execution_time_limit=30 * 60,
    )
    url = next(route.url for route in box.routes if route.port == 8080)

    # Capture the output instead of streaming it to your terminal.
    result = await box.run_command(
        "sh",
        ["-c", f"npm install -g screen-relay >&2 && screen-relay up -d --yes --public {url}"],
        capture_output=True,
        check=True,
    )

    # Print only the viewer link, after checking that it points at this sandbox.
    lines = result.stdout.decode(errors="replace").strip().splitlines()
    link = lines[-1] if lines else ""
    viewer, public = urlsplit(link), urlsplit(url)
    same_origin = (viewer.scheme, viewer.netloc) == (public.scheme, public.netloc)
    has_token = viewer.fragment.startswith("token=")
    if not (same_origin and has_token and link.isascii() and link.isprintable()):
        raise RuntimeError("screen-relay printed an unexpected viewer link.")
    print(link)


asyncio.run(main())
```

The script captures screen-relay's output, checks that the viewer link points at your sandbox, and prints only that link, token included. Run it in your own terminal, not where output is stored or shared, such as CI logs. If the script fails, run `sandbox exec desktop -- screen-relay logs` to see why.

The rest of this guide uses the Sandbox CLI. If you started with the SDK, install the CLI as shown above and run it from the same project directory as your script, so that both use the same Vercel project.

### Open the viewer link

Both ways end by printing a viewer link:

```text filename="Terminal"
https://your_sandbox_domain.vercel.run/#token=your_token
```

Open the full link in your browser to see the desktop. The viewer opens view-only. To use your mouse and keyboard, select the control button at the top of the viewer and choose **Take control**. Choose **Release control** to hand input back.

The token is a random secret that screen-relay creates when the desktop starts. Only someone with the full link, token included, can see or control the desktop, so keep it private.

- **First session**: the first start takes from about a minute to several minutes, because `screen-relay up` installs a virtual screen, the XFCE desktop, and the libraries its streaming engine needs, then builds the engine. `--yes` lets it install without asking for confirmation.
- **Later sessions**: a sandbox keeps its files when it stops, so screen-relay stays installed and the desktop starts in seconds. With the SDK, run the script again. With the CLI, see [Start the desktop again](#start-the-desktop-again).
- **`--public`** tells screen-relay the sandbox's public URL, so the viewer link works from outside the sandbox.

## Open an application

`screen-relay run` starts a program on the sandbox's desktop. Each example below installs an application with the image's package manager, as in [Install system packages](/docs/sandbox/examples/install-system-packages), and opens it. You can paste the commands as they are.

### Browser

```bash filename="Terminal"
sandbox exec --sudo desktop -- curl -fsSLo /root/chrome.deb \
  https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sandbox exec --sudo desktop -- apt-get install -y /root/chrome.deb
sandbox exec desktop -- screen-relay run -- google-chrome --no-first-run https://vercel.com
```

A Chrome window opens on the desktop and loads the Vercel homepage. `--no-first-run` skips the dialog that Chrome shows on first launch. The package downloads to `/root`, not `/tmp`, so a restricted user in a shared sandbox can't replace it before it's installed.

### Image editor

```bash filename="Terminal"
sandbox exec --sudo desktop -- apt-get install -y gimp
sandbox exec desktop -- screen-relay run -- gimp
```

GIMP opens with its welcome dialog.

### Blender

```bash filename="Terminal"
sandbox exec --sudo desktop -- apt-get install -y blender
sandbox exec desktop -- screen-relay run -- blender
```

Blender opens with its splash screen. It draws and renders on the sandbox's CPUs.

### Game

```bash filename="Terminal"
sandbox exec --sudo desktop -- apt-get install -y chocolate-doom freedoom
sandbox exec desktop -- screen-relay run -- /usr/games/chocolate-doom \
  -iwad /usr/share/games/doom/freedoom1.wad -window -nosound
```

Freedoom opens in a window. screen-relay streams video only, so the game runs without sound.

To open any other program, install it and start it with `sandbox exec desktop -- screen-relay run -- your_program`.

## screen-relay commands

Run each command in the sandbox by putting `sandbox exec desktop --` in front of it.

| Command                                 | What it does                                      |
| --------------------------------------- | ------------------------------------------------- |
| `screen-relay up`                       | Starts the desktop and prints the viewer link.    |
| `screen-relay down`                     | Stops the desktop and the applications on it.     |
| `screen-relay run -- your_program`      | Opens a program on the desktop.                   |
| `screen-relay status`                   | Shows whether the desktop is running.             |
| `screen-relay logs`                     | Prints recent log lines.                          |
| `screen-relay screenshot your_file.png` | Saves a picture of the screen.                    |
| `screen-relay click 0.5 0.5`            | Clicks at a point on the screen.                  |
| `screen-relay move 0.5 0.5`             | Moves the pointer.                                |
| `screen-relay scroll 0.5 0.5 --dy 3`    | Scrolls at a point.                               |
| `screen-relay type "your text"`         | Types text.                                       |
| `screen-relay key Enter`                | Presses a key, or a combination such as `ctrl+l`. |

Coordinates are fractions of the screen from `0` to `1`, measured from the top-left corner. `0.5 0.5` is the center.

## Let an agent control the desktop

Ask an agent that can run terminal commands, such as Claude Code, to use the desktop for you by describing the task. Keep the viewer open to watch it work:

```text filename="Prompt"
Use screen-relay in my sandbox named desktop to open a terminal and run `echo hello`.
```

To show the agent how, give it the [screen-relay commands](#screen-relay-commands) in your prompt or in your `AGENTS.md`. screen-relay also prints its own agent instructions with `sandbox exec desktop -- screen-relay skills get core`. That text comes from inside the sandbox, so read it before you copy it into your `AGENTS.md`, and don't have an agent load it on its own. The agent then:

1. Takes a screenshot to see the screen.
2. Clicks or types.
3. Takes another screenshot to check the result.

In the viewer, you see a terminal open and `hello` print below the command.

### What the agent runs

You don't need to run these commands yourself. For the prompt above, the agent runs commands like these. The last two save a screenshot and copy it to your computer. You can run them by hand to see each step:

```bash filename="Terminal"
sandbox exec desktop -- screen-relay run -- xfce4-terminal
sandbox exec desktop -- screen-relay click 0.5 0.5
sandbox exec desktop -- screen-relay type "echo hello"
sandbox exec desktop -- screen-relay key Enter
sandbox exec desktop -- screen-relay screenshot /tmp/screen.png
sandbox copy desktop:/tmp/screen.png ./screen.png
```

- **One controller at a time**: only one viewer or agent sends input. The viewer opens view-only, so an agent can send input while you watch. If you choose **Take control** in the viewer, the agent's input returns `busy` until you choose **Release control** or close the tab. Screenshots work at any time.
- **Speed**: each `sandbox exec` call adds a network round trip. An agent that runs inside the sandbox, or that uses [screen-relay's Node SDK](https://screen-relay.dev/docs/sdk), skips it.

## Stream the desktop into Claude, ChatGPT, and other apps

You can show the live desktop inside a conversation in a chat app such as Claude or ChatGPT, so you watch the model work without switching to a browser tab.

This uses [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview), an extension to the Model Context Protocol (MCP) that lets a tool show an interactive interface inside the chat. Here, that interface is the screen-relay viewer. screen-relay still does the streaming and control, and the chat app is another place to show the viewer.

The [screen-relay MCP Apps example](https://github.com/vercel-labs/screen-relay/tree/main/examples/mcp-app) is a prototype that you can start from:

1. Run the example's MCP server on your computer, with the sandbox's URL and the token in the server's environment.
2. Add the server to a chat app that [supports MCP Apps](https://modelcontextprotocol.io/extensions/client-matrix).
3. Ask the model to open the desktop. The viewer appears in the chat.

The example also gives the model tools to take screenshots and to act in the sandbox. Its README covers their setup.

- **Token**: keep the token in the server's environment, not in a prompt or a tool argument, so it stays out of the conversation.
- **Input**: the example's viewer has rendered in Claude Desktop and Codex. Mouse and keyboard input inside a chat app is not confirmed, so check it in the app you plan to use.

## Limits

- screen-relay streams video only. It does not support audio or the clipboard.
- One viewer or agent controls input at a time.
- A desktop has one token and no separate user identities. To replace an exposed token, stop the desktop and start it again.

## Troubleshoot the desktop

| Symptom                                                       | What to check                                                                                                                                                                                                                        |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| The viewer does not connect                                   | Port `8080` is published, `--public` matches the sandbox's URL, and you opened the full link with its token.                                                                                                                         |
| The viewer shows `WebCodecs unavailable in this browser`      | Use a current version of Chrome, Edge, or Safari. The viewer needs the browser's H.264 WebCodecs support.                                                                                                                            |
| Input returns `busy`                                          | A viewer that took control, or another controller, holds input. Choose **Release control** in the viewer or close its tab, then retry.                                                                                               |
| The viewer's control button reads **click to control**        | The sandbox has screen-relay 0.1.0, where an open viewer blocks an agent's input. To update, run `sandbox exec desktop -- screen-relay down`, then run the last two commands in [With the Sandbox CLI](#with-the-sandbox-cli) again. |
| An application does not appear                                | Start it with `screen-relay run` so it uses the desktop's display.                                                                                                                                                                   |
| The desktop stopped or failed                                 | Run `screen-relay status` and `screen-relay logs` in the sandbox.                                                                                                                                                                    |
| `screen-relay up` reports that the session is already running | The desktop is still running. Use the viewer link you have, or stop the desktop and start it again to print a link.                                                                                                                  |
| `sandbox domain` reports `Not a valid subcommand name`        | Your Sandbox CLI is older than 4.12.0. Update it with `npm install -g sandbox`.                                                                                                                                                      |
| `sandbox domain` reports no running session                   | The sandbox is stopped. Run `sandbox exec desktop -- true` to resume it, then retry.                                                                                                                                                 |
| `sandbox create` reports that the name already exists         | A stopped sandbox keeps its name. [Start the desktop again](#start-the-desktop-again), or [remove the sandbox](#remove-the-sandbox).                                                                                                 |

## Stop the desktop

```bash filename="Terminal"
sandbox exec desktop -- screen-relay down
sandbox stop desktop
```

Sandboxes are [persistent](/docs/sandbox/concepts/persistent-sandboxes) by default, so screen-relay and the applications you installed stay in place after a stop. For other ways to stop a sandbox, see [Stop a sandbox](/docs/sandbox/examples/stop-a-sandbox).

### Start the desktop again

```bash filename="Terminal"
sandbox exec desktop -- true
sandbox exec desktop -- screen-relay up -d --public $(sandbox domain desktop 8080)
```

The first command [resumes the same sandbox](/docs/sandbox/examples/resume-a-long-lived-sandbox) in a new session. The second starts the desktop without repeating the installation and prints a new viewer link.

### Remove the sandbox

Stopping saves the sandbox's files as a snapshot, which counts toward [Snapshot Storage](/docs/sandbox/pricing#snapshot-storage). To delete the sandbox and that snapshot when you're done, run:

```bash filename="Terminal"
sandbox rm desktop --delete-orphan-snapshots
```

Without `--delete-orphan-snapshots`, `sandbox rm` deletes the sandbox and keeps its snapshot until the snapshot expires. To delete a sandbox from the dashboard or the SDK, see [Delete a sandbox](/docs/sandbox/examples/delete-a-sandbox).

## Search the docs from your terminal

Search the Vercel docs and read pages as Markdown with the Vercel CLI. No login required.

```bash
# Find docs pages by keyword
npx vercel@latest docs search "environment variables"
npx vercel@latest docs search "function timeout"

# Print a docs page as Markdown, by path or URL
npx vercel@latest docs inspect <page>
```

---

[View full sitemap](/docs/sitemap)


If you encounter incorrect information, can’t find what you need, need a capability Vercel doesn’t currently offer, or have any other feedback to report, please do it by following the instructions at https://vercel.com/feedback.md.
