How to control sandbox lifetime: TTL, idle, and cleanup

Every team that ships an agent product has the same month-three conversation. The bill is higher than the work justifies, and the reason turns out to be sandboxes nobody killed — created by a worker that crashed on step four, or by a conversation the user closed, or by a test suite that failed before its teardown.

This is entirely preventable, and it costs about ten lines. Here are the five controls, what each one actually does to the bill, and how to combine them. The API is PandaStack's; the reasoning applies anywhere.

TTL: the one that always works

A TTL is wall-clock seconds until the platform kills the sandbox. It is the only cleanup mechanism enforced by something other than your own code, which is precisely why it's the one that matters. Your finally block does not run when the process is OOM-killed; the TTL does.

from pandastack import Sandbox

# Set it at creation. Always.
sandbox = Sandbox.create(template="code-interpreter", ttl_seconds=1800)

# Extend it when a long job legitimately needs longer
sandbox.set_ttl(7200)

print(sandbox.lifecycle())
# {"ttl_seconds": 7200, "persistent": False, "idle_seconds": 12}

Pick the TTL from the task, not from caution. A code tool in a chat gets thirty minutes. A CI job gets fifteen. A long training run gets hours and a monitoring alert. The instinct to set everything to twenty-four hours 'just in case' converts an abandoned sandbox from a rounding error into a real number.

Pause: stop the clock without losing anything

Pause halts the vCPU and leaves memory untouched. Nothing is written to disk, the process tree is intact, and resume is effectively instant. The use case is narrow and genuinely useful: an agent that has finished a step and is waiting for a human to approve the next one.

sandbox.pause()          # vCPU stopped; memory still resident
# ... wait for the human ...
sandbox.resume()         # back where it was, immediately

What pause saves depends on how you're billed. Under active-CPU metering, a paused sandbox stops the CPU charge but keeps the memory charge, because the memory is still occupying a host. If you're paying a flat provisioned rate, pausing saves you nothing at all — worth knowing before you build a workflow around it.

Hibernate: free the host, keep the state

Hibernate dumps memory and disk to a snapshot and stops the VM entirely. The host's RAM and vCPUs are released. Waking restores from the snapshot, which on a snapshot-restore platform is fast enough to be invisible in a request — roughly a couple of hundred milliseconds rather than a cold boot.

sandbox.hibernate()      # memory + disk to snapshot, VM stopped
# ... minutes or hours later ...
sandbox.wake()           # restored, same state

The catch is storage. A hibernated sandbox with 2 GB of memory is roughly 2 GB on disk, and you're paying for that disk for as long as it exists. Hibernation is the right answer for a workspace someone will come back to. It's the wrong answer for a finished job — that's what kill is for.

Persistent: opt out of TTL deliberately

Marking a sandbox persistent takes it out of TTL reaping. That's the right call for a long-lived developer workspace or a database VM, and the wrong call for anything created per request — a persistent sandbox created by a runaway loop is a persistent bill.

sandbox.set_persistent(True)     # no TTL kill
sandbox.set_persistent(False)    # back under TTL

Persistent sandboxes are still subject to the idle sweeper: after a few minutes with no activity they're hibernated, and the next request wakes them implicitly. The state survives; the host resources don't sit idle. That's the behaviour you want for a workspace someone uses twice a day.

Kill: the one people forget

Deleting the sandbox releases everything — the network slot, the rootfs, the memory. It's the only operation that takes the cost to zero rather than reducing it.

The reliable way to do this is a language feature rather than discipline, because discipline fails on the exception path.

# Python: context manager
with Sandbox.create(template="code-interpreter", ttl_seconds=1800) as sandbox:
    sandbox.exec("python3 analyse.py")
# killed on the way out, including on exception

// TypeScript: explicit resource management
{
  await using sandbox = await Sandbox.create({
    template: "code-interpreter",
    ttlSeconds: 1800,
  });
  await sandbox.exec("npm test");
}  // kill() called automatically

Putting them together

Four patterns cover nearly every application.

1. One-shot job — TTL matched to the expected runtime plus generous headroom, plus a context manager. The TTL is the backstop; the context manager is the mechanism.
2. Chat conversation — a sandbox per session, created lazily on the first code call, TTL around thirty minutes refreshed by use, explicit kill on an end-session endpoint.
3. Developer workspace — persistent, no TTL, and let idle hibernation handle the overnight and weekend gaps.
4. Fan-out — a short TTL on every branch and an explicit kill on the ones you don't promote. This is where costs get away from people fastest: sixteen forks that each live an hour because nobody reaped the fifteen losers.

Finding what's already running

Before optimising anything, look. The answer is usually a specific worker or a specific test suite, not a general problem.

from pandastack import Sandbox

for sb in Sandbox.list():
    lc = sb.lifecycle()
    if lc["idle_seconds"] > 3600:
        print(sb.id, sb.template, sb.info.get("metadata"), lc)
        # sb.kill()

Which is the argument for setting metadata at creation. A list of orphaned UUIDs tells you nothing; a list of orphaned UUIDs tagged with the job id and the service that created them tells you exactly which code path is leaking.

sandbox = Sandbox.create(
    template="code-interpreter",
    ttl_seconds=1800,
    metadata={"service": "chat-api", "session": session_id, "env": "prod"},
)

One thing that changes all of this

How much any of this matters depends on the billing model, and it's worth checking before you design around it.

Under flat provisioned pricing, an idle sandbox costs the same as a busy one, so lifetime management is the whole game and you'll be pushed toward pooling and reuse — which reintroduces the isolation problems you were avoiding.

Under per-second metering on active CPU and resident memory, idle is genuinely cheap. On PandaStack the rates are $0.000015 per active vCPU-second and $0.0000045 per working-set GiB-second, so a sandbox sitting idle waiting for a model to respond costs close to nothing. That changes the design: per-session isolation becomes the cheap option as well as the safe one, and the thing worth policing is sandboxes that keep burning CPU after their work is done, not sandboxes that merely exist.

The short version

1. Always set a TTL at creation. It's the only cleanup your code can't fail to run.
2. Use the context manager or await using for the happy path — discipline doesn't survive exceptions.
3. Pause for a human-in-the-loop wait; hibernate for a workspace someone returns to; kill for anything finished.
4. Reserve persistent for genuinely long-lived things, never for per-request work.
5. Tag every sandbox with metadata so a leak points at the code path that caused it.
6. Check whether your platform bills for existence or for use before you build a pooling layer you may not need.