Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
docs: clarify published Fleet image selection and evidence (#3591)
Francesco Bonacci8765dc30b069
diff --git a/docs/content/docs/concepts/how-fleet-images-work.mdx b/docs/content/docs/concepts/how-fleet-images-work.mdxindex be169835c5..76770e893b 100644--- a/docs/content/docs/concepts/how-fleet-images-work.mdx+++ b/docs/content/docs/concepts/how-fleet-images-work.mdx@@ -3,9 +3,7 @@ title: 'How Fleet images work'description: 'How Fleet boot artifacts define the operating system, compatibility boundary, and service contract for managed sandbox capacity.'----A Fleet image is the boot artifact from which a Fleet pool starts its reusable sandbox replicas. It is an infrastructure-level input such as a VM disk or container-backed boot artifact. It is **not** the public `Image` abstraction from the Sandbox SDK.--The public Sandbox SDK `Image` describes the starting environment for a sandbox created through the SDK. A Fleet image is the deployed guest artifact that a pool repeatedly boots as shared capacity for later claims.+A Fleet image is a prebuilt guest boot artifact that a pool uses to start its sandbox replicas. The Sandbox SDK's `Image` specification selects that artifact; the pool boots it before a workload claims a replica.## Fleet images and Sandbox SDK Images are separate layers@@ -17,7 +15,7 @@ The public SDK model is documented in [How sandboxes work](/concepts/how-sandbox## Fleet uses a constrained subset of the SDK image surface-Fleet uses a prebuilt registry artifact as its starting point. The Sandbox SDK can reference that artifact directly with `Image.from_registry(...)` or resolve a supported built-in image to one. In `cua-sandbox` 0.4.3, the built-in Ubuntu 24.04 and Windows Server 2022 VM images have registry mappings.+Fleet uses a prebuilt registry artifact as its starting point. The Sandbox SDK can reference that artifact directly with `Image.from_registry(...)` or resolve a built-in image with a registry mapping. In `cua-sandbox` 0.4.3, the built-in Ubuntu 24.04 and Windows Server 2022 VM images have registry mappings.Fleet does **not** build an environment from SDK layers such as `apt_install`, `pip_install`, `uv_install`, `run`, `copy`, `env`, `from_file`, or snapshot-derived images. The Fleet registry input must reference a guest artifact published before sandbox creation.@@ -35,6 +33,8 @@ A pool's image reference is part of what makes one replica compatible with anothA pinned image reference identifies the artifact used by a pool. With a mutable tag, registry content can change while the pool specification remains unchanged, so replicas created at different times can boot different artifact contents.+A digest identifies specific registry content. It does not establish that Fleet can pull the artifact, that its guest architecture matches the runtime, or that its services work. Those require separate evidence. The [OS and image catalog](/reference/sandbox-sdk/os-image-catalog) records image identities and their evidence boundaries.+## Boot configuration must match the imageThe image and the pool's boot configuration must agree. Firmware expectations, disk layout, guest drivers, and startup services are properties of the boot artifact and its runtime configuration.diff --git a/docs/content/docs/how-to-guides/sandbox/images.mdx b/docs/content/docs/how-to-guides/sandbox/images.mdxindex 9571334d84..861b59d934 100644--- a/docs/content/docs/how-to-guides/sandbox/images.mdx+++ b/docs/content/docs/how-to-guides/sandbox/images.mdx@@ -7,6 +7,9 @@ import { Callout } from 'fumadocs-ui/components/callout';Use an **Image** to define the OS and software environment for a sandbox before you start it.+For Fleet, [choose a published image](#choose-a-published-fleet-image). For local+execution, [choose a base image](#choose-a-base-image) and add the setup steps below.+<Callout type="warn">**SDK builder customization is local-only in `cua-sandbox` 0.4.3.** `apt_install()`, `pip_install()`, `env()`,`run()`, `copy()` and the other builder methods are applied when you boot the image@@ -15,6 +18,49 @@ Use an **Image** to define the OS and software environment for a sandbox beforeoptional exposed services only`. For Fleet customization, [prepare and publish the guest image first](/how-to-guides/sandbox/prepare-and-reference-a-fleet-image). See [Sandbox runtime support](/reference/sandbox-sdk/runtime-support) for versioned acceptance and verification limits.</Callout>+## Choose a published Fleet image++1. Open the [OS and image catalog](/reference/sandbox-sdk/os-image-catalog) and+ choose a Fleet VM artifact that matches your guest OS and workload. Check its+ architecture and evidence limits. Local Docker and Lume entries are separate+ runtime choices, not built-in Fleet mappings.+2. Check the artifact's guest services against your client. The Sandbox SDK's+ default connection expects computer-server on port `8000`; an MCP client needs+ an image that starts an MCP service. Declaring a port does not install either+ service. See the [Fleet guest-service contract](/reference/sandbox-sdk/runtime-support#fleet-guest-service-contract).+3. Use the built-in constructor for a mapped artifact, or copy the exact registry+ reference into `Image.from_registry()`. Set the guest OS and `kind='vm'`+ explicitly. Use a digest when you need an identity independent of tag changes.+4. Follow [Create a sandbox pool with Python](/how-to-guides/sandbox/create-pool-with-python) to apply+ the image and claim a replica. Confirm registry access, guest readiness, and+ the operation your workload needs before reusing that pool.++For an explicit registry reference, set `FLEET_IMAGE_REF` to the artifact you+selected, then construct the image specification:++```python+import os+from cua_sandbox import Image++image = Image.from_registry(+ os.environ['FLEET_IMAGE_REF'],+ os_type='linux',+ kind='vm',+)+```++For a Windows artifact, change `os_type` to `'windows'`; this selects EFI in the+generated Fleet template. This snippet defines an image without provisioning it.+For image-specific service configuration, use the catalogue's linked recipe.++Windows images do not include a Windows license. Before provisioning one,+confirm that your own licenses cover your intended use, including applicable+hosting and virtualization rights. A successful boot is not a licensing check.++If the artifact lacks required software, [prepare and publish a guest image](/how-to-guides/sandbox/prepare-and-reference-a-fleet-image)+before creating the pool. The local builder examples below do not publish a+Fleet artifact or run during a Fleet claim.+## Choose a base imageAn Image describes the OS and software environment. Images are *immutable* and *chainable*. Each builder method returns a new Image.diff --git a/docs/content/docs/reference/sandbox-sdk/image.mdx b/docs/content/docs/reference/sandbox-sdk/image.mdxindex cf14dce331..d9843a574e 100644--- a/docs/content/docs/reference/sandbox-sdk/image.mdx+++ b/docs/content/docs/reference/sandbox-sdk/image.mdx@@ -23,6 +23,8 @@ In 0.4.3, the built-in registry mappings are `Image.linux()` with Ubuntu 24.04and `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](/reference/sandbox-sdk/os-image-catalog).The builder methods below describe image specifications. They do not establishthat every runtime, operating system, or cloud deployment executes thosediff --git a/docs/content/docs/reference/sandbox-sdk/os-image-catalog.mdx b/docs/content/docs/reference/sandbox-sdk/os-image-catalog.mdxindex a552fb35fa..4b8a254b63 100644--- a/docs/content/docs/reference/sandbox-sdk/os-image-catalog.mdx+++ b/docs/content/docs/reference/sandbox-sdk/os-image-catalog.mdx@@ -3,13 +3,18 @@ title: OS and image catalogdescription: Sandbox operating systems, Linux distributions, desktop environments, window managers, and image registries.----| OS | Distribution / version | Desktop / window manager | Image kind / runtime | Registry image or source | Status / limits |-| --- | --- | --- | --- | --- | --- |-| Linux | Ubuntu 24.04 | Artifact-dependent; not specified by SDK mapping | Fleet containerDisk; local bare-metal QEMU | `public.ecr.aws/k5j5w0x5/cua-ubuntu-24.04:main-38352d34` | Built-in `Image.linux()` mapping; [versioned runtime support](/reference/sandbox-sdk/runtime-support), not universal boot certification |-| Linux | Ubuntu 24.04 | XFCE runtime mapping | Local Docker container | `public.ecr.aws/k5j5w0x5/cua-ubuntu-24.04:docker-latest` | Local container selector; mutable tag, not the Fleet VM disk |-| Linux | Omarchy (Arch Linux-based), amd64 | Hyprland / Wayland | Fleet containerDisk | `public.ecr.aws/k5j5w0x5/cua-omarchy-workspace@sha256:d9b7be06beac425084eaa99eb912589b38b5cc86ae3e3ec45c9c5d59d4b3a7ab` | Explicit registry image; boot evidence applies to the [Fleet recipe](/how-to-guides/sandbox/run-omarchy-on-cloud-fleet), not all Hyprland configurations |-| Linux | NixOS | StumpWM | Published candidate image | `public.ecr.aws/k5j5w0x5/cua-nixos-stumpwm:git-ee87f38043c043831a8761016015d6ef5ae783d9` | Includes computer-server and Cua Driver; publication reports guest tests and CI anonymous-pull verification passed; immutable candidate, not promoted to `latest`; not a built-in SDK mapping |-| Linux | NixOS | Xfce / Xfwm4 | Published candidate image | `public.ecr.aws/k5j5w0x5/cua-nixos-xfce:git-ee87f38043c043831a8761016015d6ef5ae783d9` | Includes computer-server and Cua Driver; publication reports guest tests and CI anonymous-pull verification passed; immutable candidate, not promoted to `latest`; not a built-in SDK mapping |-| Windows | Server 2022 | Native Windows desktop | Fleet containerDisk; local Hyper-V or QEMU | `public.ecr.aws/k5j5w0x5/cua-windows-2022:main-bac7daa3` | Built-in `Image.windows()` mapping; Fleet selects EFI; [runtime and host limits](/reference/sandbox-sdk/runtime-support) apply |-| macOS | Sequoia 15 | Native macOS desktop | Local Lume VM | `ghcr.io/trycua/macos-sequoia-cua:latest` | Compatible Apple silicon host required; mutable tag; no built-in Fleet mapping |-| macOS | Tahoe 26 | Native macOS desktop | Local Lume VM | `ghcr.io/trycua/macos-tahoe-cua:latest` | Default `Image.macos()` version; compatible Apple silicon host required; mutable tag; no built-in Fleet mapping |+Windows images do not include a Windows license. Bring your own valid licenses+covering your intended use, including the applicable hosting and virtualization+rights. An image being available or booting successfully does not establish+licensing eligibility. Bundled applications have their own license terms.++| OS | Distribution / version / architecture | Desktop / window manager | Image kind / runtime | Registry image or source | Evidence / limits |+| ------- | ----------------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Linux | Ubuntu 24.04; artifact architecture not established by SDK mapping | Artifact-dependent; not specified by SDK mapping | Fleet containerDisk; local bare-metal QEMU | `public.ecr.aws/k5j5w0x5/cua-ubuntu-24.04:main-38352d34` | `Image.linux()` mapping in `cua-sandbox` 0.4.3; versioned tag, not a digest pin. [SDK checks](/reference/sandbox-sdk/runtime-support#evidence-and-limits) establish selection, not a live pull, boot, or guest-service check. |+| Linux | Ubuntu 24.04 | XFCE runtime mapping | Local Docker container | `public.ecr.aws/k5j5w0x5/cua-ubuntu-24.04:docker-latest` | Local container selector; mutable tag, not the Fleet VM disk |+| Linux | Omarchy (Arch Linux-based), amd64 | Hyprland / Wayland | Fleet containerDisk | `public.ecr.aws/k5j5w0x5/cua-omarchy-workspace@sha256:d9b7be06beac425084eaa99eb912589b38b5cc86ae3e3ec45c9c5d59d4b3a7ab` | Digest-pinned explicit registry image. The [Fleet recipe](/how-to-guides/sandbox/run-omarchy-on-cloud-fleet) reports boot verification and defines `server: 8000` (computer-server) and `mcp: 3000` (Cua Driver); it does not certify every operation or Hyprland configuration. |+| Linux | NixOS; release and architecture not recorded in the publication summary | StumpWM | Published candidate image | `public.ecr.aws/k5j5w0x5/cua-nixos-stumpwm:git-ee87f38043c043831a8761016015d6ef5ae783d9` | [Publication summary](https://github.com/trycua/cua/pull/3585) reports computer-server and Cua Driver included, guest tests and CI anonymous-pull checks passed. Component versions, service ports, and Fleet claim checks are not recorded there. Commit-named candidate tag, not a digest pin or `latest`; no built-in SDK mapping. |+| Linux | NixOS; release and architecture not recorded in the publication summary | Xfce / Xfwm4 | Published candidate image | `public.ecr.aws/k5j5w0x5/cua-nixos-xfce:git-ee87f38043c043831a8761016015d6ef5ae783d9` | [Publication summary](https://github.com/trycua/cua/pull/3585) reports computer-server and Cua Driver included, guest tests and CI anonymous-pull checks passed. Component versions, service ports, and Fleet claim checks are not recorded there. Commit-named candidate tag, not a digest pin or `latest`; no built-in SDK mapping. |+| Windows | Server 2022; artifact architecture not established by SDK mapping | Native Windows desktop | Fleet containerDisk; local Hyper-V or QEMU | `public.ecr.aws/k5j5w0x5/cua-windows-2022:main-bac7daa3` | `Image.windows()` mapping in `cua-sandbox` 0.4.3; Fleet selects EFI. Versioned tag, not a digest pin. [SDK checks](/reference/sandbox-sdk/runtime-support#evidence-and-limits) establish selection and firmware, not a live pull, boot, or guest-service check. |+| macOS | Sequoia 15 | Native macOS desktop | Local Lume VM | `ghcr.io/trycua/macos-sequoia-cua:latest` | Compatible Apple silicon host required; mutable tag; no built-in Fleet mapping |+| macOS | Tahoe 26 | Native macOS desktop | Local Lume VM | `ghcr.io/trycua/macos-tahoe-cua:latest` | Default `Image.macos()` version; compatible Apple silicon host required; mutable tag; no built-in Fleet mapping |diff --git a/docs/content/docs/reference/sandbox-sdk/runtime-support.mdx b/docs/content/docs/reference/sandbox-sdk/runtime-support.mdxindex b9f5d50a40..f6357c67b2 100644--- a/docs/content/docs/reference/sandbox-sdk/runtime-support.mdx+++ b/docs/content/docs/reference/sandbox-sdk/runtime-support.mdx@@ -64,6 +64,26 @@ before pool creation. See [Prepare and reference a Fleet image](/how-to-guides/s## Ports and transports+### Fleet guest-service contract++Image acceptance and service readiness are separate checks. In 0.4.3, the default+pool template and Sandbox connection use these contracts:++| Service | Template or client behavior | Required guest behavior |+| -------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |+| `server` | Default port `8000`; TCP readiness probe; Sandbox connection waits for `/status` | Start a compatible computer-server endpoint reachable from the guest network |+| `port-N` | `.expose(N)` adds a named service for a non-server port | Start the application on port `N`; the declaration does not install or start it |+| Explicit names | `Pool.apply(services={...})` declares named ports while retaining `server` | Start the corresponding services; clients must speak their protocol |++The SDK's default template probe checks the server port, not every additional+service. A ready server does not prove that an MCP endpoint or application service+works. An MCP service's name, port, path, and installed driver version belong to+the artifact's documented contract; they cannot be inferred from its Linux or+Windows label. For an example service layout, see the+[Omarchy Fleet recipe](/how-to-guides/sandbox/run-omarchy-on-cloud-fleet).++### Transport availability+| Sandbox connection | `sb.tunnel.forward()` in 0.4.3 | Connection behavior || --- | --- | --- || Local VM through `HTTPTransport` | Not implemented | Use the runtime's startup mapping where available, such as bare-metal QEMU's `sb.exposed_ports` |