Cloud vs Local Sandbox Execution in Cua: Key Differences and When to Use Each

Cua provides two sandbox execution modes—cloud and local—that share the same high-level API but provision completely different underlying infrastructure, with cloud running remote VMs via the CloudProvider and local executing on your machine via the cua-sandbox runtime.

The trycua/cua repository offers a unified interface for running isolated computer environments, but choosing between cloud and local execution modes significantly impacts latency, resource availability, and persistence. While both modes expose identical APIs through Sandbox.ephemeral and the cua sb CLI, they diverge at the provider level to serve different development workflows.

Architecture and Provisioning Differences

The fundamental distinction lies in where the virtual machine actually runs. Cua abstracts this through the provider pattern implemented in libs/python/cua-sandbox/cua_sandbox/sandbox.py.

Cloud Sandbox Implementation

Cloud sandboxes provision remote infrastructure through the CloudProvider class located in libs/python/computer/computer/providers/cloud/provider.py. This implementation communicates with the CUA API using your CUA_API_KEY to start, stop, and destroy VMs on Cua's managed infrastructure.

The provider handles endpoint exposure through methods like _get_vnc_host and _get_ip, exposing VNC and web-socket endpoints over the internet. This architecture supports cross-platform testing across Linux, Windows, and macOS regardless of your local development machine.

Local Sandbox Implementation

Local sandboxes execute directly on your developer machine using the cua-sandbox runtime. As implemented in libs/python/cua-sandbox/cua_sandbox/localhost.py, this mode leverages native virtualization: Lume VMs on macOS via the Hypervisor framework, or QEMU containers on Linux and Windows.

Unlike the cloud provider, the local implementation requires no API keys and creates direct sockets on localhost for VNC access.

Performance and Resource Characteristics

Latency and isolation guarantees differ substantially between execution modes:

• Cloud sandbox: Network round-trips typically measure approximately 100ms due to internet traversal. However, cloud VMs offer hardware isolation from your host and access to scalable CPU, RAM, GPU, and persistent storage that can exceed laptop capabilities.
• Local sandbox: Delivers sub-millisecond latency through direct localhost sockets. Resource constraints mirror your local hardware limits, and isolation depends on the host OS virtualization layer rather than physical separation.

Persistence and Storage Models

Persistence behavior varies by execution mode:

• Cloud: Images and snapshots live in the cloud registry (accessed via cua image push/pull). Sandboxes can survive process restarts and maintain state across sessions.
• Local: By default, sandboxes are ephemeral—when the Python process exits, the local VM tears down automatically. You can create named persistent local sandboxes using cua sb start <name>, but they remain bound to the local host.

How the Execution Mode Flag Works

The local boolean parameter in Sandbox.ephemeral determines provider selection through a simple conditional in libs/python/cua-sandbox/cua_sandbox/sandbox.py:

if local:
    provider = LocalProvider()   # runs on the host

else:
    provider = CloudProvider()   # talks to the CUA cloud API

Both providers implement the abstract BaseVMProvider interface, ensuring that sandbox operations—screen capture, mouse/keyboard actions, and VNC streaming—remain identical regardless of VM location.

Practical Usage Examples

Python API Examples

Create a cloud sandbox by setting local=False:

from cua import Image, Sandbox

# Pull a cloud image from the cloud registry

image = await Image.get("cua-ai/ubuntu-22.04")

# Create an ephemeral cloud sandbox

async with Sandbox.ephemeral(image, local=False) as sb:
    await sb.computer.click(x=200, y=150)
    screenshot = await sb.computer.screenshot()

Create a local sandbox by setting local=True:

from cua import Image, Sandbox

# Use the same image locally

image = await Image.get("cua-ai/ubuntu-22.04")

# Create an ephemeral local sandbox

async with Sandbox.ephemeral(image, local=True) as sb:
    await sb.computer.type(text="Hello, local sandbox!")
    await sb.computer.screenshot()

CLI Examples

Cloud sandboxes require explicit provider selection:

# Create and manage a cloud sandbox

cua sb create my-cloud --provider cloud
cua sb start my-cloud
cua sb vnc my-cloud

Local sandboxes use the default provider:

# Create and access a local sandbox

cua sb create my-local
cua sb vnc my-local

Summary

• Cloud sandboxes run on remote infrastructure via CloudProvider in libs/python/computer/computer/providers/cloud/provider.py, offering scalable resources and cross-platform testing at ~100ms latency.
• Local sandboxes execute via LocalProvider using Lume VMs or QEMU on your machine, providing sub-millisecond latency for rapid prototyping and offline development.
• Both modes share the same Sandbox.ephemeral API and BaseVMProvider interface, switching behavior through the local boolean flag.
• Cloud mode persists state in the remote registry; local mode defaults to ephemeral instances unless explicitly named with cua sb start.

Frequently Asked Questions

When should I use cloud sandbox vs local sandbox?

Use cloud sandbox for production workloads, CI pipelines, cross-platform testing (running Windows on a Mac, for example), or when you need GPU resources exceeding local hardware. Use local sandbox for rapid iteration during development, debugging automation scripts, or working in environments with restricted internet access.

Can I switch between cloud and local execution without changing my code?

Yes. The Sandbox class abstracts provider differences through the BaseVMProvider interface. Changing local=False to local=True (or using the --provider CLI flag) switches execution modes while keeping your automation logic identical. The test suite in tests/test_interfaces.py validates this API compatibility across both modes.

What are the hardware requirements for local sandbox mode?

Local sandbox requires hardware virtualization support: macOS users need the Hypervisor framework (Lume VMs), while Linux and Windows users need QEMU support. Your machine must have sufficient RAM and CPU to run the guest OS alongside your development environment, unlike cloud mode which offloads resource consumption to remote infrastructure.

How does image storage differ between cloud and local modes?

Cloud sandboxes store images in Cua's remote registry, accessible via cua image push and cua image pull, enabling persistence across sessions and machines. Local sandboxes cache images on your local filesystem and default to ephemeral storage that destroys the VM when the Python process exits, though named local sandboxes can persist until explicitly stopped.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}