# 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.

## 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 |