Hardware

What a sandbox host needs, how to check a machine, and how the installer uses its disks.

A sandbox host needs an x86_64 CPU with hardware virtualization exposed as /dev/kvm. The control plane needs none of this: it runs in Docker on any linux/amd64 machine.

Check the requirements

	Requirement
CPU	x86_64 with Intel VT-x or AMD-V, exposed as `/dev/kvm`
OS	Ubuntu 24.04. The installer needs `apt`.
Where	Bare metal. Nested virtualization is for evaluation only.
Network	`10.42.0.0/16` unused on your network: sandboxes live on the `pt-br0` bridge there.
Access	An out-of-band console is wise: the installer changes boot parameters and reboots.

Containers, macOS and WSL2 cannot run sandbox hosts.

Check a machine before installing

Run these on the candidate host.

grep -cwE 'vmx|svm' /proc/cpuinfo   # any number above 0
ls -l /dev/kvm                      # the device exists
nproc; free -g; df -h /

A 0 from the first line means the CPU lacks virtualization, it is off in firmware, or a VM hides it. On bare metal, turn on VT-x or AMD SVM in the firmware and reboot. The installer exits when /dev/kvm is missing.

Know what the installer changes

Change	Effect
Boot parameters	SMT off (`nosmt`), `lockdown=integrity`, IOMMU on. Count physical cores, not threads.
Huge pages	Reserves 8 GB of RAM as 2 MB pages.
Data directory	`/var/platinum/data` on XFS with `reflink=1`.
Firewall	An nftables ruleset in `/etc/nftables.conf`. See Hardening.
Reboot	Once, at the end, to apply the boot parameters.

Plan the disk layout

Sandbox and template disks live at /var/platinum/data, which must be XFS with reflink=1. The installer picks a layout in this order.

A volume labelled pt-data. Used directly, formatted XFS.
Free NVMe partitions. With no pt-data volume, the installer builds one as RAID0 from every NVMe partition over 100 GiB that is unmounted and not in an md array.
A loop file. Otherwise it loop-mounts an XFS image file on the root filesystem. This works on an ext4 root too.

For the best I/O, install the OS on a small partition and leave the rest of each drive free.

Plan capacity

Rule	Default	Setting
vCPUs offered per CPU thread the host reports	5	`PT_CPU_OVERCOMMIT` in the host's `/etc/platinum/host.env`; `1` turns it off
New sandboxes while allocated RAM stays under this share of the host's	0.8	`overcommit.ram_alloc_ratio`
No new sandboxes above this measured CPU use	85%	`overcommit.host_cpu_refuse_pct`
No new sandboxes above this measured memory use	90%	`overcommit.host_ram_refuse_pct`

RAM usually decides how many sandboxes fit. The overcommit.* keys are runtime settings: see Configuration.

Buy identical machines

Moving a sandbox between hosts needs a compatible CPU and the same guest kernel. A fleet of identical machines keeps every host a valid target.