# 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](https://sandbox.wbx.cz/docs/sandboxes/desktop.md) (beta, enabled per team on request).

## What is inside

| Part | Details |
| --- | --- |
| System | Debian 12 (bookworm), 2 vCPU, 2 GB memory and an 8 GB disk by default – billed by vCPU and memory like any sandbox |
| Screen | a virtual 1280×800 screen (Xvfb, display `:0`); the size is fixed |
| Desktop | XFCE – panel with the *Applications* menu at the top, desktop icons, window manager with workspaces |
| Desktop user | `user` (uid 1000), home `/home/user`; the desktop and everything started from it run as this user, not as root |
| Programs | **Chromium** (`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 automation | Python 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](#install) 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:

**Python**

```
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
```

**TypeScript**

```
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);
```

**Terminal**

```
# 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](https://sandbox.wbx.cz/docs/sandboxes/console.md) 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](https://sandbox.wbx.cz/docs/sandboxes/desktop.md) 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](https://sandbox.wbx.cz/docs/templates.md)).

## 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](https://sandbox.wbx.cz/docs/sandboxes/files.md), 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](https://sandbox.wbx.cz/docs/sandboxes/desktop.md).

Source: https://sandbox.wbx.cz/docs/sandboxes/desktop-environment
