Requirements

qbox boots a real VM per sandbox with Firecracker, which needs hardware virtualization exposed to the operating system as /dev/kvm. This is the single most important requirement — on a plain cloud VM without nested virtualization, /dev/kvm doesn’t exist and nothing will spawn.

You need one of

• A bare-metal server — anything with VT-x/AMD-V (Hetzner, OVH, Equinix Metal, your own hardware). Always works.
• A cloud instance with nested virtualization — a VM that exposes /dev/kvm to the guest OS.

Known-good cloud instances

Provider	What to pick
DigitalOcean	Standard Droplets expose /dev/kvm — this is the easiest start.
AWS	.metal instances (e.g. c5.metal, m5.metal, i3.metal). Regular Nitro instances (t3/m5/c5 non-metal) do not expose nested virt.
GCP	Instances with nested virtualization enabled (Intel Haswell+; set --enable-nested-virtualization).
Azure	v3+ sizes that advertise nested virtualization (e.g. Dv3/Ev3 and newer).

Rule of thumb: if it’s a shared/standard cloud VM and the provider doesn’t mention nested virtualization or bare metal, assume /dev/kvm is not available. CPU virtualization flags alone (vmx/svm in /proc/cpuinfo) are not enough — the hypervisor must pass KVM through to your instance.

Check a candidate host

# 1. KVM must be exposed to this host:
ls -l /dev/kvm                       # must exist

# 2. CPU virtualization flags present:
egrep -c '(vmx|svm)' /proc/cpuinfo   # > 0

# 3. (optional) the cpu-checker package gives a clear verdict:
sudo apt-get install -y cpu-checker && sudo kvm-ok

If /dev/kvm is missing, pick a bare-metal or nested-virt instance from the table above — you can’t run qbox here otherwise.

Operating system

• Linux, x86_64 (amd64). arm64 isn’t supported yet.
• The TUN/TAP kernel module (tun) for per-VM tap devices — the installer loads it (modprobe tun) and persists it across reboots.
• Docker with the Compose plugin — the installer installs it if it’s missing.

Sizing

qbox itself is light; size the host for the sandboxes you’ll run concurrently.

Resource	Minimum	Notes
vCPU	2	Plus headroom for the sandboxes you run in parallel.
RAM	4 GB	Plus the sum of your sandboxes’ memory.
Disk	20 GB	Template snapshots, the rootfs cache, and per-VM dirs. Grows with templates.

Disk / filesystem

Point QBOX_DATA_DIR at a disk with room to grow. For best performance use a reflink-capable filesystem — xfs (created with reflink=1) or btrfs — so the host agent clones rootfs images with instant copy-on-write. It falls back to a plain copy on ext4 (the default on most droplets), which still works, just slower on spawn.

Storage requirements

Each template stores three artifacts in object storage, and the host caches them locally on first spawn:

• rootfs — the image’s filesystem plus 512 MB writable free space for the sandbox to write files (configurable via QBOX_BUILDER_ROOTFS_FREE_MB).
• memory snapshot — roughly the template’s configured guest RAM (e.g. a 512 MB template ≈ a 512 MB snapshot). This is usually the largest piece.
• kernel — shared across all templates (stored once).

So budget, per template, roughly (image size + 512 MB) + (guest RAM) in both object storage and the host cache. Each running sandbox adds only its copy-on-write writes (up to the free space) on a reflink filesystem — a full copy otherwise. Terminated-sandbox rows and their data are reaped after the retention window; the artifact cache is bounded by QBOX_CACHE_SIZE_BYTES (LRU-evicted).

Where a sandbox writes

A running sandbox has two writable areas:

• / (the rootfs) — disk-backed; persists for the sandbox’s life. The image content plus the build-time free space (QBOX_BUILDER_ROOTFS_FREE_MB, default 512 MB). Use this for large or lasting files.
• /tmp — RAM-backed tmpfs, sized to 50% of the guest’s RAM (capped at 512 MB). Fast scratch, lost on stop, and it counts against guest memory — so on a small-RAM template /tmp is correspondingly small.

Network

• Outbound internet to pull container images and the qbox assets.
• For automatic HTTPS, point your domain’s A/AAAA record at the host’s public IP before installing, with ports 80 and 443 reachable — Let’s Encrypt can’t issue a certificate until the domain resolves to this host. On a bare IP, qbox serves a self-signed certificate instead.

Ready? Continue to Self-hosting.