Set Up a Sandbox

Create and manage cloud sandboxes that run Linux (Ubuntu), Windows, or macOS.

First, create your API key:

1. Go to cua.ai/signin
2. Navigate to Dashboard > API Keys > New API Key to create your API key
3. Important: Copy and save your API key immediately - you won't be able to see it again (you'll need to regenerate if lost)

Then, create your sandbox using either option:

Option 1: Via Website

1. Navigate to Dashboard > Sandboxes > Create Sandbox
2. Create a sandbox, choosing Linux, Windows, or macOS

3. Note your sandbox name

Option 2: Via CLI

1. Install the Cua CLI:

# macOS/Linux
curl -LsSf https://cua.ai/cli/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://cua.ai/cli/install.ps1 | iex"

2. Login and create a sandbox:

cua auth login
cua sb create --os linux --size small --region north-america

3. Note your sandbox name and password from the output

Your Cloud Sandbox will be automatically configured and ready to use.

Run Linux desktop locally on macOS, Windows, or Linux hosts.

1. Install Docker Desktop or Docker Engine

2. Pull a Cua Docker image:

# XFCE (Lightweight) - recommended for most use cases
docker pull --platform=linux/amd64 trycua/cua-xfce:latest

# OR KASM (Full-Featured) - full Ubuntu desktop
docker pull --platform=linux/amd64 trycua/cua-ubuntu:latest

Run full Linux (Ubuntu Desktop), Windows 11, or Android 11 VMs inside Docker containers using QEMU virtualization.

docker pull trycua/cua-qemu-linux:latest

docker run -it --rm \
    --device=/dev/kvm \
    --cap-add NET_ADMIN \
    --mount type=bind,source=/path/to/ubuntu-22.04.5-live-server-amd64.iso,target=/custom.iso \
    -v ~/cua-storage/linux:/storage \
    -p 8006:8006 \
    -p 5000:5000 \
    -e RAM_SIZE=8G \
    -e CPU_CORES=4 \
    -e DISK_SIZE=64G \
    trycua/cua-qemu-linux:latest

docker pull trycua/cua-qemu-windows:latest

docker run -it --rm \
    --device=/dev/kvm \
    --cap-add NET_ADMIN \
    --mount type=bind,source=/path/to/windows-11-enterprise-eval.iso,target=/custom.iso \
    -v ~/cua-storage/windows:/storage \
    -p 8006:8006 \
    -p 5000:5000 \
    -e RAM_SIZE=8G \
    -e CPU_CORES=4 \
    -e DISK_SIZE=64G \
    trycua/cua-qemu-windows:latest

docker pull trycua/cua-qemu-android:latest

macOS hosts only - requires Lume CLI.

1. Install the Lume CLI:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"

2. Start a local Cua sandbox:

lume run macos-sequoia-cua:latest

Windows hosts only - requires Windows 10 Pro/Enterprise or Windows 11.

1. Enable Windows Sandbox
2. Install the pywinsandbox dependency:

pip install -U git+git://github.com/karkason/pywinsandbox.git

3. Windows Sandbox will be automatically configured when you run the CLI