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

# Sandbox lifecycle and states

> A sandbox moves through the Running, Paused, and Killed states. This page covers the transitions, the timeout and idle timeout settings, and the SDK defaults.

A sandbox moves through three states, and two settings decide when it leaves the first one. This page is the reference for the state model, the settings that drive the transitions, and the defaults the SDK applies when a setting is not passed.

> [!NOTE]
>
> Install the SDK, or the CLI for `ppio` commands, and set the `PPIO_API_KEY` and `PPIO_DOMAIN` environment variables before running these examples. See [Quickstart](https://docs.ppio.ai/sandbox/quickstart.md) and [Install and authenticate](https://docs.ppio.ai/sandbox/cli/install.md).

## States

A sandbox moves through three states: Running, Paused, and Killed.

* **Running**: the sandbox is active and can execute commands and serve connections.
* **Paused**: the sandbox is suspended. Its filesystem and memory state are preserved and billing for compute stops. It can be resumed back to Running, typically in about a second.
* **Killed**: the sandbox is terminated and its resources are released. A killed sandbox cannot be resumed.

```mermaid theme={null}
stateDiagram-v2
    [*] --> Running
    Running --> Paused: pause
    Running --> Killed: kill
    Running --> Killed: timeout or idle timeout
    Running --> Paused: timeout or idle timeout with pause
    Paused --> Running: resume
    Paused --> Running: auto-resume
    Paused --> Killed: kill
```

## What moves a sandbox out of Running

Two settings drive the transitions out of Running.

> [card] [Timeout](https://docs.ppio.ai/sandbox/timeout.md)
>
> The maximum lifetime, counting down from creation regardless of activity.

> [card] [Idle timeout](https://docs.ppio.ai/sandbox/idle-timeout.md)
>
> Fires only when no client is connected for the configured duration.

On timeout or idle timeout, **pause** can be chosen instead of **kill**, so the sandbox can be resumed later, optionally with auto-resume. When paused, resuming restores the sandbox to Running with its state intact. When killed, the sandbox and its data are gone.

The timeout of a running sandbox can be extended at any time. Pausing a sandbox keeps its state without a running clock.

## Timeout and auto-resume settings

Both settings live in the `lifecycle` object at creation. If `lifecycle` is not passed, the sandbox is killed when the timeout expires.

```python Python theme={null}
from ppio_sandbox import PPIO

ppio = PPIO()
sandbox = ppio.sandbox.create(
    lifecycle={
        'on_timeout': 'pause',
        'auto_resume': True,
    },
)

sandbox.kill()
```

```javascript Node.js theme={null}
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create({
  lifecycle: {
    onTimeout: 'pause',
    autoResume: true,
  },
})

await sandbox.kill()
```

> [tab] Python
>
> **lifecycle** `SandboxLifecycle`
>
> What happens when the timeout expires.
>
> **properties**
>
> **on\_timeout** `string` (default: kill)
>
> `kill` or `pause`.
>
> **auto\_resume** `bool` (default: False)
>
> Whether activity resumes a paused sandbox. Valid only when `on_timeout` is `pause`.

> [tab] Node.js
>
> **lifecycle** `SandboxLifecycle`
>
> What happens when the timeout expires.
>
> **properties**
>
> **onTimeout** `string` (default: kill)
>
> `kill` or `pause`.
>
> **autoResume** `boolean` (default: false)
>
> Whether activity resumes a paused sandbox. Valid only when `onTimeout` is `pause`.

## SDK defaults

The SDK applies these defaults when the call does not set them:

* A new sandbox stays alive for 5 minutes unless `timeout` is passed.
* A sandbox resumed with `connect()` gets a new timeout of 5 minutes unless a timeout is passed to `connect()`.
* The sandbox is killed, not paused, when the timeout expires.
* Long-running mode is off, so `timeout` is capped by the team's maximum session duration.

> [!NOTE]
>
> The console Playground applies different defaults. **Lifecycle** is **Long running** and **On timeout** is **Pause**, so a sandbox created there can outlive the SDK default and pauses instead of being killed. Both settings are on the [Playground](https://console.ppio.ai/sandbox/playground).

## Long-running sandboxes

By default, `timeout` is effective for at most the team's maximum session duration, and a larger value is capped. See [Quotas and limits](https://docs.ppio.ai/sandbox/quotas.md). Long-running mode lifts that cap, so the `timeout` passed at creation can exceed it. Use it for workloads that stay alive beyond a typical session, such as persistent services, long agent tasks, and background jobs.

Long-running mode is configured through the `metadata` field at creation. The key is `long_running` and the value is `"true"`, as a string.

`long_running` works together with `timeout`: set the timeout the sandbox needs. Without `long_running`, `timeout` is effective for at most the team's maximum session duration. If `timeout` is not set, it defaults to 5 minutes.

> [!WARNING]
>
> Long-running mode does not disable the [idle timeout](https://docs.ppio.ai/sandbox/idle-timeout.md). A sandbox with an idle timeout is still paused or killed when it has no active connections.

### Scope and inheritance

* Only `create` accepts `long_running`.
* `resume`, including auto-resume, keeps the behavior: a sandbox created with `long_running` keeps it after being resumed from a snapshot.
* `clone` inherits the parameter, and the sandbox keeps it when it continues running after a `reset`.

### Cost and quota

The team's cap is returned by the quota API as `limit.max_length_hours` in Python and `limit.maxLengthHours` in Node.js.

> [!TIP]
>
> A long-running sandbox keeps running until its timeout, an idle timeout, or `kill()`, and bills per second the whole time. Set an explicit `timeout`, and an idle timeout for services that can sleep.


## Related topics

- [Agent Sandbox: secure cloud sandboxes for AI agents](https://docs.ppio.ai/sandbox/overview.md)
- [Pause and resume a sandbox](https://docs.ppio.ai/sandbox/pause-resume.md)
- [Set or extend a sandbox timeout](https://docs.ppio.ai/sandbox/timeout.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.