Check your machines
You need a controller to run the CLI and a dedicated host to run your boxes. You do not need a cloud account or a public Incus endpoint.
Prepare your controller
Use Linux with Python 3.11.8 or later, OpenSSH and npm for the recommended installation. Install Git for Git-filtered uploads and rsync for incremental sync. Your controller must reach the host over SSH without password prompts.
A Python wheel installed with uv can run the CLI, but host onboarding needs deployment files from the npm package or a source checkout.
Choose a dedicated host
| Requirement | Minimum |
|---|---|
| OS | Ubuntu 22.04 or 24.04 |
| Architecture | ARM64 or AMD64; guest binaries match the host |
| CPU and RAM | 2 CPUs and 8 GiB RAM |
| Free disk | 80 GiB for a fresh deployment |
| Access | Key-based SSH, Python 3 and passwordless sudo; sudo -n true must succeed |
| Network | Inbound SSH from your controller; outbound access for packages and images |
Do not deploy on a machine with unrelated Incus pools or virtualization workloads. Deployment changes storage, firewall rules and system services. An Ubuntu VM is supported; a macOS host is not.
The shared storage pool is 60 GiB. Optional own box disks require an additional pool: --disk-pool 100GiB needs 180 GiB free on a fresh host, or 120 GiB when adding it to an existing deployment. Pools do not resize on redeployment.
Understand the limits
Boxes share the host kernel. Guest root is not host root, but your controller's SSH identity has host sudo. Give that identity only to trusted operators and jobs. Raft has not had a security audit.
CPU and RAM limits cap individual boxes, not reserve hardware. raft capacity leaves an advisory margin of 1 CPU and the larger of 2 GiB or 10% of RAM. Raft has no box-count cap, but oversized requests and insufficient own-disk reservations fail.
Continue with host setup, which checks host prerequisites before changing anything.