Sandbox Class API Reference — Cua Python SDK

The cua-sandbox package gives you programmatic control over ephemeral and persistent sandboxed computer environments — virtual machines and containers running Linux, macOS, Windows, and Android — from Python. The same API works against the Cua cloud and against a local runtime (Docker, Lume, or QEMU), controlled by a single local=True flag.

Installation

Full SDK
Sandbox only

pip install cua

pip install cua-sandbox

Field	Value
Package	`cua-sandbox`
Import name	`cua`
Python versions	3.11, 3.12, 3.13

Top-level exports

from cua import Sandbox, Image, Localhost, SandboxInfo, configure, login, whoami

Export	Description
`Sandbox`	VM or container control class
`Image`	Image builder class (see Image reference)
`Localhost`	Direct host control — no sandbox required
`SandboxInfo`	Sandbox metadata dataclass
`configure()`	Global SDK configuration helper
`login()`	Browser-based Cua authentication
`whoami()`	Fetch authenticated user info

Environment variables

Variable	Description
`CUA_API_KEY`	Cua cloud API key. Passed directly or read automatically by all methods.

Sandbox class

Sandbox is the main entry point. It exposes interfaces (shell, mouse, keyboard, screen, clipboard, tunnel, terminal, window, mobile) for controlling a running VM or container.

When local=False (the default), sandboxes are created in the Cua cloud using the CUA_API_KEY. Pass local=True to use a local Docker, Lume (macOS), or QEMU runtime — no API key required.

`Sandbox.ephemeral`

Async context manager. Provisions a sandbox, yields it, then destroys it automatically on exit — ideal for one-shot tasks.

async def ephemeral(
    cls,
    image: Image,
    name: str | None = None,
    api_key: str | None = None,
    local: bool = False,
    runtime=None,
    cpu: int | None = None,
    memory_mb: int | None = None,
    disk_gb: int | None = None,
    region: str = 'us-east-1',
) -> AsyncIterator[Sandbox]

image

Image

required

The image to run. Build one with Image.linux(), Image.macos(), etc.

name

str | None

default:"None"

Optional human-readable name for the sandbox.

api_key

str | None

default:"None"

Cua API key. Reads CUA_API_KEY from the environment if None.

local

bool

default:"False"

Use a local runtime (Docker, Lume, QEMU) instead of the Cua cloud.

runtime

Runtime | None

default:"None"

Explicit runtime backend. Usually inferred from image.kind and local.

cpu

int | None

default:"None"

CPU core count override (cloud only).

memory_mb

int | None

default:"None"

Memory in megabytes override (cloud only).

disk_gb

int | None

default:"None"

Disk size in gigabytes override (cloud only).

region

str

default:"'us-east-1'"

Cloud region to provision in.

import asyncio
from cua import Sandbox, Image

async def main():
    async with Sandbox.ephemeral(Image.linux()) as sb:
        result = await sb.shell.run('uname -a')
        print(result.stdout)

asyncio.run(main())

`Sandbox.create`

Provisions a persistent sandbox. It keeps running after your script exits. Use Sandbox.connect() to reconnect to it later.

async def create(
    cls,
    image: Image,
    name: str | None = None,
    api_key: str | None = None,
    local: bool = False,
    runtime=None,
    cpu: int | None = None,
    memory_mb: int | None = None,
    disk_gb: int | None = None,
    region: str = 'us-east-1',
) -> Sandbox

All parameters are identical to Sandbox.ephemeral.

sb = await Sandbox.create(Image.linux(), name='my-dev-box', local=True)
await sb.shell.run('apt-get install -y htop')
await sb.disconnect()   # Close transport; sandbox stays running

`Sandbox.connect`

Connects to an existing sandbox by name. Supports both await (plain connection) and async with (auto-disconnects on exit, sandbox keeps running).

def connect(
    cls,
    name: str,
    api_key: str | None = None,
    local: bool = False,
    ws_url: str | None = None,
    http_url: str | None = None,
    container_name: str | None = None,
    cpu: int | None = None,
    memory_mb: int | None = None,
    disk_gb: int | None = None,
    region: str = 'us-east-1',
) -> _ConnectResult

name

str

required

Name of the sandbox to connect to.

api_key

str | None

default:"None"

Cua API key. Reads CUA_API_KEY if None.

local

bool

default:"False"

Connect to a locally running sandbox.

ws_url

str | None

default:"None"

Override the WebSocket URL for the transport connection.

http_url

str | None

default:"None"

Override the HTTP URL for the transport connection.

container_name

str | None

default:"None"

Override the container name (local Docker runtimes).

region

str

default:"'us-east-1'"

Cloud region.

# Plain await
sb = await Sandbox.connect('my-dev-box', local=True)
await sb.shell.run('htop -b -n 1')
await sb.disconnect()

# Context manager — auto-disconnect, sandbox keeps running
async with Sandbox.connect('my-dev-box', local=True) as sb:
    await sb.shell.run('echo still running')

Instance methods

Lifecycle

disconnect

async () → None

Drop the transport connection. The sandbox keeps running. Use this when you want to release resources without destroying the sandbox.

destroy

async () → None

Disconnect and permanently delete the sandbox. All state is lost.

Screenshots

screenshot

async (text=None, format='png', quality=95) → bytes

Capture the sandbox display. format is 'png' or 'jpeg'. quality (1–95) applies only to JPEG. text is an optional annotation overlaid on the image.

screenshot_base64

