Sandbox Lifecycle

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 — 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.

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:

1
from islo import Islo
2
3
client = Islo()
4
5
sandbox = client.sandboxes.create_sandbox(
6
    name="preview-env",
7
    image="ghcr.io/islo-labs/islo-runner:latest",
8
    lifecycle={
9
        "pause_after_idle": 600,
10
        "delete_after": 86400,
11
        "auto_resume": "on_activity",
12
    },
13
)

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:

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

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 for CLI details.

Reading the policy back

SandboxResponse echoes the lifecycle policy on get_sandbox and list responses:

1
sandbox = client.sandboxes.get_sandbox_by_name(sandbox_name="preview-env")
2
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

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 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.