Install Raft and set up a host
You can create boxes after onboarding one dedicated Ubuntu host. First check the machine requirements. Run these commands on your Linux controller, not inside a box.
Install the CLI
With Python 3.11.8+ and npm available:
npm install -g @microck/raft
raft --versionInstallation does not change hosts or download images. raft host add uses the release image matching your installed CLI version by default.
Verify host access
Replace ubuntu@192.0.2.10 with your dedicated host's SSH target or an alias from ~/.ssh/config. Check the host key fingerprint against a trusted source before accepting it:
ssh ubuntu@192.0.2.10 true
ssh -o BatchMode=yes ubuntu@192.0.2.10 'sudo -n true'Resolve authentication or sudo errors before continuing. Do not disable host-key checking.
Review and apply the plan
Deployment changes host storage, firewall rules and system services. Do not target a shared machine or a host with unrelated Incus resources.
raft host add lab --ssh ubuntu@192.0.2.10 --dry-run
raft host add lab --ssh ubuntu@192.0.2.10The first command checks prerequisites and prints a plan without changing the host. The second asks for confirmation, installs Incus and Raft services, imports a checksum-verified native image, and registers lab in ~/.config/raft/incus.json with its immutable fingerprint. It finishes with diagnostics and a disposable create/exec/destroy test.
The host gets a 60 GiB shared storage pool and a private NAT network. Boxes cannot contact peers on the bridge. No guest SSH port or public Incus listener is required.
To cap disk use per box, add --disk-pool 100GiB to both onboarding commands. This sets aside an additional 100 GiB on the host; individual boxes opt in with --disk SIZE. Without it, boxes share the pool without per-box disk caps. See disk sizing.
For unattended onboarding, review the dry run and then pass --yes. Other image sources are optional: --image-release TAG selects a release, --image-archive PATH imports a trusted local archive, and --build builds on the host. Choose only one. See host add.
Confirm the host is ready
raft locations
raft doctor --location labIf onboarding fails before registration, host changes may remain. If the final diagnostics fail, Raft removes the location from controller inventory but leaves host changes in place. Fix the reported cause, then rerun onboarding; it reuses the deployment. An already registered location is rejected, so use doctor to inspect it instead.
For a missing release asset, failed checksum or unsupported architecture, do not bypass verification. Use a matching release or build a native image. For SSH and storage errors, see troubleshooting.
Continue with your first box. For host redeployment or an image change, use the upgrade guide.