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
fix(sandbox)!: make the documented Image builder methods work, and boot the pinned disk locally (#3128)
r33drichards664456fc5ffa
diff --git a/docs/content/docs/how-to-guides/sandbox/images.mdx b/docs/content/docs/how-to-guides/sandbox/images.mdxindex e797e641a0..abcbcbc7ef 100644--- a/docs/content/docs/how-to-guides/sandbox/images.mdx+++ b/docs/content/docs/how-to-guides/sandbox/images.mdx@@ -7,6 +7,14 @@ 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()`,+ `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+ a customized one with `NotImplementedError: Fleet cloud supports registry images with+ optional exposed services only`. `expose()` is the one builder method the cloud honors.+</Callout>+## Choose a base imageAn Image describes the OS and software environment. Images are *immutable* and *chainable*. Each builder method returns a new Image.@@ -26,13 +34,64 @@ Image.windows('11') # Windows 11 (local ISO install only)Image.android() # Android 14```-| Image | Kind | Notes |-|-------|------|-------|-| Image.linux() | VM | Default (QEMU), supports /dev/kvm |-| Image.linux(kind='container') | container | Lighter, Docker/XFCE |-| Image.macos() | VM | Apple Virtualization / Lume |-| Image.windows() | VM | QEMU or Hyper-V |-| Image.android() | VM | QEMU Android emulator |+| 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 |++<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>++<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>++### 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:++```python+from cua import Image, Sandbox++async with Sandbox.ephemeral(Image.linux(), local=True) as sb:+ print((await sb.shell.run('uname -a')).stdout)+```++That path needs `qemu-system-x86_64` on the host, and uses `/dev/kvm` when it is+available. Without QEMU the call raises rather than quietly starting something else:++```+RuntimeError: Image.linux() is a VM and needs QEMU, which was not found on this host.+```++`Image.linux(kind='container')` is the Docker path instead, and needs no QEMU.++<Callout type="warn">+ Passing `runtime=QEMURuntime()` explicitly selects `mode='docker'`, which wraps+ QEMU in a container and does **not** boot the pinned containerDisk. Use+ `QEMURuntime(mode='bare-metal')` if you are naming a runtime by hand, or leave+ `runtime=` off and let the default pick it.+</Callout>## Install packages@@ -61,6 +120,15 @@ Set non-sensitive environment variables with `.env()`.Image.linux().env(DATABASE_URL='postgres://localhost/mydb', LOG_LEVEL='debug')```+Variables are baked in as `/etc/profile.d/cua-env.sh` on Linux and macOS, and as+machine-scoped `setx` variables on Windows. On Linux that file is read by *login*+shells, so a bare `sb.shell.run()` does not see them — ask for a login shell:++```python+await sb.shell.run("echo $MY_TOKEN") # empty+await sb.shell.run("bash -lc 'echo $MY_TOKEN'") # abc123+```+<Callout type="warn">Avoid putting real secrets in .env() because anyone who can read the Image spec can see the values.</Callout>@@ -89,6 +157,12 @@ Expose every port the sandbox workload must listen on.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.+</Callout>+## Chain builder callsChaining: builder calls are composable, each returns a new Image:@@ -116,13 +190,36 @@ prod = base.pip_install('gunicorn').run('useradd -m appuser')Use `Image.from_registry()` when your base image already exists in a registry.+The reference must be a **KubeVirt containerDisk** — an image carrying a bootable+disk at `/disk/disk.img`. An ordinary OCI application image such as `ubuntu:22.04`+is not one, and fails with+`FileNotFoundError: OCI image 'ubuntu:22.04' does not contain /disk/disk.img`.+```pythonImage.from_registry('ghcr.io/trycua/macos-tahoe-cua:latest')-Image.from_registry('ubuntu:22.04')+Image.from_registry('public.ecr.aws/k5j5w0x5/cua-ubuntu-24.04:main-38352d34')# chain builder on top-img = Image.from_registry('ubuntu:22.04').apt_install('curl')+img = Image.from_registry('ghcr.io/trycua/macos-tahoe-cua:latest').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:++```python+from cua import QEMURuntime, Sandbox++async with Sandbox.ephemeral(img, local=True, runtime=QEMURuntime(mode='bare-metal')) as sb:+ ...+```++<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. On Cua cloud, only Cua-published images are pullable.+</Callout>+## Use a local disk imageUse `Image.from_file()` for qcow2, vhdx, raw, or iso disk images. URLs are also supported and cached automatically.@@ -133,7 +230,11 @@ Image.from_file('/path/to/windows.vhdx', os_type='windows')Image.from_file('https://example.com/disk.qcow2', os_type='linux')```-Images are cached in `~/.cua/cua-sandbox/image-cache/`.+Disk images downloaded from a URL are cached in `~/.cua/cua-sandbox/image-cache/`,+keyed by a hash of the URL. This is a different cache from the one used for+registry containerDisks, which land in+`~/.cua/cua-sandbox/images/container-disks/<sha256-of-ref>/disk.qcow2`. Delete+either directory to force a re-download.## Inspect an image@@ -142,5 +243,16 @@ Call `.to_dict()` to inspect the final image spec before using it.```pythonimg = Image.linux().apt_install('curl').pip_install('requests')print(img.to_dict())-# {'os_type': 'linux', 'distro': 'ubuntu', 'version': '24.04', 'kind': 'container', 'layers': [...]}+# {'os_type': 'linux', 'distro': 'ubuntu', 'version': '24.04', 'kind': 'vm',+# 'layers': [{'type': 'apt_install', 'packages': ['curl']},+# {'type': 'pip_install', 'packages': ['requests']}]}+```++`env`, `ports` and `files` keys appear only when you have set them:++```python+img = Image.linux().env(DEBUG='1').expose(8080).copy('./a.json', '/app/a.json')+print(img.to_dict())+# {..., 'kind': 'vm', 'layers': [], 'env': {'DEBUG': '1'},+# 'ports': [8080], 'files': [['./a.json', '/app/a.json']]}```diff --git a/docs/content/docs/tutorials/your-first-local-sandbox.mdx b/docs/content/docs/tutorials/your-first-local-sandbox.mdxindex e765a1eba9..b4d0b7442a 100644--- a/docs/content/docs/tutorials/your-first-local-sandbox.mdx+++ b/docs/content/docs/tutorials/your-first-local-sandbox.mdx@@ -11,6 +11,18 @@ In this tutorial, you create an *ephemeral* Linux sandbox on your machine, run `Prerequisites: Python 3.12 or 3.13 and Docker Desktop or Docker Engine.</Callout>+<Callout type="error">+ **This tutorial does not currently work.** 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`), so Docker's+ published port mapping forwards to nothing and the script fails with+ `TimeoutError: Container <name> not ready after 120s`. The image needs rebuilding.+ In the meantime, drop `kind="container"` and use `Image.linux()`, which boots as a+ VM under QEMU and does not go through that image. It needs `qemu-system-x86_64`+ installed instead of Docker — see+ [Choose and build a sandbox image](/how-to-guides/sandbox/images#how-a-linux-image-runs-locally).+</Callout>+## Install the SDKOpen a terminal and install the Python SDK:diff --git a/libs/python/cua-cli/cua_cli/auth/store.py b/libs/python/cua-cli/cua_cli/auth/store.pyindex 6cbc6b5045..d1ef05ad34 100644--- a/libs/python/cua-cli/cua_cli/auth/store.py+++ b/libs/python/cua-cli/cua_cli/auth/store.py@@ -11,6 +11,43 @@ from keyring.errors import KeyringError, PasswordDeleteErrorKEYRING_SERVICE = "run.cua.ai"KEYRING_ACCOUNT = "cua-cli"+# Headless Linux (servers, CI, containers) usually has no D-Bus Secret Service, so+# `keyring` resolves to its no-op fail backend and every command dead-ends here.+# We deliberately do not fall back to on-disk storage on the user's behalf: that+# would silently downgrade an OAuth refresh token to cleartext. Instead, say what+# to run to opt in to it.+#+# Every command below was run end to end in a clean venv before being suggested.+# keyrings.cryptfile rather than keyrings.alt's EncryptedKeyring because the+# latter imports Crypto at construction and keyrings.alt does not depend on a+# crypto library, so recommending it lands the reader on a second dead end+# (ModuleNotFoundError: No module named 'Crypto'); keyrings.cryptfile pulls in+# pycryptodome itself and works from a single install.+_NO_STORE_MESSAGE = (+ "No secure credential store is available.\n"+ "\n"+ "On a desktop, install and unlock an OS keyring (GNOME Keyring, KWallet, macOS "+ "Keychain, Windows Credential Manager).\n"+ "\n"+ "On a headless host, pick one:\n"+ "\n"+ " 1. Unattended (CI, containers, scripts) — skip the credential store and\n"+ " supply a token per run. An encrypted store cannot be unlocked without a\n"+ " prompt, so this is the only option that works without a terminal:\n"+ " export FLEETS_TOKEN=<token>\n"+ "\n"+ " 2. Interactive headless (a server you log into) — encrypted file store.\n"+ " Asks for a passphrase on every command:\n"+ " pip install keyrings.cryptfile\n"+ " export PYTHON_KEYRING_BACKEND=keyrings.cryptfile.cryptfile.CryptFileKeyring\n"+ "\n"+ " 3. Unencrypted file store — only where a recoverable token on disk is\n"+ " acceptable. The file is mode 600, but the token is plainly readable by\n"+ " anyone who can read it, including backups and snapshots:\n"+ " pip install keyrings.alt\n"+ " export PYTHON_KEYRING_BACKEND=keyrings.alt.file.PlaintextKeyring"+)+class CredentialStorageError(RuntimeError):"""Raised when the operating system credential vault is unavailable."""@@ -54,9 +91,7 @@ def _read() -> str | None:try:return keyring.get_password(KEYRING_SERVICE, KEYRING_ACCOUNT)except KeyringError as error:- raise CredentialStorageError(- "No secure credential store is available. Configure an OS keyring before logging in."- ) from error+ raise CredentialStorageError(_NO_STORE_MESSAGE) from errordef load_credentials() -> OAuthCredentials | None:@@ -78,9 +113,7 @@ def save_credentials(credentials: OAuthCredentials) -> None:try:keyring.set_password(KEYRING_SERVICE, KEYRING_ACCOUNT, json.dumps(credentials.to_dict()))except KeyringError as error:- raise CredentialStorageError(- "No secure credential store is available. Configure an OS keyring before logging in."- ) from error+ raise CredentialStorageError(_NO_STORE_MESSAGE) from errordef clear_credentials() -> bool:diff --git a/libs/python/cua-cli/cua_cli/commands/sandbox.py b/libs/python/cua-cli/cua_cli/commands/sandbox.pyindex a035acc4ec..6b96a978f4 100644--- a/libs/python/cua-cli/cua_cli/commands/sandbox.py+++ b/libs/python/cua-cli/cua_cli/commands/sandbox.py@@ -500,6 +500,9 @@ def cmd_ls(args: argparse.Namespace) -> int:as_json = getattr(args, "json", False)results: list[dict] = []+ # A source that failed is not a source that was empty. Swallowing these+ # told anyone hitting an outage that they simply had no sandboxes.+ errors: list[dict] = []if show_all or local:try:@@ -512,8 +515,8 @@ def cmd_ls(args: argparse.Namespace) -> int:"source": getattr(s, "source", "local"),})- except Exception:- pass+ except Exception as error:+ errors.append({"source": "local", "error": f"{type(error).__name__}: {error}"})if show_all or not local:if get_fleets_token():@@ -529,22 +532,25 @@ def cmd_ls(args: argparse.Namespace) -> int:"source": "cloud",})- except Exception:- pass+ except Exception as error:+ errors.append({"source": "cloud", "error": f"{type(error).__name__}: {error}"})if as_json:- print_json(results)- return 0-- if not results:+ print_json({"sandboxes": results, "errors": errors} if errors else results)+ return 1 if errors else 0++ for failure in errors:+ print_error(f"Could not list {failure['source']} sandboxes: {failure['error']}")++ if results:+ print_table(+ results,+ [("name", "NAME"), ("status", "STATUS"), ("source", "SOURCE")],+ )+ elif not errors:print_info("No sandboxes found.")- return 0- print_table(- results,- [("name", "NAME"), ("status", "STATUS"), ("source", "SOURCE")],- )- return 0+ return 1 if errors else 0return run_async(_run())diff --git a/libs/python/cua-cli/tests/auth/test_store.py b/libs/python/cua-cli/tests/auth/test_store.pyindex b540c3a82c..9f27ce5dac 100644--- a/libs/python/cua-cli/tests/auth/test_store.py+++ b/libs/python/cua-cli/tests/auth/test_store.py@@ -55,3 +55,44 @@ def test_store_errors_explain_secure_storage_requirement() -> None:with patch("cua_cli.auth.store.keyring.get_password", side_effect=NoKeyringError):with pytest.raises(CredentialStorageError, match="secure credential store"):load_credentials()+++def test_store_errors_name_a_headless_workaround() -> None:+ """A headless host has no OS keyring, so "configure an OS keyring" is a dead+ end. The error has to name something the user can actually run."""+ for target in ("get_password", "set_password"):+ with patch(f"cua_cli.auth.store.keyring.{target}", side_effect=NoKeyringError):+ with pytest.raises(CredentialStorageError) as excinfo:+ if target == "get_password":+ load_credentials()+ else:+ save_credentials(credentials())+ message = str(excinfo.value)+ assert "PYTHON_KEYRING_BACKEND" in message+ assert "FLEETS_TOKEN" in message+ # The encrypted option must be the one that works from a single+ # install. keyrings.alt's EncryptedKeyring needs pycryptodome on top+ # and dies with "No module named 'Crypto'" without it, which would+ # send the reader to a second dead end.+ assert "keyrings.cryptfile" in message+ assert "keyrings.alt.file.EncryptedKeyring" not in message+++def _no_store_message() -> str:+ with patch("cua_cli.auth.store.keyring.get_password", side_effect=NoKeyringError):+ with pytest.raises(CredentialStorageError) as excinfo:+ load_credentials()+ return str(excinfo.value)+++def test_unattended_hosts_are_told_to_use_a_token() -> None:+ """An encrypted keyring prompts for a passphrase on every command, so CI and+ containers cannot use one. The token path has to be named first."""+ message = _no_store_message()+ assert message.index("FLEETS_TOKEN") < message.index("keyrings.cryptfile")+++def test_plaintext_option_is_marked_as_recoverable() -> None:+ message = _no_store_message()+ assert "PlaintextKeyring" in message+ assert "readable" in messagediff --git a/libs/python/cua-cli/tests/commands/test_sandbox.py b/libs/python/cua-cli/tests/commands/test_sandbox.pyindex 9da55f3a50..1a64f76bb5 100644--- a/libs/python/cua-cli/tests/commands/test_sandbox.py+++ b/libs/python/cua-cli/tests/commands/test_sandbox.py@@ -118,6 +118,91 @@ class TestExecute:mock_error.assert_called()+class TestCmdLsSurfacesFailures:+ """A source that failed is not a source that was empty.++ cmd_ls used to wrap both listings in `except Exception: pass`, so a user+ hitting a real outage was told "No sandboxes found." and got exit 0.+ """++ def test_cloud_failure_is_reported_not_swallowed(self, args_namespace, mock_api_key):+ args = args_namespace(json=False, local=False, all=False)+ mock_sdk = MagicMock()+ mock_sdk.Sandbox.list = AsyncMock(side_effect=ValueError("Expecting value"))++ with patch.dict("sys.modules", {"cua_sandbox": mock_sdk}):+ with patch.object(sandbox, "print_error") as mock_error:+ with patch.object(sandbox, "print_info") as mock_info:+ result = sandbox.cmd_ls(args)++ assert result == 1, "a failed listing must not exit 0"+ mock_info.assert_not_called(), "must not claim there are no sandboxes"+ assert mock_error.call_count == 1+ message = mock_error.call_args[0][0]+ assert "cloud" in message+ assert "Expecting value" in message++ def test_local_failure_is_reported_not_swallowed(self, args_namespace):+ args = args_namespace(json=False, local=True, all=False)+ mock_sdk = MagicMock()+ mock_sdk.Sandbox.list = AsyncMock(side_effect=RuntimeError("docker down"))++ with patch.dict("sys.modules", {"cua_sandbox": mock_sdk}):+ with patch.object(sandbox, "print_error") as mock_error:+ result = sandbox.cmd_ls(args)++ assert result == 1+ assert "local" in mock_error.call_args[0][0]+ assert "docker down" in mock_error.call_args[0][0]++ def test_partial_failure_still_shows_what_worked(self, args_namespace, mock_api_key):+ """--all with a live local and a dead cloud shows the local rows and+ still reports the cloud failure."""+ args = args_namespace(json=False, local=False, all=True)+ local_sandboxes = [SimpleNamespace(name="localbox", status="running", source="local")]+ mock_sdk = MagicMock()+ mock_sdk.Sandbox.list = AsyncMock(side_effect=[local_sandboxes, ValueError("boom")])++ with patch.dict("sys.modules", {"cua_sandbox": mock_sdk}):+ with patch.object(sandbox, "print_table") as mock_table:+ with patch.object(sandbox, "print_error") as mock_error:+ result = sandbox.cmd_ls(args)++ assert result == 1+ mock_table.assert_called_once()+ assert mock_table.call_args[0][0] == [+ {"name": "localbox", "status": "running", "source": "local"}+ ]+ assert "cloud" in mock_error.call_args[0][0]++ def test_json_output_carries_the_errors(self, args_namespace, mock_api_key):+ args = args_namespace(json=True, local=False, all=False)+ mock_sdk = MagicMock()+ mock_sdk.Sandbox.list = AsyncMock(side_effect=ValueError("boom"))++ with patch.dict("sys.modules", {"cua_sandbox": mock_sdk}):+ with patch.object(sandbox, "print_json") as mock_json:+ result = sandbox.cmd_ls(args)++ assert result == 1+ payload = mock_json.call_args[0][0]+ assert payload["sandboxes"] == []+ assert payload["errors"][0]["source"] == "cloud"+ assert "boom" in payload["errors"][0]["error"]++ def test_genuinely_empty_still_says_so(self, args_namespace, mock_api_key):+ args = args_namespace(json=False, local=False, all=False)+ mock_sdk = MagicMock()+ mock_sdk.Sandbox.list = AsyncMock(return_value=[])++ with patch.dict("sys.modules", {"cua_sandbox": mock_sdk}):+ with patch.object(sandbox, "print_info") as mock_info:+ result = sandbox.cmd_ls(args)++ assert result == 0+ mock_info.assert_called_once_with("No sandboxes found.")++class TestCmdLs:"""Tests for cmd_ls function."""diff --git a/libs/python/cua-sandbox/cua_sandbox/builder/build.py b/libs/python/cua-sandbox/cua_sandbox/builder/build.pyindex d1b15bc2eb..3d00c5f00c 100644--- a/libs/python/cua-sandbox/cua_sandbox/builder/build.py+++ b/libs/python/cua-sandbox/cua_sandbox/builder/build.py@@ -15,8 +15,11 @@ Usage::from __future__ import annotationsimport asyncio+import hashlibimport jsonimport logging+import re+import shlexfrom pathlib import Pathfrom typing import Optional@@ -241,6 +244,79 @@ async def _build_linux_base(version: str, base_path: Path) -> Path:raise NotImplementedError("Linux base image building not yet implemented")+_ENV_NAME_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")+++def has_build_work(image: Image) -> bool:+ """Whether anything on this image has to be baked into a user disk.++ ``.env()`` and ``.copy()`` count: they are as much a part of the built image+ as ``.apt_install()`` is, and a layers-only check silently drops them.+ """+ return bool(image._layers or image._env or image._files)+++def build_hash(image: Image) -> str:+ """Stable cache key for the user image built from this spec.++ Everything baked in has to participate, or two images differing only by an+ env var or a copied file would share one cached disk. File *contents* are+ hashed, not just paths, so editing a copied file rebuilds the image.++ Layers-only images keep their historical :func:`layers_hash` key so existing+ caches stay valid.+ """+ layers = list(image._layers)+ if not image._env and not image._files:+ return layers_hash(layers)++ files: list[list[str]] = []+ for src, dst in image._files:+ digest = ""+ try:+ digest = hashlib.sha256(Path(src).read_bytes()).hexdigest()+ except OSError:+ # Unreadable now — let the copy layer raise the real error at build time.+ digest = f"<unreadable:{src}>"+ files.append([dst, digest])++ raw = json.dumps(+ {"layers": layers, "env": [list(e) for e in image._env], "files": files},+ sort_keys=True,+ ).encode()+ return hashlib.sha256(raw).hexdigest()[:16]+++async def _apply_env(executor, image: Image) -> None:+ """Bake ``.env()`` variables into the image being built.++ Linux/macOS get a sourceable ``/etc/profile.d/cua-env.sh`` (the same file the+ Docker and Lume runtimes write, and the one ``LayerExecutor`` sources before+ each ``run`` layer). Windows gets machine-scoped ``setx`` variables.+ """+ if not image._env:+ return++ for key, _ in image._env:+ if not _ENV_NAME_RE.fullmatch(key):+ raise ValueError(f"Unsafe env var name: {key!r}")++ if image.os_type == "windows":+ for key, value in image._env:+ await executor.run_command(f'setx {key} "{value}" /M')+ return++ sudo = "echo lume | sudo -S" if image.os_type == "macos" else "sudo"+ await executor.run_command(+ f"printf '#!/bin/sh\\n' | {sudo} tee /etc/profile.d/cua-env.sh > /dev/null"+ )+ for key, value in image._env:+ await executor.run_command(+ f"printf 'export {key}=%s\\n' {shlex.quote(value)} "+ f"| {sudo} tee -a /etc/profile.d/cua-env.sh > /dev/null"+ )++async def build_user_image(image: Image,base_path: Path,@@ -254,11 +330,11 @@ async def build_user_image(Returns the path to the user image qcow2."""- if not image._layers:- # No user layers — just use the base+ if not has_build_work(image):+ # Nothing to bake in — just use the basereturn base_path- lhash = layers_hash(list(image._layers))+ lhash = build_hash(image)user_path = user_image_path(image.os_type, image.version, lhash)if user_path.exists() and not force:@@ -279,11 +355,19 @@ async def build_user_image(try:info = await runtime.start(build_image, f"cua-build-{lhash}")- # Execute layers via computer-server+ # Execute layers via computer-server. os_type matters: the executor wraps+ # `run` commands per-OS (sudo bash on Linux, plain cmd on Windows).from cua_sandbox.builder.executor import LayerExecutor- executor = LayerExecutor(f"http://{info.host}:{info.api_port}")- await executor.execute_layers(list(image._layers))+ executor = LayerExecutor(f"http://{info.host}:{info.api_port}", os_type=image.os_type)++ # Env first, so copied files and run layers can reference the variables.+ await _apply_env(executor, image)+ # Files before layers, so later run layers can reference copied files.+ for src, dst in image._files:+ await executor.execute_layers([{"type": "copy", "src": src, "dst": dst}])+ if image._layers:+ await executor.execute_layers(list(image._layers))# Shut down cleanlylogger.info("Layers applied, shutting down build VM...")@@ -307,6 +391,8 @@ async def build_user_image("os_type": image.os_type,"version": image.version,"layers": list(image._layers),+ "env": [list(e) for e in image._env],+ "files": [list(f) for f in image._files],"base": str(base_path),"hash": lhash,},@@ -357,8 +443,8 @@ async def create_session_disk(Returns the disk path to boot."""- # If image has a direct disk path and no layers, use it directly- if image._disk_path and not image._layers:+ # If image has a direct disk path and nothing to bake in, use it directly+ if image._disk_path and not has_build_work(image):return Path(image._disk_path)# Determine the backing disk@@ -369,9 +455,9 @@ async def create_session_disk(else:backing = await resolve_backing_disk(image)- # If there are user layers, check for cached user image- if image._layers:- lhash = layers_hash(list(image._layers))+ # If anything has to be baked in, check for a cached user image+ if has_build_work(image):+ lhash = build_hash(image)user_disk = user_image_path(image.os_type, image.version, lhash)if user_disk.exists():backing = user_diskdiff --git a/libs/python/cua-sandbox/cua_sandbox/runtime/qemu.py b/libs/python/cua-sandbox/cua_sandbox/runtime/qemu.pyindex 7357b34613..fefef5357c 100644--- a/libs/python/cua-sandbox/cua_sandbox/runtime/qemu.py+++ b/libs/python/cua-sandbox/cua_sandbox/runtime/qemu.py@@ -166,6 +166,26 @@ _UEFI_FIRMWARE_CANDIDATES: list[tuple[str, str]] = []+def _find_free_vnc_display(start: int = 0, span: int = 64) -> int:+ """Return a VNC display number whose TCP port (5900+N) is free.++ QEMU exits with "Failed to find an available port" when the display is taken,+ so a fixed default makes the second concurrent local sandbox on a host die.+ """+ import socket++ for display in range(start, start + span):+ # No SO_REUSEADDR here on purpose: it would let this probe bind a port a+ # running VM already listens on, which is exactly what we are testing for.+ with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:+ try:+ s.bind(("", 5900 + display))+ except OSError:+ continue+ return display+ return start++def _locate_uefi_firmware(qemu_dir: Path) -> tuple[Optional[Path], Optional[Path]]:"""Return the first (OVMF code, matching vars template) pair present on this host."""for code_name, vars_name in _UEFI_FIRMWARE_CANDIDATES:@@ -248,15 +268,13 @@ class QEMUBaremetalRuntime(Runtime):async def start(self, image: Image, name: str, **opts) -> RuntimeInfo:ephemeral = opts.pop("ephemeral", True)- # If image has layers or no direct disk path, use the builder to resolve- if not opts.get("disk_path") and not image._disk_path and image.kind == "vm":- from cua_sandbox.builder.build import create_session_disk+ from cua_sandbox.builder.build import create_session_disk, has_build_work+ # If image has build work or no direct disk path, use the builder to resolve+ if not opts.get("disk_path") and not image._disk_path and image.kind == "vm":disk_path = str(await create_session_disk(image, name))- elif image._layers and (image._disk_path or opts.get("disk_path")):- # Has a base disk AND user layers — build user image + session overlay- from cua_sandbox.builder.build import create_session_disk-+ elif has_build_work(image) and (image._disk_path or opts.get("disk_path")):+ # Has a base disk AND user layers/env/files — build user image + session overlaybase = Path(opts.get("disk_path") or image._disk_path)disk_path = str(await create_session_disk(image, name, base_disk=base))else:@@ -281,8 +299,12 @@ class QEMUBaremetalRuntime(Runtime):memory = opts.get("memory_mb", self.memory_mb)cpus = opts.get("cpu_count", self.cpu_count)- vnc_display = opts.get("vnc_display", self.vnc_display)+ # VNC and QMP need a free port each, the same way the API port does —+ # the class defaults are only a starting point. Two concurrent local+ # sandboxes would otherwise both claim :0 and 4444 and the second dies.+ vnc_display = _find_free_vnc_display(opts.get("vnc_display", self.vnc_display))hostfwd_port = opts.get("api_port") or _find_free_port(self.api_port)+ qmp_port = opts.get("qmp_port") or _find_free_port(self.qmp_port)enable_kvm = opts.get("enable_kvm", True)# Detect guest server port from transport hint@@ -300,8 +322,10 @@ class QEMUBaremetalRuntime(Runtime):_locate_uefi_firmware(qemu_dir) if image.os_type == "windows" else (None, None))- # EFI vars — look next to disk or copy the template that matches the firmware- efivars = Path(disk_path).parent / "efivars.fd"+ # EFI vars — one pflash file per VM, named after its disk. A single shared+ # sessions/efivars.fd would be mapped writable into every concurrent UEFI+ # guest at once, so they would clobber each other's boot variables.+ efivars = Path(disk_path).with_suffix(".efivars.fd")if ovmf_code and not efivars.exists():import shutil as _shutil@@ -323,6 +347,7 @@ class QEMUBaremetalRuntime(Runtime):hostfwd_port,vnc_display,enable_kvm,+ qmp_port,)else:cmd = [@@ -381,7 +406,7 @@ class QEMUBaremetalRuntime(Runtime):cmd += ["-accel", "whpx"]# QMP socket — always enabled for VM management (suspend/resume)- cmd += ["-qmp", f"tcp:127.0.0.1:{self.qmp_port},server,nowait"]+ cmd += ["-qmp", f"tcp:127.0.0.1:{qmp_port},server,nowait"]# Attach ISO as CD-ROM if booting from an ISO fileif self._iso_path:@@ -412,7 +437,7 @@ class QEMUBaremetalRuntime(Runtime):api_port=hostfwd_port,vnc_port=5900 + vnc_display,name=name,- qmp_port=self.qmp_port if use_qmp else None,+ qmp_port=qmp_port if use_qmp else None,environment=image.os_type if use_qmp else None,agent_type=image._agent_type,guest_server_port=guest_port if not is_android else 8000,@@ -436,7 +461,7 @@ class QEMUBaremetalRuntime(Runtime):host="localhost",api_port=hostfwd_port,vnc_port=5900 + vnc_display,- qmp_port=self.qmp_port,+ qmp_port=qmp_port,disk_path=str(disk_path) if disk_path else None,os_type=image.os_type,vnc_display=vnc_display,@@ -488,6 +513,7 @@ class QEMUBaremetalRuntime(Runtime):hostfwd_port: int,vnc_display: int,enable_kvm: bool,+ qmp_port: Optional[int] = None,) -> list[str]:"""Build QEMU command for Android x86_64 VM.@@ -553,7 +579,7 @@ class QEMUBaremetalRuntime(Runtime):cmd += ["-usb", "-device", "usb-tablet"]# QMP socket for direct VM control (mouse/keyboard/screenshot without guest agent)- cmd += ["-qmp", f"tcp:127.0.0.1:{self.qmp_port},server,nowait"]+ cmd += ["-qmp", f"tcp:127.0.0.1:{qmp_port or self.qmp_port},server,nowait"]# Daemonize on Unixif _plat.system() != "Windows":@@ -905,14 +931,12 @@ class QEMUWSL2Runtime(Runtime):async def start(self, image: Image, name: str, **opts) -> RuntimeInfo:ephemeral = opts.pop("ephemeral", True)+ from cua_sandbox.builder.build import create_session_disk, has_build_work+# Resolve disk pathif not opts.get("disk_path") and not image._disk_path and image.kind == "vm":- from cua_sandbox.builder.build import create_session_disk-disk_path = str(await create_session_disk(image, name))- elif image._layers and (image._disk_path or opts.get("disk_path")):- from cua_sandbox.builder.build import create_session_disk-+ elif has_build_work(image) and (image._disk_path or opts.get("disk_path")):base = Path(opts.get("disk_path") or image._disk_path)disk_path = str(await create_session_disk(image, name, base_disk=base))else:diff --git a/libs/python/cua-sandbox/cua_sandbox/sandbox.py b/libs/python/cua-sandbox/cua_sandbox/sandbox.pyindex ed21c6be74..4db761c652 100644--- a/libs/python/cua-sandbox/cua_sandbox/sandbox.py+++ b/libs/python/cua-sandbox/cua_sandbox/sandbox.py@@ -190,6 +190,29 @@ class _ConnectResult:await self._instance.disconnect()+def _remove_orphan_container(name: str) -> bool:+ """Remove a container left behind by a launch that never wrote state.++ A local launch that times out during the readiness probe leaves a running+ container and no state file, which put it beyond the reach of+ ``Sandbox.delete``. Returns whether a container was actually removed.+ """+ import subprocess++ try:+ exists = subprocess.run(+ ["docker", "inspect", "--type", "container", name],+ capture_output=True,+ )+ if exists.returncode != 0:+ return False+ removed = subprocess.run(["docker", "rm", "-f", name], capture_output=True)+ return removed.returncode == 0+ except (OSError, subprocess.SubprocessError):+ # Docker missing or unusable — no orphan we can claim to have removed.+ return False++def _auto_runtime(image: Image) -> "Runtime":"""Pick a runtime automatically based on image.os_type and image.kind."""import platform as _plat@@ -234,6 +257,24 @@ def _auto_runtime(image: Image) -> "Runtime":# Linux VM or Windows VM → prefer Docker-wrapped QEMU; fall back to bare-metalfrom cua_sandbox.runtime.qemu import QEMURuntime+ if image.os_type == "linux":+ # A Linux VM boots the pinned containerDisk under bare-metal QEMU — the+ # same disk Fleet cloud boots. Docker-wrapped QEMU cannot reach that path+ # at all: resolve_image() hands it the XFCE *container* image, so asking+ # for a VM used to quietly get you a container.+ from cua_sandbox.runtime.compat import _has_qemu++ if not _has_qemu():+ raise RuntimeError(+ "Image.linux() is a VM and needs QEMU, which was not found on "+ "this host. Install it:\n"+ " Debian/Ubuntu: sudo apt install qemu-system-x86\n"+ " Fedora/RHEL: sudo dnf install qemu-system-x86\n"+ " macOS: brew install qemu\n"+ "Or pass an explicit runtime= if you want a different one."+ )+ return QEMURuntime(mode="bare-metal")+if image.os_type == "windows":# Windows bare-metal QEMU works on any host with qemu-system-x86_64try:@@ -1298,6 +1339,10 @@ class Sandbox:subprocess.run(["docker", "stop", name], capture_output=True)subprocess.run(["docker", "rm", name], capture_output=True)+ elif not _remove_orphan_container(name):+ # No state file and no container by that name — deleting nothing at+ # all used to report success, so a typo looked like a deletion.+ raise ValueError(f"No local sandbox named {name!r}")sandbox_state.delete(name)# ── Internal factory ─────────────────────────────────────────────────@@ -1452,6 +1497,7 @@ class Sandbox:if not any([ws_url, http_url]):transport = _make_transport(api_key=api_key,+ image=image,name=name,cpu=cpu,memory_mb=memory_mb,@@ -1837,6 +1883,7 @@ def _make_transport(http_url: Optional[str] = None,api_key: Optional[str] = None,container_name: Optional[str] = None,+ image: Optional[Image] = None,name: Optional[str] = None,cpu: Optional[int] = None,memory_mb: Optional[int] = None,@@ -1850,6 +1897,7 @@ def _make_transport(return CloudTransport(name=name,api_key=api_key,+ image=image,cpu=cpu,memory_mb=memory_mb,disk_gb=disk_gb,diff --git a/libs/python/cua-sandbox/tests/test_docs_regressions.py b/libs/python/cua-sandbox/tests/test_docs_regressions.pynew file mode 100644index 0000000000..cbbd747796--- /dev/null+++ b/libs/python/cua-sandbox/tests/test_docs_regressions.py@@ -0,0 +1,272 @@+"""Regression tests for bugs found while verifying the sandbox images guide.++Each test here fails against the code as it was before the accompanying fix.+"""++import inspect++import pytest+from cua_sandbox.image import Image+++def _build_helpers():+ """Imported lazily so this module still collects against a tree without the fix."""+ from cua_sandbox.builder.build import build_hash, has_build_work++ return build_hash, has_build_work+++class TestCloudTransportGetsItsImage:+ """`_make_transport` dropped `image`, so every API-key cloud create raised+ "Cannot create a cloud VM without an image"."""++ def test_make_transport_accepts_an_image(self):+ from cua_sandbox.sandbox import _make_transport++ assert "image" in inspect.signature(_make_transport).parameters++ def test_cloud_transport_receives_the_image(self):+ from cua_sandbox.sandbox import _make_transport++ img = Image.linux()+ transport = _make_transport(api_key="sk-test", name="probe", image=img)+ assert transport._image is img++ def test_create_passes_the_image_to_every_make_transport_that_creates_a_vm(self):+ """Guards the exact regression: the Fleet branch passed image=image while+ the api-key branch right below it silently did not."""+ from cua_sandbox.sandbox import Sandbox++ src = inspect.getsource(Sandbox._create)+ creating_call = "_make_transport(\n api_key=api_key,\n"+ assert creating_call in src, "the VM-creating _make_transport call moved"+ start = src.index(creating_call)+ call = src[start : src.index(")", start)]+ assert "image=image" in call+++class TestEnvAndFilesAreBuildInputs:+ """`.env()` and `.copy()` were dropped on the QEMU VM path: the builder only+ looked at `_layers`, so the variables and files never reached the guest."""++ def test_env_alone_counts_as_build_work(self):+ _, has_build_work = _build_helpers()+ assert has_build_work(Image.linux().env(MY_TOKEN="abc123"))++ def test_copy_alone_counts_as_build_work(self):+ _, has_build_work = _build_helpers()+ assert has_build_work(Image.linux().copy("./config.json", "/app/config.json"))++ def test_layers_alone_still_counts(self):+ _, has_build_work = _build_helpers()+ assert has_build_work(Image.linux().apt_install("curl"))++ def test_a_plain_image_has_no_build_work(self):+ _, has_build_work = _build_helpers()+ assert not has_build_work(Image.linux())++ def test_env_participates_in_the_cache_key(self):+ """Two images differing only by an env var must not share a built disk."""+ build_hash, _ = _build_helpers()+ a = Image.linux().apt_install("curl").env(TOKEN="a")+ b = Image.linux().apt_install("curl").env(TOKEN="b")+ assert build_hash(a) != build_hash(b)++ def test_copied_file_contents_participate_in_the_cache_key(self, tmp_path):+ build_hash, _ = _build_helpers()+ src = tmp_path / "config.json"+ src.write_text('{"v": 1}')+ first = build_hash(Image.linux().copy(str(src), "/app/config.json"))+ src.write_text('{"v": 2}')+ second = build_hash(Image.linux().copy(str(src), "/app/config.json"))+ assert first != second, "editing a copied file must rebuild the image"++ def test_layers_only_images_keep_their_historical_cache_key(self):+ """Existing cached user images stay valid — the key only changes when+ env or files are actually present."""+ from cua_sandbox.builder.overlay import layers_hash++ build_hash, _ = _build_helpers()+ img = Image.linux().apt_install("curl").pip_install("requests")+ assert build_hash(img) == layers_hash(list(img._layers))+++class TestConcurrentLocalVMsDoNotCollide:+ """A second concurrent bare-metal sandbox died on fixed VNC/QMP ports and+ corrupted the first VM's UEFI variables through a shared efivars.fd."""++ def test_vnc_display_skips_a_busy_port(self):+ import socket++ from cua_sandbox.runtime.qemu import _find_free_vnc_display++ with socket.socket() as taken:+ taken.bind(("", 5900))+ taken.listen(1)+ assert _find_free_vnc_display(0) != 0++ def test_efivars_is_per_vm_not_shared(self):+ """Every session disk lives in one directory; a shared efivars.fd would+ be mapped writable into every concurrent UEFI guest at once."""+ from pathlib import Path++ src = inspect.getsource(+ __import__("cua_sandbox.runtime.qemu", fromlist=["x"]).QEMUBaremetalRuntime.start+ )+ assert 'Path(disk_path).parent / "efivars.fd"' not in src+ assert 'with_suffix(".efivars.fd")' in src++ a = Path("/s/alpha.qcow2").with_suffix(".efivars.fd")+ b = Path("/s/beta.qcow2").with_suffix(".efivars.fd")+ assert a != b++ def test_qmp_port_is_allocated_not_fixed(self):+ src = inspect.getsource(+ __import__("cua_sandbox.runtime.qemu", fromlist=["x"]).QEMUBaremetalRuntime.start+ )+ assert "_find_free_port(self.qmp_port)" in src+ assert 'f"tcp:127.0.0.1:{self.qmp_port},server,nowait"' not in src+++class TestLayerExecutorKnowsTheGuestOS:+ """The builder constructed LayerExecutor without os_type, so Windows `run`+ layers were wrapped in `sudo bash -c`."""++ def test_build_user_image_passes_os_type(self):+ from cua_sandbox.builder import build as build_mod++ src = inspect.getsource(build_mod.build_user_image)+ # Assert on the LayerExecutor construction itself — build_user_image also+ # calls Image.from_file(..., os_type=image.os_type), which must not count.+ start = src.index("LayerExecutor(")+ construction = src[start : src.index(")", src.index("api_port", start))]+ assert "os_type=image.os_type" in construction+++ "image, expected_kind",+ [+ (Image.linux(), "vm"),+ (Image.linux(kind="container"), "container"),+ (Image.windows(), "vm"),+ ],+)+def test_to_dict_reports_the_real_kind(image, expected_kind):+ """The guide printed 'kind': 'container' for Image.linux(), which is a VM."""+ assert image.to_dict()["kind"] == expected_kind+++class TestDeletingNothingIsNotSuccess:+ """`Sandbox.delete(local=True)` dispatched on runtime_type from a state file+ and took no branch when there was none, so deleting a name that never+ existed reported success — and a container from a launch that timed out+ before writing state could not be deleted at all."""++ def test_unknown_name_raises(self, monkeypatch):+ import asyncio+ import importlib++ # cua_sandbox exports a `sandbox()` function that shadows the submodule.+ sandbox_mod = importlib.import_module("cua_sandbox.sandbox")+ state_mod = importlib.import_module("cua_sandbox.sandbox_state")++ monkeypatch.setattr(state_mod, "load", lambda name: None)+ monkeypatch.setattr(sandbox_mod, "_remove_orphan_container", lambda name: False)++ with pytest.raises(ValueError, match="No local sandbox named"):+ asyncio.run(sandbox_mod.Sandbox._delete_local("never-existed"))++ def test_orphan_container_is_removed(self, monkeypatch):+ import asyncio+ import importlib++ # cua_sandbox exports a `sandbox()` function that shadows the submodule.+ sandbox_mod = importlib.import_module("cua_sandbox.sandbox")+ state_mod = importlib.import_module("cua_sandbox.sandbox_state")++ deleted_state = []+ monkeypatch.setattr(state_mod, "load", lambda name: None)+ monkeypatch.setattr(state_mod, "delete", lambda name: deleted_state.append(name))+ monkeypatch.setattr(sandbox_mod, "_remove_orphan_container", lambda name: True)++ asyncio.run(sandbox_mod.Sandbox._delete_local("timed-out-launch"))+ assert deleted_state == ["timed-out-launch"]++ def test_orphan_probe_reports_missing_container(self, monkeypatch):+ import subprocess++ from cua_sandbox.sandbox import _remove_orphan_container++ def fake_run(cmd, **kwargs):+ assert cmd[:2] == ["docker", "inspect"]+ return subprocess.CompletedProcess(cmd, 1)++ monkeypatch.setattr(subprocess, "run", fake_run)+ assert _remove_orphan_container("nope") is False++ def test_orphan_probe_survives_missing_docker(self, monkeypatch):+ import subprocess++ from cua_sandbox.sandbox import _remove_orphan_container++ def fake_run(cmd, **kwargs):+ raise FileNotFoundError("docker")++ monkeypatch.setattr(subprocess, "run", fake_run)+ assert _remove_orphan_container("nope") is False+++class TestLocalRuntimeSelection:+ """`Image.linux()` says kind='vm'. Started locally with no explicit runtime it+ used to land on Docker-wrapped QEMU, which `resolve_image` hands the XFCE+ *container* image — so a VM request quietly became a container, identical to+ `kind='container'`, and never touched the pinned containerDisk."""++ def test_a_linux_vm_boots_under_bare_metal_qemu(self, monkeypatch):+ from cua_sandbox.runtime import compat+ from cua_sandbox.runtime.qemu import QEMUBaremetalRuntime+ from cua_sandbox.sandbox import _auto_runtime++ monkeypatch.setattr(compat, "_has_qemu", lambda: True)+ assert isinstance(_auto_runtime(Image.linux()), QEMUBaremetalRuntime)++ def test_a_linux_container_still_goes_to_docker(self):+ from cua_sandbox.runtime.docker import DockerRuntime+ from cua_sandbox.sandbox import _auto_runtime++ assert isinstance(_auto_runtime(Image.linux(kind="container")), DockerRuntime)++ def test_vm_and_container_do_not_resolve_alike(self, monkeypatch):+ """The regression in one assertion. Comparing the two runtime classes is+ not enough: QEMUDockerRuntime *subclasses* DockerRuntime and resolved to+ the same `trycua/cua-xfce` image, so the old behaviour passed a+ type-inequality check while still booting an identical container. The VM+ must not go through Docker at all."""+ from cua_sandbox.runtime import compat+ from cua_sandbox.runtime.docker import DockerRuntime+ from cua_sandbox.sandbox import _auto_runtime++ monkeypatch.setattr(compat, "_has_qemu", lambda: True)+ vm = _auto_runtime(Image.linux())+ container = _auto_runtime(Image.linux(kind="container"))++ assert isinstance(container, DockerRuntime)+ assert not isinstance(vm, DockerRuntime)++ def test_missing_qemu_fails_loudly_rather_than_silently_downgrading(self, monkeypatch):+ """Falling back to Docker would hand back the XFCE container, which+ cannot become ready — a 120s timeout instead of a named dependency."""+ import pytest as _pytest+ from cua_sandbox.runtime import compat+ from cua_sandbox.sandbox import _auto_runtime++ monkeypatch.setattr(compat, "_has_qemu", lambda: False)+ with _pytest.raises(RuntimeError, match="needs QEMU"):+ _auto_runtime(Image.linux())++ def test_a_disk_path_still_reaches_bare_metal_qemu(self):+ from cua_sandbox.runtime.qemu import QEMUBaremetalRuntime+ from cua_sandbox.sandbox import _auto_runtime++ with_disk = Image.from_file("/tmp/does-not-need-to-exist.qcow2", os_type="linux")+ assert isinstance(_auto_runtime(with_disk), QEMUBaremetalRuntime)