# Use the desktop and browser

> How to start a sandbox's desktop, drive its Chromium browser from an agent, and watch or take control from the dashboard.

Every sandbox has a desktop with Chromium. It is off until you start it and costs nothing beyond the sandbox. This guide shows how to start it, drive the browser, and watch it.

## Start the desktop and open a page

1. Create a sandbox. Each open page takes 250 to 350 MB of memory, so `standard` suits most browsing. `small` holds a few tabs.

   ```bash
   SB=$(div sandbox create --size standard)
   ```

2. Start the desktop. The command returns when the browser is ready, after a few seconds.

   ```bash
   div sandbox desktop $SB
   ```

   The output includes a dashboard link where you can watch the screen.

3. Open a page.

   ```bash
   div sandbox open $SB https://example.com
   ```

If you want a different screen size, pass `--resolution` to `desktop`, up to `1920x1080`.

## Drive the browser with the accessibility tree

Use the accessibility tree first. It lists every button, link and field on screen, uses fewer tokens than a screenshot, and does not change when the layout shifts.

1. Read the tree for the browser:

   ```bash
   div sandbox a11y $SB --app chromium > tree.json
   ```

2. Find the node you want by its `role` and `name`, and note its `ref`, for example `n12`.

3. Act on it:

   ```bash
   div sandbox a11y $SB do n12 set-text 'https://example.com/login'
   div sandbox a11y $SB do n7 press
   ```

If an action is refused because the page changed, read the tree again and use the new ref.

If the output ends with `"truncated": true`, narrow it with `--app` or `--depth`.

## Drive the browser with screenshots and input

Use screenshots and input for what the tree does not describe, such as a canvas. This is also how computer-use models work.

```bash
div sandbox screenshot $SB shot.png
div sandbox input $SB click 640 400
div sandbox input $SB type 'hello world'
div sandbox input $SB key Return
```

Positions are pixels in the screenshot, from the top left. A node's `bounds` in the accessibility tree use the same pixels, so you can click the center of a node.

To read small text, capture part of the screen. `--region` takes the top-left and bottom-right corners, and the PNG is that part scaled up to the screen size:

```bash
div sandbox screenshot $SB zoom.png --region 0,0,640,400
```

Other inputs:

```bash
div sandbox input $SB click 640 400 --count 3      # select a line
div sandbox input $SB click 200 300 --mods ctrl    # open a link in a new tab
div sandbox input $SB key Down --repeat 5
div sandbox input $SB hold shift --seconds 2
div sandbox input $SB cursor                       # prints {"x":640,"y":400}
```

To let Claude, an OpenAI model or the AI SDK drive the desktop from your own code, use the [TypeScript SDK](https://docs.divergentlabs.xyz/sandboxes/sdk.md), which runs their computer-use tool calls on the desktop.

## Drive the browser with Playwright or Puppeteer

The desktop's Chromium serves the DevTools protocol on port 9222 in the sandbox.

- From a script inside the sandbox, connect to `http://127.0.0.1:9222`.
- From your machine, forward the port, then connect to `http://localhost:9222`:

  ```bash
  div sandbox forward $SB 9222
  ```

  ```js
  const browser = await chromium.connectOverCDP('http://localhost:9222')
  ```

Playwright controls the same browser that is on screen.

## Watch the screen or take control

1. Open the sandbox's page in the dashboard. The link is in the output of `div sandbox desktop`.
2. Click **Take over** to use the keyboard and mouse yourself, for example to solve a CAPTCHA or enter a one-time code.
3. Click **Hand back** when you are done.

Only org members signed in to the dashboard can watch there. An agent uses `div sandbox screenshot` instead. To show the screen to your own users in your product, see [Add computer use to your product](https://docs.divergentlabs.xyz/sandboxes/computer-use.md).

If you want to watch in a VNC viewer, run `div sandbox forward $SB 5900` and connect the viewer to `localhost:5900`.

## Sign in once and reuse the session

The browser keeps its cookies and sign-ins on the sandbox's disk.

1. Sign the sandbox in to the sites a task needs.
2. Stop it: `div sandbox stop $SB`.
3. Fork it for each task: `div sandbox fork $SB`. Each fork starts signed in.

A stopped and resumed sandbox is also still signed in, and its windows are still open. A fork starts with the desktop off.

## Run other programs on the screen

While the desktop runs, a program with a window that you start with `div sandbox exec` opens on the screen.

## Stop the desktop

```bash
div sandbox desktop $SB stop
```

To check whether it is running, use `div sandbox desktop $SB status`.

## Limitations

- A sandbox has no GPU. Pages, forms and documents work well. WebGL and video are slow.
- Commands that need the desktop fail with exit code 1 and the code `no_desktop` when it is not running. Start it with `div sandbox desktop`.
- A sandbox created before an input action existed refuses that action with `desktop_outdated`. Create a new sandbox to use it.

For every flag and the full tree format, see [`div sandbox`](https://docs.divergentlabs.xyz/sandboxes/cli/sandbox.md#desktop). For agents using MCP, see [Sandbox MCP tools](https://docs.divergentlabs.xyz/sandboxes/mcp.md#desktop). For code, see the [TypeScript SDK](https://docs.divergentlabs.xyz/sandboxes/sdk.md).