async (text=None, format='png', quality=95) → str

Same as screenshot() but returns a base64-encoded string — suitable for embedding in JSON or passing to LLM vision APIs.

# Top-level convenience — delegates to sb.screen
img_bytes = await sb.screenshot()
img_b64   = await sb.screenshot_base64(format='jpeg', quality=80)

Display and environment

get_environment

async () → str

Returns the OS type: 'linux', 'mac', 'windows', or 'browser'.

get_display_url

async (share=False) → str

URL to view the sandbox display in a browser. Pass share=True for a public shareable link (cloud only).

get_dimensions

async () → tuple[int, int]

Screen width and height in pixels as (width, height).

Class methods (sandbox management)

These methods do not require an active sandbox connection.

Method	Signature	Description
`list`	`async list(local=False, api_key=None) → list[SandboxInfo]`	List all running and suspended sandboxes.
`get_info`	`async get_info(name, local=False, api_key=None) → SandboxInfo`	Fetch metadata for a specific sandbox.
`suspend`	`async suspend(name, local=False, api_key=None) → None`	Suspend a sandbox (save state).
`resume`	`async resume(name, local=False, api_key=None) → Sandbox`	Resume a suspended sandbox. Returns a connected `Sandbox`.
`restart`	`async restart(name, local=False, api_key=None) → Sandbox`	Suspend then resume. Returns a connected `Sandbox`.
`delete`	`async delete(name, local=False, api_key=None) → None`	Permanently delete a sandbox.

Cloud vs local suspend: On cloud, suspend calls POST /v1/vms/{name}/stop. On local QEMU, it takes a QMP snapshot. On local Docker, it pauses the container. On local Lume (macOS), it stops the VM.

Sandbox attributes

Attribute	Type	Description
`name`	`str \| None`	Sandbox name.
`shell`	`Shell`	Run shell commands — see Interfaces.
`mouse`	`Mouse`	Mouse control — see Interfaces.
`keyboard`	`Keyboard`	Keyboard input — see Interfaces.
`screen`	`Screen`	Screenshots and dimensions — see Interfaces.
`clipboard`	`Clipboard`	Clipboard read/write — see Interfaces.
`tunnel`	`Tunnel`	Port forwarding — see Interfaces.
`terminal`	`Terminal`	PTY sessions — see Interfaces.
`window`	`Window`	Window management — see Interfaces.
`mobile`	`Mobile`	Android touch and hardware keys — see Interfaces.

SandboxInfo

Returned by Sandbox.list() and Sandbox.get_info().

name

str

Sandbox name.

status

str

Current status: 'running', 'stopped', 'provisioning', etc.

source

str

Runtime source identifier.

os_type

str | None

OS type: 'linux', 'macos', 'windows', 'android', or None.

host

str | None

Host address for the sandbox.

vnc_url

str | None

VNC URL if available.

api_url

str | None

API URL for direct communication.

created_at

str | None

ISO 8601 creation timestamp.

SDK configuration

`configure`

def configure(api_key: str | None = None, base_url: str | None = None) -> None

Set global SDK configuration. Equivalent to setting CUA_API_KEY in the environment.

api_key

str | None

default:"None"

Cua API key.

base_url

str | None

default:"None"

Override the Cua API base URL.

def login(base_url: str | None = None) -> None

Open the Cua login page in the browser and store credentials in ~/.cua/credentials (Clerk auth flow).

`whoami`

def whoami(api_key: str | None = None) -> Dict[str, Any]

Return a dict with authenticated user information (id, email, etc.) from the Cua API.

Localhost

Localhost provides the same interface as Sandbox but controls the host machine directly via cua_auto — no sandbox is created. Useful for local automation without spinning up a VM.

from cua import Localhost

# Plain await
host = await Localhost.connect()
await host.shell.run('echo hello from host')
await host.disconnect()

# Context manager
async with Localhost.connect() as host:
    img = await host.screenshot()

Localhost exposes: screen, mouse, keyboard, clipboard, shell, window, terminal. It does not expose tunnel or mobile. Methods screenshot, screenshot_base64, get_environment, get_dimensions, and disconnect have the same signatures as on Sandbox.

Cua Driver

Sandbox SDK

Lume

Cua Bench

Sandbox Class API Reference — Cua Python SDK

Installation

Top-level exports

Environment variables

Sandbox class

`Sandbox.ephemeral`

`Sandbox.create`

`Sandbox.connect`

Instance methods

Lifecycle

Screenshots

Display and environment

Class methods (sandbox management)

Sandbox attributes

SandboxInfo

SDK configuration

`configure`

`whoami`

Localhost

Build docs developers (and LLMs) love

Cua Driver

Sandbox SDK

Lume

Cua Bench

Documentation Index

​Installation

​Top-level exports

​Environment variables

​Sandbox class

​Sandbox.ephemeral

​Sandbox.create

​Sandbox.connect

​Instance methods

​Lifecycle

​Screenshots

​Display and environment

​Class methods (sandbox management)

​Sandbox attributes

​SandboxInfo

​SDK configuration

​configure

​login

​whoami

​Localhost

Build docs developers (and LLMs) love

Installation

Top-level exports

Environment variables

Sandbox class

`Sandbox.ephemeral`

`Sandbox.create`

`Sandbox.connect`

Instance methods

Lifecycle

Screenshots

Display and environment

Class methods (sandbox management)

Sandbox attributes

SandboxInfo

SDK configuration

`configure`

`login`

`whoami`

Localhost