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

# Platform-Managed Lifecycle

A sandbox pauses or terminates on its own when its timeout or its idle timeout passes. Both are set on the create, and the timeout can be changed while the sandbox exists. A paused sandbox also terminates once its retention period ends.

## Timeout

`timeout` is the sandbox's lifetime in seconds of running. It defaults to `300`, and `null` means none. The clock starts at `started_at` and stops while the sandbox is paused. When it passes, `on_timeout` applies.

| `on_timeout` | Effect |
| - | - |
| `terminate` (default) | The sandbox terminates with `termination_reason` `timeout`. |
| `pause` | The sandbox pauses with `pause_reason` `timeout`. |

While the sandbox is `starting` or `running`, `expires_at` is when its timeout fires. While it is `paused`, `remaining` is the number of seconds of its timeout left.

`POST /sandbox/{id}/timeout` with `{"seconds": 3600}` sets the expiry to now plus `seconds`, or removes it with `null`. On a paused sandbox it sets `remaining`. A resume always grants at least 300 seconds, so a sandbox paused by its timeout runs again after a resume. `telnyx-edge sandbox-cpu timeout <id> 3600` sends the same request, and `none` removes the timeout.

## Idle Timeout

`idle_timeout` is the number of seconds without activity after which `on_idle` applies. It has no default and cannot exceed `timeout`.

| `on_idle` | Effect |
| - | - |
| `pause` (default) | The sandbox pauses with `pause_reason` `idle_timeout`. |
| `terminate` | The sandbox terminates with `termination_reason` `idle_timeout`. |

Activity is any of the following.

* An exec that starts, or one that is still running
* Stdin written, or an attach held open
* A file request
* A connect

The main command's own work is not activity.

## Paused Retention

A sandbox that stays paused for 7 days terminates with `termination_reason` `paused_expired`. See [Persistence](https://developers.telnyx.com/docs/edge-compute/sandboxes/platform-properties/persistence.md#retention).
