Image

Image is an immutable, chainable description of what a sandbox boots. Builder methods return a new Image.

Builder methods add layers and return a new Image. Locally, a container image is built into your container engine before boot; in the cloud the same layers run as a remote build. Both are cached by content. Layers a build cannot run (brew_install, choco_install, ...) are applied after boot through cua-spacesd, so they need an image that runs it.

Image builder#

Image#

class Image
 
Image(os_type: str, distro: str, version: str, kind: Optional[str] = None)

Immutable, chainable image specification.

Each mutation method returns a new Image instance so that builders can be forked at any point.

Example

from cua_sandbox import Image
 
img = Image.linux().apt_install("curl").pip_install("requests").env(DEBUG="1").expose(8080)
print(img.to_dict())
# {'os_type': 'linux', 'distro': 'ubuntu', 'version': '24.04', 'kind': None,
#  'layers': [{'type': 'apt_install', 'packages': ['curl']},
#             {'type': 'pip_install', 'packages': ['requests']}],
#  'env': {'DEBUG': '1'}, 'ports': [8080]}

Image.linux#

@classmethod
def linux(
    distro: str = 'ubuntu',
    version: str = '24.04',
    kind: Optional[str] = None,
    tier: Optional[str] = None,
) -> Image

Linux: the canonical ghcr.io/trycua/linux:<version> image.

kind=None (or "auto") runs what the image is (the rootfs: a gVisor container locally and in the cloud); kind="vm" its -disk containerDisk (QEMU locally, KubeVirt in the cloud); kind="container" the rootfs. Sandbox.create(kind=...) overrides it.

tier: "full" (the default: dev tooling) or "slim" (24.04-slim: cua-spacesd and Chromium only; what CI runs). A tier CI has not published yet raises CuaError.ImageNotPublished; use Image.from_registry(ref) to run it anyway.

Image.macos#

@classmethod
def macos(version: str = '26', kind: str = 'vm', tier: Optional[str] = None) -> Image

macOS: the canonical ghcr.io/trycua/macos:<version> image (Lume locally).

Supported versions: "15" / "sequoia", "26" / "tahoe". tier: "full" (the default), "slim" or "xcode" / "xcode-<X.Y>" (full plus one pinned Xcode); unpublished tiers raise CuaError.ImageNotPublished.

Image.windows#

@classmethod
def windows(
    version: str = '2022',
    kind: str = 'vm',
    tier: Optional[str] = None,
) -> Image

Windows: the canonical ghcr.io/trycua/windows:2022 containerDisk.

Other versions, including "11", have no canonical image: on Fleet they are unsupported, and locally they are installed from a downloaded evaluation ISO. tier="slim" names 2022-slim once published.

Image.omarchy#

@classmethod
def omarchy(channel: Optional[str] = None) -> Image

Omarchy (Arch Linux, Hyprland) with cua-spacesd: ghcr.io/trycua/omarchy:edge (or "rc"/"stable").

An amd64 VM: QEMU locally (emulated on arm64 hosts, so slow there), KubeVirt in the cloud. Until CI publishes it this raises CuaError.ImageNotPublished; use Image.from_registry("ghcr.io/trycua/omarchy:edge", kind="vm") to run it anyway.

Image.android#

@classmethod
def android(version: str = '14', kind: str = 'vm') -> Image

Android image. Always a VM (QEMU emulator).

Image.from_registry#

@classmethod
def from_registry(
    ref: str,
    *,
    os_type: str = 'linux',
    kind: Optional[str] = None,
    agent_type: Optional[str] = None,
    secret: Optional[Any] = None,
) -> Image

Create an image from a registry reference.

secret (a cua_sandbox.RegistrySecret) pulls a private image, the same way locally (the pull) and in the cloud (a registry pull secret for the sandbox). It is never logged or saved.

os_type selects the firmware: Windows guest disks are built UEFI-only, so a Windows containerDisk pulled from a registry must say so or it is handed BIOS and will not boot. kind is resolved after pull when omitted. agent_type names the guest control server the disk already runs, the same hint as from_file: "osworld" selects the OSWorld Flask server on port 5000 instead of the computer-server on 8000, both for local QEMU and for Fleet pools.

Image.from_file#

@classmethod
def from_file(
    path: str,
    *,
    os_type: str = 'windows',
    kind: str = 'vm',
    agent_type: Optional[str] = None,
) -> Image

Create an image from a local disk, ISO file, or URL.

Supported formats: qcow2, vhdx, raw, img, iso. URLs (http/https) are downloaded automatically. Zip files are extracted. For ISOs, the runtime will create a qcow2 disk and attach the ISO as a CD-ROM for installation/boot.

Image.from_dict#

@classmethod
def from_dict(data: Dict[str, Any]) -> Image

Reconstruct an Image from a serialized spec dict.

Example

from cua_sandbox import Image
 
base = Image.linux().apt_install("git")
dev = base.pip_install("rich")
same = Image.from_dict(dev.to_dict()).to_dict() == dev.to_dict()
print([same, len(base.to_dict()["layers"]), len(dev.to_dict()["layers"])])
# [True, 1, 2]

Image.apt_install#

def apt_install(*packages: str) -> Image

Install packages via apt (Linux only).

Image.brew_install#

def brew_install(*packages: str) -> Image

Install packages via Homebrew (macOS).

Image.choco_install#

def choco_install(*packages: str) -> Image

Install packages via Chocolatey (Windows).

Image.winget_install#

def winget_install(*packages: str) -> Image

