Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

docs(sandbox): centralize versioned runtime support guidance (#2394)

r33drichards87298bc20763
diff --git a/docs/content/docs/concepts/how-fleet-images-work.mdx b/docs/content/docs/concepts/how-fleet-images-work.mdx
new file mode 100644
index 0000000000..be169835c5
--- /dev/null
+++ b/docs/content/docs/concepts/how-fleet-images-work.mdx
@@ -0,0 +1,64 @@
+---
+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.
+
+## Fleet images and Sandbox SDK Images are separate layers
+
+The public `Image` type is the sandbox API's immutable environment specification. It lets you describe a sandbox's operating system, packages, copied files, setup commands, and ports before you start that sandbox.
+
+A Fleet image is the guest boot artifact referenced by a pool definition. A pool can keep multiple replicas running from the same artifact, and later workloads claim those replicas. The Fleet image is therefore an input to capacity management and replica compatibility rather than a step in one sandbox's SDK setup sequence.
+
+The public SDK model is documented in [How sandboxes work](/concepts/how-sandboxes-work#images-as-starting-state-contracts), [Choose and build a sandbox image](/how-to-guides/sandbox/images), and the [Image reference](/reference/sandbox-sdk/image).
+
+## 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 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.
+
+The versioned acceptance rules and their verification limits are in [Sandbox runtime support](/reference/sandbox-sdk/runtime-support). The publication and reference workflow is in [Prepare and reference a Fleet image](/how-to-guides/sandbox/prepare-and-reference-a-fleet-image).
+
+## Fleet references an OCI artifact that carries the boot image
+
+At the pool layer, Fleet stores the registry reference as the deployed boot artifact for the pool template. The referenced OCI artifact must carry the bootable guest image expected by Fleet. The SDK contract is the registry reference itself; the build pipeline determines how the bootable guest is packaged inside that artifact.
+
+`Image.from_registry(...)` does not assemble the artifact. It points Fleet at a prebuilt OCI image that already carries the bootable environment. Artifact publication occurs before the claim path.
+
+## Image identity defines compatibility
+
+A pool's image reference is part of what makes one replica compatible with another. Two pools with different boot artifacts can differ in operating system, installed software, startup behavior, readiness checks, and service endpoints even if they request the same CPU and memory.
+
+A 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.
+
+## Boot configuration must match the image
+
+The 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.
+
+Linux-oriented and Windows-oriented artifacts can require different firmware, devices, and service startup contracts before their configured services become ready.
+
+## Service behavior starts at the image boundary
+
+A Fleet image does not only determine what operating system boots. It also determines what software is already present when a replica starts and which services can become ready inside that guest.
+
+Readiness depends on the services started by the image. A running replica whose configured readiness checks have not passed remains unready for claims.
+
+Ports you mark with `.expose(...)` become named Fleet services. A service URL identifies an endpoint in Fleet's proxy; it does not create a localhost listener or grant access by itself. Access requires Fleet authentication. In 0.4.3, pool-backed sandboxes use `sb.services.request()` for authenticated HTTP requests; their transport does not implement `sb.tunnel.forward()`. See [ports and transports](/reference/sandbox-sdk/runtime-support#ports-and-transports).
+
+With the Sandbox SDK's default service configuration, the published image must start the computer-server endpoint on port `8000`. The SDK creates the `server` service and a TCP readiness probe on that port, then waits for `/status` before returning a connected sandbox.
+
+## Image contents are present before claims
+
+Dependencies and startup behavior included in the image are present when a replica boots. The claim path does not apply SDK image-builder layers.
+
+Changing the referenced image version requires publishing the corresponding artifact and updating the pool reference. Replicas created from the same immutable artifact receive the same image contents.
+
+## Related pages
+
+- [How sandboxes work](/concepts/how-sandboxes-work)
+- [Choose and build a sandbox image](/how-to-guides/sandbox/images)
+- [Image reference](/reference/sandbox-sdk/image)
diff --git a/docs/content/docs/concepts/how-sandboxes-work.mdx b/docs/content/docs/concepts/how-sandboxes-work.mdx
index 8c591c2645..1ece5cc8d9 100644
--- a/docs/content/docs/concepts/how-sandboxes-work.mdx
+++ b/docs/content/docs/concepts/how-sandboxes-work.mdx
@@ -37,7 +37,7 @@ The trade-off is startup latency versus OS fidelity. Containers are suited to fa
An `Image` is the **immutable** description of the sandbox's starting environment. It is not the running sandbox. An `Image` defines the OS type, distro or OS version, packages, environment variables, copied files, and setup commands that should exist when a sandbox starts.
-The image builder composes layers such as `apt_install`, `pip_install`, `run`, `copy`, and `env`. Those layers are applied once at launch to produce the sandbox's initial state. Installing another package later changes that sandbox, not the Image.
+The image builder composes layers such as `apt_install`, `pip_install`, `run`, `copy`, and `env`. Local execution applies those layers at launch to produce the sandbox's initial state. Fleet instead boots a prebuilt registry artifact and rejects these builder layers. Installing another package later changes that sandbox, not the Image. [How Fleet images work](/concepts/how-fleet-images-work) explains the published-artifact model.
This separation makes environments reproducible. The `Image` describes what a fresh sandbox should look like. The sandbox is the live machine created from that description.
@@ -51,14 +51,25 @@ Connect mode attaches to an already-running sandbox. It does not create a sandbo
## Snapshots and forks
-A _snapshot_ captures the disk state of a running sandbox and returns a new `Image`. That `Image` can start any number of fresh sandboxes from the captured point.
+A _snapshot_ records a machine's state for later reuse. A _fork_ starts a separate
+machine from that captured state. These mechanisms can avoid repeating expensive
+setup, but they require support from the provisioning and storage system.
-Snapshots are useful when setup is expensive. Packages can be installed once, models can be downloaded once, and data can be prepared once. After the snapshot is created, new sandboxes can start from that prepared state instead of repeating the setup work.
-
-Each _fork_ starts from the same snapshot but gets its own writable disk. Changes in one fork do not affect the snapshot or sibling forks. On copy-on-write storage, forks can be near-instant because unchanged blocks are shared until a sandbox writes to them.
+In `cua-sandbox` 0.4.3, `Sandbox.snapshot()` is not implemented for local sandboxes
+or the Fleet creation paths. Fleet also rejects snapshot-derived image inputs.
+For these paths, prepare a reusable boot artifact instead. See
+[Sandbox runtime support](/reference/sandbox-sdk/runtime-support#image-customization)
+for the versioned limits and [Prepare and reference a Fleet image](/how-to-guides/sandbox/prepare-and-reference-a-fleet-image)
+for the published-artifact workflow.
## Local execution
Local mode runs on the developer's hardware. Linux containers use Docker Desktop, macOS VMs use Lume, and VM backends can use QEMU or Hyper-V. Local execution depends on the machine's available CPU, memory, disk, and virtualization support. Select it with `local=True`.
-The sandbox still starts from an `Image`, exposes a code half and a GUI half, and can be ephemeral or persistent. See [Choose and build a sandbox image](/how-to-guides/sandbox/images#how-a-linux-image-runs-locally) for local runtime details, or [Your first Cloud Fleet](/tutorials/your-first-cloud-fleet) for a guided hosted path.
+The sandbox still starts from an `Image`, exposes a code half and a GUI half, and can be ephemeral or persistent. See [Choose and build a sandbox image](/how-to-guides/sandbox/images#how-a-linux-image-runs-locally) for local setup.
+
+## Fleet execution
+
+Fleet runs sandboxes as managed capacity. A pool defines the boot artifact and capacity; a claim reserves a sandbox for a workload. Preparing the image and acquiring a running sandbox are separate operations, so the guest's dependencies and services must already be part of the published artifact.
+
+Choosing local execution or Fleet changes the provisioning and connection path, not the idea of an isolated computer. It can also change which image inputs, customization methods, snapshots, and port connections are available. Use [Sandbox runtime support](/reference/sandbox-sdk/runtime-support) for the versioned contract, or [Your first Cloud Fleet](/tutorials/your-first-cloud-fleet) for a guided hosted path.
diff --git a/docs/content/docs/concepts/index.mdx b/docs/content/docs/concepts/index.mdx
index 6e971b8fe2..3a194c02cf 100644
--- a/docs/content/docs/concepts/index.mdx
+++ b/docs/content/docs/concepts/index.mdx
@@ -3,6 +3,8 @@ title: 'Concepts'
description: 'Understand the design ideas behind Cua and how its main pieces fit together.'
---
-Use these pages when you want the model behind Cua rather than a step-by-step guide or API table. They explain what computer use means in Cua, how Cua Driver keeps the desktop usable while it acts, and how Cua Sandbox gives an agent a disposable local computer.
+Use these pages when you want the model behind Cua rather than a step-by-step guide or API table. They explain what computer use means in Cua, how Cua Driver keeps the desktop usable while it acts, and how Cua Sandbox gives an agent an isolated computer on local infrastructure or Fleet.
+
+For sandbox compatibility lookup, use [Sandbox runtime support](/reference/sandbox-sdk/runtime-support). For the relationship between an SDK image and a pool's boot artifact, read [How Fleet images work](/concepts/how-fleet-images-work).
Start with [What is computer use?](/concepts/what-is-computer-use) for the basic model. If you are adding Cua Driver to an agent or product, use [Choose a Cua Driver integration](/concepts/choose-a-cua-driver-integration) before reading the deeper [SDK, MCP, and process hosting](/concepts/sdk-mcp-and-hosting) model. Read [Best-effort background](/concepts/the-no-foreground-contract) to understand Cua Driver's default behavior on a shared machine, then [Capture and delivery modalities](/concepts/capture-and-delivery-modalities) for the action axes. [How we continuously validate Cua Driver](/concepts/how-cua-driver-is-validated) explains why desktop support requires application-owned E2E evidence in addition to unit tests. Read [How sandboxes work](/concepts/how-sandboxes-work) when you need the model for disposable computers, then [Sandbox lifecycle](/concepts/sandbox-lifecycle) for the lifetime and connection patterns. Read [How Lume creates local macOS sandboxes](/concepts/how-lume-unattended-setup-works) for the local VM setup model, and [How SIP works in Lume VMs](/concepts/how-sip-works-in-lume-vms) for signed boot-policy changes. For evaluation, start with [What is Cua-Bench?](/concepts/what-is-cua-bench), then read [The Cua-Bench task lifecycle](/concepts/cua-bench-task-lifecycle).
diff --git a/docs/content/docs/concepts/meta.json b/docs/content/docs/concepts/meta.json
index 5e93b43aa5..8366f8eb19 100644
--- a/docs/content/docs/concepts/meta.json
+++ b/docs/content/docs/concepts/meta.json
@@ -14,6 +14,7 @@
"how-cua-driver-is-validated",
"---Cua Sandbox---",
"how-sandboxes-work",
+ "how-fleet-images-work",
"sandbox-lifecycle",
"---Lume---",
"how-lume-unattended-setup-works",
diff --git a/docs/content/docs/concepts/sandbox-lifecycle.mdx b/docs/content/docs/concepts/sandbox-lifecycle.mdx
index 6f62cf18b7..7ef348a87a 100644
--- a/docs/content/docs/concepts/sandbox-lifecycle.mdx
+++ b/docs/content/docs/concepts/sandbox-lifecycle.mdx
@@ -7,6 +7,11 @@ import { Callout } from 'fumadocs-ui/components/callout';
Use the **lifecycle pattern** that matches whether you want the sandbox _deleted after the job_, _kept for later_, or _attached to while it is already running_.
+The examples below use local execution. Fleet uses managed pools and claims, whose
+release behavior differs from deleting a local VM. See [Your first Cloud Fleet](/tutorials/your-first-cloud-fleet)
+for a pool-and-claim workflow and [Sandbox runtime support](/reference/sandbox-sdk/runtime-support)
+for image and transport limits.
+
## Create and auto-destroy a sandbox
Use `Sandbox.ephemeral` for scripts, CI, and one-off tasks.
@@ -85,7 +90,7 @@ for info in sandboxes:
## Choose a local runtime
-Pass `local=True` to use a runtime on your own machine. Cua selects a compatible local runtime from the image type: Docker for Linux containers, QEMU for Linux VMs, Lume for macOS VMs, and QEMU or Hyper-V for Windows VMs.
+Pass `local=True` to use a runtime on your own machine. Cua selects a local runtime from the image type: Docker for Linux containers, QEMU for Linux VMs, Lume for macOS VMs, and QEMU or Hyper-V for Windows VMs. Selection still requires a compatible host and usable image; it is not a boot check. See the [runtime support reference](/reference/sandbox-sdk/runtime-support#operating-systems-and-image-kinds) before choosing a backend.
```python
# local Docker desktop container
diff --git a/docs/content/docs/concepts/what-is-computer-use.mdx b/docs/content/docs/concepts/what-is-computer-use.mdx
index f219ea4e65..7f9e1aa07e 100644
--- a/docs/content/docs/concepts/what-is-computer-use.mdx
+++ b/docs/content/docs/concepts/what-is-computer-use.mdx
@@ -90,7 +90,7 @@ You bring the agent, which already handles coding and tool-use on its own. Cua g
**Cua Driver** drives the GUI of a real machine you already have, whether that machine runs macOS, Windows, or Linux. It is the right shape when the agent needs to work with local applications, signed-in accounts, existing files, or machine state that already lives on that computer.
-**Cua Sandbox** is a fresh isolated computer running on local Docker or VM infrastructure where the agent can run code and drive the GUI together. It is a full computer with all three action surfaces available inside the same environment rather than a remote desktop, which matters when the task needs both programmatic work and visible interaction without changing the host desktop. The agent brings the model and its reasoning; Cua provides the computer where that reasoning can turn into action.
+**Cua Sandbox** is a fresh isolated computer running on local infrastructure or Fleet where the agent can run code and drive the GUI together. It is a full computer with all three action surfaces available inside the same environment rather than a remote desktop, which matters when the task needs both programmatic work and visible interaction without changing the host desktop. The agent brings the model and its reasoning; Cua provides the computer where that reasoning can turn into action. Available guest operating systems and operations depend on the [runtime and image](/reference/sandbox-sdk/runtime-support).
## Safety and isolation
diff --git a/docs/content/docs/how-to-guides/index.mdx b/docs/content/docs/how-to-guides/index.mdx
index 59af927eca..8ff0231bb3 100644
--- a/docs/content/docs/how-to-guides/index.mdx
+++ b/docs/content/docs/how-to-guides/index.mdx
@@ -5,4 +5,4 @@ description: 'Follow recipes for specific Cua goals.'
How-to guides are recipes for **a specific goal**. They assume you already know the basics, so do a tutorial first if not. Unlike tutorials, they are *not a lesson*; they get you to a result and stop.
-They are grouped by product: Cua Driver for operating apps on a physical machine, Sandbox for isolated local desktops, Lume for local Apple silicon VMs, and Cua-Bench for verifiable computer-use tasks. Recipes and agent context cover workflows that span those products.
+They are grouped by product: Cua Driver for operating apps on a physical machine, Sandbox for isolated computers on local infrastructure or Fleet, Lume for local Apple silicon VMs, and Cua-Bench for verifiable computer-use tasks. Recipes and agent context cover workflows that span those products. Check [Sandbox runtime support](/reference/sandbox-sdk/runtime-support) for the image and connection requirements of a sandbox recipe.
diff --git a/docs/content/docs/how-to-guides/sandbox/images.mdx b/docs/content/docs/how-to-guides/sandbox/images.mdx
index ae544f2449..9571334d84 100644
--- a/docs/content/docs/how-to-guides/sandbox/images.mdx
+++ b/docs/content/docs/how-to-guides/sandbox/images.mdx
@@ -8,11 +8,11 @@ import { Callout } from 'fumadocs-ui/components/callout';
Use an **Image** to define the OS and software environment for a sandbox before you start it.
<Callout type="warn">
- **Customization is local-only today.** `apt_install()`, `pip_install()`, `env()`,
+ **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
- locally (`local=True`). Cua cloud runs the pinned base image as published, and rejects
+ locally (`local=True`). Fleet runs a prebuilt registry artifact and rejects
a customized one with `NotImplementedError: Fleet cloud supports registry images with
- optional exposed services only`. `expose()` is the one builder method the cloud honors.
+ optional 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 base image
@@ -27,48 +27,32 @@ from cua import Image
Image.linux() # Ubuntu 24.04 VM (default, QEMU)
Image.linux(kind='container') # Ubuntu 24.04 container (lighter, Docker/XFCE)
Image.linux('ubuntu', '22.04') # Older Ubuntu
-Image.macos() # macOS Tahoe (version '26', latest)
+Image.macos() # macOS Tahoe (version '26')
Image.macos('15') # macOS Sequoia
Image.windows() # Windows Server 2022
Image.windows('11') # Windows 11 (local ISO install only)
Image.android() # Android 14
```
-| Image | Kind | Runs in cloud | Notes |
-|-------|------|---------------|-------|
-| Image.linux() | VM | yes | Ubuntu 24.04; boots the pinned containerDisk under QEMU, needs qemu-system-x86_64 |
-| Image.linux(kind='container') | container | no | Lighter, Docker/XFCE, no QEMU needed |
-| Image.linux('ubuntu', '22.04') | VM | no | Built locally, no pinned disk |
-| Image.macos() | VM | no | Apple Virtualization / Lume |
-| Image.windows() | VM | yes | QEMU or Hyper-V |
-| Image.windows('11') | VM | no | Local ISO install only |
-| Image.android() | VM | no | QEMU Android emulator |
+Choose a constructor using the [OS and runtime table](/reference/sandbox-sdk/runtime-support#operating-systems-and-image-kinds).
+The built-in Ubuntu 24.04 and Windows Server 2022 VMs map to registry artifacts for
+Fleet; the other built-in inputs do not. A constructor returning an `Image` does
+not verify that its guest can boot on your host or Fleet deployment.
-<Callout type="warn">
- Only `Image.linux()` and `Image.windows()` have a pinned disk in the registry, so
- only those two run on Cua cloud. Every other constructor is local-only — in the
- cloud they raise `NotImplementedError: Fleet cloud sandboxes require a supported
- built-in image or Image.from_registry(...)`.
-
- `Image.windows()` in the cloud is additionally blocked today: its containerDisk is
- UEFI/GPT, while cloud templates default to BIOS firmware, so the guest never boots
- and the claim ends in `BindDeadlineExceeded`. A firmware fix is in flight.
-</Callout>
+For Windows, released 0.4.3 selects EFI in the Fleet template. See
+[Windows firmware](/reference/sandbox-sdk/runtime-support#windows-firmware) before
+diagnosing an unready Windows guest as a BIOS mismatch.
-<Callout type="error">
- **`kind='container'` cannot start right now.** The published
- `trycua/cua-xfce:latest` runs computer-server bound to `127.0.0.1:8000` inside the
- container (`computer_server/cli.py:34` defaults `--host` to `127.0.0.1`, and the
- image's start script does not override it), so Docker's published port mapping
- forwards to nothing and every launch ends in `TimeoutError: Container <name> not
- ready after 120s`. This needs a rebuild of the image; until then use
- `Image.linux()`, which runs as a VM and does not go through that image.
-</Callout>
+If a local Docker image times out on readiness, check the guest server's listening
+address. An earlier `trycua/cua-xfce:latest` recipe reported the server bound to
+`127.0.0.1:8000` inside the container, which Docker's published port could not reach.
+That observation does not establish the state of every later mutable image tag.
### How a Linux image runs locally
`Image.linux()` is a VM. Locally it boots the same pinned containerDisk that Cua
-cloud boots, under QEMU on the host — so a sandbox behaves the same in both places:
+Fleet references, under QEMU on the host. Sharing an artifact does not make host
+networking, firmware, resources, or available SDK operations identical:
```python
from cua import Image, Sandbox
@@ -158,9 +142,10 @@ Image.linux().expose(8080).expose(5432)
```
<Callout type="warn">
- `expose()` currently affects the cloud path only, where each port becomes a Fleet
- service. The bare-metal QEMU runtime never reads the exposed ports, so on a local
- VM they are not forwarded and no error is raised.
+ In 0.4.3, bare-metal QEMU forwards exposed ports at startup and reports their
+ host ports in `sb.exposed_ports`. Other local backends can differ. Fleet creates
+ named services instead. `expose()` does not make `tunnel.forward()` available
+ on every transport; see [ports and transports](/reference/sandbox-sdk/runtime-support#ports-and-transports).
</Callout>
## Chain builder calls
@@ -196,14 +181,18 @@ is not one, and fails with
`FileNotFoundError: OCI image 'ubuntu:22.04' does not contain /disk/disk.img`.
```python
-Image.from_registry('ghcr.io/trycua/macos-tahoe-cua:latest')
-Image.from_registry('public.ecr.aws/k5j5w0x5/cua-ubuntu-24.04:main-809e3f81')
-# chain builder on top
-img = Image.from_registry('ghcr.io/trycua/macos-tahoe-cua:latest').run('echo hi')
+img = Image.from_registry(
+ 'registry.example/workspace@sha256:...',
+ os_type='linux',
+ kind='vm',
+)
+# Local setup only; Fleet rejects builder layers.
+img = img.run('echo hi')
```
-A registry image has no resolved `kind`, so the SDK cannot pick a runtime for it.
-Pass one explicitly when you boot it locally:
+A registry image defaults to `kind=None`, so the SDK cannot automatically select
+a runtime unless you set the kind. For local use, select a runtime compatible
+with the actual guest disk. The Linux VM example uses bare-metal QEMU:
```python
from cua import QEMURuntime, Sandbox
@@ -213,11 +202,10 @@ async with Sandbox.ephemeral(img, local=True, runtime=QEMURuntime(mode='bare-met
```
<Callout type="warn">
- Two more limits worth knowing. `Image.from_registry()` records the reference but
- does not set `os_type` — every registry image reports `os_type='linux'`, including
- the macOS one above, so pass a runtime matching the real guest. And the puller
- authenticates anonymously, which works for `public.ecr.aws` and `ghcr.io` but not
- for Docker Hub.
+ Replace the example reference with an artifact you published. `Image.from_registry()`
+ defaults to `os_type='linux'`; set `os_type='windows', kind='vm'` for a Windows VM
+ disk. The registry reference does not prove that the artifact is accessible or
+ bootable. Local pull authentication and Fleet registry access are separate requirements.
</Callout>
## Use a local disk image
diff --git a/docs/content/docs/how-to-guides/sandbox/meta.json b/docs/content/docs/how-to-guides/sandbox/meta.json
index 1bd0df9716..e2464e10bc 100644
--- a/docs/content/docs/how-to-guides/sandbox/meta.json
+++ b/docs/content/docs/how-to-guides/sandbox/meta.json
@@ -14,6 +14,7 @@
"tunneling",
"share-service-with-signed-url",
"images",
+ "prepare-and-reference-a-fleet-image",
"interactive-shell",
"minecraft"
]
diff --git a/docs/content/docs/how-to-guides/sandbox/minecraft.mdx b/docs/content/docs/how-to-guides/sandbox/minecraft.mdx
index 9f393c575d..89dd192fb0 100644
--- a/docs/content/docs/how-to-guides/sandbox/minecraft.mdx
+++ b/docs/content/docs/how-to-guides/sandbox/minecraft.mdx
@@ -7,9 +7,14 @@ import { Callout } from 'fumadocs-ui/components/callout';
Minecraft exercises almost everything a Windows sandbox can do: it needs internet access, a Java runtime, working OpenGL, and a GUI that only clicks can drive. This guide boots a Windows sandbox, installs Minecraft Java Edition, and hands it to an agent that talks to **cua-driver's MCP server inside the sandbox** — the same loop against a local sandbox and against Fleet.
+The timings, guest hardware, graphics behavior, and deployment errors below are
+observations from this recipe's environment. They are not a certification of every
+Fleet deployment or local host. The [runtime support reference](/reference/sandbox-sdk/runtime-support)
+separates those observations from the released 0.4.3 image and transport contracts.
+
## Before you start
-- **cua-sandbox 0.3.3 or newer.** Windows on Fleet needs 0.3.0, `Image.expose()` on the local QEMU runtime landed in 0.3.1, the `sb.exposed_ports` this guide reads the forwarded port from landed in 0.3.2, and 0.3.3 brought both `Image.from_registry(..., os_type=...)` and the pull-secret fix that lets Fleet boot an image from a registry outside its own allowlist — which the containerDisk section below needs.
+- **cua-sandbox 0.4.3** for the examples below, including the explicit Fleet pool and claim workflow. The local recipe was originally developed against 0.3.3; its recorded timings and guest behavior are observations from that environment, not a new end-to-end test of 0.4.3.
- **A host with hardware virtualisation** for the local path — a Linux x86_64 machine with `/dev/kvm`, or an Intel Mac. This guide passes `-cpu host`, which QEMU only accepts with KVM or HVF. An x86_64 guest on Apple Silicon runs under TCG emulation, where `-cpu host` is rejected outright. The Fleet path runs there instead, including the game, with the one extra environment variable described in the Fleet section below.
- **A Microsoft account that owns Minecraft Java Edition.** Signing in uses Microsoft device authorization, so one step in the middle is manual: a code appears inside the sandbox and you approve it in your own browser.
- **A vision-capable LLM endpoint** for the agent loop.
@@ -56,7 +61,12 @@ asyncio.run(main())
A warm boot takes about 30 seconds. `exposed_ports` maps each exposed guest port to the host port it landed on, and `GET /healthz` on that port answers `ok` once cua-driver is up.
<Callout type="warn">
- **Read the port from `sb.exposed_ports`, not from a tunnel.** `sb.tunnel.forward(3000)` — the usual way to get a forwarded port, and the one the Fleet section below uses — raises `NotImplementedError: HTTPTransport does not support port forwarding` on the local transport. `exposed_ports` is the local equivalent: the runtime picks a free host port at boot, so the mapping is only knowable at runtime, and it is saved with the sandbox state so a later `Sandbox.connect()` can read it back. On Fleet the property is empty, because Fleet publishes services instead — use `tunnel.forward()` there.
+ **Read the port from `sb.exposed_ports` on this bare-metal QEMU path.**
+ `sb.tunnel.forward(3000)` raises `NotImplementedError: HTTPTransport does not support port forwarding`
+ on the local HTTP transport in 0.4.3. This runtime picks a host port at boot and
+ saves the mapping with the sandbox state so a later `Sandbox.connect()` can read
+ it back. The property is backend-specific. Fleet publishes services instead;
+ use an authenticated named-service request or the service URL as shown below.
</Callout>
<Callout type="warn">
@@ -169,7 +179,7 @@ The sandbox already runs **cua-driver**, which serves an MCP endpoint on guest p
Three things about cua-driver's tools shape the loop:
-- **A YAML policy governs which tools may actually run, and `list_tools()` does not reflect it.** Every cua-driver release to date advertises the full surface and refuses out-of-policy calls only when you make them, with `Permission denied: user policy: tool 'X' is not allowed by the YAML policy`. So the listing is a menu of what exists, not of what you can call. Here that surface was 55 tools, identically over the local and Fleet transports: `get_desktop_state`, `list_apps`, `list_windows`, `get_window_state`, `click`, `double_click`, `type_text`, `press_key`, `hotkey`, `launch_app`, `bring_to_front`, `scroll` and `drag` ran, while `get_screen_size`, `get_accessibility_tree`, `get_config`, `check_permissions`, `get_cursor_position` and `zoom` were refused. Treat that split as something to probe on your own image rather than a fixed list — a denial arrives before the tool executes, so probing is cheap. Later drivers filter the listing through the policy, at which point the two finally agree.
+- **A tool listing is not permission to execute a tool.** In the guest used for this recipe, `list_tools()` advertised 55 tools over both the local and Fleet transports, including tools the guest's YAML policy refused. A denied call returned `Permission denied: user policy: tool 'X' is not allowed by the YAML policy`. Check the policy and handle permission errors on the image you use; this observed tool list is not a contract for other Driver versions. See [Restrict tool access](/how-to-guides/driver/restrict-tool-access).
- **Clicks are addressed to an application, not the screen.** `click(pid=..., x=..., y=...)` targets a window belonging to that pid, which you find with `list_windows`. Add `delivery_mode='foreground'` when a background-delivered click does not land.
- **There is no wait tool.** The loop waits by calling `get_desktop_state` again, so say that in the system prompt or the model will invent something worse.
@@ -309,7 +319,10 @@ Everything above is a one-time cost, and none of it has to be repeated — least
Despite the name, `/disk/disk.img` is a **qcow2**, not a raw image. The puller looks for exactly `disk/disk.img` or `./disk/disk.img` inside the layer tarball and caches whatever it finds under `~/.cua/cua-sandbox/images/container-disks/`. Nothing reads the extension — it is a KubeVirt convention.
-`Sandbox.snapshot()` is a different feature and not a substitute: it forks a *cloud* sandbox in place, raises `NotImplementedError: Snapshots are only supported for cloud sandboxes` on the local runtime, and returns an `Image` you cannot push or pull.
+`Sandbox.snapshot()` is not a substitute for publishing a containerDisk. In
+`cua-sandbox` 0.4.3, it is not implemented for local sandboxes or the current Fleet
+creation paths. The package's legacy cloud snapshot code does not enable this
+workflow. See [image customization support](/reference/sandbox-sdk/runtime-support#image-customization).
<Callout type="error">
**Build the image before you sign in, never after.** A disk that has ever held a signed-in Minecraft account cannot be reliably cleaned, and a containerDisk you publish is a disk anyone can pull.
@@ -417,7 +430,7 @@ IMAGE = Image.from_registry(REF, os_type='windows', kind='vm').expose(3000)
`IMAGE` is then a drop-in replacement for `Image.windows().expose(3000)` in both snippets earlier in this guide — the local `Sandbox.create(..., local=True, runtime=QEMURuntime(...))` call and the Fleet one. Nothing else changes: the same `EXTRA_ARGS` locally, the same agent loop, and on Fleet the same `GALLIUM_DRIVER=softpipe`.
<Callout type="warn">
- `sb.tunnel.forward(3000)` is not available on every Fleet path. A sandbox handed back by a pool claim carries the base `FleetTransport`, which does not implement port forwarding, and the error names the transport rather than the cause: `FleetTransport does not support port forwarding`. A sandbox created directly carries `FleetCloudTransport`, which does. If you hit it, reach the service through Fleet's proxy at `/api/svc/<namespace>/<sandbox>-port-3000/` instead.
+ A Fleet pool claim carries `FleetTransport`, which does not implement `sb.tunnel.forward(3000)` in 0.4.3. Image-based `Sandbox.ephemeral()` uses a pool claim too, and `Sandbox.create(image)` requires an explicitly named pool. For HTTP requests, use `sb.services.request('port-3000', method='GET', path='/healthz')`. A streaming MCP client instead needs the service URL and authentication shown below.
</Callout>
Booted locally, that image printed `Image(windows/registry:latest, kind=vm, ...)`, came up on the first try, and had everything in it: `instances\1.20.1`, `java\java-runtime-gamma`, Mesa's `opengl32.dll` beside `javaw.exe`, `minecraft-1.20.1-client.jar`, `MaxMemAlloc=2048` — and `Test-Path C:\mc\prismw\accounts.json` returning `False`. Opening Prism shows the Quick Setup account page and *No accounts added!*, which is what a correctly-built image looks like.
@@ -438,30 +451,56 @@ The reader's remaining work is the part that has to be theirs: open Prism, *Acco
The image and the agent loop are identical on Fleet. Two things change: there is no `local=True` and no `runtime=`, and the MCP endpoint is reached through Fleet's service proxy rather than a forwarded localhost port.
-`.expose(3000)` becomes a Fleet **service** named `port-3000`, and `sb.tunnel.forward()` hands you its URL — the same call documented in [Forward a port from a sandbox](/how-to-guides/sandbox/tunneling), so there is nothing Fleet-specific to hand-assemble.
+`.expose(3000)` becomes a Fleet **service** named `port-3000`. Configure
+[Fleet pool credentials](/reference/cua-cli/authentication#fleet-pools-need-their-own-credentials)
+before running this `cua-sandbox` 0.4.3 example. It creates a dedicated pool with a
+unique name and claims a sandbox. The proxy URL uses the returned namespace and
+bound sandbox name, not the claim name. The MCP client sends a bearer token;
+the URL alone does not grant access.
```python
import httpx
-from cua import Image, Pool, Sandbox
-
-pool = await Pool.apply(Image.windows().expose(3000), name='mc-fleet')
-sb = await Sandbox.create(pool=pool, name='mc-fleet', time_to_start=900)
-
-tunnel = await sb.tunnel.forward(3000)
-# https://run.cua.ai/api/svc/<namespace>/<sandbox>-port-3000/
-
-token = httpx.post(
- 'https://auth.cua.ai/realms/cyclops-cs/protocol/openid-connect/token',
- data={'grant_type': 'client_credentials',
- 'client_id': os.environ['CUA_CLIENT_ID'],
- 'client_secret': os.environ['CUA_CLIENT_SECRET']},
-).json()['access_token']
+import os
+import uuid
+from urllib.parse import quote
+from cua import Image, Sandbox
+from cua_sandbox import Pool
+
+pool = await Pool.apply(
+ Image.windows().expose(3000), name=f'minecraft-{uuid.uuid4().hex[:12]}'
+)
+try:
+ async with Sandbox.ephemeral(pool=pool, name='mc-fleet', time_to_start=900) as sb:
+ health = await sb.services.request('port-3000', method='GET', path='/healthz')
+ health.raise_for_status()
+
+ reference = sb.to_dict()
+ namespace = quote(reference['namespace'], safe='')
+ sandbox_name = quote(sb.name, safe='')
+ service_url = f'https://run.cua.ai/api/svc/{namespace}/{sandbox_name}-port-3000/'
+
+ async with httpx.AsyncClient(timeout=30.0) as client:
+ response = await client.post(
+ 'https://auth.cua.ai/realms/cyclops-cs/protocol/openid-connect/token',
+ data={'grant_type': 'client_credentials',
+ 'client_id': os.environ['CUA_CLIENT_ID'],
+ 'client_secret': os.environ['CUA_CLIENT_SECRET']},
+ )
+ response.raise_for_status()
+ token = response.json()['access_token']
-await run(tunnel.url + 'mcp', TASK, 'your-model',
- headers={'Authorization': f'Bearer {token}'})
+ await run(service_url + 'mcp', TASK, 'your-model',
+ headers={'Authorization': f'Bearer {token}'})
+finally:
+ await pool.delete()
```
-That is the same `run()` as above, with only the URL and an auth header changed. A Fleet Windows sandbox takes about three minutes to become ready, against about thirty seconds for a warm local one, and `GET healthz` on that service URL answers `ok` when cua-driver is up.
+That is the same `run()` as above, with only the URL and an auth header changed.
+The context releases the claim, and `finally` deletes this example's dedicated
+pool. For interrupted runs, follow the [Fleet cleanup guidance](/tutorials/your-first-cloud-fleet).
+In this recipe's environment, a Fleet Windows sandbox took about three minutes
+to become ready, against about thirty seconds for a warm local one. `GET healthz`
+on that service URL answers `ok` when cua-driver is up.
Notice there is no `-cpu host` here. That flag exists on the local path because the bare-metal runtime defaults to the thin `qemu64` model; a Fleet sandbox is provisioned for you and already reports a full host CPU — `Intel Xeon Processor (SapphireRapids)`, with AVX, AVX2 and AVX-512 all present — so there is nothing to override, and no QEMU arguments to pass.
@@ -496,7 +535,7 @@ What that crash is *not*, since each obvious explanation was tested and eliminat
| `GLFW error 65542: WGL: The driver does not appear to support OpenGL` | Mesa DLLs missing beside the `javaw.exe` actually in use, or the MSVC Mesa build failed to load | copy the MinGW Mesa DLLs into every `javaw.exe` directory |
| Game exits during resource loading with no Java exception, **local** | default `qemu64` CPU model | append `-cpu host` to `extra_args` |
| Game exits during resource loading with `exitcode -2147024809`, **Fleet** | Mesa's default llvmpipe renderer | set `GALLIUM_DRIVER=softpipe` in the process that starts the launcher, and restart the launcher if it is already running |
-| `Permission denied: user policy: tool 'X' is not allowed` | cua-driver's YAML policy refuses that tool, which `list_tools()` advertises anyway on every driver released so far | use an allowed tool — `get_desktop_state` instead of `get_screen_size`, `list_windows` instead of `get_accessibility_tree` |
+| `Permission denied: user policy: tool 'X' is not allowed` | The guest's YAML policy refuses that tool; the recipe's guest advertised some denied tools in `list_tools()` | Check the policy and use an allowed tool; do not infer permission from the listing alone |
| Model replies with empty output on the first call | endpoint is streaming-only | issue `stream=True` and rebuild with `litellm.stream_chunk_builder` |
| Sandbox from `Image.from_registry()` never becomes ready | `os_type` defaults to `"linux"`, so a Windows disk gets BIOS instead of UEFI | pass `os_type="windows", kind="vm"` (needs cua-sandbox 0.3.3; before that, `dataclasses.replace()` on the result) |
| `SSLError(1, '[SSL: WRONG_VERSION_NUMBER] wrong version number')` while pulling | the registry speaks plain HTTP; `oras` only speaks HTTPS | give the registry a certificate, and set `REQUESTS_CA_BUNDLE` for a self-signed one |
diff --git a/docs/content/docs/how-to-guides/sandbox/prepare-and-reference-a-fleet-image.mdx b/docs/content/docs/how-to-guides/sandbox/prepare-and-reference-a-fleet-image.mdx
new file mode 100644
index 0000000000..05cb77b03d
--- /dev/null
+++ b/docs/content/docs/how-to-guides/sandbox/prepare-and-reference-a-fleet-image.mdx
@@ -0,0 +1,108 @@
+---
+title: Prepare and reference a Fleet image
+description: Publish a Fleet-compatible OCI image and reference it from the Sandbox SDK.
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+Fleet does not build a sandbox environment from the full SDK image-builder surface. Instead, Fleet expects a **prebuilt OCI artifact** that already carries the bootable guest image for the pool.
+
+<Callout type="info">
+ Configure [Fleet pool credentials](/reference/cua-cli/authentication#fleet-pools-need-their-own-credentials) before running the SDK example. The image-based `Sandbox.ephemeral()` path in `cua-sandbox` 0.4.3 accepts only the default region, `us-east-1`.
+</Callout>
+
+## Before you start
+
+This guide uses `cua-sandbox` 0.4.3 through `cua` 0.1.6. Choose a bootable guest
+artifact compatible with your Fleet deployment and a registry that deployment
+can pull from. SDK acceptance does not establish registry access or successful boot.
+
+You can use the built-in Ubuntu 24.04 or Windows Server 2022 VM image without
+publishing your own artifact. Follow this guide when you need software or startup
+configuration baked into a custom image. See [Sandbox runtime support](/reference/sandbox-sdk/runtime-support)
+for the accepted image inputs and customization limits.
+
+<Callout type="warn">
+ Treat Fleet as a published-image workflow. Build first, publish first, then reference the resulting registry artifact from the SDK.
+</Callout>
+
+## 1. Build the guest image outside the claim path
+
+Prepare the operating system, installed software, startup behavior, and service layout before you ask Fleet to boot it.
+
+The published OCI artifact must already carry the bootable guest image Fleet expects. The Sandbox SDK's Fleet VM template references a containerDisk artifact, with a guest disk at `/disk/disk.img`; an ordinary application container is not a substitute. The SDK does not build that artifact, convert a disk file, or apply SDK layers on your behalf.
+
+## 2. Publish the OCI artifact immutably
+
+Push the finished artifact to a registry and prefer an immutable digest over a mutable tag.
+
+```text
+registry.example/fleet/workspace@sha256:...
+```
+
+Pinned digests make it possible to say exactly which boot image a pool launched. Mutable tags weaken that guarantee because the same pool spec can resolve to different guest images over time.
+
+## 3. Reference the published image from the SDK
+
+Use `Image.from_registry(...)` with any additional Fleet services declared through `.expose(...)`.
+
+With the SDK's default service configuration used here, your published image must
+already start the computer-server service on port `8000`. The generated template
+declares the `server` service and probes that port for readiness; the SDK also
+waits for its `/status` endpoint. Extra `.expose(...)` ports declare additional
+services your image starts. Explicit pool configurations can use a different
+service layout; see the [Pool reference](/reference/sandbox-sdk/pool).
+
+Replace the example reference with your published Linux VM artifact. For a Windows
+VM artifact, use `os_type='windows', kind='vm'`; the OS hint controls the generated
+firmware configuration and is not inferred from the disk.
+
+```python
+import asyncio
+from cua import Image, Sandbox
+
+async def main():
+ image = (
+ Image.from_registry(
+ "registry.example/fleet/workspace@sha256:...",
+ os_type="linux",
+ kind="vm",
+ )
+ .expose(3000)
+ )
+
+ async with Sandbox.ephemeral(image) as sb:
+ result = await sb.shell.run("uname -a")
+ print(result.stdout)
+
+asyncio.run(main())
+```
+
+## 4. Expose only the services your image actually starts
+
+`expose()` is how you declare additional named Fleet services that your guest brings up after boot.
+
+If your image only needs the default computer-server endpoint on `8000`, you do not need extra exposed ports. If it serves additional application traffic on another port, expose that port on the registry image you reference.
+
+## 5. Request the Fleet service through the authenticated connection
+
+Within the sandbox context, use `sb.services.request()` to send an authenticated
+HTTP request to the named service. Replace `/healthz` with a route your service
+implements:
+
+```python
+response = await sb.services.request("port-3000", method="GET", path="/healthz")
+response.raise_for_status()
+print(response.text)
+```
+
+The image-based `Sandbox.ephemeral()` example creates a temporary pool and claim
+and uses the same `FleetTransport` as `Pool.claim()` and `Sandbox.create(pool=...)`.
+It does not create a localhost listener, and that transport does not implement
+`tunnel.forward()` in 0.4.3. See [ports and transports](/reference/sandbox-sdk/runtime-support#ports-and-transports).
+
+## Related pages
+
+- [How Fleet images work](/concepts/how-fleet-images-work)
+- [Sandbox runtime support](/reference/sandbox-sdk/runtime-support)
+- [Image reference](/reference/sandbox-sdk/image)
diff --git a/docs/content/docs/how-to-guides/sandbox/tunneling.mdx b/docs/content/docs/how-to-guides/sandbox/tunneling.mdx
index 4f9ff62878..69c890a8f4 100644
--- a/docs/content/docs/how-to-guides/sandbox/tunneling.mdx
+++ b/docs/content/docs/how-to-guides/sandbox/tunneling.mdx
@@ -1,79 +1,105 @@
---
title: Forward a port from a sandbox
-description: Expose a sandbox port on localhost so local tools can connect to it.
+description: Reach a sandbox service through a local startup mapping, a Fleet service request, or a supported tunnel transport.
---
-import { Callout } from 'fumadocs-ui/components/callout';
+Choose the connection method for your sandbox's transport. In `cua-sandbox`
+0.4.3, local VM `HTTPTransport` and pool-backed `FleetTransport` do not implement
+`sb.tunnel.forward()`. Use the supported paths below; see
+[Sandbox runtime support](/reference/sandbox-sdk/runtime-support#ports-and-transports)
+for the versioned transport contract.
-`sb.tunnel.forward()` exposes a port (or Android abstract socket) running inside the sandbox on the local host.
+## Expose a local QEMU service at startup
-## Forward a single port
-
-Start the service inside the sandbox, then forward its port.
+Declare the port on the image before starting a bare-metal QEMU VM, then read the
+host mapping from `sb.exposed_ports`. This example requires QEMU, a compatible
+host, `cua==0.1.6`, and `httpx`:
```python
-from cua import Sandbox, Image
-
-async with Sandbox.ephemeral(Image.linux(), local=True) as sb:
- await sb.shell.run('python3 -m http.server 8080 &')
-
- async with sb.tunnel.forward(8080) as t:
- print(t.url) # http://localhost:49823
- print(t.host, t.port) # localhost, 49823
+import asyncio
+import httpx
+from cua import Image, QEMURuntime, Sandbox
+
+async def main():
+ image = Image.linux().expose(8080)
+ async with Sandbox.ephemeral(
+ image, local=True, runtime=QEMURuntime(mode='bare-metal')
+ ) as sb:
+ await sb.shell.run(
+ 'nohup python3 -m http.server 8080 --bind 0.0.0.0 '
+ '>/tmp/docs-http-server.log 2>&1 </dev/null &'
+ )
+ host_port = sb.exposed_ports[8080]
+ url = f'http://127.0.0.1:{host_port}/'
+ async with httpx.AsyncClient(timeout=5.0) as client:
+ for attempt in range(30):
+ try:
+ response = await client.get(url)
+ response.raise_for_status()
+ print(f'Service is ready at {url}')
+ break
+ except httpx.HTTPError:
+ if attempt == 29:
+ raise
+ await asyncio.sleep(1)
+
+asyncio.run(main())
```
-The tunnel **closes automatically** when the async with block exits.
-
-## Forward multiple ports at once
+The service must listen on a guest-reachable address, not only guest localhost.
+The mapping lasts for the VM's lifetime; exiting the ephemeral context stops
+the VM and removes the mapping. Other local runtimes may expose ports differently.
-Pass multiple ports to get a `dict[port, TunnelInfo]`.
-
-```python
-async with sb.tunnel.forward(8080, 9222) as tunnels:
- app_url = tunnels[8080].url
- devtools_url = tunnels[9222].url
-```
+For multiple ports, chain declarations such as
+`Image.linux().expose(8080).expose(9222)` and read each guest port's entry from
+`sb.exposed_ports` after startup.
-## Close a tunnel manually
+## Request a named Fleet service
-If you need the tunnel outside an `async with` block, close it yourself.
+Configure [Fleet pool credentials](/reference/cua-cli/authentication#fleet-pools-need-their-own-credentials)
+and use a pool whose guest starts the desired service. Within the claimed
+sandbox's context, send an authenticated request by service name:
```python
-t = await sb.tunnel.forward(8080)
-print(t.url)
-# ... do work ...
-await t.close()
+response = await sb.services.request('port-3000', method='GET', path='/healthz')
+response.raise_for_status()
+print(response.text)
```
-## Android abstract sockets
+An image's `.expose(3000)` declaration creates the `port-3000` service in the
+default pool template. It does not start an application on that port or create
+a localhost listener. See [Prepare and reference a Fleet image](/how-to-guides/sandbox/prepare-and-reference-a-fleet-image)
+for the complete image and claim workflow. External clients need the Fleet
+service URL and authentication; an endpoint URL is not anonymous access.
-Pass a string instead of a port number.
+## Forward through SSH or ADB
+
+For an existing sandbox connected through `SSHTransport` or `ADBTransport`, the
+tunnel helper creates a localhost forwarding endpoint. Start the guest service
+first, then keep its tunnel open for as long as the client needs it:
```python
-async with sb.tunnel.forward('chrome_devtools_remote') as t:
- print(t.url) # http://localhost:<random>
+# sb must use a transport that implements forwarding, such as SSH or ADB.
+async with sb.tunnel.forward(8080) as tunnel:
+ print(tunnel.url)
+ # Connect your local client before leaving this context.
```
-<Callout type="info">
- Abstract socket names are Linux-only (Android). On Linux and macOS sandboxes use integer port numbers.
-</Callout>
-
-## Reference
-
-See [Sandbox SDK interfaces](/reference/sandbox-sdk/interfaces) for the full `TunnelInfo` shape.
+For several ports, `sb.tunnel.forward(8080, 9222)` returns a dictionary keyed by
+guest port. When using `tunnel = await sb.tunnel.forward(8080)` without a context
+manager, call `await tunnel.close()` after the client finishes.
-## Example: Chrome DevTools Protocol
+### Android abstract sockets
-Start Chrome with remote debugging enabled, then read the DevTools target list through the forwarded port.
+ADB also accepts a guest abstract socket name, such as the DevTools socket of a
+running Android Chrome instance:
```python
-from cua import Sandbox, Image
-
-async with Sandbox.ephemeral(Image.linux(), local=True) as sb:
- await sb.shell.run('google-chrome --remote-debugging-port=9222 --headless &')
-
- async with sb.tunnel.forward(9222) as t:
- import httpx
- targets = httpx.get(f'{t.url}/json').json()
- print(targets)
+# sb must be connected to the Android guest through ADBTransport.
+async with sb.tunnel.forward('chrome_devtools_remote') as tunnel:
+ print(tunnel.url)
```
+
+A socket name or integer port does not enable forwarding on an unsupported
+transport. See [Sandbox SDK interfaces](/reference/sandbox-sdk/interfaces) for
+the tunnel handle's fields and cleanup behavior.
diff --git a/docs/content/docs/reference/sandbox-sdk/meta.json b/docs/content/docs/reference/sandbox-sdk/meta.json
index fe87e5f7e1..96e7effc51 100644
--- a/docs/content/docs/reference/sandbox-sdk/meta.json
+++ b/docs/content/docs/reference/sandbox-sdk/meta.json
@@ -1 +1,4 @@
-{ "title": "Sandbox SDK", "pages": ["index", "pool", "interfaces", "image", "typescript"] }
+{
+ "title": "Sandbox SDK",
+ "pages": ["index", "pool", "interfaces", "image", "typescript", "runtime-support"]
+}
diff --git a/docs/content/docs/reference/sandbox-sdk/runtime-support.mdx b/docs/content/docs/reference/sandbox-sdk/runtime-support.mdx
new file mode 100644
index 0000000000..b9f5d50a40
--- /dev/null
+++ b/docs/content/docs/reference/sandbox-sdk/runtime-support.mdx
@@ -0,0 +1,113 @@
+---
+title: Sandbox runtime support
+description: Versioned image, runtime, customization, and transport support for the Sandbox SDK.
+---
+
+This reference describes the Python Sandbox SDK in `cua-sandbox` **0.4.3**, exported
+by `cua` **0.1.6**. An accepted image specification or generated Fleet template is
+evidence of SDK behavior, not proof that a guest boots on every host or deployment.
+
+## Operating systems and image kinds
+
+Local execution uses `local=True`. Fleet execution uses managed pools and claims.
+The same guest OS can have different image formats, runtime requirements, and
+available operations on those two paths.
+
+| Image input | Guest and kind | Local runtime selection | Fleet SDK acceptance in 0.4.3 | Verification boundary |
+| --- | --- | --- | --- | --- |
+| `Image.linux()` | Ubuntu 24.04 VM | Bare-metal QEMU; requires `qemu-system-x86_64` | Maps to a built-in registry artifact | Mapping and runtime selection checked; host and Fleet boot not tested here |
+| `Image.linux(kind='container')` | Ubuntu 24.04 container | Docker | Rejected; no built-in Fleet mapping | Constructor and rejection checked; Docker image readiness not tested here |
+| `Image.linux('ubuntu', '22.04')` | Ubuntu 22.04 VM | Bare-metal QEMU | Rejected; no built-in Fleet mapping | Runtime selection alone does not establish a usable boot image |
+| `Image.windows()` | Windows Server 2022 VM | Hyper-V when available on Windows; otherwise Docker-wrapped QEMU, or bare-metal QEMU when Docker is unavailable | Maps to a built-in registry artifact; template selects EFI | Mapping and firmware selection checked; deployment boot not tested here |
+| `Image.windows('11')` | Windows 11 VM | Windows runtime selection; local ISO installation path | Rejected; no built-in Fleet mapping | Requires a suitable host, installation media, and guest setup |
+| `Image.macos()` / `Image.macos('15')` | macOS 26 / 15 VM | Lume on a compatible Apple silicon host | Rejected as built-in Fleet inputs | Constructor and selection checked; no macOS Fleet deployment established |
+| `Image.android()` | Android 14 VM | Android emulator | Rejected as a built-in Fleet input | Constructor and selection checked; emulator boot not tested here |
+| `Image.from_registry(...)` | Explicit guest OS and optional kind | Set `kind='vm'` or pass a compatible runtime when kind is unresolved | Registry reference accepted | Acceptance does not validate artifact contents, registry access, guest support, or readiness |
+| `Image.from_file(...)` | Disk or ISO with explicit guest OS | Compatible local VM runtime | Rejected | Format and guest requirements depend on the runtime |
+
+The built-in registry mappings in 0.4.3 are:
+
+| Built-in image | Registry artifact |
+| --- | --- |
+| Ubuntu 24.04 VM | `public.ecr.aws/k5j5w0x5/cua-ubuntu-24.04:main-38352d34` |
+| Windows Server 2022 VM | `public.ecr.aws/k5j5w0x5/cua-windows-2022:main-bac7daa3` |
+
+These are versioned tags selected by the package. Use an immutable digest when
+artifact identity must remain fixed independently of a registry tag.
+
+### Windows firmware
+
+In released 0.4.3, `FleetCloudTransport` generates `Firmware.EFI` when
+`image.os_type == 'windows'`. The earlier claim that Windows always receives the
+default BIOS template does not apply to this release. This mapping does not prove
+that a particular account, registry artifact, or Fleet deployment can boot it.
+
+`Image.from_registry()` defaults to `os_type='linux'` and `kind=None`; it does not
+inspect the disk to infer its OS. For a Windows VM artifact, specify
+`os_type='windows', kind='vm'`.
+
+## Image customization
+
+| Operation | Local execution | Fleet execution in 0.4.3 |
+| --- | --- | --- |
+| Package and setup layers, including `apt_install()`, `pip_install()`, and `run()` | Applied through local image setup; commands must match the guest OS | Rejected |
+| `env()` and `copy()` | Applied through local image setup | Rejected |
+| `expose()` | Backend-specific startup port mapping; bare-metal QEMU returns mappings in `sb.exposed_ports` | Declares named services on the pool template |
+| Prebuilt registry artifact | Requires a compatible runtime and bootable guest payload | Accepted as the boot artifact; software must already be installed |
+| `Sandbox.snapshot()` | Not implemented | Not implemented; snapshot-derived image inputs are also rejected |
+
+The package retains snapshot code on its legacy `CloudTransport`. That does not
+enable snapshots on local connections or pool-backed Fleet connections.
+
+Fleet customization means preparing and publishing a compatible guest artifact
+before pool creation. See [Prepare and reference a Fleet image](/how-to-guides/sandbox/prepare-and-reference-a-fleet-image).
+
+## Ports and transports
+
+| 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` |
+| Fleet pool claim through base `FleetTransport` | Not implemented | Use `sb.services.request()` for authenticated requests to a named service |
+| SSH or ADB transport | Implemented by those transports | Forwarding depends on the transport; ADB also accepts Android socket names |
+
+`Pool.claim()`, `Sandbox.create(pool=...)`, and the Fleet image path of
+`Sandbox.ephemeral(image)` all return the base `FleetTransport`. For persistent
+Fleet sandboxes, `Sandbox.create(image)` rejects a registry image without an
+explicitly named pool. Apply the pool first, then claim from it.
+
+The older `FleetCloudTransport` class implements a numeric-port helper, but its
+presence in the package does not make that helper available on the pool-backed
+creation paths above. A method on the common Sandbox interface does not establish
+support on all transports.
+
+Fleet service URLs require authentication. `sb.services.request()` uses the Fleet
+connection's authenticated lease. The lower-level Python Fleet SDK's
+`request_service()` sends authenticated service requests; the TypeScript SDK
+exposes `serviceRequest()`. A URL alone does not grant access. See
+[Fleet pool credentials](/reference/cua-cli/authentication#fleet-pools-need-their-own-credentials)
+and [Sandbox SDK interfaces](/reference/sandbox-sdk/interfaces).
+
+The Fleet image path of `Sandbox.ephemeral()` in 0.4.3 accepts only the default
+`region='us-east-1'`; `Pool.apply()` has no region argument.
+Registry access, account permissions, resource limits, capacity, and readiness are
+deployment requirements that SDK validation cannot establish.
+
+## Evidence and limits
+
+The contracts above were checked against these public release artifacts:
+
+- [`cua-sandbox` 0.4.3 on PyPI](https://pypi.org/project/cua-sandbox/0.4.3/):
+ `image.py` (constructors and registry mappings), `sandbox.py` (runtime selection),
+ `pool.py` (claims), `transport/fleet_cloud.py` (validation, EFI, and services),
+ and the transport and runtime implementations.
+- [`cua` 0.1.6 on PyPI](https://pypi.org/project/cua/0.1.6/): public Python exports.
+- [`cua-fleet` 0.1.14 on PyPI](https://pypi.org/project/cua-fleet/0.1.14/): Python
+ bound-claim service requests.
+- [`@trycua/fleet` 0.1.1 npm version metadata](https://registry.npmjs.org/@trycua/fleet/0.1.1):
+ TypeScript service request surface.
+
+Verification covers released source and offline contract checks. It does not
+include provisioned Fleet boots, authenticated service requests, local VM or
+container boots, or a deployment-wide operating-system certification. Specific
+recipe observations, such as the [Windows Minecraft workflow](/how-to-guides/sandbox/minecraft),
+describe their own tested environment and do not broaden these guarantees.