> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# User-Controlled Lifecycle

A sandbox moves between four states. Requests pause, resume, and terminate it, an agent connects to it at the start of each turn, and a fork copies a running sandbox into many.

## States

A sandbox is always in one of four states. Each arrow below is a request or an event that moves it to the next.

The diagram shows the four states. A sandbox goes from `starting` to `running`. A pause request, the idle timeout, or the timeout with `on_timeout` `pause` moves it to `paused`, and a resume or a connect moves it back to `starting`. It reaches `terminated` from `starting` on a failure, from `running` on a terminate request, a timeout, or the main command's exit, and from `paused` on a terminate request or the end of its paused retention.

| `state` | Meaning |
| - | - |
| `starting` | Being placed, built, booted, restored, or resumed. |
| `running` | Running. A pause or a snapshot in progress still reads `running`. |
| `paused` | Memory, processes, and disks saved. No CPU used. |
| `terminated` | Ended. `termination_reason` says why. See [Terminate](#terminate). |

`started_at` is set when the boot starts. The sandbox reads `running` with `ready` `true` about 2 seconds later, and the `started` [lifecycle event](https://developers.telnyx.com/docs/edge-compute/sandboxes/data-plane-operations/lifecycle-events.md#event-types) marks that moment.

## Pause and Resume

`POST /sandbox/{id}/pause` pauses a `running` sandbox. The response is `202`. The sandbox reads `running` until the pause completes, then `paused`, with `paused_at` and a `pause_reason` of `customer`, `idle_timeout`, or `timeout`. See [Persistence](https://developers.telnyx.com/docs/edge-compute/sandboxes/platform-properties/persistence.md#memory-persistence) for what a pause keeps.

`POST /sandbox/{id}/resume` restores a `paused` sandbox on the same host. The response is `202`, and the sandbox reads `starting`, then `running`. A resume when the organization is at its quota is refused with `429 quota_exceeded`, and the sandbox stays paused.

Execs and file requests to a paused sandbox are refused with `409 sandbox_paused`.

`telnyx-edge sandbox-cpu pause` and `resume` send the same requests and wait for the state.

## Connect

`POST /sandbox/{id}/connect` is the request an agent sends at the start of each turn.

```json Request theme={null}
{ "timeout": 600 }
```

* On a `paused` sandbox, it starts the resume and answers `202` once the resume is under way, after several seconds.
* On a `running` sandbox, it answers `200`, and on a `starting` one `202`.
* On every sandbox, it moves `expires_at` to at least now plus `timeout`, never earlier. `timeout` defaults to 300 seconds, and `null` leaves the expiry unchanged. The sandbox's `timeout` field stays as created.

A connect counts as activity for `idle_timeout`.

## Terminate

`POST /sandbox/{id}/terminate` ends a sandbox in any state and discards its memory, disks, and snapshots. The response is `202`, and the sandbox reads `terminated` once the host has released it. A second terminate answers `202` with the sandbox unchanged. `telnyx-edge sandbox-cpu terminate` sends it after a confirmation, which `--yes` skips.

A terminated sandbox's `termination_reason` says why it ended.

| `termination_reason` | Cause |
| - | - |
| `terminated` | A terminate request. |
| `exited` | The main command exited. `exit_code` is set. |
| `timeout` | The `timeout` passed with `on_timeout` `terminate`. |
| `idle_timeout` | The `idle_timeout` passed with `on_idle` `terminate`. |
| `paused_expired` | The sandbox stayed paused past the retention period. |
| `build_failed` | The image could not be pulled or built. |
| `no_capacity` | A fork sibling no host could place. |
| `node_lost` | The sandbox's host failed. |
| `internal_error` | The platform failed. |

## Wait

`GET /sandbox/{id}/wait?timeout=10` returns once the sandbox is `paused` or `terminated`, or after `timeout` seconds, at most 10. `timeout=0` answers at once, and a larger value is capped at 10. A client uses it to wait for a pause or a terminate to complete.

## Fork

`POST /sandbox/{id}/fork` creates up to 20 siblings of a `running` sandbox, each with its memory, processes, and disks as they are now.

```json Request theme={null}
{
  "count": 5,
  "name": "attempt",
  "tags": { "branch": "refactor" }
}
```

The response is `202` at once, with every sibling in `starting`.

```json Output theme={null}
{
  "items": [
    {
      "index": 1,
      "sandbox": {
        "id": "sb-us-east-1-0193c4d3-...",
        "name": "attempt-1",
        "state": "starting",
        "fork_of": "sb-us-east-1-0193c4d2-...",
        "swarm": "swm-0193c4d3-...",
        ...
      }
    },
    ...
  ],
  "swarm": "swm-0193c4d3-..."
}
```

* **Live state.** Each sibling starts from the source's state at the moment of the fork. The source's processes stand still while that state is saved, about 10 seconds at 1 GiB, with its state reading `running`, and continue afterwards.
* **Names and tags.** A sibling's name is `<name>-<index>`, with `index` counted from 1. Its tags are the source's, with the request's tags merged over them.
* **Swarm.** The source and every sibling share one `swarm` ID for their whole lives, and a fork of a sibling joins the same swarm. `GET /sandbox?swarm=<id>` lists them.
* **Placement.** A sibling no host can place reads `terminated` with `termination_reason` `no_capacity`.

A fork of a sandbox that is not `running` is refused with `409 sandbox_not_running`. A fork past the quota is refused whole with `429 quota_exceeded`. The source holds a slot of the quota, so the largest fork under the default quota of 20 is 19 siblings.
