> ## Documentation Index
> Fetch the complete documentation index at: https://vms.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# See the desktop of a sandbox

> Open the desktop of a running sandbox, or only its Chrome window, in a browser tab at 1080p and 60 frames each second, with sound.

Each sandbox has a desktop. It starts when the sandbox starts. Open it in a browser tab to watch your agent or to help it. The desktop shows at 1080p and 60 frames each second, with sound. With no viewer, it uses about 350 MiB of memory in the sandbox.

With the CLI, `vms desktop <name>` opens the desktop in your default browser. Add `--mode browser` to show only Chrome. See [CLI reference](https://vms.dev/docs/reference/cli.md#desktop).

Write the code that opens the desktop of a sandbox.

Use POST /v1/sandboxes/{id}/desktop-sessions to get a desktop link for a running sandbox.
Open the url of the answer in a browser within 10 minutes.
Do not ask me to share my API key.

## Before you start

* You need an API key with the `sandboxes:desktop` scope. See [API keys](https://vms.dev/docs/workspace/api-keys.md).
* The sandbox must be `running`.

## Open the desktop

In the app, open a running sandbox on the **Sandboxes** page and choose **Open desktop**. See [Open the desktop](https://vms.dev/docs/sandboxes/in-the-app.md#open-the-desktop).

With the API, send `POST /v1/sandboxes/{id}/desktop-sessions`.

```typescript TypeScript theme={null}
const response = await fetch(
  `https://vms.dev/api/v1/sandboxes/${sandboxId}/desktop-sessions`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VMS_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({}),
  },
);

const session = await response.json();
```

```bash cURL theme={null}
curl -X POST "https://vms.dev/api/v1/sandboxes/sbx_06d8k3m7q2v9x4b1n5c0e8f2ja/desktop-sessions" \
  -H "Authorization: Bearer $VMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

The answer is `201` with the link:

```json theme={null}
{
  "id": "dsk_06d8k3m7q2v9x4b1n5c0e8f2jc",
  "sandboxId": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
  "mode": "desktop",
  "url": "https://agent-42-desktop-k3m7q2v9.vmsdev.run/?_token=vmsd_Gq3n0Yb1c2d3e4f5g6h7i8j9k0l1m2n3o4p5q6r7s8t",
  "expiresAt": "2026-11-16T03:40:00.000Z",
  "createdAt": "2026-11-16T03:30:00.000Z"
}
```

Open `url` in a browser. The link contains a token, so do not share it.

To see only the Chrome window of the sandbox, send `"mode": "browser"`. See [Show only Chrome](#show-only-chrome).

* The link stops working at `expiresAt`, 10 minutes after the create, if nobody opens it.
* The link opens one time. A second open answers `401`.
* A browser that opens the link gets a cookie and shows the desktop. The cookie works for 1 hour. Each load of the desktop page checks your access again and gives a new cookie for 1 hour.
* If the member who made the link leaves the workspace, or you delete the API key that made it, the desktop page answers `403`.
* Each create gives a new link. Make a new link for each person or each browser.

| Problem | Answer |
| - | - |
| The API key has no `sandboxes:desktop` scope | `403` |
| The `mode` is not `desktop` or `browser` | `400` with `invalid` |
| The sandbox does not exist | `404` |
| The sandbox is not running | `409` with `sandbox_not_running`, `sandbox_starting`, or `sandbox_stopping` |
| The link expired or was used, or the browser has no cookie | `401` when you open the desktop |
| The person or the API key that made the link has no access now | `403` when you open the desktop |

## Use the desktop

* The mouse and the keyboard of your browser control the desktop.
* A program in the sandbox shows on the desktop when it uses the display `:0`. Commands and SSH sessions have `DISPLAY=:0`. For example, run `xterm &`.
* A computer-use agent in the sandbox can use the same display.

## Show only Chrome

Send `"mode": "browser"` to get a link that shows only the Chrome window of the sandbox. You and a computer-use agent see the same page.

```typescript TypeScript theme={null}
const response = await fetch(
  `https://vms.dev/api/v1/sandboxes/${sandboxId}/desktop-sessions`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VMS_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ mode: "browser" }),
  },
);

const session = await response.json();
```

```bash cURL theme={null}
curl -X POST "https://vms.dev/api/v1/sandboxes/sbx_06d8k3m7q2v9x4b1n5c0e8f2ja/desktop-sessions" \
  -H "Authorization: Bearer $VMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "browser"}'
```

* Chrome fills the screen and stays above the other windows.
* If Chrome is not open, it opens when the page loads.
* The sandbox has one screen. The last page that loads sets what it shows. A `desktop` link shows the other windows again.
* This mode changes the view only. A person with the link can use the keyboard and the mouse as in `desktop` mode.

Chrome in the sandbox uses the profile `/home/user/.config/vms-browser`. It accepts the Chrome DevTools Protocol on `127.0.0.1:9222`, so an agent in the sandbox can control the page that you see. To open Chrome from a command, run `sudo systemctl start vms-desktop-browser`.

## Sound

The stream carries the sound of the sandbox. A program that plays sound in the sandbox plays in your browser tab. For example, play a video in Chrome, or run `paplay sound.wav` with a WAV file of your own.

* Your browser starts the sound after you click or press a key in the tab.
* Programs in the sandbox use PulseAudio. Commands and SSH sessions connect to it with no setup.

## Networks and firewalls

The desktop streams the screen with WebRTC. It connects directly over IPv6 when it can. On a network that blocks a direct connection, such as a strict NAT or a company firewall, the desktop goes through a relay (TURN) on the host of the sandbox. You do not set anything.

Read the [changelog.](https://vms.dev/docs/changelog.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.