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

# TTL & Lifecycle

Every sandbox has a configurable **time-to-live (TTL)** — a hard limit after which Modbox automatically destroys all resources, regardless of whether you called `destroy` explicitly.

## Why TTL matters

Without TTL, a sandbox lives until you explicitly destroy it. If your application crashes, your agent hangs, or you simply forget to clean up, orphaned sandboxes accumulate and consume resources.

TTL is your safety net.

## Setting TTL

Pass `ttl_seconds` when provisioning:

```bash
POST /sandboxes/provision

{
  "task_id": "my-sandbox",
  "ttl_seconds": 300   // destroy after 5 minutes
}
```

Valid range: **60 seconds (1 min) to 86400 seconds (24 hours)**.

## Default TTL per image

You can set a default TTL on an image so every sandbox provisioned from it gets that TTL automatically:

```bash
PUT /sandbox-images/{image_id}

{
  "ttl_seconds": 3600   // 1 hour default for all sandboxes using this image
}
```

The TTL passed at provision time takes precedence over the image default.

## TTL recommendations

| Use case                   | Recommended TTL |
| -------------------------- | --------------- |
| Single code execution      | 60–120s         |
| AI agent step              | 120–300s        |
| Multi-step agent session   | 600–1800s       |
| Interactive session / REPL | 3600s           |
| PR preview environment     | 86400s (24h)    |
| Workshop environment       | 14400s (4h)     |

## Lifecycle events

| Event                      | Trigger                                               |
| -------------------------- | ----------------------------------------------------- |
| `PROVISIONING → RUNNING`   | Pod passes readiness probe                            |
| `RUNNING → DESTROYED`      | `POST /sandboxes/destroy` called **or** TTL expires   |
| `PROVISIONING → DESTROYED` | `POST /sandboxes/destroy` called before pod was ready |

## Checking time remaining

The sandbox `detail` endpoint returns `created_at`. You can calculate remaining time:

```typescript
const sandbox = await modbox.getSandbox(sandboxId);
const createdAt = new Date(sandbox.createdAt).getTime();
const ttl = 300; // seconds (you set this at provision time)
const expiresAt = new Date(createdAt + ttl * 1000);
const remaining = Math.max(0, expiresAt.getTime() - Date.now()) / 1000;
console.log(`Sandbox expires in ${remaining.toFixed(0)}s`);
```

## Reaper background process

Modbox runs an internal TTL reaper every **60 seconds** that scans for expired sandboxes and destroys them. This means a sandbox may live up to 60 seconds past its TTL before being destroyed.

This 60-second grace window is intentional — it avoids bursting the infrastructure with deletions and gives in-flight requests time to complete.