divergent/docs
Sandboxes

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.

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

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

    div sandbox desktop $SB

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

  3. Open a page.

    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:

    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:

    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.

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:

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

Other inputs:

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, 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:

    div sandbox forward $SB 9222
    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.

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

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. For agents using MCP, see Sandbox MCP tools. For code, see the TypeScript SDK.

esc