Skip to content
RuntimeDocs

Sandbox states and actions

A sandbox is always in one of seven states. The state field of every read names it, and actions lists what you can do from there: each listed action changes the sandbox. An action not listed changes nothing (a pause of a paused sandbox returns it as it is) or returns 409, with the same list in details.actions. A wait for a state (GET /v1/sandboxes/{id}?waitFor=running) returns as soon as the sandbox is there, or as soon as it cannot get there without a new action, such as a sandbox you stopped.

This page is generated from the sandbox's lifecycle in the code.

Updated .md

States#

State You can It moves by itself to
starting stop, delete running, stopping, stopped
running pause, stop, restart, delete starting, pausing, paused, stopping, stopped
pausing wake, stop, delete paused, stopping, stopped
paused wake, stop, delete starting, resuming, stopping, stopped
resuming stop, delete running, pausing, paused, stopping, stopped
stopping delete stopped
stopped restart, delete nothing: it has ended

restart on a stopped sandbox needs its disk kept (diskKept); on a running one it reboots it. A job's run lists no restart. While Runtime moves a sandbox between servers, only pause is listed.

When the server a sandbox runs on is lost, its memory is lost with it. A disk with a copy on another server (diskKept: true) is kept. A sandbox that was running is stopped with stopReason: host_lost, then Runtime restarts it from that disk on another server. One that was paused stays paused; its next wake starts it from its disk (memoryRestored: false).

Every move#

From To Made by Why
starting stopping your action stop
starting running Runtime its machine started
starting stopping Runtime its machine was lost as it started and not put back
starting stopping Runtime its start failed
starting stopping Runtime no room came while it waited
starting stopping Runtime its time or cost limit
starting stopped Runtime its host was lost
starting stopped Runtime its machine ended on its own
starting stopped Runtime its moved pause could not be restored
running stopping your action stop
running pausing your action pause
running stopped Runtime a primary lost with its host took over its machine
running starting Runtime its machine was lost as it started
running stopping Runtime its machine was lost as it started and not put back
running stopping Runtime no room came while it waited
running pausing Runtime idle pause
running stopping Runtime its time or cost limit
running paused Runtime its machine was frozen under it
running stopped Runtime its host was lost
running stopped Runtime its machine ended on its own
pausing stopping your action stop
pausing resuming your action wake
pausing starting your action wake
pausing stopping Runtime its machine was lost as it started and not put back
pausing stopping Runtime no room came while it waited
pausing stopping Runtime its time or cost limit
pausing paused Runtime its machine froze
pausing stopped Runtime its host was lost
pausing stopped Runtime its machine ended on its own
paused stopping your action stop
paused resuming your action wake
paused starting your action wake
paused stopping Runtime its machine was lost as it started and not put back
paused stopping Runtime no room came while it waited
paused stopping Runtime its time or cost limit
paused resuming Runtime a process's timer
paused starting Runtime a process's timer
paused stopped Runtime its host was lost
paused stopped Runtime its machine ended on its own
resuming stopping your action stop
resuming stopping Runtime its machine was lost as it started and not put back
resuming stopping Runtime no room came while it waited
resuming paused Runtime no host can hold it
resuming pausing Runtime its wake was given up
resuming stopping Runtime its time or cost limit
resuming running Runtime its machine woke
resuming stopped Runtime its host was lost
resuming stopped Runtime its machine ended on its own
resuming paused Runtime its moved pause could not be restored
stopping stopped Runtime its machine froze
stopping stopped Runtime its host was lost
stopping stopped Runtime its machine ended on its own
stopped starting your action restart
stopped starting Runtime started again over its disks after its host was lost
stopped running Runtime it took over a standby's running machine
Try it on your own work.Free hours every month, no card. Or paste the setup prompt into your agent.
Start free, no card