Resume and fork

Resume and fork both start a machine from the latest snapshot of a sandbox.

	Resume	Fork
You get	The same sandbox, with the same id	A new sandbox, with a new id
The source sandbox	Is the sandbox	Keeps running. Boat does not change it
Use it to	Continue your work after a stop	Try something risky, start a second branch of work, give one sandbox to each of your users

If you fork the same sandbox again and again, make it a template instead.

Resume

A resume brings a stopped sandbox back on a new machine. The sandbox keeps its id and its disk.

boat resume bx_f7k2q9hd
boat resume bx_f7k2q9hd --type large      # different machine size
boat resume bx_f7k2q9hd --ttl 7200        # new lifetime, in seconds
boat resume bx_f7k2q9hd --no-auto-stop    # runs until you stop it

curl -sS -X POST "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/resume" \
  -H "Authorization: Bearer $BOAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"large","ttlSeconds":7200}'

await sandbox.resume({
  sandboxId: "bx_f7k2q9hd",
  type: "large", ttlSeconds: 7200,
});

sandbox.resume(sandbox_id="bx_f7k2q9hd", resume_request=ResumeRequest(type="large", ttl_seconds=7200))

A resume needs a complete snapshot. You get one when you stop the sandbox with boat stop.
You can resume on a smaller machine. If the sandbox has more data than the smaller machine 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).

Fork

A fork copies a sandbox into a new sandbox. Boat uses the latest snapshot of the source. The source keeps running, and Boat does not change it.

boat fork bx_f7k2q9hd
boat fork bx_f7k2q9hd --type small
boat fork bx_f7k2q9hd --ttl 600         # lifetime for the fork, in seconds
boat fork bx_f7k2q9hd --no-auto-stop    # runs until you stop it

curl -sS -X POST "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/fork" \
  -H "Authorization: Bearer $BOAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"small","ttlSeconds":600}'

const forked = await sandbox.fork({
  sandboxId: "bx_f7k2q9hd",
  type: "small", ttlSeconds: 600,
});

forked = sandbox.fork(sandbox_id="bx_f7k2q9hd", fork_request=ForkRequest(type="small", ttl_seconds=600))

What the fork gets from the source:

The whole disk.
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.

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. You see all your files at once. Boat downloads their content in the background.

What	What happens
Every resume, fork and deploy	It runs on a new machine. Boat downloads your files again in the background, even if the sandbox had all its files before the stop. `hydrated` is `false` until the download ends.
A file that is not downloaded yet	When you open or read it, Boat gets that file first. Then you get the right bytes.
End of the download	`hydrated` becomes `true`, `hydratedAt` is set, and the `sandbox.hydrated` webhook fires.
Files of the machine image	They are already on every machine. Boat downloads only the files that differ from the image.
Paths in `.boxignore`	Boat does not save them, so it does not download them. Read Leave files out.

A restore does not need space for a second copy of your disk. Boat removes each downloaded part when it has used it. The restore limits of each machine count the size of your files, not the smaller download size. Permissions, owners, times and extended attributes come back with your files and folders. Two of them come back later:

Extended attributes of a file come back when the content of that file arrives. Folders have theirs from the start.
Folder modification times come back when the download ends. Each new file in a folder changes the time of that folder, so Boat sets the time last.

Make the first start faster

When a sandbox starts from a snapshot, it records which files open first. It keeps this list in .ascii/playbook.json. At the next start, Boat downloads these files first. Your app then works before the rest of the disk arrives. ready does not wait for these files. The list is a normal file. It goes into the snapshot, so forks and deploys get it too. The list is recorded only while a sandbox starts from a snapshot. Do these steps in this order:

Start the sandbox from a snapshot

Resume a stopped sandbox, or deploy one from the template that you want to update. A new, empty sandbox has nothing to record.

boat resume bx_f7k2q9hd

Start your app at once

Run your normal start command at once, while files still download. Boat records each file that your app opens, in order. Boat does not record files that open after the download ends.

boat exec bx_f7k2q9hd "cd my-repo && npm run dev"

Wait for the download to end, then save

Boat writes the list when the download ends. Save after that. If you save too early, the template does not have this run.

boat snapshot bx_f7k2q9hd web-stack

Each run adds to the list. It does not replace it. The newest run counts most. Each time you repeat these steps, the template starts a little faster. The list holds the first 5,000 paths.

​Resume

​Fork

​How fast a sandbox comes back

​Make the first start faster

Resume

Fork

How fast a sandbox comes back

Make the first start faster