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.

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.mdx
index 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 image
An 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 calls
Chaining: 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`.
+
```python
Image.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 image
Use `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.
```python
img = 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.mdx
index 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 SDK
Open 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.py
index 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, PasswordDeleteError
KEYRING_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 error
def 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 error
def clear_credentials() -> bool:
diff --git a/libs/python/cua-cli/cua_cli/commands/sandbox.py b/libs/python/cua-cli/cua_cli/commands/sandbox.py
index 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 0
return run_async(_run())
diff --git a/libs/python/cua-cli/tests/auth/test_store.py b/libs/python/cua-cli/tests/auth/test_store.py
index 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 message
diff --git a/libs/python/cua-cli/tests/commands/test_sandbox.py b/libs/python/cua-cli/tests/commands/test_sandbox.py
index 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.py
index 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 annotations
import asyncio
+import hashlib
import json
import logging
+import re
+import shlex
from pathlib import Path
from 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 base
return 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 cleanly
logger.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_disk
diff --git a/libs/python/cua-sandbox/cua_sandbox/runtime/qemu.py b/libs/python/cua-sandbox/cua_sandbox/runtime/qemu.py
index 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 overlay
base = 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 file
if 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 Unix
if _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 path
if 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.py
index 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-metal
from 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_64
try:
@@ -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.py
new file mode 100644
index 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)