code-yeongyu Local Cua sandbox
In mode: "local" (the default), cua_sandbox_start spins up a sandbox on
your machine. Cua picks the runtime from the image OS unless you pass
runtime explicitly.
Runtime selection
| OS image | Auto runtime | When kind: "container" |
Override |
|---|---|---|---|
linux |
Docker (XFCE) | XFCE Docker (trycua/cua-xfce) |
qemu, docker |
macos |
Lume (Apple Silicon required) | - | tart |
windows |
QEMU Docker | - | - |
android |
Android Emulator | - | - |
kind defaults to "container" for Linux (fast, GUI via XFCE) and "vm"
for everything else.
Prerequisites
- Docker Desktop or Colima for Linux containers / Windows VMs
- macOS Apple Silicon for
Image.macos()via Lume qemuinstalled locally forruntime: "qemu"
Cua will print actionable errors when prerequisites are missing.
Example calls
// Fast Linux XFCE container - recommended for most automation
cua_sandbox_start({ os: "linux", kind: "container" })
// Full Ubuntu VM via QEMU
cua_sandbox_start({ os: "linux", kind: "vm", runtime: "qemu" })
// macOS guest via Lume (Apple Silicon host only)
cua_sandbox_start({ os: "macos", kind: "vm", runtime: "lume" })
Performance notes
- XFCE containers are fastest (seconds to start).
- QEMU VMs take ~30s for Linux, several minutes for Windows.
- macOS Lume VMs need a one-time
lume pullfor the image.
After start
The returned sandbox name is also used as name for cua_sandbox_stop and
the sandbox argument of control tools. If you only use one sandbox you can
omit the sandbox argument; the manager remembers the first sandbox as
default.