Sandbox SDK reference

Packages, configuration, and Sandbox lifecycle APIs for Python and TypeScript.

The Python Sandbox SDK supports local execution and hosted Fleet pools through one API. Backend support differs even when method names are shared. Use Sandbox runtime support for local/Fleet image and transport differences, and Sandbox lifecycle for connection, claim, and capacity ownership.

Packages#

This reference describes the published cua-sandbox 0.7.0 Python package and @trycua/fleet 0.1.2 TypeScript package.

The Python Sandbox distribution can be installed independently:

pip install cua-sandbox==0.7.0

Its primary imports are:

from cua_sandbox import Image, Pool, Sandbox, Template

See Pool and claim reference, Image reference, OS and image catalog, Sandbox interfaces, and TypeScript Fleet reference.

Configuration and authentication#

configure() updates process-wide settings. All parameters are optional, keyword-only strings; None leaves a setting unchanged.

def configure(
    *, api_key=None, base_url=None, fleet_base_url=None, token_url=None,
    client_id=None, client_secret=None, fleet_token=None,
) -> None: ...

Fleet authentication uses a configured fleet_token, then FLEETS_TOKEN. If neither supplies a nonempty token, it uses client_id and client_secret from configure(), falling back to CUA_CLIENT_ID and CUA_CLIENT_SECRET.

Endpoint environment variables override the corresponding configure() values. Legacy API keys resolve from the per-call api_key, global configuration, ~/.cua/credentials, then CUA_API_KEY.

Credential acquisition is documented in Fleet pools need their own credentials. login(base_url=None) and whoami(api_key=None) belong to the legacy API-key flow; they do not configure Fleet OAuth credentials.

Sandbox creation#

Sandbox.create() returns a connected Sandbox. Sandbox.ephemeral() is an async context manager that performs cleanup on exit.

The complete create() signature is:

async def create(
    image=None, *, pool=None, name=None, replicas=1, service="server",
    claim_spec=None, keep_alive_minutes=None, api_key=None, local=False,
    runtime=None, cpu=None, memory_mb=None, disk_gb=None,
    region="us-east-1", time_to_start=None, request_timeout=None,
    server_port=8000, telemetry_enabled=True,
) -> Sandbox: ...

ephemeral() accepts the same parameters plus keep_pool=False.

Fleet selection and constraints#

pool= explicitly selects Fleet. It rejects an image, resource overrides, replicas != 1, local=True, an explicit runtime or API key, a nondefault region, request_timeout, or a nondefault server_port. Configure the pool through Pool.apply() or Pool.reconcile() instead.

For image-based calls, Fleet is selected when Fleet authentication is configured, no per-call api_key is supplied, the image resolves to a Fleet registry image, and neither local=True nor a runtime is supplied. Persistent Fleet creation requires an explicitly named pool: Sandbox.create(image) rejects this path. Sandbox.ephemeral(image) can create a disposable pool and claim. Fleet image-based provisioning rejects disk_gb, a nondefault region, and request_timeout.

The presence of an image constructor does not establish backend support. See the Fleet image constraints.

Lifecycle and ownership#

Fleet pool configuration and claim lifetime are separate resources.

destroy() is the local/legacy transport cleanup method. It does not release a claim obtained through Pool.claim(); use close() for that claim. Local and legacy ephemeral() call destroy() on exit, or suspend when the instance has snapshots. Cleanup can fail; it is not a guarantee of deletion.

Reconnection and renewal#

These methods apply to Fleet claim-backed instances:

The serialized shape is:

{
    "version": 1,
    "provider": "fleet",
    "namespace": "example-pool",
    "pool": "example-pool",
    "claim": "example-claim",
    "service": "server",
}

Sandbox.from_dict() requires the namespace to match the pool. It still requires Fleet credentials and a claim that exists. Serialization, renewal, and close() raise NotImplementedError on instances without a Fleet claim handle.

Other Sandbox methods#

Sandbox.connect() supports await and async with; context exit disconnects. For durable Fleet claim reconnection, use the serialized reference above.

def connect(
    name: str, *, api_key=None, local=False, ws_url=None, http_url=None,
    container_name=None, cpu=None, memory_mb=None, disk_gb=None,
    region="us-east-1", telemetry_enabled=True,
): ...

The lifecycle class methods accept keyword-only local=False, api_key=None:

These name-based operations are backend-specific. For an explicitly acquired Fleet claim, use close() to release it and Pool.delete() to remove its pool.

The connected instance also provides these methods:

SandboxInfo has required string fields name, status, and source, plus optional string fields os_type, host, vnc_url, api_url, and created_at.

Interfaces and Localhost#

Sandbox exposes shell, files, mouse, keyboard, screen, clipboard, tunnel, terminal, window, mobile, services, and apps. Availability depends on the connected transport. exposed_ports maps local guest ports to host ports; Fleet publishes named services instead.

Localhost.connect() supports await and async with and controls the host through cua_auto, without a sandbox. Context exit disconnects. Its interfaces include screen, mouse, keyboard, clipboard, shell, window, and terminal. See Sandbox interfaces.