WBX Sandbox
Sandboxes

Desktop environment (XFCE)

What is on the desktop of a desktop sandbox, how to start programs on it from your code, your agent or the terminal, and how to add more software. The desktop is part of Desktop & Computer Use (beta, enabled per team on request).

What is inside

PartDetails
SystemDebian 12 (bookworm), 2 vCPU, 2 GB memory and an 8 GB disk by default – billed by vCPU and memory like any sandbox
Screena virtual 1280×800 screen (Xvfb, display :0); the size is fixed
DesktopXFCE – panel with the Applications menu at the top, desktop icons, window manager with workspaces
Desktop useruser (uid 1000), home /home/user; the desktop and everything started from it run as this user, not as root
ProgramsChromium (chromium; the window title says Chrome for Testing) – also opened by Web Browser in the menu, Terminal (xfce4-terminal), File Manager (Thunar), Application Finder and the XFCE Settings
For automationPython 3.12 with Playwright (its Chromium) and requests; xdotool, wmctrl, xrandr and ImageMagick (import)

A text editor, an office suite or other desktop programs are not preinstalled – install them when you need them.

Start a program on the desktop

Commands sent through the API, the SDKs and MCP (run_command) run as root in a shell without a screen. To open a window on the desktop, run the program as the desktop user with DISPLAY=:0 and in the background, so the command returns while the window stays open:

from wbxsandbox import Sandbox

sb = Sandbox.create(template="desktop", timeout=1800)
sb.run("su user -c 'DISPLAY=:0 nohup chromium https://example.com >/dev/null 2>&1 &'")
sb.run("su user -c 'DISPLAY=:0 nohup xfce4-terminal >/dev/null 2>&1 &'")
print(sb.run("DISPLAY=:0 wmctrl -l").stdout)   # open windows
import { WBX } from "wbxsandbox";

const wbx = new WBX({ apiKey: process.env.WBXSANDBOX_API_KEY! });
const sb = await wbx.sandboxes.create({ template: "desktop", timeoutSeconds: 1800 });
await sb.commands.run("su user -c 'DISPLAY=:0 nohup chromium https://example.com >/dev/null 2>&1 &'");
console.log((await sb.commands.run("DISPLAY=:0 wmctrl -l")).stdout);
# in the portal's Terminal (you are root)
su user -c 'DISPLAY=:0 nohup chromium https://example.com >/dev/null 2>&1 &'
DISPLAY=:0 wmctrl -l

In the live console you can of course start programs the usual way – take control and use the Applications menu, the desktop icons or the Terminal on the desktop. To check what is open, DISPLAY=:0 wmctrl -l lists the windows; DISPLAY=:0 wmctrl -a "Example" brings a window to the front.

Playwright on the visible screen

Playwright normally runs the browser without a window. On a desktop sandbox you can run it with a visible window, so you can follow – or help – in the live console while your script works:

sb.files.write("/home/user/visit.py", """
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
    browser = p.chromium.launch(headless=False)     # a window on the desktop
    page = browser.new_page()
    page.goto("https://example.com")
    print(page.title())
    browser.close()
""")
print(sb.run("su user -c 'DISPLAY=:0 python3 /home/user/visit.py'").stdout)

Where a page has a clear structure, Playwright selectors are faster and more reliable than coordinates. Use screenshots and mouse/keyboard actions for what Playwright cannot reach: other programs, native dialogs, canvas-heavy pages.

Install more software

You are root in the sandbox, so apt and pip work as on any Debian machine (the sandbox needs internet access, which it has by default):

sb.run("apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y mousepad", timeout=300)
sb.run("su user -c 'DISPLAY=:0 nohup mousepad >/dev/null 2>&1 &'")

Programs installed this way stay in the sandbox's files – also while it sleeps – but not in other sandboxes. If your agent needs the same programs every time, ask us for a custom template so they are ready when the sandbox starts (see Templates).

Files and downloads

  • The desktop user's files are in /home/user; files Chromium downloads go to /home/user/Downloads.
  • Read and write them with the Files API, the SDKs or MCP, or open them in the File Manager on the desktop.
  • A file you create as root (through run_command) belongs to root – chown user:user FILE if a desktop program should change it.

Sleep, wake and restarts

  • When the sandbox falls asleep, its files stay but every running program – windows included – stops. After it wakes up, the desktop starts again within a few seconds (computer/status reports available: true when it is ready); start your programs again.
  • Watching in the console does not keep the sandbox awake. Commands, actions and your input while in control do.

Using it with an agent

A typical loop for an agent is: take a screenshot, decide, act with the mouse and keyboard, take a screenshot again to check. Over MCP the tools are computer_screenshot and computer_action (they appear only when the feature is enabled for your team); start programs with run_command as shown above. Keep the screenshots small (JPEG, max_width) – they go to the model as images. Details and limits: Desktop & Computer Use.