Publish a Fleet image

A cloud sandbox boots an OCI artifact from a registry: the same reference you run locally. The runtime follows the artifact:

The canonical images publish both forms (linux:24.04 and linux:24.04-disk) and one resolver picks the one a runtime needs, pinned by digest. Set the runtime yourself with runtime="kubevirt" (or kind="vm") or --runtime; the SDK rejects a pairing the image cannot run (InvalidPlacement) before it creates anything.

• The cloud runs amd64, so the image needs an amd64 variant.
• Managed capacity is keyed by image digest and shape: two images never share replicas. Pin a digest when every sandbox must boot the same content.
• A Windows containerDisk needs os_type="windows" (EFI firmware).

For small changes (packages, files, env), add layers to an Image (Choose and build an image). Build and publish your own image for a VM disk, a pinned artifact your team shares, or while cloud builds from layers are not available. This uses the cua 0.2.0 CLI.

1. Describe the image#

cua image build takes an images.cua.ai/v1alpha1 Image resource. Layer types are apt_install, pip_install, uv_install, app_install and run; env and ports are recorded in the image. Keep secrets out of it.

{
  "apiVersion": "images.cua.ai/v1alpha1",
  "kind": "Image",
  "metadata": { "name": "my-workspace", "namespace": "my-workspace" },
  "spec": {
    "recipe": {
      "osType": "linux",
      "distro": "ubuntu",
      "version": "24.04",
      "kind": "vm",
      "layers": [
        { "type": "apt_install", "packages": ["curl", "git"] },
        { "type": "run", "command": "mkdir -p /opt/app" }
      ],
      "env": { "APP_ENV": "production" },
      "ports": [8080]
    }
  }
}

2. Build and push#

# containerDisk for VMs: KubeVirt and local QEMU (boots the base VM, applies layers over SSH)
cua image build image.json --base vm:ghcr.io/trycua/linux:24.04-disk \
  --push ghcr.io/<you>/my-workspace:1.0-disk
 
# rootfs for containers: gVisor in the cloud, Docker locally
cua image build image.json --base container:ghcr.io/trycua/linux:24.04 \
  --push ghcr.io/<you>/my-workspace:1.0

The build prints <reference>@sha256:<digest>. It produces an image for the host architecture, so build cloud images on an x86_64 host. Registry credentials come from CUA_REGISTRY_USERNAME / CUA_REGISTRY_PASSWORD, GITHUB_TOKEN for ghcr.io, or your Docker config.

3. Reference it#

cua sb create ghcr.io/<you>/my-workspace:1.0 --name ws                 # local container
cua sb create ghcr.io/<you>/my-workspace:1.0 --on cloud --name ws-cloud

In code, pass the digest to Image.from_registry(...). cua image create --file image.json submits the same resource for a remote build where the deployment supports it.