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:

$
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:

$
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

Lifecycle events

Checking time remaining

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

1
const sandbox = await modbox.getSandbox(sandboxId);
2
const createdAt = new Date(sandbox.createdAt).getTime();
3
const ttl = 300; // seconds (you set this at provision time)
4
const expiresAt = new Date(createdAt + ttl * 1000);
5
const remaining = Math.max(0, expiresAt.getTime() - Date.now()) / 1000;
6
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.