Performance

See Under the Hood: Performance for the specific QEMU flags behind each optimization.

Boot time

Measured with quicksand benchmark -n 5 on macOS ARM64 (Apple M3 Max, HVF):

Image	Boot p50	Boot p95
alpine	0.37s	0.45s
ubuntu	0.88s	0.91s
alpine-desktop	0.47s	0.54s
ubuntu-desktop	0.90s	0.96s
quicksand-agent	0.91s	0.92s
quicksand-cua	0.85s	1.01s

Boot time is measured from start() to sandbox ready (agent connected, mounts configured). The biggest factor is hardware acceleration (TCG is 10-50x slower).

CPU performance

With hardware acceleration (KVM, HVF, WHPX), the guest runs at near-native speed. Code compiles, tests run, and browsers load at essentially the same speed as the host.

Without hardware acceleration (TCG), everything is 10-50x slower. TCG is a fallback for environments that don't support virtualization, such as CI containers and nested VMs without passthrough. If your workload is CPU-intensive, hardware acceleration is essential.

Quicksand auto-detects the best accelerator for the current platform. You can check what's in use:

async with Sandbox(image="ubuntu") as sb:
    print(sb.accelerator)  # Accelerator.KVM, HVF, WHPX, or TCG

Disk I/O

Quicksand uses several optimizations for disk performance:

• IOThreads. Disk I/O runs on a dedicated thread, not QEMU's main loop.
• io_uring (Linux only). Modern async I/O kernel API, with ~50% lower latency.
• virtio-blk. Paravirtualized disk device, much faster than emulated SATA.
• qcow2 overlays. Thin files that only store changes, so sandbox creation is instant.

Snapshot performance

Operation	Typical time
checkpoint()	~1-2 seconds (saves RAM + disk state)
revert()	~1-2 seconds (restores RAM + disk state)
save()	~1-5 seconds (copies overlay chain to disk)
save(compress=True)	~10-30 seconds (compresses overlays)

checkpoint() and revert() use QEMU's built-in snapshot mechanism. save() freezes the current overlay and copies it. The VM never pauses.

Memory

Each sandbox uses as much host RAM as configured:

Sandbox(image="ubuntu", memory="512M")  # 512MB of host RAM
Sandbox(image="ubuntu", memory="2G")    # 2GB of host RAM

Plus ~50-100MB of overhead for the QEMU process itself. Multiple sandboxes run concurrently but each gets its own RAM allocation.

Platform comparison

	Linux + KVM	macOS + HVF	Windows + WHPX	Any + TCG
Boot (Alpine)	< 0.5s	0.37s	~1-2s	~10-30s
Boot (Ubuntu)	< 1s	0.88s	~2-3s	~10-30s
CPU performance	Near-native	Near-native	Near-native	10-50x slower
Disk AIO	io_uring	threads	threads	threads
Machine type	Q35/VIRT	Q35/VIRT	Q35	Q35/VIRT

Tips

• Use the smallest image that works. Alpine (~75MB) boots faster than Ubuntu (~340MB).
• Use save() to avoid repeated setup. Install packages once, save, and resume from the save.
• Avoid TCG for CPU-heavy workloads. If you're in CI, ensure KVM is available (/dev/kvm).
• Use disk_size sparingly. Expanding the disk adds time to boot.
• Concurrent sandboxes share base images. Running 10 Ubuntu sandboxes doesn't use 10x the disk space, because overlays only store changes.