Desktop Streaming

Every box includes a browser-accessible Linux desktop. Use it when you need to inspect a running app visually, use Chrome, debug Electron apps, or control GUI tools that are awkward over SSH. The box’s own agents drive that same screen through the built-in computer tools, so you can watch a prompt do GUI work live.

Open the desktop

From your local machine, open an authenticated desktop URL. Integrations can request the same URL through the SDK or API:

box desktop bx_f7k2q9hd

curl -sS -X POST "$BOX_API_BASE/boxes/bx_f7k2q9hd/desktop?theme=light" \
  -H "Authorization: Bearer $BOX_API_KEY"

const desktop = await box.desktop({ boxId: "bx_f7k2q9hd", theme: "light" });
console.log(desktop.desktopUrl);

desktop = box.desktop("bx_f7k2q9hd", theme="light")
print(desktop.desktop_url)

You can also open the desktop from the Boxes tab of the dashboard while the box is running.

Desktop streaming is available only after the box’s machine is up. If the box is provisioning, archived, or stopped, start or resume it first.

Streaming modes

The default desktop streams video and audio over Moonlight (WebRTC) at 1920x1080 and 60 fps. WebRTC relies on UDP and peer connectivity, so on restrictive, corporate, or low-bandwidth networks it can be choppy or fail to connect. For those cases, use VNC, which tunnels over plain HTTPS and is far more tolerant of poor connections (at a lower frame rate):

box desktop bx_f7k2q9hd --vnc
box desktop bx_f7k2q9hd --vnc --public

curl -sS -X POST "$BOX_API_BASE/boxes/bx_f7k2q9hd/desktop?vnc=1" \
  -H "Authorization: Bearer $BOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"publicAccess":true}'

const vnc = await box.desktop({
  boxId: "bx_f7k2q9hd",
  vnc: 1,
  requestBody: { publicAccess: true },
});
console.log(vnc.desktopUrl);

vnc = box.desktop("bx_f7k2q9hd", vnc=1, request_body={"publicAccess": True})
print(vnc.desktop_url)

You don’t have to decide up front: the browser viewer shows a “Switch to VNC” option while the default stream is connecting or playing, and again if it errors. The dashboard box menu exposes Desktop, Browser, and Desktop via VNC.

The VNC viewer opens as its own top-level page (not embedded), which is required for its connection to authenticate. The first --vnc on a box takes a few seconds to prepare; later opens are instant.

Open only the browser

Use a browser-only view when someone should see and control Chrome without seeing the Box desktop. From the dashboard, open the box menu and choose Browser. From the CLI:

box browser bx_f7k2q9hd
box browser bx_f7k2q9hd --profile /data/chrome-profile

Pass --profile <absolute path on the box> to run the stream on a specific Chrome user data dir, so one box can hold several signed-in profiles and you choose which one to open. The directory is created for you, must sit outside system directories and outside /home/user, and travels with the box’s snapshots and forks. Boxes created before this feature return chrome_profile_unsupported. This opens a separate browser surface on the same running Box. The stream is 1920x1080 at 60 fps, the same as the default desktop. Chrome keeps its tabs and address bar. Window-close chrome is hidden on purpose, and Chrome’s minimize cannot leave the stream on a blank desktop. Closing the last tab opens a new tab and does not tear down the stream. Running box browser again leaves the live stream up and prints a new URL. Opening that URL in a second tab takes the stream from the first tab. Desktop and browser can run together. Two browser viewer tabs cannot share. The new one takes the stream. The viewer keeps the same mute, reconnect, and fullscreen controls as the desktop stream. New boxes get the browser-view files at provision; the guest image must already have Chrome, X, Openbox, Sunshine, and Moonlight. Its Moonlight process, streaming identity, active-stream slot, and clipboard policy are isolated from the desktop stream, so browser URLs cannot attach to the direct desktop stream. It does not create another Box, and it never falls back to the desktop or VNC.

Browser-only means the stream is confined to Chrome and does not expose controls for closing it. It is not a security boundary against code already running inside the Box. A Box user with arbitrary code execution or root can inspect or change the browser process and its data. Treat the returned URL as a secret.

Drive the desktop

The desktop on this page is the same screen the Box’s coding agents drive. Every harness on a Box has a built-in set of computer tools for screenshots, clicks, typing, scrolling, and launching apps, so a prompt is all it takes:

box prompt bx_f7k2q9hd "Open example.com in Chrome and tell me the page title"

curl -sS -X POST "$BOX_API_BASE/boxes/bx_f7k2q9hd/prompt" \
  -H "Authorization: Bearer $BOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Open example.com in Chrome and tell me the page title"}'

await box.prompt({
  boxId: "bx_f7k2q9hd",
  promptRequest: { prompt: "Open example.com in Chrome and tell me the page title" },
});

box.prompt("bx_f7k2q9hd", PromptRequest(
    prompt="Open example.com in Chrome and tell me the page title",
))

