---
title: Vercel Sandbox
description: Run screen-relay in a Vercel Sandbox and open the desktop in your browser.
url: "https://screen-relay.dev/docs/vercel-sandbox"
docs_index: /llms.txt
lastUpdated: 2026-11-17
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

Run screen-relay in a Vercel Sandbox and open its desktop in your browser. The sandbox is the VM that runs the desktop.

The sandbox runs Ubuntu 26.04 on x86_64 as the `ubuntu` user, which has passwordless sudo. It needs Node 22 or newer with npm.

## With the Sandbox CLI

1. Install the [Sandbox CLI](https://vercel.com/docs/vercel-sandbox/cli-reference) and sign in:

   ```sh
   npm install -g sandbox
   sandbox login
   ```

2. Create a sandbox and publish port 8080:

   ```sh
   sandbox create --name screen-relay --timeout 45m -p 8080
   ```

   The command prints a URL like `https://sb-xxxx.vercel.run`. Use your URL in place of the example in the commands below. Hobby plans cap the sandbox timeout at 45 minutes. On plans that allow longer runtimes, `sandbox extend screen-relay 30m` adds 30 minutes.

3. Install screen-relay from npm, then set up the machine. Setup can take several minutes.

   ```sh
   sandbox exec screen-relay sh -c 'npm install -g screen-relay'
   sandbox exec screen-relay sh -c 'screen-relay install --yes'
   ```

4. Start screen-relay with your public URL:

   ```sh
   sandbox exec screen-relay sh -c 'screen-relay up -d --public https://sb-xxxx.vercel.run'
   ```

   Open the viewer link that the command prints in your browser. It includes `#token=` and grants access to the desktop, so keep it secret.

   For Wayland, add `--backend wayland` to both the `screen-relay install` and `screen-relay up` commands. See [Linux](/docs/linux).

5. Take a screenshot inside the sandbox:

   ```sh
   sandbox exec screen-relay sh -c 'screen-relay screenshot /tmp/screen.png'
   ```

   The PNG is saved inside the sandbox. To control the desktop from your laptop, [install the screen-relay CLI](/docs/remote-access) and save the token from the viewer link into a local file named `token`:

   ```sh
   screen-relay screenshot screen.png --url https://sb-xxxx.vercel.run --token-file ./token
   ```

   See [Tokens](/docs/remote-access#tokens) and the [Node SDK options](/docs/sdk#options) for remote access.

6. Remove the sandbox and its sessions:

   ```sh
   sandbox rm screen-relay
   ```

   Existing snapshots are kept.

Agents can load these instructions with `screen-relay skills get vercel-sandbox`.

## With the Sandbox SDK

Prerequisites:

- Node.js 24, and a project with the [Vercel CLI](https://vercel.com/docs/cli) installed.

1. In the project, install the Sandbox SDK, link the project, and pull its environment:

   ```sh
   npm install @vercel/sandbox
   vercel link
   vercel env pull
   ```

2. Save this as `relay-sandbox.mjs`:

   ```js
   import { Sandbox } from '@vercel/sandbox';

   const sandbox = await Sandbox.create({
     name: 'relay-sdk',
     ports: [8080],
     timeout: 45 * 60 * 1000,
   });

   const install = await sandbox.runCommand({
     cmd: 'sh',
     args: ['-c', 'npm install -g screen-relay && screen-relay install --yes'],
     stdout: process.stdout,
     stderr: process.stderr,
   });
   if (install.exitCode !== 0) throw new Error('screen-relay installation failed');

   const start = await sandbox.runCommand({
     cmd: 'sh',
     args: ['-c', 'screen-relay up -d --public "$1"', 'sh', sandbox.domain(8080)],
     stdout: process.stdout,
     stderr: process.stderr,
   });
   if (start.exitCode !== 0) throw new Error('screen-relay failed to start');
   ```

3. Run the script:

   ```sh
   node --env-file=.env.local relay-sandbox.mjs
   ```

The script prints the viewer link after installation. Open it in your browser, and keep it secret.

To clean up, remove the sandbox with `sandbox rm relay-sdk`, or call [`sandbox.delete()`](https://vercel.com/docs/sandbox/sdk-reference#sandbox.delete) in your application. Removal keeps existing snapshots.

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)