Size a box and check capacity
You can choose any positive whole CPU count and whole GiB RAM size up to the host total. CPU and RAM are ceilings, not hardware reservations. Raft has no box-count cap; capacity estimates do not block creation. Own disks do require storage reservations.
Choose CPU and RAM
box=$(raft new --location lab --ttl 3600 --cpu 2 --memory 4GiB --disk shared --persistent --purpose "Project build" --owner "Local operator" --next "Stop after building")Without flags or controller defaults, image-based creation uses 1 CPU, 2 GiB RAM and shared storage. Snapshot copies and forks keep source sizes instead of controller size defaults. CPU or RAM requests above the whole host fail before changes; RAM comparison rounds host memory up to whole GiB.
For a stopped box, raft resume "$box" --ttl 1800 --cpu 2 --memory 8GiB replaces only supplied limits. Fork accepts the same CPU/RAM overrides. The CLI does not resize a running box or change a disk on resume or fork.
Own box disks
Shared boxes grow in the 60 GiB raft-data pool without per-box disk caps. A box's Docker data can fill that pool for every box. To enforce a cap, first enable own disks on the dedicated host, then create a box with --disk 40GiB.
For a fresh host, pass --disk-pool 100GiB to raft host add. For an existing deployment, run the matching release's deployer:
python3 deploy/deploy.py --location lab --disk-pool 100GiBA fresh host needs 80 GiB plus pool size free; adding the pool needs pool size plus 20 GiB. This reserves real host disk space. Redeployment does not resize pools; a different explicit size is refused. To change pool size, back up and remove affected boxes, explicitly remove the pool, then redeploy. Do not do this without an approved interruption and verified backups.
An own disk lives in raft-disks and caps all guest writes, including Docker. At the cap, writes fail with "No space left on device" instead of taking another box's space. The development image contains about 5 GiB of files; allow at least 8 GiB. Disks of 10 GiB or more avoid a shrink step and start faster. Filesystem overhead leaves usable space slightly below the requested size.
A host without raft-disks is healthy, but an own-disk request fails with enablement instructions. --disk shared can override a controller disk default for image-based creation. With --from, omit --disk to keep the snapshot disk or pass a size for an own disk; shared is rejected.
Fork, template and snapshot copies share unchanged blocks. A fork keeps disk size. To change it, snapshot a stopped persistent box and use new --from BOX/SNAPSHOT --disk SIZE. Own-disk backups recover to an own disk of the original size and require the target pool.
Reservation accounting
Each own disk and each snapshot reserves its full size even when blocks are shared. The cached image also reserves space. A request that would exceed pool capacity fails before allocating a volume.
| Operation | Additional reservation |
|---|---|
Image-based new --disk SIZE | Larger of SIZE and image volume; also the image volume if not cached |
| Own-disk snapshot copy, with optional size override | Larger of source and requested size |
Shared snapshot copied with --disk SIZE | SIZE |
| Own-disk fork or snapshot | Source disk size |
| Own-disk recovery | Disk size for the box and once per included snapshot |
| Restore | No added reservation |
Plan for the cached image's 10 GiB default plus all boxes and snapshots. The pool has slightly less data space than its configured size because of metadata. Destroying a box or deleting a snapshot frees its reservation; the cached image can remain reserved. capacity reports actual reservations, including operator-created volumes.
Read the estimate
raft capacity --location lab
raft capacity --location lab --json
raft usage "$box"capacity counts every non-Stopped box as active, subtracts active CPU/RAM limits, and leaves 1 CPU plus the larger of 2 GiB or 10% of host RAM for the host. Memory headroom also considers available RAM. These margins are advice, not enforced reservations. Example shapes double from 1 CPU / 2 GiB; other sizes are supported. Fit counts divide headroom by the requested CPU and RAM and take the smaller result.
| JSON field | Meaning |
|---|---|
location, note, notice | Host selection, guidance and advisory warning |
host | CPU count, total/available RAM, host disk free, sharedPool, boxDiskPool |
host.boxDiskPool | null if disabled; otherwise totalBytes, reservedBytes, usedBytes, metadataUsedPercent |
boxes, activeBoxes, allocated | Saved/active counts and active CPU/RAM limits |
reserve, headroom | Advisory host margin and remaining CPU/RAM |
estimates | Example sizes with fitEmptyHost and fitNow |
warnings | Overcommit, low memory/disk or high thin-pool metadata use |
Own-disk space available for reservations is totalBytes - reservedBytes; written usage is not the same. usedBytes and metadataUsedPercent can be null while no own-disk volume is active. Warnings begin below 5 GiB host/shared-pool free space or at 80% own-pool metadata use; metadata exhaustion can stop all own-disk boxes and require offline repair.
list reports disk as shared or a size. info exposes the root disk in expanded_devices.root. Running usage filesystem counters cover either the shared pool or one own disk, distinguished by filesystemScope; they are not per-box shared-storage accounting.