Skip to content

armgit / cua

Public Imported from GitHub
0

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

SDK integration tests, auto-generated docs, and snapshot support (#1242)

ddupontd7a2452fdf31
diff --git a/demo/1_fleet_throughput.py b/demo/1_fleet_throughput.py
index 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 = 0
latencies: 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.json
index 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.mdx
new file mode 100644
index 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.mdx
index 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:&lt;random&gt;/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 &#123;"pid": int, "cols": int, "rows": int&#125;.
-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 &gt;= 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.swift
index 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: UInt16
private let controller: LumeController
private 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: - Initialization
diff --git a/libs/python/cua-sandbox/cua_sandbox/__init__.py b/libs/python/cua-sandbox/cua_sandbox/__init__.py
index 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, whoami
from cua_sandbox._config import configure
from cua_sandbox.image import Image
from 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, sandbox
from 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.py
index 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_url
def _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.py
index 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 dict
into shell commands and executes them sequentially.
@@ -6,7 +6,10 @@ into shell commands and executes them sequentially.
from __future__ import annotations
+import base64
+import json
import logging
+import os
from typing import Any
import 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 /cmd
resp = 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-wide
return 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 result
async 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.py
index 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.py
index 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 result
async 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.py
index 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.py
index 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-android
Path.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.request
import 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 PATH
found = 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.py
index 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 annotations
from abc import ABC, abstractmethod
-from dataclasses import dataclass
+from dataclasses import dataclass, field
from typing import TYPE_CHECKING, Optional
from 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)
+
+
@dataclass
class 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.py
new file mode 100644
index 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.py
index 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 timeout
extra_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 info
async 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 ports
result = 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_port
result2 = 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.py
index 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 exists
async 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.py
index 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 = 95
diff --git a/libs/python/cua-sandbox/cua_sandbox/transport/adb.py b/libs/python/cua-sandbox/cua_sandbox/transport/adb.py
index 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.py
index 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 Path
assert 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)
+
@staticmethod
def _resolve_endpoint(vm_info: dict) -> str:
"""Build the computer-server HTTP URL from VM info."""
- # Prefer explicit endpoints array (Incus VMs)
+ # Prefer explicit endpoints array
for 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.py
index 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 annotations
import asyncio
import functools
+import platform
import shutil
import subprocess
from 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.py
index 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__.py
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/libs/python/cua-sandbox/tests/interfaces/__init__.py b/libs/python/cua-sandbox/tests/interfaces/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/libs/python/cua-sandbox/tests/test_android_multitouch.py b/libs/python/cua-sandbox/tests/test_android_multitouch.py
index 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 pytest
import pytest_asyncio
from cua_sandbox.image import Image
from cua_sandbox.runtime.android_emulator import AndroidEmulatorRuntime
+from cua_sandbox.runtime.compat import skip_if_unsupported
from cua_sandbox.sandbox import Sandbox
# ── Config ─────────────────────────────────────────────────────────────────
@@ -141,7 +142,13 @@ async def local_android_sb():
Boot a single AndroidEmulatorRuntime via Sandbox.ephemeral(), install the TouchTest
APK, 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:
yield
return
- 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.py
index 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.py
new file mode 100644
index 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.lock
index 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__.py
index 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.toml
index 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.py
new file mode 100644
index 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("<", "&lt;")
+ .replace(">", "&gt;")
+ .replace("{", "&#123;")
+ .replace("}", "&#125;")
+ )
+ 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.ini
index 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/agent
markers =
asyncio: asyncio mark
\ No newline at end of file
diff --git a/tests/test_image_builder.py b/tests/test_image_builder.py
new file mode 100644
index 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 out
diff --git a/tests/test_image_builder_cloud.py b/tests/test_image_builder_cloud.py
new file mode 100644
index 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 out
diff --git a/tests/test_interfaces.py b/tests/test_interfaces.py
new file mode 100644
index 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.lock
index 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" },