Image Class API Reference — Cua Sandbox

The Image class is an immutable, chainable image specification used to configure sandbox environments in Cua. Each builder method returns a new Image instance — the original is never mutated. This makes it safe to share base images across multiple sandboxes and to compose configurations freely. Import Image from cua:

from cua import Image

Constructors

Class methods that create a new Image for a specific operating system or source.

`Image.linux`

Creates a Linux image. Defaults to a QEMU VM running Ubuntu 24.04. Pass kind='container' to use Docker with an XFCE desktop instead.

distro

str

default:"'ubuntu'"

Linux distribution name, e.g. 'ubuntu' or 'debian'.

version

str

default:"'24.04'"

Distribution version string, e.g. '24.04' or '22.04'.

kind

str

default:"'vm'"

Runtime type. 'vm' for QEMU, 'container' for Docker/XFCE.

image = Image.linux()                          # Ubuntu 24.04 VM
image = Image.linux(distro='ubuntu', version='22.04', kind='container')

Returns: Image

`Image.macos`

Creates a macOS image using Apple Virtualization or the Lume runtime. Always a VM. Supported version strings: '15' / 'sequoia', '26' / 'tahoe'.

version

str

default:"'26'"

macOS version string or friendly name, e.g. '26' or 'tahoe'.

kind

str

default:"'vm'"

Always 'vm'. macOS sandboxes cannot run as containers.

image = Image.macos()                          # macOS Tahoe VM
image = Image.macos(version='15')              # macOS Sequoia VM

Returns: Image

`Image.windows`

Creates a Windows image. Always a VM (QEMU or Hyper-V).

version

str

default:"'11'"

Windows version string, e.g. '11'.

kind

str

default:"'vm'"

Always 'vm'.

image = Image.windows()                        # Windows 11 VM

Returns: Image

`Image.android`

Creates an Android image. Always a VM (QEMU emulator).

version

str

default:"'14'"

Android version string, e.g. '14'.

kind

str

default:"'vm'"

Always 'vm'.

image = Image.android()                        # Android 14 VM
image = Image.android(version='13')

Returns: Image

`Image.from_registry`

Creates an image from an OCI registry reference. The kind is resolved automatically after the image is pulled.

ref

str

required

OCI registry reference, e.g. 'ghcr.io/trycua/macos-tahoe-cua:latest' or 'ubuntu:22.04'.

image = Image.from_registry('ghcr.io/trycua/macos-tahoe-cua:latest')

Returns: Image

`Image.from_file`

Creates an image from a local disk file, ISO, or HTTP/HTTPS URL. Supported formats: qcow2, vhdx, raw, img, iso. Downloaded images are cached in ~/.cua/cua-sandbox/image-cache/. Zip archives are extracted automatically. For ISOs, a qcow2 disk is created and the ISO is attached as a CD-ROM.

path

str

required

Local filesystem path or an http/https URL pointing to the image file.

os_type

str

default:"'windows'"

Target operating system: 'linux', 'windows', 'macos', or 'android'.

kind

str

default:"'vm'"

Runtime type: 'vm' or 'container'.

agent_type

str | None

default:"None"

Optional agent type. Use 'osworld' to enable the OSWorld Flask server inside the VM.

image = Image.from_file('/path/to/disk.qcow2', os_type='linux')
image = Image.from_file('https://example.com/win11.vhdx', os_type='windows')

Returns: Image

`Image.from_dict`

Reconstructs an Image from a serialized spec dictionary, such as the output of Image.to_dict(). Useful for persisting and restoring image configurations.

data

Dict[str, Any]

required

A dictionary previously produced by Image.to_dict().

spec = image.to_dict()
restored = Image.from_dict(spec)

Returns: Image

Builder Methods

Builder methods return a new Image with the additional layer applied. They can be chained in any order.

Package installation

.apt_install(*packages)

str

Install one or more packages via apt. Linux only.

image = Image.linux().apt_install('curl', 'git', 'python3')

.brew_install(*packages)

str

Install one or more packages via Homebrew. macOS only.

image = Image.macos().brew_install('wget', 'jq')

.choco_install(*packages)

str

Install one or more packages via Chocolatey. Windows only.

image = Image.windows().choco_install('googlechrome', 'vscode')

.winget_install(*packages)

str

Install one or more packages via winget. Windows only.

image = Image.windows().winget_install('Microsoft.VisualStudioCode')

.apk_install(*apk_paths)

str

Install one or more APK files via adb. Android only.

image = Image.android().apk_install('./MyApp.apk')

.pip_install(*packages)

str

Install one or more Python packages via pip. Works across all OS types.

image = Image.linux().pip_install('requests', 'playwright')

