Sandbox lifecycle

How connection lifetime, local sandbox lifetime, and Fleet pool capacity differ.

A connection, a local sandbox, and a Fleet pool have separate lifetimes. Choose who owns each resource before deciding when to disconnect or clean up.

Local machine and connection lifetime#

An ephemeral local sandbox belongs to one block of work. Its context manager calls cleanup when the block exits. A persistent local sandbox outlives the creating script until you delete it. Give it a name so another process can reconnect later.

Sandbox.connect attaches to an existing running local sandbox. Closing that connection leaves the sandbox running; deleting the sandbox discards its state. Save results before deleting it. The local lifecycle guide shows creation, reconnection, and cleanup patterns.

Fleet claims and pool capacity#

On Fleet, disconnect() drops the connection without releasing the claim. Exiting a pool.claim() context releases the claim, but the pool can keep warm capacity available and incur cloud usage charges. Deleting the pool is a separate operation that removes its capacity and state.

The Pool reference defines ownership and release behavior. Expire pools and claims automatically explains cleanup deadlines. Keep claim cleanup inside each workload and delete a pool only when you own its lifecycle; a shared pool can serve other callers.

Runtime limits#

Local execution and Fleet share SDK concepts, but that does not make their lifecycle operations interchangeable. See Sandbox runtime support for versioned image and transport limits. In cua-sandbox 0.7.0, Sandbox.snapshot() is not implemented for local sandboxes or Fleet creation paths, and Fleet rejects snapshot-derived images.

Create and auto-destroy a sandbox#

See Create and auto-destroy a sandbox for the local SDK pattern.

Create a persistent sandbox#

See Create a persistent sandbox for the local SDK pattern.

Reconnect to a running sandbox#

See Reconnect to a running sandbox for the local SDK pattern.

List running sandboxes#

See List running sandboxes for the local SDK pattern.

Choose a local runtime#

See Choose a local runtime for the local SDK pattern.