Sandbox & provider
A sandbox is the machine-like environment an agent controls. A provider creates or attaches that sandbox, exposes one uniform control endpoint, and releases it after the run.
What a sandbox provides
Every sandbox exposes the operating-system paths, applications, shell, filesystem, and graphical desktop expected by the task. Most ALE runs use a complete Ubuntu or Windows virtual machine. The local-container profile reproduces the supported Ubuntu userspace inside Docker and shares the host kernel.
This distinction affects isolation and task compatibility, but not the agent interface. Agents receive the same CLI and GUI tools across providers.
What a provider owns
The framework calls acquire() with the task's snapshot and
resource shape. The provider returns a SandboxHandle with a
live CUA endpoint and image path conventions. After evaluation,
release() applies the requested cleanup mode.
Provider implementations
| Code identifier | Sandbox realization | Lifecycle |
|---|---|---|
gcloud | A complete GCE VM | Creates a fresh VM per unit and manages it through the Google Cloud CLI. |
aws | A complete EC2 instance | Creates a fresh instance per unit and manages it through the AWS CLI. |
aliyun | A complete Alibaba Cloud ECS instance | Creates a fresh instance per unit and manages it through the Alibaba Cloud CLI. |
docker | A Linux container with a virtual desktop | Creates a fresh container per unit and exposes the CUA port through Docker. |
qemu | A complete QEMU/KVM guest inside a Docker-packaged runner | Caches a base qcow2, creates a disposable overlay, and starts one guest per unit. |
static | An existing CUA-enabled machine | Attaches to a fixed endpoint. It does not provision or destroy the machine. |
Snapshot routing
Tasks request logical snapshots such as cpu-free-ubuntu or
gpu-free. An environment profile maps each snapshot to a
provider and image. Routing is per snapshot, so one environment can mix
provider kinds, although the shipped profiles use one primary provider
family each.
Resource hints come from the task card. Google Cloud uses its machine type directly, Docker translates it into container limits, and QEMU translates it into guest vCPU and memory values.
How ALE reaches the sandbox
Each managed image runs the open-source
Cua
computer-server. It exposes shell, filesystem, and GUI
operations over the same HTTP API on Windows and Linux.
SandboxHandle and cua-bench's remote desktop session are
clients of that endpoint.
Providers can use optimized host-side transports for bulk artifacts.
Docker uses docker cp; the QEMU provider uses a guest share.
These transports do not change the agent's control surface.
Published sandbox assets
ALE maintains the ale-ubuntu22 and ale-win10
environments with professional applications, CUA tooling, agent runtimes,
and task data. Google Cloud publishes machine images, while the local VM
provider uses qcow2 disks from
Hugging
Face. The local-container provider uses a separate data-less Docker
export of the Ubuntu userspace.