Image
Canonical images, image references, build layers and registry credentials.
Canonical images, image references, build layers and registry credentials.
Images are references: the functions here resolve and normalise them without pulling anything. ImageBuild layers and a RegistrySecret go into SandboxCreateOptions.
Python programs usually use the high-level API instead: cua_sandbox.Image.
canonical_image names one public repository per OS; CUA_IMAGE_LINUX, CUA_IMAGE_WINDOWS and CUA_IMAGE_MACOS override it. The image catalog details lists each image's variants, and runtime support where each one runs.
canonical_image#The canonical image for os (linux, windows, macos) and
version (None = default: ghcr.io/trycua/linux:24.04,
ghcr.io/trycua/windows:2022, ghcr.io/trycua/macos:26; macOS accepts
tahoe/sequoia). CUA_IMAGE_<OS> overrides the default version.
def canonical_image(os: str, version: Optional[str]) -> str| Parameter | Type | Default |
|---|---|---|
os | String | required |
version | Option<String> | required |
Returns String · Raises CuaError
Example
import cua
print([cua.canonical_image(os, None) for os in ("linux", "windows", "macos")])
# ['ghcr.io/trycua/linux:24.04', 'ghcr.io/trycua/windows:2022', 'ghcr.io/trycua/macos:26']image_alias#The canonical image a CLI alias (linux, windows, macos[:version],
bare ubuntu) names, or None for a plain reference (ubuntu:24.04
is Docker Hub's image).
def image_alias(name: str) -> Optional[str]| Parameter | Type | Default |
|---|---|---|
name | String | required |
Returns Option<String>
Example
import cua
print([cua.image_alias("macos:sequoia"), cua.image_alias("ubuntu:24.04")])
# ['ghcr.io/trycua/macos:15', None]normalize_image#Normalises a reference like the docker CLI (python is
docker.io/library/python:latest). No registry read.
def normalize_image(reference: str) -> str| Parameter | Type | Default |
|---|---|---|
reference | String | required |
Returns String · Raises CuaError
Example
import cua
print([cua.normalize_image("python:3.12-slim"), cua.normalize_image("ghcr.io/trycua/linux:24.04")])
# ['docker.io/library/python:3.12-slim', 'ghcr.io/trycua/linux:24.04']resolve_image#Resolves reference for backend (auto, local, fleet,
container/docker/gvisor, vm/qemu/kubevirt, lume)
on arch (amd64/arm64; None = this host, or amd64 for fleet).
reference is literal (ubuntu:24.04 is Docker Hub's image): no
alias applies here; use image_alias or canonical_image first.
Raises NotFound (no such image: e.g. a tag only the local engine has),
Unauthenticated (the registry refused the credentials), Unsupported
(no variant the backend runs, e.g. a macOS image on Fleet).
Blocks while the registry is read (cached for five minutes).
def resolve_image(reference: str, backend: str, arch: Optional[str]) -> ResolvedImage| Parameter | Type | Default |
|---|---|---|
reference | String | required |
backend | String | required |
arch | Option<String> | required |
Returns ResolvedImage · Raises CuaError (NotFound, Unauthenticated, Unsupported)
resolve_image_with_secret#resolve_image for a private image: secret joins the head of the
registry auth chain (it is read in this process and never cached or
logged). Same errors as resolve_image.
def resolve_image_with_secret(reference: str, backend: str, arch: Optional[str], secret: RegistrySecret) -> ResolvedImage| Parameter | Type | Default |
|---|---|---|
reference | String | required |
backend | String | required |
arch | Option<String> | required |
secret | RegistrySecret | required |
Returns ResolvedImage · Raises CuaError
ResolvedImage record#A reference resolved for a backend.
Returned by resolve_image, resolve_image_with_secret.
| Field | Type | Default | Description |
|---|---|---|---|
reference | String | The reference as given, normalised (docker.io/library/python:3.12-slim). | |
variant_ref / variantRef | String | The chosen variant by tag (the input or its sibling). Lume pulls this. | |
pinned_ref / pinnedRef | String | registry/repo@sha256:… of the chosen variant. | |
digest | String | The digest in pinned_ref. | |
variant | String | rootfs, containerdisk or lume. | |
arch | Option<String> | Architecture to run (amd64/arm64). | |
architectures | Vec<String> | Architectures the variant offers. | |
emulated | bool | Whether arch differs from the requested one (runs emulated). | |
os | String | Guest OS: linux, windows or macos. | |
spacesd | Option<bool> | Whether the image carries cua-spacesd (None: cannot tell). |
ImageInfo record#The image a sandbox runs, as resolved and pinned at create time.
Returned by Fleet.pool_image_info, Sandbox.image_info.
| Field | Type | Default | Description |
|---|---|---|---|
reference | String | The reference as requested, normalised (docker.io/library/python:3.12-slim). | |
pinned_ref / pinnedRef | String | registry/repo@sha256:... of the variant that runs. | |
digest | String | The digest in pinned_ref. | |
variant | String | rootfs, containerdisk or lume. | |
arch | Option<String> | Architecture that runs (amd64/arm64), when known. | |
os | String | Guest OS: linux, windows or macos. | |
emulated | bool | Whether it runs emulated (no build for the requested architecture). | |
spacesd | Option<bool> | None | Whether the image carries cua-spacesd (ai.cua.spacesd label or a published 3211); None when it does not say. |
ImageBuild record#Image layers built on top of a sandbox's image. Cloud: a remote build
(Fleet images API). Local: a build into the container engine (container
images only; VM images take no layers here). Both are cached by the same
content hash (cua-b-<hash>), so an identical spec never rebuilds.
| Field | Type | Default | Description |
|---|---|---|---|
layers | Vec<ImageLayer> | [] | Steps, in order. |
env | HashMap<String, String> | [:] | Image environment. |
ports | Vec<u16> | [] | Ports the image exposes. |
files | Vec<BuildFile> | [] | Local files copied in. |
timeout_ms / timeoutMs | Option<u32> | None | Build budget (default one hour). |
ImageLayer enum#One image build step (as in images.cua.ai/v1alpha1 recipes).
ImageLayer.APT_INSTALL(packages: List[str])
ImageLayer.PIP_INSTALL(packages: List[str])
ImageLayer.UV_INSTALL(packages: List[str])
ImageLayer.RUN(command: str)
ImageLayer.APP_INSTALL(app_id: str)| Variant | Description |
|---|---|
AptInstall | apt-get install. Fields: packages: Vec<String> |
PipInstall | pip install. Fields: packages: Vec<String> |
UvInstall | uv pip install. Fields: packages: Vec<String> |
Run | A shell command. Fields: command: String |
AppInstall | An app from the cua catalog (VM images only). Fields: app_id: String |
BuildFile record#A local file copied into a built image.
| Field | Type | Default | Description |
|---|---|---|---|
source | String | Local path. | |
destination | String | Absolute path in the image. |
RegistrySecret enum#Credentials for a private registry image. Local sandboxes pull with them; cloud sandboxes store them as the sandbox's registry pull Secret. Never logged or persisted.
RegistrySecret.BASIC(username: str, password: str, registry: Optional[str])
RegistrySecret.FROM_ENV(username_var: str, password_var: str, registry: Optional[str])
RegistrySecret.AWS_ECR(region: Optional[str])| Variant | Description |
|---|---|
Basic | A user name and password (or access token). Fields: username: String, password: String, registry: Option<String> |
FromEnv | Read from environment variables of this process at create time. Fields: username_var: String, password_var: String, registry: Option<String> |
AwsEcr | A private Amazon ECR image: a login token from the AWS CLI (aws ecr get-login-password) with the caller's AWS credentials. Fields: region: Option<String> |
canonical_image_tier#The canonical image for os, version and tier: slim (the minimum
that passes cua-spacesd doctor --strict; CI and benchmarks use it),
full or None (the default, with dev tooling) or, on macOS, xcode
/ xcode-<X.Y> (full plus one pinned Xcode). The tag is
<os-version>[-<tier>] (ghcr.io/trycua/linux:24.04-slim); the
resolver finds its -disk sibling. CUA_IMAGE_<OS> overrides only the
default full image. Raises ImageNotPublished for a tier CI has not
published yet, InvalidArgument for an unknown tier or xcode
outside macOS.
def canonical_image_tier(os: str, version: Optional[str], tier: Optional[str]) -> str| Parameter | Type | Default |
|---|---|---|
os | String | required |
version | Option<String> | required |
tier | Option<String> | required |
Returns String · Raises CuaError (ImageNotPublished, InvalidArgument)
omarchy_image#The Omarchy image, ghcr.io/trycua/omarchy:<channel> (default edge;
also rc, stable): Omarchy (Arch Linux, Hyprland) with cua-spacesd,
as an amd64 VM (QEMU locally, KubeVirt in the cloud; emulated on arm64
hosts). Raises ImageNotPublished until CI publishes the channel; pass
the reference explicitly to use it before then.
def omarchy_image(channel: Optional[str]) -> str| Parameter | Type | Default |
|---|---|---|
channel | Option<String> | required |
Returns String · Raises CuaError (ImageNotPublished)