Space kinds: container, VM, microVM

What a container, a VM and a microVM Space are, which computers run each, how Cua picks one, and how to ask for a kind in the CLI, the SDKs and the app.

Every Space is one of three kinds. The kind decides how the Space is kept apart from the computer it runs on, how fast it starts, and which images it runs.

The three kinds#

Any OCI image is a full Space on the container and microVM kinds: an image without cua-spacesd (alpine:3.20, node:20) gets a static one put in, so exec, files and ports work. A VM needs a Cua disk image. See Choose where sandboxes run.

Isolation, speed and compatibility#

Use a container for most Linux work: it starts fastest and runs on the most computers. Use a VM for Windows or macOS, or a full Linux desktop OS. Use a microVM to run any Linux image, such as untrusted code, behind its own kernel.

Which computers run which kind#

The microVM runtimes:

• vz: Cua's own monitor (cua-vz) on Apple's Virtualization framework, with checkpoints and forks. It ships next to cua in the Mac app and the installer. The guest kernel and its network helper download on first use.
• containerization: Apple's Containerization. Cua downloads Apple's container (signed by Apple) into ~/.cua on first use, or run cua runtime setup containerization. It has no checkpoints or forks. If another install of Apple's container runs its services, stop them with container system stop.
• firecracker: Firecracker on Linux. It needs /dev/kvm with read and write access. cua runtime setup firecracker downloads Firecracker, and the guest kernel downloads on first use.

cua runtime doctor has a row for each (firecracker, vz, containerization) that says whether it is ready and what is missing.

An egress policy is enforced on Firecracker microVMs. On vz and Containerization microVMs it is refused.

Your own cloud and your other computers#

• Another of your computers runs the kinds it reports to your account.
• AWS: a pool machine needs KVM for VM and microVM Spaces. Of the machine types Cua offers, only bare metal (c6g.metal) has it. A metal machine costs dollars an hour, so a single small request is refused unless you allow it with cua cloud budget --allow-metal on.
• Hetzner and Google Cloud: the machine types Cua offers have no KVM, so they run containers only.
• Modal: --on modal --kind microvm (or --runtime microvm) runs the sandbox on Modal's VM runtime. Linux images only.

cua cloud plan --kind microvm shows where microVM Spaces would go and which machines the pool would add for them. See Use your own cloud.

How the default is chosen#

With no kind given, the kind is auto and comes from the image:

• macOS and Windows images are VMs.
• An image with a container rootfs is a container.
• An image that only has a disk (a -disk containerDisk, a Lume image) is a VM.

auto never picks microvm. You ask for it.

The runtime is auto too: the first one that fits the image and the host. Containers use gVisor before runc. VMs use QEMU, and Lume for a macOS guest. MicroVMs use vz on a Mac when it is installed, else containerization, and firecracker on Linux.

To change your default, set default.kind (or CUA_DEFAULT_KIND for one shell or CI job). A default that does not fit an explicit request is skipped. See Change the default.

Some tools have their own default: cua build builds a VM, and cua compat serve makes VMs where this computer can accelerate them, else containers.

Pick a kind#

cua sb create linux --kind microvm --name fast          # runtime auto
cua sb create linux --kind microvm --runtime containerization --name fast2
cua run --kind microvm -- python job.py
cua config set default.kind microvm                     # your default

A kind or runtime the location does not offer fails with InvalidPlacement, and the message lists the valid values.

The E2B, Daytona and Modal SDKs take the kind as cua.kind in E2B metadata, Daytona labels and Modal experimental_options, and cua-e2b takes CUA_E2B_KIND.