raft / docs

Verify your setup

Use raft doctor --location lab for a read-only host check, then create a box and run a command. For test evidence or deeper checks, use the suites below from a source checkout matching your CLI.

Choose an isolated test host

Live suites create and destroy boxes, run guest processes, transfer files and may change host policies. Use dedicated disposable test infrastructure, not a daily development host. You need configured SSH, pinned native images and enough scratch space for archives. Recovery requires matching source and target CPU architecture.

The feature suite requires an empty Raft host, sets and clears note and retention policies, and tests timer-driven deletion. Recovery tests also set and clear target note policies. Own-disk live checks need an enabled pool with at least 42 GiB unreserved. Backups can delay host expiry checks while exporting.

Run the check you need

Replace lab and second-host with your isolated locations. These commands change the selected test hosts:

GoalCommand
Exercise lifecycle, tools, Docker, files, jobs, tunnels and isolationpython3 deploy/verify-live.py --location lab --extended
Check templates, recursive transfers, notes, retention and cleanuppython3 deploy/verify-features.py --location lab
Check capacity transitions and own diskspython3 deploy/verify-limits.py --location lab
Check disposable CI jobs and artifact cleanuppython3 deploy/verify-run.py --location lab
Check same-host backup/recoverypython3 deploy/verify-controls.py --source lab --target lab
Check cross-host full-image recoverypython3 deploy/verify-controls.py --source lab --target second-host --development-image

Recovery uses controller temporary storage by default; pass --directory PATH for a directory with enough archive space. python3 deploy/verify-tools.py "$box" runs development-tool checks in an existing running test box as developer.

Do not use --restart-incus unless daemon interruption is approved on a disposable host. --reboot-host requires a disposable host and a separate controller. These options belong to verify-live.py and affect the whole host, not only test boxes.

For host-independent checks, omit --location from verify-features.py, verify-limits.py and verify-run.py. python3 deploy/verify-image-tests.py checks archive safety; python3 deploy/verify-self-update.py tests temporary npm/uv installations. Local worker and orchestration fixtures do not establish native-host behavior.

python3 deploy/verify-plugins.py exercises executable plugin registration, capability failures, opaque handles, commands, files and removal through real CLI processes with a temporary HOME and provider state. It contacts no hosts. The optional examples/sandbox-sdk/ smoke exercises the published SDK and a disposable filesystem provider, not cloud accounts. These checks do not certify a third-party provider's isolation, billing or expiry guarantees.

Read the evidence and its limits

Native ARM64 and AMD64 validation exercises lifecycle, workspace controls, tool checks, backup/recovery and startup measurements. Fresh-host validation covers deployment and reboot on a disposable AMD64 Ubuntu 24 KVM host. See measured startup results for samples and methodology.

The suites check file rollback, copied network identity, retained output, binary and recursive transfers, Docker execution, private HTTP and desktop input, and network separation. Own-disk checks cover capped guest/Docker writes and reservations; shared-pool boxes have no per-box quota. Tests verify Raft behavior, not conformance with the hosted Boat service.

Desktop checks open Voxl through the default tunnel and require decoded 1280×720 video frames in the guest's packaged Chromium. They also select noVNC explicitly and exercise its framebuffer, keyboard, clipboard and reconnect behavior. The linked native runs above predate Voxl and do not establish Voxl frame rate or latency. A controller browser without H.264 WebCodecs support needs the explicit noVNC backend.

Desktop browser checks wait for the application page to load before checking window bounds and opening the viewer. An advertised debugging target alone does not establish page readiness.

These results do not certify arbitrary long-running workloads, host loss, multi-tenant security, cross-architecture recovery, ARM64 host reboot or physical storage capacity. VM tests with sparse virtual disks do not prove real free-disk capacity. Boxes share the host kernel, and Raft has not had a security audit.

For release gates and implementation details, see publishing and the runtime contract.

On this page