Create capacity and claim from it

Sandbox.create(image, local=False) needs no pool. Create one when you want a fixed name that other processes or teams claim from, a static warm size, a creation-age TTL, or Terraform (Terraform). Pool names are lowercase DNS labels, unique across all accounts.

Create a pool#

import os
 
from cua_sandbox import Image, Pool, PoolOptions, SandboxSpec
 
pool = await Pool.apply(
    os.environ["CUA_POOL_NAME"],
    SandboxSpec(image=Image.linux(), cpu=4, memory_mb=4096, services={"env": 3211}),
    PoolOptions(replicas=1),
)
print(f"Pool ready to claim from: {pool.name}")

Pool.apply creates or updates the pool and its template. SandboxSpec is what the sandboxes run; PoolOptions is how capacity is kept (Pool reference). PoolAccessDeniedError (403) usually means another account owns the name.

Claim from it#

A pool fixes the image, command, services and size, so pass only the pool:

cua sb create --on cloud --pool my-team-desktop --name my-task
cua sb exec my-task uname -a
cua sb rm -f my-task

Fields you pass with a pool must match its template, else PoolSpecMismatch shows the diff; CloudOptions(pool=..., apply=True) (CLI --apply) writes them to the template instead. A released sandbox may be recycled, so copy results out first.

Claim calls#

A failed claim releases a claim it created, never a preexisting one. Images without cua-spacesd pass their own service=.

Keep a sandbox across processes#

Name the sandbox, do not release it, and extend its lease for idle periods (TypeScript: sb.keepAlive(...), sb.detach(), sandboxes().connect(name)):

sb = await Sandbox.create(image, local=False, name="my-task", keep_alive_minutes=120)
reference = sb.to_dict()   # store it (JSON-serializable)
await sb.disconnect()      # the sandbox stays held
 
sb = await Sandbox.from_dict(reference)   # later, in another process
await sb.keep_alive(minutes=120)
await sb.close()           # releases it

cua sb keep-alive my-task --for 2h
cua sb info my-task

Expiry#

from cua_sandbox import CloudOptions, Image, Sandbox
 
sb = await Sandbox.create(Image.linux(), cloud=CloudOptions(claim_ttl=30 * 60))
await sb.keep_alive(minutes=120)   # an absolute shutdown time two hours from now

pool = await Pool.apply(
    Image.from_registry(IMAGE),
    name=POOL_NAME,
    replicas=1,
    ttl_seconds_after_created=86400,   # the pool deletes itself after 24 hours
)
async with pool.claim(name=CLAIM_NAME, ttl_seconds_after_created=3600) as sb:
    ...

• Reapplying a pool or reconnecting to a named claim does not reset a creation-age TTL, so a rerun can expire soon after it starts.
• A pool that expires deletes its sandboxes too. Keep its TTL longer than the work, and copy results out first.
• In TypeScript set poolTtlSeconds in poolOptions({...}); in Terraform, ttl_seconds_after_created on fleets_pool.

Delete a pool#

Delete it after its users have released their sandboxes. Deleting removes its template and remaining sandboxes; deletion is asynchronous.

await pool.delete()  # the Pool from Pool.apply() also deletes its template