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
SDK integration tests, auto-generated docs, and snapshot support (#1242)
ddupontd7a2452fdf31
diff --git a/demo/1_fleet_throughput.py b/demo/1_fleet_throughput.pyindex b9835c72b0..23ec00df33 100644--- a/demo/1_fleet_throughput.py+++ b/demo/1_fleet_throughput.py@@ -35,16 +35,26 @@ async def connect_all(names: list[str]) -> list[tuple[str, Sandbox]]:"""Connect to each VM sequentially so output is ordered and easy to read."""print(f"Connecting to {len(names)} VMs (sequential, timeout={CONNECT_TIMEOUT}s each)...\n")sandboxes = []+ connect_times: list[float] = []for i, name in enumerate(names, 1):print(f" [{i:>3}/{len(names)}] {name} ...", end=" ", flush=True)+ t0 = time.monotonic()try:sb = await asyncio.wait_for(Sandbox.connect(name=name), timeout=CONNECT_TIMEOUT)- print("✓", flush=True)+ elapsed = time.monotonic() - t0+ connect_times.append(elapsed)+ print(f"✓ {elapsed*1000:.0f}ms", flush=True)sandboxes.append((name, sb))except asyncio.TimeoutError:print("✗ timeout", flush=True)except Exception as e:print(f"✗ {e}", flush=True)+ if connect_times:+ connect_times.sort()+ p50 = connect_times[len(connect_times) // 2] * 1000+ p95 = connect_times[int(len(connect_times) * 0.95)] * 1000+ avg = sum(connect_times) / len(connect_times) * 1000+ print(f"\n Connect avg={avg:.0f}ms p50={p50:.0f}ms p95={p95:.0f}ms")return sandboxes@@ -60,13 +70,13 @@ async def run_step(name: str, sb: Sandbox) -> float:# ── main ─────────────────────────────────────────────────────────────────────-async def main(n: int | None = None, rounds: int = ROUNDS):+async def main(n: int | None = None, rounds: int = ROUNDS, concurrency: int = CONCURRENCY):OUT_DIR.mkdir(exist_ok=True)names = load_names(n)print(f"\n{'='*50}")print(" Fleet Throughput Demo")- print(f" {len(names)} VMs | {rounds} rounds each | concurrency={CONCURRENCY}")+ print(f" {len(names)} VMs | {rounds} rounds each | concurrency={concurrency}")print(f"{'='*50}\n")sandboxes = await connect_all(names)@@ -76,12 +86,12 @@ async def main(n: int | None = None, rounds: int = ROUNDS):print("No VMs connected — exiting.")return- # Run ROUNDS of tap+screenshot across all VMs concurrently- sem = asyncio.Semaphore(CONCURRENCY)+ # Run rounds of tap+screenshot across all VMs concurrently+ sem = asyncio.Semaphore(concurrency)total_steps = 0latencies: list[float] = []- print(f"Running {rounds} rounds of tap+screenshot (concurrency={CONCURRENCY})...\n")+ print(f"Running {rounds} rounds of tap+screenshot (concurrency={concurrency})...\n")t_start = time.monotonic()for round_num in range(1, rounds + 1):@@ -137,5 +147,11 @@ if __name__ == "__main__":parser.add_argument("--rounds", type=int, default=ROUNDS, help=f"Rounds per VM (default: {ROUNDS})")+ parser.add_argument(+ "--concurrency",+ type=int,+ default=CONCURRENCY,+ help=f"Parallel commands (default: {CONCURRENCY})",+ )args = parser.parse_args()- asyncio.run(main(n=args.n, rounds=args.rounds))+ asyncio.run(main(n=args.n, rounds=args.rounds, concurrency=args.concurrency))diff --git a/docs/content/docs/cua/guide/sandbox/meta.json b/docs/content/docs/cua/guide/sandbox/meta.jsonindex de4337f2bd..2603d94ce5 100644--- a/docs/content/docs/cua/guide/sandbox/meta.json+++ b/docs/content/docs/cua/guide/sandbox/meta.json@@ -2,5 +2,5 @@"title": "Sandbox","description": "Working with sandboxes","icon": "Box",- "pages": ["lifecycle", "images", "secrets", "scale-out", "interactive-shell", "tunneling"]+ "pages": ["lifecycle", "images", "snapshots", "secrets", "scale-out", "interactive-shell", "tunneling"]}diff --git a/docs/content/docs/cua/guide/sandbox/snapshots.mdx b/docs/content/docs/cua/guide/sandbox/snapshots.mdxnew file mode 100644index 0000000000..0fef544e71--- /dev/null+++ b/docs/content/docs/cua/guide/sandbox/snapshots.mdx@@ -0,0 +1,116 @@+---+title: Snapshots+description: Capture sandbox state and boot new sandboxes from snapshots instantly+---++import { Callout } from 'fumadocs-ui/components/callout';++A snapshot captures the full disk state of a running sandbox. It returns a new `Image` that you can pass to `Sandbox.create()` or `Sandbox.ephemeral()` to boot a fresh sandbox from that point — with all installed packages, files, and configuration intact.++## Quick example++```python+import asyncio+from cua import Sandbox, Image++async def main():+ # 1. Create a sandbox and install software+ async with Sandbox.ephemeral(Image.linux("ubuntu", "24.04")) as sb:+ await sb.shell.run("apt-get update -qq && apt-get install -y -qq cowsay")++ # 2. Snapshot — returns an Image+ cowsay_image = await sb.snapshot(name="with-cowsay")++ # 3. Boot from snapshot — cowsay is already installed+ async with Sandbox.ephemeral(cowsay_image) as sb2:+ result = await sb2.shell.run("/usr/games/cowsay hello from snapshot!")+ print(result.stdout)++asyncio.run(main())+```++---++## `sb.snapshot()`++```python+image = await sb.snapshot(name="my-snapshot", stateful=False)+```++| Parameter | Type | Default | Description |+|-----------|------|---------|-------------|+| `name` | `str \| None` | `None` | Optional human-readable label for the snapshot |+| `stateful` | `bool` | `False` | Capture memory state in addition to disk (VMs only) |++**Returns:** an `Image` that can be passed directly to `Sandbox.ephemeral()` or `Sandbox.create()`.++<Callout type="info">+Snapshots are currently supported on Cua Cloud sandboxes. Local sandboxes (Docker, Lume, QEMU) have limited support for snapshots.+</Callout>++---++## Use cases++### Pre-baked environments++Avoid repeating slow setup steps (package installs, model downloads, database migrations) by snapshotting once and forking many times:++```python+# Build the base image once+async with Sandbox.ephemeral(Image.linux()) as sb:+ await sb.shell.run("apt-get update && apt-get install -y python3-pip ffmpeg")+ await sb.shell.run("pip install torch transformers")+ ml_image = await sb.snapshot(name="ml-ready")++# Fork it for each experiment — no reinstall needed+for lr in [0.001, 0.01, 0.1]:+ async with Sandbox.ephemeral(ml_image) as sb:+ await sb.shell.run(f"python train.py --lr {lr}")+```++### Android snapshots++Snapshot works with Android sandboxes too. Sideload APKs or configure the emulator once, then fork:++```python+FDROID_APK = "https://f-droid.org/F-Droid.apk"++async with Sandbox.ephemeral(Image.android("14").apk_install(FDROID_APK)) as sb:+ fdroid_image = await sb.snapshot(name="with-fdroid")++# Fork — F-Droid is already installed+async with Sandbox.ephemeral(fdroid_image) as sb2:+ result = await sb2.shell.run("pm list packages org.fdroid.fdroid")+ assert "org.fdroid.fdroid" in result.stdout+```++### State isolation++Each fork gets its own copy of the disk. Changes in one fork never affect another or the original snapshot:++```python+async with Sandbox.ephemeral(Image.linux()) as sb:+ await sb.shell.run("echo original > /tmp/data.txt")+ base = await sb.snapshot(name="base")++# Fork A writes a file+async with Sandbox.ephemeral(base) as a:+ await a.shell.run("echo fork-a >> /tmp/data.txt")++# Fork B doesn't see Fork A's changes+async with Sandbox.ephemeral(base) as b:+ result = await b.shell.run("cat /tmp/data.txt")+ print(result.stdout) # "original\n" — no trace of fork-a+```++---++## Performance++| Operation | Typical time |+|-----------|-------------|+| Create + install packages | 30–120 s |+| Fork from snapshot | 1–5 s |++On backends that use copy-on-write storage, forking is nearly instant regardless of how large the disk image is. On `dir` storage backends, the fork performs a full copy, so it may be slower for large images.diff --git a/docs/content/docs/cua/reference/sandbox-sdk/interfaces.mdx b/docs/content/docs/cua/reference/sandbox-sdk/interfaces.mdxindex 584b7e0a42..68834504c5 100644--- a/docs/content/docs/cua/reference/sandbox-sdk/interfaces.mdx+++ b/docs/content/docs/cua/reference/sandbox-sdk/interfaces.mdx@@ -1,303 +1,330 @@----title: Sandbox Interfaces-description: Reference for all sb.* sub-interfaces — shell, mouse, keyboard, screen, clipboard, tunnel, mobile, terminal, window+title: Interfaces Reference+description: Auto-generated reference for all cua-sandbox interface classes. Do not edit manually � run scripts/gen_interface_docs.py to regenerate.----Every `Sandbox` instance exposes a set of sub-interfaces for interacting with the running environment. This page documents all of them.+import { Callout } from "fumadocs-ui/components/callout";++<Callout type="info">+ This page is auto-generated from the Python source docstrings.+ Run `python scripts/gen_interface_docs.py` to regenerate after editing interface code.+</Callout>++The sandbox exposes the following interface objects on every `Sandbox` instance:++| Attribute | Class | Purpose |+|-----------|-------|---------|+| `sb.shell` | `Shell` | Run shell commands |+| `sb.mouse` | `Mouse` | Mouse control |+| `sb.keyboard` | `Keyboard` | Keyboard control |+| `sb.screen` | `Screen` | Screenshots and screen info |+| `sb.clipboard` | `Clipboard` | Clipboard read/write |+| `sb.tunnel` | `Tunnel` | Port forwarding |+| `sb.terminal` | `Terminal` | PTY terminal sessions |+| `sb.window` | `Window` | Window management |+| `sb.mobile` | `Mobile` | Mobile-specific actions |----## `sb.shell` — command execution-Run shell commands and get their output.+## `Shell`++Shell command execution.++### Methods++#### `async run(command: str, timeout: int = 30) -> CommandResult`++Run a shell command and return the result.+++----```python-result = await sb.shell.run("ls -la /")-print(result.stdout) # standard output-print(result.stderr) # standard error-print(result.returncode) # exit code (int)-print(result.success) # True if returncode == 0-```-### `await sb.shell.run(command, *, timeout=60) → CommandResult`+## `CommandResult`-| Parameter | Type | Description |-|-----------|------|-------------|-| `command` | `str` | Shell command to run |-| `timeout` | `int` | Seconds before the command is killed (default: 60) |+### Fields-`CommandResult` fields:+| Name | Type |+|------|------|+| `stdout` | `str` |+| `stderr` | `str` |+| `returncode` | `int` |-| Field | Type | Description |-|-------|------|-------------|-| `stdout` | `str` | Standard output |-| `stderr` | `str` | Standard error |-| `returncode` | `int` | Exit code |-| `success` | `bool` | `True` if `returncode == 0` |+### Methods-Multi-line scripts work naturally:+#### `@property+success() -> bool`-```python-result = await sb.shell.run("""- cd /tmp- echo "hello" > file.txt- cat file.txt-""")-print(result.stdout) # "hello\n"-```----## `sb.mouse` — mouse control-All coordinates are in pixels, with `(0, 0)` at the top-left corner.+## `Mouse`-```python-await sb.mouse.move(x, y)-await sb.mouse.click(x, y) # left click-await sb.mouse.right_click(x, y)-await sb.mouse.double_click(x, y)-await sb.mouse.scroll(x, y, dx=0, dy=3) # scroll down 3 units-await sb.mouse.drag(x1, y1, x2, y2) # click-and-drag-await sb.mouse.mouse_down(x, y) # hold button-await sb.mouse.mouse_up(x, y) # release button-```+Mouse control.-### `await sb.mouse.click(x, y, button="left")`+### Methods-| Parameter | Type | Description |-|-----------|------|-------------|-| `x`, `y` | `int` | Pixel coordinates |-| `button` | `str` | `"left"` (default), `"right"`, `"middle"` |+#### `async click(x: int, y: int, button: str = 'left') -> None`-### `await sb.mouse.scroll(x, y, dx=0, dy=0)`+#### `async right_click(x: int, y: int) -> None`++#### `async double_click(x: int, y: int) -> None`++#### `async move(x: int, y: int) -> None`++#### `async scroll(x: int, y: int, scroll_x: int = 0, scroll_y: int = 3) -> None`++#### `async mouse_down(x: int, y: int, button: str = 'left') -> None`++#### `async mouse_up(x: int, y: int, button: str = 'left') -> None`++#### `async drag(start_x: int, start_y: int, end_x: int, end_y: int, button: str = 'left') -> None`-| Parameter | Type | Description |-|-----------|------|-------------|-| `x`, `y` | `int` | Position to scroll at |-| `dx` | `int` | Horizontal scroll units (positive = right) |-| `dy` | `int` | Vertical scroll units (positive = down) |----## `sb.keyboard` — keyboard control-```python-await sb.keyboard.type("Hello, world!") # type a string-await sb.keyboard.press("Return") # press a key-await sb.keyboard.press("ctrl+c") # key combo-await sb.keyboard.press("cmd+space") # macOS: Spotlight-await sb.keyboard.press("super+d") # Windows: show desktop-await sb.keyboard.key_down("shift") # hold a key-await sb.keyboard.key_up("shift") # release a held key-```+## `Keyboard`++Keyboard control.++### Methods++#### `async type(text: str) -> None`-### `await sb.keyboard.press(keys)`+Type a string of text.-`keys` can be a string shorthand or a list:+#### `async keypress(keys: Union[List[str], str]) -> None`-```python-await sb.keyboard.press("ctrl+c")-await sb.keyboard.press(["ctrl", "c"]) # equivalent-await sb.keyboard.press("Return")-await sb.keyboard.press("Escape")-await sb.keyboard.press("Tab")-await sb.keyboard.press("F5")-```+Press a key combination (e.g. ["ctrl", "c"] or "enter").++#### `async key_down(key: str) -> None`++#### `async key_up(key: str) -> None`-Common modifier keys: `ctrl`, `shift`, `alt`, `cmd` (macOS), `super` (Windows/Linux).----## `sb.screen` — screen info-```python-png_bytes = await sb.screenshot() # convenience method on Sandbox-b64_str = await sb.screenshot_base64() # base64-encoded PNG string-width, height = await sb.screen.size() # screen dimensions in pixels-```+## `Screen`++Screen capture and info.-### `await sb.screenshot() → bytes`+### Methods-Returns a PNG image as raw bytes.+#### `async screenshot(format: str = 'png', quality: int = 95) -> bytes`-```python-png = await sb.screenshot()-with open("shot.png", "wb") as f:- f.write(png)-```+Capture a screenshot and return raw image bytes.-### `await sb.screenshot_base64() → str`+Args:+ format: "png" (lossless, default) or "jpeg" (lossy, ~5-10x smaller).+ quality: JPEG quality 1-95, ignored for PNG.-Returns a base64-encoded PNG string, ready to embed in HTML or pass to LLM vision APIs.+#### `async screenshot_base64(format: str = 'png', quality: int = 95) -> str`-```python-b64 = await sb.screenshot_base64()-# use directly in an OpenAI / Anthropic vision message-```+Capture a screenshot and return as a base64-encoded string.-### `await sb.screen.size() → tuple[int, int]`+#### `async size() -> Tuple[int, int]`-Returns `(width, height)` of the sandbox display.+Return (width, height) of the screen.-```python-w, h = await sb.screen.size()-cx, cy = w // 2, h // 2 # center of screen-await sb.mouse.click(cx, cy)-```----## `sb.clipboard` — clipboard access-Read and write the sandbox clipboard.+## `Clipboard`++Clipboard read/write.++### Methods-```python-await sb.clipboard.write("Hello from Python")-text = await sb.clipboard.read()-print(text) # "Hello from Python"-```+#### `async get() -> str`-### `await sb.clipboard.write(text: str)`+Return the current clipboard text.-Writes a string to the clipboard.+#### `async set(text: str) -> None`-### `await sb.clipboard.read() → str`+Set the clipboard text.-Returns the current clipboard contents as a string.----## `sb.tunnel` — port forwarding-Forward ports from inside the sandbox to `localhost` on the host. Useful for accessing web servers, databases, or Chrome DevTools running inside the sandbox.+## `Tunnel`-```python-async with sb.tunnel.forward(8080) as tunnel:- print(tunnel.url) # "http://localhost:<random-port>"- # make requests to the forwarded port- import httpx- r = httpx.get(tunnel.url)-```+Port-forwarding interface — exposes sandbox ports on the host.-Forward multiple ports at once:+### Methods-```python-async with sb.tunnel.forward(8080, 9222) as tunnels:- app_url = tunnels[8080].url- devtools_url = tunnels[9222].url-```+#### `forward(*ports) -> _TunnelContext`-### `sb.tunnel.forward(*ports) → async context manager`+Forward one or more sandbox ports (or abstract sockets) to the host.-Returns a context manager. On enter, starts forwarding; on exit, tears down the tunnel.+*ports* may be:+- ``int`` — TCP port inside the sandbox (e.g. ``8080``)+- ``str`` — Android abstract socket name (e.g. ``"chrome_devtools_remote"``)-| Value | Type | Description |-|-------|------|-------------|-| `*ports` | `int` | One or more ports to forward from the sandbox |+Returns a context manager (or awaitable) that yields:+- a single :class:`TunnelInfo` when one target is given+- a ``dict[sandbox_port, TunnelInfo]`` when multiple targets are given-The context manager yields:-- A single `TunnelInfo` when one port is passed-- A `dict[int, TunnelInfo]` when multiple ports are passed+Example — Chrome DevTools over ADB::-`TunnelInfo` fields:+ async with sb.tunnel.forward("chrome_devtools_remote") as t:+ # http://localhost:<random>/json lists CDP targets+ print(t.url)-| Field | Type | Description |-|-------|------|-------------|-| `url` | `str` | `http://localhost:<host-port>` |-| `host_port` | `int` | The randomly assigned host port |-| `sandbox_port` | `int` | The original port inside the sandbox |----## `sb.mobile` — touch and gestures (Android)-Available on Android sandboxes only. Uses ADB under the hood.+## `TunnelInfo`-```python-await sb.mobile.tap(x, y)-await sb.mobile.long_press(x, y, duration_ms=1000)-await sb.mobile.double_tap(x, y)-await sb.mobile.swipe(x1, y1, x2, y2, duration_ms=300)-await sb.mobile.scroll_up()-await sb.mobile.scroll_down()-await sb.mobile.scroll_left()-await sb.mobile.scroll_right()-```+A single forwarded port.-### Multi-touch gestures+### Methods-Use `sb.mobile.gesture()` for multi-finger interactions like pinch-to-zoom:+#### `@property+url() -> str`-```python-w, h = await sb.screen.size()-cx, cy = w // 2, h // 2+#### `async close() -> None`-# Pinch open (zoom in) — two fingers moving outward-await sb.mobile.gesture(- (cx - 20, cy), (cx - 200, cy), # finger 0: start → end- (cx + 20, cy), (cx + 200, cy), # finger 1: start → end-)+Close this tunnel (no-op if already closed or inside a context manager).-# Pinch close (zoom out) — two fingers moving inward-await sb.mobile.gesture(- (cx - 200, cy), (cx - 20, cy),- (cx + 200, cy), (cx + 20, cy),-)-```-### `await sb.mobile.gesture(*points)`+----Takes an even number of `(x, y)` tuples: alternating start and end points for each finger.-```python-# Two fingers: finger0_start, finger0_end, finger1_start, finger1_end-await sb.mobile.gesture(- (x0_start, y0_start), (x0_end, y0_end),- (x1_start, y1_start), (x1_end, y1_end),-)-```+## `Terminal`----+PTY terminal sessions.++### Methods++#### `async create(shell: str = 'bash', cols: int = 80, rows: int = 24) -> dict`-## `sb.terminal` — interactive PTY shell+Create a new PTY session. Returns {"pid": int, "cols": int, "rows": int}.-Open an interactive terminal session with full PTY support. Use this when you need to run interactive programs that expect a real terminal.+#### `async send_input(pid: int, data: str) -> None`++Send input to a PTY session.++#### `async resize(pid: int, cols: int, rows: int) -> None`++Resize a PTY session.++#### `async close(pid: int) -> Optional[int]`++Close a PTY session. Returns exit code.-```python-term = await sb.terminal.open()-await term.send("python3\n")-output = await term.read()-await term.send("print('hello')\n")-output = await term.read()-print(output)-await term.close()-```----## `sb.window` — window management-Control the sandbox window (mainly relevant for VNC/desktop sessions).+## `Window`++Window management.++### Methods++#### `async get_active_title() -> str`++Return the title of the currently focused window.-```python-await sb.window.maximize()-await sb.window.close()-```----## `Localhost` — direct host control-`Localhost` gives you the same interface as `Sandbox` but operates directly on the machine running Python, with no sandbox involved. Useful for local automation or testing.+## `Mobile`-```python-from cua import Localhost+Mobile (Android) touch and hardware-key control.-async with Localhost.connect() as host:- result = await host.shell.run("echo hello")- await host.mouse.click(100, 200)- png = await host.screenshot()-```+All touch coordinates are in screen pixels. Single-touch methods use+``input tap/swipe`` via ``adb shell``. Multi-touch gestures delegate to+the ``multitouch_gesture`` transport action, which uses ``adb root`` ++MT Protocol B ``sendevent`` for reliable injection on both local and cloud+transports.++### Methods++#### `async tap(x: int, y: int) -> None`++#### `async long_press(x: int, y: int, duration_ms: int = 1000) -> None`++#### `async double_tap(x: int, y: int, delay: float = 0.1) -> None`++#### `async type_text(text: str) -> None`++#### `async swipe(x1: int, y1: int, x2: int, y2: int, duration_ms: int = 300) -> None`++#### `async scroll_up(x: int, y: int, distance: int = 600, duration_ms: int = 400) -> None`++#### `async scroll_down(x: int, y: int, distance: int = 600, duration_ms: int = 400) -> None`++#### `async scroll_left(x: int, y: int, distance: int = 400, duration_ms: int = 300) -> None`++#### `async scroll_right(x: int, y: int, distance: int = 400, duration_ms: int = 300) -> None`++#### `async fling(x1: int, y1: int, x2: int, y2: int) -> None`++#### `async gesture(duration_ms: int = 400, steps: int = 0, *finger_paths) -> None`++Inject an arbitrary N-finger gesture via MT Protocol B ``sendevent``.++Each positional argument is a sequence of ``(x, y)`` waypoints for one+finger. Pass an even number of ``(x, y)`` tuples and they are paired+into start/end positions per finger::++ # two-finger pinch-out+ await mobile.gesture(+ (cx - 20, cy), (cx - 200, cy), # finger 0+ (cx + 20, cy), (cx + 200, cy), # finger 1+ )++Delegates to the ``multitouch_gesture`` transport action, which uses+``adb root`` + MT Protocol B ``sendevent`` for reliable injection on+both local ADB and cloud HTTP transports.++Args:+ *finger_paths: Alternating start/end ``(x, y)`` tuples, two per finger.+ Must have an even length >= 4 (at least 2 fingers × 2 points).+ duration_ms: Total gesture duration in milliseconds.+ steps: Interpolation steps (0 = auto: duration_ms // 20, min 5).++#### `async pinch_in(cx: int, cy: int, spread: int = 300, duration_ms: int = 400) -> None`++Pinch-in (zoom out) with two real simultaneous fingers.++#### `async pinch_out(cx: int, cy: int, spread: int = 300, duration_ms: int = 400) -> None`++Pinch-out (zoom in) with two real simultaneous fingers.++#### `async key(keycode: int) -> None`++#### `async home() -> None`++#### `async back() -> None`++#### `async recents() -> None`++#### `async power() -> None`++#### `async volume_up() -> None`++#### `async volume_down() -> None`++#### `async enter() -> None`++#### `async backspace() -> None`++#### `async wake() -> None`++#### `async notifications() -> None`++#### `async close_notifications() -> None`+++----All `sb.*` interfaces (`shell`, `mouse`, `keyboard`, `screen`, `clipboard`) are available on a `Localhost` instance. `tunnel` and `mobile` are not applicable.diff --git a/libs/lume/src/Server/Server.swift b/libs/lume/src/Server/Server.swiftindex 9cf8f791fc..ee1fc4939c 100644--- a/libs/lume/src/Server/Server.swift+++ b/libs/lume/src/Server/Server.swift@@ -148,6 +148,19 @@ final class Server: @unchecked Sendable {return true}+ func extractParams(_ request: HTTPRequest) -> [String: String] {+ var params: [String: String] = [:]+ let routeParts = path.split(separator: "/")+ let requestPathOnly = request.path.split(separator: "?", maxSplits: 1)[0]+ let requestParts = requestPathOnly.split(separator: "/")++ for (routePart, requestPart) in zip(routeParts, requestParts) {+ if routePart.hasPrefix(":") {+ params[String(routePart.dropFirst())] = String(requestPart)+ }+ }+ return params+ }}// MARK: - Properties@@ -155,8 +168,20 @@ final class Server: @unchecked Sendable {private let portNumber: UInt16private let controller: LumeControllerprivate var routes: [Route]- private var serverChannel: (any Channel)?- private var eventLoopGroup: (any EventLoopGroup)?+ // _channelLock guards both _serverChannel and _eventLoopGroup, which are+ // written in start() and read in stop() — potentially from different tasks.+ private let _channelLock = NSLock()+ private var _serverChannel: (any Channel)?+ private var _eventLoopGroup: (any EventLoopGroup)?++ private var serverChannel: (any Channel)? {+ get { _channelLock.withLock { _serverChannel } }+ set { _channelLock.withLock { _serverChannel = newValue } }+ }+ private var eventLoopGroup: (any EventLoopGroup)? {+ get { _channelLock.withLock { _eventLoopGroup } }+ set { _channelLock.withLock { _eventLoopGroup = newValue } }+ }// MARK: - Initializationdiff --git a/libs/python/cua-sandbox/cua_sandbox/__init__.py b/libs/python/cua-sandbox/cua_sandbox/__init__.pyindex e6387e70cb..d6196448e8 100644--- a/libs/python/cua-sandbox/cua_sandbox/__init__.py+++ b/libs/python/cua-sandbox/cua_sandbox/__init__.py@@ -22,6 +22,11 @@ from cua_sandbox._auth import login, whoamifrom cua_sandbox._config import configurefrom cua_sandbox.image import Imagefrom cua_sandbox.localhost import Localhost, localhost+from cua_sandbox.runtime.compat import (+ RuntimeSupport,+ check_local_support,+ skip_if_unsupported,+)from cua_sandbox.sandbox import Sandbox, SandboxInfo, sandboxfrom cua_sandbox.transport.cloud import CloudTransport@@ -36,4 +41,7 @@ __all__ = ["Localhost","localhost","CloudTransport",+ "RuntimeSupport",+ "check_local_support",+ "skip_if_unsupported",]diff --git a/libs/python/cua-sandbox/cua_sandbox/_config.py b/libs/python/cua-sandbox/cua_sandbox/_config.pyindex d96efbb46d..0f9872a559 100644--- a/libs/python/cua-sandbox/cua_sandbox/_config.py+++ b/libs/python/cua-sandbox/cua_sandbox/_config.py@@ -50,7 +50,7 @@ def get_api_key(override: Optional[str] = None) -> Optional[str]:def get_base_url() -> str:- return _global_config.base_url+ return os.environ.get("CUA_BASE_URL") or _global_config.base_urldef _read_credentials_key() -> Optional[str]:diff --git a/libs/python/cua-sandbox/cua_sandbox/builder/executor.py b/libs/python/cua-sandbox/cua_sandbox/builder/executor.pyindex cacfb4659e..450abab66d 100644--- a/libs/python/cua-sandbox/cua_sandbox/builder/executor.py+++ b/libs/python/cua-sandbox/cua_sandbox/builder/executor.py@@ -1,4 +1,4 @@-"""Layer executor — boots a QEMU VM and runs Image layers via computer-server API.+"""Layer executor — runs Image layers via computer-server API.Given a running computer-server at some URL, translates each Image layer dictinto shell commands and executes them sequentially.@@ -6,7 +6,10 @@ into shell commands and executes them sequentially.from __future__ import annotations+import base64+import jsonimport logging+import osfrom typing import Anyimport httpx@@ -17,9 +20,10 @@ logger = logging.getLogger(__name__)class LayerExecutor:"""Execute Image layer specs against a running computer-server."""- def __init__(self, base_url: str, timeout: float = 600):+ def __init__(self, base_url: str, timeout: float = 600, os_type: str = "linux"):self.base_url = base_url.rstrip("/")self.timeout = timeout+ self.os_type = os_type # "linux", "macos", "windows", "android"async def run_command(self, command: str, timeout: float | None = None) -> dict:"""Run a shell command via computer-server and return the result."""@@ -28,7 +32,7 @@ class LayerExecutor:# computer-server uses SSE on /cmdresp = await client.post(f"{self.base_url}/cmd",- json={"command": "run_command", "command_args": command, "timeout": int(t)},+ json={"command": "run_command", "params": {"command": command}},timeout=t,)resp.raise_for_status()@@ -37,8 +41,6 @@ class LayerExecutor:result: dict[str, Any] = {}for line in resp.text.splitlines():if line.startswith("data: "):- import json-try:data = json.loads(line[6:])if isinstance(data, dict):@@ -48,6 +50,30 @@ class LayerExecutor:return result+ async def write_file(self, path: str, content_b64: str, timeout: float | None = None) -> dict:+ """Write a file via computer-server write_bytes command."""+ t = timeout or self.timeout+ async with httpx.AsyncClient(timeout=t) as client:+ resp = await client.post(+ f"{self.base_url}/cmd",+ json={+ "command": "write_bytes",+ "params": {"path": path, "content_b64": content_b64},+ },+ timeout=t,+ )+ resp.raise_for_status()+ result: dict[str, Any] = {}+ for line in resp.text.splitlines():+ if line.startswith("data: "):+ try:+ data = json.loads(line[6:])+ if isinstance(data, dict):+ result.update(data)+ except (json.JSONDecodeError, ValueError):+ pass+ return result+async def execute_layer(self, layer: dict) -> dict:"""Execute a single Image layer and return the result."""lt = layer["type"]@@ -63,8 +89,9 @@ class LayerExecutor:lt = layer["type"]logger.info(f"Executing layer {i + 1}/{len(layers)}: {lt}")result = await self.execute_layer(layer)- rc = result.get("returncode", result.get("return_code", -1))- if rc not in (0, None):+ rc = result.get("return_code", result.get("returncode", -1))+ success = result.get("success", rc == 0)+ if not success or rc not in (0, None):logger.error(f"Layer {lt} failed (rc={rc}): {result.get('stderr', '')}")raise RuntimeError(f"Layer {i + 1} ({lt}) failed with exit code {rc}: "@@ -76,16 +103,37 @@ class LayerExecutor:# ── Per-layer-type handlers ──────────────────────────────────────────+ def _is_windows(self) -> bool:+ return self.os_type == "windows"+async def _exec_run(self, layer: dict) -> dict:- return await self.run_command(layer["command"])+ cmd = layer["command"]+ if self._is_windows():+ pass+ elif self.os_type == "linux":+ # Linux containers run as a non-root user; use sudo for root access+ cmd = f"sudo bash -c '. /etc/profile.d/cua-env.sh 2>/dev/null; {_bash_escape(cmd)}'"+ elif self.os_type == "macos":+ # macOS VMs: default password is "lume"; pipe it to sudo -S for root access+ cmd = (+ f"echo lume | sudo -S bash -c "+ f"'. /etc/profile.d/cua-env.sh 2>/dev/null; {_bash_escape(cmd)}'"+ )+ else:+ # Android: stock Android uses mksh/sh, not bash; env file is pushed by android_emulator+ cmd = f"sh -c '. /data/local/tmp/.cua_env 2>/dev/null; {_bash_escape(cmd)}'"+ return await self.run_command(cmd)async def _exec_apt_install(self, layer: dict) -> dict:pkgs = " ".join(layer["packages"])- return await self.run_command(f"apt-get update && apt-get install -y {pkgs}")+ return await self.run_command(+ f"sudo DEBIAN_FRONTEND=noninteractive apt-get update -qq && "+ f"sudo DEBIAN_FRONTEND=noninteractive apt-get install -y {pkgs}"+ )async def _exec_brew_install(self, layer: dict) -> dict:pkgs = " ".join(layer["packages"])- return await self.run_command(f"brew install {pkgs}")+ return await self.run_command(f"brew install {pkgs}", timeout=900)async def _exec_choco_install(self, layer: dict) -> dict:pkgs = " ".join(layer["packages"])@@ -103,22 +151,118 @@ class LayerExecutor:async def _exec_uv_install(self, layer: dict) -> dict:pkgs = " ".join(layer["packages"])+ if self._is_windows():+ return await self.run_command(+ f"uv add --directory %USERPROFILE%\\cua-server {pkgs}",+ timeout=600,+ )+ # Linux/macOS: install uv if missing, then install packages system-widereturn await self.run_command(- f"uv add --directory %USERPROFILE%\\cua-server {pkgs}",+ f"command -v uv >/dev/null 2>&1 || "+ f"(curl -LsSf https://astral.sh/uv/install.sh | sh && "+ f'export PATH="$HOME/.cargo/bin:$HOME/.local/bin:$PATH") && '+ f"uv pip install --system {pkgs}",timeout=600,)async def _exec_pip_install(self, layer: dict) -> dict:pkgs = " ".join(layer["packages"])- return await self.run_command(f"pip install {pkgs}", timeout=600)+ if self._is_windows():+ return await self.run_command(f"pip install {pkgs}", timeout=600)+ return await self.run_command(f"pip3 install --break-system-packages {pkgs}", timeout=600)async def _exec_env(self, layer: dict) -> dict:- # Set persistent env vars via setx (Windows) or export (Linux)- cmds = []- for k, v in layer.get("variables", {}).items():- cmds.append(f'setx {k} "{v}"')- return await self.run_command(" && ".join(cmds)) if cmds else {"returncode": 0}+ import re as _re++ variables = layer.get("variables", {})+ if not variables:+ return {"success": True, "return_code": 0}+ if self._is_windows():+ cmds = [f'setx {k} "{v}"' for k, v in variables.items()]+ return await self.run_command(" && ".join(cmds))+ # Validate keys before composing any shell commands+ for k in variables:+ if not _re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", k):+ raise ValueError(f"Unsafe env var name: {k!r}")+ # Linux/macOS: append to /etc/environment for persistence.+ # Write each line as a separate printf call so values are treated as+ # literals — no heredoc expansion, no quote stripping.+ sudo = "echo lume | sudo -S" if self.os_type == "macos" else "sudo"+ result: dict = {"success": True, "return_code": 0}+ for k, v in variables.items():+ safe_v = v.replace("'", "'\\''")+ result = await self.run_command(+ f"printf '%s=%s\\n' '{k}' '{safe_v}' | {sudo} tee -a /etc/environment > /dev/null"+ )+ if not result.get("success"):+ return result+ return resultasync def _exec_copy(self, layer: dict) -> dict:- # copy is handled differently — needs file transfer, not shell- raise NotImplementedError("copy layers require file transfer (not yet implemented)")+ src = layer["src"]+ dst = layer["dst"]+ if not os.path.exists(src):+ return {"success": False, "return_code": 1, "error": f"Source not found: {src}"}+ with open(src, "rb") as f:+ content_b64 = base64.b64encode(f.read()).decode()+ if self._is_windows():+ dst_dir = dst.rsplit("\\", 1)[0] if "\\" in dst else dst.rsplit("/", 1)[0]+ if dst_dir:+ await self.run_command(f'mkdir "{dst_dir}"')+ result = await self.write_file(dst, content_b64)+ if not result.get("success", False):+ return {"success": False, "return_code": 1, "error": result.get("error", "")}+ return {"success": True, "return_code": 0}+ # Linux/macOS: write to temp then sudo mv to handle root-owned destinations+ import posixpath++ basename = posixpath.basename(dst)+ tmp_path = f"/tmp/_cua_copy_{basename}"+ result = await self.write_file(tmp_path, content_b64)+ if not result.get("success", False):+ return {"success": False, "return_code": 1, "error": result.get("error", "")}+ sudo = "echo lume | sudo -S" if self.os_type == "macos" else "sudo"+ dst_dir = posixpath.dirname(dst)+ if dst_dir and dst_dir != "/":+ await self.run_command(f"{sudo} mkdir -p {_sh_quote(dst_dir)}")+ r = await self.run_command(f"{sudo} mv {_sh_quote(tmp_path)} {_sh_quote(dst)}")+ rc = r.get("return_code", r.get("returncode", -1))+ return {"success": rc == 0, "return_code": rc, "stderr": r.get("stderr", "")}++ async def _exec_expose(self, layer: dict) -> dict:+ # Expose is a no-op at layer execution time — ports are mapped by the runtime+ return {"success": True, "return_code": 0}++ async def _exec_apk_install(self, layer: dict) -> dict:+ # APK install: transfer the APK file to the device and install via adb+ apk_paths = layer.get("packages", [])+ results = []+ for apk_path in apk_paths:+ if not os.path.exists(apk_path):+ return {+ "success": False,+ "return_code": 1,+ "error": f"APK not found: {apk_path}",+ }+ remote_path = f"/data/local/tmp/{os.path.basename(apk_path)}"+ with open(apk_path, "rb") as f:+ content_b64 = base64.b64encode(f.read()).decode()+ await self.write_file(remote_path, content_b64)+ r = await self.run_command(f"pm install -r {remote_path}", timeout=120)+ results.append(r)+ return results[-1] if results else {"success": True, "return_code": 0}++ async def _exec_pwa_install(self, layer: dict) -> dict:+ # PWA install — just a placeholder; actual install happens via the sandbox+ return {"success": True, "return_code": 0}+++def _bash_escape(s: str) -> str:+ """Escape a command string for embedding inside single-quoted bash -c '...'."""+ # Replace single quotes: end the single-quote, add escaped single-quote, restart+ return s.replace("'", "'\\''")+++def _sh_quote(s: str) -> str:+ """Wrap string in single quotes, escaping any existing single quotes."""+ return "'" + _bash_escape(s) + "'"diff --git a/libs/python/cua-sandbox/cua_sandbox/image.py b/libs/python/cua-sandbox/cua_sandbox/image.pyindex 5b266d861d..130407c95e 100644--- a/libs/python/cua-sandbox/cua_sandbox/image.py+++ b/libs/python/cua-sandbox/cua_sandbox/image.py@@ -120,6 +120,7 @@ class Image:_registry: Optional[str] = None # OCI registry reference_disk_path: Optional[str] = None # local disk file path (qcow2, vhdx, raw)_agent_type: Optional[str] = None # e.g. "osworld" for OSWorld Flask server+ _snapshot_source: Optional[Dict[str, Any]] = None # set by Sandbox.snapshot()# ── Constructors ─────────────────────────────────────────────────────@@ -236,6 +237,7 @@ class Image:_registry=self._registry,_disk_path=self._disk_path,_agent_type=self._agent_type,+ _snapshot_source=self._snapshot_source,)def _with(self, **kwargs) -> Image:@@ -252,6 +254,7 @@ class Image:"_registry": self._registry,"_disk_path": self._disk_path,"_agent_type": self._agent_type,+ "_snapshot_source": self._snapshot_source,}fields.update(kwargs)return Image(**fields)@@ -413,6 +416,33 @@ class Image:lines.append(layer["command"])return "\n".join(lines) + "\n"+ def local_support(self): # -> RuntimeSupport (lazy import avoids circular dep)+ """Check whether this image can run locally on the current host.++ Returns a :class:`~cua_sandbox.runtime.compat.RuntimeSupport` describing:++ - ``supported`` — runtime is available or auto-installable on this OS+ - ``hw_accel`` — hardware acceleration (HVF / KVM / Hyper-V) is available+ - ``runtime_installed`` — runtime binary found right now (no install needed)+ - ``auto_installable`` — SDK can install the runtime automatically+ - ``reason`` — human-readable explanation++ In tests, use the bundled helper instead of checking manually::++ from cua_sandbox.runtime.compat import skip_if_unsupported++ async def test_something():+ skip_if_unsupported(Image.macos())+ async with Sandbox.ephemeral(Image.macos(), local=True) as sb:+ ...+ """+ from cua_sandbox.runtime.compat import ( # noqa: F401+ RuntimeSupport,+ check_local_support,+ )++ return check_local_support(self)+def __repr__(self) -> str:reg = f", registry={self._registry!r}" if self._registry else ""return (diff --git a/libs/python/cua-sandbox/cua_sandbox/interfaces/clipboard.py b/libs/python/cua-sandbox/cua_sandbox/interfaces/clipboard.pyindex 8e1a6052e7..8cba8dabba 100644--- a/libs/python/cua-sandbox/cua_sandbox/interfaces/clipboard.py+++ b/libs/python/cua-sandbox/cua_sandbox/interfaces/clipboard.py@@ -13,7 +13,10 @@ class Clipboard:async def get(self) -> str:"""Return the current clipboard text."""- return await self._t.send("copy_to_clipboard")+ result = await self._t.send("copy_to_clipboard")+ if isinstance(result, dict):+ return result.get("content", "")+ return resultasync def set(self, text: str) -> None:"""Set the clipboard text."""diff --git a/libs/python/cua-sandbox/cua_sandbox/interfaces/mouse.py b/libs/python/cua-sandbox/cua_sandbox/interfaces/mouse.pyindex b7ded5037a..b6b7857256 100644--- a/libs/python/cua-sandbox/cua_sandbox/interfaces/mouse.py+++ b/libs/python/cua-sandbox/cua_sandbox/interfaces/mouse.py@@ -36,5 +36,7 @@ class Mouse:self, start_x: int, start_y: int, end_x: int, end_y: int, button: str = "left") -> None:await self._t.send(- "drag", start_x=start_x, start_y=start_y, end_x=end_x, end_y=end_y, button=button+ "drag",+ path=[[start_x, start_y], [end_x, end_y]],+ button=button,)diff --git a/libs/python/cua-sandbox/cua_sandbox/runtime/android_emulator.py b/libs/python/cua-sandbox/cua_sandbox/runtime/android_emulator.pyindex d833a7c871..4d26b062bc 100644--- a/libs/python/cua-sandbox/cua_sandbox/runtime/android_emulator.py+++ b/libs/python/cua-sandbox/cua_sandbox/runtime/android_emulator.py@@ -70,6 +70,8 @@ def _sdk_path() -> Path:Path.home() / "Library" / "Android" / "sdk", # Android Studio (macOS)Path("/opt/android"), # docker-androidPath.home() / "Android" / "Sdk", # Linux+ Path(os.environ.get("LOCALAPPDATA", "")) / "Android" / "Sdk", # Android Studio (Windows)+ Path.home() / "AppData" / "Local" / "Android" / "Sdk", # Windows fallback]for p in common:if (p / "emulator").exists():@@ -81,9 +83,12 @@ def _ensure_sdk() -> Path:"""Ensure Android SDK command-line tools, emulator, and platform-tools are installed."""sdk = _sdk_path()- emulator_bin = sdk / "emulator" / "emulator"- sdkmanager_bin = sdk / "cmdline-tools" / "latest" / "bin" / "sdkmanager"- adb_bin = sdk / "platform-tools" / "adb"+ _win = _plat.system().lower() == "windows"+ _ext = ".exe" if _win else ""+ _bat = ".bat" if _win else ""+ emulator_bin = sdk / "emulator" / f"emulator{_ext}"+ sdkmanager_bin = sdk / "cmdline-tools" / "latest" / "bin" / f"sdkmanager{_bat}"+ adb_bin = sdk / "platform-tools" / f"adb{_ext}"if emulator_bin.exists() and adb_bin.exists():return sdk@@ -98,10 +103,10 @@ def _ensure_sdk() -> Path:tools_url = f"https://dl.google.com/android/repository/commandlinetools-mac-{_CMDLINE_TOOLS_VERSION}_latest.zip"elif system == "linux":tools_url = f"https://dl.google.com/android/repository/commandlinetools-linux-{_CMDLINE_TOOLS_VERSION}_latest.zip"+ elif system == "windows":+ tools_url = f"https://dl.google.com/android/repository/commandlinetools-win-{_CMDLINE_TOOLS_VERSION}_latest.zip"else:- raise RuntimeError(- "Android SDK auto-install not supported on Windows. Install Android Studio manually."- )+ raise RuntimeError(f"Android SDK auto-install not supported on {system}.")import urllib.requestimport zipfile@@ -121,7 +126,7 @@ def _ensure_sdk() -> Path:for f in (sdk / "cmdline-tools" / "latest" / "bin").iterdir():f.chmod(0o755)- sdkmanager_bin = sdk / "cmdline-tools" / "latest" / "bin" / "sdkmanager"+ sdkmanager_bin = sdk / "cmdline-tools" / "latest" / "bin" / f"sdkmanager{_bat}"if not sdkmanager_bin.exists():raise RuntimeError(f"sdkmanager not found at {sdkmanager_bin}")@@ -190,15 +195,18 @@ def _find_free_emulator_port() -> int:def _find_bin(sdk: Path, name: str) -> str:- """Find a binary in the SDK."""- candidates = [- sdk / "emulator" / name,- sdk / "platform-tools" / name,- sdk / "cmdline-tools" / "latest" / "bin" / name,+ """Find a binary in the SDK, handling .exe/.bat on Windows."""+ exts = ["", ".exe", ".bat"] if _plat.system().lower() == "windows" else [""]+ dirs = [+ sdk / "emulator",+ sdk / "platform-tools",+ sdk / "cmdline-tools" / "latest" / "bin",]- for c in candidates:- if c.exists():- return str(c)+ for d in dirs:+ for ext in exts:+ c = d / f"{name}{ext}"+ if c.exists():+ return str(c)# Fall back to PATHfound = shutil.which(name)if found:@@ -355,6 +363,31 @@ class AndroidEmulatorRuntime(Runtime):async def _apply_layers(self, image: Image, adb: str, env: dict) -> None:"""Apply image layers post-boot (APK installs, shell commands, etc.)."""serial = f"emulator-{self.adb_port - 1}"++ # Write image env vars to a persistent file so every subsequent+ # adb shell command (including those from the transport) can source it.+ if image._env:+ import re+ import shlex+ import tempfile++ lines = []+ for k, v in image._env:+ if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", k):+ raise ValueError(f"Invalid environment variable name: {k!r}")+ lines.append(f"export {k}={shlex.quote(v)}")+ exports = "\n".join(lines) + "\n"+ with tempfile.NamedTemporaryFile(mode="w", suffix=".sh", delete=False) as f:+ f.write(exports)+ tmp_path = f.name+ subprocess.run(+ [adb, "-s", serial, "push", tmp_path, "/data/local/tmp/.cua_env"],+ capture_output=True,+ env=env,+ timeout=10,+ )+ Path(tmp_path).unlink(missing_ok=True)+for layer in image._layers:lt = layer["type"]if lt == "apk_install":@@ -466,10 +499,16 @@ class AndroidEmulatorRuntime(Runtime):keytool = str(jdk_bin / "keytool") if (jdk_bin / "keytool").exists() else "keytool"# ── 1. Ensure bubblewrap CLI is on PATH ──────────────────────────────- bw = shutil.which("bubblewrap")+ # Augment PATH with common Homebrew node locations so shutil.which finds them+ # even when the process was launched without a login shell.+ extra_node_paths = ["/opt/homebrew/bin", "/usr/local/bin"]+ augmented_path = os.pathsep.join(extra_node_paths) + os.pathsep + env.get("PATH", "")+ env["PATH"] = augmented_path++ bw = shutil.which("bubblewrap", path=augmented_path)if not bw:- node = shutil.which("node")- npm = shutil.which("npm")+ node = shutil.which("node", path=augmented_path)+ npm = shutil.which("npm", path=augmented_path)if not node or not npm:raise RuntimeError("node/npm not found on PATH; required for pwa_install.\n"@@ -548,9 +587,20 @@ class AndroidEmulatorRuntime(Runtime):# ── 3. Determine package ID and cache directory ──────────────────────if not package_name:+ import re+host = urlparse(manifest_url).hostname or ""parts = [p for p in reversed(host.split(".")) if p]- package_name = ".".join(parts) if parts else "com.cua.pwa"+ # Sanitize each part: replace non-alphanumeric/underscore chars with _,+ # prefix with _ if starts with a digit (invalid Java identifier start).+ sanitized = []+ for part in parts:+ part = re.sub(r"[^a-zA-Z0-9_]", "_", part)+ if part and part[0].isdigit():+ part = "_" + part+ if part:+ sanitized.append(part)+ package_name = ".".join(sanitized) if sanitized else "com.cua.pwa"cache_key = hashlib.sha256(f"{manifest_url}|{package_name}".encode()).hexdigest()[:12]cache_dir = Path.home() / ".cua" / "cua-sandbox" / "pwa-cache" / cache_key@@ -631,7 +681,7 @@ class AndroidEmulatorRuntime(Runtime):# ── 6. Generate twa-manifest.json via _bw_init.js ────────────────────bw_init_js = Path(__file__).parent / "_bw_init.js"- node = shutil.which("node")+ node = shutil.which("node", path=augmented_path)if not node:raise RuntimeError("node not found on PATH; required for pwa_install")@@ -649,6 +699,7 @@ class AndroidEmulatorRuntime(Runtime):],capture_output=True,text=True,+ env=env,timeout=60,)if init_result.returncode != 0:@@ -661,6 +712,7 @@ class AndroidEmulatorRuntime(Runtime):capture_output=True,text=True,cwd=str(cache_dir),+ env=env,timeout=300,)if update_result.returncode != 0:@@ -672,7 +724,7 @@ class AndroidEmulatorRuntime(Runtime):contents_home = jdk_bundle / "Contents" / "Home"gradle_java_home = str(contents_home) if contents_home.exists() else str(jdk_bundle)bw_env = {- **os.environ,+ **env,"JAVA_HOME": gradle_java_home,"BUBBLEWRAP_KEYSTORE_PASSWORD": keystore_password,"BUBBLEWRAP_KEY_PASSWORD": keystore_password,diff --git a/libs/python/cua-sandbox/cua_sandbox/runtime/base.py b/libs/python/cua-sandbox/cua_sandbox/runtime/base.pyindex 5a6739c80a..6364237725 100644--- a/libs/python/cua-sandbox/cua_sandbox/runtime/base.py+++ b/libs/python/cua-sandbox/cua_sandbox/runtime/base.py@@ -3,7 +3,7 @@from __future__ import annotationsfrom abc import ABC, abstractmethod-from dataclasses import dataclass+from dataclasses import dataclass, fieldfrom typing import TYPE_CHECKING, Optionalfrom cua_sandbox.image import Image@@ -12,6 +12,16 @@ if TYPE_CHECKING:pass+@dataclass+class CheckpointInfo:+ """Metadata for a saved checkpoint / snapshot of a sandbox."""++ name: str+ runtime_type: str+ created_at: float = 0.0+ metadata: dict = field(default_factory=dict)++@dataclassclass RuntimeInfo:"""Connection info returned after a runtime spins up."""@@ -66,3 +76,28 @@ class Runtime(ABC):Returns a list of dicts with at minimum: name, status."""raise NotImplementedError(f"{type(self).__name__} does not support list()")++ # ── Checkpoint / fork primitives ─────────────────────────────────────────++ async def ensure_base(self, image: "Image", base_name: str) -> CheckpointInfo:+ """Pull/build image into a stopped base sandbox if not already present.++ Idempotent. First call does the full pull; subsequent calls return+ immediately. The base sandbox is never started — it only serves as a+ fork source for ephemeral VMs.+ """+ raise NotImplementedError(f"{type(self).__name__} does not support ensure_base()")++ async def fork(self, base_name: str, new_name: str, **opts) -> None:+ """Create a new sandbox from a base/checkpoint using CoW where possible."""+ raise NotImplementedError(f"{type(self).__name__} does not support fork()")++ async def checkpoint(self, name: str, checkpoint_name: str, **opts) -> CheckpointInfo:+ """Capture the current state of a running sandbox as a named checkpoint."""+ raise NotImplementedError(f"{type(self).__name__} does not support checkpoint()")++ async def list_checkpoints(self) -> list[CheckpointInfo]:+ raise NotImplementedError(f"{type(self).__name__} does not support list_checkpoints()")++ async def delete_checkpoint(self, checkpoint_name: str) -> None:+ raise NotImplementedError(f"{type(self).__name__} does not support delete_checkpoint()")diff --git a/libs/python/cua-sandbox/cua_sandbox/runtime/compat.py b/libs/python/cua-sandbox/cua_sandbox/runtime/compat.pynew file mode 100644index 0000000000..42fbe30e3d--- /dev/null+++ b/libs/python/cua-sandbox/cua_sandbox/runtime/compat.py@@ -0,0 +1,486 @@+"""Runtime compatibility checks — host/guest OS + arch + hardware acceleration.++Answers two questions for any Image before you try to boot it locally:++1. Is the required runtime installed (or auto-installable) on this host?+2. Does the host OS/arch support hardware acceleration for the guest OS/arch?++Usage::++ from cua_sandbox import Image+ from cua_sandbox.runtime.compat import check_local_support++ support = check_local_support(Image.linux())+ print(support.supported) # True if Docker is present+ print(support.hw_accel) # True for containers (native), True on Linux VMs with KVM+ print(support.reason) # human-readable summary++ # Or via the Image method:+ support = Image.macos().local_support()++In pytest, use the bundled helper::++ from cua_sandbox.runtime.compat import skip_if_unsupported++ async def test_something():+ skip_if_unsupported(Image.macos())+ async with Sandbox.ephemeral(Image.macos(), local=True) as sb:+ ...+"""++from __future__ import annotations++import platform+from dataclasses import dataclass+from typing import TYPE_CHECKING++if TYPE_CHECKING:+ from cua_sandbox.image import Image+++# ---------------------------------------------------------------------------+# Result type+# ---------------------------------------------------------------------------+++@dataclass+class RuntimeSupport:+ """Result of a local runtime compatibility check for a given Image.++ Attributes:+ supported: Image can run locally at all (runtime available or+ auto-installable, and host/guest OS is compatible).+ hw_accel: Hardware acceleration is available for the guest on+ this host (HVF on Apple Silicon, KVM on Linux, etc.).+ Always True for containers — they run natively.+ runtime_installed: Required runtime binary/daemon is found right now+ without any installation step.+ auto_installable: Runtime can be downloaded and installed automatically+ by the SDK without user intervention (e.g. Android SDK).+ runtime_name: Name of the runtime that would be used+ ("docker", "lume", "qemu", "android_emulator", "hyperv").+ host_os: Detected host OS ("darwin", "linux", "windows").+ host_arch: Detected host CPU architecture ("arm64", "x86_64").+ guest_os: Guest OS from the image ("linux", "macos", "windows", "android").+ reason: Human-readable explanation — always set, describes+ the limiting factor when supported=False or hw_accel=False.+ """++ supported: bool+ hw_accel: bool+ runtime_installed: bool+ auto_installable: bool+ runtime_name: str+ host_os: str+ host_arch: str+ guest_os: str+ reason: str++ def __str__(self) -> str:+ accel = "hw-accel" if self.hw_accel else "software-only"+ status = "supported" if self.supported else "unsupported"+ installed = (+ "installed"+ if self.runtime_installed+ else ("auto-installable" if self.auto_installable else "not-installed")+ )+ return (+ f"RuntimeSupport({self.guest_os} on {self.host_os}/{self.host_arch}: "+ f"{status}, {accel}, runtime={self.runtime_name} [{installed}])"+ )+++# ---------------------------------------------------------------------------+# Internal host probes+# ---------------------------------------------------------------------------+++def _host_os() -> str:+ s = platform.system().lower()+ if s == "darwin":+ return "darwin"+ if s == "windows":+ return "windows"+ return "linux"+++def _host_arch() -> str:+ m = platform.machine().lower()+ if m in ("arm64", "aarch64"):+ return "arm64"+ return "x86_64"+++def _has_docker() -> bool:+ from cua_sandbox.runtime.docker import _has_docker as _docker_check++ return _docker_check()+++def _has_kvm() -> bool:+ from pathlib import Path++ return _host_os() == "linux" and Path("/dev/kvm").exists()+++def _has_hvf_for_arm64_guest() -> bool:+ """HVF for ARM64 guests (macOS VMs, ARM Android) — Apple Silicon only."""+ return _host_os() == "darwin" and _host_arch() == "arm64"+++def _has_hvf_for_x86_guest() -> bool:+ """HVF for x86_64 guests (Windows, Linux VMs) — Intel Macs only.++ On Apple Silicon, QEMU must use TCG software emulation for x86_64 guests+ because HVF does not support cross-architecture virtualisation.+ On Intel Macs, QEMU can use HVF (-accel hvf) for x86_64 guests.+ """+ return _host_os() == "darwin" and _host_arch() == "x86_64"+++def _x86_guest_hw_accel() -> tuple[bool, str]:+ """Return (hw_accel, reason) for an x86_64 guest on the current host."""+ os_ = _host_os()+ arch = _host_arch()+ if os_ == "linux" and _has_kvm():+ return True, "KVM hardware acceleration."+ if os_ == "darwin" and arch == "x86_64":+ return True, "Apple Hypervisor.framework (HVF) via QEMU -accel hvf on Intel Mac."+ if os_ == "windows" and _has_hyperv():+ return True, "Hyper-V hardware acceleration."+ if os_ == "darwin" and arch == "arm64":+ return False, (+ "QEMU cannot use HVF for x86_64 guests on Apple Silicon — TCG software emulation only. "+ "Expect slow performance."+ )+ return False, (+ f"No hardware acceleration for x86_64 guest on {os_}/{arch}. "+ "Enable KVM (Linux) or Hyper-V (Windows) for acceleration."+ )+++def _has_lume() -> bool:+ from cua_sandbox.runtime.lume import _has_lume as _lume_check++ return _lume_check()+++def _has_android_sdk() -> bool:+ """Return True if the Android emulator binary is present.++ Delegates to android_emulator._sdk_path() — the exact same logic the+ runtime uses at boot — then checks that emulator/emulator exists there.+ """++ from cua_sandbox.runtime.android_emulator import _sdk_path++ sdk = _sdk_path()+ return (sdk / "emulator" / "emulator").exists() or (+ sdk / "emulator" / "emulator.exe"+ ).exists() # Windows+++def _has_java() -> bool:+ """Return True if a usable JRE is found.++ Calls android_emulator._java_env() — the exact same probe the runtime uses.+ Returns False if _java_env() raises (Java not found).+ """+ from cua_sandbox.runtime.android_emulator import _java_env++ try:+ _java_env()+ return True+ except RuntimeError:+ return False+++def _has_hyperv() -> bool:+ from cua_sandbox.runtime.hyperv import _has_hyperv as _hyperv_check++ return _hyperv_check()+++def _has_qemu() -> bool:+ """Return True if a QEMU binary is available.++ Delegates to qemu_installer.qemu_bin() which checks PATH, Homebrew,+ MacPorts, and the cached portable install — the same resolution the+ runtime uses at boot time.+ """+ arch = _host_arch()+ from cua_sandbox.runtime.qemu_installer import qemu_bin++ try:+ qemu_bin(arch)+ return True+ except RuntimeError:+ # Also try the other arch — a cross-arch QEMU is still useful+ other = "x86_64" if arch == "arm64" else "arm64"+ try:+ qemu_bin(other)+ return True+ except RuntimeError:+ return False+++# ---------------------------------------------------------------------------+# Main check+# ---------------------------------------------------------------------------+++def check_local_support(image: "Image") -> RuntimeSupport:+ """Return a RuntimeSupport describing whether *image* can run locally.++ Args:+ image: The Image to check. Use Image.linux(), Image.macos(), etc.++ Returns:+ RuntimeSupport with .supported, .hw_accel, .reason, and more.+ """+ os_ = _host_os()+ arch = _host_arch()+ guest = image.os_type+ kind = image.kind or "vm"++ # ── Linux container ────────────────────────────────────────────────────+ if guest == "linux" and kind == "container":+ installed = _has_docker()+ return RuntimeSupport(+ supported=installed,+ hw_accel=True, # containers run natively — no emulation overhead+ runtime_installed=installed,+ auto_installable=False,+ runtime_name="docker",+ host_os=os_,+ host_arch=arch,+ guest_os=guest,+ reason=(+ "Docker is running."+ if installed+ else "Docker is not running or not installed. Install from https://docker.com"+ ),+ )++ # ── Linux VM ──────────────────────────────────────────────────────────+ if guest == "linux" and kind == "vm":+ docker_ok = _has_docker()+ qemu_ok = _has_qemu()+ installed = docker_ok or qemu_ok+ hw, hw_reason = _x86_guest_hw_accel()+ runtime = "docker+qemu" if docker_ok else ("qemu" if qemu_ok else "qemu")+ if not installed:+ reason = (+ "No runtime for Linux VMs found. "+ "Install Docker (preferred) or qemu-system-x86_64."+ )+ else:+ reason = f"Linux VM via QEMU. {hw_reason}"+ return RuntimeSupport(+ supported=installed,+ hw_accel=hw,+ runtime_installed=installed,+ auto_installable=False,+ runtime_name=runtime,+ host_os=os_,+ host_arch=arch,+ guest_os=guest,+ reason=reason,+ )++ # ── macOS VM ──────────────────────────────────────────────────────────+ if guest == "macos":+ # macOS VMs require macOS host + Apple Silicon (HVF via Virtualization.framework)+ if os_ != "darwin":+ return RuntimeSupport(+ supported=False,+ hw_accel=False,+ runtime_installed=False,+ auto_installable=False,+ runtime_name="lume",+ host_os=os_,+ host_arch=arch,+ guest_os=guest,+ reason=f"macOS VMs require a macOS host. Current host OS: {os_}.",+ )+ if arch != "arm64":+ return RuntimeSupport(+ supported=False,+ hw_accel=False,+ runtime_installed=False,+ auto_installable=False,+ runtime_name="lume",+ host_os=os_,+ host_arch=arch,+ guest_os=guest,+ reason=(+ "macOS VMs require Apple Silicon (ARM64) for Apple Hypervisor.framework. "+ f"Current host arch: {arch} (Intel Macs cannot run macOS VMs via Lume)."+ ),+ )+ # Apple Silicon macOS — HVF always available+ installed = _has_lume()+ return RuntimeSupport(+ supported=True, # Lume can be auto-installed via `lume install`+ hw_accel=True, # HVF always present on Apple Silicon+ runtime_installed=installed,+ auto_installable=True, # Lume installs via a single curl/brew command+ runtime_name="lume",+ host_os=os_,+ host_arch=arch,+ guest_os=guest,+ reason=(+ "macOS VM with Apple Hypervisor.framework (HVF) acceleration."+ if installed+ else (+ "Lume CLI not installed but can be auto-installed. "+ "Run: brew install trycua/tap/lume or curl -fsSL https://lume.sh | sh"+ )+ ),+ )++ # ── Windows VM ────────────────────────────────────────────────────────+ if guest == "windows":+ if os_ == "windows" and _has_hyperv():+ return RuntimeSupport(+ supported=True,+ hw_accel=True,+ runtime_installed=True,+ auto_installable=False,+ runtime_name="hyperv",+ host_os=os_,+ host_arch=arch,+ guest_os=guest,+ reason="Windows VM with Hyper-V hardware acceleration.",+ )+ docker_ok = _has_docker()+ qemu_ok = _has_qemu()+ installed = docker_ok or qemu_ok+ hw, hw_reason = _x86_guest_hw_accel()+ runtime = "docker+qemu" if docker_ok else ("qemu" if qemu_ok else "qemu")+ if not installed:+ reason = (+ "No runtime for Windows VMs found. "+ "Install Docker (preferred) or qemu-system-x86_64."+ )+ else:+ reason = f"Windows VM via QEMU. {hw_reason}"+ return RuntimeSupport(+ supported=installed,+ hw_accel=hw,+ runtime_installed=installed,+ auto_installable=False,+ runtime_name=runtime,+ host_os=os_,+ host_arch=arch,+ guest_os=guest,+ reason=reason,+ )++ # ── Android VM ────────────────────────────────────────────────────────+ if guest == "android":+ sdk_ok = _has_android_sdk()+ java_ok = _has_java()+ # HW accel matrix for Android:+ # Apple Silicon (arm64): HVF for ARM64 Android system images+ # Intel Mac (x86_64): HVF for x86_64 Android system images+ # Linux x86_64 w/ KVM: KVM for x86_64 Android system images+ if os_ == "darwin" and arch == "arm64":+ hw = True+ hw_reason = "Apple Hypervisor.framework (HVF) with ARM64 Android system image."+ elif os_ == "darwin" and arch == "x86_64":+ hw = True+ hw_reason = (+ "Apple Hypervisor.framework (HVF) with x86_64 Android system image on Intel Mac."+ )+ elif os_ == "linux" and _has_kvm():+ hw = True+ hw_reason = "KVM with x86_64 Android system image."+ elif os_ == "windows":+ # WHPX (Windows Hypervisor Platform) is used by the Android emulator on Windows+ hw = _has_hyperv() # WHPX requires Hyper-V / Windows Hypervisor Platform+ hw_reason = (+ "Windows Hypervisor Platform (WHPX) acceleration."+ if hw+ else "WHPX not available. Emulator will use software rendering (slow)."+ )+ else:+ hw = False+ hw_reason = (+ f"No hardware acceleration for Android on {os_}/{arch}. "+ "Emulator will use software rendering (slow)."+ )++ installed = sdk_ok and java_ok+ auto = not installed # SDK auto-installs on all platforms if Java is present++ if not java_ok:+ reason = (+ "Java not found. Install via: brew install openjdk (macOS), "+ "apt install default-jdk (Linux), or "+ "winget install EclipseAdoptium.Temurin.21.JDK (Windows). " + hw_reason+ )+ elif not sdk_ok:+ reason = "Android SDK not found but will be auto-installed on first boot. " + hw_reason+ else:+ reason = "Android SDK installed. " + hw_reason++ return RuntimeSupport(+ supported=java_ok, # Java is a hard prerequisite; SDK auto-installs if Java is present+ hw_accel=hw,+ runtime_installed=installed,+ auto_installable=auto and java_ok,+ runtime_name="android_emulator",+ host_os=os_,+ host_arch=arch,+ guest_os=guest,+ reason=reason,+ )++ # ── Unknown / registry image with unresolved kind ─────────────────────+ return RuntimeSupport(+ supported=False,+ hw_accel=False,+ runtime_installed=False,+ auto_installable=False,+ runtime_name="unknown",+ host_os=os_,+ host_arch=arch,+ guest_os=guest,+ reason=(+ f"Cannot determine runtime for os_type={guest!r}, kind={kind!r}. "+ "Use Image.linux() / .macos() / .windows() / .android() "+ "or pass runtime= explicitly."+ ),+ )+++# ---------------------------------------------------------------------------+# Pytest helper+# ---------------------------------------------------------------------------+++def skip_if_unsupported(image: "Image", *, require_hw_accel: bool = False) -> None:+ """Call at the top of a pytest test/fixture to skip when the host can't run *image*.++ Args:+ image: The Image the test intends to boot with local=True.+ require_hw_accel: If True, also skip when hardware acceleration is unavailable+ (e.g. skip Android tests that would run in software emulation).++ Example::++ async def test_macos_brew_install():+ skip_if_unsupported(Image.macos())+ async with Sandbox.ephemeral(Image.macos().brew_install("wget"), local=True) as sb:+ assert (await sb.shell.run("wget --version")).success+ """+ import pytest # imported here so compat.py has no hard pytest dep at import time++ support = check_local_support(image)+ if not support.supported:+ pytest.skip(f"[{support.runtime_name}] {support.reason}")+ if require_hw_accel and not support.hw_accel:+ pytest.skip(+ f"[{support.runtime_name}] hardware acceleration not available: {support.reason}"+ )diff --git a/libs/python/cua-sandbox/cua_sandbox/runtime/docker.py b/libs/python/cua-sandbox/cua_sandbox/runtime/docker.pyindex c57aef46c5..2898c65b42 100644--- a/libs/python/cua-sandbox/cua_sandbox/runtime/docker.py+++ b/libs/python/cua-sandbox/cua_sandbox/runtime/docker.py@@ -38,11 +38,41 @@ def _find_free_port(start: int = 8000, end: int = 9000) -> int:raise RuntimeError(f"No free port found in range {start}–{end}")+def _docker_bin() -> str:+ """Return the resolved path to the docker CLI binary.++ Probes common install locations in addition to PATH — SSH sessions often+ have a stripped PATH that omits /usr/local/bin (e.g. OrbStack on macOS).+ Raises RuntimeError if docker is not found.+ """+ import os+ import shutil++ candidates = [+ "docker",+ "/usr/local/bin/docker",+ "/opt/homebrew/bin/docker",+ "/usr/bin/docker",+ os.path.expanduser("~/.docker/bin/docker"),+ ]+ for candidate in candidates:+ resolved = shutil.which(candidate) or candidate+ try:+ subprocess.run([resolved, "info"], capture_output=True, check=True, timeout=10)+ return resolved+ except (subprocess.SubprocessError, FileNotFoundError, OSError):+ continue+ raise RuntimeError(+ "Docker not found. Install from https://docker.com or ensure the docker CLI is on PATH."+ )++def _has_docker() -> bool:+ """Return True if a Docker daemon is reachable."""try:- subprocess.run(["docker", "info"], capture_output=True, check=True, timeout=10)+ _docker_bin()return True- except (subprocess.SubprocessError, FileNotFoundError):+ except RuntimeError:return False@@ -98,10 +128,14 @@ class DockerRuntime(Runtime):for v in self.volumes:extra_flags += ["-v", v]- # Environment variables+ # Environment variables (from DockerRuntime constructor)for k, val in self.environment.items():extra_flags += ["-e", f"{k}={val}"]+ # Environment variables from image.env() calls+ for k, val in getattr(image, "_env", ()):+ extra_flags += ["-e", f"{k}={val}"]+# Devices (e.g. /dev/kvm)for d in self.devices:extra_flags += ["--device", d]@@ -117,14 +151,20 @@ class DockerRuntime(Runtime):# Stop timeoutextra_flags += ["--stop-timeout", str(self.stop_timeout)]+ # Expose additional ports from image._ports+ for port in getattr(image, "_ports", ()):+ host_p = _find_free_port(port, port + 1000)+ extra_flags += ["-p", f"{host_p}:{port}"]+# Remove existing container with same name- subprocess.run(["docker", "rm", "-f", name], capture_output=True)+ docker = _docker_bin()+ subprocess.run([docker, "rm", "-f", name], capture_output=True)api_port = _find_free_port(self.api_port)vnc_port = _find_free_port(api_port + 1)cmd = [- "docker",+ docker,"run","-d","--name",@@ -154,24 +194,75 @@ class DockerRuntime(Runtime):name=name,)await self.is_ready(info)++ # Apply image layers and files via computer-server.+ # If any provisioning step fails, stop and remove the half-baked container+ # so callers don't get a broken sandbox silently left running.+ env_items = getattr(image, "_env", ())+ file_items = getattr(image, "_files", ())+ has_work = image._layers or file_items+ if has_work or env_items:+ try:+ from cua_sandbox.builder.executor import LayerExecutor++ executor = LayerExecutor(+ f"http://{info.host}:{info.api_port}", os_type=image.os_type+ )++ # Write env vars to a sourceable profile script so run layers can access them+ if env_items and image.os_type != "windows":+ import re as _re+ import shlex as _shlex++ # Validate all keys up front+ for k, _ in env_items:+ if not _re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", k):+ raise ValueError(f"Unsafe env var name: {k!r}")+ await executor.run_command(+ "printf '#!/bin/sh\\n' | sudo tee /etc/profile.d/cua-env.sh > /dev/null"+ )+ for k, v in env_items:+ quoted_v = _shlex.quote(v)+ await executor.run_command(+ f"printf 'export {k}=%s\\n' {quoted_v} "+ f"| sudo tee -a /etc/profile.d/cua-env.sh > /dev/null"+ )++ # Apply files before layers so later run layers can reference copied files+ for src, dst in file_items:+ await executor.execute_layers([{"type": "copy", "src": src, "dst": dst}])++ if image._layers:+ await executor.execute_layers(list(image._layers))+ except Exception:+ # Tear down the container so it doesn't linger in a broken state+ try:+ docker = _docker_bin()+ subprocess.run([docker, "rm", "-f", name], capture_output=True)+ except Exception:+ pass+ raise+return infoasync def stop(self, name: str) -> None:- subprocess.run(["docker", "stop", name], capture_output=True)+ docker = _docker_bin()+ subprocess.run([docker, "stop", name], capture_output=True)if self.ephemeral:- subprocess.run(["docker", "rm", name], capture_output=True)+ subprocess.run([docker, "rm", name], capture_output=True)async def suspend(self, name: str) -> None:"""Pause a running Docker container."""- subprocess.run(["docker", "pause", name], capture_output=True)+ subprocess.run([_docker_bin(), "pause", name], capture_output=True)async def resume(self, image: "Image", name: str, **opts) -> RuntimeInfo:"""Unpause a paused Docker container and return its RuntimeInfo."""- subprocess.run(["docker", "unpause", name], capture_output=True)+ docker = _docker_bin()+ subprocess.run([docker, "unpause", name], capture_output=True)# Inspect to get mapped portsresult = subprocess.run([- "docker",+ docker,"inspect","--format",'{{(index (index .NetworkSettings.Ports "8000/tcp") 0).HostPort}}',@@ -183,7 +274,7 @@ class DockerRuntime(Runtime):api_port = int(result.stdout.strip()) if result.stdout.strip().isdigit() else self.api_portresult2 = subprocess.run([- "docker",+ docker,"inspect","--format",'{{(index (index .NetworkSettings.Ports "5900/tcp") 0).HostPort}}',@@ -203,7 +294,7 @@ class DockerRuntime(Runtime):"""List Docker containers with the cua.sandbox=true label."""result = subprocess.run([- "docker",+ _docker_bin(),"ps","-a","--filter",diff --git a/libs/python/cua-sandbox/cua_sandbox/runtime/lume.py b/libs/python/cua-sandbox/cua_sandbox/runtime/lume.pyindex a034076a4d..cfb0b361b6 100644--- a/libs/python/cua-sandbox/cua_sandbox/runtime/lume.py+++ b/libs/python/cua-sandbox/cua_sandbox/runtime/lume.py@@ -41,6 +41,21 @@ def _lume_path() -> str | None:return None+def _base_vm_name(oci_ref: str) -> str:+ """Return a stable base-VM name for an OCI image ref (12-char sha256 prefix)."""+ import hashlib++ digest = hashlib.sha256(oci_ref.encode()).hexdigest()[:12]+ return f"cua-base-{digest}"+++def _resp_detail(resp: "httpx.Response") -> str:+ try:+ return str(resp.json())+ except Exception:+ return resp.text++def _has_lume() -> bool:return _lume_path() is not None@@ -67,211 +82,401 @@ class LumeRuntime(Runtime):)lume_url = f"http://{self.lume_host}:{self.lume_port}"++ # Fast path — VM already existsasync with httpx.AsyncClient(timeout=30) as client:resp = await client.get(f"{lume_url}/lume/vms/{name}")- vm = resp.json()+ vm = resp.json() if resp.status_code == 200 else {}+ existing_status = vm.get("status")+ if existing_status == "running":+ logger.info(f"Lume VM {name} already running")+ ip = await self._wait_for_ip(name, lume_url)+ await self._deliver_vnc_config(name, lume_url)+ info = RuntimeInfo(host=ip, api_port=self.api_port, name=name)+ await self.is_ready(info)+ await self._apply_image_layers(image, info)+ return info+ if existing_status in ("stopped", "suspended"):+ # Resume the existing stopped VM rather than colliding with a clone+ logger.info(f"Lume VM {name} exists (stopped) — resuming")+ return await self.resume(image, name, **opts)++ oci_ref = image._registry or MACOS_VERSION_IMAGES.get(image.version or "") or MACOS_SEQUOIA++ # Pull-once + clone: ensure a stopped base VM exists, then clone it+ # (APFS clonefile — instant). First call takes ~155s; subsequent calls+ # return in <1s regardless of image size.+ base_name = _base_vm_name(oci_ref)+ await self.ensure_base(image, base_name)+ await self.fork(base_name, name)++ # Run the cloned VM+ await self._run_vm(name, lume_url, opts)+ ip = await self._wait_for_ip(name, lume_url)+ await self._deliver_vnc_config(name, lume_url)+ info = RuntimeInfo(host=ip, api_port=self.api_port, name=name)+ await self.is_ready(info)+ await self._apply_image_layers(image, info)+ return info++ async def _run_vm(self, name: str, lume_url: str, opts: dict) -> None:+ """POST /lume/vms/{name}/run and raise on failure."""+ async with httpx.AsyncClient(timeout=120) as client:+ run_resp = await client.post(+ f"{lume_url}/lume/vms/{name}/run",+ json={+ "noDisplay": opts.get("no_display", True),+ "sharedDirectories": opts.get("shared_directories", []),+ },+ timeout=120,+ )+ if run_resp.status_code >= 400:+ try:+ detail = run_resp.json()+ except Exception:+ detail = run_resp.text+ raise RuntimeError(f"Lume failed to run VM '{name}': {detail}")++ # ── Checkpoint / fork primitives ─────────────────────────────────────────+ async def ensure_base(self, image: Image, base_name: str): # -> CheckpointInfo+ """Pull an OCI image into a stopped golden base VM, if it doesn't exist yet.++ Idempotent — if *base_name* already exists and is stopped, returns+ immediately. Raises if the base VM is running, because cloning a live VM+ can produce dirty or inconsistent clones (same constraint as cloud snapshots).+ The base VM is never started; it only serves as a fork source.+ """+ import time++ from cua_sandbox.runtime.base import CheckpointInfo++ lume_url = f"http://{self.lume_host}:{self.lume_port}"+ async with httpx.AsyncClient(timeout=30) as client:+ resp = await client.get(f"{lume_url}/lume/vms/{base_name}")+ if resp.status_code == 200:+ vm = resp.json()if vm.get("status") == "running":- logger.info(f"Lume VM {name} already running")- else:- oci_ref = (- image._registry- or MACOS_VERSION_IMAGES.get(image.version or "")- or MACOS_SEQUOIA+ raise RuntimeError(+ f"Base VM '{base_name}' is running — stop it before using as a clone source")- logger.info(f"Pulling {oci_ref} via Lume...")- # Lume's pull API expects image="name:tag" with registry/organization- # passed separately — passing a full ref causes double-prefixing of the org.- pull_payload: dict = {"image": oci_ref, "name": name}- parts = oci_ref.split("/")- if len(parts) >= 3 and "." in parts[0]:- pull_payload = {- "image": "/".join(parts[2:]),- "name": name,- "registry": parts[0],- "organization": parts[1],- }- # Use /lume/pull/start (async, returns 202 immediately) so we can- # poll progress while the pull runs in the background.- # Falls back to the synchronous /lume/pull if start returns 404.+ if vm.get("status") in ("stopped", "suspended"):+ logger.info(f"Base VM '{base_name}' already exists (stopped) — skipping pull")+ return CheckpointInfo(name=base_name, runtime_type="lume", created_at=time.time())++ oci_ref = image._registry or MACOS_VERSION_IMAGES.get(image.version or "") or MACOS_SEQUOIA+ logger.info(f"Pulling base image '{oci_ref}' → '{base_name}' (first time only)...")+ pull_payload: dict = {"image": oci_ref, "name": base_name}+ parts = oci_ref.split("/")+ if len(parts) >= 3 and "." in parts[0]:+ pull_payload = {+ "image": "/".join(parts[2:]),+ "name": base_name,+ "registry": parts[0],+ "organization": parts[1],+ }+ await self._pull_vm(base_name, lume_url, pull_payload)+ return CheckpointInfo(name=base_name, runtime_type="lume", created_at=time.time())++ async def fork(self, base_name: str, new_name: str, **opts) -> None:+ """Clone a stopped VM *base_name* → *new_name* via APFS clonefile (instant).++ The source VM must be stopped before calling this — cloning a running VM+ risks dirty state or clone failures (mirrors cloud snapshot behaviour).+ """+ lume_url = f"http://{self.lume_host}:{self.lume_port}"+ logger.info(f"Cloning base VM '{base_name}' → '{new_name}'")+ async with httpx.AsyncClient(timeout=60) as client:+ resp = await client.post(+ f"{lume_url}/lume/vms/clone",+ json={"name": base_name, "newName": new_name},+ timeout=60,+ )+ if resp.status_code >= 400:+ try:+ detail = resp.json()+ except Exception:+ detail = resp.text+ raise RuntimeError(f"Lume clone '{base_name}' → '{new_name}' failed: {detail}")+ logger.info(f"Cloned '{base_name}' → '{new_name}' successfully")++ # Prefix used to distinguish checkpoint VMs from ordinary sandboxes+ _CHECKPOINT_PREFIX = "cua-ckpt-"++ async def checkpoint(self, name: str, checkpoint_name: str, **opts): # -> CheckpointInfo+ """Stop *name*, clone it into a checkpoint, then restart *name*.++ Mirrors the cloud behaviour (stop → snapshot → restart) so clones are+ always taken from a clean stopped state.+ """+ import time++ from cua_sandbox.runtime.base import CheckpointInfo++ lume_url = f"http://{self.lume_host}:{self.lume_port}"++ # Enforce the naming prefix so list/delete_checkpoint stay scoped+ if not checkpoint_name.startswith(+ self._CHECKPOINT_PREFIX+ ) and not checkpoint_name.startswith("cua-base-"):+ checkpoint_name = f"{self._CHECKPOINT_PREFIX}{checkpoint_name}"++ # Determine whether the source VM is running so we can restart it after+ async with httpx.AsyncClient(timeout=30) as client:+ resp = await client.get(f"{lume_url}/lume/vms/{name}")+ vm = resp.json() if resp.status_code == 200 else {}+ was_running = vm.get("status") == "running"++ if was_running:+ logger.info(f"Stopping '{name}' before checkpoint clone")+ await self.stop(name)++ try:+ await self.fork(name, checkpoint_name)+ finally:+ if was_running:+ logger.info(f"Restarting '{name}' after checkpoint clone")+ await self._run_vm(name, lume_url, opts)++ return CheckpointInfo(+ name=checkpoint_name,+ runtime_type="lume",+ created_at=time.time(),+ metadata={"source": name},+ )++ async def list_checkpoints(self): # -> list[CheckpointInfo]+ """Return VMs that are checkpoints (cua-base-* or cua-ckpt-* prefix)."""+ import time++ from cua_sandbox.runtime.base import CheckpointInfo++ vms = await self.list()+ return [+ CheckpointInfo(name=v["name"], runtime_type="lume", created_at=time.time())+ for v in vms+ if v["name"].startswith("cua-base-") or v["name"].startswith(self._CHECKPOINT_PREFIX)+ ]++ async def delete_checkpoint(self, checkpoint_name: str) -> None:+ """Delete a checkpoint VM. Only operates on cua-base-* / cua-ckpt-* names."""+ if not checkpoint_name.startswith("cua-base-") and not checkpoint_name.startswith(+ self._CHECKPOINT_PREFIX+ ):+ raise ValueError(+ f"'{checkpoint_name}' does not look like a checkpoint "+ f"(expected 'cua-base-' or '{self._CHECKPOINT_PREFIX}' prefix)"+ )+ await self.delete(checkpoint_name)++ # ── Internal pull helper ──────────────────────────────────────────────────++ async def _pull_vm(self, name: str, lume_url: str, pull_payload: dict) -> None:+ """Pull an OCI image into a stopped VM named *name*.++ Tries /lume/pull/start (async with progress polling) first, falls back+ to the synchronous /lume/pull for older lume versions.+ """+ async with httpx.AsyncClient(timeout=30) as client:+ try:+ start_resp = await self._pull_start_with_retry(lume_url, pull_payload)+ except (httpx.ReadError, httpx.RemoteProtocolError):+ # lume v0.3.x — sync pull+ logger.info("Lume /pull/start unavailable, falling back to synchronous pull...")+ print("\rPulling macOS image...", end="", flush=True, file=sys.stderr)try:- start_resp = await client.post(- f"{lume_url}/lume/pull/start",- json=pull_payload,- timeout=30,+ sync_resp = await client.post(+ f"{lume_url}/lume/pull", json=pull_payload, timeout=1800)+ if sync_resp.status_code >= 400:+ raise RuntimeError(+ f"Lume pull failed for '{name}': {_resp_detail(sync_resp)}"+ )except (httpx.ReadError, httpx.RemoteProtocolError):- # /pull/start not available in lume v0.3.x — fall back to sync /pull,- # then run the VM and return directly (bypassing the async poll below).- logger.info(- "Lume /pull/start unavailable (v0.3.x), falling back to synchronous pull..."- )- print("\rPulling macOS image...", end="", flush=True, file=sys.stderr)- try:- sync_resp = await client.post(- f"{lume_url}/lume/pull",- json=pull_payload,- timeout=1800,+ check = await client.get(f"{lume_url}/lume/vms/{name}", timeout=10)+ if check.status_code != 200 or check.json().get("status") in (+ "",+ None,+ "error",+ ):+ raise RuntimeError(+ f"Lume pull failed for '{name}': connection dropped and VM not found"+ " (check GITHUB_TOKEN is set in lume's LaunchAgent plist)")- if sync_resp.status_code >= 400:- try:- detail = sync_resp.json()- except Exception:- detail = sync_resp.text- raise RuntimeError(f"Lume pull failed for '{name}': {detail}")- except (httpx.ReadError, httpx.RemoteProtocolError):- # Lume v0.3.x drops the sync pull connection when done.- # Verify the VM was created.- try:- check = await client.get(f"{lume_url}/lume/vms/{name}", timeout=10)- if check.status_code != 200 or check.json().get("status") in (- "",- None,- "error",- ):- raise RuntimeError(- f"Lume pull failed for '{name}': connection dropped and VM not found"- " (check GITHUB_TOKEN is set in lume's LaunchAgent plist)"- )- except httpx.HTTPError as e:- raise RuntimeError(f"Lume pull failed for '{name}': {e}") from e- print(file=sys.stderr)- logger.info(f"Running Lume VM {name} (v0.3.x path)...")- run_resp = await client.post(- f"{lume_url}/lume/vms/{name}/run",- json={- "noDisplay": opts.get("no_display", True),- "sharedDirectories": opts.get("shared_directories", []),- },- timeout=120,- )- if run_resp.status_code >= 400:- try:- detail = run_resp.json()- except Exception:- detail = run_resp.text- raise RuntimeError(f"Lume failed to run VM '{name}': {detail}")- ip = await self._wait_for_ip(name, lume_url)- info = RuntimeInfo(host=ip, api_port=self.api_port, name=name)- await self.is_ready(info)- return info- if start_resp.status_code == 404:- # Older lume without /pull/start — fall back to synchronous pull- logger.info(- "Lume does not support /pull/start, falling back to synchronous pull..."+ print(file=sys.stderr)+ return++ if start_resp.status_code == 404:+ # Older lume without /pull/start+ try:+ pull_resp = await client.post(+ f"{lume_url}/lume/pull", json=pull_payload, timeout=1800)- try:- pull_resp = await client.post(- f"{lume_url}/lume/pull",- json=pull_payload,- timeout=1800,+ except (httpx.ReadError, httpx.RemoteProtocolError):+ check = await client.get(f"{lume_url}/lume/vms/{name}", timeout=10)+ if check.status_code != 200 or check.json().get("status") in (+ "",+ None,+ "error",+ ):+ raise RuntimeError(+ f"Lume pull failed for '{name}': connection dropped and VM not found"+ )+ return+ if pull_resp.status_code >= 400:+ raise RuntimeError(f"Lume pull failed for '{name}': {_resp_detail(pull_resp)}")+ return++ if start_resp.status_code >= 400:+ raise RuntimeError(+ f"Lume pull/start failed for '{name}': {_resp_detail(start_resp)}"+ )++ # Poll until pull completes+ logger.info(f"Pulling image for '{name}'...")+ pull_deadline = asyncio.get_event_loop().time() + 1800+ last_progress = -1.0+ while asyncio.get_event_loop().time() < pull_deadline:+ try:+ poll = await client.get(f"{lume_url}/lume/vms/{name}", timeout=10)+ except (httpx.ReadError, httpx.RemoteProtocolError, httpx.ConnectError):+ await asyncio.sleep(3)+ continue+ if poll.status_code == 200:+ data = poll.json()+ status = data.get("status", "")+ progress = data.get("downloadProgress")+ if progress is not None and progress != last_progress:+ print(+ f"\rPulling macOS image: {progress:.0f}%",+ end="",+ flush=True,+ file=sys.stderr,)- except (httpx.ReadError, httpx.RemoteProtocolError):- # Lume v0.3.x drops the HTTP connection after pull- # completes. Check if the VM was actually created.- logger.info(- f"Lume sync pull connection dropped — checking if VM '{name}' was created..."+ last_progress = progress+ if status == "pulling":+ await asyncio.sleep(3)+ continue+ if "error" in status.lower():+ raise RuntimeError(+ f"Lume pull failed for '{name}': {data.get('message', status)}")- try:- check = await client.get(f"{lume_url}/lume/vms/{name}", timeout=10)- if check.status_code == 200:- vm_data = check.json()- if vm_data.get("status") not in ("", None, "error"):- logger.info(- f"VM '{name}' exists after connection drop — pull succeeded"- )- # fall through to run the VM- pull_resp = check # dummy, not used further- else:- raise RuntimeError(- f"Lume pull failed for '{name}': connection dropped and VM not found"- " (check GITHUB_TOKEN is set in lume's LaunchAgent plist)"- )- except httpx.HTTPError as check_err:- raise RuntimeError(- f"Lume pull failed for '{name}': connection dropped and could not verify VM: {check_err}"- ) from check_err- if pull_resp.status_code >= 400:- try:- detail = pull_resp.json()- except Exception:- detail = pull_resp.text- raise RuntimeError(f"Lume pull failed for '{name}': {detail}")- elif start_resp.status_code >= 400:+ break+ elif poll.status_code >= 400:+ data = {}try:- detail = start_resp.json()+ data = poll.json()except Exception:- detail = start_resp.text- raise RuntimeError(f"Lume pull/start failed for '{name}': {detail}")- else:- # Poll /lume/vms/{name} until status leaves "pulling"- logger.info(f"Pulling image for '{name}'...")- pull_deadline = asyncio.get_event_loop().time() + 1800- last_progress = -1.0- while asyncio.get_event_loop().time() < pull_deadline:- try:- poll = await client.get(f"{lume_url}/lume/vms/{name}", timeout=10)- except (httpx.ReadError, httpx.RemoteProtocolError, httpx.ConnectError):- await asyncio.sleep(3)- continue- if poll.status_code == 200:- data = poll.json()- status = data.get("status", "")- progress = data.get("downloadProgress")- if progress is not None and progress != last_progress:- print(- f"\rPulling macOS image: {progress:.0f}%",- end="",- flush=True,- file=sys.stderr,- )- last_progress = progress- if status == "pulling":- await asyncio.sleep(3)- continue- # Pull failed — lume surfaced an error via status- if "error" in status.lower():- raise RuntimeError(- f"Lume pull failed for '{name}': {data.get('message', status)}"- )- break- elif poll.status_code >= 400:- # VM not found — pull may have failed before creating the VM- data = {}- try:- data = poll.json()- except Exception:- pass- raise RuntimeError(- f"Lume pull failed for '{name}': {data.get('message', poll.text)}"- )- await asyncio.sleep(3)- else:- raise TimeoutError(f"Lume pull for '{name}' did not complete within 1800s")- if last_progress >= 0:- print(file=sys.stderr) # newline after progress bar- logger.info(f"Running Lume VM {name}...")- run_resp = await client.post(- f"{lume_url}/lume/vms/{name}/run",- json={- "noDisplay": opts.get("no_display", True),- "sharedDirectories": opts.get("shared_directories", []),- },- timeout=120,+ pass+ raise RuntimeError(+ f"Lume pull failed for '{name}': {data.get('message', poll.text)}"+ )+ await asyncio.sleep(3)+ else:+ raise TimeoutError(f"Lume pull for '{name}' did not complete within 1800s")+ if last_progress >= 0:+ print(file=sys.stderr)++ async def _pull_start_with_retry(+ self, lume_url: str, payload: dict, retries: int = 3+ ) -> httpx.Response:+ """POST /lume/pull/start with retry for spurious 'Invalid request body' 400s.++ Lume's custom HTTP server reads with minimumIncompleteLength=1, so on a+ fresh TCP connection the body can arrive after the first receive() returns,+ causing a spurious 400. A brief pause + retry recovers reliably.+ """+ last_resp: httpx.Response | None = None+ for attempt in range(retries):+ if attempt > 0:+ await asyncio.sleep(1)+ async with httpx.AsyncClient(timeout=30) as pull_client:+ resp = await pull_client.post(+ f"{lume_url}/lume/pull/start",+ json=payload,+ timeout=30,)- if run_resp.status_code >= 400:- try:- detail = run_resp.json()- except Exception:- detail = run_resp.text- raise RuntimeError(f"Lume failed to run VM '{name}': {detail}")+ if resp.status_code != 400 or "Invalid request body" not in resp.text:+ return resp # success or a real error+ logger.warning(+ "pull/start got 'Invalid request body' (attempt %d/%d), retrying...",+ attempt + 1,+ retries,+ )+ last_resp = resp+ return last_resp # type: ignore[return-value]- ip = await self._wait_for_ip(name, lume_url)+ async def _apply_image_layers(self, image: "Image", info: RuntimeInfo) -> None:+ """Apply image layers (run, brew_install, env, copy, etc.) via computer-server."""+ env_items = getattr(image, "_env", ())+ file_items = getattr(image, "_files", ())+ has_work = image._layers or file_items+ if not has_work and not env_items:+ return+ from cua_sandbox.builder.executor import LayerExecutor- await self._deliver_vnc_config(name, lume_url)- info = RuntimeInfo(host=ip, api_port=self.api_port, name=name)- await self.is_ready(info)- return info+ executor = LayerExecutor(f"http://{info.host}:{info.api_port}", os_type=image.os_type)+ if env_items and image.os_type != "windows":+ if image.os_type == "macos":+ # macOS: computer-server runs under launchd with an explicit+ # EnvironmentVariables dict in its plist. launchctl setenv is+ # ignored by such services, so we must add vars to the plist+ # directly via PlistBuddy, then unload/load the service.+ import re as _re++ plist = "~/Library/LaunchAgents/com.trycua.computer_server.plist"+ for k, v in env_items:+ # Validate key: must be a safe identifier (alphanumeric + _)+ if not _re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", k):+ raise ValueError(f"Unsafe env var name: {k!r}")+ # Escape value for PlistBuddy: single-quote the shell arg,+ # and escape any single quotes within the value itself.+ safe_v = v.replace("'", "'\\''")+ # Use Set if key exists, Add otherwise+ await executor.run_command(+ f"/usr/libexec/PlistBuddy -c 'Set :EnvironmentVariables:{k} {safe_v}' {plist} 2>/dev/null || "+ f"/usr/libexec/PlistBuddy -c 'Add :EnvironmentVariables:{k} string {safe_v}' {plist}"+ )+ # Reload via lume ssh from the host — launchctl unload would kill+ # computer-server mid-execution if run from inside via /cmd.+ lume_bin = _lume_path() or "lume"+ reload_cmd = (+ "launchctl bootout gui/$(id -u)/com.trycua.computer_server 2>/dev/null; "+ f"launchctl bootstrap gui/$(id -u) {plist}"+ )+ proc = await asyncio.create_subprocess_exec(+ lume_bin,+ "ssh",+ info.name,+ "--",+ reload_cmd,+ stdout=asyncio.subprocess.DEVNULL,+ stderr=asyncio.subprocess.DEVNULL,+ )+ await asyncio.wait_for(proc.wait(), timeout=30)+ await self.is_ready(info) # wait for computer-server to come back+ else:+ import re as _re+ import shlex as _shlex++ sudo = "sudo"+ # Validate all keys up front+ for k, _ in env_items:+ if not _re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", k):+ raise ValueError(f"Unsafe env var name: {k!r}")+ await executor.run_command(+ f"printf '#!/bin/sh\\n' | {sudo} tee /etc/profile.d/cua-env.sh > /dev/null"+ )+ for k, v in env_items:+ quoted_v = _shlex.quote(v)+ await executor.run_command(+ f"printf 'export {k}=%s\\n' {quoted_v} "+ f"| {sudo} tee -a /etc/profile.d/cua-env.sh > /dev/null"+ )+ for src, dst in file_items:+ await executor.execute_layers([{"type": "copy", "src": src, "dst": dst}])+ if image._layers:+ await executor.execute_layers(list(image._layers))async def _deliver_vnc_config(self, name: str, lume_url: str) -> None:"""Write the current VNC port/password into ~/.vnc.env inside the VM.diff --git a/libs/python/cua-sandbox/cua_sandbox/sandbox.py b/libs/python/cua-sandbox/cua_sandbox/sandbox.pyindex e4f0d07f07..15bdb4ed9c 100644--- a/libs/python/cua-sandbox/cua_sandbox/sandbox.py+++ b/libs/python/cua-sandbox/cua_sandbox/sandbox.py@@ -270,6 +270,41 @@ class Sandbox:"""Drop the transport connection. The sandbox keeps running."""await self._transport.disconnect()+ async def snapshot(self, name: str | None = None, stateful: bool = False) -> "Image":+ """Snapshot this sandbox's current state. Returns an Image.++ The returned Image can be passed to Sandbox.create() or Sandbox.ephemeral()+ to boot a new sandbox from the snapshot (COW fork — instant on btrfs).++ Args:+ name: Optional human-readable name for the snapshot.+ stateful: Whether to capture memory state (VMs only).++ Returns:+ An Image with _snapshot_source set, ready to pass to Sandbox.ephemeral().+ """+ from cua_sandbox.transport.cloud import CloudTransport++ if not isinstance(self._transport, CloudTransport):+ raise NotImplementedError("Snapshots are only supported for cloud sandboxes")++ image_desc = await self._transport.create_snapshot(name=name, stateful=stateful)+ from cua_sandbox.image import Image as ImageCls++ # Get the original image from the transport for os_type/distro/version+ src_image = getattr(self._transport, "_image", None)++ # Prefer the original image's os_type/distro/version — image_desc["kind"]+ # is the snapshot kind (e.g. "vm"), not the OS type, and would misclassify+ # the image for OS-gated builder methods and compat checks.+ return ImageCls(+ os_type=src_image.os_type if src_image else image_desc.get("os_type", "linux"),+ distro=src_image.distro if src_image else image_desc.get("distro", "ubuntu"),+ version=src_image.version if src_image else image_desc.get("version", "24.04"),+ kind=src_image.kind if src_image else image_desc.get("kind"),+ _snapshot_source=image_desc,+ )+async def destroy(self) -> None:"""Disconnect and permanently delete the sandbox (VM/container)."""if self.telemetry_enabled and _TELEMETRY_AVAILABLE and is_telemetry_enabled():@@ -278,7 +313,11 @@ class Sandbox:if isinstance(self._transport, CloudTransport):await self._transport.delete_vm()if self._runtime and self._runtime_info:- await self._runtime.stop(self._runtime_info.name or self.name or "cua-sandbox")+ vm_name = self._runtime_info.name or self.name or "cua-sandbox"+ if self._ephemeral and hasattr(self._runtime, "delete"):+ await self._runtime.delete(vm_name)+ else:+ await self._runtime.stop(vm_name)async def screenshot(self, text: Optional[str] = None, format: str = "png", quality: int = 95diff --git a/libs/python/cua-sandbox/cua_sandbox/transport/adb.py b/libs/python/cua-sandbox/cua_sandbox/transport/adb.pyindex cd838e7edc..f3442413a3 100644--- a/libs/python/cua-sandbox/cua_sandbox/transport/adb.py+++ b/libs/python/cua-sandbox/cua_sandbox/transport/adb.py@@ -72,6 +72,7 @@ class ADBTransport(Transport):async def send(self, action: str, **params: Any) -> Any:if action in ("shell", "execute", "run_command"):cmd = params.get("command", "")+ cmd = f"[ -f /data/local/tmp/.cua_env ] && . /data/local/tmp/.cua_env; {cmd}"result = await self._adb_cmd_async("shell", cmd)return {"stdout": result.stdout.decode(errors="replace"),diff --git a/libs/python/cua-sandbox/cua_sandbox/transport/cloud.py b/libs/python/cua-sandbox/cua_sandbox/transport/cloud.pyindex 3e1f6c2bd5..384b52670b 100644--- a/libs/python/cua-sandbox/cua_sandbox/transport/cloud.py+++ b/libs/python/cua-sandbox/cua_sandbox/transport/cloud.py@@ -91,8 +91,27 @@ class CloudTransport(Transport):vm_info = await self._wait_for_running(vm_info)logger.debug("[cloud] VM %r is running", self._name)- # Resolve computer-server endpoint — auth with CUA API key + container name+ # Resolve computer-server endpoint — auth with CUA API key + container name.+ # In local-dev mode the API initially returns .cua.sh placeholder URLs and+ # replaces them with direct IPs once the container IP is known, so we poll+ # until we get a non-.cua.sh address. On prod the reverse-proxy .cua.sh URL+ # is the real endpoint, so we skip this loop entirely.cs_url = self._resolve_endpoint(vm_info)+ _is_local_dev = not self._base_url.rstrip("/").endswith("cua.sh") and (+ "localhost" in self._base_url+ or "127.0.0.1" in self._base_url+ or "0.0.0.0" in self._base_url+ )+ poll_elapsed = 0.0+ while _is_local_dev and (cs_url.endswith(".cua.sh") or ".cua.sh:" in cs_url):+ if poll_elapsed >= 120:+ break # Fall through — _wait_for_server_ready will handle the error+ await asyncio.sleep(3)+ poll_elapsed += 3+ vm_info = await self._get_vm(self._name)+ cs_url = self._resolve_endpoint(vm_info)+ logger.debug("[cloud] re-resolving endpoint: %s (%.0fs)", cs_url, poll_elapsed)+logger.debug("[cloud] resolved endpoint: %s", cs_url)self._inner = HTTPTransport(cs_url, api_key=api_key, container_name=self._name)logger.debug("[cloud] connecting inner HTTPTransport")@@ -104,8 +123,8 @@ class CloudTransport(Transport):await self._wait_for_server_ready()logger.debug("[cloud] computer-server ready")- # Apply image layers (e.g. APK installs) after server is ready- if self._image and self._image._layers:+ # Apply env vars and image layers (e.g. APK installs) after server is ready+ if self._image and (self._image._layers or self._image._env):logger.debug("[cloud] applying image layers")await self._apply_image_layers()@@ -117,6 +136,32 @@ class CloudTransport(Transport):await self._api_client.aclose()self._api_client = None+ async def create_snapshot(self, name: str | None = None, stateful: bool = False) -> dict:+ """Create a snapshot of this VM. Returns an image descriptor dict."""+ assert self._api_client and self._name+ resp = await self._api_client.post(+ f"/v1/vms/{self._name}/snapshot",+ json={"name": name or "", "stateful": stateful},+ timeout=600.0, # snapshot can take minutes on dir storage+ )+ resp.raise_for_status()+ data = resp.json()+ # Poll until snapshot is ready+ image_desc = data.get("image", data)+ snap_name = image_desc.get("snapshot", "")+ if snap_name:+ await self._wait_for_snapshot_ready(snap_name)+ return image_desc++ async def _wait_for_snapshot_ready(self, snapshot_name: str, timeout: float = 120) -> None:+ """Wait for snapshot to be ready.++ The API's snapshot endpoint is now synchronous — it blocks until the+ Kopf operator finishes the snapshot. This method is kept as a no-op+ for compatibility.+ """+ return+async def delete_vm(self) -> None:"""Delete the cloud VM via the platform API."""api_key = get_api_key(self._api_key_override)@@ -154,6 +199,18 @@ class CloudTransport(Transport):async def send(self, action: str, **params: Any) -> Any:assert self._inner, "Transport not connected"+ # Source .cua_env before run_command on Android (same as ADB/gRPC transports)+ if (+ action == "run_command"+ and "command" in params+ and self._image+ and self._image.os_type == "android"+ ):+ params = dict(params)+ params["command"] = (+ "[ -f /data/local/tmp/.cua_env ] && . /data/local/tmp/.cua_env; "+ + params["command"]+ )return await self._inner.send(action, **params)async def screenshot(self, format: str = "png", quality: int = 95) -> bytes:@@ -172,7 +229,7 @@ class CloudTransport(Transport):if not self._name:raise ValueError("Transport not connected — no VM name available")if not share:- return f"https://cua.ai/connect/incus/{self._name}"+ return f"https://cua.ai/connect/{self._name}"vm_info = await self._get_vm(self._name)password = vm_info.get("password", "")for ep in vm_info.get("endpoints", []):@@ -207,6 +264,20 @@ class CloudTransport(Transport):" Sandbox.create(image=Image.linux()) or Sandbox.create(image=Image.windows()) or Sandbox.create(image=Image.macos())\n""Or connect to an existing VM by name: Sandbox.connect(name='my-vm')")++ # Fork path: image came from sb.snapshot() — create VM from snapshot+ snap_source = getattr(self._image, "_snapshot_source", None)+ if snap_source:+ body = {+ "source": "snapshot",+ "instance": snap_source["instance"],+ "snapshot": snap_source["snapshot"],+ "instanceType": snap_source.get("instanceType", "vm"),+ }+ resp = await self._api_client.post("/v1/vms", json=body)+ resp.raise_for_status()+ return resp.json()+os_type = getattr(self._image, "os_type", None)if not os_type:raise ValueError(@@ -271,56 +342,125 @@ class CloudTransport(Transport):)async def _apply_image_layers(self) -> None:- """Apply image layers (APK installs, shell commands) after the VM is ready."""+ """Apply env vars and image layers (APK installs, PWA, shell commands) after the VM is ready."""import base64- import hashlib- import urllib.request- from pathlib import Pathassert self._inner++ # Apply environment variables by writing a .cua_env sourced file+ if self._image._env:+ import shlex++ lines = []+ for k, v in self._image._env:+ lines.append(f"export {k}={shlex.quote(v)}")+ env_content = "\n".join(lines) + "\n"+ await self._inner.send(+ "write_bytes",+ path="/data/local/tmp/.cua_env",+ content_b64=base64.b64encode(env_content.encode()).decode(),+ )+ logger.debug("[cloud] wrote %d env vars to .cua_env", len(self._image._env))+for layer in self._image._layers:lt = layer["type"]if lt == "apk_install":for apk in layer["packages"]:- dest = "/data/local/tmp/cua_install.apk"- # Resolve APK to local bytes (download URL if needed)- if apk.startswith(("http://", "https://")):- cache_dir = Path.home() / ".cua" / "cua-sandbox" / "apk-cache"- cache_dir.mkdir(parents=True, exist_ok=True)- cache_file = cache_dir / (- hashlib.sha256(apk.encode()).hexdigest()[:16] + ".apk"- )- if not cache_file.exists():- urllib.request.urlretrieve(apk, cache_file)- apk_bytes = cache_file.read_bytes()- else:- apk_bytes = Path(apk).read_bytes()- # Push to device via write_bytes (base64), then install- await self._inner.send(- "write_bytes",- path=dest,- content_b64=base64.b64encode(apk_bytes).decode(),- )- # Install; on signature mismatch uninstall existing and retry.- # The script always exits 0 so run_command does not raise.- await self._inner.send(- "run_command",- command=(- f"out=$(pm install -r {dest} 2>&1); "- f'if echo "$out" | grep -q INSTALL_FAILED_UPDATE_INCOMPATIBLE; then '- f' pkg=$(echo "$out" | sed -n "s/.*Package \\(\\S*\\) signatures.*/\\1/p"); '- f' pm uninstall "$pkg"; pm install -r {dest}; '- f'else echo "$out"; fi; true'- ),- timeout=90,- )+ await self._install_apk(apk)+ elif lt == "pwa_install":+ await self._install_pwa(layer)elif lt == "run":await self._inner.send("run_command", command=layer["command"], timeout=60)+ async def _install_apk(self, apk: str) -> None:+ """Download (if URL) and install an APK via the computer-server."""+ import base64+ import hashlib+ import urllib.request+ from pathlib import Path++ dest = "/data/local/tmp/cua_install.apk"+ if apk.startswith(("http://", "https://")):+ cache_dir = Path.home() / ".cua" / "cua-sandbox" / "apk-cache"+ cache_dir.mkdir(parents=True, exist_ok=True)+ cache_file = cache_dir / (hashlib.sha256(apk.encode()).hexdigest()[:16] + ".apk")+ if not cache_file.exists():+ urllib.request.urlretrieve(apk, cache_file)+ apk_bytes = cache_file.read_bytes()+ else:+ apk_bytes = Path(apk).read_bytes()++ await self._inner.send(+ "write_bytes",+ path=dest,+ content_b64=base64.b64encode(apk_bytes).decode(),+ )+ await self._inner.send(+ "run_command",+ command=(+ f"out=$(pm install -r {dest} 2>&1); "+ f'if echo "$out" | grep -q INSTALL_FAILED_UPDATE_INCOMPATIBLE; then '+ f' pkg=$(echo "$out" | sed -n "s/.*Package \\(\\S*\\) signatures.*/\\1/p"); '+ f' pm uninstall "$pkg"; pm install -r {dest}; '+ f'else echo "$out"; fi; true'+ ),+ timeout=90,+ )++ async def _install_pwa(self, layer: dict) -> None:+ """Build PWA APK on the host using bubblewrap, then push and install.++ Auto-installs Android SDK and bubblewrap if not present (same as local runtime).+ """+ import base64+ from pathlib import Path++ from cua_sandbox.runtime.android_emulator import (+ AndroidEmulatorRuntime,+ _ensure_sdk,+ )++ # Ensure Android SDK is available (auto-installs if missing)+ _ensure_sdk()++ manifest_url = layer["manifest_url"]+ pkg = layer.get("package_name")+ ks = Path(layer["keystore"]) if layer.get("keystore") else None+ ks_alias = layer.get("keystore_alias", "android")+ ks_pass = layer.get("keystore_password", "android")++ # Build APK on host (auto-installs bubblewrap via npm if missing)+ runtime = AndroidEmulatorRuntime.__new__(AndroidEmulatorRuntime)+ apk_path, fingerprint = await runtime._build_pwa_apk(+ manifest_url, pkg, ks, ks_alias, ks_pass+ )+ logger.info(f"[cloud] PWA APK built: {apk_path} (fingerprint: {fingerprint})")++ apk_bytes = Path(apk_path).read_bytes()+ dest = "/data/local/tmp/cua_pwa.apk"+ await self._inner.send(+ "write_bytes",+ path=dest,+ content_b64=base64.b64encode(apk_bytes).decode(),+ )+ await self._inner.send(+ "run_command",+ command=f"pm install -r {dest} 2>&1; true",+ timeout=120,+ )+ # Suppress Chrome first-run wizard for TWA+ for cmd in [+ "am set-debug-app --persistent com.android.chrome",+ "mkdir -p /data/local/tmp && "+ "echo 'chrome --no-first-run --disable-fre --no-default-browser-check' "+ "> /data/local/tmp/chrome-command-line",+ ]:+ await self._inner.send("run_command", command=cmd, timeout=10)+@staticmethoddef _resolve_endpoint(vm_info: dict) -> str:"""Build the computer-server HTTP URL from VM info."""- # Prefer explicit endpoints array (Incus VMs)+ # Prefer explicit endpoints arrayfor ep in vm_info.get("endpoints", []):if ep.get("name") in ("computer-server", "api"):host = ep["host"]diff --git a/libs/python/cua-sandbox/cua_sandbox/transport/grpc_emulator.py b/libs/python/cua-sandbox/cua_sandbox/transport/grpc_emulator.pyindex 6a50c293fd..1fabfc5b31 100644--- a/libs/python/cua-sandbox/cua_sandbox/transport/grpc_emulator.py+++ b/libs/python/cua-sandbox/cua_sandbox/transport/grpc_emulator.py@@ -15,6 +15,7 @@ from __future__ import annotationsimport asyncioimport functools+import platformimport shutilimport subprocessfrom io import BytesIO@@ -39,9 +40,10 @@ if TYPE_CHECKING:def _find_adb(sdk_root: Optional[str] = None) -> str:if sdk_root:- candidate = Path(sdk_root) / "platform-tools" / "adb"- if candidate.exists():- return str(candidate)+ for ext in (".exe", "") if platform.system().lower() == "windows" else ("",):+ candidate = Path(sdk_root) / "platform-tools" / f"adb{ext}"+ if candidate.exists():+ return str(candidate)found = shutil.which("adb")if found:return found@@ -165,6 +167,7 @@ class GRPCEmulatorTransport(Transport):if action in ("shell", "execute", "run_command"):assert self._adb is not None, "Transport not connected"cmd = params.get("command", "")+ cmd = f"[ -f /data/local/tmp/.cua_env ] && . /data/local/tmp/.cua_env; {cmd}"timeout = float(params.get("timeout", 15))loop = asyncio.get_event_loop()result = await loop.run_in_executor(diff --git a/libs/python/cua-sandbox/cua_sandbox/transport/local.py b/libs/python/cua-sandbox/cua_sandbox/transport/local.pyindex 65a8b205ce..8213d3542d 100644--- a/libs/python/cua-sandbox/cua_sandbox/transport/local.py+++ b/libs/python/cua-sandbox/cua_sandbox/transport/local.py@@ -47,8 +47,18 @@ class LocalTransport(Transport):p.get("x"), p.get("y"), p.get("button", "left")),"mouse_up": lambda p: mouse.mouse_up(p.get("x"), p.get("y"), p.get("button", "left")),- "drag": lambda p: mouse.drag(- p["start_x"], p["start_y"], p["end_x"], p["end_y"], p.get("button", "left")+ "drag": lambda p: (+ mouse.drag(+ p["path"][0][0],+ p["path"][0][1],+ p["path"][-1][0],+ p["path"][-1][1],+ p.get("button", "left"),+ )+ if "path" in p+ else mouse.drag(+ p["start_x"], p["start_y"], p["end_x"], p["end_y"], p.get("button", "left")+ )),# Keyboard"type_text": lambda p: keyboard.type_text(p["text"]),diff --git a/libs/python/cua-sandbox/tests/image/__init__.py b/libs/python/cua-sandbox/tests/image/__init__.pynew file mode 100644index 0000000000..e69de29bb2diff --git a/libs/python/cua-sandbox/tests/interfaces/__init__.py b/libs/python/cua-sandbox/tests/interfaces/__init__.pynew file mode 100644index 0000000000..e69de29bb2diff --git a/libs/python/cua-sandbox/tests/test_android_multitouch.py b/libs/python/cua-sandbox/tests/test_android_multitouch.pyindex 9330b8ef71..e4e29d5612 100644--- a/libs/python/cua-sandbox/tests/test_android_multitouch.py+++ b/libs/python/cua-sandbox/tests/test_android_multitouch.py@@ -49,6 +49,7 @@ import pytestimport pytest_asynciofrom cua_sandbox.image import Imagefrom cua_sandbox.runtime.android_emulator import AndroidEmulatorRuntime+from cua_sandbox.runtime.compat import skip_if_unsupportedfrom cua_sandbox.sandbox import Sandbox# ── Config ─────────────────────────────────────────────────────────────────@@ -141,7 +142,13 @@ async def local_android_sb():Boot a single AndroidEmulatorRuntime via Sandbox.ephemeral(), install the TouchTestAPK, escalate to root, launch the app, and yield the ready Sandbox.Shared across all local tests so we only pay the boot cost once.++ The compatibility gate lives here (not in the autouse reset fixture) so that+ cloud tests, which have their own API-key gate and don't depend on a local+ emulator, are not affected when local Android support is absent."""+ skip_if_unsupported(Image.android(str(_API_LEVEL)))+apk = _get_apk()runtime = AndroidEmulatorRuntime(@@ -162,12 +169,17 @@ async def local_android_sb():@pytest_asyncio.fixture(autouse=True)-async def _reset_between_tests(request, local_android_sb: Sandbox):- """Clear logcat + app event counter before every local test."""+async def _reset_between_tests(request):+ """Clear logcat + app event counter before every local test.++ Resolves local_android_sb lazily so that cloud tests (which don't request+ the local emulator fixture) don't trigger emulator boot or the compat skip.+ """if "local_android_sb" not in request.fixturenames:yieldreturn- await _reset(local_android_sb)+ sb = request.getfixturevalue("local_android_sb")+ await _reset(sb)yield@@ -431,6 +443,7 @@ class TestAndroidMultitouchLocal(_MultitouchTests):# ══════════════════════════════════════════════════════════════════════════════skip_no_api_key = pytest.mark.skipif(not _API_KEY, reason="CUA_TEST_API_KEY not set")+# Note: cloud Android tests are gated by API key only — hardware compat is the cloud's concern.@pytest_asyncio.fixture(scope="session", loop_scope="session")diff --git a/libs/python/cua-sandbox/tests/test_runtime.py b/libs/python/cua-sandbox/tests/test_runtime.pyindex 0bebcb1da2..4ca681cf48 100644--- a/libs/python/cua-sandbox/tests/test_runtime.py+++ b/libs/python/cua-sandbox/tests/test_runtime.py@@ -548,7 +548,6 @@ async def test_cloud_linux_ephemeral():"""Cloud sandbox: Sandbox.ephemeral with linux image (local=False)."""async with Sandbox.ephemeral(Image.linux("ubuntu", "24.04"),- name="cua-test-cloud-linux",) as sb:result = await sb.shell.run("uname -s")assert result.success@@ -563,7 +562,6 @@ async def test_cloud_android_ephemeral():"""Cloud sandbox: Sandbox.ephemeral with android image (local=False)."""async with Sandbox.ephemeral(Image.android("14"),- name="cua-test-cloud-android",) as sb:screenshot = await sb.screenshot()assert screenshot[:4] == b"\x89PNG"diff --git a/libs/python/cua-sandbox/tests/test_snapshots.py b/libs/python/cua-sandbox/tests/test_snapshots.pynew file mode 100644index 0000000000..dca113c3da--- /dev/null+++ b/libs/python/cua-sandbox/tests/test_snapshots.py@@ -0,0 +1,110 @@+"""Snapshot integration tests — images all the way down.++Tests both Linux VM and Android container snapshot workflows:+1. Create sandbox → install something → snapshot → returns Image+2. Boot from snapshot Image → verify install persists → measure fork is faster+3. Verify state isolation (changes after snapshot don't leak to fork)++Run against local dev stack:+ CUA_API_KEY=sk-dev-test-key-local-12345 CUA_BASE_URL=http://localhost:8082 \+ pytest tests/test_snapshots.py -v -s+"""++from __future__ import annotations++import os+import time++import pytest+from cua_sandbox import Image, Sandbox++pytestmark = pytest.mark.asyncio+++def _has_cua_api_key() -> bool:+ return bool(os.environ.get("CUA_API_KEY"))++[email protected](not _has_cua_api_key(), reason="CUA_API_KEY not set")+async def test_snapshot_linux():+ """Linux: create → install cowsay → snapshot → boot from snapshot → verify."""+ t_create_start = time.monotonic()++ async with Sandbox.ephemeral(Image.linux("ubuntu", "24.04")) as sb:+ # Install something unique+ result = await sb.shell.run(+ "apt-get update -qq && apt-get install -y -qq cowsay", timeout=120+ )+ assert result.success, f"Install failed: {result.stderr}"++ # Measure create+install time only after install completes+ t_create = time.monotonic() - t_create_start++ # Verify it works+ result = await sb.shell.run("/usr/games/cowsay hello")+ assert result.success+ assert "hello" in result.stdout++ # Snapshot → returns Image+ cowsay_image = await sb.snapshot(name="with-cowsay")+ assert cowsay_image is not None+ assert cowsay_image._snapshot_source is not None++ # Boot from snapshot image — should be faster (COW fork)+ t_fork_start = time.monotonic()+ async with Sandbox.ephemeral(cowsay_image) as sb2:+ t_fork = time.monotonic() - t_fork_start++ # cowsay should still be installed+ result = await sb2.shell.run("/usr/games/cowsay forked!")+ assert result.success, f"cowsay not found in fork: {result.stderr}"+ assert "forked!" in result.stdout++ print(f"\nCreate+install: {t_create:.1f}s, Fork from snapshot: {t_fork:.1f}s")+ # Fork should be faster than original create + install+ assert (+ t_fork < t_create+ ), f"Fork ({t_fork:.1f}s) should be faster than create ({t_create:.1f}s)"++[email protected](not _has_cua_api_key(), reason="CUA_API_KEY not set")+async def test_snapshot_android():+ """Android: create with F-Droid → snapshot → boot from snapshot → APK persists."""+ FDROID_APK = "https://f-droid.org/F-Droid.apk"+ t_create_start = time.monotonic()++ async with Sandbox.ephemeral(Image.android("14").apk_install(FDROID_APK)) as sb:+ t_create = time.monotonic() - t_create_start++ # Verify F-Droid installed (sb.shell.run on android → adb shell)+ result = await sb.shell.run("pm list packages org.fdroid.fdroid")+ assert result.success+ assert "org.fdroid.fdroid" in result.stdout++ screenshot = await sb.screenshot()+ assert screenshot[:4] == b"\x89PNG"++ # Snapshot → Image+ fdroid_image = await sb.snapshot(name="with-fdroid")++ # Boot from snapshot — F-Droid should persist+ t_fork_start = time.monotonic()+ async with Sandbox.ephemeral(fdroid_image) as sb2:+ t_fork = time.monotonic() - t_fork_start++ result = await sb2.shell.run("pm list packages org.fdroid.fdroid")+ assert result.success, f"F-Droid not found in fork: {result.stderr}"+ assert "org.fdroid.fdroid" in result.stdout++ screenshot = await sb2.screenshot()+ assert screenshot[:4] == b"\x89PNG"+ assert len(screenshot) > 1000++ print(f"\nCreate+install: {t_create:.1f}s, Fork from snapshot: {t_fork:.1f}s")+ # On COW storage (btrfs/zfs), fork is instant. On dir storage the copy+ # is a full rsync so it can be slower than the original create. Only+ # assert that the fork completed (timing checked on COW backends in CI).+ if t_fork < t_create:+ print(" → Fork was faster (COW or small image)")+ else:+ print(" → Fork was slower (dir storage — expected)")diff --git a/libs/python/cua-sandbox/uv.lock b/libs/python/cua-sandbox/uv.lockindex 63e979ed12..1fcf42ddfb 100644--- a/libs/python/cua-sandbox/uv.lock+++ b/libs/python/cua-sandbox/uv.lock@@ -407,7 +407,7 @@ wheels = [[[package]]name = "cua-agent"-version = "0.7.38"+version = "0.7.39"source = { editable = "../agent" }dependencies = [{ name = "aiohttp" },@@ -417,6 +417,7 @@ dependencies = [{ name = "cua-core" },{ name = "httpx" },{ name = "litellm" },+ { name = "pillow" },{ name = "pydantic" },{ name = "python-dotenv" },{ name = "rich" },@@ -452,6 +453,7 @@ requires-dist = [{ name = "litellm", specifier = "==1.80.0" },{ name = "mlx-vlm", marker = "sys_platform == 'darwin' and extra == 'all'", specifier = ">=0.1.27" },{ name = "mlx-vlm", marker = "sys_platform == 'darwin' and extra == 'uitars-mlx'", specifier = ">=0.1.27" },+ { name = "pillow", specifier = ">=10.0.0" },{ name = "pillow", marker = "extra == 'all'", specifier = ">=10.0.0" },{ name = "pillow", marker = "extra == 'cloud'", specifier = ">=10.0.0" },{ name = "pillow", marker = "extra == 'qwen'", specifier = ">=10.0.0" },@@ -506,7 +508,7 @@ wheels = [[[package]]name = "cua-core"-version = "0.1.18"+version = "0.1.19"source = { editable = "../core" }dependencies = [{ name = "posthog" },@@ -529,7 +531,7 @@ dev = [{ name = "pytest", specifier = ">=8.3.5" }][[package]]name = "cua-sandbox"-version = "0.1.1"+version = "0.1.2"source = { editable = "." }dependencies = [{ name = "cua-auto" },diff --git a/libs/python/cua/cua/__init__.py b/libs/python/cua/cua/__init__.pyindex 1686c34782..ab85f8acc2 100644--- a/libs/python/cua/cua/__init__.py+++ b/libs/python/cua/cua/__init__.py@@ -40,22 +40,79 @@ from cua_sandbox import ()# ----------------------------------------------------------------------------# cua-agent surface (lazy to avoid import-time side effects when only-# sandbox symbols are needed)+# Runtime compatibility helpers — lazily imported so older cua-sandbox+# releases that pre-date compat.py still work.# ---------------------------------------------------------------------------+try:+ from cua_sandbox.runtime.compat import (+ RuntimeSupport,+ check_local_support,+ skip_if_unsupported,+ )+except ImportError: # cua-sandbox < compat.py introduction++ def _missing_compat(*_args, **_kwargs): # type: ignore[misc]+ raise ImportError(+ "cua_sandbox.runtime.compat is not available in this version of cua-sandbox. "+ "Upgrade cua-sandbox to use RuntimeSupport, check_local_support, or skip_if_unsupported."+ )++ RuntimeSupport = _missing_compat # type: ignore[assignment,misc]+ check_local_support = _missing_compat # type: ignore[assignment]+ skip_if_unsupported = _missing_compat # type: ignore[assignment]++# ---------------------------------------------------------------------------+# Lazy imports — runtime classes, interface types, agent surface.+# These are pulled in on first attribute access so that `import cua` stays+# fast even when heavy optional deps (grpcio, vncdotool, …) are not installed.+# ---------------------------------------------------------------------------++_RUNTIME_NAMES: dict[str, tuple[str, str]] = {+ # name -> (module, attr)+ "DockerRuntime": ("cua_sandbox.runtime.docker", "DockerRuntime"),+ "QEMURuntime": ("cua_sandbox.runtime.qemu", "QEMURuntime"),+ "LumeRuntime": ("cua_sandbox.runtime.lume", "LumeRuntime"),+ "AndroidEmulatorRuntime": ("cua_sandbox.runtime.android_emulator", "AndroidEmulatorRuntime"),+ "HyperVRuntime": ("cua_sandbox.runtime.hyperv", "HyperVRuntime"),+ "RuntimeInfo": ("cua_sandbox.runtime.base", "RuntimeInfo"),+}++_INTERFACE_NAMES: dict[str, tuple[str, str]] = {+ "Shell": ("cua_sandbox.interfaces.shell", "Shell"),+ "CommandResult": ("cua_sandbox.interfaces.shell", "CommandResult"),+ "Mouse": ("cua_sandbox.interfaces.mouse", "Mouse"),+ "Keyboard": ("cua_sandbox.interfaces.keyboard", "Keyboard"),+ "Screen": ("cua_sandbox.interfaces.screen", "Screen"),+ "Clipboard": ("cua_sandbox.interfaces.clipboard", "Clipboard"),+ "Tunnel": ("cua_sandbox.interfaces.tunnel", "Tunnel"),+ "TunnelInfo": ("cua_sandbox.interfaces.tunnel", "TunnelInfo"),+ "Mobile": ("cua_sandbox.interfaces.mobile", "Mobile"),+ "Terminal": ("cua_sandbox.interfaces.terminal", "Terminal"),+ "Window": ("cua_sandbox.interfaces.window", "Window"),+}++_AGENT_NAMES: dict[str, tuple[str, str]] = {+ "ComputerAgent": ("agent", "ComputerAgent"),+ "AgentResponse": ("agent", "AgentResponse"),+ "Messages": ("agent", "Messages"),+ "register_agent": ("agent", "register_agent"),+}++_LAZY: dict[str, tuple[str, str]] = {**_RUNTIME_NAMES, **_INTERFACE_NAMES, **_AGENT_NAMES}def __getattr__(name: str):- _AGENT_NAMES = {"ComputerAgent", "AgentResponse", "Messages", "register_agent"}- if name in _AGENT_NAMES:- import agent as _agent+ if name in _LAZY:+ mod_path, attr = _LAZY[name]+ import importlib- return getattr(_agent, name)+ mod = importlib.import_module(mod_path)+ return getattr(mod, attr)raise AttributeError(f"module 'cua' has no attribute {name!r}")__all__ = [- # cua-sandbox+ # cua-sandbox core"configure","login","whoami",@@ -66,6 +123,29 @@ __all__ = ["Localhost","localhost","CloudTransport",+ # runtime compat (always available)+ "RuntimeSupport",+ "check_local_support",+ "skip_if_unsupported",+ # runtime classes (lazy)+ "DockerRuntime",+ "QEMURuntime",+ "LumeRuntime",+ "AndroidEmulatorRuntime",+ "HyperVRuntime",+ "RuntimeInfo",+ # interface types (lazy)+ "Shell",+ "CommandResult",+ "Mouse",+ "Keyboard",+ "Screen",+ "Clipboard",+ "Tunnel",+ "TunnelInfo",+ "Mobile",+ "Terminal",+ "Window",# cua-agent (lazy)"ComputerAgent","AgentResponse",diff --git a/libs/python/cua/pyproject.toml b/libs/python/cua/pyproject.tomlindex c4632633c3..311ac60477 100644--- a/libs/python/cua/pyproject.toml+++ b/libs/python/cua/pyproject.toml@@ -66,3 +66,8 @@ exclude = [[tool.hatch.build.targets.wheel]packages = ["cua"]++[tool.uv.sources]+cua-sandbox = { path = "../cua-sandbox", editable = true }+cua-agent = { path = "../agent", editable = true }+cua-cli = { path = "../cua-cli", editable = true }diff --git a/scripts/gen_interface_docs.py b/scripts/gen_interface_docs.pynew file mode 100644index 0000000000..8b10128568--- /dev/null+++ b/scripts/gen_interface_docs.py@@ -0,0 +1,323 @@+#!/usr/bin/env python3+"""Generate docs/content/docs/cua/reference/sandbox-sdk/interfaces.mdx+from the pydocstrings in cua_sandbox/interfaces/*.py.++Usage:+ python scripts/gen_interface_docs.py+ python scripts/gen_interface_docs.py --dry-run # print to stdout only++The script introspects each interface module, collects class/method+docstrings + signatures, and emits structured MDX.+"""++from __future__ import annotations++import argparse+import ast+import inspect+import textwrap+from pathlib import Path++REPO_ROOT = Path(__file__).resolve().parent.parent+INTERFACES_DIR = REPO_ROOT / "libs/python/cua-sandbox/cua_sandbox/interfaces"+OUTPUT_FILE = REPO_ROOT / "docs/content/docs/cua/reference/sandbox-sdk/interfaces.mdx"++# Order in which classes appear in the output+CLASS_ORDER = [+ "Shell",+ "CommandResult",+ "Mouse",+ "Keyboard",+ "Screen",+ "Clipboard",+ "Tunnel",+ "TunnelInfo",+ "Terminal",+ "Window",+ "Mobile",+]++# Module file for each class+CLASS_MODULE = {+ "Shell": "shell",+ "CommandResult": "shell",+ "Mouse": "mouse",+ "Keyboard": "keyboard",+ "Screen": "screen",+ "Clipboard": "clipboard",+ "Tunnel": "tunnel",+ "TunnelInfo": "tunnel",+ "Terminal": "terminal",+ "Window": "window",+ "Mobile": "mobile",+}++# ── AST helpers ──────────────────────────────────────────────────────────────+++def _parse_module(path: Path) -> ast.Module:+ return ast.parse(path.read_text())+++def _get_docstring(node) -> str:+ ds = ast.get_docstring(node) or ""+ return textwrap.dedent(ds).strip()+++def _format_arg(arg: ast.arg, defaults: dict[str, ast.expr]) -> str:+ name = arg.arg+ annotation = ""+ if arg.annotation:+ annotation = f": {ast.unparse(arg.annotation)}"+ default = ""+ if name in defaults:+ default = f" = {ast.unparse(defaults[name])}"+ return f"{name}{annotation}{default}"+++def _method_signature(func: ast.FunctionDef) -> str:+ """Return a human-readable signature string (without 'self')."""+ args = func.args+ # Build default map: last N positional args get the last N defaults+ all_args = args.args+ defaults = {}+ n_defaults = len(args.defaults)+ if n_defaults:+ for arg, default in zip(all_args[-n_defaults:], args.defaults):+ defaults[arg.arg] = default++ # kwonly defaults+ for arg, default in zip(args.kwonlyargs, args.kw_defaults):+ if default is not None:+ defaults[arg.arg] = default++ parts = []+ for arg in all_args:+ if arg.arg == "self":+ continue+ parts.append(_format_arg(arg, defaults))++ for arg in args.kwonlyargs:+ parts.append(_format_arg(arg, defaults))++ if args.vararg:+ parts.append(f"*{args.vararg.arg}")+ if args.kwarg:+ parts.append(f"**{args.kwarg.arg}")++ ret = ""+ if func.returns:+ ret = f" -> {ast.unparse(func.returns)}"++ return f"({', '.join(parts)}){ret}"+++def _is_public(name: str) -> bool:+ return not name.startswith("_")+++# ── Collect info ─────────────────────────────────────────────────────────────+++class FieldInfo:+ def __init__(self, name: str, annotation: str):+ self.name = name+ self.annotation = annotation+++class MethodInfo:+ def __init__(self, name: str, sig: str, doc: str, is_async: bool, is_property: bool):+ self.name = name+ self.sig = sig+ self.doc = doc+ self.is_async = is_async+ self.is_property = is_property+++class ClassInfo:+ def __init__(self, name: str, doc: str, fields: list[FieldInfo], methods: list[MethodInfo]):+ self.name = name+ self.doc = doc+ self.fields = fields+ self.methods = methods+++def _collect_class(tree: ast.Module, class_name: str) -> ClassInfo | None:+ for node in ast.walk(tree):+ if not isinstance(node, ast.ClassDef) or node.name != class_name:+ continue+ doc = _get_docstring(node)+ fields: list[FieldInfo] = []+ methods: list[MethodInfo] = []+ for item in node.body:+ # Dataclass-style annotated field: `name: type` or `name: type = value`+ if isinstance(item, ast.AnnAssign) and isinstance(item.target, ast.Name):+ fname = item.target.id+ if _is_public(fname):+ ann = ast.unparse(item.annotation) if item.annotation else ""+ fields.append(FieldInfo(name=fname, annotation=ann))+ elif isinstance(item, ast.FunctionDef | ast.AsyncFunctionDef):+ if not _is_public(item.name):+ continue+ is_property = any(+ (isinstance(d, ast.Name) and d.id == "property")+ or (isinstance(d, ast.Attribute) and d.attr == "property")+ for d in item.decorator_list+ )+ methods.append(+ MethodInfo(+ name=item.name,+ sig=_method_signature(item),+ doc=_get_docstring(item),+ is_async=isinstance(item, ast.AsyncFunctionDef),+ is_property=is_property,+ )+ )+ return ClassInfo(name=class_name, doc=doc, fields=fields, methods=methods)+ return None+++def collect_all() -> list[ClassInfo]:+ infos = []+ for class_name in CLASS_ORDER:+ mod_name = CLASS_MODULE[class_name]+ path = INTERFACES_DIR / f"{mod_name}.py"+ if not path.exists():+ print(f" [skip] {path} not found")+ continue+ tree = _parse_module(path)+ info = _collect_class(tree, class_name)+ if info:+ infos.append(info)+ else:+ print(f" [warn] class {class_name} not found in {path}")+ return infos+++# ── MDX rendering ─────────────────────────────────────────────────────────────+++def _escape_mdx(text: str) -> str:+ """Escape <> in doc text so MDX doesn't treat them as JSX tags.++ Preserves content inside backtick code spans and fenced code blocks.+ """+ import re++ # Split on backtick-delimited segments (`` ` `` or ``` `` ```)+ # Odd-indexed segments are inside backticks — leave them alone+ parts = re.split(r"(```.+?```|``.+?``|`.+?`)", text, flags=re.DOTALL)+ for i, part in enumerate(parts):+ if i % 2 == 0: # outside code+ parts[i] = (+ part.replace("<", "<")+ .replace(">", ">")+ .replace("{", "{")+ .replace("}", "}")+ )+ return "".join(parts)+++def _render_method(m: MethodInfo) -> str:+ lines = []+ prefix = "async " if m.is_async else ""+ prop = "@property\n" if m.is_property else ""+ lines.append(f"#### `{prop}{prefix}{m.name}{m.sig}`\n")+ if m.doc:+ lines.append(_escape_mdx(m.doc))+ lines.append("")+ return "\n".join(lines)+++def _render_class(c: ClassInfo) -> str:+ lines = []+ lines.append(f"## `{c.name}`\n")+ if c.doc:+ lines.append(_escape_mdx(c.doc))+ lines.append("")++ if c.fields:+ lines.append("### Fields\n")+ lines.append("| Name | Type |")+ lines.append("|------|------|")+ for f in c.fields:+ lines.append(f"| `{f.name}` | `{_escape_mdx(f.annotation)}` |")+ lines.append("")++ if c.methods:+ lines.append("### Methods\n")+ for m in c.methods:+ lines.append(_render_method(m))++ return "\n".join(lines)+++HEADER = """\+---+title: Interfaces Reference+description: Auto-generated reference for all cua-sandbox interface classes. Do not edit manually — run scripts/gen_interface_docs.py to regenerate.+---++import { Callout } from "fumadocs-ui/components/callout";++<Callout type="info">+ This page is auto-generated from the Python source docstrings.+ Run `python scripts/gen_interface_docs.py` to regenerate after editing interface code.+</Callout>++The sandbox exposes the following interface objects on every `Sandbox` instance:++| Attribute | Class | Purpose |+|-----------|-------|---------|+| `sb.shell` | `Shell` | Run shell commands |+| `sb.mouse` | `Mouse` | Mouse control |+| `sb.keyboard` | `Keyboard` | Keyboard control |+| `sb.screen` | `Screen` | Screenshots and screen info |+| `sb.clipboard` | `Clipboard` | Clipboard read/write |+| `sb.tunnel` | `Tunnel` | Port forwarding |+| `sb.terminal` | `Terminal` | PTY terminal sessions |+| `sb.window` | `Window` | Window management |+| `sb.mobile` | `Mobile` | Mobile-specific actions |++---++"""+++def render(infos: list[ClassInfo]) -> str:+ parts = [HEADER]+ for info in infos:+ parts.append(_render_class(info))+ parts.append("\n---\n\n")+ return "\n".join(parts)+++# ── Main ──────────────────────────────────────────────────────────────────────+++def main() -> None:+ parser = argparse.ArgumentParser(description=__doc__)+ parser.add_argument(+ "--dry-run",+ action="store_true",+ help="Print output to stdout instead of writing to file",+ )+ args = parser.parse_args()++ print(f"Collecting interfaces from {INTERFACES_DIR} ...")+ infos = collect_all()+ print(f" Found {len(infos)} classes: {[c.name for c in infos]}")++ content = render(infos)++ if args.dry_run:+ print("\n" + "=" * 60 + "\n")+ print(content)+ else:+ OUTPUT_FILE.parent.mkdir(parents=True, exist_ok=True)+ OUTPUT_FILE.write_text(content)+ print(f"Written to {OUTPUT_FILE}")+++if __name__ == "__main__":+ main()diff --git a/tests/pytest.ini b/tests/pytest.iniindex 998cbeafb2..7c14af8064 100644--- a/tests/pytest.ini+++ b/tests/pytest.ini@@ -1,4 +1,8 @@[pytest]asyncio_mode = auto+pythonpath =+ ../libs/python/cua+ ../libs/python/cua-sandbox+ ../libs/python/agentmarkers =asyncio: asyncio mark\ No newline at end of filediff --git a/tests/test_image_builder.py b/tests/test_image_builder.pynew file mode 100644index 0000000000..89963419aa--- /dev/null+++ b/tests/test_image_builder.py@@ -0,0 +1,408 @@+"""Integration tests for Image builder methods across all guest OS types.++Every image builder method is tested on every guest OS that supports it.+Tests auto-skip via skip_if_unsupported() when the required runtime is+not installed on this host.++Run with:+ pytest tests/test_image_builder.py -v+ pytest tests/test_image_builder.py -v -k linux # only linux tests+"""++from __future__ import annotations++import pytest+from cua import Image, Sandbox, skip_if_unsupported++# ── helpers ──────────────────────────────────────────────────────────────────+++async def _run(image: Image, cmd: str) -> str:+ """Ephemeral sandbox: run cmd and return stdout. Asserts success."""+ async with Sandbox.ephemeral(image, local=True) as sb:+ r = await sb.shell.run(cmd, timeout=120)+ assert r.success, f"Command failed (rc={r.returncode}): {r.stderr}"+ return r.stdout.strip()+++# ═══════════════════════════════════════════════════════════════════════════+# Linux (Docker container)+# ═══════════════════════════════════════════════════════════════════════════+++class TestLinuxAptInstall:+ def _base(self):+ return Image.linux()++ def setup_method(self):+ skip_if_unsupported(self._base())++ async def test_single_package(self):+ image = self._base().apt_install("curl")+ out = await _run(image, "curl --version")+ assert "curl" in out.lower()++ async def test_multiple_packages(self):+ image = self._base().apt_install("curl", "wget")+ out = await _run(image, "curl --version && wget --version")+ assert "curl" in out.lower()++ async def test_chained_calls(self):+ image = self._base().apt_install("curl").apt_install("wget")+ out = await _run(image, "curl --version && wget --version")+ assert "curl" in out.lower()+++class TestLinuxPipInstall:+ def _base(self):+ return Image.linux().apt_install("python3-pip")++ def setup_method(self):+ skip_if_unsupported(Image.linux())++ async def test_single_package(self):+ image = self._base().pip_install("httpx")+ out = await _run(image, "python3 -c 'import httpx; print(httpx.__version__)'")+ assert out # any version string++ async def test_multiple_packages(self):+ image = self._base().pip_install("httpx", "rich")+ out = await _run(image, "python3 -c 'import httpx, rich; print(\"ok\")'")+ assert "ok" in out+++class TestLinuxUvInstall:+ def setup_method(self):+ skip_if_unsupported(Image.linux())++ async def test_single_package(self):+ image = Image.linux().uv_install("httpx")+ out = await _run(image, "uv run python -c 'import httpx; print(\"ok\")'")+ assert "ok" in out++ async def test_multiple_packages(self):+ image = Image.linux().uv_install("httpx", "rich")+ out = await _run(image, "uv run python -c 'import httpx, rich; print(\"ok\")'")+ assert "ok" in out+++class TestLinuxRun:+ def setup_method(self):+ skip_if_unsupported(Image.linux())++ async def test_writes_file(self):+ image = Image.linux().run("echo 'hello' > /etc/hello.txt")+ out = await _run(image, "cat /etc/hello.txt")+ assert "hello" in out++ async def test_creates_directory(self):+ image = Image.linux().run("mkdir -p /opt/myapp")+ out = await _run(image, "test -d /opt/myapp && echo exists")+ assert "exists" in out++ async def test_chained(self):+ image = Image.linux().run("mkdir -p /opt/myapp").run("echo 'v1' > /opt/myapp/version.txt")+ out = await _run(image, "cat /opt/myapp/version.txt")+ assert "v1" in out+++class TestLinuxEnv:+ def setup_method(self):+ skip_if_unsupported(Image.linux())++ async def test_single_variable(self):+ image = Image.linux().env(MY_VAR="hello_integration")+ out = await _run(image, "echo $MY_VAR")+ assert "hello_integration" in out++ async def test_multiple_variables(self):+ image = Image.linux().env(VAR_A="alpha", VAR_B="beta")+ out = await _run(image, "echo $VAR_A $VAR_B")+ assert "alpha" in out+ assert "beta" in out++ async def test_variable_used_in_run(self):+ image = Image.linux().env(APP_PORT="8080").run("echo port=$APP_PORT > /tmp/port.txt")+ out = await _run(image, "cat /tmp/port.txt")+ assert "8080" in out+++class TestLinuxCopy:+ def setup_method(self):+ skip_if_unsupported(Image.linux())++ async def test_copy_file(self, tmp_path):+ src = tmp_path / "hello.txt"+ src.write_text("from host")+ image = Image.linux().copy(str(src), "/tmp/hello.txt")+ out = await _run(image, "cat /tmp/hello.txt")+ assert "from host" in out++ async def test_copy_preserves_content(self, tmp_path):+ src = tmp_path / "data.json"+ src.write_text('{"key": "value"}')+ image = Image.linux().copy(str(src), "/tmp/data.json")+ out = await _run(image, "cat /tmp/data.json")+ assert '"key"' in out+++class TestLinuxExpose:+ def setup_method(self):+ skip_if_unsupported(Image.linux())++ async def test_expose_port_reachable(self):+ """expose() should not raise — container starts with the port mapped."""+ image = Image.linux().expose(9999)+ async with Sandbox.ephemeral(image, local=True) as sb:+ # Just verify the sandbox is reachable; port mapping is a docker-run concern+ r = await sb.shell.run("echo ok")+ assert r.success+++class TestLinuxFromRegistry:+ def setup_method(self):+ skip_if_unsupported(Image.linux())++ async def test_ubuntu_22(self):+ # from_registry with plain images only works if the image has computer-server.+ # Use the cua base image which always has it.+ image = Image.from_registry("docker.io/trycua/cua-xfce:latest")+ out = await _run(image, "cat /etc/os-release")+ assert "ubuntu" in out.lower() or "linux" in out.lower()++ async def test_debian(self):+ # Same constraint — use cua base image.+ image = Image.from_registry("docker.io/trycua/cua-xfce:latest")+ out = await _run(image, "uname -s")+ assert "linux" in out.lower()+++class TestLinuxFullChain:+ def setup_method(self):+ skip_if_unsupported(Image.linux())++ async def test_full_chain(self, tmp_path):+ src = tmp_path / "app.sh"+ src.write_text("#!/bin/sh\necho app-$VERSION\n")+ image = (+ Image.linux()+ .apt_install("curl")+ .env(VERSION="1.0.0")+ .copy(str(src), "/usr/local/bin/app.sh")+ .run("chmod +x /usr/local/bin/app.sh")+ .expose(8080)+ )+ out = await _run(image, "/usr/local/bin/app.sh")+ assert "app-1.0.0" in out+++# ═══════════════════════════════════════════════════════════════════════════+# macOS VM+# ═══════════════════════════════════════════════════════════════════════════+++class TestMacOSBrewInstall:+ def setup_method(self):+ skip_if_unsupported(Image.macos())++ async def test_single_package(self):+ image = Image.macos().brew_install("jq")+ out = await _run(image, "jq --version")+ assert "jq" in out++ async def test_multiple_packages(self):+ image = Image.macos().brew_install("jq", "wget")+ out = await _run(image, "jq --version && wget --version")+ assert "jq" in out+++class TestMacOSRun:+ def setup_method(self):+ skip_if_unsupported(Image.macos())++ async def test_run_command(self):+ image = Image.macos().run("echo setup > /tmp/setup.txt")+ out = await _run(image, "cat /tmp/setup.txt")+ assert "setup" in out+++class TestMacOSEnv:+ def setup_method(self):+ skip_if_unsupported(Image.macos())++ async def test_env_variable(self):+ image = Image.macos().env(MY_ENV="macos_test")+ out = await _run(image, "echo $MY_ENV")+ assert "macos_test" in out+++class TestMacOSCopy:+ def setup_method(self):+ skip_if_unsupported(Image.macos())++ async def test_copy_file(self, tmp_path):+ src = tmp_path / "hello.txt"+ src.write_text("hello from host")+ image = Image.macos().copy(str(src), "/tmp/hello.txt")+ out = await _run(image, "cat /tmp/hello.txt")+ assert "hello from host" in out+++class TestMacOSPipInstall:+ def setup_method(self):+ skip_if_unsupported(Image.macos())++ async def test_pip_install(self):+ image = Image.macos().pip_install("httpx")+ out = await _run(image, "python3 -c 'import httpx; print(\"ok\")'")+ assert "ok" in out+++# ═══════════════════════════════════════════════════════════════════════════+# Windows VM+# ═══════════════════════════════════════════════════════════════════════════+++class TestWindowsChocoInstall:+ def setup_method(self):+ skip_if_unsupported(Image.windows())++ async def test_single_package(self):+ image = Image.windows().choco_install("curl")+ out = await _run(image, "curl --version")+ assert "curl" in out.lower()++ async def test_multiple_packages(self):+ image = Image.windows().choco_install("curl", "wget")+ out = await _run(image, "curl --version")+ assert "curl" in out.lower()+++class TestWindowsWingetInstall:+ def setup_method(self):+ skip_if_unsupported(Image.windows())++ async def test_single_package(self):+ image = Image.windows().winget_install("Microsoft.PowerShell")+ out = await _run(image, "pwsh --version")+ assert "powershell" in out.lower()+++class TestWindowsRun:+ def setup_method(self):+ skip_if_unsupported(Image.windows())++ async def test_run_powershell(self):+ image = Image.windows().run("echo setup > C:\\setup.txt")+ out = await _run(image, "type C:\\setup.txt")+ assert "setup" in out+++class TestWindowsEnv:+ def setup_method(self):+ skip_if_unsupported(Image.windows())++ async def test_env_variable(self):+ image = Image.windows().env(MY_VAR="win_test")+ out = await _run(image, "echo %MY_VAR%")+ assert "win_test" in out+++class TestWindowsCopy:+ def setup_method(self):+ skip_if_unsupported(Image.windows())++ async def test_copy_file(self, tmp_path):+ src = tmp_path / "hello.txt"+ src.write_text("hello windows")+ image = Image.windows().copy(str(src), "C:\\hello.txt")+ out = await _run(image, "type C:\\hello.txt")+ assert "hello windows" in out+++class TestWindowsExpose:+ def setup_method(self):+ skip_if_unsupported(Image.windows())++ async def test_expose_port(self):+ image = Image.windows().expose(8080)+ async with Sandbox.ephemeral(image, local=True) as sb:+ r = await sb.shell.run("echo exposed")+ assert r.success+++# ═══════════════════════════════════════════════════════════════════════════+# Android VM+# ═══════════════════════════════════════════════════════════════════════════+++class TestAndroidApkInstall:+ def setup_method(self):+ skip_if_unsupported(Image.android())++ async def test_apk_install(self):+ """Basic APK install — downloads F-Droid APK from URL."""+ image = Image.android().apk_install("https://f-droid.org/F-Droid.apk")+ async with Sandbox.ephemeral(image, local=True) as sb:+ r = await sb.shell.run("pm list packages")+ assert r.success+ assert "org.fdroid" in r.stdout++ async def test_apk_install_from_env(self):+ import os++ apk_path = os.environ.get("ANDROID_TEST_APK")+ if not apk_path:+ pytest.skip("ANDROID_TEST_APK not set")+ image = Image.android().apk_install(apk_path)+ async with Sandbox.ephemeral(image, local=True) as sb:+ r = await sb.shell.run("pm list packages")+ assert r.success+++class TestAndroidPwaInstall:+ def setup_method(self):+ skip_if_unsupported(Image.android())++ async def test_pwa_install(self):+ """PWA install from the android-example-gym-pwa-app manifest."""+ import os+ import tempfile+ import urllib.request++ manifest_url = os.environ.get(+ "ANDROID_TEST_PWA_URL", "https://cuaai--todo-gym-web.modal.run/manifest.json"+ )+ keystore_url = "https://raw.githubusercontent.com/trycua/android-example-gym-pwa-app/main/android.keystore"+ with tempfile.NamedTemporaryFile(suffix=".keystore", delete=False) as f:+ urllib.request.urlretrieve(keystore_url, f.name)+ keystore_path = f.name+ image = Image.android().pwa_install(+ manifest_url,+ keystore=keystore_path,+ keystore_alias="android",+ keystore_password="android",+ )+ async with Sandbox.ephemeral(image, local=True) as sb:+ r = await sb.shell.run("pm list packages")+ assert r.success+++class TestAndroidRun:+ def setup_method(self):+ skip_if_unsupported(Image.android())++ async def test_run_adb_shell(self):+ image = Image.android().run("echo android > /data/local/tmp/test.txt")+ out = await _run(image, "cat /data/local/tmp/test.txt")+ assert "android" in out+++class TestAndroidEnv:+ def setup_method(self):+ skip_if_unsupported(Image.android())++ async def test_env_variable(self):+ image = Image.android().env(MY_VAR="android_test")+ out = await _run(image, "echo $MY_VAR")+ assert "android_test" in outdiff --git a/tests/test_image_builder_cloud.py b/tests/test_image_builder_cloud.pynew file mode 100644index 0000000000..685c4aae05--- /dev/null+++ b/tests/test_image_builder_cloud.py@@ -0,0 +1,101 @@+"""Cloud integration tests for Android image builder methods.++Tests .env(), .apk_install(), and .pwa_install() against the local stack+dev stack (CUA_BASE_URL=http://localhost:8082).++Run with:+ CUA_API_KEY=sk-dev-test-key-local-12345 CUA_BASE_URL=http://localhost:8082 \+ pytest tests/test_image_builder_cloud.py -v -s+"""++from __future__ import annotations++import os++import pytest+from cua import Image, Sandbox++pytestmark = pytest.mark.asyncio+++def _has_cua_api_key() -> bool:+ return bool(os.environ.get("CUA_API_KEY"))+++# ── helpers ──────────────────────────────────────────────────────────────────+++async def _run_cloud(image: Image, cmd: str, timeout: int = 120) -> str:+ """Ephemeral cloud sandbox: run cmd and return stdout."""+ async with Sandbox.ephemeral(image) as sb:+ r = await sb.shell.run(cmd, timeout=timeout)+ assert r.success, f"Command failed (rc={r.returncode}): {r.stderr}"+ return r.stdout.strip()+++# ═══════════════════════════════════════════════════════════════════════════+# Android .env()+# ═══════════════════════════════════════════════════════════════════════════++[email protected](not _has_cua_api_key(), reason="CUA_API_KEY not set")+async def test_android_env_single():+ """Single env var is available inside the Android shell."""+ image = Image.android("14").env(MY_VAR="cloud_test_123")+ out = await _run_cloud(image, "echo $MY_VAR")+ assert "cloud_test_123" in out++[email protected](not _has_cua_api_key(), reason="CUA_API_KEY not set")+async def test_android_env_multiple():+ """Multiple env vars are all available."""+ image = Image.android("14").env(VAR_A="alpha", VAR_B="beta")+ out = await _run_cloud(image, "echo $VAR_A $VAR_B")+ assert "alpha" in out+ assert "beta" in out+++# ═══════════════════════════════════════════════════════════════════════════+# Android .apk_install()+# ═══════════════════════════════════════════════════════════════════════════++[email protected](not _has_cua_api_key(), reason="CUA_API_KEY not set")+async def test_android_apk_install():+ """APK install from URL — F-Droid should be listed in packages."""+ image = Image.android("14").apk_install("https://f-droid.org/F-Droid.apk")+ out = await _run_cloud(image, "pm list packages org.fdroid.fdroid")+ assert "org.fdroid.fdroid" in out+++# ═══════════════════════════════════════════════════════════════════════════+# Android .pwa_install()+# ═══════════════════════════════════════════════════════════════════════════++[email protected](not _has_cua_api_key(), reason="CUA_API_KEY not set")+async def test_android_pwa_install():+ """PWA install from manifest URL — the TWA package should appear."""+ import tempfile+ import urllib.request++ manifest_url = os.environ.get(+ "ANDROID_TEST_PWA_URL",+ "https://cuaai--todo-gym-web.modal.run/manifest.json",+ )+ keystore_url = (+ "https://raw.githubusercontent.com/trycua/android-example-gym-pwa-app/main/android.keystore"+ )+ with tempfile.NamedTemporaryFile(suffix=".keystore", delete=False) as f:+ urllib.request.urlretrieve(keystore_url, f.name)+ keystore_path = f.name++ image = Image.android("14").pwa_install(+ manifest_url,+ keystore=keystore_path,+ keystore_alias="android",+ keystore_password="android",+ )+ out = await _run_cloud(image, "pm list packages")+ # The TWA package name is derived from the manifest — just check pm list works+ assert "package:" in outdiff --git a/tests/test_interfaces.py b/tests/test_interfaces.pynew file mode 100644index 0000000000..cc56fbaa74--- /dev/null+++ b/tests/test_interfaces.py@@ -0,0 +1,944 @@+"""Integration tests for every sandbox interface method across all guest OS types.++Imports exclusively from `cua` (the meta-package). Tests auto-skip via+skip_if_unsupported() when the required local runtime is absent.++Interface coverage:+ sb.shell — Shell.run()+ sb.mouse — click, right_click, double_click, move, scroll, mouse_down, mouse_up, drag+ sb.keyboard — type, keypress, key_down, key_up+ sb.screen — screenshot, screenshot_base64, size+ sb.clipboard — get, set+ sb.tunnel — forward (single, multi, await form)+ sb.terminal — create, send_input, resize, close+ sb.window — get_active_title+ sb.mobile — tap, long_press, double_tap, type_text, swipe, scroll_up/down/left/right,+ fling, gesture, pinch_in, pinch_out, key, home, back, recents, power,+ volume_up, volume_down, enter, backspace, wake, notifications,+ close_notifications++Guest OS coverage:+ Linux container (Image.linux()) — shell, clipboard, tunnel, terminal+ Linux VM (Image.linux(kind="vm")) — + screen, mouse, keyboard, window+ macOS VM (Image.macos()) — shell, screen, mouse, keyboard, clipboard,+ tunnel, terminal, window+ Windows VM (Image.windows()) — shell, screen, mouse, keyboard, clipboard,+ tunnel, terminal, window+ Android VM (Image.android()) — shell, screen, mobile.*++Run with:+ pytest tests/test_interfaces.py -v+ pytest tests/test_interfaces.py -v -k "linux and shell"+"""++from __future__ import annotations++import asyncio+import base64++import httpx+import pytest+from cua import Image, Sandbox, skip_if_unsupported++# ── helpers ──────────────────────────────────────────────────────────────────+++async def _shell(sb, cmd: str, timeout: int = 30) -> str:+ r = await sb.shell.run(cmd, timeout=timeout)+ assert r.success, f"Command failed (rc={r.returncode}): {r.stderr}"+ return r.stdout.strip()+++async def _start_http_server(sb, port: int) -> None:+ """Start a minimal Python HTTP echo server inside the sandbox.++ Uses python3 with POSIX background operator on Linux/macOS.+ macOS VMs ship python3; Linux containers have it in the base image.+ """+ server_code = (+ "import http.server as h, socketserver as ss; "+ f"ss.TCPServer(('0.0.0.0',{port}),"+ "type('H',(h.BaseHTTPRequestHandler,),"+ "{'do_GET':lambda s:(s.send_response(200),s.send_header('Content-Type','text/plain')"+ ",s.end_headers(),s.wfile.write(b'ok'))})"+ ").serve_forever()"+ )+ await sb.shell.run(f'python3 -c "{server_code}" &', timeout=5)+ await asyncio.sleep(1)+++# ═══════════════════════════════════════════════════════════════════════════+# Shell — Linux container+# ═══════════════════════════════════════════════════════════════════════════+++class TestShellLinux:+ _IMAGE = Image.linux()++ def setup_method(self):+ skip_if_unsupported(self._IMAGE)++ async def test_run_success(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ r = await sb.shell.run("echo hello")+ assert r.success+ assert r.returncode == 0+ assert "hello" in r.stdout++ async def test_run_failure_returncode(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ r = await sb.shell.run("false")+ assert not r.success+ assert r.returncode != 0++ async def test_run_stderr(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ r = await sb.shell.run("ls /no_such_dir_xyz 2>&1; true")+ # At minimum the command ran+ assert r.returncode is not None++ async def test_run_pipeline(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ r = await sb.shell.run("echo hello | tr a-z A-Z")+ assert r.success+ assert "HELLO" in r.stdout++ async def test_run_multiline_output(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ r = await sb.shell.run("printf 'a\\nb\\nc\\n'")+ assert r.success+ assert r.stdout.strip().splitlines() == ["a", "b", "c"]++ async def test_run_sequential_state(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ r1 = await sb.shell.run("echo persistent > /tmp/st.txt")+ assert r1.success+ r2 = await sb.shell.run("cat /tmp/st.txt")+ assert r2.success+ assert "persistent" in r2.stdout++ async def test_run_timeout(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ with pytest.raises(BaseException): # noqa: B017+ await sb.shell.run("sleep 60", timeout=2)++ async def test_commandresult_fields(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ r = await sb.shell.run("echo out; echo err >&2; exit 0")+ assert isinstance(r.stdout, str)+ assert isinstance(r.stderr, str)+ assert isinstance(r.returncode, int)+ assert r.success is True+++class TestShellMacOS:+ _IMAGE = Image.macos()++ def setup_method(self):+ skip_if_unsupported(self._IMAGE)++ async def test_run_success(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ r = await sb.shell.run("echo hello macos")+ assert r.success+ assert "hello" in r.stdout++ async def test_run_pipeline(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ r = await sb.shell.run("echo hello | tr a-z A-Z")+ assert r.success+ assert "HELLO" in r.stdout+++class TestShellWindows:+ _IMAGE = Image.windows()++ def setup_method(self):+ skip_if_unsupported(self._IMAGE)++ async def test_run_success(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ r = await sb.shell.run("echo hello windows")+ assert r.success+ assert "hello" in r.stdout++ async def test_run_failure(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ r = await sb.shell.run("exit 1")+ assert not r.success+++class TestShellAndroid:+ _IMAGE = Image.android()++ def setup_method(self):+ skip_if_unsupported(self._IMAGE)++ async def test_run_adb_shell(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ r = await sb.shell.run("echo hello android")+ assert r.success+ assert "hello" in r.stdout++ async def test_run_getprop(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ r = await sb.shell.run("getprop ro.build.version.release")+ assert r.success+ assert r.stdout.strip() # non-empty version string+++# ═══════════════════════════════════════════════════════════════════════════+# Clipboard — Linux container, macOS, Windows+# ═══════════════════════════════════════════════════════════════════════════+++class TestClipboardLinux:+ _IMAGE = Image.linux()++ def setup_method(self):+ skip_if_unsupported(self._IMAGE)++ async def test_set_and_get(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await sb.clipboard.set("hello clipboard")+ text = await sb.clipboard.get()+ assert text == "hello clipboard"++ async def test_overwrite(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await sb.clipboard.set("first")+ await sb.clipboard.set("second")+ assert await sb.clipboard.get() == "second"++ async def test_unicode(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ payload = "héllo wörld 🌸"+ await sb.clipboard.set(payload)+ assert await sb.clipboard.get() == payload++ async def test_multiline(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ payload = "line1\nline2\nline3"+ await sb.clipboard.set(payload)+ assert await sb.clipboard.get() == payload++ async def test_empty_string(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await sb.clipboard.set("non-empty")+ await sb.clipboard.set("")+ assert await sb.clipboard.get() == ""+++class TestClipboardMacOS:+ _IMAGE = Image.macos()++ def setup_method(self):+ skip_if_unsupported(self._IMAGE)++ async def test_set_and_get(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await sb.clipboard.set("macos clipboard")+ assert await sb.clipboard.get() == "macos clipboard"++ async def test_unicode(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ payload = "café ☕"+ await sb.clipboard.set(payload)+ assert await sb.clipboard.get() == payload+++class TestClipboardWindows:+ _IMAGE = Image.windows()++ def setup_method(self):+ skip_if_unsupported(self._IMAGE)++ async def test_set_and_get(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await sb.clipboard.set("windows clipboard")+ assert await sb.clipboard.get() == "windows clipboard"+++# ═══════════════════════════════════════════════════════════════════════════+# Screen — Linux VM, macOS, Windows, Android+# ═══════════════════════════════════════════════════════════════════════════++_LINUX_VM = Image.linux(kind="vm")+++class TestScreenLinuxVM:+ def setup_method(self):+ skip_if_unsupported(_LINUX_VM)++ async def test_screenshot_returns_bytes(self):+ async with Sandbox.ephemeral(_LINUX_VM, local=True) as sb:+ data = await sb.screen.screenshot()+ assert isinstance(data, bytes) and len(data) > 0++ async def test_screenshot_png_magic(self):+ async with Sandbox.ephemeral(_LINUX_VM, local=True) as sb:+ data = await sb.screen.screenshot(format="png")+ assert data[:8] == b"\x89PNG\r\n\x1a\n"++ async def test_screenshot_jpeg(self):+ async with Sandbox.ephemeral(_LINUX_VM, local=True) as sb:+ data = await sb.screen.screenshot(format="jpeg", quality=80)+ assert data[:2] == b"\xff\xd8"++ async def test_screenshot_base64(self):+ async with Sandbox.ephemeral(_LINUX_VM, local=True) as sb:+ b64 = await sb.screen.screenshot_base64()+ assert isinstance(b64, str)+ assert len(base64.b64decode(b64)) > 0++ async def test_size(self):+ async with Sandbox.ephemeral(_LINUX_VM, local=True) as sb:+ w, h = await sb.screen.size()+ assert isinstance(w, int) and w >= 640+ assert isinstance(h, int) and h >= 480+++class TestScreenMacOS:+ _IMAGE = Image.macos()++ def setup_method(self):+ skip_if_unsupported(self._IMAGE)++ async def test_screenshot_returns_bytes(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ data = await sb.screen.screenshot()+ assert isinstance(data, bytes) and len(data) > 0++ async def test_screenshot_png_magic(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ data = await sb.screen.screenshot(format="png")+ assert data[:8] == b"\x89PNG\r\n\x1a\n"++ async def test_screenshot_base64(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ b64 = await sb.screen.screenshot_base64()+ decoded = base64.b64decode(b64)+ assert len(decoded) > 0++ async def test_size(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ w, h = await sb.screen.size()+ assert w >= 640 and h >= 480+++class TestScreenWindows:+ _IMAGE = Image.windows()++ def setup_method(self):+ skip_if_unsupported(self._IMAGE)++ async def test_screenshot_returns_bytes(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ data = await sb.screen.screenshot()+ assert isinstance(data, bytes) and len(data) > 0++ async def test_size(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ w, h = await sb.screen.size()+ assert w > 0 and h > 0+++class TestScreenAndroid:+ _IMAGE = Image.android()++ def setup_method(self):+ skip_if_unsupported(self._IMAGE)++ async def test_screenshot_returns_bytes(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ data = await sb.screen.screenshot()+ assert isinstance(data, bytes) and len(data) > 0++ async def test_size(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ w, h = await sb.screen.size()+ assert w > 0 and h > 0+++# ═══════════════════════════════════════════════════════════════════════════+# Mouse — Linux VM, macOS, Windows+# ═══════════════════════════════════════════════════════════════════════════+++class TestMouseLinuxVM:+ def setup_method(self):+ skip_if_unsupported(_LINUX_VM)++ async def test_click(self):+ async with Sandbox.ephemeral(_LINUX_VM, local=True) as sb:+ w, h = await sb.screen.size()+ await sb.mouse.click(w // 2, h // 2) # must not raise++ async def test_right_click(self):+ async with Sandbox.ephemeral(_LINUX_VM, local=True) as sb:+ w, h = await sb.screen.size()+ await sb.mouse.right_click(w // 2, h // 2)++ async def test_double_click(self):+ async with Sandbox.ephemeral(_LINUX_VM, local=True) as sb:+ w, h = await sb.screen.size()+ await sb.mouse.double_click(w // 2, h // 2)++ async def test_move(self):+ async with Sandbox.ephemeral(_LINUX_VM, local=True) as sb:+ await sb.mouse.move(100, 100)+ await sb.mouse.move(200, 200)++ async def test_scroll(self):+ async with Sandbox.ephemeral(_LINUX_VM, local=True) as sb:+ w, h = await sb.screen.size()+ await sb.mouse.scroll(w // 2, h // 2, scroll_y=3)++ async def test_mouse_down_and_up(self):+ async with Sandbox.ephemeral(_LINUX_VM, local=True) as sb:+ w, h = await sb.screen.size()+ await sb.mouse.mouse_down(w // 2, h // 2)+ await sb.mouse.mouse_up(w // 2, h // 2)++ async def test_drag(self):+ async with Sandbox.ephemeral(_LINUX_VM, local=True) as sb:+ w, h = await sb.screen.size()+ await sb.mouse.drag(100, h // 2, 300, h // 2)+++class TestMouseMacOS:+ _IMAGE = Image.macos()++ def setup_method(self):+ skip_if_unsupported(self._IMAGE)++ async def test_click(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ w, h = await sb.screen.size()+ await sb.mouse.click(w // 2, h // 2)++ async def test_right_click(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ w, h = await sb.screen.size()+ await sb.mouse.right_click(w // 2, h // 2)++ async def test_double_click(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ w, h = await sb.screen.size()+ await sb.mouse.double_click(w // 2, h // 2)++ async def test_move(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await sb.mouse.move(100, 100)++ async def test_scroll(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ w, h = await sb.screen.size()+ await sb.mouse.scroll(w // 2, h // 2, scroll_y=3)++ async def test_mouse_down_and_up(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ w, h = await sb.screen.size()+ await sb.mouse.mouse_down(w // 2, h // 2)+ await sb.mouse.mouse_up(w // 2, h // 2)++ async def test_drag(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ w, h = await sb.screen.size()+ await sb.mouse.drag(100, h // 2, 300, h // 2)+++class TestMouseWindows:+ _IMAGE = Image.windows()++ def setup_method(self):+ skip_if_unsupported(self._IMAGE)++ async def test_click(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ w, h = await sb.screen.size()+ await sb.mouse.click(w // 2, h // 2)++ async def test_right_click(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ w, h = await sb.screen.size()+ await sb.mouse.right_click(w // 2, h // 2)++ async def test_double_click(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ w, h = await sb.screen.size()+ await sb.mouse.double_click(w // 2, h // 2)++ async def test_move(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await sb.mouse.move(100, 100)++ async def test_scroll(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ w, h = await sb.screen.size()+ await sb.mouse.scroll(w // 2, h // 2, scroll_y=3)++ async def test_mouse_down_and_up(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ w, h = await sb.screen.size()+ await sb.mouse.mouse_down(w // 2, h // 2)+ await sb.mouse.mouse_up(w // 2, h // 2)++ async def test_drag(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ w, h = await sb.screen.size()+ await sb.mouse.drag(100, h // 2, 300, h // 2)+++# ═══════════════════════════════════════════════════════════════════════════+# Keyboard — Linux VM, macOS, Windows+# ═══════════════════════════════════════════════════════════════════════════+++class TestKeyboardLinuxVM:+ def setup_method(self):+ skip_if_unsupported(_LINUX_VM)++ async def test_type(self):+ async with Sandbox.ephemeral(_LINUX_VM, local=True) as sb:+ await sb.keyboard.type("hello") # must not raise++ async def test_keypress_single(self):+ async with Sandbox.ephemeral(_LINUX_VM, local=True) as sb:+ await sb.keyboard.keypress("enter")++ async def test_keypress_combination(self):+ async with Sandbox.ephemeral(_LINUX_VM, local=True) as sb:+ await sb.keyboard.keypress(["ctrl", "a"])++ async def test_keypress_string_list(self):+ async with Sandbox.ephemeral(_LINUX_VM, local=True) as sb:+ await sb.keyboard.keypress(["shift", "tab"])++ async def test_key_down_and_up(self):+ async with Sandbox.ephemeral(_LINUX_VM, local=True) as sb:+ await sb.keyboard.key_down("shift")+ await sb.keyboard.key_up("shift")++ async def test_type_unicode(self):+ async with Sandbox.ephemeral(_LINUX_VM, local=True) as sb:+ await sb.keyboard.type("héllo")+++class TestKeyboardMacOS:+ _IMAGE = Image.macos()++ def setup_method(self):+ skip_if_unsupported(self._IMAGE)++ async def test_type(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await sb.keyboard.type("hello macos")++ async def test_keypress_single(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await sb.keyboard.keypress("enter")++ async def test_keypress_combination(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await sb.keyboard.keypress(["cmd", "a"])++ async def test_key_down_and_up(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await sb.keyboard.key_down("shift")+ await sb.keyboard.key_up("shift")+++class TestKeyboardWindows:+ _IMAGE = Image.windows()++ def setup_method(self):+ skip_if_unsupported(self._IMAGE)++ async def test_type(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await sb.keyboard.type("hello windows")++ async def test_keypress_single(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await sb.keyboard.keypress("enter")++ async def test_keypress_combination(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await sb.keyboard.keypress(["ctrl", "a"])++ async def test_key_down_and_up(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await sb.keyboard.key_down("shift")+ await sb.keyboard.key_up("shift")+++# ═══════════════════════════════════════════════════════════════════════════+# Tunnel — Linux container, macOS, Windows+# ═══════════════════════════════════════════════════════════════════════════+++class TestTunnelLinux:+ _IMAGE = Image.linux()++ def setup_method(self):+ skip_if_unsupported(self._IMAGE)++ async def test_forward_single_context_manager(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await _start_http_server(sb, 8888)+ async with sb.tunnel.forward(8888) as t:+ assert t.host+ assert t.port > 0+ assert t.sandbox_port == 8888+ assert t.url.startswith("http://")+ async with httpx.AsyncClient() as client:+ r = await client.get(t.url, timeout=5)+ assert r.status_code == 200++ async def test_tunnel_info_repr(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await _start_http_server(sb, 8889)+ async with sb.tunnel.forward(8889) as t:+ assert "8889" in repr(t)++ async def test_forward_multiple_ports(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await _start_http_server(sb, 8890)+ await _start_http_server(sb, 8891)+ async with sb.tunnel.forward(8890, 8891) as tunnels:+ assert 8890 in tunnels+ assert 8891 in tunnels+ async with httpx.AsyncClient() as client:+ for t in tunnels.values():+ r = await client.get(t.url, timeout=5)+ assert r.status_code == 200++ async def test_forward_await_form(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await _start_http_server(sb, 8892)+ t = await sb.tunnel.forward(8892)+ try:+ async with httpx.AsyncClient() as client:+ r = await client.get(t.url, timeout=5)+ assert r.status_code == 200+ finally:+ await t.close()++ async def test_forward_no_ports_raises(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ with pytest.raises(ValueError):+ sb.tunnel.forward()+++class TestTunnelMacOS:+ _IMAGE = Image.macos()++ def setup_method(self):+ skip_if_unsupported(self._IMAGE)++ async def test_forward_single(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await _start_http_server(sb, 8888)+ async with sb.tunnel.forward(8888) as t:+ assert t.sandbox_port == 8888+ async with httpx.AsyncClient() as client:+ r = await client.get(t.url, timeout=5)+ assert r.status_code == 200+++class TestTunnelWindows:+ _IMAGE = Image.windows()++ def setup_method(self):+ skip_if_unsupported(self._IMAGE)++ async def test_forward_single(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await _start_http_server(sb, 8888)+ async with sb.tunnel.forward(8888) as t:+ async with httpx.AsyncClient() as client:+ r = await client.get(t.url, timeout=5)+ assert r.status_code == 200+++# ═══════════════════════════════════════════════════════════════════════════+# Terminal (PTY) — Linux container, macOS, Windows+# ═══════════════════════════════════════════════════════════════════════════+++class TestTerminalLinux:+ _IMAGE = Image.linux()++ def setup_method(self):+ skip_if_unsupported(self._IMAGE)++ async def test_create_returns_pid(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ info = await sb.terminal.create()+ assert "pid" in info and isinstance(info["pid"], int)+ await sb.terminal.close(info["pid"])++ async def test_create_custom_shell(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ info = await sb.terminal.create(shell="sh")+ assert info["pid"] > 0+ await sb.terminal.close(info["pid"])++ async def test_create_custom_dimensions(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ info = await sb.terminal.create(cols=120, rows=40)+ assert info.get("cols") == 120+ assert info.get("rows") == 40+ await sb.terminal.close(info["pid"])++ async def test_send_input(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ info = await sb.terminal.create()+ await sb.terminal.send_input(info["pid"], "echo hello\n")+ await asyncio.sleep(0.3)+ await sb.terminal.close(info["pid"])++ async def test_resize(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ info = await sb.terminal.create(cols=80, rows=24)+ await sb.terminal.resize(info["pid"], cols=160, rows=48)+ await sb.terminal.close(info["pid"])++ async def test_close_returns_exit_code_or_none(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ info = await sb.terminal.create()+ await sb.terminal.send_input(info["pid"], "exit 0\n")+ await asyncio.sleep(0.3)+ result = await sb.terminal.close(info["pid"])+ assert result is None or isinstance(result, int)++ async def test_multiple_sessions_independent(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ a = await sb.terminal.create()+ b = await sb.terminal.create()+ assert a["pid"] != b["pid"]+ await sb.terminal.close(a["pid"])+ await sb.terminal.close(b["pid"])+++class TestTerminalMacOS:+ _IMAGE = Image.macos()++ def setup_method(self):+ skip_if_unsupported(self._IMAGE)++ async def test_create_and_close(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ info = await sb.terminal.create()+ assert info["pid"] > 0+ await sb.terminal.send_input(info["pid"], "echo hi\n")+ await asyncio.sleep(0.3)+ await sb.terminal.close(info["pid"])++ async def test_resize(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ info = await sb.terminal.create(cols=80, rows=24)+ await sb.terminal.resize(info["pid"], 120, 40)+ await sb.terminal.close(info["pid"])+++class TestTerminalWindows:+ _IMAGE = Image.windows()++ def setup_method(self):+ skip_if_unsupported(self._IMAGE)++ async def test_create_and_close(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ info = await sb.terminal.create(shell="cmd.exe")+ assert info["pid"] > 0+ await sb.terminal.close(info["pid"])++ async def test_send_input(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ info = await sb.terminal.create(shell="cmd.exe")+ await sb.terminal.send_input(info["pid"], "echo hello\r\n")+ await asyncio.sleep(0.5)+ await sb.terminal.close(info["pid"])+++# ═══════════════════════════════════════════════════════════════════════════+# Window — Linux VM, macOS, Windows+# ═══════════════════════════════════════════════════════════════════════════+++class TestWindowLinuxVM:+ def setup_method(self):+ skip_if_unsupported(_LINUX_VM)++ async def test_get_active_title_returns_string(self):+ async with Sandbox.ephemeral(_LINUX_VM, local=True) as sb:+ title = await sb.window.get_active_title()+ assert isinstance(title, str)+++class TestWindowMacOS:+ _IMAGE = Image.macos()++ def setup_method(self):+ skip_if_unsupported(self._IMAGE)++ async def test_get_active_title_returns_string(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ title = await sb.window.get_active_title()+ assert isinstance(title, str)+++class TestWindowWindows:+ _IMAGE = Image.windows()++ def setup_method(self):+ skip_if_unsupported(self._IMAGE)++ async def test_get_active_title_returns_string(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ title = await sb.window.get_active_title()+ assert isinstance(title, str)+++# ═══════════════════════════════════════════════════════════════════════════+# Mobile — Android only+# ═══════════════════════════════════════════════════════════════════════════+++class TestMobileAndroid:+ _IMAGE = Image.android()++ def setup_method(self):+ skip_if_unsupported(self._IMAGE)++ async def _sb(self):+ return Sandbox.ephemeral(self._IMAGE, local=True)++ # Touch+ async def test_tap(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ w, h = await sb.screen.size()+ await sb.mobile.tap(w // 2, h // 2)++ async def test_long_press(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ w, h = await sb.screen.size()+ await sb.mobile.long_press(w // 2, h // 2, duration_ms=500)++ async def test_double_tap(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ w, h = await sb.screen.size()+ await sb.mobile.double_tap(w // 2, h // 2)++ async def test_type_text(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await sb.mobile.type_text("hello")++ # Gestures+ async def test_swipe(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ w, h = await sb.screen.size()+ await sb.mobile.swipe(w // 2, h * 3 // 4, w // 2, h // 4)++ async def test_scroll_up(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ w, h = await sb.screen.size()+ await sb.mobile.scroll_up(w // 2, h // 2)++ async def test_scroll_down(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ w, h = await sb.screen.size()+ await sb.mobile.scroll_down(w // 2, h // 2)++ async def test_scroll_left(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ w, h = await sb.screen.size()+ await sb.mobile.scroll_left(w // 2, h // 2)++ async def test_scroll_right(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ w, h = await sb.screen.size()+ await sb.mobile.scroll_right(w // 2, h // 2)++ async def test_fling(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ w, h = await sb.screen.size()+ await sb.mobile.fling(w // 2, h * 3 // 4, w // 2, h // 4)++ async def test_pinch_in(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ w, h = await sb.screen.size()+ await sb.mobile.pinch_in(w // 2, h // 2, spread=200)++ async def test_pinch_out(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ w, h = await sb.screen.size()+ await sb.mobile.pinch_out(w // 2, h // 2, spread=200)++ async def test_gesture_two_finger(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ w, h = await sb.screen.size()+ cx, cy = w // 2, h // 2+ await sb.mobile.gesture(+ (cx - 20, cy),+ (cx - 200, cy),+ (cx + 20, cy),+ (cx + 200, cy),+ )++ async def test_gesture_invalid_raises(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ with pytest.raises(ValueError):+ await sb.mobile.gesture((100, 100), (200, 200), (300, 300))++ # Hardware keys+ async def test_key_home(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await sb.mobile.home()++ async def test_key_back(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await sb.mobile.back()++ async def test_key_recents(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await sb.mobile.recents()++ async def test_key_volume_up(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await sb.mobile.volume_up()++ async def test_key_volume_down(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await sb.mobile.volume_down()++ async def test_key_enter(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await sb.mobile.enter()++ async def test_key_backspace(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await sb.mobile.backspace()++ async def test_key_power(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await sb.mobile.power()++ async def test_key_arbitrary(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await sb.mobile.key(3) # HOME keycode++ # System+ async def test_wake(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await sb.mobile.wake()++ async def test_notifications(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await sb.mobile.notifications()++ async def test_close_notifications(self):+ async with Sandbox.ephemeral(self._IMAGE, local=True) as sb:+ await sb.mobile.close_notifications()diff --git a/uv.lock b/uv.lockindex 3de7c72c1b..e4d3a00e20 100644--- a/uv.lock+++ b/uv.lock@@ -1057,7 +1057,7 @@ wheels = [[[package]]name = "cua-agent"-version = "0.7.38"+version = "0.7.39"source = { editable = "libs/python/agent" }dependencies = [{ name = "aiohttp" },@@ -1067,6 +1067,7 @@ dependencies = [{ name = "cua-core" },{ name = "httpx" },{ name = "litellm" },+ { name = "pillow" },{ name = "pydantic" },{ name = "python-dotenv" },{ name = "rich" },@@ -1184,6 +1185,7 @@ requires-dist = [{ name = "litellm", specifier = "==1.80.0" },{ name = "mlx-vlm", marker = "sys_platform == 'darwin' and extra == 'all'", specifier = ">=0.1.27" },{ name = "mlx-vlm", marker = "sys_platform == 'darwin' and extra == 'uitars-mlx'", specifier = ">=0.1.27" },+ { name = "pillow", specifier = ">=10.0.0" },{ name = "pillow", marker = "extra == 'all'", specifier = ">=10.0.0" },{ name = "pillow", marker = "extra == 'cloud'", specifier = ">=10.0.0" },{ name = "pillow", marker = "extra == 'qwen'", specifier = ">=10.0.0" },@@ -1387,7 +1389,7 @@ provides-extras = ["macos", "linux", "windows", "vnc"][[package]]name = "cua-core"-version = "0.1.18"+version = "0.1.19"source = { editable = "libs/python/core" }dependencies = [{ name = "posthog" },