Stop, pause, and resume a sandbox
This guide stops and pauses a sandbox, then brings it back. You need
tritonctl signed in to your cloud and a running sandbox, here named dev.
Pause needs the memory feature gate, which your operator turns on. A
desktop sandbox cannot be paused, and neither can a sandbox on a compute node
that cannot save memory. Both answer 400 PersistModeUnsupported; use stop
for them.
| Verb | Keeps | Processes after |
|---|---|---|
stop, then start | Disk | Boot fresh |
pause, then resume | Memory and disk | Go on where they were |
Stop and start
tritonctl sandbox stop dev
The guest shuts down and the disk is kept. Add --force to halt the guest
without asking it to shut down.
tritonctl sandbox start dev
The command waits until the sandbox runs again.
Pause and resume
tritonctl sandbox pause dev
The sandbox saves its memory and disk, and then frees its memory on the compute node. A paused sandbox holds no memory. Its deadline becomes the stopped lifetime, as for a stopped sandbox. The paused sandbox, with its disk and saved memory, is deleted 7 days after the pause, or at its own deadline if that is later. See the deletion notice in Deadlines and idle time.
The command asks the API to wait up to 120 seconds, but tritonctl gives up
on a request after 60 seconds by default. A large sandbox can take longer.
Add --timeout 0 to wait without a limit:
tritonctl sandbox pause dev --timeout 0
If the command times out, the pause goes on. Check the state with
tritonctl sandbox show dev.
tritonctl sandbox resume dev
The command waits until the sandbox runs, with the same 120-second wait and
60-second client timeout as pause. Every process goes on where it was.
A resume resets the deadline to now plus the sandbox's TTL. To ask for a
longer one, give --ttl in seconds. The resume uses the longer of the two:
tritonctl sandbox resume dev --ttl 3600
resume is never gated, so you can always bring back a paused sandbox.
Choose what the deadline does
Every sandbox has a deadline. Set the action when you create the sandbox:
tritonctl sandbox create --name dev --ttl 2h --on-deadline pause
The action is delete (the default), stop, or pause. pause needs the
memory gate. Add --idle-timeout to apply the action after a time with no
activity:
tritonctl sandbox create --name dev --ttl 8h --idle-timeout 30m --on-deadline stop
Change these later with tritonctl sandbox update, and move the deadline
with tritonctl sandbox keepalive dev --ttl 1h.
If a resume fails
A resume that fails before the guest runs keeps the saved memory. The
sandbox goes back to paused, and you can run resume again.
If the compute node reports the saved memory gone, the sandbox goes to
stopped with the reason memory_lost. sandbox show reports the error
SandboxStateConflict, "the paused memory could not be restored", and guest
calls answer 409 SandboxNotRunning.
Start it to boot cold with its disk:
tritonctl sandbox start dev
| Error | Cause | Fix |
|---|---|---|
403 FeatureDisabled naming memory | Pause is not on for your tenant. | Use stop, or ask your operator. |
400 PersistModeUnsupported | The sandbox is a desktop, or its compute node cannot save memory. | Use stop and start. |
409 SandboxNotRunning on pause | The sandbox is not running. | Check the state with tritonctl sandbox show dev. |
409 SandboxStateConflict on pause | A snapshot of the sandbox is being taken. | Pause it when the snapshot ends. |
409 SandboxStateConflict on resume | The sandbox is not paused. A stopped sandbox starts. | Run tritonctl sandbox start dev. |