Skip to main content
Resume and fork both start a machine from the newest snapshot of a sandbox. To deploy many sandboxes from one fixed state, use a saved snapshot instead of forks.

Resume

A resume brings a stopped sandbox back on a new machine. The sandbox keeps its id and its disk.
$BOAT_API_BASE is https://boat.dev/api/v1.
  • Every stop makes the snapshot that a resume needs: boat stop, auto-stop, and a stop for an empty wallet. Only boat stop --force and snapshots off skip it.
  • boat keeps the snapshot of a stopped sandbox for at least 14 days. After that, automated retention cleanup can delete it once enabled. Resume and fork fail with 409 snapshot_data_expired once deletion completes. Save a saved snapshot before day 14 to keep the disk longer. Read Keep a stopped sandbox longer than 14 days.
  • A sandbox in error can also resume. It comes back from its newest snapshot. Read A sandbox is in error.
  • To change the size, stop the sandbox first. Then resume with --type. A resume of a running sandbox with a new --type fails.
  • You can resume on a smaller size. If the sandbox has more data than the smaller size can hold, boat refuses the resume and does not change the sandbox. Read Machines.
  • If you do not send ttlSeconds, the sandbox keeps its current lifetime.
  • To turn auto-stop off, send null (--no-auto-stop).
  • boat resume waits until the sandbox runs a command. Then it returns. To return at once, add --no-wait.
  • The IP address changes at every resume.
What works at ready, and what comes a few seconds later, is in Readiness and resume speed.

Fork

A fork copies a sandbox into a new sandbox. The source keeps running, and boat does not change it.
A fork of a running sandbox uses its last background snapshot. boat takes one each minute. Writes from the last minute or so can be missing from the fork.For an exact copy, save a saved snapshot first: boat snapshot <id> <name>. A save of a running sandbox takes a new snapshot at that moment. Then run boat new --from <name>. A fork of a stopped sandbox has everything, because the stop took the last snapshot.
What the fork gets from the source:
  • The whole disk, as it was at the newest snapshot.
  • The per-sandbox variables of the source. If you send your own env, the fork uses yours.
  • The exact environment version of the source. Read Environments.
What the fork does not get:
  • The lifetime of the source. A fork stops after 1 hour by default, even if the source has auto-stop turned off. To change this, send ttlSeconds or use --no-auto-stop.
  • A per-sandbox setup script (--setup-file) of the source. That script runs one time, on the sandbox that you created with it.
To make many copies at once, read Make many copies.

Restore an older snapshot (roll back)

Resume and fork always use the newest snapshot. You cannot resume or fork an older snapshot. There is no point-in-time restore. The snapshot list of a sandbox holds only recent snapshots. boat removes older ones, usually within a day. Read How long boat keeps data. To get files back from an older snapshot that is still in the list:
  1. Find the snapshot: boat snapshots <sandboxId>.
  2. Download its files: boat snapshot pull <snapshotId> -o ./old. Or download one path. Read Download a snapshot.
  3. Copy the files into the sandbox: boat scp.
To keep states that you can go back to, save a saved snapshot at each point. A saved snapshot has no scheduled expiry, but unpaid extras can be deleted. For example, save one each day from cron:
Then start a sandbox from any of them with boat new --from daily-2026-10-12. Your plan includes some saved snapshots at no cost. Read Saved snapshot pricing.

How fast a sandbox comes back

A resume, a fork or a deploy is ready in a few seconds, whatever the size of the disk. boat downloads your files in the background. What works at ready, how to wait for the rest, and how to make the first start faster are in Readiness and resume speed.

No machine free

A resume or a fork waits for a machine when none is free. To get an answer at once instead, read Fail fast when no machine is free.