Image reference

API reference for the Image class: the immutable, chainable image specification used to configure sandbox environments.

Image is an immutable, chainable image specification in cua-sandbox 0.7.0. Each builder method returns a new Image instance; the original is unchanged. Import it from cua_sandbox:

from cua_sandbox import Image

Fleet image constraints#

Pool.apply() accepts an explicit registry reference or a built-in descriptor that resolves to a registry image. Fleet rejects images with setup layers, environment variables, copied files, snapshot sources, or local disk paths. Exposed service ports are accepted. An OCI reference for Fleet must identify a compatible container disk; an arbitrary application container is not a VM disk.

In 0.7.0, the built-in registry mappings are Image.linux() with Ubuntu 24.04 and kind='vm', and Image.windows() with version '2022' and kind='vm'. Other descriptors require an explicit compatible registry image for Fleet. These mappings describe client image selection, not deployment certification. Exact artifact references and per-image evidence are listed in the OS and image catalog.

The builder methods below describe image specifications. They do not establish that every runtime, operating system, or cloud deployment executes those specifications. Local runtime selection and legacy cloud provisioning are separate from Fleet. See Pool reference for Fleet configuration and Sandbox creation for backend selection.

Constructors#

Image.linux#

@classmethod
def linux(cls, distro: str = 'ubuntu', version: str = '24.04', kind: str = 'vm') -> Image

Linux image specification. Defaults to kind='vm'; kind='container' describes a container. Local runtime selection depends on the host and installed runtime.

Image.macos#

@classmethod
def macos(cls, version: str = '26', kind: str = 'vm') -> Image

macOS image specification. Version aliases include '15' / 'sequoia' and '26' / 'tahoe'. The constructor does not establish Fleet availability.

Image.windows#

@classmethod
def windows(cls, version: str = '2022', kind: str = 'vm') -> Image

Windows image specification. The released default is Windows Server 2022.

Image.android#

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

Android image specification. This constructor does not establish Fleet support.

Image.from_registry#

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

Image from an OCI registry reference. os_type identifies the guest operating system; it is not inferred from a tag. When omitted, kind remains unresolved until image resolution.

Image.from_file#

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

Local-runtime image from a disk file, ISO, or URL. Disk handling depends on the runtime. HTTP/HTTPS images are downloaded and cached under ~/.cua/cua-sandbox/image-cache/. Fleet rejects from_file() specifications.

Image.from_dict#

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

Reconstruct an Image from a serialized spec dict (e.g. the output of to_dict()).

Builder methods#

Each method returns a new Image. These methods add setup instructions for a runtime that implements them. Fleet rejects setup layers; use an image with the required software already installed.

Image.apt_install#

def apt_install(self, *packages: str) -> Image

Install packages via apt. Linux only.

Image.brew_install#

def brew_install(self, *packages: str) -> Image

Install packages via Homebrew. macOS only.

Image.choco_install#

def choco_install(self, *packages: str) -> Image

Install packages via Chocolatey. Windows only.

Image.winget_install#

def winget_install(self, *packages: str) -> Image

Install packages via winget. Windows only.

Image.apk_install#

def apk_install(self, *apk_paths: str) -> Image

Install APK files via adb. Android only.

Image.pwa_install#

def pwa_install(
    self,
    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 via adb. Android only. The default builder='pwa2apk' produces a lightweight WebView APK. With builder='bubblewrap' it builds a Trusted Web Activity (TWA), which additionally requires the keystore SHA-256 fingerprint to match the server's /.well-known/assetlinks.json so Chrome opens the PWA without browser chrome.

Built APKs are cached by (manifest_url, package_name). Requirements: Node.js >= 18, Java <= 21 on PATH (Gradle does not support Java 22+).

Image.pip_install#

def pip_install(self, *packages: str) -> Image

Install Python packages via pip.

Image.uv_install#

def uv_install(self, *packages: str) -> Image

Adds a uv add package-installation layer for the cua-server project.

Image.run#

def run(self, command: str) -> Image

Run an arbitrary shell command during image setup.

Image.env#

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

Set environment variables. Values are stored in the Image spec in plaintext. Do not use for secrets.

Image.copy#

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

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

Image.expose#

def expose(self, port: int) -> Image

Marks a port the sandbox will serve on. Fleet's default service mapping names it port-N, where N is the port, except for the server port. Local forwarding is reported by sb.exposed_ports where the runtime provides it.

Image.app_install#

def app_install(self, app_id: str) -> Image

Adds an application-installation layer by app catalog ID. Requires the runtime and application installer to support the selected app; Fleet rejects this layer.

Serialization#

Image.to_dict#

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

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

Example output:

{
    'os_type': 'linux',
    'distro': 'ubuntu',
    'version': '24.04',
    'kind': 'container',
    'layers': [
        {'type': 'apt_install', 'packages': ['curl']},
        {'type': 'pip_install', 'packages': ['requests']},
    ]
}

Image.to_cloud_init#

def to_cloud_init(self) -> str

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

Attributes#