Expire pools and claims automatically

Set a creation-age TTL so sandbox pools and claims delete themselves.

Pools and claims accept an optional creation-age TTL. Pass ttl_seconds_after_created= (requires cua-sandbox>=0.4.2) and the resource is deleted once it has existed that many seconds, whether or not it is in use. Without the argument nothing is reaped — pools and claims live until you delete them.

This guide assumes a pool created as in Create a sandbox pool with Python.

Expire a pool#

Pass the TTL to Pool.apply() to delete the whole pool — its warm replicas and its template — a fixed time after the pool was first created:

from cua_sandbox import Image, Pool
 
# Delete the whole pool 24 hours after it was first created.
pool = await Pool.apply(
    Image.from_registry(IMAGE),
    name=POOL_NAME,
    replicas=1,
    ttl_seconds_after_created=86400,
)

Expire a claim#

Pass the same argument to pool.claim() (or pool.create_claim()) to delete one claim and its sandbox a fixed time after the claim was created:

# Delete this claim and its sandbox one hour after the claim was created.
async with pool.claim(
    name=CLAIM_NAME,
    ttl_seconds_after_created=3600,
) as sandbox:
    ...

A claim TTL fills in the claim's lifecycle shutdown time with a Delete policy; a claim that already carries an explicit lifecycle keeps it.

The clock starts at creation#

The TTL counts from the resource's original creation, not its last use: re-running Pool.apply() reconciles the existing pool without resetting its age, and reconnecting to a named claim keeps the deadline set when the claim was first created.

Hand-built claim specs#

When you build a claim spec by hand, put the TTL inside it — passing both spec= and ttl_seconds_after_created= raises ValueError:

from cua_sandbox import ClaimSpec
 
spec = ClaimSpec(
    sandbox_template_ref=pool.resource.spec.sandbox_template_ref,
    warmpool=None,
    bind_deadline=None,
    lifecycle=None,
    ttl_seconds_after_created=3600,
)
async with pool.claim(spec=spec) as sandbox:
    ...

Pool expiry under live claims#