How sandboxes work

How a Cua Sandbox gives an agent one isolated computer it can both run code in and drive through the GUI.

A Cua Sandbox is a full, isolated computer, not a remote desktop session. In that one machine, an agent can run code through Python, shell commands, or a PTY, and it can also drive the graphical interface through screenshots, the accessibility tree, clicks, and typing.

Those are two complementary halves of the same computer. The code half and the GUI half share one filesystem, one set of processes, and one OS state. The value is that they live in the same place. An agent can click through an app and then run a Python function against the files or process state that app produced. It can also set up state in code and then automate the UI over that state.

The Sandbox SDK is the shared interface. Local execution starts the guest through a runtime on your hardware; Fleet manages hosted capacity in pools, and a claim reserves a guest for your workload. They share the sandbox concept, but differ in image preparation, credentials, supported operations, and cleanup. Use Cloud Fleets for the hosted path or Manage local sandbox lifecycle for local setup.

For the broader model that combines code, structured tools, and graphical interfaces, read What is computer use?.

Sandboxes and real machines#

Cua Driver observes and controls the desktop where it is installed and targeted. That can be your existing computer or a guest with a compatible installation and connection path. Running Driver on your host does not automatically target a sandbox guest.

A sandbox is an isolated computer created for a task. It starts from an image and accumulates its own state. Deleting it discards that state, so save any results you need first. Code and GUI actions through the sandbox connection target the guest. Explicitly shared files and exposed services remain connections to the outside world.

This isolation is what makes a sandbox useful for repeatable agent work. The agent gets a whole computer, but the effects are contained within that computer.

The code half and the GUI half#

The code half is how an agent runs programs inside the sandbox. It includes shell commands through shell.run, an interactive PTY or terminal through computer.pty and cua do shell, and sandboxed Python that runs a function inside the sandbox's own virtualenv through venv_install, venv_exec, and the @sandboxed decorator.

The GUI half is how an agent uses the sandbox like a desktop computer. It can observe the screen through screenshots and the accessibility tree, then act through clicks, typing, scrolling, keypresses, and other input events.

The Sandbox SDK's default Fleet connection uses the guest's computer-server endpoint. Fleet provisions and manages the capacity; the SDK acquires a guest and connects to its service. Using Cua Driver in that guest requires its own compatible installation and validated integration; it does not follow merely from creating a pool. See How Fleet images work for the default guest service contract.

Because both halves are interfaces to the same machine, they can be mixed within one task. A shell command can create a file that is opened in the GUI. A GUI workflow can download data that is then inspected with Python. A PTY session can start a server, and the GUI half can open a browser against it. The important point is that all of these actions share the same filesystem and OS state.

Containers and full VMs#

A Linux container sandbox starts quickly because it shares the host kernel. It layers a Linux userspace, a desktop such as XFCE, and a remote display stack such as KasmWeb. This makes startup fast, but it is not identical to a physical Linux box. Kernel behavior, device access, and isolation come from the container host.

A full VM emulates hardware and boots its own kernel. macOS sandboxes use Apple Virtualization. Windows sandboxes use QEMU or Hyper-V. Android sandboxes use QEMU. Full VMs are slower to start than containers, but they provide higher OS fidelity because the guest OS owns its kernel and hardware model.

The trade-off is startup latency versus OS fidelity. Containers are suited to fast Linux environments. Full VMs are suited to work that depends on the behavior of a complete guest operating system.

Images as starting-state contracts#

An Image is the immutable description of the sandbox's starting environment. It is not the running sandbox. An Image defines the OS type, distro or OS version, packages, environment variables, copied files, and setup commands that should exist when a sandbox starts.

The image builder composes layers such as apt_install, pip_install, run, copy, and env. Local execution applies those layers at launch to produce the sandbox's initial state. Fleet instead boots a prebuilt registry artifact and rejects these builder layers. Installing another package later changes that sandbox, not the Image. How Fleet images work explains the published-artifact model.

This separation makes environments reproducible. The Image describes what a fresh sandbox should look like. The sandbox is the live machine created from that description.

Lifecycle patterns#

The patterns below describe local sandbox ownership. Fleet pools and claims add a separate capacity lifetime: releasing a claim does not delete its pool or remove the pool's desired warm capacity. Cloud Fleets links the hosted workflow and resource cleanup guides.

Sandbox lifetime is separate from agent connection lifetime. An ephemeral sandbox exists for one block of work and is destroyed at the end. This fits CI jobs, tests, and one-shot tasks where the state has no value afterward.

A persistent or named sandbox is created once, identified by name, and can survive process exits. A later process can reconnect to the same sandbox and continue from the state it already has.

Connect mode attaches to an already-running sandbox. It does not create a sandbox and it does not delete one. Disconnecting drops the control connection. Deleting destroys the machine and its state. Those are different operations, and the distinction matters when the sandbox contains work that should survive the current process. Sandbox lifecycle explains local ownership and Fleet capacity; Manage local sandbox lifecycle shows the local SDK patterns.

Snapshots and forks#

A snapshot records a machine's state for later reuse. A fork starts a separate machine from that captured state. These mechanisms can avoid repeating expensive setup, but they require support from the provisioning and storage system.

In cua-sandbox 0.7.0, Sandbox.snapshot() is not implemented for local sandboxes or the Fleet creation paths. Fleet also rejects snapshot-derived image inputs. For these paths, prepare a reusable boot artifact instead. See Sandbox runtime support for the versioned limits and Prepare and reference a Fleet image for the published-artifact workflow.

Local execution#

Local mode runs on the developer's hardware. Linux containers use Docker Desktop, macOS VMs use Lume, and VM backends can use QEMU or Hyper-V. Local execution depends on the machine's available CPU, memory, disk, and virtualization support. Select it with local=True.

The sandbox still starts from an Image, exposes a code half and a GUI half, and can be ephemeral or persistent. See Build a local sandbox image for local setup.

Fleet execution#

Fleet runs sandboxes as managed capacity. A pool defines the boot artifact and capacity; a claim reserves a sandbox for a workload. Preparing the image and acquiring a running sandbox are separate operations, so the guest's dependencies and services must already be part of the published artifact.

Choosing local execution or Fleet changes the provisioning and connection path, not the idea of an isolated computer. It can also change which image inputs, customization methods, snapshots, and port connections are available. Use Sandbox runtime support for the versioned contract, or Your first Cloud Fleet for a guided hosted path.