Snapshot and fork a sandbox
This guide takes snapshots of a sandbox and makes copies of it, called forks.
You need tritonctl signed in to your cloud and a sandbox in the running or
stopped state, here named dev. Memory snapshots and memory forks also need
the memory feature gate, which your operator turns on.
Snapshots and forks stay on the parent's compute node. Snapshots belong to their sandbox and are deleted with it.
Take a filesystem snapshot
tritonctl sandbox snapshot create dev --name ready
The guest's filesystem is frozen for a moment while the snapshot is taken. Running processes are not part of a filesystem snapshot.
List and inspect snapshots:
tritonctl sandbox snapshot list dev
tritonctl sandbox snapshot show dev ready
Fork from a snapshot
tritonctl sandbox fork dev --count 3 --from-snapshot ready --name-prefix worker
Each child boots fresh with the parent's disk as it was in the snapshot, and
gets its own address. The children are named worker-1, worker-2, and
worker-3. Without --name-prefix, each gets a name of the form sb-<HEX>.
--count takes 1 to 20.
Each child takes the parent's package, template, start command, labels,
metadata, network policy, idle timeout, deadline action, auto_resume
setting, and the default user and working directory for exec. --label adds
labels to the ones it takes. The command waits until every child runs. If a
child does not start, the command names it and exits 1. The other children
keep running.
Add --ttl to give the children a shorter life than the parent's remaining
time:
tritonctl sandbox fork dev --count 3 --from-snapshot ready --ttl 30m
Fork the live sandbox
Without --from-snapshot, the fork takes a snapshot now, named
fork-<HEX>. The parent keeps running:
tritonctl sandbox fork dev --count 2
The fork-<HEX> snapshot stays on the parent after the fork. A sandbox holds
at most 16 snapshots, and these count toward that limit. Delete the ones you
no longer need.
Take a memory snapshot and fork with memory
A memory fork holds everything that was in the parent's memory, including secrets and open sessions. Take the memory snapshot before you load secrets.
A memory fork continues the parent's running processes in each child:
tritonctl sandbox fork dev --count 3 --kind memory
Each child gets its own hostname, MAC and IP address, clock, and random number seed. To keep a memory snapshot for later:
tritonctl sandbox snapshot create dev --name warm --kind memory
Delete a snapshot
tritonctl sandbox snapshot delete dev ready
The command asks for confirmation. Add -y in scripts. A snapshot that a
live fork came from cannot be deleted until that fork is gone.
Keep a snapshot after the sandbox is gone
Build a template from it:
tritonctl sandbox template build devbox --from-snapshot dev/ready --wait
If a fork fails
| Error | Cause | Fix |
|---|---|---|
400 BadRequest, "count must be between 1 and 20" | --count is 0 or above 20. | Ask for 1 to 20 children. |
403 FeatureDisabled naming memory | Memory forks are not on for your tenant. The parent's deadline action is pause, which also needs the gate. | Use a filesystem fork, change the parent's --on-deadline, or ask your operator. |
403 FeatureDisabled naming fork | Forks are off for your tenant. | Ask your operator. |
403 FeatureDisabled naming desktop or egress_domains | The parent is a desktop, or its network policy has domain rules, and that gate is off for your tenant. | Ask your operator. |
409 SandboxNotRunning | The parent is neither running nor stopped. | Check the state with tritonctl sandbox show dev. |
409 SandboxStateConflict | The snapshot is not ready yet. | Wait for tritonctl sandbox snapshot show to report it ready, then fork. |
409 QuotaExceeded | The parent holds 16 snapshots. | Delete a snapshot, then fork. |
503 SandboxNoCompatibleNode | The parent's compute node has no room for that many children. | Ask for fewer, or retry later. |