Open a stream in one window and watch it happen in the other. There is nothing to install and nothing to register: the tools are already on every harness. See Computer use for the full tool list, the per-harness names, and the health check. Shell commands still work on the same screen, and mix freely with prompts. Put a page up yourself, then hand the box a visual task:

box exec bx_f7k2q9hd 'DISPLAY=:0 google-chrome-stable "https://example.com" & sleep 2; wmctrl -a Chrome'
box prompt bx_f7k2q9hd "Complete the checkout flow in the open browser window"

curl -sS -X POST "$BOX_API_BASE/boxes/bx_f7k2q9hd/commands" \
  -H "Authorization: Bearer $BOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command":"DISPLAY=:0 google-chrome-stable \"https://example.com\" & sleep 2; wmctrl -a Chrome"}'

await box.command({
  boxId: "bx_f7k2q9hd",
  commandRequest: { command: 'DISPLAY=:0 google-chrome-stable "https://example.com" & sleep 2; wmctrl -a Chrome' },
});

box.command("bx_f7k2q9hd", CommandRequest(
    command='DISPLAY=:0 google-chrome-stable "https://example.com" & sleep 2; wmctrl -a Chrome',
))

A Box has one screen, and every conversation on it drives that same screen. Two agents clicking at once will fight over it, so give each parallel GUI task its own Box, or run them one after another.

Record what happens on screen

ascii-record-desktop captures the live desktop to an MP4 from inside the Box, which is the simplest way to produce a demo or keep evidence of a GUI run:

box exec bx_f7k2q9hd "ascii-record-desktop start /home/user/demo.mp4"
# ... drive the desktop ...
box exec bx_f7k2q9hd "ascii-record-desktop stop"
box scp bx_f7k2q9hd:/home/user/demo.mp4 ./demo.mp4

curl -sS -X POST "$BOX_API_BASE/boxes/bx_f7k2q9hd/commands" \
  -H "Authorization: Bearer $BOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command":"ascii-record-desktop start /home/user/demo.mp4"}'

curl -L -o demo.mp4 "$BOX_API_BASE/boxes/bx_f7k2q9hd/artifacts?path=demo.mp4" \
  -H "Authorization: Bearer $BOX_API_KEY"

await box.command({
  boxId: "bx_f7k2q9hd",
  commandRequest: { command: "ascii-record-desktop start /home/user/demo.mp4" },
});
const video = await box.artifact({ boxId: "bx_f7k2q9hd", path: "demo.mp4" });

box.command("bx_f7k2q9hd", CommandRequest(
    command="ascii-record-desktop start /home/user/demo.mp4",
))
video = box.artifact("bx_f7k2q9hd", "demo.mp4")

ascii-record-desktop status reports whether a capture is running. To share a recording instead of downloading it, serve its folder from the box and expose it with a token-gated URL:

box ssh bx_f7k2q9hd "cd ~ && (python3 -m http.server 8090 --bind 0.0.0.0 &) && host 8090 --private"

What happens when you open it

The CLI or dashboard asks Box for a fresh authenticated desktop URL for your box. If the desktop stream is not ready yet, Box prepares it and then opens the browser viewer. The returned URL opens a browser page. For the default Moonlight stream it looks like this:

https://<box-desktop-host>/stream.html?hostId=<host>&appId=<app>&theme=light#token=<token>

For a VNC stream (--vnc) it points at a noVNC page instead:

https://<box-vnc-host>/vnc.html?autoconnect=true&password=<pw>&_token=<token>

If you request --public or send publicAccess: true to POST /boxes/{boxId}/desktop?vnc=1, the noVNC URL does not include _token. The exact host, IDs, password, and token fields are generated for the running box. The Moonlight viewer removes its fragment immediately, sends the token in authenticated request headers and the first WebSocket frame, and never puts it in an HTTP or WebSocket request URL. Treat desktop URLs as sensitive because they can let the browser attach to that desktop session.

Security model

Desktop URLs are generated through the authenticated Box API and expire after ten minutes. Box list and info responses do not cache or return a desktop URL; call the desktop endpoint each time you open a stream. The returned URL contains a desktop access token in its fragment, so do not paste the full URL into shared chats or logs. If you need to give someone else access to a box, use the intended Box account and access controls rather than sharing a desktop URL. Desktop clipboard reads and writes are enabled only for the credentials of the active desktop Moonlight stream. Browser-only streaming does not register clipboard routes. Stopping or archiving a box makes the desktop unavailable until the box is resumed. Do not rely on desktop processes surviving resume or fork. After a resume or fork, reopen Chrome and restart your app or dev server. The computer tools come back on their own: the desktop daemon behind them is restarted with the box.

​Open the desktop

​Streaming modes

​Open only the browser

​Drive the desktop

​Record what happens on screen

​What happens when you open it

​Security model

​Related

Open the desktop

Streaming modes

Open only the browser

Drive the desktop

Record what happens on screen

What happens when you open it

Security model

Related