raft / docs
Guides

Save or copy disk state

You can save a box's filesystem or copy it on the same host. Set $box to your task's persistent box from raft list. Inspect raft info "$box" before stopping it: stopping a disposable box deletes it and its snapshots.

Snapshots, restores and forks require a stopped source. Stopping ends every process; no operation saves process memory. Copies include packages, credentials and enabled services. Remove secrets you do not want inherited.

Save a snapshot

raft stop "$box"
raft snapshot "$box" pre-upgrade
raft snapshots "$box"

Snapshot names start with an ASCII letter or digit, followed by letters, digits, _ or -, up to 64 characters. A snapshot stays with its box and disappears when the box is destroyed or deleted by retention. It is not an off-host backup.

Roll back files

Restoring discards filesystem changes made since the snapshot. Back up any needed changes first. With your box stopped:

raft restore "$box" pre-upgrade
raft resume "$box" --ttl 1800

Restore keeps the box's instance configuration, resource limits and MAC address. It rolls back files, not external effects such as a remote database change.

Fork a stopped box

A fork copies the stopped box's present filesystem without its snapshots, then starts an independent box:

copy=$(raft fork "$box" --ttl 1800 --purpose "Project experiment" --owner "Local operator" --next "Destroy after comparison")

The source remains stopped. Omitted CPU and RAM limits inherit from it; --cpu and --memory override them. The disk type and size stay unchanged. A fork is persistent regardless of controller defaults unless you pass --disposable. Without note flags, it inherits the source note; note flags replace the entire note and must satisfy host policy.

Start from a snapshot

copy=$(raft new --from "$box/pre-upgrade" --ttl 1800 --persistent --purpose "Prepared project" --owner "Local operator" --next "Destroy after use")

The source box may be running because you copy a saved snapshot. The copy stays on its source host, with a fresh handle, MAC address and deadline. It keeps the snapshot's CPU, RAM and disk unless flags override them. Controller size defaults do not apply, but the disposable default does; --persistent overrides it. Unlike fork, new --from does not inherit the source note.

On a host with own disks enabled, add --disk 40GiB to create a copy with another disk size. You cannot use --disk shared with --from, or resize a disk on resume or fork. For another host, use backup and recovery.

Copies share unchanged disk blocks. Each own-disk box and snapshot still reserves its full size, and insufficient reservation space rejects creation. See disk reservations.

Delete a snapshot or copy

These actions permanently delete the selected data. Download or back up anything needed first:

raft snapshot-delete "$box" pre-upgrade
raft destroy "$copy"

Snapshot deletion can run while the box runs. Deleting a source snapshot does not delete copies already created from it.

On this page