Timeout & TTL

Default Timeout

Every sandbox is created with a default timeout of 86,400 seconds (24 hours). When the timeout expires, the sandbox is automatically terminated by the reaper service.

This is significantly longer than most sandbox platforms -- giving your AI agents and long-running workflows plenty of time to complete without manual timeout management.

Setting a Custom Timeout

You can set a custom timeout when creating a sandbox:

const sandbox = await client.createSandbox({
  templateID: "base",
  timeout: 3600, // 1 hour in seconds
});

curl -X POST https://api.lelantos.ai/sandboxes \
  -H "X-API-Key: lel_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"templateID": "base", "timeout": 3600}'

Extending a Running Sandbox

Use refresh to extend the lifetime of a running sandbox. The timeout is reset to the specified duration from the current time:

// Extend by 1 hour from now
await sandbox.refresh(3600);

curl -X POST https://api.lelantos.ai/sandboxes/SANDBOX_ID/refresh \
  -H "X-API-Key: lel_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"timeout": 3600}'

Changing the Timeout

Use setTimeout to change the timeout of a running sandbox:

// Set timeout to 2 hours
await sandbox.setTimeout(7200);

curl -X POST https://api.lelantos.ai/sandboxes/SANDBOX_ID/timeout \
  -H "X-API-Key: lel_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"timeout": 7200}'

Disabling Auto-Expiry

Set the timeout to 0 to disable automatic expiration. The sandbox will run indefinitely until explicitly killed:

await sandbox.setTimeout(0);

How the Reaper Works

The reaper is a background service that runs every 5 seconds, checking for sandboxes whose timeout has expired. When an expired sandbox is found:

1. The reaper sends a kill command via NATS to the worker node.
2. The worker terminates the Firecracker microVM.
3. The sandbox transitions to the stopped state.
4. A sandbox.lifecycle.stopped event is recorded.

Billing stops the moment the sandbox is terminated.