Set up local runtimes

Local sandboxes run on this machine with no account. Local is the built-in default: omit on= (local= in cua-sandbox, --on in the CLI), or change the default. The SDK picks the kind and runtime from the image and starts it itself.

Check and set up the host#

cua runtime doctor              # what this host can run (read-only)
cua runtime setup --dry-run     # the install plan
cua runtime setup               # install what is missing; or name qemu, lume, container

cua doctor checks the host, an image and a sandbox's guest in one report.

Pick a kind or runtime#

cua sb create linux --name dev                       # a gVisor container
cua sb create linux --kind vm --name dev-vm          # its -disk variant under QEMU
cua sb create linux --runtime runc --name dev-runc   # a container without gVisor
cua sb create macos:tahoe --name mac                 # a Lume VM
cua sb rm dev

--runtime takes auto, gvisor or runc for containers and qemu or lume for VMs; a runtime implies its kind. A combination that does not exist fails with InvalidPlacement and lists the valid values:

invalid placement: runtime qemu runs vm sandboxes, not container ones locally; valid runtime: auto, gvisor, runc

pool:<name> runs a cloud pool's template image locally (it needs cloud credentials to read the template):

cua sb create pool:my-pool --name copy-of-my-pool

In code, pass kind= and runtime= (Sandbox.create(image, kind="vm", runtime="qemu")); cua-sandbox still accepts a Runtime object (runtime support).

What differs locally#

• The host's architecture; others run emulated and slowly.
• Services and public URLs are served on loopback (public URLs by the cua daemon, which the SDK starts).
• Sidecars need runtime="runc" where gVisor would run.
• Image layers build into your container engine before boot; VM images apply them after boot through cua-spacesd.
• A sandbox runs until you delete it; keep_alive and cloud= raise.
• Images without cua-spacesd fall back to the runtime's agentless path (QMP, VNC, SSH or ADB) where there is one.

Disk usage and cleanup#

Images share a cache budget and are evicted least recently used first; a pull that would leave under 5 GiB free fails with InsufficientDisk. cua cache du shows what images and sandboxes take. See Disk usage and cleanup.