Install packages via winget (Windows).

Image.apk_install#

def apk_install(*apk_paths: str) -> Image

Install APK files via adb (Android only).

Image.pwa_install#

def pwa_install(
    manifest_url: str,
    package_name: Optional[str] = None,
    keystore: Optional[str] = None,
    keystore_alias: str = 'android',
    keystore_password: str = 'android',
    builder: str = 'pwa2apk',
    push_timeout: Optional[float] = None,
) -> 'Image'

Build an APK from a PWA manifest URL and install it (Android only).

Two builder backends are supported:

• "pwa2apk" (default): generates a lightweight WebView-based APK. No Chrome dependency, no "Running in Chrome" banner, no Digital Asset Links needed. ~10 KB APK.
• "bubblewrap": generates a Chrome Trusted Web Activity (TWA) APK. Requires Chrome on the device and a matching /.well-known/assetlinks.json on the server. Shows a mandatory "Running in Chrome" privacy disclosure on every launch.

Image.uv_install#

def uv_install(*packages: str) -> Image

Install Python packages via uv add into the cua-server project.

Image.pip_install#

def pip_install(*packages: str) -> Image

Install Python packages via pip.

Image.app_install#

def app_install(app_id: str) -> Image

Install an app from the cua-sandbox-apps catalog.

Requires cua-sandbox-apps to be installed. The app's install script for this image's OS is executed as a build layer.

Image.run#

def run(command: str) -> Image

Run a shell command during image build.

Image.env#

def env(**variables: str) -> Image

Set environment variables.

Image.copy#

def copy(src: str, dst: str) -> Image

Copy a file into the image.

Image.expose#

def expose(port: int) -> Image

Expose a port.

Image.to_build_recipe#

def to_build_recipe(
    *,
    name: str,
    namespace: str,
    tags: Mapping[str, str] | None = None,
    timeout_seconds: int | None = None,
    disk_size: str | None = None,
    file_references: Mapping[str, ImageFileReference] | None = None,
) -> Dict[str, Any]

Return a CRD-validated Image custom-resource manifest.

Image.to_dict#

def to_dict() -> Dict[str, Any]

Serialize to a plain dict suitable for JSON or cloud API.

Image.to_cloud_init#

def to_cloud_init() -> str

Generate a cloud-init user-data script from the image layers.

Image.local_support#

def local_support()

Check whether this image can run locally on the current host.

Returns a cua_sandbox.runtime.compat.RuntimeSupport describing:

• supported : runtime is available or auto-installable on this OS
• hw_accel : hardware acceleration (HVF / KVM / Hyper-V) is available
• runtime_installed: runtime binary found right now (no install needed)
• auto_installable: SDK can install the runtime automatically
• reason : human-readable explanation

In tests, use the bundled helper instead of checking manually:

from cua_sandbox.runtime.compat import skip_if_unsupported
 
async def test_something():
    skip_if_unsupported(Image.macos())
    async with Sandbox.ephemeral(Image.macos(), local=True) as sb:
        ...

ImageInfo#

class ImageInfo
 
ImageInfo(
    reference: str,
    pinned_ref: str,
    digest: str,
    variant: str,
    arch: Optional[str],
    os: str,
    emulated: bool,
)

The image a sandbox runs, as resolved and pinned at create time.

reference is the reference as requested (normalised, e.g. docker.io/library/python:3.12-slim), pinned_ref the registry/repo@sha256:... that ran, variant one of rootfs, containerdisk or lume, arch the architecture that ran (amd64/arm64, when known), os the guest OS and emulated whether it ran under emulation.

Containers and registries#

Container#

class Container
 
Container(
    image: str,
    command: Optional[Sequence[str]] = None,
    env: Optional[Mapping[str, str]] = None,
    ports: Optional[Sequence[int]] = None,
    name: Optional[str] = None,
)

A sidecar container, reachable from the sandbox at its name.

name (a DNS label, not main) defaults from the image (redis for redis:7-alpine); the sidecar reaches the sandbox at main. command replaces the image's entrypoint. env holds plain values, not secrets.

Container.native#

def native() -> Any

RegistrySecret#

class RegistrySecret
 
RegistrySecret(
    username: str,
    password: str,
    *,
    registry: Optional[str] = None,
)

Credentials for a private registry image.

• RegistrySecret(username, password): explicit values (a token works as the password).
• RegistrySecret.from_env(): read CUA_REGISTRY_USERNAME / CUA_REGISTRY_PASSWORD (or the variables you name) at create time.
• RegistrySecret.aws_ecr(region=None): a private Amazon ECR image, with a login token from the AWS CLI.

registry scopes them to one host; by default they apply to the image's registry. The password never appears in repr or logs.

Example

from cua_sandbox import Image, RegistrySecret
 
print(Image.from_registry("python:3.12-slim").to_dict()["registry"])
print(repr(RegistrySecret("robot", "s3cr3t", registry="registry.example.com")))  # the password never shows

RegistrySecret.from_env#

@classmethod
def from_env(
    username_var: str = 'CUA_REGISTRY_USERNAME',
    password_var: str = 'CUA_REGISTRY_PASSWORD',
    *,
    registry: Optional[str] = None,
) -> 'RegistrySecret'

RegistrySecret.aws_ecr#

@classmethod
def aws_ecr(region: Optional[str] = None) -> 'RegistrySecret'

RegistrySecret.native#

def native() -> Any

ImageFileReference#

class ImageFileReference(BaseModel)