> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.islo.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.islo.dev/_mcp/server.

# Sandbox Lifecycle

> Automatic pause, resume, and deletion policies for sandboxes.

Sandboxes can run unattended for hours or days, but most workloads only need compute while someone is actively using them. Lifecycle policies let the platform pause idle sandboxes to free resources, delete abandoned ones, and optionally resume on the next request — without you polling or scripting cleanup jobs.

Set a policy when you create a sandbox (via the SDK or API). The compute plane enforces it in the background. You can still pause, resume, and delete manually with the CLI or API at any time.

For event-driven creation and cleanup (e.g. per-PR previews), use [Incoming Webhooks](/concepts/incoming-webhooks/) — `ensure_sandbox` templates accept the same `lifecycle` fields.

## How it works

```
create sandbox (with lifecycle policy)
    │
    ├── running ──pause_after_idle──► paused ──delete_after──► deleted
    │         └──pause_after────────► paused
    │
    └── on_activity (if auto_resume) resumes paused sandboxes on incoming work
```

While **running**, the sandbox behaves like any other sandbox — exec, files, port forwards, and sessions all work normally.

When a timer fires, the platform **pauses** the VM: state is snapshotted, compute is released, and the sandbox no longer counts against running-sandbox quotas. Paused sandboxes keep their filesystem and can be resumed.

When `delete_after` elapses, the sandbox is **deleted** permanently.

## Policy fields

All duration fields are **seconds** (integer). Omit a field or set it to `null` to leave that behavior disabled.

| Field              | Type                         | Description                                                                                                                                                                                    |
| ------------------ | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pause_after_idle` | integer or null              | Pause after this many seconds **without activity** (no exec, file I/O, port traffic, etc.).                                                                                                    |
| `pause_after`      | integer or null              | Pause after this many seconds of **total active runtime**, regardless of activity. Acts as a hard ceiling on how long a sandbox stays running.                                                 |
| `delete_after`     | integer or null              | Delete the sandbox after this many seconds from **creation**.                                                                                                                                  |
| `auto_resume`      | `"never"` or `"on_activity"` | When a paused sandbox receives work (exec, file access, webhook delivery, etc.), resume automatically. Defaults to platform behavior when omitted — use `never` to require an explicit resume. |

`pause_after_idle` and `pause_after` can be combined. The platform pauses when **either** condition is met.

Paused sandboxes do not accrue active runtime toward `pause_after` until they resume.

## SDK examples

### Ephemeral preview environment

Pause after 10 minutes idle, delete after 24 hours:

**`Python`**

```python title="Python"
from islo import Islo

client = Islo()

sandbox = client.sandboxes.create_sandbox(
    name="preview-env",
    image="ghcr.io/islo-labs/islo-runner:latest",
    lifecycle={
        "pause_after_idle": 600,
        "delete_after": 86400,
        "auto_resume": "on_activity",
    },
)
```

**`TypeScript`**

```typescript title="TypeScript"
import { Islo } from "@islo-labs/sdk";

const client = new Islo();

const sandbox = await client.sandboxes.createSandbox({
    name: "preview-env",
    image: "ghcr.io/islo-labs/islo-runner:latest",
    lifecycle: {
        pause_after_idle: 600,
        delete_after: 86400,
        auto_resume: "on_activity",
    },
});
```

The first `exec_in_sandbox` call after idle pause resumes the VM transparently when `auto_resume` is `on_activity`.

### Long-running agent with a daily cap

Keep an agent sandbox warm during the workday but cap total runtime:

```python
sandbox = client.sandboxes.create_sandbox(
    name="agent-worker",
    image="ghcr.io/islo-labs/islo-runner:latest",
    lifecycle={
        "pause_after_idle": 1800,   # 30 min idle
        "pause_after": 28800,       # 8 h max active runtime per stretch
        "auto_resume": "on_activity",
    },
)
```

### Manual lifecycle only

Omit `lifecycle` (or pass `null`) for sandboxes you manage entirely yourself with `islo pause`, `islo resume`, and `islo rm`. See [Sandbox Commands](/cli/sandbox-commands/) for CLI details.

## Reading the policy back

`SandboxResponse` echoes the lifecycle policy on `get_sandbox` and list responses:

```python
sandbox = client.sandboxes.get_sandbox_by_name(sandbox_name="preview-env")
print(sandbox.lifecycle)  # {"pause_after_idle": 600, "delete_after": 86400, ...}
```

Lifecycle policies are set at creation and cannot be updated on an existing sandbox. Change the policy by creating a new sandbox (or snapshot and restore if you need to preserve state).

## CLI equivalents

| Automatic policy        | CLI equivalent                                                |
| ----------------------- | ------------------------------------------------------------- |
| Pause on idle / timeout | `islo pause <name>`                                           |
| Resume on activity      | `islo resume <name>` or `islo use <name>` (prompts to resume) |
| Delete after TTL        | `islo rm <name>`                                              |

Lifecycle policies automate these transitions; the CLI commands remain useful for one-off control and debugging.

## Tips

* **Cost control**: `pause_after_idle` is the main lever for sandboxes you leave open between sessions. Paused sandboxes free compute but keep state.
* **Safety net**: `delete_after` prevents forgotten preview environments from accumulating forever.
* **PR previews**: use [Incoming Webhooks](/concepts/incoming-webhooks/) with `ensure_sandbox` + lifecycle + `deliver_to_port` for per-event sandboxes that pause when idle and delete on `closed`.
* **Quota pressure**: paused sandboxes do not count against running-sandbox limits — prefer pause over delete when you'll return to the same workspace.