.uv_install(*packages)

str

Install one or more Python packages via uv add into the cua-server project. Faster than pip_install.

image = Image.linux().uv_install('httpx', 'pydantic')

Android PWA installation

.pwa_install() builds an APK from a Progressive Web App manifest URL and installs it via adb. Android only.

manifest_url

str

required

Full URL to the PWA’s manifest.json.

package_name

str | None

default:"None"

Android package ID (e.g. 'com.example.myapp'). Derived from the manifest hostname if omitted.

keystore

str | None

default:"None"

Path to a .keystore or .jks file. Auto-generated and cached if omitted.

keystore_alias

str

default:"'android'"

Key alias inside the keystore.

keystore_password

str

default:"'android'"

Password for both the keystore and the key.

builder

str

default:"'pwa2apk'"

APK builder backend. 'pwa2apk' produces a lightweight WebView APK. 'bubblewrap' builds a Trusted Web Activity (TWA) — requires the SHA-256 fingerprint to match the server’s /.well-known/assetlinks.json.

push_timeout

float | None

default:"None"

Timeout in seconds for the adb install push step.

bubblewrap TWAs require Node.js ≥ 18 and Java ≤ 21 on PATH. Gradle does not support Java 22+.

image = (
    Image.android()
    .pwa_install('https://app.example.com/manifest.json', builder='pwa2apk')
)

Returns: Image

Environment and files

.env(**variables)

str

Set environment variables that will be present in the sandbox. Values are stored in the spec in plaintext — do not use for secrets.

image = Image.linux().env(NODE_ENV='production', PORT='3000')

.copy(src, dst)

str

Copy a local file into the image at the specified destination path.

image = Image.linux().copy('./config.yaml', '/etc/myapp/config.yaml')

.run(command)

str

Execute an arbitrary shell command during image setup.

image = Image.linux().run('curl -fsSL https://deb.nodesource.com/setup_20.x | bash -')

.expose(port)

int

Mark a TCP port the sandbox will serve on. Works in combination with sb.tunnel.forward() for port forwarding.

image = Image.linux().expose(8080)

Chaining example

Builder calls are fully composable:

image = (
    Image.linux(distro='ubuntu', version='24.04')
    .apt_install('curl', 'git')
    .pip_install('requests', 'playwright')
    .env(MY_VAR='hello')
    .run('playwright install --with-deps chromium')
    .expose(8080)
)

Serialization

`Image.to_dict`

Serializes the Image to a plain dictionary suitable for JSON or the Cua cloud API.

spec = image.to_dict()
# Example output:
# {
#     'os_type': 'linux',
#     'distro': 'ubuntu',
#     'version': '24.04',
#     'kind': 'vm',
#     'layers': [
#         {'type': 'apt_install', 'packages': ['curl']},
#         {'type': 'pip_install', 'packages': ['requests']},
#     ]
# }

Returns: Dict[str, Any]

`Image.to_cloud_init`

Generates a cloud-init user-data script from the image layers. Useful for provisioning VMs directly. Returns: str

Attributes

These read-only attributes describe the resolved image specification.

os_type

str

The operating system family: 'linux', 'macos', 'windows', or 'android'.

distro

str

The distribution name (e.g. 'ubuntu'). Empty string for non-Linux images.

version

str

The version string (e.g. '24.04', '26', '11', '14').

kind

str | None

The runtime type: 'container' or 'vm'. May be None before the image is pulled from a registry.

Cua Driver

Sandbox SDK

Lume

Cua Bench

Image Class API Reference — Cua Sandbox

Constructors

`Image.linux`

`Image.macos`

`Image.windows`

`Image.android`

`Image.from_registry`

`Image.from_file`

`Image.from_dict`

Builder Methods

Package installation

Android PWA installation

Environment and files

Chaining example

Serialization

`Image.to_dict`

`Image.to_cloud_init`

Attributes

Build docs developers (and LLMs) love

Cua Driver

Sandbox SDK

Lume

Cua Bench

Documentation Index

​Constructors

​Image.linux

​Image.macos

​Image.windows

​Image.android

​Image.from_registry

​Image.from_file

​Image.from_dict

​Builder Methods

​Package installation

​Android PWA installation

​Environment and files

​Chaining example

​Serialization

​Image.to_dict

​Image.to_cloud_init

​Attributes

Build docs developers (and LLMs) love

Constructors

`Image.linux`

`Image.macos`

`Image.windows`

`Image.android`

`Image.from_registry`

`Image.from_file`

`Image.from_dict`

Builder Methods

Package installation

Android PWA installation

Environment and files

Chaining example

Serialization

`Image.to_dict`

`Image.to_cloud_init`

Attributes