What is a Desktop Sandbox?

A desktop sandbox is an isolated virtual environment that provides a complete desktop operating system where computer-use agents can safely execute tasks. Think of it as a disposable computer that your agent can control without risk to your real system.

Why Use Sandboxes?

Running AI agents directly on your computer poses risks:

• Unintended actions - Agents might click the wrong button or delete files
• Security concerns - Malicious content could affect your system
• State pollution - Each run might leave behind artifacts that affect future runs
• Reproducibility - Hard to ensure consistent starting conditions

Sandboxes solve these problems by providing:

• Isolation - Actions in the sandbox don't affect your host system
• Reset capability - Start fresh for each task
• Safety - Experiment freely without consequences
• Consistency - Identical environment every time
• Reproducibility - Define dependencies and configurations that create baseline environments your agents can rely on

Sandbox Options in Cua

Cua supports multiple sandbox types to fit different needs:

Cloud Sandboxes

Managed virtual machines hosted by Cua's infrastructure.

# Create a cloud sandbox
cua sb create --os linux --size small --region north-america

Docker Sandboxes

Linux desktops running in Docker containers on your machine.

# Pull and run a Docker sandbox
docker pull trycua/cua-xfce:latest

QEMU Docker Sandboxes

Full virtual machines (Linux, Windows, Android) running inside Docker via QEMU emulation.

macOS Sandboxes (Lume)

Native macOS virtual machines using Apple's Virtualization framework.

# Start a macOS sandbox
lume run macos-sequoia-cua:latest

Windows Sandbox

Native Windows sandbox using Windows Sandbox feature.

How Sandboxes Connect to Agents

Your agent interacts with sandboxes through the Computer Framework:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│                 │     │                 │     │                 │
│   Your Agent    │────▶│    Computer     │────▶│    Sandbox      │
│   (AI Logic)    │     │   Framework     │     │   (Desktop)     │
│                 │◀────│                 │◀────│                 │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                              │
                              │ Unified API
                              │
                    ┌─────────┴─────────┐
                    │                   │
              Screenshots          Actions
              (what agent sees)    (click, type, etc.)

The Computer Framework provides the same API regardless of which sandbox type you're using. This means you can:

• Develop locally with Docker
• Test on specific platforms with QEMU
• Deploy to production with Cloud Sandboxes

...all without changing your agent code.

Choosing the Right Sandbox

Next Steps

• Set Up a Sandbox to create your first environment
• Learn about Computer SDK for controlling sandboxes
• Explore Computer SDK Reference for production deployments