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.

feat(sandbox-sdk): Cua Sandbox SDK — unified API for Linux, macOS, Windows, Android (#1218)

ddupont7d1fa31fb6ed
diff --git a/.github/workflows/cd-py-sandbox.yml b/.github/workflows/cd-py-sandbox.yml
new file mode 100644
index 0000000000..98ad1fd527
--- /dev/null
+++ b/.github/workflows/cd-py-sandbox.yml
@@ -0,0 +1,69 @@
+name: "CD: cua-sandbox (PyPI)"
+
+on:
+ push:
+ tags:
+ - "sandbox-v*"
+ workflow_dispatch:
+ inputs:
+ version:
+ description: "Version to publish (without v prefix)"
+ required: true
+ default: "0.1.0"
+ workflow_call:
+ inputs:
+ version:
+ description: "Version to publish"
+ required: true
+ type: string
+
+permissions:
+ contents: write
+
+jobs:
+ prepare:
+ runs-on: macos-latest
+ outputs:
+ version: ${{ steps.get-version.outputs.version }}
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Determine version
+ id: get-version
+ run: |
+ if [ -n "${{ inputs.version }}" ]; then
+ VERSION=${{ inputs.version }}
+ elif [ "${{ github.event_name }}" == "push" ]; then
+ if [[ "${{ github.ref }}" =~ ^refs/tags/sandbox-v([0-9]+\.[0-9]+\.[0-9]+) ]]; then
+ VERSION=${BASH_REMATCH[1]}
+ else
+ echo "Invalid tag format for sandbox"
+ exit 1
+ fi
+ elif [ -n "${{ github.event.inputs.version }}" ]; then
+ VERSION=${{ github.event.inputs.version }}
+ else
+ echo "ERROR: No version found!"
+ exit 1
+ fi
+ echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+ publish:
+ needs: prepare
+ uses: ./.github/workflows/py-reusable-publish.yml
+ with:
+ package_name: "sandbox"
+ package_dir: "libs/python/cua-sandbox"
+ version: ${{ needs.prepare.outputs.version }}
+ base_package_name: "cua-sandbox"
+ secrets:
+ PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
+
+ create-release:
+ needs: [prepare, publish]
+ uses: ./.github/workflows/release-github-reusable.yml
+ with:
+ tag_name: "sandbox-v${{ needs.prepare.outputs.version }}"
+ release_name: "cua-sandbox v${{ needs.prepare.outputs.version }}"
+ module_path: "libs/python/cua-sandbox"
+ body: ""
diff --git a/.github/workflows/ci-cold-start-benchmark.yml b/.github/workflows/ci-cold-start-benchmark.yml
new file mode 100644
index 0000000000..6a5a26eb23
--- /dev/null
+++ b/.github/workflows/ci-cold-start-benchmark.yml
@@ -0,0 +1,41 @@
+name: "CI: Cold Start Benchmark"
+
+on:
+ workflow_dispatch:
+
+jobs:
+ benchmark:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v4
+
+ - name: Set up uv and Python
+ uses: astral-sh/setup-uv@v4
+ with:
+ python-version: "3.12"
+
+ - name: Install dependencies
+ run: |
+ rm -rf .venv
+ uv venv --python 3.12
+ uv pip install -e libs/python/core -e libs/python/computer -e libs/python/cua-sandbox
+
+ - name: Run cold start benchmark
+ id: benchmark
+ timeout-minutes: 10
+ run: uv run python tests/cold_start_benchmark.py
+ env:
+ CUA_API_KEY: ${{ secrets.CUA_API_KEY }}
+ SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }}
+
+ - name: Send results to Slack
+ if: always()
+ uses: rtCamp/action-slack-notify@v2
+ env:
+ SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }}
+ SLACK_CHANNEL: ${{ vars.SLACK_CHANNEL }}
+ SLACK_TITLE: "Cloud Sandbox Cold Start Benchmark"
+ SLACK_COLOR: ${{ env.SLACK_COLOR }}
+ SLACK_MESSAGE: |
+ ${{ env.SLACK_MESSAGE }}
diff --git a/.github/workflows/release-bump-version.yml b/.github/workflows/release-bump-version.yml
index 5eab5ed8a2..de4769c705 100644
--- a/.github/workflows/release-bump-version.yml
+++ b/.github/workflows/release-bump-version.yml
@@ -17,6 +17,7 @@ on:
- pypi/computer-server
- pypi/core
- pypi/mcp-server
+ - pypi/sandbox
- pypi/som
- npm/cli
- npm/computer
@@ -87,6 +88,10 @@ jobs:
echo "directory=libs/python/mcp-server" >> $GITHUB_OUTPUT
echo "type=python" >> $GITHUB_OUTPUT
;;
+ "pypi/sandbox")
+ echo "directory=libs/python/cua-sandbox" >> $GITHUB_OUTPUT
+ echo "type=python" >> $GITHUB_OUTPUT
+ ;;
"pypi/som")
echo "directory=libs/python/som" >> $GITHUB_OUTPUT
echo "type=python" >> $GITHUB_OUTPUT
@@ -289,6 +294,15 @@ jobs:
echo "MCP-server version: $VERSION"
echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+ - name: Capture bumped sandbox version
+ if: ${{ inputs.service == 'pypi/sandbox' }}
+ id: sandbox_version
+ run: |
+ cd libs/python/cua-sandbox
+ VERSION=$(python -c "import tomllib; from pathlib import Path; data = tomllib.loads(Path('pyproject.toml').read_text()); print(data['project']['version'])")
+ echo "Sandbox version: $VERSION"
+ echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
- name: Capture bumped som version
if: ${{ inputs.service == 'pypi/som' }}
id: som_version
diff --git a/README.md b/README.md
index 55da68996c..fecad86c1a 100644
--- a/README.md
+++ b/README.md
@@ -69,6 +69,34 @@
---
+## Cua - Agent-Ready Sandboxes for Any OS
+
+Build agents that see screens, click buttons, and complete tasks autonomously. One API for any VM or container image — cloud or local.
+
+<!-- <img src="img/cua-architecture.png" alt="Cua Architecture" width="100%"> -->
+
+```python
+# Requires Python 3.12 or 3.13
+from cua_sandbox import Sandbox, Image
+
+# Same API regardless of OS or runtime
+async with Sandbox.ephemeral(Image.linux()) as sb: # or .macos() .windows() .android()
+ result = await sb.shell.run("echo hello")
+ screenshot = await sb.screenshot()
+ await sb.mouse.click(100, 200)
+ await sb.keyboard.type("Hello from Cua!")
+ await sb.mobile.gesture((100, 500), (100, 200)) # multi-touch gestures
+```
+
+| | Linux container | Linux VM | macOS | Windows | Android | BYOI (.qcow2, .iso) |
+| ------------------ | --------------- | -------- | ----- | ------- | ------- | ------------------- |
+| **Cloud (cua.ai)** | ✅ | ✅ | ✅ | ✅ | ✅ | 🔜 soon |
+| **Local (QEMU)** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+
+**[Get Started](https://cua.ai/docs/cua/guide/get-started/set-up-sandbox)** | **[Examples](https://cua.ai/docs/cua/examples)** | **[API Reference](https://cua.ai/docs/cua/reference/agent-sdk)**
+
+---
+
## CuaBot - Co-op computer-use for any agent
<div align="center">
@@ -103,26 +131,6 @@ Built-in support for `agent-browser` and `agent-device` (iOS, Android) out of th
</div>
-## Cua - Agentic UI Automation & Code Execution
-
-Build agents that see screens, click buttons, and complete tasks autonomously. Run isolated code execution environments for AI coding assistants like Claude Code, Codex CLI, or OpenCode.
-
-<!-- <img src="img/cua-architecture.png" alt="Cua Architecture" width="100%"> -->
-
-```python
-# Requires Python 3.12 or 3.13
-from computer import Computer
-from agent import ComputerAgent
-
-computer = Computer(os_type="linux", provider_type="cloud")
-agent = ComputerAgent(model="anthropic/claude-sonnet-4-5-20250929", computer=computer)
-
-async for result in agent.run([{"role": "user", "content": "Open Firefox and search for Cua"}]):
- print(result)
-```
-
-**[Get Started](https://cua.ai/docs/cua/guide/get-started/set-up-sandbox)** | **[Examples](https://cua.ai/docs/cua/examples)** | **[API Reference](https://cua.ai/docs/cua/reference/agent-sdk)**
-
---
## Cua-Bench - Benchmarks & RL Environments
@@ -168,8 +176,8 @@ lume run macos-sequoia-vanilla:latest
| --------------------------------------------------------------------------- | ---------------------------------------------------------- |
| [cuabot](https://docs.trycua.com/cuabot/guide/getting-started/introduction) | Multi-agent computer-use sandbox CLI |
| [cua-agent](https://cua.ai/docs/cua/reference/agent-sdk) | AI agent framework for computer-use tasks |
-| [cua-computer](https://cua.ai/docs/cua/reference/computer-sdk) | SDK for controlling desktop environments |
-| [cua-computer-server](https://cua.ai/docs/cua/reference/computer-sdk) | Driver for UI interactions and code execution in sandboxes |
+| [cua-sandbox](https://cua.ai/docs/cua/reference/sandbox-sdk) | SDK for creating and controlling sandboxes |
+| [cua-computer-server](https://cua.ai/docs/cua/reference/sandbox-sdk) | Driver for UI interactions and code execution in sandboxes |
| [cua-bench](https://cua.ai/docs/cuabench) | Benchmarks and RL environments for computer-use |
| [lume](https://cua.ai/docs/lume) | macOS/Linux VM management on Apple Silicon |
| [lumier](https://cua.ai/docs/lume/guide/advanced/lumier) | Docker-compatible interface for Lume VMs |
diff --git a/demo/1_fleet_throughput.py b/demo/1_fleet_throughput.py
new file mode 100644
index 0000000000..b9835c72b0
--- /dev/null
+++ b/demo/1_fleet_throughput.py
@@ -0,0 +1,141 @@
+"""
+Demo 1: Fleet Throughput
+Connect to 99 cloud VMs sequentially, then send tap+screenshot concurrently.
+Reports total throughput as steps/hour at the end.
+
+Usage:
+ CUA_API_KEY=sk_... python demo/1_fleet_throughput.py
+"""
+
+import argparse
+import asyncio
+import time
+from pathlib import Path
+
+from cua_sandbox import Sandbox
+
+STATE_FILE = "/tmp/android_bench_sandboxes.txt"
+CONCURRENCY = 20 # parallel commands at once
+ROUNDS = 3 # tap+screenshot rounds per VM
+CONNECT_TIMEOUT = 30 # seconds per connect attempt
+
+OUT_DIR = Path(__file__).parent / "out"
+
+
+# ── helpers ──────────────────────────────────────────────────────────────────
+
+
+def load_names(n: int | None = None) -> list[str]:
+ with open(STATE_FILE) as f:
+ names = [line.strip() for line in f if line.strip()]
+ return names[:n] if n else names
+
+
+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 = []
+ for i, name in enumerate(names, 1):
+ print(f" [{i:>3}/{len(names)}] {name} ...", end=" ", flush=True)
+ try:
+ sb = await asyncio.wait_for(Sandbox.connect(name=name), timeout=CONNECT_TIMEOUT)
+ print("✓", flush=True)
+ sandboxes.append((name, sb))
+ except asyncio.TimeoutError:
+ print("✗ timeout", flush=True)
+ except Exception as e:
+ print(f"✗ {e}", flush=True)
+ return sandboxes
+
+
+async def run_step(name: str, sb: Sandbox) -> float:
+ """Tap center + screenshot. Returns elapsed seconds."""
+ t0 = time.monotonic()
+ w, h = await sb.screen.size()
+ await sb.mouse.click(w // 2, h // 2)
+ await sb.screenshot(format="jpeg")
+ return time.monotonic() - t0
+
+
+# ── main ─────────────────────────────────────────────────────────────────────
+
+
+async def main(n: int | None = None, rounds: int = ROUNDS):
+ 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"{'='*50}\n")
+
+ sandboxes = await connect_all(names)
+ print(f"\nConnected: {len(sandboxes)}/{len(names)} VMs\n")
+
+ if not sandboxes:
+ print("No VMs connected — exiting.")
+ return
+
+ # 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")
+ t_start = time.monotonic()
+
+ for round_num in range(1, rounds + 1):
+ print(f"── Round {round_num}/{rounds} ──")
+
+ async def step(name: str, sb: Sandbox):
+ async with sem:
+ try:
+ elapsed = await run_step(name, sb)
+ print(f" {name} {elapsed * 1000:.0f}ms")
+ return elapsed
+ except Exception as e:
+ print(f" {name} ERROR: {e}")
+ return None
+
+ round_results = await asyncio.gather(*[step(n, sb) for n, sb in sandboxes])
+ ok = [r for r in round_results if r is not None]
+ total_steps += len(ok)
+ latencies.extend(ok)
+
+ t_elapsed = time.monotonic() - t_start
+
+ # Disconnect
+ await asyncio.gather(*[sb.disconnect() for _, sb in sandboxes], return_exceptions=True)
+
+ # Save results
+ steps_per_hour = total_steps / t_elapsed * 3600
+ latencies.sort()
+ p50 = latencies[len(latencies) // 2] * 1000
+ p95 = latencies[int(len(latencies) * 0.95)] * 1000
+
+ results = (
+ f"VMs active : {len(sandboxes)}\n"
+ f"Total steps : {total_steps}\n"
+ f"Elapsed : {t_elapsed:.1f}s\n"
+ f"Throughput : {steps_per_hour:,.0f} steps/hour\n"
+ f"Latency p50 : {p50:.0f}ms\n"
+ f"Latency p95 : {p95:.0f}ms\n"
+ )
+ (OUT_DIR / "fleet_results.txt").write_text(results)
+
+ print(f"\n{'='*50}")
+ print(" Results")
+ print(f"{'='*50}")
+ print(results, end="")
+ print(f" Saved to : {OUT_DIR}/fleet_results.txt")
+ print(f"{'='*50}\n")
+
+
+if __name__ == "__main__":
+ parser = argparse.ArgumentParser()
+ parser.add_argument("--n", type=int, default=None, help="Number of VMs to use (default: all)")
+ parser.add_argument(
+ "--rounds", type=int, default=ROUNDS, help=f"Rounds per VM (default: {ROUNDS})"
+ )
+ args = parser.parse_args()
+ asyncio.run(main(n=args.n, rounds=args.rounds))
diff --git a/demo/2_ephemeral_fdroid.py b/demo/2_ephemeral_fdroid.py
new file mode 100644
index 0000000000..0bd7769da1
--- /dev/null
+++ b/demo/2_ephemeral_fdroid.py
@@ -0,0 +1,58 @@
+"""
+Demo 2: Ephemeral Android Sandbox — F-Droid APK Install
+Spins up a local Android VM, installs F-Droid, takes a screenshot.
+Sandbox is automatically destroyed on exit.
+
+Usage:
+ python demo/2_ephemeral_fdroid.py
+"""
+
+import asyncio
+from pathlib import Path
+
+from cua_sandbox import Sandbox
+from cua_sandbox.image import Image
+
+FDROID_APK = "https://f-droid.org/F-Droid.apk"
+
+OUT_DIR = Path(__file__).parent / "out"
+
+
+async def main():
+ OUT_DIR.mkdir(exist_ok=True)
+
+ print("\n" + "=" * 50)
+ print(" Ephemeral Android Sandbox — F-Droid")
+ print("=" * 50 + "\n")
+
+ image = Image.android().apk_install(FDROID_APK)
+
+ print("Starting local Android VM with F-Droid pre-installed...")
+ print("(VM is ephemeral — destroyed automatically on exit)\n")
+
+ async with Sandbox.ephemeral(image, local=True) as sb:
+ print("✓ Sandbox ready\n")
+
+ w, h = await sb.screen.size()
+ print(f" Screen size : {w}x{h}")
+
+ screenshot = await sb.screenshot(format="png")
+ out = OUT_DIR / "fdroid_home.png"
+ out.write_bytes(screenshot)
+ print(f" Screenshot : {out} ({len(screenshot):,} bytes)")
+
+ print("\nLaunching F-Droid...")
+ await sb.shell.run("am start -n org.fdroid.fdroid/.views.main.MainActivity")
+ await asyncio.sleep(3)
+
+ screenshot2 = await sb.screenshot(format="png")
+ out2 = OUT_DIR / "fdroid_launched.png"
+ out2.write_bytes(screenshot2)
+ print(f" Screenshot : {out2} ({len(screenshot2):,} bytes)")
+
+ print("\n✓ Sandbox destroyed\n")
+ print("=" * 50 + "\n")
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/docs/content/docs/cua/examples/ai-models/gemini-complex-ui-navigation.mdx b/docs/content/docs/cua/examples/ai-models/gemini-complex-ui-navigation.mdx
index 5132507601..8585e1ef47 100644
--- a/docs/content/docs/cua/examples/ai-models/gemini-complex-ui-navigation.mdx
+++ b/docs/content/docs/cua/examples/ai-models/gemini-complex-ui-navigation.mdx
@@ -96,7 +96,7 @@ Create a `requirements.txt` file:
```text
cua-agent
-cua-computer
+cua-sandbox
cua-som # OmniParser for GUI element detection
litellm>=1.0.0
python-dotenv>=1.0.0
@@ -153,7 +153,7 @@ import signal
import traceback
from agent import ComputerAgent
-from computer import Computer, VMProviderType
+from cua_sandbox import Sandbox, Image, VMProviderType
from dotenv import load_dotenv
logging.basicConfig(level=logging.INFO)
@@ -169,7 +169,7 @@ async def complex_ui_navigation():
with complex, multi-step navigation tasks.
"""
try:
- async with Computer(
+ async with Sandbox.create(
os_type="linux",
provider_type=VMProviderType.CLOUD,
name=os.environ["CUA_SANDBOX_NAME"],
@@ -300,7 +300,7 @@ import signal
import traceback
from agent import ComputerAgent
-from computer import Computer, VMProviderType
+from cua_sandbox import Sandbox, Image, VMProviderType
from dotenv import load_dotenv
logging.basicConfig(level=logging.INFO)
@@ -316,7 +316,7 @@ async def complex_ui_navigation():
with complex, multi-step navigation tasks.
"""
try:
- async with Computer(
+ async with Sandbox.create(
os_type="linux",
provider_type=VMProviderType.DOCKER,
image="trycua/cua-xfce:latest",
@@ -424,7 +424,7 @@ import signal
import traceback
from agent import ComputerAgent
-from computer import Computer, VMProviderType
+from cua_sandbox import Sandbox, Image, VMProviderType
from dotenv import load_dotenv
logging.basicConfig(level=logging.INFO)
@@ -440,7 +440,7 @@ async def complex_ui_navigation():
with complex, multi-step navigation tasks.
"""
try:
- async with Computer(
+ async with Sandbox.create(
os_type="macos",
provider_type=VMProviderType.LUME,
name="macos-sequoia-cua:latest",
diff --git a/docs/content/docs/cua/examples/automation/form-filling.mdx b/docs/content/docs/cua/examples/automation/form-filling.mdx
index 9935a7975f..bb9a12a343 100644
--- a/docs/content/docs/cua/examples/automation/form-filling.mdx
+++ b/docs/content/docs/cua/examples/automation/form-filling.mdx
@@ -26,7 +26,7 @@ Create a `requirements.txt` file:
```text
cua-agent
-cua-computer
+cua-sandbox
python-dotenv>=1.0.0
```
@@ -68,7 +68,7 @@ import signal
import traceback
from agent import ComputerAgent
-from computer import Computer, VMProviderType
+from cua_sandbox import Sandbox, Image, VMProviderType
from dotenv import load_dotenv
logging.basicConfig(level=logging.INFO)
@@ -80,7 +80,7 @@ def handle_sigint(sig, frame):
async def fill_application():
try:
- async with Computer(
+ async with Sandbox.create(
os_type="linux",
provider_type=VMProviderType.CLOUD,
name="your-sandbox-name", # Replace with your sandbox name
@@ -175,7 +175,7 @@ import signal
import traceback
from agent import ComputerAgent
-from computer import Computer, VMProviderType
+from cua_sandbox import Sandbox, Image, VMProviderType
from dotenv import load_dotenv
logging.basicConfig(level=logging.INFO)
@@ -187,7 +187,7 @@ def handle_sigint(sig, frame):
async def fill_application():
try:
- async with Computer(
+ async with Sandbox.create(
os_type="linux",
provider_type=VMProviderType.DOCKER,
image="trycua/cua-xfce:latest", # or "trycua/cua-ubuntu:latest"
@@ -275,7 +275,7 @@ import signal
import traceback
from agent import ComputerAgent
-from computer import Computer, VMProviderType
+from cua_sandbox import Sandbox, Image, VMProviderType
from dotenv import load_dotenv
logging.basicConfig(level=logging.INFO)
@@ -287,7 +287,7 @@ def handle_sigint(sig, frame):
async def fill_application():
try:
- async with Computer(
+ async with Sandbox.create(
os_type="macos",
provider_type=VMProviderType.LUME,
name="macos-sequoia-cua:latest",
@@ -375,7 +375,7 @@ import signal
import traceback
from agent import ComputerAgent
-from computer import Computer, VMProviderType
+from cua_sandbox import Sandbox, Image, VMProviderType
from dotenv import load_dotenv
logging.basicConfig(level=logging.INFO)
@@ -387,7 +387,7 @@ def handle_sigint(sig, frame):
async def fill_application():
try:
- async with Computer(
+ async with Sandbox.create(
os_type="windows",
provider_type=VMProviderType.WINDOWS_SANDBOX,
verbosity=logging.INFO,
diff --git a/docs/content/docs/cua/examples/automation/post-event-contact-export.mdx b/docs/content/docs/cua/examples/automation/post-event-contact-export.mdx
index 0ce29b6097..0024b008aa 100644
--- a/docs/content/docs/cua/examples/automation/post-event-contact-export.mdx
+++ b/docs/content/docs/cua/examples/automation/post-event-contact-export.mdx
@@ -62,7 +62,7 @@ Create a `requirements.txt` file:
```text
cua-agent
-cua-computer
+cua-sandbox
python-dotenv>=1.0.0
```
@@ -135,7 +135,7 @@ import traceback
from datetime import datetime
from agent import ComputerAgent
-from computer import Computer, VMProviderType
+from cua_sandbox import Sandbox, Image, VMProviderType
from dotenv import load_dotenv
logging.basicConfig(level=logging.INFO)
@@ -231,7 +231,7 @@ async def scrape_linkedin_connections():
print("=" * 80)
try:
- async with Computer(
+ async with Sandbox.create(
os_type="linux",
provider_type=VMProviderType.CLOUD,
name=os.environ["CUA_CONTAINER_NAME"], # Your sandbox name
@@ -393,8 +393,8 @@ if __name__ == "__main__":
<Tab value="Linux on Docker">
```python
-# Same code as Cloud Sandbox, but change Computer initialization to:
-async with Computer(
+# Same code as Cloud Sandbox, but change Sandbox initialization to:
+async with Sandbox.create(
os_type="linux",
provider_type=VMProviderType.DOCKER,
image="trycua/cua-xfce:latest",
@@ -408,8 +408,8 @@ And remove the `CUA_API_KEY` and `CUA_CONTAINER_NAME` requirements from `.env` a
<Tab value="macOS Sandbox">
```python
-# Same code as Cloud Sandbox, but change Computer initialization to:
-async with Computer(
+# Same code as Cloud Sandbox, but change Sandbox initialization to:
+async with Sandbox.create(
os_type="macos",
provider_type=VMProviderType.LUME,
name="macos-sequoia-cua:latest",
@@ -423,8 +423,8 @@ And remove the `CUA_API_KEY` and `CUA_CONTAINER_NAME` requirements from `.env` a
<Tab value="Windows Sandbox">
```python
-# Same code as Cloud Sandbox, but change Computer initialization to:
-async with Computer(
+# Same code as Cloud Sandbox, but change Sandbox initialization to:
+async with Sandbox.create(
os_type="windows",
provider_type=VMProviderType.WINDOWS_SANDBOX,
verbosity=logging.INFO,
diff --git a/docs/content/docs/cua/examples/meta.json b/docs/content/docs/cua/examples/meta.json
index 19f8736688..9c05043268 100644
--- a/docs/content/docs/cua/examples/meta.json
+++ b/docs/content/docs/cua/examples/meta.json
@@ -2,5 +2,5 @@
"title": "Examples",
"description": "Real-world examples of building with Cua",
"icon": "Blocks",
- "pages": ["..."]
+ "pages": ["sandboxes", "automation", "ai-models", "platform-specific", "claude-code"]
}
diff --git a/docs/content/docs/cua/examples/platform-specific/windows-app-behind-vpn.mdx b/docs/content/docs/cua/examples/platform-specific/windows-app-behind-vpn.mdx
index 85936a564b..b866ebfabe 100644
--- a/docs/content/docs/cua/examples/platform-specific/windows-app-behind-vpn.mdx
+++ b/docs/content/docs/cua/examples/platform-specific/windows-app-behind-vpn.mdx
@@ -61,7 +61,7 @@ Create a `requirements.txt` file:
```text
cua-agent
-cua-computer
+cua-sandbox
python-dotenv>=1.0.0
```
@@ -152,7 +152,7 @@ import asyncio
import logging
import os
from agent import ComputerAgent
-from computer import Computer, VMProviderType
+from cua_sandbox import Sandbox, Image, VMProviderType
from dotenv import load_dotenv
logging.basicConfig(level=logging.INFO)
@@ -172,7 +172,7 @@ async def automate_hr_workflow():
"""
try:
# Connect to Windows Cloud Sandbox with VPN
- async with Computer(
+ async with Sandbox.create(
os_type="windows",
provider_type=VMProviderType.CLOUD,
name=os.environ["CUA_SANDBOX_NAME"],
@@ -265,7 +265,7 @@ import asyncio
import logging
import os
from agent import ComputerAgent
-from computer import Computer, VMProviderType
+from cua_sandbox import Sandbox, Image, VMProviderType
from dotenv import load_dotenv
logging.basicConfig(level=logging.INFO)
@@ -276,7 +276,7 @@ load_dotenv()
async def automate_hr_workflow():
try:
# Connect to Windows Sandbox
- async with Computer(
+ async with Sandbox.create(
os_type="windows",
provider_type=VMProviderType.WINDOWS_SANDBOX,
verbosity=logging.INFO,
@@ -344,7 +344,7 @@ import asyncio
import logging
import os
from agent import ComputerAgent
-from computer import Computer
+from cua_sandbox import Sandbox, Image
from dotenv import load_dotenv
logging.basicConfig(level=logging.INFO)
@@ -355,7 +355,7 @@ load_dotenv()
async def automate_hr_workflow():
try:
# Connect to self-hosted Windows VM running computer-server
- async with Computer(
+ async with Sandbox.create(
use_host_computer_server=True,
base_url="http://your-windows-vm-ip:5757", # Update with your VM IP
verbosity=logging.INFO,
diff --git a/docs/content/docs/cua/examples/sandboxes/android.mdx b/docs/content/docs/cua/examples/sandboxes/android.mdx
new file mode 100644
index 0000000000..ccf8298bef
--- /dev/null
+++ b/docs/content/docs/cua/examples/sandboxes/android.mdx
@@ -0,0 +1,120 @@
+---
+title: Android Sandboxes
+description: Run Android 14 VMs with touch, gesture, and hardware key controls
+# test-sources:
+# examples/sandboxes/test_android_cloud_vm.py
+# examples/sandboxes/test_android_local_vm.py
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+Android sandboxes expose the `sb.mobile` interface for touch input, gestures, and hardware keys. Cloud Android works on any host OS. Local Android uses the Android SDK emulator.
+
+---
+
+## Cloud Android VM
+
+<Callout type="info">Requires `CUA_API_KEY`. No Android SDK or emulator needed.</Callout>
+
+```python
+# source: examples/sandboxes/test_android_cloud_vm.py
+import asyncio
+from cua_sandbox import Image, Sandbox
+
+
+async def main():
+ async with Sandbox.ephemeral(
+ Image.android("14"),
+ name="example-android-cloud-vm",
+ ) as sb:
+ screenshot = await sb.screenshot()
+ with open("screenshot.png", "wb") as f:
+ f.write(screenshot)
+
+ w, h = await sb.screen.size()
+ print(f"Screen: {w}x{h}")
+
+ # Touch controls
+ await sb.mobile.tap(w // 2, h // 2)
+ await sb.mobile.home()
+
+
+asyncio.run(main())
+```
+
+## Local Android VM
+
+<Callout type="info">Requires Android SDK with `emulator` and `adb` installed. No API key needed.</Callout>
+
+```python
+# source: examples/sandboxes/test_android_local_vm.py
+import asyncio
+from cua_sandbox import Image, Sandbox
+
+
+async def main():
+ async with Sandbox.ephemeral(
+ Image.android("14"),
+ local=True,
+ name="example-android-local-vm",
+ ) as sb:
+ screenshot = await sb.screenshot()
+ with open("screenshot.png", "wb") as f:
+ f.write(screenshot)
+
+ w, h = await sb.screen.size()
+ print(f"Screen: {w}x{h}")
+
+ await sb.mobile.tap(w // 2, h // 2)
+ await sb.mobile.home()
+
+
+asyncio.run(main())
+```
+
+---
+
+## `sb.mobile` interface
+
+All touch and hardware key operations go through `sb.mobile`:
+
+```python
+# Tap, long press, double tap
+await sb.mobile.tap(x, y)
+await sb.mobile.long_press(x, y, duration_ms=1000)
+await sb.mobile.double_tap(x, y)
+
+# Swipe and scroll
+await sb.mobile.swipe(x1, y1, x2, y2, duration_ms=300)
+await sb.mobile.scroll_up()
+await sb.mobile.scroll_down()
+
+# Hardware keys
+await sb.mobile.home()
+await sb.mobile.back()
+await sb.mobile.recents()
+
+# Text input
+await sb.mobile.type_text("hello world")
+```
+
+## Multi-touch gestures
+
+Use `sb.mobile.gesture()` for pinch-to-zoom and other multi-finger inputs. Pass alternating start/end `(x, y)` pairs — one pair per finger:
+
+```python
+w, h = await sb.screen.size()
+cx, cy = w // 2, h // 2
+
+# Pinch open (zoom in)
+await sb.mobile.gesture(
+ (cx - 20, cy), (cx - 200, cy), # finger 0
+ (cx + 20, cy), (cx + 200, cy), # finger 1
+)
+
+# Pinch close (zoom out)
+await sb.mobile.gesture(
+ (cx - 200, cy), (cx - 20, cy),
+ (cx + 200, cy), (cx + 20, cy),
+)
+```
diff --git a/docs/content/docs/cua/examples/sandboxes/custom-images.mdx b/docs/content/docs/cua/examples/sandboxes/custom-images.mdx
new file mode 100644
index 0000000000..54d8938280
--- /dev/null
+++ b/docs/content/docs/cua/examples/sandboxes/custom-images.mdx
@@ -0,0 +1,148 @@
+---
+title: Custom Images
+description: Run sandboxes from OCI registry images, local disk files, and OSWorld benchmarks
+# test-sources:
+# examples/sandboxes/test_linux_local_registry_vm.py
+# examples/sandboxes/test_macos_local_registry_vm.py
+# examples/sandboxes/test_linux_local_osworld_vm.py
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+Beyond the built-in `Image.linux()` / `Image.macos()` / `Image.windows()` constructors, the SDK supports pulling from OCI registries and running local disk images directly.
+
+---
+
+## OCI Registry — Linux VM via Tart
+
+Pull a Linux OCI VM image from `ghcr.io` and run it locally with `TartRuntime`. Tart uses Apple Virtualization framework and only works on macOS.
+
+<Callout type="info">Requires macOS host with [Tart](https://github.com/cirruslabs/tart) installed.</Callout>
+
+```python
+# source: examples/sandboxes/test_linux_local_registry_vm.py
+import asyncio
+from cua_sandbox import Image, Sandbox
+from cua_sandbox.runtime import TartRuntime
+
+
+async def main():
+ async with Sandbox.ephemeral(
+ Image.from_registry("ghcr.io/trycua/cua-xfce:latest"),
+ local=True,
+ runtime=TartRuntime(),
+ name="example-linux-local-registry-vm",
+ ) as sb:
+ result = await sb.shell.run("uname -s")
+ print(result.stdout.strip()) # "Linux"
+
+ screenshot = await sb.screenshot()
+ with open("screenshot.png", "wb") as f:
+ f.write(screenshot)
+
+
+asyncio.run(main())
+```
+
+## OCI Registry — macOS VM
+
+Pull a macOS OCI image. The SDK reads the OCI manifest to auto-select Lume as the runtime.
+
+<Callout type="info">Requires macOS host with Lume installed. For cloud macOS, use `Image.macos()` without `local=True` instead.</Callout>
+
+```python
+# source: examples/sandboxes/test_macos_local_registry_vm.py
+import asyncio
+from cua_sandbox import Image, Sandbox
+
+
+async def main():
+ async with Sandbox.ephemeral(
+ Image.from_registry("ghcr.io/trycua/macos-tahoe-cua:latest"),
+ local=True,
+ name="example-macos-local-registry-vm",
+ ) as sb:
+ result = await sb.shell.run("sw_vers")
+ print(result.stdout.strip())
+
+ screenshot = await sb.screenshot()
+ with open("screenshot.png", "wb") as f:
+ f.write(screenshot)
+
+
+asyncio.run(main())
+```
+
+---
+
+## Local disk image — qcow2 / vhdx / iso
+
+Run any local disk image directly. Supported formats: `.qcow2`, `.vhdx`, `.raw`, `.img`, `.iso`.
+
+```python
+import asyncio
+from cua_sandbox import Image, Sandbox
+
+async def main():
+ async with Sandbox.ephemeral(
+ Image.from_file("/path/to/disk.qcow2", os_type="linux"),
+ local=True,
+ ) as sb:
+ result = await sb.shell.run("uname -a")
+ print(result.stdout)
+
+asyncio.run(main())
+```
+
+URLs are downloaded and cached automatically in `~/.cua/cua-sandbox/image-cache/`:
+
+```python
+Image.from_file("https://example.com/custom-linux.qcow2", os_type="linux")
+```
+
+---
+
+## OSWorld benchmark image
+
+Run the standard [OSWorld](https://os-world.github.io/) Ubuntu image using the OSWorld Flask transport (`agent_type="osworld"`). The SDK downloads and caches the image from HuggingFace automatically.
+
+<Callout type="info">
+ Requires QEMU. The first run downloads the ~8GB Ubuntu.qcow2 image — subsequent runs use the local cache at `~/.cua/cua-sandbox/image-cache/`.
+</Callout>
+
+```python
+# source: examples/sandboxes/test_linux_local_osworld_vm.py
+import asyncio
+from cua_sandbox import Image, Sandbox
+from cua_sandbox.runtime import QEMURuntime
+
+OSWORLD_IMAGE = (
+ "https://huggingface.co/datasets/xlangai/ubuntu_osworld/resolve/main/Ubuntu.qcow2.zip"
+)
+
+
+async def main():
+ async with Sandbox.ephemeral(
+ Image.from_file(OSWORLD_IMAGE, os_type="linux", agent_type="osworld"),
+ local=True,
+ runtime=QEMURuntime(
+ mode="bare-metal",
+ api_port=18020,
+ vnc_display=20,
+ memory_mb=4096,
+ cpu_count=4,
+ ),
+ name="example-linux-local-osworld-vm",
+ ) as sb:
+ screenshot = await sb.screenshot()
+ with open("screenshot.png", "wb") as f:
+ f.write(screenshot)
+
+ w, h = await sb.get_dimensions()
+ print(f"Screen: {w}x{h}") # 1920x1080
+
+
+asyncio.run(main())
+```
+
+The `agent_type="osworld"` flag tells the SDK to use the OSWorld Flask API (`/screenshot`, `/execute_action`) instead of the standard computer-server transport. This matches the interface expected by the [OSWorld benchmark harness](/cua/guide/integrations/benchmarks/introduction).
diff --git a/docs/content/docs/cua/examples/sandboxes/linux.mdx b/docs/content/docs/cua/examples/sandboxes/linux.mdx
new file mode 100644
index 0000000000..54d6cf9c79
--- /dev/null
+++ b/docs/content/docs/cua/examples/sandboxes/linux.mdx
@@ -0,0 +1,137 @@
+---
+title: Linux Sandboxes
+description: Run Linux containers and VMs — cloud or local
+# test-sources:
+# examples/sandboxes/test_linux_cloud_container.py
+# examples/sandboxes/test_linux_cloud_vm.py
+# examples/sandboxes/test_linux_local_container.py
+# examples/sandboxes/test_linux_local_vm.py
+---
+
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+import { Callout } from 'fumadocs-ui/components/callout';
+
+Linux is available as either a lightweight **container** (Docker-backed, fast startup) or a full **VM** (QEMU, full kernel isolation). Both work locally and on Cua Cloud.
+
+| | Container | VM |
+|--|-----------|-----|
+| Startup | Fast (~5s) | Slower (~30s) |
+| Isolation | Process-level | Full kernel |
+| Local runtime | Docker | QEMU (Docker-wrapped or bare-metal) |
+| Cloud | `Image.linux()` | `Image.linux(kind="vm")` |
+
+---
+
+## Cloud Container
+
+<Callout type="info">Requires `CUA_API_KEY`. No local Docker or runtime needed.</Callout>
+
+```python
+# source: examples/sandboxes/test_linux_cloud_container.py
+import asyncio
+from cua_sandbox import Image, Sandbox
+
+
+async def main():
+ async with Sandbox.ephemeral(
+ Image.linux("ubuntu", "24.04"),
+ name="example-linux-cloud-container",
+ ) as sb:
+ result = await sb.shell.run("uname -s")
+ print(result.stdout.strip()) # "Linux"
+
+ screenshot = await sb.screenshot()
+ with open("screenshot.png", "wb") as f:
+ f.write(screenshot)
+
+
+asyncio.run(main())
+```
+
+## Cloud VM
+
+<Callout type="info">Requires `CUA_API_KEY`. Full VM — heavier than a container but with full kernel.</Callout>
+
+```python
+# source: examples/sandboxes/test_linux_cloud_vm.py
+import asyncio
+from cua_sandbox import Image, Sandbox
+
+
+async def main():
+ async with Sandbox.ephemeral(
+ Image.linux("ubuntu", "24.04", kind="vm"),
+ name="example-linux-cloud-vm",
+ ) as sb:
+ result = await sb.shell.run("uname -s")
+ print(result.stdout.strip()) # "Linux"
+
+ screenshot = await sb.screenshot()
+ with open("screenshot.png", "wb") as f:
+ f.write(screenshot)
+
+
+asyncio.run(main())
+```
+
+## Local Container
+
+<Callout type="info">Requires Docker. No API key needed.</Callout>
+
+```python
+# source: examples/sandboxes/test_linux_local_container.py
+import asyncio
+from cua_sandbox import Image, Sandbox
+
+
+async def main():
+ async with Sandbox.ephemeral(
+ Image.linux("ubuntu", "24.04"),
+ local=True,
+ name="example-linux-local-container",
+ ) as sb:
+ result = await sb.shell.run("uname -s")
+ print(result.stdout.strip()) # "Linux"
+
+ screenshot = await sb.screenshot()
+ with open("screenshot.png", "wb") as f:
+ f.write(screenshot)
+
+
+asyncio.run(main())
+```
+
+## Local VM
+
+<Callout type="info">Requires Docker (QEMU runs inside a Docker container). No API key needed.</Callout>
+
+```python
+# source: examples/sandboxes/test_linux_local_vm.py
+import asyncio
+from cua_sandbox import Image, Sandbox
+
+
+async def main():
+ async with Sandbox.ephemeral(
+ Image.linux("ubuntu", "24.04", kind="vm"),
+ local=True,
+ name="example-linux-local-vm",
+ ) as sb:
+ result = await sb.shell.run("uname -s")
+ print(result.stdout.strip()) # "Linux"
+
+ screenshot = await sb.screenshot()
+ with open("screenshot.png", "wb") as f:
+ f.write(screenshot)
+
+
+asyncio.run(main())
+```
+
+---
+
+## Container vs. VM — when to use which
+
+Use a **container** when you want fast iteration and don't need kernel-level isolation — CI jobs, web scraping, most agent tasks.
+
+Use a **VM** when you need a real kernel — testing kernel modules, `/dev/kvm` workloads, OS-level benchmarks like OSWorld, or when you need stronger isolation between runs.
diff --git a/docs/content/docs/cua/examples/sandboxes/macos.mdx b/docs/content/docs/cua/examples/sandboxes/macos.mdx
new file mode 100644
index 0000000000..062fe271a4
--- /dev/null
+++ b/docs/content/docs/cua/examples/sandboxes/macos.mdx
@@ -0,0 +1,109 @@
+---
+title: macOS Sandboxes
+description: Run macOS VMs — cloud or local via Lume, with managed or registry images
+# test-sources:
+# examples/sandboxes/test_macos_cloud_vm.py
+# examples/sandboxes/test_macos_local_vm.py
+# examples/sandboxes/test_macos_local_registry_vm.py
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+macOS sandboxes are always VMs — either on Cua Cloud or locally via [Lume](https://github.com/trycua/cua/tree/main/libs/lume) (Apple Virtualization framework). Cloud macOS works on any host OS — no Mac required.
+
+**Supported versions:** `"26"` / `"tahoe"` (default), `"15"` / `"sequoia"`
+
+---
+
+## Cloud macOS VM
+
+<Callout type="info">Requires `CUA_API_KEY`. Works on any host OS — Linux, Windows, or macOS.</Callout>
+
+```python
+# source: examples/sandboxes/test_macos_cloud_vm.py
+import asyncio
+from cua_sandbox import Image, Sandbox
+
+
+async def main():
+ async with Sandbox.ephemeral(
+ Image.macos("26"),
+ name="example-macos-cloud-vm",
+ ) as sb:
+ result = await sb.shell.run("sw_vers")
+ print(result.stdout.strip())
+
+ screenshot = await sb.screenshot()
+ with open("screenshot.png", "wb") as f:
+ f.write(screenshot)
+
+
+asyncio.run(main())
+```
+
+## Local macOS VM
+
+<Callout type="info">Requires macOS host with [Lume](https://github.com/trycua/cua/tree/main/libs/lume) installed. No API key needed.</Callout>
+
+```python
+# source: examples/sandboxes/test_macos_local_vm.py
+import asyncio
+from cua_sandbox import Image, Sandbox
+
+
+async def main():
+ async with Sandbox.ephemeral(
+ Image.macos("26"),
+ local=True,
+ name="example-macos-local-vm",
+ ) as sb:
+ result = await sb.shell.run("sw_vers")
+ print(result.stdout.strip())
+
+ screenshot = await sb.screenshot()
+ with open("screenshot.png", "wb") as f:
+ f.write(screenshot)
+
+
+asyncio.run(main())
+```
+
+## Local macOS VM from OCI Registry
+
+Pull a macOS image directly from the `ghcr.io/trycua` registry. The SDK reads the OCI manifest to resolve the image kind and auto-selects Lume.
+
+<Callout type="info">Requires macOS host with Lume installed.</Callout>
+
+```python
+# source: examples/sandboxes/test_macos_local_registry_vm.py
+import asyncio
+from cua_sandbox import Image, Sandbox
+
+
+async def main():
+ async with Sandbox.ephemeral(
+ Image.from_registry("ghcr.io/trycua/macos-tahoe-cua:latest"),
+ local=True,
+ name="example-macos-local-registry-vm",
+ ) as sb:
+ result = await sb.shell.run("sw_vers")
+ print(result.stdout.strip())
+
+ screenshot = await sb.screenshot()
+ with open("screenshot.png", "wb") as f:
+ f.write(screenshot)
+
+
+asyncio.run(main())
+```
+
+---
+
+## Choosing a version
+
+```python
+Image.macos() # macOS Tahoe (26) — latest, default
+Image.macos("26") # macOS Tahoe
+Image.macos("15") # macOS Sequoia
+Image.macos("sequoia") # also Sequoia
+```
diff --git a/docs/content/docs/cua/examples/sandboxes/meta.json b/docs/content/docs/cua/examples/sandboxes/meta.json
new file mode 100644
index 0000000000..344b7aaf61
--- /dev/null
+++ b/docs/content/docs/cua/examples/sandboxes/meta.json
@@ -0,0 +1,6 @@
+{
+ "title": "Sandboxes",
+ "description": "Runnable examples for every sandbox type",
+ "icon": "Monitor",
+ "pages": ["linux", "macos", "windows", "android", "custom-images"]
+}
diff --git a/docs/content/docs/cua/examples/sandboxes/windows.mdx b/docs/content/docs/cua/examples/sandboxes/windows.mdx
new file mode 100644
index 0000000000..34f7231891
--- /dev/null
+++ b/docs/content/docs/cua/examples/sandboxes/windows.mdx
@@ -0,0 +1,68 @@
+---
+title: Windows Sandboxes
+description: Run Windows 11 VMs — cloud or local via Hyper-V / QEMU
+# test-sources:
+# examples/sandboxes/test_windows_cloud_vm.py
+# examples/sandboxes/test_windows_local_vm.py
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+Windows sandboxes run as full VMs. Cloud Windows works on any host OS. Local Windows uses Hyper-V on Windows hosts, or QEMU as a fallback.
+
+---
+
+## Cloud Windows VM
+
+<Callout type="info">Requires `CUA_API_KEY`. Works on any host OS — no Windows needed.</Callout>
+
+```python
+# source: examples/sandboxes/test_windows_cloud_vm.py
+import asyncio
+from cua_sandbox import Image, Sandbox
+
+
+async def main():
+ async with Sandbox.ephemeral(
+ Image.windows("11"),
+ name="example-windows-cloud-vm",
+ ) as sb:
+ result = await sb.shell.run("ver")
+ print(result.stdout.strip())
+
+ screenshot = await sb.screenshot()
+ with open("screenshot.png", "wb") as f:
+ f.write(screenshot)
+
+
+asyncio.run(main())
+```
+
+## Local Windows VM
+
+<Callout type="info">Requires a Windows host with Hyper-V, or QEMU installed. No API key needed.</Callout>
+
+The SDK automatically selects Hyper-V on Windows hosts with Hyper-V available, otherwise falls back to QEMU.
+
+```python
+# source: examples/sandboxes/test_windows_local_vm.py
+import asyncio
+from cua_sandbox import Image, Sandbox
+
+
+async def main():
+ async with Sandbox.ephemeral(
+ Image.windows("11"),
+ local=True,
+ name="example-windows-local-vm",
+ ) as sb:
+ result = await sb.shell.run("ver")
+ print(result.stdout.strip())
+
+ screenshot = await sb.screenshot()
+ with open("screenshot.png", "wb") as f:
+ f.write(screenshot)
+
+
+asyncio.run(main())
+```
diff --git a/docs/content/docs/cua/guide/advanced/chat-history.mdx b/docs/content/docs/cua/guide/advanced/chat-history.mdx
index fc2e4d3d0b..d5f77fd5e2 100644
--- a/docs/content/docs/cua/guide/advanced/chat-history.mdx
+++ b/docs/content/docs/cua/guide/advanced/chat-history.mdx
@@ -10,16 +10,14 @@ description: Managing conversation history for multi-turn agent interactions
Pass a message history to continue from previous context:
```python
-from computer import Computer
+from cua_sandbox import Sandbox, Image
from agent import ComputerAgent
-computer = Computer(os_type="linux", provider_type="docker", image="trycua/cua-xfce:latest")
-await computer.run()
-
-agent = ComputerAgent(
- model="anthropic/claude-sonnet-4-5-20250929",
- tools=[computer]
-)
+async with Sandbox.ephemeral(Image.linux()) as computer:
+ agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer]
+ )
# First turn
messages = [{"role": "user", "content": "Open Firefox"}]
diff --git a/docs/content/docs/cua/guide/advanced/composed-models.mdx b/docs/content/docs/cua/guide/advanced/composed-models.mdx
index 1b3a8ed0dd..094ecef84e 100644
--- a/docs/content/docs/cua/guide/advanced/composed-models.mdx
+++ b/docs/content/docs/cua/guide/advanced/composed-models.mdx
@@ -10,17 +10,15 @@ Some models excel at **grounding** (finding UI elements) but can't reason about
Use the `+` syntax to combine a grounding model with a planning model:
```python
-from computer import Computer
+from cua_sandbox import Sandbox, Image
from agent import ComputerAgent
-computer = Computer(os_type="linux", provider_type="docker", image="trycua/cua-xfce:latest")
-await computer.run()
-
-# Format: grounding_model+planning_model
-agent = ComputerAgent(
- model="huggingface-local/HelloKKMe/GTA1-7B+anthropic/claude-sonnet-4-5-20250929",
- tools=[computer]
-)
+async with Sandbox.ephemeral(Image.linux()) as computer:
+ # Format: grounding_model+planning_model
+ agent = ComputerAgent(
+ model="huggingface-local/HelloKKMe/GTA1-7B+anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer]
+ )
```
Cua uses a two-stage approach:
diff --git a/docs/content/docs/cua/guide/advanced/custom-tools.mdx b/docs/content/docs/cua/guide/advanced/custom-tools.mdx
index e25806d3bb..e9530a01da 100644
--- a/docs/content/docs/cua/guide/advanced/custom-tools.mdx
+++ b/docs/content/docs/cua/guide/advanced/custom-tools.mdx
@@ -73,7 +73,7 @@ The agent can now call `calculate` and `get_weather` alongside computer actions.
For tools that should run inside the sandbox rather than on your host machine, use the `@sandboxed` decorator:
```python
-from computer.helpers import sandboxed
+from cua_sandbox.helpers import sandboxed
@sandboxed()
def read_file(path: str) -> str:
@@ -204,7 +204,7 @@ Pass multiple tools of different types:
```python
from agent import ComputerAgent
from agent.tools import BrowserTool
-from computer.helpers import sandboxed
+from cua_sandbox.helpers import sandboxed
# Built-in tool
browser = BrowserTool(interface=computer)
@@ -252,7 +252,7 @@ Here's a complete example with file management tools:
```python
from agent import ComputerAgent
-from computer.helpers import sandboxed
+from cua_sandbox.helpers import sandboxed
@sandboxed()
def list_files(directory: str = ".") -> list:
diff --git a/docs/content/docs/cua/guide/advanced/human-in-the-loop.mdx b/docs/content/docs/cua/guide/advanced/human-in-the-loop.mdx
index 50b22f2072..0f120eccb3 100644
--- a/docs/content/docs/cua/guide/advanced/human-in-the-loop.mdx
+++ b/docs/content/docs/cua/guide/advanced/human-in-the-loop.mdx
@@ -20,16 +20,14 @@ This opens a UI that shows pending completions. Select a completion to take cont
Use `human/human` as the model:
```python
-from computer import Computer
+from cua_sandbox import Sandbox, Image
from agent import ComputerAgent
-computer = Computer(os_type="linux", provider_type="docker", image="trycua/cua-xfce:latest")
-await computer.run()
-
-agent = ComputerAgent(
- model="human/human",
- tools=[computer]
-)
+async with Sandbox.ephemeral(Image.linux()) as computer:
+ agent = ComputerAgent(
+ model="human/human",
+ tools=[computer]
+ )
async for result in agent.run("Navigate to settings and enable dark mode"):
print(result)
diff --git a/docs/content/docs/cua/guide/advanced/interactive-shell.mdx b/docs/content/docs/cua/guide/advanced/interactive-shell.mdx
index 4d34d709cb..190216370c 100644
--- a/docs/content/docs/cua/guide/advanced/interactive-shell.mdx
+++ b/docs/content/docs/cua/guide/advanced/interactive-shell.mdx
@@ -29,9 +29,9 @@ The shell is fully interactive — arrow keys, tab completion, and `Ctrl+C` all
## Python SDK
```python
-from computer import Computer
+from cua_sandbox import Sandbox, Image
-async with Computer(provider_type="docker", name="my-container") as c:
+async with Sandbox.create(provider_type="docker", name="my-container") as c:
handle = await c.pty.create(
command="bash",
cols=80,
diff --git a/docs/content/docs/cua/guide/advanced/local-computer-server.mdx b/docs/content/docs/cua/guide/advanced/local-computer-server.mdx
index b85da3d240..6ec7248522 100644
--- a/docs/content/docs/cua/guide/advanced/local-computer-server.mdx
+++ b/docs/content/docs/cua/guide/advanced/local-computer-server.mdx
@@ -24,7 +24,7 @@ Or install dependencies manually:
```bash
pip install uvicorn fastapi
-pip install cua-computer
+pip install cua-sandbox
```
## Starting the Server
@@ -54,16 +54,14 @@ The server exposes endpoints for screenshots, mouse/keyboard input, and other co
Use `use_host_computer_server=True` to connect to a running computer server:
```python
-from computer import Computer
+from cua_sandbox import Sandbox, Image
# Connect to local computer server
-computer = Computer(use_host_computer_server=True)
-await computer.run()
-
-# Now you can control your desktop
-screenshot = await computer.interface.screenshot()
-await computer.interface.left_click(500, 300)
-await computer.interface.type_text("Hello from the agent!")
+async with Sandbox.create(use_host_computer_server=True) as computer:
+ # Now you can control your desktop
+ screenshot = await computer.interface.screenshot()
+ await computer.interface.left_click(500, 300)
+ await computer.interface.type_text("Hello from the agent!")
```
### Custom Host/Port
@@ -71,11 +69,12 @@ await computer.interface.type_text("Hello from the agent!")
Connect to a computer server running on a different machine:
```python
-computer = Computer(
+async with Sandbox.create(
use_host_computer_server=True,
api_host="192.168.1.100",
api_port=8000
-)
+) as computer:
+ ...
```
## With ComputerAgent
@@ -83,19 +82,17 @@ computer = Computer(
Run agents against your desktop:
```python
-from computer import Computer
+from cua_sandbox import Sandbox, Image
from agent import ComputerAgent
-computer = Computer(use_host_computer_server=True)
-await computer.run()
-
-agent = ComputerAgent(
- model="anthropic/claude-sonnet-4-5-20250929",
- tools=[computer]
-)
+async with Sandbox.create(use_host_computer_server=True) as computer:
+ agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer]
+ )
-async for result in agent.run("Open Firefox and go to github.com"):
- print(result)
+ async for result in agent.run("Open Firefox and go to github.com"):
+ print(result)
```
## Self-Hosted VMs
@@ -104,11 +101,12 @@ For VMs you manage yourself (e.g., Windows behind a VPN), install the computer s
```python
# Connect to Windows VM running computer-server
-computer = Computer(
+async with Sandbox.create(
use_host_computer_server=True,
api_host="windows-vm.local",
api_port=8000
-)
+) as computer:
+ ...
```
See the [Windows App Behind VPN](/cua/examples/platform-specific/windows-app-behind-vpn) example for a complete walkthrough.
diff --git a/docs/content/docs/cua/guide/advanced/meta.json b/docs/content/docs/cua/guide/advanced/meta.json
index 879d7ec709..ba5dd84457 100644
--- a/docs/content/docs/cua/guide/advanced/meta.json
+++ b/docs/content/docs/cua/guide/advanced/meta.json
@@ -7,7 +7,6 @@
"custom-tools",
"sandboxed-python",
"local-computer-server",
- "interactive-shell",
"human-in-the-loop",
"vnc-recorder",
"demonstration-guided-skills",
diff --git a/docs/content/docs/cua/guide/advanced/prompt-caching.mdx b/docs/content/docs/cua/guide/advanced/prompt-caching.mdx
index 6f25c00687..a8dd0c2b79 100644
--- a/docs/content/docs/cua/guide/advanced/prompt-caching.mdx
+++ b/docs/content/docs/cua/guide/advanced/prompt-caching.mdx
@@ -10,17 +10,16 @@ description: Reduce costs and latency with provider-specific prompt caching
Set `use_prompt_caching=True` when creating your agent:
```python
-from computer import Computer
+from cua_sandbox import Sandbox, Image
from agent import ComputerAgent
-computer = Computer(os_type="linux", provider_type="docker", image="trycua/cua-xfce:latest")
-await computer.run()
+async with Sandbox.ephemeral(Image.linux()) as computer:
-agent = ComputerAgent(
- model="anthropic/claude-sonnet-4-5-20250929",
- tools=[computer],
- use_prompt_caching=True
-)
+ agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer],
+ use_prompt_caching=True
+ )
```
## Provider Behavior
diff --git a/docs/content/docs/cua/guide/advanced/sandboxed-python.mdx b/docs/content/docs/cua/guide/advanced/sandboxed-python.mdx
index 87c7e97e38..9d98cec6b6 100644
--- a/docs/content/docs/cua/guide/advanced/sandboxed-python.mdx
+++ b/docs/content/docs/cua/guide/advanced/sandboxed-python.mdx
@@ -17,12 +17,10 @@ Sometimes you don't want to rely on UI automation or shell commands—you just w
Here's the basic pattern:
```python
-from computer import Computer
+from cua_sandbox import Sandbox, Image
-computer = Computer(os_type="linux", provider_type="docker", image="trycua/cua-xfce:latest")
-await computer.run()
-
-# First, install any packages you need
+async with Sandbox.ephemeral(Image.linux()) as computer:
+ # First, install any packages you need
await computer.venv_install("my_env", ["requests", "pandas"])
# Define a function to run remotely
@@ -72,13 +70,11 @@ result = await computer.venv_cmd("data_env", "python /path/to/script.py")
For cleaner code, use the decorator to mark functions for remote execution:
```python
-from computer import Computer
-from computer.helpers import sandboxed
-
-computer = Computer(os_type="linux", provider_type="docker", image="trycua/cua-xfce:latest")
-await computer.run()
+from cua_sandbox import Sandbox, Image
+from cua_sandbox.helpers import sandboxed
-await computer.venv_install("api_env", ["requests"])
+async with Sandbox.ephemeral(Image.linux()) as computer:
+ await computer.venv_install("api_env", ["requests"])
@sandboxed("api_env")
def call_api(endpoint, payload):
diff --git a/docs/content/docs/cua/guide/advanced/telemetry.mdx b/docs/content/docs/cua/guide/advanced/telemetry.mdx
index 573e93865c..fd1cc665f6 100644
--- a/docs/content/docs/cua/guide/advanced/telemetry.mdx
+++ b/docs/content/docs/cua/guide/advanced/telemetry.mdx
@@ -47,15 +47,12 @@ export CUA_TELEMETRY_ENABLED=false
Disable on individual objects:
```python
-from computer import Computer
+from cua_sandbox import Sandbox, Image
from agent import ComputerAgent
# Disable for Computer
-computer = Computer(
- os_type="linux",
- provider_type="docker",
- telemetry_enabled=False
-)
+async with Sandbox.ephemeral(Image.linux(), telemetry_enabled=False) as computer:
+ pass
# Disable for Agent
agent = ComputerAgent(
diff --git a/docs/content/docs/cua/guide/advanced/tracing.mdx b/docs/content/docs/cua/guide/advanced/tracing.mdx
index 7cc8267dc5..835c128c9f 100644
--- a/docs/content/docs/cua/guide/advanced/tracing.mdx
+++ b/docs/content/docs/cua/guide/advanced/tracing.mdx
@@ -10,22 +10,20 @@ The **Tracing API** records everything that happens on a Computer—screenshots,
Start and stop tracing around any computer operations:
```python
-from computer import Computer
+from cua_sandbox import Sandbox, Image
-computer = Computer(os_type="linux", provider_type="docker", image="trycua/cua-xfce:latest")
-await computer.run()
+async with Sandbox.ephemeral(Image.linux()) as computer:
+ # Start tracing
+ await computer.tracing.start()
-# Start tracing
-await computer.tracing.start()
-
-# Perform operations (these get recorded)
-await computer.interface.left_click(100, 200)
-await computer.interface.type_text("Hello, World!")
-screenshot = await computer.interface.screenshot()
+ # Perform operations (these get recorded)
+ await computer.interface.left_click(100, 200)
+ await computer.interface.type_text("Hello, World!")
+ screenshot = await computer.interface.screenshot()
-# Stop and save trace
-trace_path = await computer.tracing.stop()
-print(f"Trace saved to: {trace_path}")
+ # Stop and save trace
+ trace_path = await computer.tracing.stop()
+ print(f"Trace saved to: {trace_path}")
```
This creates a ZIP archive containing all recorded events, screenshots, and metadata.
@@ -149,26 +147,24 @@ Metadata appears in the trace alongside events, making it easy to correlate acti
Tracing works alongside ComputerAgent—you get both agent-level information and detailed computer interaction logs:
```python
-from computer import Computer
+from cua_sandbox import Sandbox, Image
from agent import ComputerAgent
-computer = Computer(os_type="linux", provider_type="docker", image="trycua/cua-xfce:latest")
-await computer.run()
+async with Sandbox.ephemeral(Image.linux()) as computer:
+ # Start tracing before agent runs
+ await computer.tracing.start({"name": "agent-task"})
-# Start tracing before agent runs
-await computer.tracing.start({"name": "agent-task"})
+ agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer],
+ trajectory_dir="trajectories" # Can use both!
+ )
-agent = ComputerAgent(
- model="anthropic/claude-sonnet-4-5-20250929",
- tools=[computer],
- trajectory_dir="trajectories" # Can use both!
-)
+ async for result in agent.run("Open Firefox and search for Cua"):
+ pass
-async for result in agent.run("Open Firefox and search for Cua"):
- pass
-
-# Stop tracing after agent completes
-trace_path = await computer.tracing.stop()
+ # Stop tracing after agent completes
+ trace_path = await computer.tracing.stop()
```
Now you have:
@@ -208,24 +204,22 @@ Now you have:
Tracing is ideal for capturing human-driven workflows as training data:
```python
-computer = Computer(os_type="linux", provider_type="docker", image="trycua/cua-xfce:latest")
-await computer.run()
-
-await computer.tracing.start({
- "name": "human-demo-login",
- "accessibility_tree": True # Capture UI structure
-})
-
-# Human performs actions via VNC or other interface
-# Meanwhile, your script can add context:
-await computer.tracing.add_metadata("task", "login-to-dashboard")
-await computer.tracing.add_metadata("demonstrator", "expert-user-1")
-
-# Wait for human to finish...
-input("Press Enter when done with demonstration")
-
-trace_path = await computer.tracing.stop()
-print(f"Demo saved to: {trace_path}")
+async with Sandbox.ephemeral(Image.linux()) as computer:
+ await computer.tracing.start({
+ "name": "human-demo-login",
+ "accessibility_tree": True # Capture UI structure
+ })
+
+ # Human performs actions via VNC or other interface
+ # Meanwhile, your script can add context:
+ await computer.tracing.add_metadata("task", "login-to-dashboard")
+ await computer.tracing.add_metadata("demonstrator", "expert-user-1")
+
+ # Wait for human to finish...
+ input("Press Enter when done with demonstration")
+
+ trace_path = await computer.tracing.stop()
+ print(f"Demo saved to: {trace_path}")
```
## Privacy Considerations
diff --git a/docs/content/docs/cua/guide/fundamentals/agent-loops.mdx b/docs/content/docs/cua/guide/fundamentals/agent-loops.mdx
index 062bb68270..66a0979f05 100644
--- a/docs/content/docs/cua/guide/fundamentals/agent-loops.mdx
+++ b/docs/content/docs/cua/guide/fundamentals/agent-loops.mdx
@@ -19,11 +19,11 @@ To run an agent loop simply do:
```python
from agent import ComputerAgent
import asyncio
-from computer import Computer
+from cua_sandbox import Sandbox, Image
async def take_screenshot():
- async with Computer(
+ async with Sandbox.create(
os_type="linux",
provider_type="cloud",
name="your-sandbox-name",
diff --git a/docs/content/docs/cua/guide/fundamentals/browser-tool.mdx b/docs/content/docs/cua/guide/fundamentals/browser-tool.mdx
index 97cdc6a1f8..6243dbc844 100644
--- a/docs/content/docs/cua/guide/fundamentals/browser-tool.mdx
+++ b/docs/content/docs/cua/guide/fundamentals/browser-tool.mdx
@@ -24,16 +24,14 @@ Use the standard Computer tool when:
The Browser Tool uses Playwright under the hood to control the browser:
```python
-from computer import Computer
+from cua_sandbox import Sandbox, Image
from agent import ComputerAgent
from agent.tools import BrowserTool
# Create a computer instance
-computer = Computer(os_type="linux", provider_type="docker", image="trycua/cua-xfce:latest")
-await computer.run()
-
-# Create a browser tool from the computer interface
-browser = BrowserTool(interface=computer)
+async with Sandbox.ephemeral(Image.linux()) as computer:
+ # Create a browser tool from the computer interface
+ browser = BrowserTool(interface=computer)
# Use with a browser-optimized model
agent = ComputerAgent(
@@ -142,14 +140,12 @@ The `pause_and_memorize_fact` action lets the agent store information for later
Here's a complete example automating a web form:
```python
-from computer import Computer
+from cua_sandbox import Sandbox, Image
from agent import ComputerAgent
from agent.tools import BrowserTool
-computer = Computer(os_type="linux", provider_type="docker", image="trycua/cua-xfce:latest")
-await computer.run()
-
-browser = BrowserTool(interface=computer)
+async with Sandbox.ephemeral(Image.linux()) as computer:
+ browser = BrowserTool(interface=computer)
agent = ComputerAgent(
model="gemini-2.5-computer-use-preview-10-2025",
diff --git a/docs/content/docs/cua/guide/fundamentals/cua-vlm-router.mdx b/docs/content/docs/cua/guide/fundamentals/cua-vlm-router.mdx
index 66af3d769f..3dabad5596 100644
--- a/docs/content/docs/cua/guide/fundamentals/cua-vlm-router.mdx
+++ b/docs/content/docs/cua/guide/fundamentals/cua-vlm-router.mdx
@@ -8,16 +8,14 @@ Instead of deploying and managing computer-use vision language models yourself o
## Setup
```python
-from computer import Computer
+from cua_sandbox import Sandbox, Image
from agent import ComputerAgent
-computer = Computer(os_type="linux", provider_type="docker", image="trycua/cua-xfce:latest")
-await computer.run()
-
-agent = ComputerAgent(
- model="cua/anthropic/claude-sonnet-4.5",
- tools=[computer]
-)
+async with Sandbox.ephemeral(Image.linux()) as computer:
+ agent = ComputerAgent(
+ model="cua/anthropic/claude-sonnet-4.5",
+ tools=[computer]
+ )
```
```bash
diff --git a/docs/content/docs/cua/guide/fundamentals/meta.json b/docs/content/docs/cua/guide/fundamentals/meta.json
index 92b6b02268..ebdcd7451f 100644
--- a/docs/content/docs/cua/guide/fundamentals/meta.json
+++ b/docs/content/docs/cua/guide/fundamentals/meta.json
@@ -1,6 +1,6 @@
{
- "title": "Fundamentals",
- "description": "Core concepts for building with Cua",
+ "title": "Agent",
+ "description": "Core concepts for building agents with Cua",
"icon": "Lightbulb",
"defaultOpen": true,
"pages": ["agent-loops", "vlms", "cua-vlm-router", "browser-tool", "callbacks"]
diff --git a/docs/content/docs/cua/guide/fundamentals/vlms.mdx b/docs/content/docs/cua/guide/fundamentals/vlms.mdx
index e25e1d11d3..13402036c2 100644
--- a/docs/content/docs/cua/guide/fundamentals/vlms.mdx
+++ b/docs/content/docs/cua/guide/fundamentals/vlms.mdx
@@ -10,16 +10,14 @@ A **Vision Language Model (VLM)** is the AI that powers your computer-use agent.
Specify the model when creating your agent:
```python
-from computer import Computer
+from cua_sandbox import Sandbox, Image
from agent import ComputerAgent
-computer = Computer(os_type="linux", provider_type="docker", image="trycua/cua-xfce:latest")
-await computer.run()
-
-agent = ComputerAgent(
- model="anthropic/claude-sonnet-4-5-20250929",
- tools=[computer]
-)
+async with Sandbox.ephemeral(Image.linux()) as computer:
+ agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer]
+ )
async for result in agent.run("Open Firefox and search for 'Cua'"):
print(result)
diff --git a/docs/content/docs/cua/guide/get-started/meta.json b/docs/content/docs/cua/guide/get-started/meta.json
index 3eef4f68e7..a9fe5e0ca1 100644
--- a/docs/content/docs/cua/guide/get-started/meta.json
+++ b/docs/content/docs/cua/guide/get-started/meta.json
@@ -6,8 +6,8 @@
"pages": [
"what-is-cua",
"quickstart",
- "using-computer-sdk",
+ "using-sandbox-sdk",
"using-agent-sdk",
- "self-hosted-sandboxes"
+ "migrating-from-computer-sdk"
]
}
diff --git a/docs/content/docs/cua/guide/get-started/migrating-from-computer-sdk.mdx b/docs/content/docs/cua/guide/get-started/migrating-from-computer-sdk.mdx
new file mode 100644
index 0000000000..3ba81bbdf4
--- /dev/null
+++ b/docs/content/docs/cua/guide/get-started/migrating-from-computer-sdk.mdx
@@ -0,0 +1,136 @@
+---
+title: Migrating from the Computer SDK
+description: Move from cua-computer to cua-sandbox — the new unified Cua SDK
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+<Callout type="warn" title="Computer SDK is deprecated">
+`cua-computer` is deprecated and will no longer receive new features. All new development is happening in `cua-sandbox`. This guide shows you how to migrate.
+</Callout>
+
+## Why the change?
+
+The old Computer SDK (`cua-computer`) required you to separately provision a sandbox (via the CLI or cloud dashboard) and then connect to it with a `Computer` object. This split made the API more confusing than necessary — two packages to install, two different concepts to understand.
+
+The new Sandbox SDK (`cua-sandbox`) unifies everything: one package creates the sandbox, controls it, and cleans it up. The API surface is also cleaner — sub-objects (`sb.mouse`, `sb.keyboard`, `sb.shell`) instead of a flat `computer.interface.*` namespace.
+
+## Package rename
+
+```bash
+# Before
+pip install cua-computer
+
+# After
+pip install cua-sandbox
+```
+
+## Import and instantiation
+
+**Before:**
+
+```python
+from computer import Computer
+
+computer = Computer(
+ os_type="linux",
+ provider_type="cloud",
+ name="my-sandbox-name"
+)
+await computer.run()
+```
+
+**After:**
+
+```python
+from cua_sandbox import Sandbox, Image
+
+# Ephemeral (create + destroy automatically)
+async with Sandbox.ephemeral(Image.linux()) as sb:
+ ...
+
+# Connect to an existing sandbox by name
+async with Sandbox.connect("my-sandbox-name") as sb:
+ ...
+```
+
+## Method mapping
+
+| Computer SDK | Sandbox SDK |
+|---|---|
+| `await computer.run()` | Handled by `Sandbox.ephemeral()` / `.create()` / `.connect()` |
+| `await computer.disconnect()` | `await sb.disconnect()` |
+| `await computer.stop()` | `await sb.delete()` |
+| `await computer.interface.screenshot()` | `await sb.screenshot()` |
+| `await computer.interface.left_click(x, y)` | `await sb.mouse.click(x, y)` |
+| `await computer.interface.right_click(x, y)` | `await sb.mouse.right_click(x, y)` |
+| `await computer.interface.double_click(x, y)` | `await sb.mouse.double_click(x, y)` |
+| `await computer.interface.move(x, y)` | `await sb.mouse.move(x, y)` |
+| `await computer.interface.scroll(x, y, clicks)` | `await sb.mouse.scroll(x, y, dy=clicks)` |
+| `await computer.interface.type_text("text")` | `await sb.keyboard.type("text")` |
+| `await computer.interface.key("Enter")` | `await sb.keyboard.press("Return")` |
+| `await computer.interface.get_screen_size()` | `await sb.screen.size()` |
+
+## Provider mapping
+
+The old SDK used a `provider_type` string to select the runtime. The new SDK uses `Image` factory methods and the `local` flag.
+
+| Computer SDK `provider_type` | Sandbox SDK |
+|---|---|
+| `"cloud"` | `Sandbox.ephemeral(Image.linux())` (default) |
+| `"docker"` with Linux image | `Sandbox.ephemeral(Image.linux(), local=True)` |
+| `"docker"` with QEMU Linux | `Sandbox.ephemeral(Image.linux(kind="vm"), local=True)` |
+| `"docker"` with QEMU Windows | `Sandbox.ephemeral(Image.windows(), local=True)` |
+| `"docker"` with QEMU Android | `Sandbox.ephemeral(Image.android(), local=True)` |
+| `"lume"` | `Sandbox.ephemeral(Image.macos(), local=True)` |
+| `"windows_sandbox"` | `Sandbox.ephemeral(Image.windows(), local=True)` |
+| `use_host_computer_server=True` | `from cua_sandbox import Localhost; Localhost.connect()` |
+
+## Before and after — full example
+
+**Before:**
+
+```python
+import asyncio
+from computer import Computer
+
+computer = Computer(
+ os_type="linux",
+ provider_type="docker",
+ image="trycua/cua-xfce:latest"
+)
+
+async def main():
+ await computer.run()
+ try:
+ screenshot = await computer.interface.screenshot()
+ await computer.interface.left_click(100, 100)
+ await computer.interface.type_text("Hello!")
+ finally:
+ await computer.disconnect()
+
+asyncio.run(main())
+```
+
+**After:**
+
+```python
+import asyncio
+from cua_sandbox import Sandbox, Image
+
+async def main():
+ async with Sandbox.ephemeral(Image.linux(), local=True) as sb:
+ screenshot = await sb.screenshot()
+ await sb.mouse.click(100, 100)
+ await sb.keyboard.type("Hello!")
+
+asyncio.run(main())
+```
+
+## Agent SDK
+
+The Agent SDK (`cua-agent`) currently uses `cua-computer` internally. Migration of the agent SDK to `cua-sandbox` is in progress. For now, you can use both packages side by side — `cua-sandbox` for sandbox control and `cua-agent` for AI agent orchestration.
+
+## Getting help
+
+If you run into anything not covered here, [open an issue](https://github.com/trycua/cua/issues) or check the [Sandbox SDK Reference](/cua/reference/sandbox-sdk).
diff --git a/docs/content/docs/cua/guide/get-started/quickstart.mdx b/docs/content/docs/cua/guide/get-started/quickstart.mdx
index 3aaa9a939e..3629be418a 100644
--- a/docs/content/docs/cua/guide/get-started/quickstart.mdx
+++ b/docs/content/docs/cua/guide/get-started/quickstart.mdx
@@ -4,181 +4,125 @@ description: Get a computer-use agent running in 5 minutes
---
import { Callout } from 'fumadocs-ui/components/callout';
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
-This guide gets you from zero to a working computer-use agent using Cua Cloud sandboxes.
+This guide gets you from zero to a working computer-use agent.
<Callout type="info">
- **Prerequisites:** Python 3.12 or 3.13 and a free Cua account at [cua.ai](https://cua.ai/signin).
+ **No account? No problem.** The hello-world example below runs entirely with local Docker — no API key required. You only need a [Cua account](https://cua.ai/signin) when you want cloud sandboxes or to run the AI agent against a hosted model.
+
+ **Prerequisites:** Python 3.12 or 3.13 and [Docker](https://docs.docker.com/get-docker/) (for local sandboxes).
</Callout>
-## 1. Install the Cua CLI and SDKs
+## 1. Install
```bash
-pip install cua-cli cua-computer "cua-agent[all]"
+pip install cua-sandbox "cua-agent[all]"
```
-## 2. Authenticate
-
-Login with your Cua account:
+## 2. Hello World
-```bash
-cua auth login
-```
+Create `hello.py`:
-This opens your browser for authentication. Once complete, your API key is stored locally.
+```python
+import asyncio
+from cua_sandbox import Sandbox, Image
-To export your API key to a `.env` file for use in scripts:
+async def main():
+ # local=True uses Docker — no API key needed
+ # remove local=True to run on Cua Cloud (requires CUA_API_KEY)
+ async with Sandbox.ephemeral(Image.linux(), local=True) as sb:
+ result = await sb.shell.run("uname -a")
+ print(result.stdout)
+
+ screenshot = await sb.screenshot()
+ with open("screenshot.png", "wb") as f:
+ f.write(screenshot)
+ print("Screenshot saved to screenshot.png")
-```bash
-cua auth env
+asyncio.run(main())
```
-## 3. Create a Cloud Sandbox
-
-Create a Linux sandbox:
-
```bash
-cua sandbox create --os linux --size small --region north-america
+python hello.py
```
-Note the sandbox name from the output (e.g., `curious-fox-123`).
+The sandbox is created, used, and destroyed automatically. No pre-provisioning needed.
+
+## 3. Run an Agent
-You can view all your sandboxes:
+To add AI, you need a [Cua account](https://cua.ai/signin) and an API key:
```bash
-cua sandbox list
+pip install cua-cli
+cua auth login # opens browser, saves key locally
```
-## 4. Take a Screenshot (Hello World)
-
-Create a file `hello.py`:
+Then create `agent.py`:
```python
-import os
import asyncio
-from computer import Computer
-
-# Load API key from environment (or set directly)
-os.environ["CUA_API_KEY"] = "sk_cua-api01_..." # or use: cua auth env
-
-computer = Computer(
- os_type="linux",
- provider_type="cloud",
- name="curious-fox-123" # your sandbox name
-)
+from cua_sandbox import Sandbox, Image
+from agent import ComputerAgent
async def main():
- await computer.run() # Connect to the sandbox
-
- try:
- # Take a screenshot
- screenshot = await computer.interface.screenshot()
- screenshot.save("screenshot.png")
- print("Screenshot saved to screenshot.png")
-
- # Click at coordinates (100, 100)
- await computer.interface.left_click(100, 100)
-
- # Type some text
- await computer.interface.type_text("Hello from Cua!")
- finally:
- await computer.disconnect()
+ async with Sandbox.ephemeral(Image.linux()) as sb:
+ agent = ComputerAgent(
+ model="cua/anthropic/claude-sonnet-4-5",
+ tools=[sb],
+ )
+ messages = [{"role": "user", "content": "Open Firefox and go to google.com"}]
+ async for result in agent.run(messages):
+ for item in result["output"]:
+ if item["type"] == "message":
+ print(item["content"][0]["text"])
asyncio.run(main())
```
-Run it:
-
```bash
-python hello.py
+python agent.py
```
-## 5. Run an Agent
+## 4. Watch the Agent Live (Optional)
-Now let's add AI. Create `agent.py`:
+Call `get_display_url(share=True)` to get a shareable browser link to the live desktop — no CLI needed:
```python
-import os
import asyncio
-from computer import Computer
+from cua_sandbox import Sandbox, Image
from agent import ComputerAgent
-os.environ["CUA_API_KEY"] = "sk_cua-api01_..." # or use: cua auth env
-
-computer = Computer(
- os_type="linux",
- provider_type="cloud",
- name="curious-fox-123" # your sandbox name
-)
-
async def main():
- await computer.run()
+ async with Sandbox.ephemeral(Image.linux()) as sb:
+ url = await sb.get_display_url(share=True)
+ print(f"Watch live: {url}") # open this in your browser
- try:
agent = ComputerAgent(
- model="cua/anthropic/claude-sonnet-4.5",
- tools=[computer],
+ model="cua/anthropic/claude-sonnet-4-5",
+ tools=[sb],
)
-
messages = [{"role": "user", "content": "Open Firefox and go to google.com"}]
-
async for result in agent.run(messages):
for item in result["output"]:
if item["type"] == "message":
print(item["content"][0]["text"])
- finally:
- await computer.disconnect()
asyncio.run(main())
```
-Run it:
-
-```bash
-python agent.py
-```
-
-The agent will observe the screen, decide what actions to take, and execute them to complete your task.
+## 5. Clean Up
-## 6. Open the Desktop in Your Browser
-
-Watch your agent work in real-time:
-
-```bash
-cua sandbox vnc curious-fox-123
-```
-
-This opens a browser window showing the sandbox desktop.
-
-## 7. Clean Up
-
-When you're done, stop your sandbox to avoid charges:
+Ephemeral sandboxes delete themselves. For persistent sandboxes:
```bash
-cua sandbox stop curious-fox-123
+cua sb ls # show all running sandboxes
+cua sb delete my-agent-sandbox # delete when done
```
-Or delete it entirely:
-
-```bash
-cua sandbox delete curious-fox-123
-```
-
-## CLI Reference
-
-| Command | Description |
-| -------------------------------------------------------------- | ---------------------------------- |
-| `cua auth login` | Authenticate with your Cua account |
-| `cua auth env` | Export API key to `.env` file |
-| `cua sandbox list` | List all sandboxes |
-| `cua sandbox create --os <os> --size <size> --region <region>` | Create a sandbox |
-| `cua sandbox vnc <name>` | Open sandbox in browser |
-| `cua sandbox start <name>` | Start a stopped sandbox |
-| `cua sandbox stop <name>` | Stop a sandbox |
-| `cua sandbox delete <name>` | Delete a sandbox |
-
## Next Steps
-- [Using the Computer SDK](/cua/guide/get-started/using-computer-sdk) - Learn low-level computer control
-- [Using the Agent SDK](/cua/guide/get-started/using-agent-sdk) - Advanced AI agent configuration
-- [Self-Hosted Sandboxes](/cua/guide/get-started/self-hosted-sandboxes) - Run sandboxes locally with Docker
+- [Sandbox Lifecycle](/cua/guide/sandbox/lifecycle) — ephemeral, persistent, and connect patterns
+- [Images](/cua/guide/sandbox/images) — install packages and configure the environment
+- [Parallel Sandboxes](/cua/guide/sandbox/scale-out) — run multiple agents concurrently
+- [Using the Agent SDK](/cua/guide/get-started/using-agent-sdk) — advanced agent configuration
diff --git a/docs/content/docs/cua/guide/get-started/self-hosted-sandboxes.mdx b/docs/content/docs/cua/guide/get-started/self-hosted-sandboxes.mdx
deleted file mode 100644
index 5c4a8794c7..0000000000
--- a/docs/content/docs/cua/guide/get-started/self-hosted-sandboxes.mdx
+++ /dev/null
@@ -1,308 +0,0 @@
----
-title: Self-Hosted Sandboxes
-description: Run sandboxes locally with Docker, QEMU, or native virtualization
----
-
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
-import { Callout } from 'fumadocs-ui/components/callout';
-
-For development, testing, or air-gapped environments, you can run sandboxes locally instead of using Cua Cloud.
-
-## Options Overview
-
-| Option | OS Support | Requirements | Best For |
-| ------------------- | ----------------------- | ----------------------------- | -------------------------------- |
-| **Docker** | Linux | Docker Desktop/Engine | Local development, fastest setup |
-| **QEMU Docker** | Linux, Windows, Android | Docker + golden image | Testing specific OS versions |
-| **Lume** | macOS | macOS host + Lume CLI | macOS automation |
-| **Windows Sandbox** | Windows | Windows 10 Pro/Enterprise, 11 | Windows automation |
-
-## Linux on Docker (Recommended)
-
-The fastest way to get a local sandbox running.
-
-**1. Install Docker Desktop or Docker Engine**
-
-**2. Pull a Cua Docker image:**
-
-```bash
-# XFCE (Lightweight) - recommended for most use cases
-docker pull --platform=linux/amd64 trycua/cua-xfce:latest
-
-# OR KASM (Full-Featured) - full Ubuntu desktop
-docker pull --platform=linux/amd64 trycua/cua-ubuntu:latest
-```
-
-**3. Connect with Python:**
-
-```python
-from computer import Computer
-import asyncio
-
-computer = Computer(
- os_type="linux",
- provider_type="docker",
- image="trycua/cua-xfce:latest"
-)
-
-async def main():
- await computer.run() # Launch & connect
-
- try:
- screenshot = await computer.interface.screenshot()
- await computer.interface.left_click(100, 100)
- await computer.interface.type_text("Hello!")
- finally:
- await computer.disconnect()
-
-asyncio.run(main())
-```
-
-## QEMU Docker
-
-Run full virtual machines (Linux, Windows, Android) inside Docker containers using QEMU virtualization.
-
-<Callout type="warn">
- Linux and Windows images require a **golden image preparation step** on first use. Android images
- start directly.
-</Callout>
-
-<Tabs items={['Linux', 'Windows', 'Android']}>
- <Tab value="Linux">
-
-**1. Pull the QEMU Linux image:**
-
-```bash
-docker pull trycua/cua-qemu-linux:latest
-```
-
-**2. Download Ubuntu 22.04 LTS Server ISO:**
-
-Download the [Ubuntu 22.04 Server ISO](https://releases.ubuntu.com/22.04/ubuntu-22.04.5-live-server-amd64.iso) (~2GB)
-
-**3. Create golden image:**
-
-```bash
-docker run -it --rm \
- --device=/dev/kvm \
- --cap-add NET_ADMIN \
- --mount type=bind,source=/path/to/ubuntu-22.04.5-live-server-amd64.iso,target=/custom.iso \
- -v ~/cua-storage/linux:/storage \
- -p 8006:8006 \
- -p 5000:5000 \
- -e RAM_SIZE=8G \
- -e CPU_CORES=4 \
- -e DISK_SIZE=64G \
- trycua/cua-qemu-linux:latest
-```
-
-Monitor progress at [http://localhost:8006](http://localhost:8006). The container will install Ubuntu Desktop and shut down when complete.
-
-**4. Connect with Python:**
-
-```python
-from computer import Computer
-import asyncio
-
-computer = Computer(
- os_type="linux",
- provider_type="docker",
- image="trycua/cua-qemu-linux:latest",
- storage="~/cua-storage/linux",
- run_opts={"devices": ["/dev/kvm"]},
-)
-
-async def main():
- await computer.run()
-
- try:
- screenshot = await computer.interface.screenshot()
- await computer.interface.left_click(100, 100)
- finally:
- await computer.disconnect()
-
-asyncio.run(main())
-```
-
- </Tab>
- <Tab value="Windows">
-
-**1. Pull the QEMU Windows image:**
-
-```bash
-docker pull trycua/cua-qemu-windows:latest
-```
-
-**2. Download Windows 11 Enterprise Evaluation ISO:**
-
-- Visit [Microsoft Evaluation Center](https://info.microsoft.com/ww-landing-windows-11-enterprise.html)
-- Download **Windows 11 Enterprise Evaluation (90-day trial)** ISO (~6GB)
-
-**3. Create golden image:**
-
-```bash
-docker run -it --rm \
- --device=/dev/kvm \
- --cap-add NET_ADMIN \
- --mount type=bind,source=/path/to/windows-11-enterprise-eval.iso,target=/custom.iso \
- -v ~/cua-storage/windows:/storage \
- -p 8006:8006 \
- -p 5000:5000 \
- -e RAM_SIZE=8G \
- -e CPU_CORES=4 \
- -e DISK_SIZE=64G \
- trycua/cua-qemu-windows:latest
-```
-
-Monitor progress at [http://localhost:8006](http://localhost:8006). The container will install Windows 11 and shut down when complete.
-
-**4. Connect with Python:**
-
-```python
-from computer import Computer
-import asyncio
-
-computer = Computer(
- os_type="windows",
- provider_type="docker",
- image="trycua/cua-qemu-windows:latest",
- storage="~/cua-storage/windows",
- run_opts={"devices": ["/dev/kvm"]},
-)
-
-async def main():
- await computer.run()
-
- try:
- screenshot = await computer.interface.screenshot()
- await computer.interface.left_click(100, 100)
- finally:
- await computer.disconnect()
-
-asyncio.run(main())
-```
-
- </Tab>
- <Tab value="Android">
-
-No golden image preparation needed.
-
-**1. Pull the QEMU Android image:**
-
-```bash
-docker pull trycua/cua-qemu-android:latest
-```
-
-**2. Connect with Python:**
-
-```python
-from computer import Computer
-import asyncio
-
-computer = Computer(
- os_type="android",
- provider_type="docker",
- image="trycua/cua-qemu-android:latest",
- timeout=150, # Emulator needs more time to boot
- run_opts={
- "devices": ["/dev/kvm"],
- "env": {"EMULATOR_DEVICE": "Samsung Galaxy S10"},
- },
-)
-
-async def main():
- await computer.run()
-
- try:
- screenshot = await computer.interface.screenshot()
- await computer.interface.left_click(100, 100)
- finally:
- await computer.disconnect()
-
-asyncio.run(main())
-```
-
- </Tab>
-</Tabs>
-
-## macOS Sandbox (Lume)
-
-Run native macOS VMs using Apple's Virtualization framework. **macOS host required.**
-
-**1. Install the Lume CLI:**
-
-```bash
-/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
-```
-
-**2. Start a macOS sandbox:**
-
-```bash
-lume run macos-sequoia-cua:latest
-```
-
-**3. Connect with Python:**
-
-```python
-from computer import Computer
-import asyncio
-
-computer = Computer(
- os_type="macos",
- provider_type="lume",
- name="macos-sequoia-cua:latest"
-)
-
-async def main():
- await computer.run()
-
- try:
- screenshot = await computer.interface.screenshot()
- await computer.interface.left_click(100, 100)
- finally:
- await computer.disconnect()
-
-asyncio.run(main())
-```
-
-## Windows Sandbox
-
-Use the native Windows Sandbox feature. **Windows 10 Pro/Enterprise or Windows 11 required.**
-
-**1. Enable Windows Sandbox:**
-
-Follow the [Microsoft guide](https://learn.microsoft.com/en-us/windows/security/application-security/application-isolation/windows-sandbox/windows-sandbox-install) to enable Windows Sandbox.
-
-**2. Install the dependency:**
-
-```bash
-pip install -U git+git://github.com/karkason/pywinsandbox.git
-```
-
-**3. Connect with Python:**
-
-```python
-from computer import Computer
-import asyncio
-
-computer = Computer(
- os_type="windows",
- provider_type="windows_sandbox"
-)
-
-async def main():
- await computer.run()
-
- try:
- screenshot = await computer.interface.screenshot()
- await computer.interface.left_click(100, 100)
- finally:
- await computer.disconnect()
-
-asyncio.run(main())
-```
-
-## Next Steps
-
-- [Using the Computer SDK](/cua/guide/get-started/using-computer-sdk) - Full SDK reference with all sandbox types
-- [Using the Agent SDK](/cua/guide/get-started/using-agent-sdk) - Add AI automation to your sandboxes
diff --git a/docs/content/docs/cua/guide/get-started/using-agent-sdk.mdx b/docs/content/docs/cua/guide/get-started/using-agent-sdk.mdx
index 23c92a0a4a..ea4645552c 100644
--- a/docs/content/docs/cua/guide/get-started/using-agent-sdk.mdx
+++ b/docs/content/docs/cua/guide/get-started/using-agent-sdk.mdx
@@ -6,7 +6,7 @@ description: Add AI automation with vision-language models
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
-Now that you've verified your sandbox works with the Computer SDK, use an Agent to automate complex tasks. The agent interacts with the computer environment using a vision-language model to understand the UI and execute actions.
+Now that you've verified your sandbox works with the Sandbox SDK, use an Agent to automate complex tasks. The agent interacts with the computer environment using a vision-language model to understand the UI and execute actions.
Cua Agent Framework provides:
@@ -49,24 +49,16 @@ Use Cua's inference API to access multiple model providers with a single API key
```python
import os
import asyncio
-from computer import Computer
+from cua_sandbox import Sandbox, Image
from agent import ComputerAgent
os.environ["CUA_API_KEY"] = "sk_cua-api01_..."
-computer = Computer(
- os_type="linux", # or "windows" or "macos"
- provider_type="cloud",
- name="your-sandbox-name" # from CLI or website
-)
-
async def main():
- await computer.run() # Connect to the sandbox
-
- try:
+ async with Sandbox.ephemeral(Image.linux()) as sb:
agent = ComputerAgent(
model="cua/anthropic/claude-sonnet-4.5", # Cua-routed model
- tools=[computer],
+ tools=[sb],
max_trajectory_budget=5.0
)
@@ -76,8 +68,6 @@ async def main():
for item in result["output"]:
if item["type"] == "message":
print(item["content"][0]["text"])
- finally:
- await computer.disconnect()
asyncio.run(main())
```
@@ -109,29 +99,21 @@ asyncio.run(main())
Use your own API keys from model providers like Anthropic, OpenAI, or others.
```python
-import os
import asyncio
-from computer import Computer
+from cua_sandbox import Sandbox, Image
from agent import ComputerAgent
# Set your provider API key
+import os
os.environ["ANTHROPIC_API_KEY"] = "sk-ant-..." # For Anthropic
# OR
os.environ["OPENAI_API_KEY"] = "sk-..." # For OpenAI
-computer = Computer(
- os_type="linux", # or "windows" or "macos"
- provider_type="cloud",
- name="your-sandbox-name" # from CLI or website
-)
-
async def main():
- await computer.run() # Launch & connect to the sandbox
-
- try:
+ async with Sandbox.ephemeral(Image.linux()) as sb:
agent = ComputerAgent(
model="anthropic/claude-sonnet-4-5-20250929", # Direct provider model
- tools=[computer],
+ tools=[sb],
max_trajectory_budget=5.0
)
@@ -141,8 +123,6 @@ async def main():
for item in result["output"]:
if item["type"] == "message":
print(item["content"][0]["text"])
- finally:
- await computer.disconnect()
asyncio.run(main())
```
diff --git a/docs/content/docs/cua/guide/get-started/using-computer-sdk.mdx b/docs/content/docs/cua/guide/get-started/using-computer-sdk.mdx
index 7104db70a9..e1f8429bbf 100644
--- a/docs/content/docs/cua/guide/get-started/using-computer-sdk.mdx
+++ b/docs/content/docs/cua/guide/get-started/using-computer-sdk.mdx
@@ -6,6 +6,10 @@ description: Connect to your sandbox and perform basic interactions
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
+<Callout type="error" title="Deprecated">
+ The Computer SDK (`cua-computer`) is deprecated. New projects should use [`cua-sandbox`](/cua/guide/get-started/using-sandbox-sdk) instead. See the [migration guide](/cua/guide/get-started/migrating-from-computer-sdk) to update existing code.
+</Callout>
+
<Callout type="warn" title="Python Version Compatibility">
Cua packages require **Python 3.12 or 3.13**. Python 3.14 is not currently supported due to
dependency compatibility issues (pydantic-core/PyO3 compatibility). If you encounter build errors
diff --git a/docs/content/docs/cua/guide/get-started/using-sandbox-sdk.mdx b/docs/content/docs/cua/guide/get-started/using-sandbox-sdk.mdx
new file mode 100644
index 0000000000..bdc49423c0
--- /dev/null
+++ b/docs/content/docs/cua/guide/get-started/using-sandbox-sdk.mdx
@@ -0,0 +1,219 @@
+---
+title: Using the Sandbox SDK
+description: Create sandboxes and perform basic interactions with cua-sandbox
+---
+
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+import { Callout } from 'fumadocs-ui/components/callout';
+
+<Callout type="info">
+ **Prerequisites:** Python 3.12 or 3.13 and a free Cua account at [cua.ai](https://cua.ai/signin) for cloud sandboxes.
+</Callout>
+
+The Sandbox SDK (`cua-sandbox`) lets you create and control sandboxes — take screenshots, run shell commands, click, type, and more. Use it to verify your sandbox works before adding AI agents.
+
+## Installation
+
+```bash
+pip install cua-sandbox
+```
+
+Or with uv:
+
+```bash
+uv pip install cua-sandbox
+```
+
+## Create a Sandbox
+
+<Tabs items={['Cloud Container', 'Cloud VM', 'Cloud macOS', 'Cloud Windows', 'Local Docker', 'Local macOS (Lume)']}>
+ <Tab value="Cloud Container">
+ ```python
+ import asyncio
+ from cua_sandbox import Sandbox, Image
+
+ async def main():
+ async with Sandbox.ephemeral(Image.linux()) as sb:
+ result = await sb.shell.run("uname -s")
+ print(result.stdout) # "Linux"
+
+ screenshot = await sb.screenshot()
+ with open("screenshot.png", "wb") as f:
+ f.write(screenshot)
+
+ asyncio.run(main())
+ ```
+ Requires `CUA_API_KEY` environment variable.
+ </Tab>
+ <Tab value="Cloud VM">
+ ```python
+ import asyncio
+ from cua_sandbox import Sandbox, Image
+
+ async def main():
+ async with Sandbox.ephemeral(Image.linux(kind="vm")) as sb:
+ result = await sb.shell.run("uname -s")
+ print(result.stdout) # "Linux"
+
+ screenshot = await sb.screenshot()
+ with open("screenshot.png", "wb") as f:
+ f.write(screenshot)
+
+ asyncio.run(main())
+ ```
+ Requires `CUA_API_KEY` environment variable.
+ </Tab>
+ <Tab value="Cloud macOS">
+ ```python
+ import asyncio
+ from cua_sandbox import Sandbox, Image
+
+ async def main():
+ async with Sandbox.ephemeral(Image.macos()) as sb:
+ result = await sb.shell.run("sw_vers")
+ print(result.stdout)
+
+ screenshot = await sb.screenshot()
+ with open("screenshot.png", "wb") as f:
+ f.write(screenshot)
+
+ asyncio.run(main())
+ ```
+ Requires `CUA_API_KEY` environment variable. Works on any host OS — no Mac needed.
+ </Tab>
+ <Tab value="Cloud Windows">
+ ```python
+ import asyncio
+ from cua_sandbox import Sandbox, Image
+
+ async def main():
+ async with Sandbox.ephemeral(Image.windows()) as sb:
+ result = await sb.shell.run("ver")
+ print(result.stdout)
+
+ screenshot = await sb.screenshot()
+ with open("screenshot.png", "wb") as f:
+ f.write(screenshot)
+
+ asyncio.run(main())
+ ```
+ Requires `CUA_API_KEY` environment variable.
+ </Tab>
+ <Tab value="Local Docker">
+ ```python
+ import asyncio
+ from cua_sandbox import Sandbox, Image
+
+ async def main():
+ async with Sandbox.ephemeral(Image.linux(), local=True) as sb:
+ result = await sb.shell.run("uname -s")
+ print(result.stdout) # "Linux"
+
+ screenshot = await sb.screenshot()
+ with open("screenshot.png", "wb") as f:
+ f.write(screenshot)
+
+ asyncio.run(main())
+ ```
+ Requires Docker. No API key needed.
+ </Tab>
+ <Tab value="Local macOS (Lume)">
+ ```python
+ import asyncio
+ from cua_sandbox import Sandbox, Image
+
+ async def main():
+ async with Sandbox.ephemeral(Image.macos(), local=True) as sb:
+ result = await sb.shell.run("sw_vers")
+ print(result.stdout)
+
+ screenshot = await sb.screenshot()
+ with open("screenshot.png", "wb") as f:
+ f.write(screenshot)
+
+ asyncio.run(main())
+ ```
+ Requires macOS host with [Lume](https://cua.ai/docs/lume) installed.
+ </Tab>
+</Tabs>
+
+## Common Operations
+
+### Shell Commands
+
+```python
+result = await sb.shell.run("echo hello")
+print(result.stdout) # "hello\n"
+print(result.returncode) # 0
+print(result.success) # True
+```
+
+### Screenshots
+
+```python
+png_bytes = await sb.screenshot()
+with open("screenshot.png", "wb") as f:
+ f.write(png_bytes)
+```
+
+### Mouse & Keyboard
+
+```python
+# Click
+await sb.mouse.click(100, 200) # left click
+await sb.mouse.right_click(100, 200) # right click
+await sb.mouse.double_click(100, 200) # double click
+await sb.mouse.move(100, 200) # move without clicking
+await sb.mouse.scroll(100, 200, dy=3) # scroll
+
+# Keyboard
+await sb.keyboard.type("Hello, world!")
+await sb.keyboard.press("Return")
+await sb.keyboard.press("ctrl+c")
+```
+
+## Persistent Sandboxes
+
+For long-running workflows, create a named sandbox instead of ephemeral:
+
+```python
+# Launch via CLI: cua sb launch ubuntu:24.04 --local --json
+# → {"name": "my-sandbox-name", "status": "ready"}
+
+# Connect from Python
+from cua_sandbox import Sandbox
+
+async with Sandbox.connect("my-sandbox-name", local=True) as sb:
+ await sb.shell.run("echo connected")
+```
+
+Or manage the full lifecycle in Python:
+
+```python
+from cua_sandbox import Sandbox, Image
+
+# Create and keep running
+sb = await Sandbox.create(Image.linux(), local=True)
+await sb.shell.run("echo running")
+# ... do more work ...
+await sb.delete()
+```
+
+## Image Types
+
+| Image | Description |
+|-------|-------------|
+| `Image.linux()` | Ubuntu 24.04 container (default) |
+| `Image.linux(kind="vm")` | Ubuntu 24.04 full VM |
+| `Image.macos()` | macOS (latest) |
+| `Image.windows()` | Windows 11 |
+| `Image.from_registry("ghcr.io/...")` | Custom OCI image |
+
+## Next Steps
+
+- [Sandbox Lifecycle](/cua/guide/sandbox/lifecycle) — understand ephemeral, persistent, and connected sandboxes
+- [Images](/cua/guide/sandbox/images) — install packages and customize the environment
+- [Secrets & Environment Variables](/cua/guide/sandbox/secrets) — safely pass credentials into sandboxes
+- [Parallel Sandboxes](/cua/guide/sandbox/scale-out) — run multiple sandboxes concurrently
+- [Using the Agent SDK](/cua/guide/get-started/using-agent-sdk) — add AI automation
+- [Sandbox Interfaces Reference](/cua/reference/sandbox-sdk/interfaces) — full API for `sb.shell`, `sb.mouse`, `sb.tunnel`, `sb.mobile`, and more
diff --git a/docs/content/docs/cua/guide/get-started/what-is-cua.mdx b/docs/content/docs/cua/guide/get-started/what-is-cua.mdx
index 74b0c016f0..be2532209f 100644
--- a/docs/content/docs/cua/guide/get-started/what-is-cua.mdx
+++ b/docs/content/docs/cua/guide/get-started/what-is-cua.mdx
@@ -1,114 +1,98 @@
---
title: What is Cua?
-description: Learn about Cua, the open-source platform for building computer-use agents
+description: Open-source sandboxes and agent framework for computer-use AI
---
-Cua is an open-source platform for building, benchmarking, and deploying agents that can use any computer, with isolated, self-hostable sandboxes (Docker, QEMU, Apple Vz).
-
-<div className="not-prose relative rounded-xl overflow-hidden my-8 w-full">
- <img src="/docs/img/hero.png" alt="Cua" className="w-full h-auto rounded-xl" />
-</div>
-
-## The Cua Stack
-
-Cua consists of three main components:
-
-<div className="not-prose relative rounded-xl overflow-hidden my-8 w-full">
- <img
- src="/docs/img/cua-architecture.png"
- alt="Cua Architecture"
- className="w-full h-auto rounded-xl"
- />
-</div>
-
-### 1. Desktop Sandboxes
-
-Isolated virtual environments where your agents can safely execute tasks:
-
-- **Cloud Sandboxes** - Managed Linux, Windows, and macOS environments hosted by Cua
-- **Local Sandboxes** - Docker containers, QEMU VMs, macOS VMs via Lume, or Windows Sandbox on your own machine
-
-### 2. Computer Framework
-
-A unified SDK for controlling desktop environments programmatically:
-
-- Take screenshots and observe the screen
-- Simulate mouse clicks, movements, and scrolling
-- Type text and press keyboard shortcuts
-- Run code and shell commands
-- Works identically across all sandbox types
+Cua lets you spin up isolated desktop environments — Linux, macOS, Windows, Android — and build agents that can see and control them. One SDK, any OS, cloud or local.
+
+```python
+import asyncio
+from cua_sandbox import Sandbox, Image
+from agent import ComputerAgent
+
+async def main():
+ async with Sandbox.ephemeral(Image.linux(), local=True) as sb:
+ agent = ComputerAgent(
+ model="cua/anthropic/claude-sonnet-4-5",
+ tools=[sb],
+ )
+ async for result in agent.run([{
+ "role": "user",
+ "content": "Open Firefox and search for 'open source computer use'",
+ }]):
+ for item in result["output"]:
+ if item["type"] == "message":
+ print(item["content"][0]["text"])
+
+asyncio.run(main())
+```
-### 3. Agent Framework
+## Install
-Build agents that see screens, click buttons, and complete tasks autonomously:
+```bash
+pip install cua-sandbox "cua-agent[all]"
+```
-- **100+ vision-language model options** through Cua VLM Router or direct provider access
-- **Pre-built agent loops** optimized for computer-use tasks
-- **Composable architecture** for combining grounding and planning models
-- **Built-in telemetry** for monitoring agent performance
+No account needed to run locally with Docker. For cloud sandboxes and hosted models, get a free API key at [cua.ai](https://cua.ai/signin).
-## How Computer-Use Agents Work
+## What it includes
-Computer-use agents operate through a continuous loop:
+**Sandbox SDK** — create and control sandboxes programmatically. Same API everywhere:
-```
-┌─────────────────────────────────────────┐
-│ 1. OBSERVE │
-│ Take a screenshot of the screen │
-└──────────────────┬──────────────────────┘
- │
- ▼
-┌─────────────────────────────────────────┐
-│ 2. UNDERSTAND │
-│ Vision-language model analyzes │
-│ the screenshot and current goal │
-└──────────────────┬──────────────────────┘
- │
- ▼
-┌─────────────────────────────────────────┐
-│ 3. DECIDE │
-│ Determine the next action: │
-│ click, type, scroll, etc. │
-└──────────────────┬──────────────────────┘
- │
- ▼
-┌─────────────────────────────────────────┐
-│ 4. ACT │
-│ Execute the action on the computer │
-└──────────────────┬──────────────────────┘
- │
- ▼
- Loop back to 1
+```python
+async with Sandbox.ephemeral(Image.linux()) as sb: # cloud Linux container
+async with Sandbox.ephemeral(Image.macos()) as sb: # cloud macOS VM
+async with Sandbox.ephemeral(Image.windows()) as sb: # cloud Windows VM
+async with Sandbox.ephemeral(Image.android()) as sb: # cloud Android VM
+async with Sandbox.ephemeral(Image.linux(), local=True) as sb: # local Docker
```
-This cycle repeats until the agent completes its goal or determines it cannot proceed.
-
-## Sandbox Options
+Inside any sandbox:
+
+```python
+await sb.shell.run("npm install") # run shell commands
+await sb.screenshot() # capture the screen
+await sb.mouse.click(x, y) # click
+await sb.keyboard.type("hello") # type
+await sb.keyboard.press("ctrl+c") # key combos
+await sb.mobile.tap(x, y) # Android touch
+async with sb.tunnel.forward(3000) as t: # forward ports
+ print(t.url)
+```
-| Sandbox Type | OS Support | Best For | API Key Required |
-| ------------------- | ----------------------- | ---------------------------- | ---------------- |
-| **Cloud** | Linux, Windows, macOS | Production, teams, CI/CD | Yes |
-| **Docker** | Linux | Local development | No |
-| **QEMU Docker** | Linux, Windows, Android | Testing specific OS versions | No |
-| **Lume (macOS)** | macOS | macOS automation | No |
-| **Windows Sandbox** | Windows | Windows automation | No |
+**Agent SDK** — plug any vision-language model into a computer-use loop:
-## Why Cua?
+```python
+agent = ComputerAgent(
+ model="cua/anthropic/claude-sonnet-4-5", # or openai, gemini, qwen, ...
+ tools=[sb],
+)
+async for result in agent.run(messages): ...
+```
-- **Secure execution** - Run AI coding assistants and computer-use agents in sandboxed environments
-- **Self-hostable** - Deploy locally with Docker, QEMU, or Apple Virtualization
-- **Cross-platform** - Same API across Linux, Windows, and macOS sandboxes
-- **Visual understanding** - Agents see screens, adapt to UI changes, and complete complex tasks
+**Image builder** — configure the environment before the sandbox starts:
+
+```python
+img = (
+ Image.linux()
+ .apt_install("curl", "ffmpeg")
+ .pip_install("playwright")
+ .env(API_KEY="...")
+ .run("playwright install chromium")
+)
+async with Sandbox.ephemeral(img) as sb: ...
+```
-## Use Cases
+## Use cases
-- **AI coding assistants** - Isolated code execution environments for Claude Code, Codex CLI, OpenCode, and other AI coding tools
-- **Computer-use agents** - Build agents that interact with any desktop application autonomously
-- **Workflow automation** - Automate repetitive tasks across any application
-- **Testing** - Run end-to-end tests that interact with real UIs
-- **Benchmarks** - Evaluate agents on OSWorld, ScreenSpot, and other standardized tasks
-- **Research** - Build, evaluate, and train computer-use AI agents
+- **AI coding assistants** — safe isolated environments for Claude Code, Codex, and similar tools
+- **Browser and desktop automation** — agents that interact with any real UI
+- **Cross-platform testing** — run the same test against Linux, macOS, Windows, and Android
+- **Benchmarking** — evaluate agents on OSWorld, ScreenSpot, and custom task sets
-## Getting Started
+## Next
-Ready to build your first agent? Continue to the [Quickstart](/cua/guide/get-started/quickstart) to get a computer-use agent running.
+- [Quickstart](/cua/guide/get-started/quickstart) — running in 5 minutes
+- [Sandbox Lifecycle](/cua/guide/sandbox/lifecycle) — ephemeral, persistent, connect
+- [Images](/cua/guide/sandbox/images) — customizing your environment
+- [Examples](/cua/examples/sandboxes/linux) — runnable samples for every OS
diff --git a/docs/content/docs/cua/guide/integrations/laminar.mdx b/docs/content/docs/cua/guide/integrations/laminar.mdx
index 6571c1afe8..0b3f6ac757 100644
--- a/docs/content/docs/cua/guide/integrations/laminar.mdx
+++ b/docs/content/docs/cua/guide/integrations/laminar.mdx
@@ -24,13 +24,13 @@ import os
import litellm
from agent import ComputerAgent
-from computer import Computer
+from cua_sandbox import Sandbox, Image
from lmnr import Laminar, LaminarLiteLLMCallback # [!code highlight]
Laminar.initialize() # [!code highlight]
litellm.callbacks.append(LaminarLiteLLMCallback()) # [!code highlight]
-computer = Computer(
+computer = await Sandbox.create(
os_type="linux",
provider_type="cloud",
name=os.getenv("CUA_CONTAINER_NAME"),
diff --git a/docs/content/docs/cua/guide/meta.json b/docs/content/docs/cua/guide/meta.json
index 3cbb8bb1c8..ad96f7cce1 100644
--- a/docs/content/docs/cua/guide/meta.json
+++ b/docs/content/docs/cua/guide/meta.json
@@ -2,5 +2,5 @@
"title": "Guide",
"description": "Learn how to build with Cua",
"icon": "Book",
- "pages": ["get-started", "fundamentals", "advanced", "integrations"]
+ "pages": ["get-started", "sandbox", "fundamentals", "advanced", "integrations"]
}
diff --git a/docs/content/docs/cua/guide/sandbox/images.mdx b/docs/content/docs/cua/guide/sandbox/images.mdx
new file mode 100644
index 0000000000..7385191614
--- /dev/null
+++ b/docs/content/docs/cua/guide/sandbox/images.mdx
@@ -0,0 +1,218 @@
+---
+title: Images
+description: Choose and customize the OS image your sandbox runs
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+An `Image` describes the operating system and software environment your sandbox will run. Images are immutable and chainable — each builder method returns a new `Image` value so you can fork and reuse them freely.
+
+## Built-in images
+
+```python
+from cua_sandbox import Image
+
+Image.linux() # Ubuntu 24.04 container (default)
+Image.linux(kind="vm") # Ubuntu 24.04 full VM
+Image.linux("ubuntu", "22.04") # Older Ubuntu
+Image.macos() # macOS Tahoe (latest)
+Image.macos("15") # macOS Sequoia
+Image.windows() # Windows 11
+Image.android() # Android 14
+```
+
+| Image | Kind | Notes |
+|-------|------|-------|
+| `Image.linux()` | container | Fastest startup, Linux only |
+| `Image.linux(kind="vm")` | VM | Full kernel, supports `/dev/kvm` |
+| `Image.macos()` | VM | Apple Virtualization / Lume |
+| `Image.windows()` | VM | QEMU or Hyper-V |
+| `Image.android()` | VM | QEMU Android emulator |
+
+---
+
+## The Image builder
+
+Use the chainable builder to install packages and configure the environment before your sandbox starts. Each method returns a new `Image` — the original is unchanged.
+
+```python
+img = (
+ Image.linux()
+ .apt_install("curl", "git", "ffmpeg")
+ .pip_install("requests", "Pillow")
+ .env(MY_TOKEN="abc123", DEBUG="1")
+ .run("mkdir -p /app/data")
+ .expose(8080)
+)
+
+async with Sandbox.ephemeral(img) as sb:
+ result = await sb.shell.run("curl --version")
+ print(result.stdout)
+```
+
+### Package installation
+
+**Linux — apt**
+
+```python
+Image.linux().apt_install("curl", "git", "build-essential", "ffmpeg")
+```
+
+**macOS — Homebrew**
+
+```python
+Image.macos().brew_install("ffmpeg", "jq")
+```
+
+**Windows — Chocolatey or winget**
+
+```python
+Image.windows().choco_install("nodejs", "git")
+Image.windows().winget_install("Microsoft.VisualStudioCode")
+```
+
+**Android — APK sideloading**
+
+```python
+Image.android().apk_install("/path/to/app.apk")
+```
+
+**Android — PWA (Trusted Web Activity)**
+
+`pwa_install` builds a signed TWA APK from a Web App Manifest URL using [Bubblewrap](https://github.com/GoogleChromeLabs/bubblewrap) and installs it into the emulator. The app opens full-screen with no browser chrome.
+
+```python
+Image.android().pwa_install(
+ "https://example.com/manifest.json",
+ package_name="com.example.myapp", # optional — derived from hostname if omitted
+ keystore="/path/to/android.keystore", # optional — auto-generated if omitted
+ keystore_alias="android", # default: "android"
+ keystore_password="android", # default: "android"
+)
+```
+
+**How signing works.** Chrome will only open the PWA in TWA mode (no browser UI) when the APK's SHA-256 signing certificate matches the fingerprint served by the origin at `/.well-known/assetlinks.json`. To make this reliable across runs:
+
+1. Generate or commit a keystore to your repo.
+2. Extract the SHA-256 fingerprint with `keytool -list -v -keystore android.keystore`.
+3. Serve that fingerprint from `/.well-known/assetlinks.json` on your PWA host.
+4. Pass the keystore path to `pwa_install`.
+
+If you omit `keystore`, a fresh one is generated and cached under `~/.cua/cua-sandbox/pwa-cache/` alongside the built APK — convenient for local development, but the fingerprint will differ between machines.
+
+**System requirements.** Node.js ≥ 18 and Java ≤ 21 must be on `PATH` (Gradle does not support Java 22+). The Android SDK and Bubblewrap CLI are auto-installed on first use.
+
+**Built APKs are cached** by `(manifest_url, package_name)` under `~/.cua/cua-sandbox/pwa-cache/` and reused on subsequent runs.
+
+### Python packages
+
+```python
+Image.linux().pip_install("numpy", "pandas", "playwright")
+
+# or via uv (faster, installs into cua-server project)
+Image.linux().uv_install("numpy", "pandas")
+```
+
+### Environment variables
+
+```python
+Image.linux().env(
+ DATABASE_URL="postgres://localhost/mydb",
+ LOG_LEVEL="debug",
+)
+```
+
+<Callout type="warn">
+Avoid putting real secrets in `.env()` — anyone who can read the `Image` spec can see the values. Use [Secrets](/cua/guide/sandbox/secrets) instead.
+</Callout>
+
+### Shell commands
+
+Run arbitrary shell commands during setup:
+
+```python
+Image.linux().run("curl -fsSL https://deb.nodesource.com/setup_20.x | bash -")
+```
+
+### Copy local files
+
+```python
+Image.linux().copy("./config.json", "/app/config.json")
+```
+
+### Expose ports
+
+Mark ports the sandbox will serve on (used for `sb.tunnel.forward()`):
+
+```python
+Image.linux().expose(8080).expose(5432)
+```
+
+---
+
+## Chaining builder calls
+
+Builder calls are fully composable and can be combined in any order. Each call returns a new `Image`:
+
+```python
+base = Image.linux().apt_install("curl", "git")
+
+# Fork the base for two different use cases
+dev = base.pip_install("ipython", "rich").env(DEBUG="1")
+prod = base.pip_install("gunicorn").run("useradd -m appuser")
+```
+
+---
+
+## Custom OCI images
+
+Pull any image from a public OCI registry:
+
+```python
+Image.from_registry("ghcr.io/trycua/macos-tahoe-cua:latest")
+Image.from_registry("ubuntu:22.04")
+```
+
+You can also chain builder methods on top of a registry image:
+
+```python
+img = Image.from_registry("ubuntu:22.04").apt_install("curl")
+```
+
+---
+
+## Local disk images
+
+Run from a local `.qcow2`, `.vhdx`, `.raw`, or `.iso` file — useful for bring-your-own images or OSWorld tasks:
+
+```python
+Image.from_file("/path/to/disk.qcow2", os_type="linux")
+Image.from_file("/path/to/windows.vhdx", os_type="windows")
+```
+
+URLs are also supported and cached automatically:
+
+```python
+Image.from_file("https://example.com/disk.qcow2", os_type="linux")
+```
+
+Images are cached in `~/.cua/cua-sandbox/image-cache/`.
+
+---
+
+## Inspecting an image
+
+```python
+img = Image.linux().apt_install("curl").pip_install("requests")
+print(img.to_dict())
+# {
+# "os_type": "linux",
+# "distro": "ubuntu",
+# "version": "24.04",
+# "kind": "container",
+# "layers": [
+# {"type": "apt_install", "packages": ["curl"]},
+# {"type": "pip_install", "packages": ["requests"]}
+# ]
+# }
+```
diff --git a/docs/content/docs/cua/guide/sandbox/interactive-shell.mdx b/docs/content/docs/cua/guide/sandbox/interactive-shell.mdx
new file mode 100644
index 0000000000..190216370c
--- /dev/null
+++ b/docs/content/docs/cua/guide/sandbox/interactive-shell.mdx
@@ -0,0 +1,77 @@
+---
+title: Interactive Shell
+description: Open a live PTY session inside a sandbox or local machine from the CLI or Python SDK
+---
+
+The `cua do shell` command and `computer.pty` API give you an interactive terminal (PTY) session inside any sandbox or local machine — similar to SSH, but without any network setup.
+
+## CLI
+
+```bash
+# Switch to a target first
+cua do switch docker my-container
+# or
+cua do switch host
+
+# Open an interactive shell (bash / PowerShell on host)
+cua do shell
+
+# Run a specific program interactively
+cua do shell python3
+cua do shell vim /etc/hosts
+
+# Override terminal dimensions
+cua do shell --cols 220 --rows 50
+```
+
+The shell is fully interactive — arrow keys, tab completion, and `Ctrl+C` all work. When stdin is piped (non-TTY), the command runs non-interactively and its output is printed normally.
+
+## Python SDK
+
+```python
+from cua_sandbox import Sandbox, Image
+
+async with Sandbox.create(provider_type="docker", name="my-container") as c:
+ handle = await c.pty.create(
+ command="bash",
+ cols=80,
+ rows=24,
+ on_data=lambda chunk: print(chunk.decode(errors="replace"), end="", flush=True),
+ )
+
+ await handle.send_stdin(b"echo hello\n")
+ await handle.send_stdin(b"exit\n")
+ code = await handle.wait()
+ print(f"exited {code}")
+```
+
+### PtyHandle methods
+
+| Method | Description |
+|---|---|
+| `send_stdin(data: bytes)` | Write bytes to the terminal's stdin |
+| `resize(cols, rows)` | Resize the terminal window |
+| `kill()` | Kill the session process |
+| `disconnect()` | Close the WebSocket without killing the process |
+| `wait()` | Block until the session exits; returns the exit code |
+
+### Reconnecting
+
+```python
+# Disconnect and reconnect later (process keeps running)
+await handle.disconnect()
+
+handle2 = await c.pty.connect(
+ handle.pid,
+ on_data=lambda chunk: print(chunk.decode(errors="replace"), end=""),
+)
+```
+
+## How it works
+
+The PTY stack has four layers:
+
+1. **`cua-auto`** — spawns a real PTY process (`pty` on Unix, `pywinpty` on Windows)
+2. **`computer-server`** — exposes `/pty` REST endpoints and a WebSocket for I/O
+3. **`computer`** — Python client (`PtyInterface`) connecting over HTTP + WebSocket
+4. **`cua do shell`** — sets your terminal to raw mode and proxies I/O through the WebSocket
diff --git a/docs/content/docs/cua/guide/sandbox/lifecycle.mdx b/docs/content/docs/cua/guide/sandbox/lifecycle.mdx
new file mode 100644
index 0000000000..accc171459
--- /dev/null
+++ b/docs/content/docs/cua/guide/sandbox/lifecycle.mdx
@@ -0,0 +1,146 @@
+---
+title: Sandbox Lifecycle
+description: Understand ephemeral, persistent, and connected sandboxes — and when to use each
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+A sandbox is an isolated virtual environment — a Linux container, macOS VM, Windows VM, or Android emulator — that your code can fully control. The Sandbox SDK gives you three lifecycle patterns depending on how long you need the sandbox to live.
+
+## The three patterns
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ ephemeral create / delete lifecycle in one block │
+│ sandbox is gone when the block exits │
+│ │
+│ create you manage start and stop explicitly │
+│ sandbox persists across process exits │
+│ │
+│ connect attach to an already-running sandbox │
+│ sandbox keeps running after disconnect │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## `Sandbox.ephemeral` — one-shot tasks
+
+Use this for scripts, CI jobs, and any task where you want the sandbox to disappear automatically when you're done. It's an async context manager: the sandbox is created on enter and destroyed on exit, even if an exception is raised.
+
+```python
+import asyncio
+from cua_sandbox import Sandbox, Image
+
+async def main():
+ async with Sandbox.ephemeral(Image.linux()) as sb:
+ result = await sb.shell.run("echo hello")
+ print(result.stdout) # "hello\n"
+ # sandbox is deleted here — no cleanup needed
+
+asyncio.run(main())
+```
+
+**When to use:** scripts, tests, CI pipelines, one-off agent runs, any time you don't need state to survive past the current process.
+
+---
+
+## `Sandbox.create` — persistent sandbox
+
+Use this when you need the sandbox to outlive your Python process, or when you want to reuse it across multiple scripts without re-provisioning.
+
+```python
+import asyncio
+from cua_sandbox import Sandbox, Image
+
+async def main():
+ # Create and get back a handle — sandbox keeps running after this script exits
+ sb = await Sandbox.create(Image.linux(), name="my-dev-sandbox")
+ await sb.shell.run("apt-get install -y vim")
+ await sb.disconnect() # drop the connection; sandbox stays running
+
+asyncio.run(main())
+```
+
+Later, reconnect from any process:
+
+```python
+async with Sandbox.connect("my-dev-sandbox") as sb:
+ result = await sb.shell.run("vim --version")
+ print(result.stdout)
+```
+
+When you're finished with a persistent sandbox, delete it explicitly:
+
+```python
+async with Sandbox.connect("my-dev-sandbox") as sb:
+ await sb.delete()
+```
+
+**When to use:** interactive development, long-running workflows, sandboxes that accumulate installed software or state, multi-step pipelines spread across separate scripts.
+
+---
+
+## `Sandbox.connect` — attach to existing
+
+Use this to attach to any sandbox that's already running, whether you started it from a previous script, the CLI, or another process.
+
+```python
+# Start a sandbox from the CLI
+# $ cua sb launch ubuntu:24.04 --name my-sandbox
+
+# Then connect from Python
+async with Sandbox.connect("my-sandbox") as sb:
+ await sb.shell.run("echo reconnected")
+# connection is dropped, but sandbox keeps running
+```
+
+<Callout type="info">
+`Sandbox.connect` never starts or stops the sandbox — it only manages the network connection. The sandbox continues running after `.disconnect()` or after the `async with` block exits.
+</Callout>
+
+---
+
+## Disconnect vs. Delete
+
+| Method | Effect on sandbox | Use when |
+|--------|------------------|----------|
+| `await sb.disconnect()` | Keeps running | You want to reconnect later |
+| `await sb.delete()` | Permanently destroyed | You're done with it entirely |
+
+Exiting an `ephemeral` context manager calls `delete()` automatically. Exiting a `connect` context manager calls `disconnect()` automatically.
+
+---
+
+## Listing running sandboxes
+
+```python
+sandboxes = await Sandbox.list()
+for info in sandboxes:
+ print(info.name, info.os_type, info.status)
+```
+
+List only local sandboxes:
+
+```python
+sandboxes = await Sandbox.list(local=True)
+```
+
+---
+
+## Cloud vs. local
+
+Every lifecycle pattern works both locally and on Cua Cloud. Pass `local=True` to run on your machine using Docker, Lume, or QEMU.
+
+```python
+# Cloud (default) — requires CUA_API_KEY
+async with Sandbox.ephemeral(Image.linux()) as sb: ...
+
+# Local Docker — no API key needed
+async with Sandbox.ephemeral(Image.linux(), local=True) as sb: ...
+
+# Local macOS VM — requires Lume on macOS
+async with Sandbox.ephemeral(Image.macos(), local=True) as sb: ...
+```
+
+See [Self-Hosted Sandboxes](/cua/guide/get-started/self-hosted-sandboxes) for local setup instructions.
diff --git a/docs/content/docs/cua/guide/sandbox/meta.json b/docs/content/docs/cua/guide/sandbox/meta.json
new file mode 100644
index 0000000000..de4337f2bd
--- /dev/null
+++ b/docs/content/docs/cua/guide/sandbox/meta.json
@@ -0,0 +1,6 @@
+{
+ "title": "Sandbox",
+ "description": "Working with sandboxes",
+ "icon": "Box",
+ "pages": ["lifecycle", "images", "secrets", "scale-out", "interactive-shell", "tunneling"]
+}
diff --git a/docs/content/docs/cua/guide/sandbox/scale-out.mdx b/docs/content/docs/cua/guide/sandbox/scale-out.mdx
new file mode 100644
index 0000000000..41cc8ea059
--- /dev/null
+++ b/docs/content/docs/cua/guide/sandbox/scale-out.mdx
@@ -0,0 +1,173 @@
+---
+title: Parallel Sandboxes
+description: Run multiple sandboxes concurrently to parallelize agent workloads
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+Because `Sandbox.ephemeral` and `Sandbox.create` are async, you can run many sandboxes at the same time using standard Python async patterns. This is useful for parallel scraping, batch testing, multi-agent workflows, and CI/CD pipelines.
+
+## Run N sandboxes concurrently
+
+`asyncio.gather` is the simplest way to run a fixed set of tasks in parallel:
+
+```python
+import asyncio
+from cua_sandbox import Sandbox, Image
+
+async def run_task(task: str) -> str:
+ async with Sandbox.ephemeral(Image.linux()) as sb:
+ result = await sb.shell.run(f"echo '{task}'")
+ return result.stdout.strip()
+
+async def main():
+ tasks = ["task-1", "task-2", "task-3", "task-4"]
+ results = await asyncio.gather(*[run_task(t) for t in tasks])
+ print(results) # ["task-1", "task-2", "task-3", "task-4"]
+
+asyncio.run(main())
+```
+
+## Fan out with a semaphore (rate limiting)
+
+If you have a large batch, use a semaphore to cap the number of sandboxes running at once:
+
+```python
+import asyncio
+from cua_sandbox import Sandbox, Image
+
+MAX_CONCURRENT = 5
+
+async def process_item(sem: asyncio.Semaphore, item: str) -> dict:
+ async with sem:
+ async with Sandbox.ephemeral(Image.linux()) as sb:
+ result = await sb.shell.run(f"python /app/process.py '{item}'")
+ return {"item": item, "output": result.stdout, "ok": result.success}
+
+async def main():
+ items = [f"item-{i}" for i in range(20)]
+ sem = asyncio.Semaphore(MAX_CONCURRENT)
+ results = await asyncio.gather(*[process_item(sem, item) for item in items])
+ print(f"{sum(r['ok'] for r in results)}/{len(results)} succeeded")
+
+asyncio.run(main())
+```
+
+## Producer-consumer with a queue
+
+For dynamic workloads where tasks arrive at runtime, use `asyncio.Queue`:
+
+```python
+import asyncio
+from cua_sandbox import Sandbox, Image
+
+async def worker(queue: asyncio.Queue, worker_id: int):
+ while True:
+ task = await queue.get()
+ if task is None:
+ break
+ async with Sandbox.ephemeral(Image.linux()) as sb:
+ result = await sb.shell.run(task)
+ print(f"[worker-{worker_id}] {result.stdout.strip()}")
+ queue.task_done()
+
+async def main():
+ queue: asyncio.Queue = asyncio.Queue()
+ num_workers = 4
+
+ # Start workers
+ workers = [asyncio.create_task(worker(queue, i)) for i in range(num_workers)]
+
+ # Enqueue tasks
+ for i in range(10):
+ await queue.put(f"echo 'job {i}'")
+
+ # Signal workers to stop
+ for _ in range(num_workers):
+ await queue.put(None)
+
+ await asyncio.gather(*workers)
+
+asyncio.run(main())
+```
+
+## Collecting screenshots in parallel
+
+A common pattern for visual testing — take screenshots across multiple environments simultaneously:
+
+```python
+import asyncio
+from cua_sandbox import Sandbox, Image
+
+async def screenshot_env(image: Image, label: str) -> tuple[str, bytes]:
+ async with Sandbox.ephemeral(image) as sb:
+ await sb.shell.run("sleep 2") # wait for desktop to settle
+ png = await sb.screenshot()
+ return label, png
+
+async def main():
+ envs = [
+ (Image.linux(), "linux"),
+ (Image.linux(kind="vm"), "linux-vm"),
+ (Image.macos(), "macos"),
+ (Image.windows(), "windows"),
+ ]
+ results = await asyncio.gather(*[screenshot_env(img, label) for img, label in envs])
+ for label, png in results:
+ with open(f"screenshot-{label}.png", "wb") as f:
+ f.write(png)
+ print(f"Saved screenshot-{label}.png")
+
+asyncio.run(main())
+```
+
+## Parallel agent runs
+
+Run the same task across multiple sandboxes to compare model outputs or increase throughput:
+
+```python
+import asyncio
+from cua_sandbox import Sandbox, Image
+from agent import ComputerAgent
+
+async def run_agent(task: str, run_id: int) -> dict:
+ async with Sandbox.ephemeral(Image.linux()) as sb:
+ agent = ComputerAgent(
+ model="cua/anthropic/claude-sonnet-4-5",
+ tools=[sb],
+ )
+ messages = [{"role": "user", "content": task}]
+ outputs = []
+ async for result in agent.run(messages):
+ outputs.append(result)
+ return {"run_id": run_id, "steps": len(outputs)}
+
+async def main():
+ task = "Open Firefox and navigate to google.com"
+ runs = await asyncio.gather(*[run_agent(task, i) for i in range(3)])
+ for run in runs:
+ print(f"Run {run['run_id']}: {run['steps']} steps")
+
+asyncio.run(main())
+```
+
+<Callout type="info">
+Cloud sandboxes are billed per second of runtime. Running many sandboxes in parallel will incur charges proportional to wall-clock time × number of sandboxes. Use `local=True` during development to avoid costs.
+</Callout>
+
+## Checking results and handling errors
+
+`asyncio.gather` raises the first exception by default. Use `return_exceptions=True` to collect all results including failures:
+
+```python
+results = await asyncio.gather(
+ *[run_task(t) for t in tasks],
+ return_exceptions=True
+)
+
+for task, result in zip(tasks, results):
+ if isinstance(result, Exception):
+ print(f"{task}: FAILED — {result}")
+ else:
+ print(f"{task}: {result}")
+```
diff --git a/docs/content/docs/cua/guide/sandbox/secrets.mdx b/docs/content/docs/cua/guide/sandbox/secrets.mdx
new file mode 100644
index 0000000000..e7d4673138
--- /dev/null
+++ b/docs/content/docs/cua/guide/sandbox/secrets.mdx
@@ -0,0 +1,130 @@
+---
+title: Secrets & Environment Variables
+description: Pass credentials and configuration into sandboxes without hardcoding values
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+Sandboxes often need credentials — API keys, database URLs, tokens — to perform real work. There are several ways to get those values in safely.
+
+## The `CUA_API_KEY` environment variable
+
+The Sandbox SDK reads your Cua API key from the `CUA_API_KEY` environment variable. Set it in your shell before running scripts:
+
+```bash
+export CUA_API_KEY="sk_cua-..."
+```
+
+Or use a `.env` file with your preferred loader:
+
+```bash
+# .env
+CUA_API_KEY=sk_cua-...
+```
+
+```python
+from dotenv import load_dotenv
+load_dotenv()
+
+from cua_sandbox import Sandbox, Image
+```
+
+You can also pass the key explicitly if you manage it programmatically:
+
+```python
+async with Sandbox.ephemeral(Image.linux(), api_key=my_key) as sb:
+ ...
+```
+
+---
+
+## Passing secrets into the sandbox at runtime
+
+The recommended pattern is to read secrets from the host environment and inject them into the sandbox via `sb.shell.run`, not via `Image.env()`.
+
+```python
+import os
+import asyncio
+from cua_sandbox import Sandbox, Image
+
+async def main():
+ db_url = os.environ["DATABASE_URL"] # read from host
+ gh_token = os.environ["GITHUB_TOKEN"]
+
+ async with Sandbox.ephemeral(Image.linux()) as sb:
+ # Set inside the sandbox for this session only
+ await sb.shell.run(f"export DATABASE_URL='{db_url}'")
+ await sb.shell.run(f"export GITHUB_TOKEN='{gh_token}'")
+ await sb.shell.run("python /app/main.py")
+
+asyncio.run(main())
+```
+
+For multi-command sessions, write a wrapper script instead of exporting in each call:
+
+```python
+script = f"""
+export DATABASE_URL='{db_url}'
+export GITHUB_TOKEN='{gh_token}'
+python /app/main.py
+"""
+result = await sb.shell.run(script)
+```
+
+---
+
+## `Image.env()` — bake-in non-secret config
+
+Use `.env()` on the `Image` builder for configuration that isn't sensitive — feature flags, log levels, app settings:
+
+```python
+from cua_sandbox import Image
+
+img = (
+ Image.linux()
+ .apt_install("python3")
+ .env(
+ LOG_LEVEL="info",
+ APP_ENV="production",
+ PORT="8080",
+ )
+)
+```
+
+<Callout type="warn">
+`.env()` values are stored in the `Image` spec and visible to anyone who can inspect it. Do not use `.env()` for API keys, passwords, or tokens.
+</Callout>
+
+---
+
+## Copying secret files into the sandbox
+
+For credentials stored as files (SSH keys, service account JSON, certificates):
+
+```python
+async with Sandbox.ephemeral(Image.linux()) as sb:
+ # Read the file on the host and write it in the sandbox
+ with open(os.path.expanduser("~/.ssh/id_rsa")) as f:
+ key_content = f.read()
+
+ await sb.shell.run(f"mkdir -p /root/.ssh && chmod 700 /root/.ssh")
+ await sb.shell.run(f"cat > /root/.ssh/id_rsa << 'EOF'\n{key_content}\nEOF")
+ await sb.shell.run("chmod 600 /root/.ssh/id_rsa")
+```
+
+Alternatively, use `Image.copy()` for files that are safe to bake into the image:
+
+```python
+img = Image.linux().copy("./app-config.json", "/app/config.json")
+```
+
+---
+
+## Best practices
+
+| Do | Don't |
+|----|-------|
+| Read secrets from host environment variables | Hardcode secrets in Python source |
+| Inject secrets at runtime via `sb.shell.run` | Store secrets in `Image.env()` |
+| Use `.env` files + `python-dotenv` locally | Commit `.env` files to version control |
+| Use your CI/CD provider's secret manager | Log or print secret values |
diff --git a/docs/content/docs/cua/guide/sandbox/tunneling.mdx b/docs/content/docs/cua/guide/sandbox/tunneling.mdx
new file mode 100644
index 0000000000..b067e6582d
--- /dev/null
+++ b/docs/content/docs/cua/guide/sandbox/tunneling.mdx
@@ -0,0 +1,85 @@
+---
+title: Tunneling
+description: Forward ports and sockets from a sandbox to your local machine
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+`sb.tunnel.forward()` exposes a port (or Android abstract socket) running inside a sandbox on your local host. Useful for hitting a web server, connecting a debugger, or scraping CDP targets from a headless browser.
+
+## Basic usage
+
+```python
+from cua_sandbox import Sandbox, Image
+
+async with Sandbox.ephemeral(Image.linux()) as sb:
+ # Start something inside the sandbox
+ await sb.shell.run("python3 -m http.server 8080 &")
+
+ async with sb.tunnel.forward(8080) as t:
+ print(t.url) # http://localhost:49823
+ print(t.host, t.port) # localhost, 49823
+ # make requests to t.url from your local machine
+```
+
+The tunnel is closed automatically when the `async with` block exits.
+
+## Multiple ports
+
+Pass multiple ports to get a `dict[port, TunnelInfo]`:
+
+```python
+async with sb.tunnel.forward(8080, 9222) as tunnels:
+ app_url = tunnels[8080].url
+ devtools_url = tunnels[9222].url
+```
+
+## Manual close
+
+If you need the tunnel outside a `with` block, `await` it directly and close manually:
+
+```python
+t = await sb.tunnel.forward(8080)
+print(t.url)
+# ... do work ...
+await t.close()
+```
+
+## Android abstract sockets
+
+For Android sandboxes, pass a socket name string instead of a port number:
+
+```python
+async with sb.tunnel.forward("chrome_devtools_remote") as t:
+ # Connect a CDP client to t.url
+ print(t.url) # http://localhost:<random>
+```
+
+<Callout type="info">
+ Abstract socket names are Linux-only (Android). On Linux/macOS sandboxes use integer port numbers.
+</Callout>
+
+## TunnelInfo fields
+
+| Field | Type | Description |
+|---|---|---|
+| `host` | `str` | Always `"localhost"` |
+| `port` | `int` | The host-side port assigned |
+| `sandbox_port` | `int \| str` | The original port/socket inside the sandbox |
+| `url` | `str` | Shorthand `http://{host}:{port}` |
+
+## Chrome DevTools example
+
+Forward the DevTools port from a sandbox browser to use CDP tools locally:
+
+```python
+from cua_sandbox import Sandbox, Image
+
+async with Sandbox.ephemeral(Image.linux()) as sb:
+ await sb.shell.run("google-chrome --remote-debugging-port=9222 --headless &")
+
+ async with sb.tunnel.forward(9222) as t:
+ import httpx
+ targets = httpx.get(f"{t.url}/json").json()
+ print(targets)
+```
diff --git a/docs/content/docs/cua/reference/cli/commands.mdx b/docs/content/docs/cua/reference/cli/commands.mdx
index 40eb9cd2aa..f68dfbe7b1 100644
--- a/docs/content/docs/cua/reference/cli/commands.mdx
+++ b/docs/content/docs/cua/reference/cli/commands.mdx
@@ -4,335 +4,194 @@ description: Complete reference for all Cua CLI commands
---
import { Callout } from 'fumadocs-ui/components/callout';
-import { VersionBadge } from '@/components/version-selector';
-<VersionBadge version="0.1.0" />
+**Package:** `cua-cli` | **Install:** `pip install cua-cli`
-## Overview
+## Command Groups
-The Cua CLI provides commands for authentication, sandbox management, image management, skills recording, and MCP server.
+| Group | Alias | Description |
+|-------|-------|-------------|
+| `cua sandbox` | `cua sb` | Sandbox lifecycle management |
+| `cua auth` | | Authentication |
+| `cua image` | `cua img` | Local image management |
+| `cua skills` | | Skills recording and playback |
+| `cua serve-mcp` | | Start MCP server |
-### Command Groups
-
-| Group | Alias | Description |
-| --------------- | --------- | ---------------------------------- |
-| `cua auth` | | Authentication management |
-| `cua sandbox` | `cua sb` | Sandbox lifecycle management |
-| `cua image` | `cua img` | Cloud image management |
-| `cua skills` | | Skills recording and playback |
-| `cua serve-mcp` | | Start MCP server for AI assistants |
-
-## Authentication Commands
-
-### `cua auth login`
-
-Authenticate with your Cua account.
-
-```bash
-# Browser-based login
-cua auth login
-
-# Direct API key login
-cua auth login --api-key sk_cua-api01_...
-```
-
-### `cua auth env`
-
-Export your API key to a `.env` file in the current directory.
-
-```bash
-cua auth env
-```
-
-### `cua auth logout`
-
-Remove the stored API key.
-
-```bash
-cua auth logout
-```
+---
## Sandbox Commands
-All sandbox commands support the `cua sb` alias (e.g., `cua sb list`).
+All sandbox commands support the `cua sb` alias (e.g. `cua sb launch`).
-### `cua sandbox list`
+### `cua sb launch <image>`
-List all sandboxes.
+Launch a new sandbox. The image is a positional argument; resource specs are options.
```bash
-cua sandbox list
-
-# With JSON output
-cua sandbox list --json
+cua sb launch ubuntu:24.04
+cua sb launch macos
+cua sb launch windows:11
+cua sb launch android:14
-# Show passwords
-cua sandbox list --show-passwords
-```
-
-**Aliases:** `cua sb ls`, `cua sb ps`
+# Local (Docker / Lume / QEMU) — no API key needed
+cua sb launch ubuntu:24.04 --local
+cua sb launch macos --local
-### `cua sandbox create`
+# Specify resources (cloud only)
+cua sb launch ubuntu:24.04 --cpu 4 --memory 8GB --disk 50GB
+cua sb launch ubuntu:24.04 --region europe
-Create a new sandbox.
-
-```bash
-cua sandbox create --os <OS> --size <SIZE> --region <REGION>
+# Give it a name and get JSON output (useful in scripts)
+cua sb launch ubuntu:24.04 --local --name my-sandbox --json
```
-**Required options:**
+**Arguments:**
-| Option | Values |
-| ---------- | ---------------------------------------------------------- |
-| `--os` | `linux`, `windows`, `macos` |
-| `--size` | `small`, `medium`, `large` |
-| `--region` | `north-america`, `europe`, `asia-pacific`, `south-america` |
+| Argument | Description |
+|----------|-------------|
+| `image` | Image to run: `macos`, `ubuntu:24.04`, `windows:11`, `android:14`, or a registry ref like `ghcr.io/org/img:tag` |
-**Example:**
-
-```bash
-cua sandbox create --os linux --size small --region north-america
-```
-
-### `cua sandbox get`
+**Options:**
-Get details for a specific sandbox.
+| Option | Description |
+|--------|-------------|
+| `--local` | Run locally (Docker/Lume/QEMU) instead of Cua Cloud |
+| `--name` | Sandbox name (auto-generated if omitted) |
+| `--vm` | Force VM kind for Linux images (default: container) |
+| `--cpu N` | Number of vCPUs (cloud only) |
+| `--memory SIZE` | Memory — e.g. `8GB`, `4096MB` (cloud only) |
+| `--disk SIZE` | Disk size — e.g. `50GB` (cloud only) |
+| `--region NAME` | Cloud region (cloud only) |
+| `--json` | Output `{"name": "...", "status": "ready"}` |
-```bash
-cua sandbox get <name>
+**Image shorthands:**
-# With options
-cua sandbox get <name> --json
-cua sandbox get <name> --show-passwords
-cua sandbox get <name> --show-vnc-url
-```
+| String | Resolves to |
+|--------|-------------|
+| `macos` | `Image.macos("26")` |
+| `macos:sequoia` | `Image.macos("sequoia")` |
+| `ubuntu:24.04` | `Image.linux("ubuntu", "24.04")` |
+| `linux` | `Image.linux("ubuntu", "24.04")` |
+| `windows:11` | `Image.windows("11")` |
+| `android:14` | `Image.android("14")` |
+| `ghcr.io/org/img` | `Image.from_registry("ghcr.io/org/img")` |
-### `cua sandbox start`
+### `cua sb ls`
-Start a stopped sandbox.
+List running sandboxes.
```bash
-cua sandbox start <name>
+cua sb ls # cloud sandboxes (requires API key)
+cua sb ls --local # local sandboxes only
+cua sb ls --all # both cloud and local
+cua sb ls --json # JSON output
```
-### `cua sandbox stop`
-
-Stop a running sandbox.
-
-```bash
-cua sandbox stop <name>
-```
+Aliases: `cua sb list`
-### `cua sandbox restart`
+### `cua sb info <name>`
-Restart a sandbox.
+Get details for a sandbox.
```bash
-cua sandbox restart <name>
+cua sb info my-sandbox
+cua sb info my-sandbox --local
+cua sb info my-sandbox --json
```
-### `cua sandbox suspend`
-
-Suspend a sandbox (preserves memory state).
-
-```bash
-cua sandbox suspend <name>
-```
+Alias: `cua sb get <name>`
-### `cua sandbox delete`
+### `cua sb delete <name>`
Delete a sandbox permanently.
```bash
-cua sandbox delete <name>
+cua sb delete my-sandbox
+cua sb delete my-sandbox --local
+cua sb delete my-sandbox --force # skip confirmation
```
<Callout type="warn">
- This action is irreversible. All data on the sandbox will be permanently lost.
+ Irreversible. All data on the sandbox is permanently lost.
</Callout>
-### `cua sandbox vnc`
+### `cua sb vnc <name>`
Open the sandbox desktop in your browser.
```bash
-cua sandbox vnc <name>
+cua sb vnc my-sandbox
+cua sb vnc my-sandbox --local
```
-**Alias:** `cua sb open <name>`
+### `cua sb shell <name>`
-## Image Commands
-
-All image commands support the `cua img` alias.
-
-### `cua image list`
-
-List cloud images.
+Open an interactive shell session.
```bash
-cua image list
+cua sb shell my-sandbox
+cua sb shell my-sandbox --local
-# JSON output
-cua image list --json
-
-# List local images instead
-cua image list --local
+# Run a single command
+cua sb shell my-sandbox ls -la /
+cua sb shell my-sandbox --cols 120 --rows 40
```
-**Alias:** `cua img ls`
-
-### `cua image push`
+### `cua sb exec <name> <command>`
-Upload a local image to the cloud.
+Execute a command non-interactively (useful for scripts).
```bash
-cua image push <name> --file <path> --tag <tag>
+cua sb exec my-sandbox echo hello
+cua sb exec my-sandbox --json uname -a
```
-### `cua image pull`
+### `cua sb suspend <name>` / `cua sb resume <name>`
-Download an image from the cloud.
+Suspend a sandbox (preserves memory state) and resume it.
```bash
-cua image pull <name> --tag <tag> --output <path>
+cua sb suspend my-sandbox
+cua sb resume my-sandbox
```
-### `cua image delete`
-
-Delete a cloud image.
+### `cua sb restart <name>`
-```bash
-cua image delete <name> --tag <tag>
-
-# Skip confirmation
-cua image delete <name> --tag <tag> --force
-```
-
-## Skills Commands
-
-Skills are recorded demonstrations that guide agent behavior.
-
-### `cua skills list`
-
-List all saved skills.
-
-```bash
-cua skills list
-
-# JSON output
-cua skills list --json
-```
-
-### `cua skills record`
-
-Record a new skill from a sandbox.
-
-```bash
-cua skills record --sandbox <name>
-
-# With options
-cua skills record --sandbox <name> --name "my-skill" --description "Does something"
-cua skills record --sandbox <name> --provider anthropic --model claude-sonnet-4-5-20250514
-```
-
-**Options:**
-
-| Option | Description |
-| --------------- | --------------------------------------------------- |
-| `--sandbox` | Sandbox to record from |
-| `--name` | Skill name (skips prompt) |
-| `--description` | Skill description (skips prompt) |
-| `--provider` | LLM provider for captioning (`anthropic`, `openai`) |
-| `--model` | Model to use for captioning |
-
-### `cua skills read`
-
-Display a skill's instructions.
+Restart a sandbox.
```bash
-cua skills read <name>
-
-# JSON format with trajectory data
-cua skills read <name> --format json
+cua sb restart my-sandbox
```
-### `cua skills replay`
-
-Open the recorded video for a skill.
-
-```bash
-cua skills replay <name>
-```
+---
-### `cua skills delete`
+## Authentication Commands
-Delete a skill.
+### `cua auth login`
```bash
-cua skills delete <name>
+cua auth login # browser-based OAuth
+cua auth login --api-key sk_cua-... # direct API key
```
-### `cua skills clean`
+### `cua auth env`
-Delete all skills (with confirmation).
+Write `CUA_API_KEY` to a `.env` file in the current directory.
```bash
-cua skills clean
+cua auth env
```
-## MCP Server
-
-Run the CLI as an MCP (Model Context Protocol) server for AI assistants like Claude.
-
-### `cua serve-mcp`
-
-Start the MCP server.
+### `cua auth logout`
```bash
-cua serve-mcp
-
-# With specific sandbox
-cua serve-mcp --sandbox <name>
-
-# With permission restrictions
-cua serve-mcp --permissions sandbox:readonly
+cua auth logout
```
-**Options:**
-
-| Option | Description |
-| --------------- | ------------------------------------- |
-| `--sandbox` | Default sandbox for computer commands |
-| `--permissions` | Permission groups (see below) |
-
-**Permission groups:**
-
-| Group | Description |
-| ------------------- | ---------------------------- |
-| `all` | All permissions (default) |
-| `sandbox:all` | Full sandbox management |
-| `sandbox:readonly` | List and view sandboxes only |
-| `computer:all` | Full computer control |
-| `computer:readonly` | Screenshots only |
-| `skills:all` | Full skills management |
-| `skills:readonly` | List and read skills only |
-
-**Example with multiple permissions:**
-
-```bash
-cua serve-mcp --permissions "sandbox:all,computer:readonly,skills:list"
-```
+---
## Environment Variables
-| Variable | Description |
-| --------------------- | -------------------------- |
-| `CUA_API_KEY` | API key for authentication |
-| `CUA_SANDBOX` | Default sandbox name |
-| `CUA_MCP_PERMISSIONS` | Default MCP permissions |
-
-## Next Steps
-
-- [Quickstart Guide](/cua/guide/get-started/quickstart)
-- [Computer SDK Reference](/cua/reference/computer-sdk)
-- [Agent SDK Reference](/cua/reference/agent-sdk)
+| Variable | Description |
+|----------|-------------|
+| `CUA_API_KEY` | API key for cloud authentication |
diff --git a/docs/content/docs/cua/reference/meta.json b/docs/content/docs/cua/reference/meta.json
index f2222bec5d..1c6f97e05d 100644
--- a/docs/content/docs/cua/reference/meta.json
+++ b/docs/content/docs/cua/reference/meta.json
@@ -2,5 +2,5 @@
"title": "Reference",
"description": "SDK and CLI API reference",
"icon": "FileText",
- "pages": ["desktop-sandbox", "computer-sdk", "agent-sdk", "cli"]
+ "pages": ["desktop-sandbox", "sandbox-sdk", "agent-sdk", "cli"]
}
diff --git a/docs/content/docs/cua/reference/sandbox-sdk/index.mdx b/docs/content/docs/cua/reference/sandbox-sdk/index.mdx
new file mode 100644
index 0000000000..4f8f39af93
--- /dev/null
+++ b/docs/content/docs/cua/reference/sandbox-sdk/index.mdx
@@ -0,0 +1,2871 @@
+---
+title: Sandbox SDK API Reference
+description: Python API reference for cua-sandbox — creating and controlling sandboxes
+---
+
+{/*
+ AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
+ Generated by: npx tsx scripts/docs-generators/python-sdk.ts
+ Source: libs/python/cua-sandbox/cua_sandbox
+ Version: 0.1.0
+*/}
+
+import { Callout } from 'fumadocs-ui/components/callout';
+import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
+import { VersionHeader } from '@/components/version-selector';
+
+<VersionHeader
+ versions={[{"version":"0.1","href":"/cua/reference/sandbox-sdk","isCurrent":true}]}
+ currentVersion="0.1"
+ fullVersion="0.1.0"
+ packageName="cua-sandbox"
+/>
+
+cua-sandbox — ephemeral and persistent sandboxed computer environments.
+
+Usage::
+
+ import cua_sandbox as cua
+
+ # Configure API access
+ cua.configure(api_key="sk-...")
+
+ # Local sandbox
+ async with cua.sandbox(local=True) as sb:
+ await sb.screenshot()
+
+ # Localhost (no sandbox, direct host control)
+ async with cua.localhost() as host:
+ await host.mouse.click(100, 200)
+
+## Classes
+
+| Class | Description |
+|-------|-------------|
+| [`Image`](#image) | Immutable, chainable image specification. |
+| [`Localhost`](#localhost) | Direct host control via cua_auto — no sandboxing. |
+| [`Sandbox`](#sandbox) | A sandboxed computer environment. |
+| [`SandboxInfo`](#sandboxinfo) | Metadata for a local or cloud sandbox. |
+| [`CloudTransport`](#cloudtransport) | Transport that provisions / connects to a CUA cloud VM. |
+
+## Functions
+
+| Function | Description |
+|----------|-------------|
+| [`login`](#login) | Open the CUA login page in a browser and store credentials. |
+| [`whoami`](#whoami) | Return info about the authenticated user. |
+| [`configure`](#configure) | Set global configuration for the CUA SDK. |
+
+---
+
+## Image
+
+Immutable, chainable image specification.
+
+Each mutation method returns a new Image instance so that builders
+can be forked at any point.
+
+### Constructor
+
+```python
+Image(self, os_type: str, distro: str, version: str, kind: Optional[str] = None, _layers: Tuple[Dict[str, Any], ...] = (), _env: Tuple[Tuple[str, str], ...] = (), _ports: Tuple[int, ...] = (), _files: Tuple[Tuple[str, str], ...] = (), _registry: Optional[str] = None, _disk_path: Optional[str] = None, _agent_type: Optional[str] = None) -> None
+```
+
+### Attributes
+
+| Name | Type | Description |
+|------|------|-------------|
+| `os_type` | `str` | |
+| `distro` | `str` | |
+| `version` | `str` | |
+| `kind` | `Optional[str]` | |
+
+### Methods
+
+#### Image.linux
+
+```python
+def linux(cls, distro: str = 'ubuntu', version: str = '24.04', kind: str = 'container') -> Image
+```
+
+Linux image. Defaults to 'container' (Docker/XFCE). Use kind='vm' for QEMU.
+
+#### Image.macos
+
+```python
+def macos(cls, version: str = '26', kind: str = 'vm') -> Image
+```
+
+macOS image. Always a VM (Apple Virtualization / Lume).
+
+Supported versions: ``"15"`` / ``"sequoia"``, ``"26"`` / ``"tahoe"``.
+
+#### Image.windows
+
+```python
+def windows(cls, version: str = '11', kind: str = 'vm') -> Image
+```
+
+Windows image. Always a VM (QEMU or Hyper-V).
+
+#### Image.android
+
+```python
+def android(cls, version: str = '14', kind: str = 'vm') -> Image
+```
+
+Android image. Always a VM (QEMU emulator).
+
+#### Image.from_registry
+
+```python
+def from_registry(cls, ref: str) -> Image
+```
+
+Create an image from a registry reference. kind is resolved after pull.
+
+#### Image.from_file
+
+```python
+def from_file(cls, path: str, os_type: str = 'windows', kind: str = 'vm', agent_type: Optional[str] = None) -> Image
+```
+
+Create an image from a local disk, ISO file, or URL.
+
+Supported formats: qcow2, vhdx, raw, img, iso.
+URLs (http/https) are downloaded automatically. Zip files are extracted.
+For ISOs, the runtime will create a qcow2 disk and attach the ISO
+as a CD-ROM for installation/boot.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `path` | `Any` | Local file path or URL (http/https). |
+| `os_type` | `Any` | OS type hint ("linux", "windows", "macos", "android"). |
+| `kind` | `Any` | "vm" or "container". |
+| `agent_type` | `Any` | Agent type hint (e.g. "osworld" for OSWorld Flask server). |
+
+#### Image.from_dict
+
+```python
+def from_dict(cls, data: Dict[str, Any]) -> Image
+```
+
+Reconstruct an Image from a serialized spec dict.
+
+#### Image.apt_install
+
+```python
+def apt_install(self, packages: str = ()) -> Image
+```
+
+Install packages via apt (Linux only).
+
+#### Image.brew_install
+
+```python
+def brew_install(self, packages: str = ()) -> Image
+```
+
+Install packages via Homebrew (macOS).
+
+#### Image.choco_install
+
+```python
+def choco_install(self, packages: str = ()) -> Image
+```
+
+Install packages via Chocolatey (Windows).
+
+#### Image.winget_install
+
+```python
+def winget_install(self, packages: str = ()) -> Image
+```
+
+Install packages via winget (Windows).
+
+#### Image.apk_install
+
+```python
+def apk_install(self, apk_paths: str = ()) -> Image
+```
+
+Install APK files via adb (Android only).
+
+#### Image.pwa_install
+
+```python
+def pwa_install(self, manifest_url: str, package_name: Optional[str] = None, keystore: Optional[str] = None, keystore_alias: str = 'android', keystore_password: str = 'android') -> 'Image'
+```
+
+Build an APK from a PWA manifest URL via Bubblewrap and install it (Android only).
+
+Bubblewrap reads the Web App Manifest at *manifest_url*, generates a
+Trusted Web Activity (TWA) APK signed with *keystore*, and installs it
+via adb. The keystore's SHA-256 fingerprint must match what the server
+serves from ``/.well-known/assetlinks.json`` so Chrome trusts the TWA
+and skips the browser UI entirely.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `manifest_url` | `Any` | Full URL to the PWA's ``manifest.json``. |
+
+**Example:**
+
+```python
+package_name: Android package ID. Defaults to a reversed-hostname
+ derivation (e.g. ``"com.example.app"``).
+keystore: Path to a ``*.keystore`` / ``*.jks`` file. When
+ omitted a fresh keystore is generated and cached under
+ ``~/.cua/cua-sandbox/pwa-cache/``. Pass the keystore
+ bundled with your PWA repo so the fingerprint is
+ deterministic and pre-loaded into ``assetlinks.json``.
+keystore_alias: Key alias inside the keystore (default ``"android"``).
+keystore_password: Password for both the store and the key
+ (default ``"android"``).
+```
+
+#### Image.uv_install
+
+```python
+def uv_install(self, packages: str = ()) -> Image
+```
+
+Install Python packages via uv add into the cua-server project.
+
+#### Image.pip_install
+
+```python
+def pip_install(self, packages: str = ()) -> Image
+```
+
+Install Python packages via pip.
+
+#### Image.run
+
+```python
+def run(self, command: str) -> Image
+```
+
+Run a shell command during image build.
+
+#### Image.env
+
+```python
+def env(self, variables: str = {}) -> Image
+```
+
+Set environment variables.
+
+#### Image.copy
+
+```python
+def copy(self, src: str, dst: str) -> Image
+```
+
+Copy a file into the image.
+
+#### Image.expose
+
+```python
+def expose(self, port: int) -> Image
+```
+
+Expose a port.
+
+#### Image.to_dict
+
+```python
+def to_dict(self) -> Dict[str, Any]
+```
+
+Serialize to a plain dict suitable for JSON or cloud API.
+
+#### Image.to_cloud_init
+
+```python
+def to_cloud_init(self) -> str
+```
+
+Generate a cloud-init user-data script from the image layers.
+
+---
+
+## Localhost
+
+Direct host control via cua_auto — no sandboxing.
+
+### Constructor
+
+```python
+Localhost(self) -> None
+```
+
+### Attributes
+
+| Name | Type | Description |
+|------|------|-------------|
+| `screen` | `Any` | |
+| `mouse` | `Any` | |
+| `keyboard` | `Any` | |
+| `clipboard` | `Any` | |
+| `shell` | `Any` | |
+| `window` | `Any` | |
+| `terminal` | `Any` | |
+
+### Methods
+
+#### Localhost.disconnect
+
+```python
+async def disconnect(self) -> None
+```
+
+#### Localhost.screenshot
+
+```python
+async def screenshot(self, text: Optional[str] = None) -> bytes
+```
+
+#### Localhost.screenshot_base64
+
+```python
+async def screenshot_base64(self, text: Optional[str] = None) -> str
+```
+
+#### Localhost.get_environment
+
+```python
+async def get_environment(self) -> str
+```
+
+#### Localhost.get_dimensions
+
+```python
+async def get_dimensions(self) -> tuple[int, int]
+```
+
+#### Localhost.connect
+
+```python
+def connect(cls) -> '_ConnectResult'
+```
+
+Connect to the local machine.
+
+Supports both ``await`` and ``async with``.
+
+**Example:**
+
+```python
+# plain await
+host = await Localhost.connect()
+await host.shell.run("echo hello")
+await host.disconnect()
+
+# context manager
+async with Localhost.connect() as host:
+ await host.shell.run("echo hello")
+```
+
+---
+
+## Sandbox
+
+A sandboxed computer environment.
+
+Provides programmatic control of a VM or container through a unified
+interface: ``.mouse``, ``.keyboard``, ``.screen``, ``.clipboard``,
+``.shell``, ``.window``, and ``.terminal``.
+
+Sandboxes are always isolated — they never control the host machine
+directly. For unsandboxed host control, use :func:`cua_sandbox.localhost`.
+
+There are three ways to obtain a Sandbox:
+
+1. **Persistent** — provision and keep alive after the script exits::
+
+ sb = await Sandbox.create(Image.desktop("ubuntu"))
+ await sb.shell.run("whoami")
+ await sb.disconnect()
+
+2. **Connect** — attach to an already-running sandbox by name::
+
+ sb = await Sandbox.connect("my-sandbox")
+ await sb.screenshot()
+ await sb.disconnect()
+
+3. **Ephemeral** — auto-destroyed when the ``async with`` block exits::
+
+ async with Sandbox.ephemeral(Image.desktop("ubuntu")) as sb:
+ await sb.shell.run("whoami")
+
+### Constructor
+
+```python
+Sandbox(self, transport: Transport, name: Optional[str] = None, _runtime: Optional[Runtime] = None, _runtime_info: Optional[RuntimeInfo] = None, _ephemeral: Optional[bool] = None)
+```
+
+### Attributes
+
+| Name | Type | Description |
+|------|------|-------------|
+| `name` | `Any` | |
+| `screen` | `Any` | |
+| `mouse` | `Any` | |
+| `keyboard` | `Any` | |
+| `clipboard` | `Any` | |
+| `shell` | `Any` | |
+| `window` | `Any` | |
+| `terminal` | `Any` | |
+| `mobile` | `Any` | |
+| `tunnel` | `Any` | |
+
+### Methods
+
+#### Sandbox.disconnect
+
+```python
+async def disconnect(self) -> None
+```
+
+Drop the transport connection. The sandbox keeps running.
+
+#### Sandbox.destroy
+
+```python
+async def destroy(self) -> None
+```
+
+Disconnect and permanently delete the sandbox (VM/container).
+
+#### Sandbox.screenshot
+
+```python
+async def screenshot(self, text: Optional[str] = None, format: str = 'png', quality: int = 95) -> bytes
+```
+
+#### Sandbox.screenshot_base64
+
+```python
+async def screenshot_base64(self, text: Optional[str] = None, format: str = 'png', quality: int = 95) -> str
+```
+
+#### Sandbox.get_environment
+
+```python
+async def get_environment(self) -> str
+```
+
+#### Sandbox.get_display_url
+
+```python
+async def get_display_url(self, share: bool = False) -> str
+```
+
+Return a URL to view this sandbox's display.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `share` | `Any` | If True, return a public link with embedded credentials (cloud only). If False, return a direct connection URL. |
+
+#### Sandbox.get_dimensions
+
+```python
+async def get_dimensions(self) -> tuple[int, int]
+```
+
+#### Sandbox.create
+
+```python
+async def create(cls, image: Image, name: Optional[str] = None, api_key: Optional[str] = None, local: bool = False, runtime: Optional['Runtime'] = None, cpu: Optional[int] = None, memory_mb: Optional[int] = None, disk_gb: Optional[int] = None, region: str = 'us-east-1') -> 'Sandbox'
+```
+
+Provision a new persistent sandbox and return it connected.
+
+The sandbox is kept alive after your script exits — call ``close()``
+when you are done, or use :meth:`ephemeral` if you want it destroyed
+automatically.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `image` | `Any` | Image to run (e.g. ``Image.desktop("ubuntu")``). |
+| `name` | `Any` | Optional name to assign to the sandbox. |
+| `api_key` | `Any` | CUA API key for cloud sandboxes. |
+| `local` | `Any` | Use a local runtime instead of cloud. |
+| `runtime` | `Any` | Explicit runtime backend (DockerRuntime, QEMURuntime, etc.). |
+| `cpu` | `Any` | Number of CPUs for the cloud sandbox. |
+| `memory_mb` | `Any` | Memory in MB for the cloud sandbox. |
+| `disk_gb` | `Any` | Disk size in GB for the cloud sandbox. |
+| `region` | `Any` | Cloud region (default ``"us-east-1"``). |
+
+**Example:**
+
+```python
+sb = await Sandbox.create(Image.desktop("ubuntu"))
+await sb.shell.run("uname -a")
+print(sb.name) # save to reconnect later
+await sb.disconnect()
+```
+
+#### Sandbox.connect
+
+```python
+def connect(cls, name: str, api_key: Optional[str] = None, local: bool = False, ws_url: Optional[str] = None, http_url: Optional[str] = None, container_name: Optional[str] = None, cpu: Optional[int] = None, memory_mb: Optional[int] = None, disk_gb: Optional[int] = None, region: str = 'us-east-1') -> '_ConnectResult'
+```
+
+Connect to an existing sandbox by name.
+
+Supports both ``await`` and ``async with``. When used as a context
+manager, ``disconnect()`` is called on exit — the sandbox keeps running.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `name` | `Any` | Name of the existing sandbox. |
+| `api_key` | `Any` | CUA API key for cloud sandboxes. |
+| `ws_url` | `Any` | WebSocket URL for a remote computer-server. |
+| `http_url` | `Any` | HTTP base URL for a remote computer-server. |
+| `container_name` | `Any` | Container name for cloud auth (HTTP transport). |
+| `region` | `Any` | Cloud region (default ``"us-east-1"``). |
+
+**Example:**
+
+```python
+# plain await
+sb = await Sandbox.connect("my-sandbox")
+await sb.screenshot()
+await sb.disconnect()
+
+# context manager — disconnects on exit, sandbox keeps running
+async with Sandbox.connect("my-sandbox") as sb:
+ await sb.screenshot()
+```
+
+#### Sandbox.ephemeral
+
+```python
+async def ephemeral(cls, image: Image, name: Optional[str] = None, api_key: Optional[str] = None, local: bool = False, runtime: Optional['Runtime'] = None, cpu: Optional[int] = None, memory_mb: Optional[int] = None, disk_gb: Optional[int] = None, region: str = 'us-east-1') -> AsyncIterator['Sandbox']
+```
+
+Create an ephemeral sandbox that is automatically destroyed on exit.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `image` | `Any` | Image to run (e.g. ``Image.desktop("ubuntu")``). |
+| `name` | `Any` | Optional name to assign to the sandbox. |
+| `api_key` | `Any` | CUA API key for cloud sandboxes. |
+| `local` | `Any` | Use a local runtime instead of cloud. |
+| `runtime` | `Any` | Explicit runtime backend (DockerRuntime, QEMURuntime, etc.). |
+| `cpu` | `Any` | Number of CPUs for the cloud sandbox. |
+| `memory_mb` | `Any` | Memory in MB for the cloud sandbox. |
+| `disk_gb` | `Any` | Disk size in GB for the cloud sandbox. |
+| `region` | `Any` | Cloud region (default ``"us-east-1"``). |
+
+**Example:**
+
+```python
+async with Sandbox.ephemeral(Image.desktop("ubuntu")) as sb:
+ await sb.shell.run("whoami")
+# sandbox is destroyed here
+```
+
+#### Sandbox.list
+
+```python
+async def list(cls, local: bool = False, api_key: Optional[str] = None) -> 'list[SandboxInfo]'
+```
+
+List running and suspended sandboxes.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `local` | `Any` | If True, list local sandboxes (Lume, Docker, QEMU). If False, list cloud sandboxes. |
+| `api_key` | `Any` | CUA API key for cloud sandboxes. |
+
+#### Sandbox.get_info
+
+```python
+async def get_info(cls, name: str, local: bool = False, api_key: Optional[str] = None) -> 'SandboxInfo'
+```
+
+Get metadata for a specific sandbox.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `name` | `Any` | Sandbox name. |
+| `local` | `Any` | If True, look up in local runtimes. |
+| `api_key` | `Any` | CUA API key for cloud. |
+
+#### Sandbox.suspend
+
+```python
+async def suspend(cls, name: str, local: bool = False, api_key: Optional[str] = None) -> None
+```
+
+Suspend a running sandbox (save state).
+
+For local QEMU bare-metal: saves a QMP snapshot then quits the process.
+For local Docker/QEMU-docker: pauses the container.
+For local Lume: stops the Lume VM (Lume persists state).
+For cloud: calls POST /v1/vms/\{name\}/stop.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `name` | `Any` | Sandbox name. |
+| `local` | `Any` | If True, operate on a local sandbox. |
+| `api_key` | `Any` | CUA API key for cloud. |
+
+#### Sandbox.resume
+
+```python
+async def resume(cls, name: str, local: bool = False, api_key: Optional[str] = None) -> 'Sandbox'
+```
+
+Resume a suspended sandbox and return a connected Sandbox.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `name` | `Any` | Sandbox name. |
+| `local` | `Any` | If True, resume a local sandbox. |
+| `api_key` | `Any` | CUA API key for cloud. |
+
+**Returns:** A connected Sandbox ready to use.
+
+#### Sandbox.restart
+
+```python
+async def restart(cls, name: str, local: bool = False, api_key: Optional[str] = None) -> 'Sandbox'
+```
+
+Restart a sandbox (suspend then resume) and return a connected Sandbox.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `name` | `Any` | Sandbox name. |
+| `local` | `Any` | If True, restart a local sandbox. |
+| `api_key` | `Any` | CUA API key for cloud. |
+
+**Returns:** A connected Sandbox ready to use.
+
+#### Sandbox.delete
+
+```python
+async def delete(cls, name: str, local: bool = False, api_key: Optional[str] = None) -> None
+```
+
+Permanently delete a sandbox.
+
+For local sandboxes, stops the VM and removes the state file.
+For cloud sandboxes, calls DELETE /v1/vms/\{name\}.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `name` | `Any` | Sandbox name. |
+| `local` | `Any` | If True, delete a local sandbox. |
+| `api_key` | `Any` | CUA API key for cloud. |
+
+---
+
+## SandboxInfo
+
+Metadata for a local or cloud sandbox.
+
+### Constructor
+
+```python
+SandboxInfo(self, name: str, status: str, source: str, os_type: Optional[str] = None, host: Optional[str] = None, vnc_url: Optional[str] = None, api_url: Optional[str] = None, created_at: Optional[str] = None) -> None
+```
+
+### Attributes
+
+| Name | Type | Description |
+|------|------|-------------|
+| `name` | `str` | |
+| `status` | `str` | |
+| `source` | `str` | |
+| `os_type` | `Optional[str]` | |
+| `host` | `Optional[str]` | |
+| `vnc_url` | `Optional[str]` | |
+| `api_url` | `Optional[str]` | |
+| `created_at` | `Optional[str]` | |
+
+---
+
+## CloudTransport
+
+*Inherits from: Transport*
+
+Transport that provisions / connects to a CUA cloud VM.
+
+### Constructor
+
+```python
+CloudTransport(self, name: Optional[str] = None, api_key: Optional[str] = None, base_url: Optional[str] = None, image: Optional[Any] = None, cpu: Optional[int] = None, memory_mb: Optional[int] = None, disk_gb: Optional[int] = None, region: str = 'us-east-1')
+```
+
+### Attributes
+
+| Name | Type | Description |
+|------|------|-------------|
+| `name` | `Optional[str]` | |
+
+### Methods
+
+#### CloudTransport.connect
+
+```python
+async def connect(self) -> None
+```
+
+#### CloudTransport.disconnect
+
+```python
+async def disconnect(self) -> None
+```
+
+#### CloudTransport.delete_vm
+
+```python
+async def delete_vm(self) -> None
+```
+
+Delete the cloud VM via the platform API.
+
+#### CloudTransport.suspend_vm
+
+```python
+async def suspend_vm(self) -> None
+```
+
+Stop (suspend) the cloud VM.
+
+#### CloudTransport.resume_vm
+
+```python
+async def resume_vm(self) -> None
+```
+
+Start (resume) the cloud VM.
+
+#### CloudTransport.restart_vm
+
+```python
+async def restart_vm(self) -> None
+```
+
+Restart the cloud VM.
+
+#### CloudTransport.send
+
+```python
+async def send(self, action: str, params: Any = {}) -> Any
+```
+
+#### CloudTransport.screenshot
+
+```python
+async def screenshot(self, format: str = 'png', quality: int = 95) -> bytes
+```
+
+#### CloudTransport.get_screen_size
+
+```python
+async def get_screen_size(self) -> Dict[str, int]
+```
+
+#### CloudTransport.get_environment
+
+```python
+async def get_environment(self) -> str
+```
+
+#### CloudTransport.get_display_url
+
+```python
+async def get_display_url(self, share: bool = False) -> str
+```
+
+## login
+
+```python
+def login(base_url: Optional[str] = None) -> None
+```
+
+Open the CUA login page in a browser and store credentials.
+
+This initiates a Clerk-based browser authentication flow.
+The user completes login in their browser, and the resulting
+API key is stored in ~/.cua/credentials.
+
+## whoami
+
+```python
+def whoami(api_key: Optional[str] = None) -> Dict[str, Any]
+```
+
+Return info about the authenticated user.
+
+**Returns:** Dict with user info (id, email, etc.) from the CUA API.
+
+## configure
+
+```python
+def configure(api_key: Optional[str] = None, base_url: Optional[str] = None) -> None
+```
+
+Set global configuration for the CUA SDK.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `api_key` | `Any` | API key for cloud sandboxes. |
+| `base_url` | `Any` | Base URL for the CUA cloud API. |
+
+---
+
+## localhost
+
+Localhost — wraps cua_auto directly. No sandbox, no computer-server.
+
+All cua_auto calls are sync; async wrappers use asyncio.to_thread().
+
+Usage::
+
+ from cua_sandbox import localhost
+
+ async with localhost() as host:
+ await host.mouse.click(100, 200)
+ img = await host.screen.screenshot()
+
+---
+
+## LocalTransport
+
+*Inherits from: Transport*
+
+Transport that routes commands directly to cua_auto modules.
+
+### Methods
+
+#### LocalTransport.connect
+
+```python
+async def connect(self) -> None
+```
+
+#### LocalTransport.disconnect
+
+```python
+async def disconnect(self) -> None
+```
+
+#### LocalTransport.send
+
+```python
+async def send(self, action: str, params: Any = {}) -> Any
+```
+
+Dispatch a named command to the appropriate cua_auto module.
+
+#### LocalTransport.screenshot
+
+```python
+async def screenshot(self, format: str = 'png', quality: int = 95) -> bytes
+```
+
+#### LocalTransport.get_screen_size
+
+```python
+async def get_screen_size(self) -> Dict[str, int]
+```
+
+#### LocalTransport.get_environment
+
+```python
+async def get_environment(self) -> str
+```
+
+---
+
+## Localhost
+
+Direct host control via cua_auto — no sandboxing.
+
+### Constructor
+
+```python
+Localhost(self) -> None
+```
+
+### Attributes
+
+| Name | Type | Description |
+|------|------|-------------|
+| `screen` | `Any` | |
+| `mouse` | `Any` | |
+| `keyboard` | `Any` | |
+| `clipboard` | `Any` | |
+| `shell` | `Any` | |
+| `window` | `Any` | |
+| `terminal` | `Any` | |
+
+### Methods
+
+#### Localhost.disconnect
+
+```python
+async def disconnect(self) -> None
+```
+
+#### Localhost.screenshot
+
+```python
+async def screenshot(self, text: Optional[str] = None) -> bytes
+```
+
+#### Localhost.screenshot_base64
+
+```python
+async def screenshot_base64(self, text: Optional[str] = None) -> str
+```
+
+#### Localhost.get_environment
+
+```python
+async def get_environment(self) -> str
+```
+
+#### Localhost.get_dimensions
+
+```python
+async def get_dimensions(self) -> tuple[int, int]
+```
+
+#### Localhost.connect
+
+```python
+def connect(cls) -> '_ConnectResult'
+```
+
+Connect to the local machine.
+
+Supports both ``await`` and ``async with``.
+
+**Example:**
+
+```python
+# plain await
+host = await Localhost.connect()
+await host.shell.run("echo hello")
+await host.disconnect()
+
+# context manager
+async with Localhost.connect() as host:
+ await host.shell.run("echo hello")
+```
+
+### localhost
+
+```python
+async def localhost() -> AsyncIterator[Localhost]
+```
+
+Async context manager yielding a Localhost instance.
+
+.. deprecated::
+ Prefer ``Localhost.connect()`` instead.
+
+---
+
+## sandbox
+
+Sandbox class — the primary entry point for sandboxed environments.
+
+Exposes .mouse, .keyboard, .screen, .clipboard, .shell, .window, .terminal
+as interface objects backed by a Transport.
+
+Usage::
+
+ from cua_sandbox import Sandbox, Image
+
+ # Provision a new persistent sandbox
+ sb = await Sandbox.create(Image.desktop("ubuntu"))
+ await sb.shell.run("uname -a")
+ await sb.disconnect()
+
+ # Connect to an existing sandbox by name (plain await or async with)
+ sb = await Sandbox.connect("my-sandbox")
+ await sb.screenshot()
+ await sb.disconnect()
+
+ async with Sandbox.connect("my-sandbox") as sb: # disconnects on exit
+ await sb.screenshot()
+
+ # Ephemeral — auto-destroyed on exit
+ async with Sandbox.ephemeral(Image.desktop("ubuntu")) as sb:
+ await sb.shell.run("whoami")
+
+---
+
+## Image
+
+Immutable, chainable image specification.
+
+Each mutation method returns a new Image instance so that builders
+can be forked at any point.
+
+### Constructor
+
+```python
+Image(self, os_type: str, distro: str, version: str, kind: Optional[str] = None, _layers: Tuple[Dict[str, Any], ...] = (), _env: Tuple[Tuple[str, str], ...] = (), _ports: Tuple[int, ...] = (), _files: Tuple[Tuple[str, str], ...] = (), _registry: Optional[str] = None, _disk_path: Optional[str] = None, _agent_type: Optional[str] = None) -> None
+```
+
+### Attributes
+
+| Name | Type | Description |
+|------|------|-------------|
+| `os_type` | `str` | |
+| `distro` | `str` | |
+| `version` | `str` | |
+| `kind` | `Optional[str]` | |
+
+### Methods
+
+#### Image.linux
+
+```python
+def linux(cls, distro: str = 'ubuntu', version: str = '24.04', kind: str = 'container') -> Image
+```
+
+Linux image. Defaults to 'container' (Docker/XFCE). Use kind='vm' for QEMU.
+
+#### Image.macos
+
+```python
+def macos(cls, version: str = '26', kind: str = 'vm') -> Image
+```
+
+macOS image. Always a VM (Apple Virtualization / Lume).
+
+Supported versions: ``"15"`` / ``"sequoia"``, ``"26"`` / ``"tahoe"``.
+
+#### Image.windows
+
+```python
+def windows(cls, version: str = '11', kind: str = 'vm') -> Image
+```
+
+Windows image. Always a VM (QEMU or Hyper-V).
+
+#### Image.android
+
+```python
+def android(cls, version: str = '14', kind: str = 'vm') -> Image
+```
+
+Android image. Always a VM (QEMU emulator).
+
+#### Image.from_registry
+
+```python
+def from_registry(cls, ref: str) -> Image
+```
+
+Create an image from a registry reference. kind is resolved after pull.
+
+#### Image.from_file
+
+```python
+def from_file(cls, path: str, os_type: str = 'windows', kind: str = 'vm', agent_type: Optional[str] = None) -> Image
+```
+
+Create an image from a local disk, ISO file, or URL.
+
+Supported formats: qcow2, vhdx, raw, img, iso.
+URLs (http/https) are downloaded automatically. Zip files are extracted.
+For ISOs, the runtime will create a qcow2 disk and attach the ISO
+as a CD-ROM for installation/boot.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `path` | `Any` | Local file path or URL (http/https). |
+| `os_type` | `Any` | OS type hint ("linux", "windows", "macos", "android"). |
+| `kind` | `Any` | "vm" or "container". |
+| `agent_type` | `Any` | Agent type hint (e.g. "osworld" for OSWorld Flask server). |
+
+#### Image.from_dict
+
+```python
+def from_dict(cls, data: Dict[str, Any]) -> Image
+```
+
+Reconstruct an Image from a serialized spec dict.
+
+#### Image.apt_install
+
+```python
+def apt_install(self, packages: str = ()) -> Image
+```
+
+Install packages via apt (Linux only).
+
+#### Image.brew_install
+
+```python
+def brew_install(self, packages: str = ()) -> Image
+```
+
+Install packages via Homebrew (macOS).
+
+#### Image.choco_install
+
+```python
+def choco_install(self, packages: str = ()) -> Image
+```
+
+Install packages via Chocolatey (Windows).
+
+#### Image.winget_install
+
+```python
+def winget_install(self, packages: str = ()) -> Image
+```
+
+Install packages via winget (Windows).
+
+#### Image.apk_install
+
+```python
+def apk_install(self, apk_paths: str = ()) -> Image
+```
+
+Install APK files via adb (Android only).
+
+#### Image.pwa_install
+
+```python
+def pwa_install(self, manifest_url: str, package_name: Optional[str] = None, keystore: Optional[str] = None, keystore_alias: str = 'android', keystore_password: str = 'android') -> 'Image'
+```
+
+Build an APK from a PWA manifest URL via Bubblewrap and install it (Android only).
+
+Bubblewrap reads the Web App Manifest at *manifest_url*, generates a
+Trusted Web Activity (TWA) APK signed with *keystore*, and installs it
+via adb. The keystore's SHA-256 fingerprint must match what the server
+serves from ``/.well-known/assetlinks.json`` so Chrome trusts the TWA
+and skips the browser UI entirely.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `manifest_url` | `Any` | Full URL to the PWA's ``manifest.json``. |
+
+**Example:**
+
+```python
+package_name: Android package ID. Defaults to a reversed-hostname
+ derivation (e.g. ``"com.example.app"``).
+keystore: Path to a ``*.keystore`` / ``*.jks`` file. When
+ omitted a fresh keystore is generated and cached under
+ ``~/.cua/cua-sandbox/pwa-cache/``. Pass the keystore
+ bundled with your PWA repo so the fingerprint is
+ deterministic and pre-loaded into ``assetlinks.json``.
+keystore_alias: Key alias inside the keystore (default ``"android"``).
+keystore_password: Password for both the store and the key
+ (default ``"android"``).
+```
+
+#### Image.uv_install
+
+```python
+def uv_install(self, packages: str = ()) -> Image
+```
+
+Install Python packages via uv add into the cua-server project.
+
+#### Image.pip_install
+
+```python
+def pip_install(self, packages: str = ()) -> Image
+```
+
+Install Python packages via pip.
+
+#### Image.run
+
+```python
+def run(self, command: str) -> Image
+```
+
+Run a shell command during image build.
+
+#### Image.env
+
+```python
+def env(self, variables: str = {}) -> Image
+```
+
+Set environment variables.
+
+#### Image.copy
+
+```python
+def copy(self, src: str, dst: str) -> Image
+```
+
+Copy a file into the image.
+
+#### Image.expose
+
+```python
+def expose(self, port: int) -> Image
+```
+
+Expose a port.
+
+#### Image.to_dict
+
+```python
+def to_dict(self) -> Dict[str, Any]
+```
+
+Serialize to a plain dict suitable for JSON or cloud API.
+
+#### Image.to_cloud_init
+
+```python
+def to_cloud_init(self) -> str
+```
+
+Generate a cloud-init user-data script from the image layers.
+
+---
+
+## Transport
+
+*Inherits from: ABC*
+
+Base class for all transports.
+
+### Methods
+
+#### Transport.connect
+
+```python
+async def connect(self) -> None
+```
+
+Establish the transport connection.
+
+#### Transport.disconnect
+
+```python
+async def disconnect(self) -> None
+```
+
+Tear down the transport connection.
+
+#### Transport.send
+
+```python
+async def send(self, action: str, params: Any = {}) -> Any
+```
+
+Send a command and return the result.
+
+#### Transport.screenshot
+
+```python
+async def screenshot(self, format: str = 'png', quality: int = 95) -> bytes
+```
+
+Capture a screenshot and return raw image bytes.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `format` | `Any` | "png" (lossless, default) or "jpeg" (lossy, ~5-10x smaller). |
+| `quality` | `Any` | JPEG quality 1-95, ignored for PNG. |
+
+#### Transport.get_screen_size
+
+```python
+async def get_screen_size(self) -> Dict[str, int]
+```
+
+Return \{"width": ..., "height": ...\}.
+
+#### Transport.get_environment
+
+```python
+async def get_environment(self) -> str
+```
+
+Return 'windows', 'mac', 'linux', or 'browser'.
+
+#### Transport.forward_tunnel
+
+```python
+async def forward_tunnel(self, sandbox_port: int | str) -> 'TunnelInfo'
+```
+
+Forward *sandbox_port* to an available host port and return info.
+
+Subclasses that support tunnelling must override this method.
+The returned :class:`~cua_sandbox.interfaces.tunnel.TunnelInfo` must
+have ``host`` and ``port`` set to the host-side address.
+
+#### Transport.close_tunnel
+
+```python
+async def close_tunnel(self, info: 'TunnelInfo') -> None
+```
+
+Release a previously forwarded port or socket. No-op by default.
+
+#### Transport.get_display_url
+
+```python
+async def get_display_url(self, share: bool = False) -> str
+```
+
+Return a URL to view this sandbox's display.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `share` | `Any` | If True, return a public link with embedded credentials (cloud only). If False, return a direct connection URL (localhost VNC for local runtimes; auth-gated URL for cloud). Raises NotImplementedError for transports that don't expose a display (e.g. HTTP, ADB). |
+
+---
+
+## CloudTransport
+
+*Inherits from: Transport*
+
+Transport that provisions / connects to a CUA cloud VM.
+
+### Constructor
+
+```python
+CloudTransport(self, name: Optional[str] = None, api_key: Optional[str] = None, base_url: Optional[str] = None, image: Optional[Any] = None, cpu: Optional[int] = None, memory_mb: Optional[int] = None, disk_gb: Optional[int] = None, region: str = 'us-east-1')
+```
+
+### Attributes
+
+| Name | Type | Description |
+|------|------|-------------|
+| `name` | `Optional[str]` | |
+
+### Methods
+
+#### CloudTransport.connect
+
+```python
+async def connect(self) -> None
+```
+
+#### CloudTransport.disconnect
+
+```python
+async def disconnect(self) -> None
+```
+
+#### CloudTransport.delete_vm
+
+```python
+async def delete_vm(self) -> None
+```
+
+Delete the cloud VM via the platform API.
+
+#### CloudTransport.suspend_vm
+
+```python
+async def suspend_vm(self) -> None
+```
+
+Stop (suspend) the cloud VM.
+
+#### CloudTransport.resume_vm
+
+```python
+async def resume_vm(self) -> None
+```
+
+Start (resume) the cloud VM.
+
+#### CloudTransport.restart_vm
+
+```python
+async def restart_vm(self) -> None
+```
+
+Restart the cloud VM.
+
+#### CloudTransport.send
+
+```python
+async def send(self, action: str, params: Any = {}) -> Any
+```
+
+#### CloudTransport.screenshot
+
+```python
+async def screenshot(self, format: str = 'png', quality: int = 95) -> bytes
+```
+
+#### CloudTransport.get_screen_size
+
+```python
+async def get_screen_size(self) -> Dict[str, int]
+```
+
+#### CloudTransport.get_environment
+
+```python
+async def get_environment(self) -> str
+```
+
+#### CloudTransport.get_display_url
+
+```python
+async def get_display_url(self, share: bool = False) -> str
+```
+
+---
+
+## HTTPTransport
+
+*Inherits from: Transport*
+
+Transport that communicates with computer-server over HTTP POST /cmd (SSE).
+
+### Constructor
+
+```python
+HTTPTransport(self, base_url: str, api_key: Optional[str] = None, container_name: Optional[str] = None, timeout: float = 30.0)
+```
+
+### Methods
+
+#### HTTPTransport.connect
+
+```python
+async def connect(self) -> None
+```
+
+#### HTTPTransport.disconnect
+
+```python
+async def disconnect(self) -> None
+```
+
+#### HTTPTransport.send
+
+```python
+async def send(self, action: str, params: Any = {}) -> Any
+```
+
+#### HTTPTransport.screenshot
+
+```python
+async def screenshot(self, format: str = 'png', quality: int = 95) -> bytes
+```
+
+#### HTTPTransport.get_screen_size
+
+```python
+async def get_screen_size(self) -> Dict[str, int]
+```
+
+#### HTTPTransport.get_environment
+
+```python
+async def get_environment(self) -> str
+```
+
+---
+
+## WebSocketTransport
+
+*Inherits from: Transport*
+
+Transport that communicates with computer-server over WebSocket.
+
+### Constructor
+
+```python
+WebSocketTransport(self, url: str, api_key: Optional[str] = None)
+```
+
+### Methods
+
+#### WebSocketTransport.connect
+
+```python
+async def connect(self) -> None
+```
+
+#### WebSocketTransport.disconnect
+
+```python
+async def disconnect(self) -> None
+```
+
+#### WebSocketTransport.send
+
+```python
+async def send(self, action: str, params: Any = {}) -> Any
+```
+
+#### WebSocketTransport.screenshot
+
+```python
+async def screenshot(self, format: str = 'png', quality: int = 95) -> bytes
+```
+
+#### WebSocketTransport.get_screen_size
+
+```python
+async def get_screen_size(self) -> Dict[str, int]
+```
+
+#### WebSocketTransport.get_environment
+
+```python
+async def get_environment(self) -> str
+```
+
+---
+
+## Runtime
+
+*Inherits from: ABC*
+
+Base class for local runtimes that create VMs/containers from an Image.
+
+### Methods
+
+#### Runtime.start
+
+```python
+async def start(self, image: Image, name: str, opts = {}) -> RuntimeInfo
+```
+
+Start a VM/container and return connection info.
+
+#### Runtime.stop
+
+```python
+async def stop(self, name: str) -> None
+```
+
+Stop and clean up a VM/container.
+
+#### Runtime.is_ready
+
+```python
+async def is_ready(self, info: RuntimeInfo, timeout: float = 120) -> bool
+```
+
+Wait until the computer-server inside is reachable.
+
+#### Runtime.suspend
+
+```python
+async def suspend(self, name: str) -> None
+```
+
+Suspend (pause/save state of) a running VM.
+
+#### Runtime.resume
+
+```python
+async def resume(self, image: 'Image', name: str, opts = {}) -> RuntimeInfo
+```
+
+Resume a suspended VM and return its RuntimeInfo.
+
+#### Runtime.list
+
+```python
+async def list(self) -> list[dict]
+```
+
+List known VMs managed by this runtime.
+
+Returns a list of dicts with at minimum: name, status.
+
+---
+
+## RuntimeInfo
+
+Connection info returned after a runtime spins up.
+
+### Constructor
+
+```python
+RuntimeInfo(self, host: str, api_port: int, vnc_port: Optional[int] = None, api_key: Optional[str] = None, container_id: Optional[str] = None, name: Optional[str] = None, qmp_port: Optional[int] = None, environment: Optional[str] = None, agent_type: Optional[str] = None, guest_server_port: int = 8000, ssh_port: Optional[int] = None, ssh_username: Optional[str] = None, ssh_password: Optional[str] = None, ssh_key_filename: Optional[str] = None, vnc_host: Optional[str] = None, vnc_password: Optional[str] = None, grpc_port: Optional[int] = None) -> None
+```
+
+### Attributes
+
+| Name | Type | Description |
+|------|------|-------------|
+| `host` | `str` | |
+| `api_port` | `int` | |
+| `vnc_port` | `Optional[int]` | |
+| `api_key` | `Optional[str]` | |
+| `container_id` | `Optional[str]` | |
+| `name` | `Optional[str]` | |
+| `qmp_port` | `Optional[int]` | |
+| `environment` | `Optional[str]` | |
+| `agent_type` | `Optional[str]` | |
+| `guest_server_port` | `int` | |
+| `ssh_port` | `Optional[int]` | |
+| `ssh_username` | `Optional[str]` | |
+| `ssh_password` | `Optional[str]` | |
+| `ssh_key_filename` | `Optional[str]` | |
+| `vnc_host` | `Optional[str]` | |
+| `vnc_password` | `Optional[str]` | |
+| `grpc_port` | `Optional[int]` | |
+
+---
+
+## SandboxInfo
+
+Metadata for a local or cloud sandbox.
+
+### Constructor
+
+```python
+SandboxInfo(self, name: str, status: str, source: str, os_type: Optional[str] = None, host: Optional[str] = None, vnc_url: Optional[str] = None, api_url: Optional[str] = None, created_at: Optional[str] = None) -> None
+```
+
+### Attributes
+
+| Name | Type | Description |
+|------|------|-------------|
+| `name` | `str` | |
+| `status` | `str` | |
+| `source` | `str` | |
+| `os_type` | `Optional[str]` | |
+| `host` | `Optional[str]` | |
+| `vnc_url` | `Optional[str]` | |
+| `api_url` | `Optional[str]` | |
+| `created_at` | `Optional[str]` | |
+
+---
+
+## Sandbox
+
+A sandboxed computer environment.
+
+Provides programmatic control of a VM or container through a unified
+interface: ``.mouse``, ``.keyboard``, ``.screen``, ``.clipboard``,
+``.shell``, ``.window``, and ``.terminal``.
+
+Sandboxes are always isolated — they never control the host machine
+directly. For unsandboxed host control, use :func:`cua_sandbox.localhost`.
+
+There are three ways to obtain a Sandbox:
+
+1. **Persistent** — provision and keep alive after the script exits::
+
+ sb = await Sandbox.create(Image.desktop("ubuntu"))
+ await sb.shell.run("whoami")
+ await sb.disconnect()
+
+2. **Connect** — attach to an already-running sandbox by name::
+
+ sb = await Sandbox.connect("my-sandbox")
+ await sb.screenshot()
+ await sb.disconnect()
+
+3. **Ephemeral** — auto-destroyed when the ``async with`` block exits::
+
+ async with Sandbox.ephemeral(Image.desktop("ubuntu")) as sb:
+ await sb.shell.run("whoami")
+
+### Constructor
+
+```python
+Sandbox(self, transport: Transport, name: Optional[str] = None, _runtime: Optional[Runtime] = None, _runtime_info: Optional[RuntimeInfo] = None, _ephemeral: Optional[bool] = None)
+```
+
+### Attributes
+
+| Name | Type | Description |
+|------|------|-------------|
+| `name` | `Any` | |
+| `screen` | `Any` | |
+| `mouse` | `Any` | |
+| `keyboard` | `Any` | |
+| `clipboard` | `Any` | |
+| `shell` | `Any` | |
+| `window` | `Any` | |
+| `terminal` | `Any` | |
+| `mobile` | `Any` | |
+| `tunnel` | `Any` | |
+
+### Methods
+
+#### Sandbox.disconnect
+
+```python
+async def disconnect(self) -> None
+```
+
+Drop the transport connection. The sandbox keeps running.
+
+#### Sandbox.destroy
+
+```python
+async def destroy(self) -> None
+```
+
+Disconnect and permanently delete the sandbox (VM/container).
+
+#### Sandbox.screenshot
+
+```python
+async def screenshot(self, text: Optional[str] = None, format: str = 'png', quality: int = 95) -> bytes
+```
+
+#### Sandbox.screenshot_base64
+
+```python
+async def screenshot_base64(self, text: Optional[str] = None, format: str = 'png', quality: int = 95) -> str
+```
+
+#### Sandbox.get_environment
+
+```python
+async def get_environment(self) -> str
+```
+
+#### Sandbox.get_display_url
+
+```python
+async def get_display_url(self, share: bool = False) -> str
+```
+
+Return a URL to view this sandbox's display.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `share` | `Any` | If True, return a public link with embedded credentials (cloud only). If False, return a direct connection URL. |
+
+#### Sandbox.get_dimensions
+
+```python
+async def get_dimensions(self) -> tuple[int, int]
+```
+
+#### Sandbox.create
+
+```python
+async def create(cls, image: Image, name: Optional[str] = None, api_key: Optional[str] = None, local: bool = False, runtime: Optional['Runtime'] = None, cpu: Optional[int] = None, memory_mb: Optional[int] = None, disk_gb: Optional[int] = None, region: str = 'us-east-1') -> 'Sandbox'
+```
+
+Provision a new persistent sandbox and return it connected.
+
+The sandbox is kept alive after your script exits — call ``close()``
+when you are done, or use :meth:`ephemeral` if you want it destroyed
+automatically.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `image` | `Any` | Image to run (e.g. ``Image.desktop("ubuntu")``). |
+| `name` | `Any` | Optional name to assign to the sandbox. |
+| `api_key` | `Any` | CUA API key for cloud sandboxes. |
+| `local` | `Any` | Use a local runtime instead of cloud. |
+| `runtime` | `Any` | Explicit runtime backend (DockerRuntime, QEMURuntime, etc.). |
+| `cpu` | `Any` | Number of CPUs for the cloud sandbox. |
+| `memory_mb` | `Any` | Memory in MB for the cloud sandbox. |
+| `disk_gb` | `Any` | Disk size in GB for the cloud sandbox. |
+| `region` | `Any` | Cloud region (default ``"us-east-1"``). |
+
+**Example:**
+
+```python
+sb = await Sandbox.create(Image.desktop("ubuntu"))
+await sb.shell.run("uname -a")
+print(sb.name) # save to reconnect later
+await sb.disconnect()
+```
+
+#### Sandbox.connect
+
+```python
+def connect(cls, name: str, api_key: Optional[str] = None, local: bool = False, ws_url: Optional[str] = None, http_url: Optional[str] = None, container_name: Optional[str] = None, cpu: Optional[int] = None, memory_mb: Optional[int] = None, disk_gb: Optional[int] = None, region: str = 'us-east-1') -> '_ConnectResult'
+```
+
+Connect to an existing sandbox by name.
+
+Supports both ``await`` and ``async with``. When used as a context
+manager, ``disconnect()`` is called on exit — the sandbox keeps running.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `name` | `Any` | Name of the existing sandbox. |
+| `api_key` | `Any` | CUA API key for cloud sandboxes. |
+| `ws_url` | `Any` | WebSocket URL for a remote computer-server. |
+| `http_url` | `Any` | HTTP base URL for a remote computer-server. |
+| `container_name` | `Any` | Container name for cloud auth (HTTP transport). |
+| `region` | `Any` | Cloud region (default ``"us-east-1"``). |
+
+**Example:**
+
+```python
+# plain await
+sb = await Sandbox.connect("my-sandbox")
+await sb.screenshot()
+await sb.disconnect()
+
+# context manager — disconnects on exit, sandbox keeps running
+async with Sandbox.connect("my-sandbox") as sb:
+ await sb.screenshot()
+```
+
+#### Sandbox.ephemeral
+
+```python
+async def ephemeral(cls, image: Image, name: Optional[str] = None, api_key: Optional[str] = None, local: bool = False, runtime: Optional['Runtime'] = None, cpu: Optional[int] = None, memory_mb: Optional[int] = None, disk_gb: Optional[int] = None, region: str = 'us-east-1') -> AsyncIterator['Sandbox']
+```
+
+Create an ephemeral sandbox that is automatically destroyed on exit.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `image` | `Any` | Image to run (e.g. ``Image.desktop("ubuntu")``). |
+| `name` | `Any` | Optional name to assign to the sandbox. |
+| `api_key` | `Any` | CUA API key for cloud sandboxes. |
+| `local` | `Any` | Use a local runtime instead of cloud. |
+| `runtime` | `Any` | Explicit runtime backend (DockerRuntime, QEMURuntime, etc.). |
+| `cpu` | `Any` | Number of CPUs for the cloud sandbox. |
+| `memory_mb` | `Any` | Memory in MB for the cloud sandbox. |
+| `disk_gb` | `Any` | Disk size in GB for the cloud sandbox. |
+| `region` | `Any` | Cloud region (default ``"us-east-1"``). |
+
+**Example:**
+
+```python
+async with Sandbox.ephemeral(Image.desktop("ubuntu")) as sb:
+ await sb.shell.run("whoami")
+# sandbox is destroyed here
+```
+
+#### Sandbox.list
+
+```python
+async def list(cls, local: bool = False, api_key: Optional[str] = None) -> 'list[SandboxInfo]'
+```
+
+List running and suspended sandboxes.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `local` | `Any` | If True, list local sandboxes (Lume, Docker, QEMU). If False, list cloud sandboxes. |
+| `api_key` | `Any` | CUA API key for cloud sandboxes. |
+
+#### Sandbox.get_info
+
+```python
+async def get_info(cls, name: str, local: bool = False, api_key: Optional[str] = None) -> 'SandboxInfo'
+```
+
+Get metadata for a specific sandbox.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `name` | `Any` | Sandbox name. |
+| `local` | `Any` | If True, look up in local runtimes. |
+| `api_key` | `Any` | CUA API key for cloud. |
+
+#### Sandbox.suspend
+
+```python
+async def suspend(cls, name: str, local: bool = False, api_key: Optional[str] = None) -> None
+```
+
+Suspend a running sandbox (save state).
+
+For local QEMU bare-metal: saves a QMP snapshot then quits the process.
+For local Docker/QEMU-docker: pauses the container.
+For local Lume: stops the Lume VM (Lume persists state).
+For cloud: calls POST /v1/vms/\{name\}/stop.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `name` | `Any` | Sandbox name. |
+| `local` | `Any` | If True, operate on a local sandbox. |
+| `api_key` | `Any` | CUA API key for cloud. |
+
+#### Sandbox.resume
+
+```python
+async def resume(cls, name: str, local: bool = False, api_key: Optional[str] = None) -> 'Sandbox'
+```
+
+Resume a suspended sandbox and return a connected Sandbox.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `name` | `Any` | Sandbox name. |
+| `local` | `Any` | If True, resume a local sandbox. |
+| `api_key` | `Any` | CUA API key for cloud. |
+
+**Returns:** A connected Sandbox ready to use.
+
+#### Sandbox.restart
+
+```python
+async def restart(cls, name: str, local: bool = False, api_key: Optional[str] = None) -> 'Sandbox'
+```
+
+Restart a sandbox (suspend then resume) and return a connected Sandbox.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `name` | `Any` | Sandbox name. |
+| `local` | `Any` | If True, restart a local sandbox. |
+| `api_key` | `Any` | CUA API key for cloud. |
+
+**Returns:** A connected Sandbox ready to use.
+
+#### Sandbox.delete
+
+```python
+async def delete(cls, name: str, local: bool = False, api_key: Optional[str] = None) -> None
+```
+
+Permanently delete a sandbox.
+
+For local sandboxes, stops the VM and removes the state file.
+For cloud sandboxes, calls DELETE /v1/vms/\{name\}.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `name` | `Any` | Sandbox name. |
+| `local` | `Any` | If True, delete a local sandbox. |
+| `api_key` | `Any` | CUA API key for cloud. |
+
+### sandbox
+
+```python
+async def sandbox(local: bool = False, ws_url: Optional[str] = None, http_url: Optional[str] = None, api_key: Optional[str] = None, container_name: Optional[str] = None, image: Optional[Image] = None, runtime: Optional['Runtime'] = None, name: Optional[str] = None, ephemeral: Optional[bool] = None, cpu: Optional[int] = None, memory_mb: Optional[int] = None, disk_gb: Optional[int] = None, region: str = 'us-east-1') -> AsyncIterator[Sandbox]
+```
+
+Async context manager for a sandboxed environment.
+
+.. deprecated::
+ Prefer ``Sandbox.create()``, ``Sandbox.connect()``, or
+ ``Sandbox.ephemeral()`` instead.
+
+---
+
+## image
+
+Image builder — pure-data immutable chained builder for sandbox images.
+
+Supports Linux, macOS, and Windows constructors. Serializes to a spec dict
+for cloud API or cloud-init consumption.
+
+Usage::
+
+ from cua_sandbox import Image
+
+ img = (
+ Image.linux("ubuntu", "24.04")
+ .apt_install("curl", "git", "build-essential")
+ .pip_install("numpy", "pandas")
+ .env(MY_VAR="hello")
+ .run("echo 'setup complete'")
+ .expose(8080)
+ )
+
+ spec = img.to_dict()
+
+---
+
+## Image
+
+Immutable, chainable image specification.
+
+Each mutation method returns a new Image instance so that builders
+can be forked at any point.
+
+### Constructor
+
+```python
+Image(self, os_type: str, distro: str, version: str, kind: Optional[str] = None, _layers: Tuple[Dict[str, Any], ...] = (), _env: Tuple[Tuple[str, str], ...] = (), _ports: Tuple[int, ...] = (), _files: Tuple[Tuple[str, str], ...] = (), _registry: Optional[str] = None, _disk_path: Optional[str] = None, _agent_type: Optional[str] = None) -> None
+```
+
+### Attributes
+
+| Name | Type | Description |
+|------|------|-------------|
+| `os_type` | `str` | |
+| `distro` | `str` | |
+| `version` | `str` | |
+| `kind` | `Optional[str]` | |
+
+### Methods
+
+#### Image.linux
+
+```python
+def linux(cls, distro: str = 'ubuntu', version: str = '24.04', kind: str = 'container') -> Image
+```
+
+Linux image. Defaults to 'container' (Docker/XFCE). Use kind='vm' for QEMU.
+
+#### Image.macos
+
+```python
+def macos(cls, version: str = '26', kind: str = 'vm') -> Image
+```
+
+macOS image. Always a VM (Apple Virtualization / Lume).
+
+Supported versions: ``"15"`` / ``"sequoia"``, ``"26"`` / ``"tahoe"``.
+
+#### Image.windows
+
+```python
+def windows(cls, version: str = '11', kind: str = 'vm') -> Image
+```
+
+Windows image. Always a VM (QEMU or Hyper-V).
+
+#### Image.android
+
+```python
+def android(cls, version: str = '14', kind: str = 'vm') -> Image
+```
+
+Android image. Always a VM (QEMU emulator).
+
+#### Image.from_registry
+
+```python
+def from_registry(cls, ref: str) -> Image
+```
+
+Create an image from a registry reference. kind is resolved after pull.
+
+#### Image.from_file
+
+```python
+def from_file(cls, path: str, os_type: str = 'windows', kind: str = 'vm', agent_type: Optional[str] = None) -> Image
+```
+
+Create an image from a local disk, ISO file, or URL.
+
+Supported formats: qcow2, vhdx, raw, img, iso.
+URLs (http/https) are downloaded automatically. Zip files are extracted.
+For ISOs, the runtime will create a qcow2 disk and attach the ISO
+as a CD-ROM for installation/boot.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `path` | `Any` | Local file path or URL (http/https). |
+| `os_type` | `Any` | OS type hint ("linux", "windows", "macos", "android"). |
+| `kind` | `Any` | "vm" or "container". |
+| `agent_type` | `Any` | Agent type hint (e.g. "osworld" for OSWorld Flask server). |
+
+#### Image.from_dict
+
+```python
+def from_dict(cls, data: Dict[str, Any]) -> Image
+```
+
+Reconstruct an Image from a serialized spec dict.
+
+#### Image.apt_install
+
+```python
+def apt_install(self, packages: str = ()) -> Image
+```
+
+Install packages via apt (Linux only).
+
+#### Image.brew_install
+
+```python
+def brew_install(self, packages: str = ()) -> Image
+```
+
+Install packages via Homebrew (macOS).
+
+#### Image.choco_install
+
+```python
+def choco_install(self, packages: str = ()) -> Image
+```
+
+Install packages via Chocolatey (Windows).
+
+#### Image.winget_install
+
+```python
+def winget_install(self, packages: str = ()) -> Image
+```
+
+Install packages via winget (Windows).
+
+#### Image.apk_install
+
+```python
+def apk_install(self, apk_paths: str = ()) -> Image
+```
+
+Install APK files via adb (Android only).
+
+#### Image.pwa_install
+
+```python
+def pwa_install(self, manifest_url: str, package_name: Optional[str] = None, keystore: Optional[str] = None, keystore_alias: str = 'android', keystore_password: str = 'android') -> 'Image'
+```
+
+Build an APK from a PWA manifest URL via Bubblewrap and install it (Android only).
+
+Bubblewrap reads the Web App Manifest at *manifest_url*, generates a
+Trusted Web Activity (TWA) APK signed with *keystore*, and installs it
+via adb. The keystore's SHA-256 fingerprint must match what the server
+serves from ``/.well-known/assetlinks.json`` so Chrome trusts the TWA
+and skips the browser UI entirely.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `manifest_url` | `Any` | Full URL to the PWA's ``manifest.json``. |
+
+**Example:**
+
+```python
+package_name: Android package ID. Defaults to a reversed-hostname
+ derivation (e.g. ``"com.example.app"``).
+keystore: Path to a ``*.keystore`` / ``*.jks`` file. When
+ omitted a fresh keystore is generated and cached under
+ ``~/.cua/cua-sandbox/pwa-cache/``. Pass the keystore
+ bundled with your PWA repo so the fingerprint is
+ deterministic and pre-loaded into ``assetlinks.json``.
+keystore_alias: Key alias inside the keystore (default ``"android"``).
+keystore_password: Password for both the store and the key
+ (default ``"android"``).
+```
+
+#### Image.uv_install
+
+```python
+def uv_install(self, packages: str = ()) -> Image
+```
+
+Install Python packages via uv add into the cua-server project.
+
+#### Image.pip_install
+
+```python
+def pip_install(self, packages: str = ()) -> Image
+```
+
+Install Python packages via pip.
+
+#### Image.run
+
+```python
+def run(self, command: str) -> Image
+```
+
+Run a shell command during image build.
+
+#### Image.env
+
+```python
+def env(self, variables: str = {}) -> Image
+```
+
+Set environment variables.
+
+#### Image.copy
+
+```python
+def copy(self, src: str, dst: str) -> Image
+```
+
+Copy a file into the image.
+
+#### Image.expose
+
+```python
+def expose(self, port: int) -> Image
+```
+
+Expose a port.
+
+#### Image.to_dict
+
+```python
+def to_dict(self) -> Dict[str, Any]
+```
+
+Serialize to a plain dict suitable for JSON or cloud API.
+
+#### Image.to_cloud_init
+
+```python
+def to_cloud_init(self) -> str
+```
+
+Generate a cloud-init user-data script from the image layers.
+
+---
+
+## builder
+
+Image builder — build QEMU VM images from Image layer specs.
+
+---
+
+## LayerExecutor
+
+Execute Image layer specs against a running computer-server.
+
+### Constructor
+
+```python
+LayerExecutor(self, base_url: str, timeout: float = 600)
+```
+
+### Attributes
+
+| Name | Type | Description |
+|------|------|-------------|
+| `base_url` | `Any` | |
+| `timeout` | `Any` | |
+
+### Methods
+
+#### LayerExecutor.run_command
+
+```python
+async def run_command(self, command: str, timeout: float | None = None) -> dict
+```
+
+Run a shell command via computer-server and return the result.
+
+#### LayerExecutor.execute_layer
+
+```python
+async def execute_layer(self, layer: dict) -> dict
+```
+
+Execute a single Image layer and return the result.
+
+#### LayerExecutor.execute_layers
+
+```python
+async def execute_layers(self, layers: list[dict]) -> list[dict]
+```
+
+Execute all layers sequentially. Raises on first failure.
+
+### create_overlay
+
+```python
+def create_overlay(backing: Path, overlay: Path) -> Path
+```
+
+Create a qcow2 overlay with the given backing file.
+
+---
+
+## interfaces
+
+---
+
+## Clipboard
+
+Clipboard read/write.
+
+### Constructor
+
+```python
+Clipboard(self, transport: Transport)
+```
+
+### Methods
+
+#### Clipboard.get
+
+```python
+async def get(self) -> str
+```
+
+Return the current clipboard text.
+
+#### Clipboard.set
+
+```python
+async def set(self, text: str) -> None
+```
+
+Set the clipboard text.
+
+---
+
+## Keyboard
+
+Keyboard control.
+
+### Constructor
+
+```python
+Keyboard(self, transport: Transport)
+```
+
+### Methods
+
+#### Keyboard.type
+
+```python
+async def type(self, text: str) -> None
+```
+
+Type a string of text.
+
+#### Keyboard.keypress
+
+```python
+async def keypress(self, keys: Union[List[str], str]) -> None
+```
+
+Press a key combination (e.g. ["ctrl", "c"] or "enter").
+
+#### Keyboard.key_down
+
+```python
+async def key_down(self, key: str) -> None
+```
+
+#### Keyboard.key_up
+
+```python
+async def key_up(self, key: str) -> None
+```
+
+---
+
+## Mobile
+
+Mobile (Android) touch and hardware-key control.
+
+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.
+
+### Constructor
+
+```python
+Mobile(self, transport: Transport)
+```
+
+### Methods
+
+#### Mobile.tap
+
+```python
+async def tap(self, x: int, y: int) -> None
+```
+
+#### Mobile.long_press
+
+```python
+async def long_press(self, x: int, y: int, duration_ms: int = 1000) -> None
+```
+
+#### Mobile.double_tap
+
+```python
+async def double_tap(self, x: int, y: int, delay: float = 0.1) -> None
+```
+
+#### Mobile.type_text
+
+```python
+async def type_text(self, text: str) -> None
+```
+
+#### Mobile.swipe
+
+```python
+async def swipe(self, x1: int, y1: int, x2: int, y2: int, duration_ms: int = 300) -> None
+```
+
+#### Mobile.scroll_up
+
+```python
+async def scroll_up(self, x: int, y: int, distance: int = 600, duration_ms: int = 400) -> None
+```
+
+#### Mobile.scroll_down
+
+```python
+async def scroll_down(self, x: int, y: int, distance: int = 600, duration_ms: int = 400) -> None
+```
+
+#### Mobile.scroll_left
+
+```python
+async def scroll_left(self, x: int, y: int, distance: int = 400, duration_ms: int = 300) -> None
+```
+
+#### Mobile.scroll_right
+
+```python
+async def scroll_right(self, x: int, y: int, distance: int = 400, duration_ms: int = 300) -> None
+```
+
+#### Mobile.fling
+
+```python
+async def fling(self, x1: int, y1: int, x2: int, y2: int) -> None
+```
+
+#### Mobile.gesture
+
+```python
+async def gesture(self, finger_paths: tuple[int, int] = (), duration_ms: int = 400, steps: int = 0) -> 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.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `duration_ms` | `Any` | Total gesture duration in milliseconds. |
+| `steps` | `Any` | Interpolation steps (0 = auto: duration_ms // 20, min 5). |
+
+#### Mobile.pinch_in
+
+```python
+async def pinch_in(self, cx: int, cy: int, spread: int = 300, duration_ms: int = 400) -> None
+```
+
+Pinch-in (zoom out) with two real simultaneous fingers.
+
+#### Mobile.pinch_out
+
+```python
+async def pinch_out(self, cx: int, cy: int, spread: int = 300, duration_ms: int = 400) -> None
+```
+
+Pinch-out (zoom in) with two real simultaneous fingers.
+
+#### Mobile.key
+
+```python
+async def key(self, keycode: int) -> None
+```
+
+#### Mobile.home
+
+```python
+async def home(self) -> None
+```
+
+#### Mobile.back
+
+```python
+async def back(self) -> None
+```
+
+#### Mobile.recents
+
+```python
+async def recents(self) -> None
+```
+
+#### Mobile.power
+
+```python
+async def power(self) -> None
+```
+
+#### Mobile.volume_up
+
+```python
+async def volume_up(self) -> None
+```
+
+#### Mobile.volume_down
+
+```python
+async def volume_down(self) -> None
+```
+
+#### Mobile.enter
+
+```python
+async def enter(self) -> None
+```
+
+#### Mobile.backspace
+
+```python
+async def backspace(self) -> None
+```
+
+#### Mobile.wake
+
+```python
+async def wake(self) -> None
+```
+
+#### Mobile.notifications
+
+```python
+async def notifications(self) -> None
+```
+
+#### Mobile.close_notifications
+
+```python
+async def close_notifications(self) -> None
+```
+
+---
+
+## Mouse
+
+Mouse control.
+
+### Constructor
+
+```python
+Mouse(self, transport: Transport)
+```
+
+### Methods
+
+#### Mouse.click
+
+```python
+async def click(self, x: int, y: int, button: str = 'left') -> None
+```
+
+#### Mouse.right_click
+
+```python
+async def right_click(self, x: int, y: int) -> None
+```
+
+#### Mouse.double_click
+
+```python
+async def double_click(self, x: int, y: int) -> None
+```
+
+#### Mouse.move
+
+```python
+async def move(self, x: int, y: int) -> None
+```
+
+#### Mouse.scroll
+
+```python
+async def scroll(self, x: int, y: int, scroll_x: int = 0, scroll_y: int = 3) -> None
+```
+
+#### Mouse.mouse_down
+
+```python
+async def mouse_down(self, x: int, y: int, button: str = 'left') -> None
+```
+
+#### Mouse.mouse_up
+
+```python
+async def mouse_up(self, x: int, y: int, button: str = 'left') -> None
+```
+
+#### Mouse.drag
+
+```python
+async def drag(self, start_x: int, start_y: int, end_x: int, end_y: int, button: str = 'left') -> None
+```
+
+---
+
+## Screen
+
+Screen capture and info.
+
+### Constructor
+
+```python
+Screen(self, transport: Transport)
+```
+
+### Methods
+
+#### Screen.screenshot
+
+```python
+async def screenshot(self, format: str = 'png', quality: int = 95) -> bytes
+```
+
+Capture a screenshot and return raw image bytes.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `format` | `Any` | "png" (lossless, default) or "jpeg" (lossy, ~5-10x smaller). |
+| `quality` | `Any` | JPEG quality 1-95, ignored for PNG. |
+
+#### Screen.screenshot_base64
+
+```python
+async def screenshot_base64(self, format: str = 'png', quality: int = 95) -> str
+```
+
+Capture a screenshot and return as a base64-encoded string.
+
+#### Screen.size
+
+```python
+async def size(self) -> Tuple[int, int]
+```
+
+Return (width, height) of the screen.
+
+---
+
+## Shell
+
+Shell command execution.
+
+### Constructor
+
+```python
+Shell(self, transport: Transport)
+```
+
+### Methods
+
+#### Shell.run
+
+```python
+async def run(self, command: str, timeout: int = 30) -> CommandResult
+```
+
+Run a shell command and return the result.
+
+---
+
+## Terminal
+
+PTY terminal sessions.
+
+### Constructor
+
+```python
+Terminal(self, transport: Transport)
+```
+
+### Methods
+
+#### Terminal.create
+
+```python
+async def create(self, shell: str = 'bash', cols: int = 80, rows: int = 24) -> dict
+```
+
+Create a new PTY session. Returns \{"pid": int, "cols": int, "rows": int\}.
+
+#### Terminal.send_input
+
+```python
+async def send_input(self, pid: int, data: str) -> None
+```
+
+Send input to a PTY session.
+
+#### Terminal.resize
+
+```python
+async def resize(self, pid: int, cols: int, rows: int) -> None
+```
+
+Resize a PTY session.
+
+#### Terminal.close
+
+```python
+async def close(self, pid: int) -> Optional[int]
+```
+
+Close a PTY session. Returns exit code.
+
+---
+
+## Tunnel
+
+Port-forwarding interface — exposes sandbox ports on the host.
+
+### Constructor
+
+```python
+Tunnel(self, transport: Transport)
+```
+
+### Methods
+
+#### Tunnel.forward
+
+```python
+def forward(self, ports: int | str = ()) -> _TunnelContext
+```
+
+Forward one or more sandbox ports (or abstract sockets) to the host.
+
+*ports* may be:
+- ``int`` — TCP port inside the sandbox (e.g. ``8080``)
+- ``str`` — Android abstract socket name (e.g. ``"chrome_devtools_remote"``)
+
+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
+
+Example — Chrome DevTools over ADB::
+
+ async with sb.tunnel.forward("chrome_devtools_remote") as t:
+ # http://localhost:&lt;random>/json lists CDP targets
+ print(t.url)
+
+---
+
+## TunnelInfo
+
+A single forwarded port.
+
+### Constructor
+
+```python
+TunnelInfo(self, host: str, port: int, sandbox_port: int) -> None
+```
+
+### Attributes
+
+| Name | Type | Description |
+|------|------|-------------|
+| `host` | `Any` | |
+| `port` | `Any` | |
+| `sandbox_port` | `Any` | |
+| `url` | `str` | |
+
+### Methods
+
+#### TunnelInfo.close
+
+```python
+async def close(self) -> None
+```
+
+Close this tunnel (no-op if already closed or inside a context manager).
+
+---
+
+## Window
+
+Window management.
+
+### Constructor
+
+```python
+Window(self, transport: Transport)
+```
+
+### Methods
+
+#### Window.get_active_title
+
+```python
+async def get_active_title(self) -> str
+```
+
+Return the title of the currently focused window.
diff --git a/docs/content/docs/cua/reference/sandbox-sdk/interfaces.mdx b/docs/content/docs/cua/reference/sandbox-sdk/interfaces.mdx
new file mode 100644
index 0000000000..c975eebc8c
--- /dev/null
+++ b/docs/content/docs/cua/reference/sandbox-sdk/interfaces.mdx
@@ -0,0 +1,303 @@
+---
+title: Sandbox Interfaces
+description: Reference for all sb.* sub-interfaces — shell, mouse, keyboard, screen, clipboard, tunnel, mobile, terminal, window
+---
+
+Every `Sandbox` instance exposes a set of sub-interfaces for interacting with the running environment. This page documents all of them.
+
+---
+
+## `sb.shell` — command execution
+
+Run shell commands and get their output.
+
+```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`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `command` | `str` | Shell command to run |
+| `timeout` | `int` | Seconds before the command is killed (default: 60) |
+
+`CommandResult` fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `stdout` | `str` | Standard output |
+| `stderr` | `str` | Standard error |
+| `returncode` | `int` | Exit code |
+| `success` | `bool` | `True` if `returncode == 0` |
+
+Multi-line scripts work naturally:
+
+```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.
+
+```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
+```
+
+### `await sb.mouse.click(x, y, button="left")`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `x`, `y` | `int` | Pixel coordinates |
+| `button` | `str` | `"left"` (default), `"right"`, `"middle"` |
+
+### `await sb.mouse.scroll(x, y, dx=0, dy=0)`
+
+| 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
+```
+
+### `await sb.keyboard.press(keys)`
+
+`keys` can be a string shorthand or a list:
+
+```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")
+```
+
+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
+```
+
+### `await sb.screenshot() → bytes`
+
+Returns a PNG image as raw bytes.
+
+```python
+png = await sb.screenshot()
+with open("shot.png", "wb") as f:
+ f.write(png)
+```
+
+### `await sb.screenshot_base64() → str`
+
+Returns a base64-encoded PNG string, ready to embed in HTML or pass to LLM vision APIs.
+
+```python
+b64 = await sb.screenshot_base64()
+# use directly in an OpenAI / Anthropic vision message
+```
+
+### `await sb.screen.size() → tuple[int, int]`
+
+Returns `(width, height)` of the sandbox display.
+
+```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.
+
+```python
+await sb.clipboard.write("Hello from Python")
+text = await sb.clipboard.read()
+print(text) # "Hello from Python"
+```
+
+### `await sb.clipboard.write(text: str)`
+
+Writes a string to the clipboard.
+
+### `await sb.clipboard.read() → str`
+
+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.
+
+```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)
+```
+
+Forward multiple ports at once:
+
+```python
+async with sb.tunnel.forward(8080, 9222) as tunnels:
+ app_url = tunnels[8080].url
+ devtools_url = tunnels[9222].url
+```
+
+### `sb.tunnel.forward(*ports) → async context manager`
+
+Returns a context manager. On enter, starts forwarding; on exit, tears down the tunnel.
+
+| Value | Type | Description |
+|-------|------|-------------|
+| `*ports` | `int` | One or more ports to forward from the sandbox |
+
+The context manager yields:
+- A single `TunnelInfo` when one port is passed
+- A `dict[int, TunnelInfo]` when multiple ports are passed
+
+`TunnelInfo` fields:
+
+| 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.
+
+```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()
+```
+
+### Multi-touch gestures
+
+Use `sb.mobile.gesture()` for multi-finger interactions like pinch-to-zoom:
+
+```python
+w, h = await sb.screen.size()
+cx, cy = w // 2, h // 2
+
+# 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
+)
+
+# 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),
+)
+```
+
+---
+
+## `sb.terminal` — interactive PTY shell
+
+Open an interactive terminal session with full PTY support. Use this when you need to run interactive programs that expect a real terminal.
+
+```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).
+
+```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.
+
+```python
+from cua_sandbox import Localhost
+
+async with Localhost.connect() as host:
+ result = await host.shell.run("echo hello")
+ await host.mouse.click(100, 200)
+ png = await host.screenshot()
+```
+
+All `sb.*` interfaces (`shell`, `mouse`, `keyboard`, `screen`, `clipboard`) are available on a `Localhost` instance. `tunnel` and `mobile` are not applicable.
diff --git a/docs/content/docs/cua/reference/sandbox-sdk/meta.json b/docs/content/docs/cua/reference/sandbox-sdk/meta.json
new file mode 100644
index 0000000000..2c02f8ea4d
--- /dev/null
+++ b/docs/content/docs/cua/reference/sandbox-sdk/meta.json
@@ -0,0 +1,5 @@
+{
+ "title": "Sandbox SDK",
+ "icon": "Box",
+ "pages": ["index", "interfaces"]
+}
diff --git a/docs/src/app/(docs)/layout.tsx b/docs/src/app/(docs)/layout.tsx
index 87dec8755b..e019342460 100644
--- a/docs/src/app/(docs)/layout.tsx
+++ b/docs/src/app/(docs)/layout.tsx
@@ -1,6 +1,6 @@
import { CustomHeader } from '@/components/custom-header';
+import { ScopedDocsLayout } from '@/components/scoped-docs-layout';
import { source } from '@/lib/source';
-import { DocsLayout } from 'fumadocs-ui/layouts/docs';
import type { ReactNode } from 'react';
export default function Layout({ children }: { children: ReactNode }) {
@@ -8,22 +8,7 @@ export default function Layout({ children }: { children: ReactNode }) {
<>
<CustomHeader />
<div className="pt-14">
- <DocsLayout
- tree={source.pageTree}
- nav={{ enabled: false }}
- searchToggle={{ enabled: false }}
- themeSwitch={{ enabled: false }}
- sidebar={{
- // Disable automatic tabs - we use header navigation instead
- tabs: false,
- // Disable collapse/expand button
- collapsible: false,
- // Add top spacing in sidebar
- banner: <div className="h-6" />,
- }}
- >
- {children}
- </DocsLayout>
+ <ScopedDocsLayout tree={source.pageTree}>{children}</ScopedDocsLayout>
</div>
</>
);
diff --git a/docs/src/components/scoped-docs-layout.tsx b/docs/src/components/scoped-docs-layout.tsx
new file mode 100644
index 0000000000..bf27444c76
--- /dev/null
+++ b/docs/src/components/scoped-docs-layout.tsx
@@ -0,0 +1,86 @@
+'use client';
+
+import { usePathname } from 'next/navigation';
+import { DocsLayout } from 'fumadocs-ui/layouts/docs';
+import type { Root, Node, Folder } from 'fumadocs-core/page-tree';
+import type { ReactNode } from 'react';
+
+// Must match the navTabs prefixes defined in custom-header.tsx
+const SECTION_PREFIXES = [
+ '/cua/guide',
+ '/cua/examples',
+ '/cua/reference',
+ '/cuabench/guide',
+ '/cuabench/examples',
+ '/cuabench/reference',
+ '/lume/guide',
+ '/lume/examples',
+ '/lume/reference',
+ '/cuabot/guide',
+ '/cuabot/reference',
+];
+
+function hasDescendantWithPrefix(nodes: Node[], prefix: string): boolean {
+ for (const node of nodes) {
+ if (node.type === 'page' && node.url.startsWith(prefix)) return true;
+ if (node.type === 'folder') {
+ if (node.index?.url?.startsWith(prefix)) return true;
+ if (hasDescendantWithPrefix(node.children, prefix)) return true;
+ }
+ }
+ return false;
+}
+
+function findFolder(nodes: Node[], prefix: string): Folder | null {
+ for (const node of nodes) {
+ if (node.type !== 'folder') continue;
+ if (!hasDescendantWithPrefix([node], prefix)) continue;
+
+ // This folder is the right level if its direct children match the prefix
+ const isDirectParent = node.children.some(
+ (c: Node) =>
+ (c.type === 'page' && c.url.startsWith(prefix)) ||
+ (c.type === 'folder' &&
+ (c.index?.url?.startsWith(prefix) || hasDescendantWithPrefix(c.children, prefix)))
+ );
+
+ if (isDirectParent) return node;
+
+ const deeper = findFolder(node.children, prefix);
+ if (deeper) return deeper;
+ }
+ return null;
+}
+
+function filterTree(tree: Root, prefix: string): Root {
+ const folder = findFolder(tree.children, prefix);
+ if (!folder) return tree;
+ return { ...tree, children: folder.children };
+}
+
+interface Props {
+ tree: Root;
+ children: ReactNode;
+}
+
+export function ScopedDocsLayout({ tree, children }: Props) {
+ const pathname = usePathname();
+ const prefix = SECTION_PREFIXES.find((p) => pathname.startsWith(p)) ?? null;
+ const scopedTree = prefix ? filterTree(tree, prefix) : tree;
+
+ return (
+ <DocsLayout
+ tree={scopedTree}
+ nav={{ enabled: false }}
+ searchToggle={{ enabled: false }}
+ themeSwitch={{ enabled: false }}
+ sidebar={{
+ tabs: false,
+ collapsible: false,
+ banner: <div className="h-6" />,
+ }}
+ >
+ {children}
+ </DocsLayout>
+ );
+}
diff --git a/examples/agent_examples.py b/examples/agent_examples.py
deleted file mode 100644
index 31e82886ac..0000000000
--- a/examples/agent_examples.py
+++ /dev/null
@@ -1,129 +0,0 @@
-"""Example demonstrating the ComputerAgent capabilities with the Omni provider."""
-
-import asyncio
-import logging
-import signal
-import traceback
-
-# Import the unified agent class and types
-from agent import ComputerAgent
-from computer import Computer, VMProviderType
-
-# Import utility functions
-from utils import handle_sigint, load_dotenv_files
-
-# Set up logging
-logging.basicConfig(level=logging.INFO)
-logger = logging.getLogger(__name__)
-
-
-async def run_agent_example():
- """Run example of using the ComputerAgent with different models."""
- print("\n=== Example: ComputerAgent with different models ===")
-
- try:
- # Create a local macOS computer
- computer = Computer(
- os_type="macos",
- verbosity=logging.DEBUG,
- )
-
- # Create a remote Linux computer with Cua
- # computer = Computer(
- # os_type="linux",
- # api_key=os.getenv("CUA_API_KEY"),
- # name=os.getenv("CUA_CONTAINER_NAME"),
- # provider_type=VMProviderType.CLOUD,
- # )
-
- # Create ComputerAgent with new API
- agent = ComputerAgent(
- # Supported models:
- # == OpenAI Cua (computer-use-preview) ==
- model="openai/computer-use-preview",
- # == Anthropic Cua (Claude > 3.5) ==
- # model="anthropic/claude-opus-4-20250514",
- # model="anthropic/claude-sonnet-4-20250514",
- # model="anthropic/claude-3-7-sonnet-20250219",
- # model="anthropic/claude-sonnet-4-5-20250929",
- # == UI-TARS ==
- # model="huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B",
- # model="mlx/mlx-community/UI-TARS-1.5-7B-6bit",
- # model="ollama_chat/0000/ui-tars-1.5-7b",
- # == Omniparser + Any LLM ==
- # model="omniparser+anthropic/claude-opus-4-20250514",
- # model="omniparser+ollama_chat/gemma3:12b-it-q4_K_M",
- # == Omniparser + Vertex AI Gemini 3 (with thinking_level) ==
- # model="omni+vertex_ai/gemini-3-flash",
- # thinking_level="high", # or "low"
- # media_resolution="medium", # or "low" or "high"
- tools=[computer],
- only_n_most_recent_images=3,
- verbosity=logging.DEBUG,
- trajectory_dir="trajectories",
- use_prompt_caching=True,
- max_trajectory_budget=1.0,
- )
-
- # Example tasks to demonstrate the agent
- tasks = [
- "Look for a repository named trycua/cua on GitHub.",
- "Check the open issues, open the most recent one and read it.",
- "Clone the repository in users/lume/projects if it doesn't exist yet.",
- "Open the repository with an app named Cursor (on the dock, black background and white cube icon).",
- "From Cursor, open Composer if not already open.",
- "Focus on the Composer text area, then write and submit a task to help resolve the GitHub issue.",
- ]
-
- # Use message-based conversation history
- history = []
-
- for i, task in enumerate(tasks):
- print(f"\nExecuting task {i+1}/{len(tasks)}: {task}")
-
- # Add user message to history
- history.append({"role": "user", "content": task})
-
- # Run agent with conversation history
- async for result in agent.run(history, stream=False):
- # Add agent outputs to history
- history += result.get("output", [])
-
- # Print output for debugging
- for item in result.get("output", []):
- if item.get("type") == "message":
- content = item.get("content", [])
- for content_part in content:
- if content_part.get("text"):
- print(f"Agent: {content_part.get('text')}")
- elif item.get("type") == "computer_call":
- action = item.get("action", {})
- action_type = action.get("type", "")
- print(f"Computer Action: {action_type}({action})")
- elif item.get("type") == "computer_call_output":
- print("Computer Output: [Screenshot/Result]")
-
- print(f"✅ Task {i+1}/{len(tasks)} completed: {task}")
-
- except Exception as e:
- logger.error(f"Error in run_agent_example: {e}")
- traceback.print_exc()
- raise
-
-
-def main():
- """Run the Anthropic agent example."""
- try:
- load_dotenv_files()
-
- # Register signal handler for graceful exit
- signal.signal(signal.SIGINT, handle_sigint)
-
- asyncio.run(run_agent_example())
- except Exception as e:
- print(f"Error running example: {e}")
- traceback.print_exc()
-
-
-if __name__ == "__main__":
- main()
diff --git a/examples/agent_ui_examples.py b/examples/agent_ui_examples.py
deleted file mode 100644
index 97f54856cc..0000000000
--- a/examples/agent_ui_examples.py
+++ /dev/null
@@ -1,25 +0,0 @@
-#!/usr/bin/env python3
-"""
-Simple example script for the Computer-Use Agent Gradio UI.
-
-This script launches the advanced Gradio UI for the Computer-Use Agent
-with full model selection and configuration options.
-It can be run directly from the command line.
-"""
-
-
-from utils import load_dotenv_files
-
-load_dotenv_files()
-
-# Import the create_gradio_ui function
-from agent.ui.gradio.ui_components import create_gradio_ui
-
-if __name__ == "__main__":
- print("Launching Computer-Use Agent Gradio UI with advanced features...")
- app = create_gradio_ui()
- app.launch(
- share=False,
- server_name="0.0.0.0",
- server_port=7860,
- )
diff --git a/examples/browser_agent_example.py b/examples/browser_agent_example.py
deleted file mode 100644
index 63be92153a..0000000000
--- a/examples/browser_agent_example.py
+++ /dev/null
@@ -1,97 +0,0 @@
-"""
-Browser Agent Example
-
-Demonstrates how to use the ComputerAgent with BrowserTool to control a browser
-programmatically via the computer server using Azure AI model (Fara-7B).
-
-Prerequisites:
- - Computer server running (Docker container or local)
- - For Docker: Container should be running with browser tool support
- - For local: Playwright and Firefox must be installed
-
-Usage:
- python examples/browser_agent_example.py
-"""
-
-import asyncio
-import logging
-import signal
-import sys
-import traceback
-from pathlib import Path
-
-# Add the libs path to sys.path
-libs_path = Path(__file__).parent.parent / "libs" / "python"
-sys.path.insert(0, str(libs_path))
-
-from agent import ComputerAgent
-from agent.tools import BrowserTool
-from computer import Computer
-
-# Import utility functions
-from utils import handle_sigint, load_dotenv_files
-
-# Configure logging to see what's happening
-logging.basicConfig(level=logging.INFO)
-logger = logging.getLogger(__name__)
-
-
-async def run_browser_agent_example():
- """Run example of using ComputerAgent with BrowserTool."""
- print("\n=== Example: ComputerAgent with BrowserTool (Azure AI - Fara-7B) ===")
-
- try:
- # Initialize the computer interface
- # For local testing, use provider_type="docker"
- # For provider_type="cloud", provide name and api_key
- computer = Computer(
- provider_type="docker",
- os_type="linux",
- image="cua-xfce:dev",
- # verbosity=logging.DEBUG,
- )
- await computer.run()
-
- # Initialize the browser tool with the computer interface
- browser = BrowserTool(interface=computer)
-
- # Create ComputerAgent with BrowserTool
- agent = ComputerAgent(
- model="azure_ml/Fara-7B",
- tools=[browser],
- api_base="https://foundry-inference-gxttr.centralus.inference.ml.azure.com",
- api_key="YOUR API KEY HERE",
- only_n_most_recent_images=3,
- # verbosity=logging.DEBUG,
- trajectory_dir="trajectories",
- max_trajectory_budget=1.0,
- )
-
- # Open playground UI
- agent.open()
-
- # Wait until key press
- input("Press enter to exit")
-
- except Exception as e:
- logger.error(f"Error in run_browser_agent_example: {e}")
- traceback.print_exc()
- raise
-
-
-def main():
- """Run the browser agent example."""
- try:
- load_dotenv_files()
-
- # Register signal handler for graceful exit
- signal.signal(signal.SIGINT, handle_sigint)
-
- asyncio.run(run_browser_agent_example())
- except Exception as e:
- print(f"Error running example: {e}")
- traceback.print_exc()
-
-
-if __name__ == "__main__":
- main()
diff --git a/examples/browser_tool_example.py b/examples/browser_tool_example.py
deleted file mode 100644
index e5767f27c8..0000000000
--- a/examples/browser_tool_example.py
+++ /dev/null
@@ -1,119 +0,0 @@
-"""
-Browser Tool Example
-
-Demonstrates how to use the BrowserTool to control a browser programmatically
-via the computer server. The browser runs visibly on the XFCE desktop so visual
-agents can see it.
-
-Prerequisites:
- - Computer server running (Docker container or local)
- - For Docker: Container should be running with browser tool support
- - For local: Playwright and Firefox must be installed
-
-Usage:
- python examples/browser_tool_example.py
-"""
-
-import asyncio
-import logging
-import sys
-from pathlib import Path
-
-# Add the libs path to sys.path
-libs_path = Path(__file__).parent.parent / "libs" / "python"
-sys.path.insert(0, str(libs_path))
-
-from agent.tools.browser_tool import BrowserTool
-
-# Import Computer interface and BrowserTool
-from computer import Computer
-
-# Configure logging to see what's happening
-logging.basicConfig(level=logging.INFO)
-logger = logging.getLogger(__name__)
-
-
-async def test_browser_tool():
- """Test the BrowserTool with various commands."""
-
- # Initialize the computer interface
- # For local testing, use provider_type="docker"
- # For provider_type="cloud", provide name and api_key
- computer = Computer(provider_type="docker", os_type="linux", image="cua-xfce:dev")
- await computer.run()
-
- # Initialize the browser tool with the computer interface
- browser = BrowserTool(interface=computer)
-
- logger.info("Testing Browser Tool...")
-
- try:
- # Test 0: Take a screenshot (pre-init)
- logger.info("Test 0: Taking a screenshot...")
- screenshot_bytes = await browser.screenshot()
- screenshot_path = Path(__file__).parent / "browser_screenshot_init.png"
- with open(screenshot_path, "wb") as f:
- f.write(screenshot_bytes)
- logger.info(f"Screenshot captured: {len(screenshot_bytes)} bytes")
-
- # Test 1: Visit a URL
- logger.info("Test 1: Visiting a URL...")
- result = await browser.visit_url("https://www.trycua.com")
- logger.info(f"Visit URL result: {result}")
-
- # Wait a bit for the page to load
- await asyncio.sleep(2)
-
- # Test 2: Take a screenshot
- logger.info("Test 2: Taking a screenshot...")
- screenshot_bytes = await browser.screenshot()
- screenshot_path = Path(__file__).parent / "browser_screenshot.png"
- with open(screenshot_path, "wb") as f:
- f.write(screenshot_bytes)
- logger.info(f"Screenshot captured: {len(screenshot_bytes)} bytes")
-
- # Wait a bit
- await asyncio.sleep(1)
-
- # Test 3: Visit bot detector
- logger.info("Test 3: Visiting bot detector...")
- result = await browser.visit_url("https://bot-detector.rebrowser.net/")
- logger.info(f"Visit URL result: {result}")
-
- # Test 2: Web search
- logger.info("Test 2: Performing a web search...")
- result = await browser.web_search("Python programming")
- logger.info(f"Web search result: {result}")
-
- # Wait a bit
- await asyncio.sleep(2)
-
- # Test 3: Scroll
- logger.info("Test 3: Scrolling the page...")
- result = await browser.scroll(delta_x=0, delta_y=500)
- logger.info(f"Scroll result: {result}")
-
- # Wait a bit
- await asyncio.sleep(1)
-
- # Test 4: Click (example coordinates - adjust based on your screen)
- logger.info("Test 4: Clicking at coordinates...")
- result = await browser.click(x=500, y=300)
- logger.info(f"Click result: {result}")
-
- # Wait a bit
- await asyncio.sleep(1)
-
- # Test 5: Type text (if there's a focused input field)
- logger.info("Test 5: Typing text...")
- result = await browser.type("Hello from BrowserTool!")
- logger.info(f"Type result: {result}")
-
- logger.info("All tests completed!")
-
- except Exception as e:
- logger.error(f"Error during testing: {e}", exc_info=True)
-
-
-if __name__ == "__main__":
- asyncio.run(test_browser_tool())
diff --git a/examples/cloud_api_examples.py b/examples/cloud_api_examples.py
deleted file mode 100644
index 3444aa30ff..0000000000
--- a/examples/cloud_api_examples.py
+++ /dev/null
@@ -1,72 +0,0 @@
-import asyncio
-import os
-
-from utils import load_dotenv_files
-
-load_dotenv_files()
-
-from computer.providers.cloud.provider import CloudProvider
-
-
-async def main() -> None:
- # CloudProvider will automatically read CUA_API_KEY from environment if not provided
- # You can still pass api_key explicitly if needed: CloudProvider(api_key="your_key")
- api_base = os.getenv("CUA_API_BASE")
- if api_base:
- print(f"Using API base: {api_base}")
-
- provider = CloudProvider(verbose=True)
- async with provider:
-
- # List all VMs
- vms = await provider.list_vms()
- print(f"Found {len(vms)} VM(s)")
- for vm in vms:
- print(
- f"name: {vm['name']}\n",
- f"status: {vm['status']}\n", # pending, running, stopped, terminated, failed
- f"api_url: {vm.get('api_url')}\n",
- f"vnc_url: {vm.get('vnc_url')}\n",
- )
-
- # # --- Additional operations (commented out) ---
- # # To stop a VM by name:
- # name = "m-linux-96lcxd2c2k"
- # resp = await provider.stop_vm(name)
- # print(
- # "stop_vm response:\n",
- # f"name: {resp['name']}\n",
- # f"status: {resp['status']}\n", # stopping
- # )
-
- # # To start a VM by name:
- # name = "m-linux-96lcxd2c2k"
- # resp = await provider.run_vm(name)
- # print(
- # "run_vm response:\n",
- # f"name: {resp['name']}\n",
- # f"status: {resp['status']}\n", # starting
- # )
-
- # # To restart a VM by name:
- # name = "m-linux-96lcxd2c2k"
- # resp = await provider.restart_vm(name)
- # print(
- # "restart_vm response:\n",
- # f"name: {resp['name']}\n",
- # f"status: {resp['status']}\n", # restarting
- # )
-
- # # To probe a VM's status via its public hostname (if you know the name):
- # name = "m-linux-96lcxd2c2k"
- # info = await provider.get_vm(name)
- # print("get_vm info:\n",
- # f"name: {info['name']}\n",
- # f"status: {info['status']}\n", # running
- # f"api_url: {info.get('api_url')}\n",
- # f"os_type: {info.get('os_type')}\n",
- # )
-
-
-if __name__ == "__main__":
- asyncio.run(main())
diff --git a/examples/computer_examples.py b/examples/computer_examples.py
deleted file mode 100644
index 7e990e8bc3..0000000000
--- a/examples/computer_examples.py
+++ /dev/null
@@ -1,122 +0,0 @@
-import asyncio
-import os
-import sys
-import traceback
-from pathlib import Path
-
-# Load environment variables from .env file
-project_root = Path(__file__).parent.parent
-env_file = project_root / ".env"
-print(f"Loading environment from: {env_file}")
-from dotenv import load_dotenv
-
-load_dotenv(env_file)
-
-# Add paths to sys.path if needed
-pythonpath = os.environ.get("PYTHONPATH", "")
-for path in pythonpath.split(":"):
- if path and path not in sys.path:
- sys.path.insert(0, path) # Insert at beginning to prioritize
- print(f"Added to sys.path: {path}")
-
-from computer.computer import Computer
-from computer.logger import LogLevel
-from computer.providers.base import VMProviderType
-
-
-async def main():
- try:
- print("\n=== Using direct initialization ===")
-
- # Create a local macOS computer
- computer = Computer(
- display="1024x768",
- memory="8GB",
- cpu="4",
- os_type="macos",
- name="macos",
- verbosity=LogLevel.VERBOSE,
- provider_type=VMProviderType.LUME,
- storage="/Users/<USER>/repos/trycua/computer/examples/storage",
- shared_directories=["/Users/<USER>/repos/trycua/computer/examples/shared"],
- ephemeral=False,
- )
-
- # Create a remote Linux computer with Cua
- # computer = Computer(
- # os_type="linux",
- # api_key=os.getenv("CUA_API_KEY"),
- # name=os.getenv("CONTAINER_NAME"),
- # provider_type=VMProviderType.CLOUD,
- # )
-
- try:
- # Run the computer with default parameters
- await computer.run()
-
- screenshot = await computer.interface.screenshot()
-
- # Create output directory if it doesn't exist
- output_dir = Path("./output")
- output_dir.mkdir(exist_ok=True)
-
- screenshot_path = output_dir / "screenshot.png"
- with open(screenshot_path, "wb") as f:
- f.write(screenshot)
- print(f"Screenshot saved to: {screenshot_path.absolute()}")
-
- # await computer.interface.hotkey("command", "space")
-
- # res = await computer.interface.run_command("touch ./Downloads/empty_file")
- # print(f"Run command result: {res}")
-
- accessibility_tree = await computer.interface.get_accessibility_tree()
- print(f"Accessibility tree: {accessibility_tree}")
-
- # Screen Actions Examples
- # print("\n=== Screen Actions ===")
- # screenshot = await computer.interface.screenshot()
- # with open("screenshot_direct.png", "wb") as f:
- # f.write(screenshot)
-
- screen_size = await computer.interface.get_screen_size()
- print(f"Screen size: {screen_size}")
-
- # Demonstrate coordinate conversion
- center_x, center_y = 733, 736
- print(f"Center in screen coordinates: ({center_x}, {center_y})")
-
- screenshot_center = await computer.to_screenshot_coordinates(center_x, center_y)
- print(f"Center in screenshot coordinates: {screenshot_center}")
-
- screen_center = await computer.to_screen_coordinates(*screenshot_center)
- print(f"Back to screen coordinates: {screen_center}")
-
- # Mouse Actions Examples
- print("\n=== Mouse Actions ===")
- await computer.interface.move_cursor(100, 100)
- await computer.interface.left_click()
- await computer.interface.right_click(300, 300)
- await computer.interface.double_click(400, 400)
-
- # Keyboard Actions Examples
- print("\n=== Keyboard Actions ===")
- await computer.interface.type_text("Hello, World!")
- await computer.interface.press_key("enter")
-
- # Clipboard Actions Examples
- print("\n=== Clipboard Actions ===")
- await computer.interface.set_clipboard("Test clipboard")
- content = await computer.interface.copy_to_clipboard()
- print(f"Clipboard content: {content}")
-
- finally:
- # Important to clean up resources
- await computer.stop()
- except Exception as e:
- print(f"Error in main: {e}")
- traceback.print_exc()
-
-
-if __name__ == "__main__":
- asyncio.run(main())
diff --git a/examples/computer_examples_windows.py b/examples/computer_examples_windows.py
deleted file mode 100644
index 19d228bf76..0000000000
--- a/examples/computer_examples_windows.py
+++ /dev/null
@@ -1,145 +0,0 @@
-import asyncio
-import os
-import sys
-import traceback
-from pathlib import Path
-
-# Load environment variables from .env file
-project_root = Path(__file__).parent.parent
-env_file = project_root / ".env"
-print(f"Loading environment from: {env_file}")
-from computer.helpers import sandboxed
-from dotenv import load_dotenv
-
-load_dotenv(env_file)
-
-# Add paths to sys.path if needed
-pythonpath = os.environ.get("PYTHONPATH", "")
-for path in pythonpath.split(":"):
- if path and path not in sys.path:
- sys.path.insert(0, path) # Insert at beginning to prioritize
- print(f"Added to sys.path: {path}")
-
-from computer.computer import Computer
-from computer.logger import LogLevel
-from computer.providers.base import VMProviderType
-
-# ANSI color codes
-RED = "\033[91m"
-RESET = "\033[0m"
-
-
-async def main():
- try:
- print("\n=== Using direct initialization ===")
-
- # Create a remote Windows computer with Cua
- computer = Computer(
- os_type="windows",
- api_key=os.getenv("CUA_API_KEY"),
- name=os.getenv("CONTAINER_NAME") or "",
- provider_type=VMProviderType.CLOUD,
- )
-
- try:
- # Run the computer with default parameters
- await computer.run()
-
- # Create output directory if it doesn't exist
- output_dir = Path("./output")
- output_dir.mkdir(exist_ok=True)
-
- # Keyboard Actions Examples
- print("\n=== Keyboard Actions ===")
- await computer.interface.type_text("Hello, World!")
- await computer.interface.press_key("enter")
-
- # Mouse Actions Examples
- print("\n=== Mouse Actions ===")
- await computer.interface.move_cursor(100, 100)
- await computer.interface.left_click()
- await computer.interface.double_click(400, 400)
- await computer.interface.right_click(300, 300)
-
- print("\n=== RPC ===")
- await computer.venv_install("demo_venv", ["mss"])
-
- @sandboxed("demo_venv")
- def greet_and_print(name):
- import os
-
- from mss import mss
-
- # get username
- username = os.getlogin()
- print(f"Hello from inside the container, {name}!")
- print("Username:", username)
- print("Screens:", mss().monitors)
-
- # take a screenshot
- with mss() as sct:
- filename = sct.shot(mon=-1, output="C:/Users/azureuser/Desktop/fullscreen.png")
- print(filename)
-
- return {"greeted": name, "username": username}
-
- # Call with args and kwargs
- result = await greet_and_print("John Doe")
- print("Result from sandboxed function:", result)
-
- # Command Actions Examples
- print("\n=== Command Actions ===")
- result = await computer.interface.run_command("notepad")
- print("Result from command:", result)
-
- screenshot = await computer.interface.screenshot()
- screenshot_path = output_dir / "screenshot.png"
- with open(screenshot_path, "wb") as f:
- f.write(screenshot)
- print(f"Screenshot saved to: {screenshot_path.absolute()}")
-
- # Clipboard Actions Examples
- print("\n=== Clipboard Actions ===")
- await computer.interface.set_clipboard("Test clipboard")
- content = await computer.interface.copy_to_clipboard()
- print(f"Clipboard content: {content}")
-
- # Simple REPL Loop
- print("\n=== Command REPL ===")
- print("Enter commands to run on the remote computer.")
- print("Type 'exit' or 'quit' to leave the REPL.\n")
-
- while True:
- try:
- # Get command from user
- command = input("command> ").strip()
-
- # Check for exit commands
- if command.lower() in ["exit", "quit", ""]:
- if command.lower() in ["exit", "quit"]:
- print("Exiting REPL...")
- break
-
- # Run the command
- result = await computer.interface.run_command(command)
-
- print(result.stdout)
- if result.stderr:
- print(f"{RED}{result.stderr}{RESET}")
- except KeyboardInterrupt:
- print("\nExiting REPL...")
- break
- except Exception as e:
- print(f"{RED}Error running command: {e}{RESET}")
-
- finally:
- # Important to clean up resources
- # await computer.stop()
- pass
- except Exception as e:
- print(f"Error in main: {e}")
- traceback.print_exc()
-
-
-if __name__ == "__main__":
- asyncio.run(main())
diff --git a/examples/computer_ui_examples.py b/examples/computer_ui_examples.py
deleted file mode 100644
index 2151b9d88d..0000000000
--- a/examples/computer_ui_examples.py
+++ /dev/null
@@ -1,31 +0,0 @@
-#!/usr/bin/env python3
-"""
-Simple example script for the Computer Interface Gradio UI.
-
-This script launches the advanced Gradio UI for the Computer Interface
-with full model selection and configuration options.
-It can be run directly from the command line.
-"""
-
-
-from utils import load_dotenv_files
-
-load_dotenv_files()
-
-# Import the create_gradio_ui function
-from computer.ui.gradio.app import create_gradio_ui
-
-if __name__ == "__main__":
- print("Launching Computer Interface Gradio UI with advanced features...")
- app = create_gradio_ui()
- app.launch(
- share=False,
- server_name="0.0.0.0",
- server_port=7860,
- )
-
- # Optional: Using the saved dataset
- # import datasets
- # from computer.ui.utils import convert_to_unsloth
- # ds = datasets.load_dataset("ddupont/highquality-cua-demonstrations")
- # ds = convert_to_unsloth(ds)
diff --git a/examples/docker_examples.py b/examples/docker_examples.py
deleted file mode 100644
index 84af0f5908..0000000000
--- a/examples/docker_examples.py
+++ /dev/null
@@ -1,46 +0,0 @@
-import asyncio
-import os
-
-from computer import Computer, VMProviderType
-from computer.providers.factory import VMProviderFactory
-
-
-async def main():
- # # Create docker provider
- # provider = VMProviderFactory.create_provider(
- # provider_type="docker",
- # image="cua-ubuntu:latest", # Your Cua Ubuntu image
- # port=8080,
- # vnc_port=6901
- # )
-
- # # Run a container
- # async with provider:
- # vm_info = await provider.run_vm(
- # image="cua-ubuntu:latest",
- # name="my-cua-container",
- # run_opts={
- # "memory": "4GB",
- # "cpu": 2,
- # "vnc_port": 6901,
- # "api_port": 8080
- # }
- # )
- # print(vm_info)
-
- computer = Computer(
- os_type="linux",
- provider_type=VMProviderType.DOCKER,
- name="my-cua-container",
- image="cua-ubuntu:latest",
- )
-
- await computer.run()
-
- screenshot = await computer.interface.screenshot()
- with open("screenshot_docker.png", "wb") as f:
- f.write(screenshot)
-
-
-if __name__ == "__main__":
- asyncio.run(main())
diff --git a/examples/evals/hud_eval_examples.py b/examples/evals/hud_eval_examples.py
deleted file mode 100644
index a734d71e28..0000000000
--- a/examples/evals/hud_eval_examples.py
+++ /dev/null
@@ -1,103 +0,0 @@
-"""
-hud_eval_examples.py — minimal HUD evaluation runner
-
-- Auto-discovers .env anywhere up the directory tree (via find_dotenv)
-- Requires HUD_API_KEY in the resolved environment
-- No Docker/local computer usage
-"""
-
-# imports
-import asyncio
-import logging
-import os
-import uuid
-from pathlib import Path
-from pprint import pprint
-
-from agent import ComputerAgent
-from agent.integrations.hud import run_full_dataset
-from dotenv import find_dotenv, load_dotenv
-
-"""
-Loading env
-"""
-
-
-def load_env_or_fail() -> None:
- # Walk up from CWD / file dir to find nearest .env
- env_path = find_dotenv(usecwd=False)
- if not env_path:
- raise FileNotFoundError(
- "❌ .env not found. Place a .env at your repo root (or export HUD_API_KEY)."
- )
- load_dotenv(env_path, override=True)
- if not os.getenv("HUD_API_KEY"):
- raise EnvironmentError("❌ HUD_API_KEY is missing in the loaded environment")
-
-
-"""
-Build Agent Config
-- customize agent behavior, tool integration, callbacks, resource management, and more
-- https://cua.ai/docs/agent-sdk/agent-loops#parameters
-- https://cua.ai/docs/agent-sdk/supported-model-providers
-"""
-
-
-def build_agent_config() -> dict:
-
- instruction = "You are a computer-using agent graded by deterministic checkers."
-
- return {
- "model": "openai/computer-use-preview",
- "trajectory_dir": str(Path("trajectories")),
- "only_n_most_recent_images": 3,
- "verbosity": logging.INFO,
- "instruction": instruction,
- }
-
-
-"""
-Hud Eval
-"""
-
-
-async def run_hud_eval() -> None:
- # load env and agent config
- load_env_or_fail()
- agent_config = build_agent_config()
-
- # Initialize to ensure config is valid (tools, verbosity, etc.)
- _ = ComputerAgent(**agent_config)
-
- job_name = (
- f"osworld-test-{str(uuid.uuid4())[:4]}" # job name (each run of your task is a job on hud)
- )
- print(f"🚀 Running HUD eval: {job_name}")
-
- """
- Customize your hud eval below, check the doc for additional params
- - https://cua.ai/docs/agent-sdk/integrations/hud#parameters-1
- - recommend low max steps (5-10) for testing, then max 100 for benchmarking
- - also select specific tasks to run by using splitting the dataset
- """
- results = await run_full_dataset(
- dataset="ddupont/OSWorld-Tiny-Public",
- job_name=job_name,
- **agent_config,
- max_concurrent=20,
- max_steps=50,
- # split="train[0:1]"
- )
-
- print(f"\n📊 Job: {job_name}")
- print(f"Total results: {len(results)}")
- pprint(results[:3])
-
-
-def main() -> None:
- logging.basicConfig(level=logging.INFO)
- asyncio.run(run_hud_eval())
-
-
-if __name__ == "__main__":
- main()
diff --git a/examples/evals/wikipedia_most_linked.txt b/examples/evals/wikipedia_most_linked.txt
deleted file mode 100644
index 877909d29f..0000000000
--- a/examples/evals/wikipedia_most_linked.txt
+++ /dev/null
@@ -1,1000 +0,0 @@
-ISBN (identifier)
-United States
-Main Page
-Tilde
-Doi (identifier)
-Fair use
-Association football
-Years
-Wayback Machine
-ISSN (identifier)
-India
-Wikimedia Foundation
-Wikidata
-Animal
-Taxonomy (biology)
-Australia
-France
-Eukaryote
-IP address
-U.S. state
-Time zone
-City
-Copyright
-Canada
-Town
-ASCII
-Greek alphabet
-Typographic ligature
-Diacritical mark
-Wikipedia
-Germany
-Human settlement
-Open Tree of Life
-IMDb (identifier)
-United Kingdom
-Catalogue of Life
-Insect
-Russia
-Japan
-Italy
-Arthropod
-Television show
-Public domain
-INaturalist
-Poland
-England
-PMID (identifier)
-Daylight saving time
-S2CID (identifier)
-China
-Encyclopedia of Life
-Spain
-OCLC (identifier)
-Plant
-Flickr
-Wikispecies
-Africa
-Song
-Record label
-Lepidoptera
-Iran
-English language
-Music genre
-News aggregator
-Web feed
-Proxy server
-X-Forwarded-For
-College football
-World War II
-Brazil
-Sweden
-Politics
-Olympics
-Netherlands
-Record producer
-California
-New York City
-Surname
-The New York Times
-London
-New Zealand
-PMC (identifier)
-Logo
-Synonym (taxonomy)
-Switzerland
-Turkey
-Sport
-Video game
-Architecture
-Norway
-Bibcode (identifier)
-Mexico
-Botany
-JSTOR (identifier)
-Rail transport
-Field hockey
-Ireland
-Scotland
-Belgium
-South Africa
-Common name
-Professional sports
-Sport governing body
-Sport industry
-Olympic games
-Election
-Austria
-Ukraine
-Anthroponymy
-Pakistan
-Baseball
-Denmark
-Christianity
-Philippines
-Woman
-Romania
-Czech Republic
-Album
-Godzilla Minus One
-Single (music)
-Electoral reform
-Nofollow
-Basketball
-New York (state)
-Argentina
-Finland
-Soviet Union
-Greece
-Russian language
-Historic site
-Free content
-YouTube
-Catholic Church
-Hungary
-Kingdom Hearts
-Beetle
-Company
-Tetris
-Portugal
-BioShock
-Abandonware
-Deus Ex (video game)
-4A Engine
-Yoshi's New Island
-Kaboom! (video game)
-Rain World
-Juno (Overwatch)
-Crash Team Rumble
-Vault 101
-Tales of Commons
-NHL Hockey
-Clutch Gaming
-Haseo
-Allin Kempthorne
-Ilyas El Maliki
-Ratalaika Games
-3D mousepad
-HaptX
-Walid Sultan Midani
-Rustler (video game)
-Look Outside
-Ducks Ahoy!
-Fusion Engine
-Cricket
-Geography
-Chordate
-The Guardian
-Israel
-Billboard (magazine)
-Ice hockey
-Given name
-Chicago
-World War I
-Pennsylvania
-Indonesia
-Alma mater
-Vascular plant
-Amorphea
-Wikimedia Commons
-Novel
-Village
-Visual arts
-Film poster
-Flowering plant
-Opisthokont
-Obazoa
-County seat
-Short story
-First-class cricket
-Law
-Europe
-University
-Croatia
-Sport of athletics
-Holozoa
-Choanozoa
-Filozoa
-German language
-Tennis
-Eumetazoa
-Serbia
-ParaHoxozoa
-Thailand
-History
-Midfielder
-Bilateria
-Unincorporated area
-French language
-AllMusic
-Astronomy
-Nephrozoa
-Novella
-Ship
-Twitter
-Character (arts)
-College
-Malaysia
-Conflict of interest
-Higher education
-IUCN Red List
-Rock music
-Gastropoda
-Creative Commons
-Wales
-Bulgaria
-UTC+2
-Paris
-Species
-Illinois
-HTML element
-South Korea
-BBC
-Persian language
-Moth
-Conservation status
-Pop music
-Colombia
-Wicket
-American football
-Jazz
-World Flora Online
-Los Angeles
-Songwriter
-Hong Kong
-Hdl (identifier)
-Genus
-Spanish language
-Egypt
-Not out
-Slovenia
-Chile
-Korea
-Tropicos
-Slovakia
-Bishop
-Family (biology)
-Rugby union
-Women's history
-Nigeria
-College basketball
-Sports Reference
-Washington, D.C.
-GFDL
-Afghanistan
-Sri Lanka
-Newspapers.com
-UTC+1
-Eudicots
-Estonia
-Los Angeles Times
-Olympedia
-Bangladesh
-Peru
-Singapore
-Typographical error
-UTC
-Virginia
-Taiwan
-Fast bowling
-COVID-19 pandemic
-Food
-Fish
-River
-Republic of Ireland
-Beer
-Caribbean
-Michigan
-Drink
-Chinese language
-Business
-Leg break
-Women's Test cricket
-Women's cricket
-Innings
-New Jersey
-Protostome
-Spin bowling
-Sugar
-Underarm bowling
-Roger Federer
-Googly
-Apple
-Comics
-Cricket Australia XI
-Fair and unfair play
-Anime
-Rafael Nadal
-Leander Paes
-Kazakhstan
-Capital city
-Blessed Virgin Mary
-Venezuela
-Case sensitivity
-Arabic language
-North America
-Texas
-Burger King
-The Plant List
-Justine Henin
-Sushi
-Angelus
-Beef
-Sanctification
-Cuthbert Tunstall
-Bread
-Saint Mungo
-Incumbent
-Americanism (heresy)
-Curry
-Ensoulment
-Associated Press
-Adolph John Paschang
-French cuisine
-Altar Society
-UTC-5
-Philadelphia
-Bill Mallon
-Yogurt
-Soy sauce
-Open Era (tennis)
-Belarus
-Manga
-English Wikipedia
-Islam
-Trademark
-ISO 4
-Wisconsin
-Lithuania
-The Washington Post
-Agaricus bisporus
-Reptile
-Sociology
-Organizations
-Death
-Ham and eggs
-Asia
-Swimming (sport)
-South America
-Northern Ireland
-Observation.org
-European Union
-Astronomical object
-Georgia (U.S. state)
-Gmina
-Provinces of Iran
-Computing
-Counties of Iran
-Discogs
-Mathematics
-Powiat
-Missouri
-Bachelor of Arts
-Iran Standard Time
-Florida
-Bakhsh
-Minnesota
-Oregon
-Nepal
-Variety (magazine)
-Japanese language
-Journalism
-Rome
-Computer
-Ohio
-Ontario
-Internet Archive
-Latvia
-Comedy
-Azerbaijan
-BBC News
-Morocco
-Ecdysozoa
-Print-on-demand
-Bengali language
-A5 paper
-Pedia Press
-Education
-Mollusca
-American Civil War
-Berlin
-Taxon
-Maryland
-Panarthropoda
-Hebrew language
-Toronto
-Tactopoda
-Episode
-Cuba
-Country music
-Religion
-Rotten Tomatoes
-Georgia (country)
-Classical music
-Month
-Puerto Rico
-GEOnet Names Server
-Sydney
-The Times
-Iraq
-Polyphaga
-Derivative work
-Lisbon
-Syria
-Ecuador
-Uzbekistan
-Greek language
-Latin
-United Nations
-Literature
-Animation
-Physics
-Amphibian
-Romanize
-List of countries
-Moscow
-Politician
-Philosophy
-Metacritic
-Mammal
-Pinyin
-Open access
-New South Wales
-Theatre
-Allmusic
-Syntax
-Women in music
-Fly
-Colorado
-Academic journal
-LGBTQ
-Seal (emblem)
-Rolling Stone
-Saudi Arabia
-Science fiction
-Tweet (social media)
-Heavy metal music
-Boston
-Vietnam
-Molecular biology
-Facebook
-Iceland
-Albania
-Cycling
-Tennessee
-Armenia
-Massachusetts
-Mandibulata
-United States Navy
-Communes of France
-Census
-Algeria
-United States Army
-Wikilink
-Pancrustacea
-Alternative rock
-American English
-Radio stations
-History of Romania
-Endemism
-San Francisco
-Award
-Ghana
-Judaism
-Alabama
-Blog
-The Independent
-Melbourne
-Cantons of France
-Lebanon
-West Germany
-Quotation mark
-Regions of France
-Chernivtsi Oblast
-Tokyo
-Italian language
-Connecticut
-Country
-Screenshot
-Ghost town
-Iran Daylight Time
-NatureServe
-Mongolia
-Cyprus
-Northern Bukovina
-Rugby league
-Northern Bessarabia
-State highway
-Harvard University
-Yorkshire
-Pterygota
-Slash (punctuation)
-Prize
-Science
-Asian Games
-Eastern Time Zone
-Myanmar
-Nazi Germany
-Ottoman Empire
-Quebec
-Billboard Hot 100
-United Arab Emirates
-Neoptera
-Hexapoda
-Least Concern
-Type species
-EPPO Code
-Wikisource
-Kyrgyzstan
-Allotriocarida
-Volleyball
-Geology
-Second World War
-British Columbia
-Socialism
-Zoology
-The Daily Telegraph
-Paleontology
-Vienna
-Dicondylia
-BugGuide
-United States Senate
-Hermit crab
-Paraphrase
-CNN
-Royal Navy
-Indian Standard Time
-Billboard 200
-Kenya
-DVD
-Sipuncula
-Tajikistan
-National park
-Economics
-Heterocyathus
-Uruguay
-Heteropsammia
-Road
-Spanish name
-Luxembourg
-Korean language
-UK Singles Chart
-Queensland
-Montreal
-New York Times
-Bolivia
-CP/M
-Timestamp
-Electronic music
-INSEE code
-ArXiv (identifier)
-PubMed
-SVG
-USA Today
-Omnivore
-Tunisia
-Psychology
-ESPN
-UEFA
-Hawaii
-Gastropod
-Aliyah
-North Carolina
-Russian Empire
-Tibet
-Fungi
-Oklahoma
-Fauna Europaea
-Turkmenistan
-British English
-The London Gazette
-Civil township
-Boxing
-Barack Obama
-Animal Diversity Web
-Reuters
-Eumetabola
-Voter turnout
-Transport
-False positive
-Donald Trump
-Kansas
-Antarctica
-Lake
-Ethiopia
-Time (magazine)
-Marriage
-NBC
-Beijing
-Vertebrate
-Czechoslovakia
-Protected area
-Energy
-Poetry
-Archaeology
-Columbia University
-Poverty line
-Alaska
-Computing platform
-British Empire
-University of Oxford
-Costa Rica
-Dublin
-A-side and B-side
-ZIP code
-Actinopterygii
-UTC-6
-Photoperiodism
-Mayor
-Sphaeriidae
-Animal suicide
-Atka mackerel
-Starling
-Arizona
-Entertainment Weekly
-Sphaerium beckmani
-Junqueira cow
-Zaniolepis frenata
-Campocraspedon
-Zimbabwe
-Motorsport
-Bird flight
-Cnemophilidae
-Hinduism
-Phalarope
-Indiana
-Museums
-Holometabola
-Pytilia
-North Macedonia
-Malta
-Cathartiformes
-Darter
-Saker falcon
-Cathartes
-Avian malaria
-Coal tit
-Magpie duck
-Video game developer
-Bird bath
-Vesper sparrow
-Gouldian finch
-Debeaking
-Vector graphics
-Semiplumbeous hawk
-Scottish crossbill
-Bullfinch
-Fregata
-Nidicolous
-Plushcap
-Pallid scops owl
-Hip-hop
-Blyth's frogmouth
-Sunda scops owl
-Argus (bird)
-Operation Migration
-Nik Borrow
-Per capita income
-Guy Oseary
-Madrid
-Buddhism
-Drainage basin
-Sephardic Haredim
-Rami Kleinstein
-Guy Bavli
-David Bar-Hayim
-Levin Kipnis
-Edna Arbel
-Prisoner of Zion
-Ayala Procaccia
-Nachum Heiman
-Zman Tel Aviv
-CBS
-ARIA Charts
-Cucujiformia
-Away colours
-Regex
-2019 African Games
-1962 Asian Games
-1958 Asian Games
-Chemistry
-Olympic Games
-The Middle Ages
-Central Asia
-Bengalis
-Southeast Asia
-Find a Grave
-Microsoft Windows
-Swing (politics)
-White (U.S. Census)
-Roman Catholic
-Maine
-The Times of India
-Season (sports)
-Jamaica
-Video game genre
-Munich
-Asterids
-Rosids
-Golf
-Language
-Hangul
-Atlanta
-Glasgow
-UTC+3
-Library of Congress
-Deuterostome
-COVID-19
-Video game publisher
-Montenegro
-ESPNcricinfo
-Brand
-UTC-4
-IGN
-Stockholm
-Istanbul
-NASA
-Gnathostomata
-Ukrainian language
-Human rights
-Chicago Tribune
-ProQuest
-IMDb
-River mouth
-Hip hop music
-Gene
-Netflix
-Moldova
-Barcelona
-Paraguay
-Olfactores
-Labour Party (UK)
-United States dollar
-Qatar
-Photography
-Guatemala
-Summit
-Cold War
-Running
-First World War
-Precipitation
-Edinburgh
-Amsterdam
-Lima
-New Eskaton
-Computer program
-Xinjiang
-Women in science
-Manhattan
-Warsaw
-Magazine
-Horror film
-Deadline Hollywood
-Jordan
-Aparaglossata
-Agriculture
-Internet
-Prague
-The Hindu
-Cretaceous
-Latino (U.S. Census)
-Vietnam War
-Music download
-Encyclopedia
-Chemical compounds
-Pittsburgh
-Soap opera
-Budapest
-George W. Bush
-Seattle
-Extended play
-Washington (state)
-Listed building
-Palestine
-LCCN (identifier)
-Portland, Oregon
-Panama
-Plagiarism
-Brooklyn
-Teleostomi
-Manchester
-Bird
-Mollusk
-Automobile
-Historic England
-Linguistics
-Dependent territory
-Athens
-Civil engineering
-Sea snail
-Population density
-Finance
-Disaster management
-Tanzania
-Jurassic
-Districts of Russia
-Western Australia
-Louisiana
-Portuguese language
-Anatomy
-The Beatles
-Tamil language
-Milan
-Uganda
-Natural environment
-FIFA
-Cameroon
-Blu-ray
-Mexico City
-Chemical formula
-Jimmy Wales
-Papua New Guinea
-Diaphoretickes
-UNESCO
-Forbes
-Technology
-Buenos Aires
-Vancouver
-Dominican Republic
-2007
-Species description
-East Germany
-Folk music
-Kentucky
-Multimedia
-Monocotyledon
-Rio de Janeiro
-Automated
-Hindi
-Houston
-Google
-Devonian
-Member of Parliament
-Bible
-Mumbai
-FishBase
-African diaspora
-Carboniferous
-Cambrian
-Triassic
-Montana
-Handball
-Ordovician
-San Diego
-Archive.today
-Stanford University
-British Army
-Middle Ages
-Frequency
-Ultratop
-Permian
-Detroit
-Earth
-Precambrian
-Hamburg
-Alberta
-Tamil Nadu
-Madagascar
-Lancashire
-Guitar
-Trade union
-Instagram
-Engineering
-2006
-Silurian
-NPR
-Railway station
-CAS Registry Number
-Yemen
-Noctuoidea
-Fiji
-Haiti
-Rowing (sport)
-New Orleans
-NME
-Alternative media
-North Korea
-Microsoft
-Jerusalem
-Paleogene
-Audery Mill Creek
-Horse racing
-Post town
-Piano
-Bavaria
-Polish language
-Horror fiction
-Neogene
-Kerala
-Copenhagen
-Google Books
-Central Time Zone
-Island
-Birmingham
-Anglicanism
-Software
-Mountain range
-Investment
-Brussels
-Muhammad Ali
-Asian (U.S. Census)
-Video game culture
-Brisbane
-Church of England
-Kosovo
-Bachelor of Science
-Molar mass
-Arachnid
-Own goal
-Yale University
-Caenogastropoda
-Auckland
-World Athletics
-Trinidad and Tobago
-Hanyu Pinyin
-Sound bite
-Time
-El Salvador
-Microbiology
-Columbia Records
-Seoul
-Cerambycidae
-Maharashtra
-Chelicerata
-Fungus
-Media influence
-South Carolina
-Radio
-Telenovela
-FA Cup
-Senegal
-Internet trolling
-Nashville, Tennessee
-Demonym
-Standard Chinese
-Sculpture
-Liverpool
-Thesis
-Bass guitar
-Chess
-Women artists
-Icon (computing)
-PubChem
-UK Albums Chart
-Head coach
-Roman Empire
-Grand Slam (tennis)
-JSmol
-Formula One
-Biology
-Kent
-Ancient Rome
-Inner Carniola
-Oslo
-Dutch language
-Wingspan
-Archaeplastida
-MTV
-Edvard Ravnikar
-ITunes
-Feminism
-German Empire
-Pacific Ocean
-Atlantic Ocean
-Pharmacology
-Track gauge
-ChemSpider
-Doctor of Philosophy
-Regions of England
-Districts of England
-Christmas
-Pavel Golia
-Predjama Castle
-Overtime (sports)
-Forum
-Swiss Hitparade
-Stumped
-Majority
-Male
-Shanghai
-Siddharta (band)
\ No newline at end of file
diff --git a/examples/sandboxed_functions_examples.py b/examples/sandboxed_functions_examples.py
deleted file mode 100644
index a983f95d9b..0000000000
--- a/examples/sandboxed_functions_examples.py
+++ /dev/null
@@ -1,58 +0,0 @@
-import os
-import sys
-from pathlib import Path
-
-# Load environment variables from .env file
-project_root = Path(__file__).parent.parent
-env_file = project_root / ".env"
-print(f"Loading environment from: {env_file}")
-from dotenv import load_dotenv
-
-load_dotenv(env_file)
-
-# Add paths to sys.path if needed
-pythonpath = os.environ.get("PYTHONPATH", "")
-for path in pythonpath.split(":"):
- if path and path not in sys.path:
- sys.path.insert(0, path) # Insert at beginning to prioritize
- print(f"Added to sys.path: {path}")
-
-import asyncio
-
-from computer.computer import Computer
-from computer.helpers import sandboxed
-
-
-async def main():
- # Initialize the computer in a Cua Container
- computer = Computer()
- await computer.run()
-
- # Install a package in a virtual environment in the container
- await computer.venv_install("demo_venv", ["requests", "macos-pyxa"])
-
- # Open Safari
- await computer.interface.run_command("open -a Safari")
- await asyncio.sleep(2)
-
- # Define a sandboxed function
- # This function will run inside the Cua Container
- @sandboxed("demo_venv")
- def greet_and_print(name):
- # get .html of the current Safari tab
- import PyXA
-
- safari = PyXA.Application("Safari")
- current_doc = safari.current_document
- html = current_doc.source()
- print(f"Hello from inside the container, {name}!")
- print("Safari HTML length:", len(html))
- return {"greeted": name, "safari_html_length": len(html), "safari_html_snippet": html[:200]}
-
- # Call with args and kwargs
- result = await greet_and_print("Cua")
- print("Result from sandboxed function:", result)
-
-
-if __name__ == "__main__":
- asyncio.run(main())
diff --git a/examples/sandboxes-cli/conftest.py b/examples/sandboxes-cli/conftest.py
new file mode 100644
index 0000000000..9b42865456
--- /dev/null
+++ b/examples/sandboxes-cli/conftest.py
@@ -0,0 +1,18 @@
+"""Ensure tool bins are on PATH for subprocess calls made during tests."""
+
+from __future__ import annotations
+
+import os
+
+
+def pytest_configure(config): # noqa: ARG001
+ extra = [
+ os.path.expanduser("~/.local/bin"),
+ "/Applications/OrbStack.app/Contents/MacOS/xbin", # OrbStack docker CLI
+ "/opt/homebrew/bin", # Homebrew (qemu, etc.)
+ ]
+ path_parts = os.environ.get("PATH", "").split(os.pathsep)
+ for p in reversed(extra):
+ if p not in path_parts:
+ path_parts.insert(0, p)
+ os.environ["PATH"] = os.pathsep.join(path_parts)
diff --git a/examples/sandboxes-cli/test_android_cloud_vm.py b/examples/sandboxes-cli/test_android_cloud_vm.py
new file mode 100644
index 0000000000..73b827bbf8
--- /dev/null
+++ b/examples/sandboxes-cli/test_android_cloud_vm.py
@@ -0,0 +1,75 @@
+"""Launch a persistent cloud Android VM via the CLI.
+
+ cua sb launch android:14 --json
+ # parse name from JSON output, connect with SDK, run assertions
+ cua sb delete <name>
+
+Mirrors examples/sandboxes/test_android_cloud_vm.py but exercises the CLI
+launch path and persistent state tracking instead of Sandbox.ephemeral().
+Requires CUA_API_KEY. No Android SDK or emulator needed.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import subprocess
+
+import pytest
+from cua_sandbox import Sandbox
+
+pytestmark = pytest.mark.asyncio
+
+
+def _has_cua_api_key() -> bool:
+ return bool(os.environ.get("CUA_API_KEY"))
+
+
+def _cua(*args: str) -> subprocess.CompletedProcess:
+ return subprocess.run(["cua", *args], capture_output=True, text=True)
+
+
[email protected](not _has_cua_api_key(), reason="CUA_API_KEY not set")
+async def test_android_cloud_vm():
+ result = _cua("sb", "launch", "android:14", "--json")
+ assert result.returncode == 0, f"launch failed:\n{result.stderr}"
+ name = json.loads(result.stdout)["name"]
+
+ try:
+ async with Sandbox.connect(name) as sb:
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+ assert len(screenshot) > 1000
+
+ w, h = await sb.screen.size()
+ assert w > 0 and h > 0
+
+ await sb.mobile.home()
+ finally:
+ _cua("sb", "delete", name)
+
+
+async def main():
+ r = _cua("sb", "launch", "android:14", "--json")
+ print(f"launch exit={r.returncode}")
+ name = json.loads(r.stdout)["name"]
+ print(f"name: {name}")
+
+ try:
+ async with Sandbox.connect(name) as sb:
+ screenshot = await sb.screenshot()
+ print(f"Screenshot: {len(screenshot)} bytes")
+ with open("/tmp/cli_android_cloud_vm.png", "wb") as f:
+ f.write(screenshot)
+ w, h = await sb.screen.size()
+ print(f"Screen size: {w}x{h}")
+ await sb.mobile.tap(w // 2, h // 2)
+ await sb.mobile.home()
+ print("Tap + home: OK")
+ finally:
+ _cua("sb", "delete", name)
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/sandboxes-cli/test_android_local_cdp.py b/examples/sandboxes-cli/test_android_local_cdp.py
new file mode 100644
index 0000000000..030234f8b2
--- /dev/null
+++ b/examples/sandboxes-cli/test_android_local_cdp.py
@@ -0,0 +1,206 @@
+"""Test CDP (Chrome DevTools Protocol) access via sb.tunnel on a local Android VM.
+
+Flow:
+ 1. Launch android:14 via CLI
+ 2. Connect with SDK
+ 3. Open Chrome to a data: URI that seeds localStorage
+ 4. Forward Chrome's devtools port (9222) via sb.tunnel.forward(9222)
+ 5. Use CDP Runtime.evaluate to read back localStorage and assert correctness
+ 6. Delete sandbox
+
+Requires:
+ - Android SDK (emulator + adb)
+ - Chrome / WebView debugging enabled (Android 14 emulator has it on by default)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import subprocess
+import time
+
+import pytest
+
+pytestmark = pytest.mark.asyncio
+
+
+def _has_java() -> bool:
+ """Only Java must be pre-installed — the Android SDK auto-installs on first run."""
+ try:
+ from cua_sandbox.runtime.android_emulator import _java_env
+
+ _java_env()
+ return True
+ except Exception:
+ return False
+
+
+def _cua(*args: str) -> subprocess.CompletedProcess:
+ return subprocess.run(["cua", *args], capture_output=True, text=True)
+
+
+def _ls_names() -> list[str]:
+ r = _cua("sb", "ls", "--all", "--json")
+ if r.returncode != 0:
+ return []
+ return [s["name"] for s in json.loads(r.stdout)]
+
+
+async def _wait_for_chrome(tunnel, timeout: int = 60) -> None:
+ """Wait until Chrome is responding to DevTools discovery on tunnel.port."""
+ import urllib.request
+
+ deadline = time.monotonic() + timeout
+ while time.monotonic() < deadline:
+ try:
+ with urllib.request.urlopen(f"{tunnel.url}/json", timeout=2) as r:
+ targets = json.loads(r.read())
+ if targets:
+ return
+ except Exception:
+ pass
+ await asyncio.sleep(2)
+ raise TimeoutError("Chrome DevTools not ready within timeout")
+
+
+async def _cdp_evaluate(ws_url: str, expression: str) -> object:
+ """Send a single CDP Runtime.evaluate and return the result value."""
+ import websockets
+
+ async with websockets.connect(ws_url) as ws:
+ await ws.send(
+ json.dumps(
+ {
+ "id": 1,
+ "method": "Runtime.evaluate",
+ "params": {"expression": expression, "returnByValue": True},
+ }
+ )
+ )
+ raw = await asyncio.wait_for(ws.recv(), timeout=10)
+ resp = json.loads(raw)
+ result = resp.get("result", {}).get("result", {})
+ if result.get("subtype") == "error":
+ raise RuntimeError(f"CDP evaluate error: {result.get('description')}")
+ return result.get("value")
+
+
[email protected](not _has_java(), reason="Java not found (required to auto-install Android SDK)")
+async def test_android_local_cdp():
+ result = _cua("sb", "launch", "android:14", "--local", "--json")
+ assert result.returncode == 0, f"launch failed:\n{result.stderr}"
+ name = json.loads(result.stdout)["name"]
+ assert name in _ls_names()
+
+ try:
+ from cua_sandbox import Sandbox
+
+ async with Sandbox.connect(name, local=True) as sb:
+ # ── 1. Enable Chrome remote debugging ─────────────────────────────
+ # Set the global WebView debug flag (works without a debug APK)
+ await sb.shell.run("settings put global debug_view_attributes 1")
+
+ # ── 2. Open Chrome to a data: page that sets localStorage ─────────
+ page_html = (
+ "<html><body><script>"
+ "localStorage.setItem('cua_test', JSON.stringify({hello:'world',n:42}));"
+ "document.title='CUA CDP Test';"
+ "</script></body></html>"
+ )
+ import urllib.parse
+
+ data_uri = "data:text/html," + urllib.parse.quote(page_html)
+ await sb.shell.run(
+ f"am start -a android.intent.action.VIEW "
+ f"-n com.android.chrome/com.google.android.apps.chrome.Main "
+ f"-d '{data_uri}'"
+ )
+ await asyncio.sleep(3) # let Chrome load
+
+ # ── 3. Forward Chrome devtools abstract socket via sb.tunnel ─────
+ # Chrome on Android exposes devtools on localabstract:chrome_devtools_remote,
+ # not on TCP 9222 — use the socket name directly.
+ async with sb.tunnel.forward("chrome_devtools_remote") as tunnel:
+ assert tunnel.port > 0
+ assert tunnel.sandbox_port == "chrome_devtools_remote"
+ assert tunnel.url.startswith("http://localhost:")
+
+ await _wait_for_chrome(tunnel, timeout=30)
+
+ # ── 4. Discover the CDP target ────────────────────────────────
+ import urllib.request
+
+ with urllib.request.urlopen(f"{tunnel.url}/json", timeout=5) as r:
+ targets = json.loads(r.read())
+
+ # CDP WebSocket URLs use the host-side port
+ ws_url = targets[0]["webSocketDebuggerUrl"]
+ ws_url = ws_url.replace("localhost/", f"localhost:{tunnel.port}/")
+
+ # ── 5. Read localStorage via CDP ──────────────────────────────
+ raw = await _cdp_evaluate(
+ ws_url,
+ "JSON.parse(localStorage.getItem('cua_test'))",
+ )
+ assert isinstance(raw, dict), f"Expected dict, got: {raw!r}"
+ assert raw.get("hello") == "world"
+ assert raw.get("n") == 42
+
+ # ── 6. Write a new key via CDP ────────────────────────────────
+ await _cdp_evaluate(
+ ws_url,
+ "localStorage.setItem('cua_written', 'via_cdp')",
+ )
+ written = await _cdp_evaluate(
+ ws_url,
+ "localStorage.getItem('cua_written')",
+ )
+ assert written == "via_cdp"
+
+ # tunnel.forward context exited — forward rule removed
+ finally:
+ _cua("sb", "delete", name, "--local")
+ assert name not in _ls_names()
+
+
+async def main():
+ """Quick manual smoke-test."""
+ r = _cua("sb", "launch", "android:14", "--local", "--json")
+ print(f"launch exit={r.returncode}")
+ name = json.loads(r.stdout)["name"]
+ print(f"name: {name}")
+
+ try:
+ from cua_sandbox import Sandbox
+
+ async with Sandbox.connect(name, local=True) as sb:
+ await sb.shell.run("settings put global debug_view_attributes 1")
+ await sb.shell.run(
+ "am start -a android.intent.action.VIEW "
+ "-n com.android.chrome/com.google.android.apps.chrome.Main "
+ '-d \'data:text/html,<script>localStorage.setItem("k","v")</script>\''
+ )
+ await asyncio.sleep(3)
+
+ async with sb.tunnel.forward("chrome_devtools_remote") as t:
+ print(f"DevTools at {t.url}")
+ await _wait_for_chrome(t, timeout=30)
+ import urllib.request
+
+ with urllib.request.urlopen(f"{t.url}/json", timeout=5) as r:
+ targets = json.loads(r.read())
+ print(f"CDP targets: {[x['url'] for x in targets]}")
+ ws_url = targets[0]["webSocketDebuggerUrl"].replace(
+ "localhost/", f"localhost:{t.port}/"
+ )
+ val = await _cdp_evaluate(ws_url, "localStorage.getItem('k')")
+ print(f"localStorage['k'] = {val!r}")
+ assert val == "v"
+ print("CDP localStorage round-trip: OK")
+ finally:
+ _cua("sb", "delete", name, "--local")
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/sandboxes-cli/test_android_local_vm.py b/examples/sandboxes-cli/test_android_local_vm.py
new file mode 100644
index 0000000000..3b652faccf
--- /dev/null
+++ b/examples/sandboxes-cli/test_android_local_vm.py
@@ -0,0 +1,91 @@
+"""Launch a persistent local Android VM via the CLI.
+
+ cua sb launch android:14 --local --json
+ # parse name from JSON output, connect with SDK, run assertions
+ cua sb delete <name> --local
+
+Mirrors examples/sandboxes/test_android_local_vm.py but exercises the CLI
+launch path and persistent state tracking instead of Sandbox.ephemeral().
+Requires Android SDK (emulator + adb) to be installed.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import subprocess
+
+import pytest
+from cua_sandbox import Sandbox
+
+pytestmark = pytest.mark.asyncio
+
+
+def _has_java() -> bool:
+ """Only Java must be pre-installed — the Android SDK auto-installs on first run."""
+ try:
+ from cua_sandbox.runtime.android_emulator import _java_env
+
+ _java_env()
+ return True
+ except Exception:
+ return False
+
+
+def _cua(*args: str) -> subprocess.CompletedProcess:
+ return subprocess.run(["cua", *args], capture_output=True, text=True)
+
+
+def _ls_names() -> list[str]:
+ r = _cua("sb", "ls", "--all", "--json")
+ if r.returncode != 0:
+ return []
+ return [s["name"] for s in json.loads(r.stdout)]
+
+
[email protected](not _has_java(), reason="Java not found (required to auto-install Android SDK)")
+async def test_android_local_vm():
+ result = _cua("sb", "launch", "android:14", "--local", "--json")
+ assert result.returncode == 0, f"launch failed:\n{result.stderr}"
+ name = json.loads(result.stdout)["name"]
+
+ assert name in _ls_names(), f"'{name}' not found in `cua sb ls --all` after launch"
+
+ try:
+ async with Sandbox.connect(name, local=True) as sb:
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+ assert len(screenshot) > 10000
+
+ w, h = await sb.screen.size()
+ assert w > 0 and h > 0
+
+ await sb.mobile.home()
+ finally:
+ _cua("sb", "delete", name, "--local")
+ assert name not in _ls_names(), f"'{name}' still in `cua sb ls --all` after delete"
+
+
+async def main():
+ r = _cua("sb", "launch", "android:14", "--local", "--json")
+ print(f"launch exit={r.returncode}")
+ name = json.loads(r.stdout)["name"]
+ print(f"name: {name}")
+
+ try:
+ async with Sandbox.connect(name, local=True) as sb:
+ screenshot = await sb.screenshot()
+ print(f"Screenshot: {len(screenshot)} bytes")
+ with open("/tmp/cli_android_local_vm.png", "wb") as f:
+ f.write(screenshot)
+ w, h = await sb.screen.size()
+ print(f"Screen size: {w}x{h}")
+ await sb.mobile.tap(w // 2, h // 2)
+ await sb.mobile.home()
+ print("Tap + home: OK")
+ finally:
+ _cua("sb", "delete", name, "--local")
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/sandboxes-cli/test_linux_cloud_container.py b/examples/sandboxes-cli/test_linux_cloud_container.py
new file mode 100644
index 0000000000..4773f13233
--- /dev/null
+++ b/examples/sandboxes-cli/test_linux_cloud_container.py
@@ -0,0 +1,70 @@
+"""Launch a persistent cloud Linux container via the CLI.
+
+ cua sb launch ubuntu:24.04 --json
+ # parse name from JSON output, connect with SDK, run assertions
+ cua sb delete <name>
+
+Mirrors examples/sandboxes/test_linux_cloud_container.py but exercises the
+CLI launch path and persistent state tracking instead of Sandbox.ephemeral().
+Requires CUA_API_KEY environment variable.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import subprocess
+
+import pytest
+from cua_sandbox import Sandbox
+
+pytestmark = pytest.mark.asyncio
+
+
+def _has_cua_api_key() -> bool:
+ return bool(os.environ.get("CUA_API_KEY"))
+
+
+def _cua(*args: str) -> subprocess.CompletedProcess:
+ return subprocess.run(["cua", *args], capture_output=True, text=True)
+
+
[email protected](not _has_cua_api_key(), reason="CUA_API_KEY not set")
+async def test_linux_cloud_container():
+ result = _cua("sb", "launch", "ubuntu:24.04", "--json")
+ assert result.returncode == 0, f"launch failed:\n{result.stderr}"
+ name = json.loads(result.stdout)["name"]
+
+ try:
+ async with Sandbox.connect(name) as sb:
+ out = await sb.shell.run("uname -s")
+ assert out.success
+ assert "Linux" in out.stdout
+
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+ finally:
+ _cua("sb", "delete", name)
+
+
+async def main():
+ r = _cua("sb", "launch", "ubuntu:24.04", "--json")
+ print(f"launch exit={r.returncode}")
+ name = json.loads(r.stdout)["name"]
+ print(f"name: {name}")
+
+ try:
+ async with Sandbox.connect(name) as sb:
+ out = await sb.shell.run("uname -s")
+ print(f"uname: {out.stdout.strip()}")
+ screenshot = await sb.screenshot()
+ print(f"Screenshot: {len(screenshot)} bytes")
+ with open("/tmp/cli_linux_cloud_container.png", "wb") as f:
+ f.write(screenshot)
+ finally:
+ _cua("sb", "delete", name)
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/sandboxes-cli/test_linux_cloud_vm.py b/examples/sandboxes-cli/test_linux_cloud_vm.py
new file mode 100644
index 0000000000..ef5d15476a
--- /dev/null
+++ b/examples/sandboxes-cli/test_linux_cloud_vm.py
@@ -0,0 +1,70 @@
+"""Launch a persistent cloud Linux VM via the CLI.
+
+ cua sb launch ubuntu:24.04 --vm --json
+ # parse name from JSON output, connect with SDK, run assertions
+ cua sb delete <name>
+
+Mirrors examples/sandboxes/test_linux_cloud_vm.py but exercises the CLI
+launch path and persistent state tracking instead of Sandbox.ephemeral().
+Requires CUA_API_KEY environment variable.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import subprocess
+
+import pytest
+from cua_sandbox import Sandbox
+
+pytestmark = pytest.mark.asyncio
+
+
+def _has_cua_api_key() -> bool:
+ return bool(os.environ.get("CUA_API_KEY"))
+
+
+def _cua(*args: str) -> subprocess.CompletedProcess:
+ return subprocess.run(["cua", *args], capture_output=True, text=True)
+
+
[email protected](not _has_cua_api_key(), reason="CUA_API_KEY not set")
+async def test_linux_cloud_vm():
+ result = _cua("sb", "launch", "ubuntu:24.04", "--vm", "--json")
+ assert result.returncode == 0, f"launch failed:\n{result.stderr}"
+ name = json.loads(result.stdout)["name"]
+
+ try:
+ async with Sandbox.connect(name) as sb:
+ out = await sb.shell.run("uname -s")
+ assert out.success
+ assert "Linux" in out.stdout
+
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+ finally:
+ _cua("sb", "delete", name)
+
+
+async def main():
+ r = _cua("sb", "launch", "ubuntu:24.04", "--vm", "--json")
+ print(f"launch exit={r.returncode}")
+ name = json.loads(r.stdout)["name"]
+ print(f"name: {name}")
+
+ try:
+ async with Sandbox.connect(name) as sb:
+ out = await sb.shell.run("uname -s")
+ print(f"uname: {out.stdout.strip()}")
+ screenshot = await sb.screenshot()
+ print(f"Screenshot: {len(screenshot)} bytes")
+ with open("/tmp/cli_linux_cloud_vm.png", "wb") as f:
+ f.write(screenshot)
+ finally:
+ _cua("sb", "delete", name)
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/sandboxes-cli/test_linux_local_container.py b/examples/sandboxes-cli/test_linux_local_container.py
new file mode 100644
index 0000000000..c484f9adb9
--- /dev/null
+++ b/examples/sandboxes-cli/test_linux_local_container.py
@@ -0,0 +1,82 @@
+"""Launch a persistent local Linux container via the CLI.
+
+ cua sb launch ubuntu:24.04 --local --json
+ # parse name from JSON output, connect with SDK, run assertions
+ cua sb delete <name> --local
+
+Mirrors examples/sandboxes/test_linux_local_container.py but exercises the
+CLI launch path and persistent state tracking instead of Sandbox.ephemeral().
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import subprocess
+
+import pytest
+from cua_sandbox import Sandbox
+
+pytestmark = pytest.mark.asyncio
+
+
+def _has_docker() -> bool:
+ try:
+ subprocess.run(["docker", "info"], capture_output=True, check=True, timeout=10)
+ return True
+ except (subprocess.SubprocessError, FileNotFoundError):
+ return False
+
+
+def _cua(*args: str) -> subprocess.CompletedProcess:
+ return subprocess.run(["cua", *args], capture_output=True, text=True)
+
+
+def _ls_names() -> list[str]:
+ r = _cua("sb", "ls", "--all", "--json")
+ if r.returncode != 0:
+ return []
+ return [s["name"] for s in json.loads(r.stdout)]
+
+
[email protected](not _has_docker(), reason="Docker not available")
+async def test_linux_local_container():
+ result = _cua("sb", "launch", "ubuntu:24.04", "--local", "--json")
+ assert result.returncode == 0, f"launch failed:\n{result.stderr}"
+ name = json.loads(result.stdout)["name"]
+
+ assert name in _ls_names(), f"'{name}' not found in `cua sb ls --all` after launch"
+
+ try:
+ async with Sandbox.connect(name, local=True) as sb:
+ out = await sb.shell.run("uname -s")
+ assert out.success
+ assert "Linux" in out.stdout
+
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+ finally:
+ _cua("sb", "delete", name, "--local")
+ assert name not in _ls_names(), f"'{name}' still in `cua sb ls --all` after delete"
+
+
+async def main():
+ r = _cua("sb", "launch", "ubuntu:24.04", "--local", "--json")
+ print(f"launch exit={r.returncode}")
+ name = json.loads(r.stdout)["name"]
+ print(f"name: {name}")
+
+ try:
+ async with Sandbox.connect(name, local=True) as sb:
+ out = await sb.shell.run("uname -s")
+ print(f"uname: {out.stdout.strip()}")
+ screenshot = await sb.screenshot()
+ print(f"Screenshot: {len(screenshot)} bytes")
+ with open("/tmp/cli_linux_local_container.png", "wb") as f:
+ f.write(screenshot)
+ finally:
+ _cua("sb", "delete", name, "--local")
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/sandboxes-cli/test_linux_local_registry_vm.py b/examples/sandboxes-cli/test_linux_local_registry_vm.py
new file mode 100644
index 0000000000..ac50a22595
--- /dev/null
+++ b/examples/sandboxes-cli/test_linux_local_registry_vm.py
@@ -0,0 +1,78 @@
+"""Launch a persistent local Linux VM from a trycua OCI registry image via the CLI.
+
+ cua sb launch ghcr.io/trycua/cua-xfce:latest --local --json
+ # parse name from JSON output, connect with SDK, run assertions
+ cua sb delete <name> --local
+
+Mirrors examples/sandboxes/test_linux_local_registry_vm.py but exercises the
+CLI launch path. Note: the SDK example uses explicit TartRuntime(); the CLI
+auto-selects the runtime from the OCI manifest. On macOS with Tart installed,
+pass --runtime tart to use TartRuntime instead of QEMU.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import platform
+import subprocess
+
+import pytest
+from cua_sandbox import Sandbox
+
+pytestmark = pytest.mark.asyncio
+
+IS_MACOS = platform.system() == "Darwin"
+IMAGE = "ghcr.io/trycua/cua-xfce:latest"
+
+
+def _has_tart() -> bool:
+ try:
+ subprocess.run(["tart", "--version"], capture_output=True, check=True)
+ return True
+ except (subprocess.SubprocessError, FileNotFoundError):
+ return False
+
+
+def _cua(*args: str) -> subprocess.CompletedProcess:
+ return subprocess.run(["cua", *args], capture_output=True, text=True)
+
+
[email protected](not IS_MACOS or not _has_tart(), reason="Tart only on macOS")
+async def test_linux_local_registry_vm():
+ result = _cua("sb", "launch", IMAGE, "--local", "--json")
+ assert result.returncode == 0, f"launch failed:\n{result.stderr}"
+ name = json.loads(result.stdout)["name"]
+
+ try:
+ async with Sandbox.connect(name, local=True) as sb:
+ out = await sb.shell.run("uname -s")
+ assert out.success
+ assert "Linux" in out.stdout
+
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+ finally:
+ _cua("sb", "delete", name, "--local")
+
+
+async def main():
+ r = _cua("sb", "launch", IMAGE, "--local", "--json")
+ print(f"launch exit={r.returncode}")
+ name = json.loads(r.stdout)["name"]
+ print(f"name: {name}")
+
+ try:
+ async with Sandbox.connect(name, local=True) as sb:
+ out = await sb.shell.run("uname -s")
+ print(f"uname: {out.stdout.strip()}")
+ screenshot = await sb.screenshot()
+ print(f"Screenshot: {len(screenshot)} bytes")
+ with open("/tmp/cli_linux_local_registry_vm.png", "wb") as f:
+ f.write(screenshot)
+ finally:
+ _cua("sb", "delete", name, "--local")
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/sandboxes-cli/test_linux_local_vm.py b/examples/sandboxes-cli/test_linux_local_vm.py
new file mode 100644
index 0000000000..655139d872
--- /dev/null
+++ b/examples/sandboxes-cli/test_linux_local_vm.py
@@ -0,0 +1,82 @@
+"""Launch a persistent local Linux VM via the CLI.
+
+ cua sb launch ubuntu:24.04 --local --vm --json
+ # parse name from JSON output, connect with SDK, run assertions
+ cua sb delete <name> --local
+
+Mirrors examples/sandboxes/test_linux_local_vm.py but exercises the CLI
+launch path and persistent state tracking instead of Sandbox.ephemeral().
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import subprocess
+
+import pytest
+from cua_sandbox import Sandbox
+
+pytestmark = pytest.mark.asyncio
+
+
+def _has_docker() -> bool:
+ try:
+ subprocess.run(["docker", "info"], capture_output=True, check=True, timeout=10)
+ return True
+ except (subprocess.SubprocessError, FileNotFoundError):
+ return False
+
+
+def _cua(*args: str) -> subprocess.CompletedProcess:
+ return subprocess.run(["cua", *args], capture_output=True, text=True)
+
+
+def _ls_names() -> list[str]:
+ r = _cua("sb", "ls", "--all", "--json")
+ if r.returncode != 0:
+ return []
+ return [s["name"] for s in json.loads(r.stdout)]
+
+
[email protected](not _has_docker(), reason="Docker not available")
+async def test_linux_local_vm():
+ result = _cua("sb", "launch", "ubuntu:24.04", "--local", "--vm", "--json")
+ assert result.returncode == 0, f"launch failed:\n{result.stderr}"
+ name = json.loads(result.stdout)["name"]
+
+ assert name in _ls_names(), f"'{name}' not found in `cua sb ls --all` after launch"
+
+ try:
+ async with Sandbox.connect(name, local=True) as sb:
+ out = await sb.shell.run("uname -s")
+ assert out.success
+ assert "Linux" in out.stdout
+
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+ finally:
+ _cua("sb", "delete", name, "--local")
+ assert name not in _ls_names(), f"'{name}' still in `cua sb ls --all` after delete"
+
+
+async def main():
+ r = _cua("sb", "launch", "ubuntu:24.04", "--local", "--vm", "--json")
+ print(f"launch exit={r.returncode}")
+ name = json.loads(r.stdout)["name"]
+ print(f"name: {name}")
+
+ try:
+ async with Sandbox.connect(name, local=True) as sb:
+ out = await sb.shell.run("uname -s")
+ print(f"uname: {out.stdout.strip()}")
+ screenshot = await sb.screenshot()
+ print(f"Screenshot: {len(screenshot)} bytes")
+ with open("/tmp/cli_linux_local_vm.png", "wb") as f:
+ f.write(screenshot)
+ finally:
+ _cua("sb", "delete", name, "--local")
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/sandboxes-cli/test_macos_cloud_vm.py b/examples/sandboxes-cli/test_macos_cloud_vm.py
new file mode 100644
index 0000000000..ada27958a8
--- /dev/null
+++ b/examples/sandboxes-cli/test_macos_cloud_vm.py
@@ -0,0 +1,70 @@
+"""Launch a persistent cloud macOS VM via the CLI.
+
+ cua sb launch macos --json
+ # parse name from JSON output, connect with SDK, run assertions
+ cua sb delete <name>
+
+Mirrors examples/sandboxes/test_macos_cloud_vm.py but exercises the CLI
+launch path and persistent state tracking instead of Sandbox.ephemeral().
+Requires CUA_API_KEY. Works on any host OS — no Mac needed.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import subprocess
+
+import pytest
+from cua_sandbox import Sandbox
+
+pytestmark = pytest.mark.asyncio
+
+
+def _has_cua_api_key() -> bool:
+ return bool(os.environ.get("CUA_API_KEY"))
+
+
+def _cua(*args: str) -> subprocess.CompletedProcess:
+ return subprocess.run(["cua", *args], capture_output=True, text=True)
+
+
[email protected](not _has_cua_api_key(), reason="CUA_API_KEY not set")
+async def test_macos_cloud_vm():
+ result = _cua("sb", "launch", "macos", "--json")
+ assert result.returncode == 0, f"launch failed:\n{result.stderr}"
+ name = json.loads(result.stdout)["name"]
+
+ try:
+ async with Sandbox.connect(name) as sb:
+ out = await sb.shell.run("sw_vers")
+ assert out.success
+ assert "macOS" in out.stdout or "Mac" in out.stdout
+
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+ finally:
+ _cua("sb", "delete", name)
+
+
+async def main():
+ r = _cua("sb", "launch", "macos", "--json")
+ print(f"launch exit={r.returncode}")
+ name = json.loads(r.stdout)["name"]
+ print(f"name: {name}")
+
+ try:
+ async with Sandbox.connect(name) as sb:
+ out = await sb.shell.run("sw_vers")
+ print(f"sw_vers: {out.stdout.strip()}")
+ screenshot = await sb.screenshot()
+ print(f"Screenshot: {len(screenshot)} bytes")
+ with open("/tmp/cli_macos_cloud_vm.png", "wb") as f:
+ f.write(screenshot)
+ finally:
+ _cua("sb", "delete", name)
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/sandboxes-cli/test_macos_local_registry_vm.py b/examples/sandboxes-cli/test_macos_local_registry_vm.py
new file mode 100644
index 0000000000..6249f71e4b
--- /dev/null
+++ b/examples/sandboxes-cli/test_macos_local_registry_vm.py
@@ -0,0 +1,77 @@
+"""Launch a persistent local macOS VM from a trycua OCI registry image via the CLI.
+
+ cua sb launch ghcr.io/trycua/macos-tahoe-cua@sha256:... --local --json
+ # parse name from JSON output, connect with SDK, run assertions
+ cua sb delete <name> --local
+
+Mirrors examples/sandboxes/test_macos_local_registry_vm.py but exercises the
+CLI launch path. The registry ref is passed to Image.from_registry(), which
+fetches the OCI manifest to auto-infer os_type=macos and selects LumeRuntime.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import platform
+import subprocess
+
+import pytest
+from cua_sandbox import Sandbox
+
+pytestmark = pytest.mark.asyncio
+
+IS_MACOS = platform.system() == "Darwin"
+IMAGE = "ghcr.io/trycua/macos-tahoe-cua:latest"
+
+
+def _has_lume() -> bool:
+ try:
+ subprocess.run(["lume", "--version"], capture_output=True, check=True)
+ return True
+ except (subprocess.SubprocessError, FileNotFoundError):
+ return False
+
+
+def _cua(*args: str) -> subprocess.CompletedProcess:
+ return subprocess.run(["cua", *args], capture_output=True, text=True)
+
+
[email protected](not IS_MACOS or not _has_lume(), reason="Lume only on macOS")
+async def test_macos_local_registry_vm():
+ result = _cua("sb", "launch", IMAGE, "--local", "--json")
+ assert result.returncode == 0, f"launch failed:\n{result.stderr}"
+ name = json.loads(result.stdout)["name"]
+
+ try:
+ async with Sandbox.connect(name, local=True) as sb:
+ out = await sb.shell.run("sw_vers")
+ assert out.success
+ assert "macOS" in out.stdout or "Mac" in out.stdout
+
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+ finally:
+ _cua("sb", "delete", name, "--local")
+
+
+async def main():
+ r = _cua("sb", "launch", IMAGE, "--local", "--json")
+ print(f"launch exit={r.returncode}")
+ name = json.loads(r.stdout)["name"]
+ print(f"name: {name}")
+
+ try:
+ async with Sandbox.connect(name, local=True) as sb:
+ out = await sb.shell.run("sw_vers")
+ print(f"sw_vers: {out.stdout.strip()}")
+ screenshot = await sb.screenshot()
+ print(f"Screenshot: {len(screenshot)} bytes")
+ with open("/tmp/cli_macos_local_registry_vm.png", "wb") as f:
+ f.write(screenshot)
+ finally:
+ _cua("sb", "delete", name, "--local")
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/sandboxes-cli/test_macos_local_vm.py b/examples/sandboxes-cli/test_macos_local_vm.py
new file mode 100644
index 0000000000..40d71a157e
--- /dev/null
+++ b/examples/sandboxes-cli/test_macos_local_vm.py
@@ -0,0 +1,86 @@
+"""Launch a persistent local macOS VM via the CLI.
+
+ cua sb launch macos --local --json
+ # parse name from JSON output, connect with SDK, run assertions
+ cua sb delete <name> --local
+
+Mirrors examples/sandboxes/test_macos_local_vm.py but exercises the CLI
+launch path and persistent state tracking instead of Sandbox.ephemeral().
+Requires the Lume CLI on a macOS host.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import platform
+import subprocess
+
+import pytest
+from cua_sandbox import Sandbox
+
+pytestmark = pytest.mark.asyncio
+
+IS_MACOS = platform.system() == "Darwin"
+
+
+def _has_lume() -> bool:
+ try:
+ subprocess.run(["lume", "--version"], capture_output=True, check=True)
+ return True
+ except (subprocess.SubprocessError, FileNotFoundError):
+ return False
+
+
+def _cua(*args: str) -> subprocess.CompletedProcess:
+ return subprocess.run(["cua", *args], capture_output=True, text=True)
+
+
+def _ls_names() -> list[str]:
+ r = _cua("sb", "ls", "--all", "--json")
+ if r.returncode != 0:
+ return []
+ return [s["name"] for s in json.loads(r.stdout)]
+
+
[email protected](not IS_MACOS or not _has_lume(), reason="Lume only on macOS")
+async def test_macos_local_vm():
+ result = _cua("sb", "launch", "macos", "--local", "--json")
+ assert result.returncode == 0, f"launch failed:\n{result.stderr}"
+ name = json.loads(result.stdout)["name"]
+
+ assert name in _ls_names(), f"'{name}' not found in `cua sb ls --all` after launch"
+
+ try:
+ async with Sandbox.connect(name, local=True) as sb:
+ out = await sb.shell.run("sw_vers")
+ assert out.success
+ assert "macOS" in out.stdout or "Mac" in out.stdout
+
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+ finally:
+ _cua("sb", "delete", name, "--local")
+ assert name not in _ls_names(), f"'{name}' still in `cua sb ls --all` after delete"
+
+
+async def main():
+ r = _cua("sb", "launch", "macos", "--local", "--json")
+ print(f"launch exit={r.returncode}")
+ name = json.loads(r.stdout)["name"]
+ print(f"name: {name}")
+
+ try:
+ async with Sandbox.connect(name, local=True) as sb:
+ out = await sb.shell.run("sw_vers")
+ print(f"sw_vers: {out.stdout.strip()}")
+ screenshot = await sb.screenshot()
+ print(f"Screenshot: {len(screenshot)} bytes")
+ with open("/tmp/cli_macos_local_vm.png", "wb") as f:
+ f.write(screenshot)
+ finally:
+ _cua("sb", "delete", name, "--local")
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/sandboxes-cli/test_windows_cloud_vm.py b/examples/sandboxes-cli/test_windows_cloud_vm.py
new file mode 100644
index 0000000000..e8e67f011a
--- /dev/null
+++ b/examples/sandboxes-cli/test_windows_cloud_vm.py
@@ -0,0 +1,69 @@
+"""Launch a persistent cloud Windows VM via the CLI.
+
+ cua sb launch windows:11 --json
+ # parse name from JSON output, connect with SDK, run assertions
+ cua sb delete <name>
+
+Mirrors examples/sandboxes/test_windows_cloud_vm.py but exercises the CLI
+launch path and persistent state tracking instead of Sandbox.ephemeral().
+Requires CUA_API_KEY. Works on any host OS — no Windows needed.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import subprocess
+
+import pytest
+from cua_sandbox import Sandbox
+
+pytestmark = pytest.mark.asyncio
+
+
+def _has_cua_api_key() -> bool:
+ return bool(os.environ.get("CUA_API_KEY"))
+
+
+def _cua(*args: str) -> subprocess.CompletedProcess:
+ return subprocess.run(["cua", *args], capture_output=True, text=True)
+
+
[email protected](not _has_cua_api_key(), reason="CUA_API_KEY not set")
+async def test_windows_cloud_vm():
+ result = _cua("sb", "launch", "windows:11", "--json")
+ assert result.returncode == 0, f"launch failed:\n{result.stderr}"
+ name = json.loads(result.stdout)["name"]
+
+ try:
+ async with Sandbox.connect(name) as sb:
+ out = await sb.shell.run("ver")
+ assert out.success or "Windows" in out.stdout
+
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+ finally:
+ _cua("sb", "delete", name)
+
+
+async def main():
+ r = _cua("sb", "launch", "windows:11", "--json")
+ print(f"launch exit={r.returncode}")
+ name = json.loads(r.stdout)["name"]
+ print(f"name: {name}")
+
+ try:
+ async with Sandbox.connect(name) as sb:
+ out = await sb.shell.run("ver")
+ print(f"ver: {out.stdout.strip()}")
+ screenshot = await sb.screenshot()
+ print(f"Screenshot: {len(screenshot)} bytes")
+ with open("/tmp/cli_windows_cloud_vm.png", "wb") as f:
+ f.write(screenshot)
+ finally:
+ _cua("sb", "delete", name)
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/sandboxes-cli/test_windows_local_vm.py b/examples/sandboxes-cli/test_windows_local_vm.py
new file mode 100644
index 0000000000..2d63d73167
--- /dev/null
+++ b/examples/sandboxes-cli/test_windows_local_vm.py
@@ -0,0 +1,80 @@
+"""Launch a persistent local Windows VM via the CLI.
+
+ cua sb launch windows:11 --local --json
+ # parse name from JSON output, connect with SDK, run assertions
+ cua sb delete <name> --local
+
+Mirrors examples/sandboxes/test_windows_local_vm.py but exercises the CLI
+launch path and persistent state tracking instead of Sandbox.ephemeral().
+Requires a Windows host or QEMU with a Windows image.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import platform
+import subprocess
+
+import pytest
+from cua_sandbox import Sandbox
+
+pytestmark = pytest.mark.asyncio
+
+# x86_64 Windows via QEMU TCG on macOS Apple Silicon is impractically slow
+# (no hardware acceleration; full install takes hours).
+_IS_MACOS_ARM = platform.system() == "Darwin" and platform.machine() == "arm64"
+
+
+def _has_qemu() -> bool:
+ try:
+ from cua_sandbox.runtime.qemu_installer import qemu_bin
+
+ qemu_bin("x86_64")
+ return True
+ except Exception:
+ return False
+
+
+def _cua(*args: str) -> subprocess.CompletedProcess:
+ return subprocess.run(["cua", *args], capture_output=True, text=True)
+
+
[email protected](_IS_MACOS_ARM, reason="x86_64 Windows TCG too slow on macOS Apple Silicon")
[email protected](not _has_qemu(), reason="QEMU not available")
+async def test_windows_local_vm():
+ result = _cua("sb", "launch", "windows:11", "--local", "--json")
+ assert result.returncode == 0, f"launch failed:\n{result.stderr}"
+ name = json.loads(result.stdout)["name"]
+
+ try:
+ async with Sandbox.connect(name, local=True) as sb:
+ out = await sb.shell.run("ver")
+ assert out.success or "Windows" in out.stdout
+
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+ finally:
+ _cua("sb", "delete", name, "--local")
+
+
+async def main():
+ r = _cua("sb", "launch", "windows:11", "--local", "--json")
+ print(f"launch exit={r.returncode}")
+ name = json.loads(r.stdout)["name"]
+ print(f"name: {name}")
+
+ try:
+ async with Sandbox.connect(name, local=True) as sb:
+ out = await sb.shell.run("ver")
+ print(f"ver: {out.stdout.strip()}")
+ screenshot = await sb.screenshot()
+ print(f"Screenshot: {len(screenshot)} bytes")
+ with open("/tmp/cli_windows_local_vm.png", "wb") as f:
+ f.write(screenshot)
+ finally:
+ _cua("sb", "delete", name, "--local")
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/sandboxes/test_android_cloud_vm.py b/examples/sandboxes/test_android_cloud_vm.py
new file mode 100644
index 0000000000..d6e09c76dd
--- /dev/null
+++ b/examples/sandboxes/test_android_cloud_vm.py
@@ -0,0 +1,71 @@
+"""Run a cloud Android VM in Python with the Cua Sandbox SDK.
+
+ async with Sandbox.ephemeral(Image.android("14")) as sb:
+ screenshot = await sb.screenshot()
+ await sb.mobile.tap(540, 960)
+
+Sandbox.ephemeral() without local=True provisions an Android VM on the Cua cloud.
+Requires CUA_API_KEY environment variable. No Android SDK or emulator needed.
+
+The sb.mobile interface provides touch, gesture, and hardware key controls:
+ sb.mobile.tap(x, y)
+ sb.mobile.swipe(x1, y1, x2, y2, duration_ms=300)
+ sb.mobile.home() / sb.mobile.back() / sb.mobile.recents()
+ sb.mobile.type_text("hello")
+
+Contrast:
+ Image.android("14") + local=False -> Cua cloud Android VM (this file)
+ Image.android("14") + local=True -> Android SDK emulator on your machine
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+
+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_android_cloud_vm():
+ async with Sandbox.ephemeral(
+ Image.android("14"),
+ name="example-android-cloud-vm",
+ ) as sb:
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+ assert len(screenshot) > 1000
+
+ w, h = await sb.screen.size()
+ assert w > 0 and h > 0
+
+ await sb.mobile.home()
+
+
+async def main():
+ async with Sandbox.ephemeral(
+ Image.android("14"),
+ name="example-android-cloud-vm",
+ ) as sb:
+ screenshot = await sb.screenshot()
+ print(f"Screenshot: {len(screenshot)} bytes")
+ with open("/tmp/android_cloud_vm.png", "wb") as f:
+ f.write(screenshot)
+
+ w, h = await sb.screen.size()
+ print(f"Screen size: {w}x{h}")
+
+ await sb.mobile.tap(w // 2, h // 2)
+ await sb.mobile.home()
+ print("Tap + home: OK")
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/sandboxes/test_android_local_gym_pwa.py b/examples/sandboxes/test_android_local_gym_pwa.py
new file mode 100644
index 0000000000..d12aee182b
--- /dev/null
+++ b/examples/sandboxes/test_android_local_gym_pwa.py
@@ -0,0 +1,290 @@
+"""End-to-end test: gym-pwa on Modal, agent inside Android emulator as TWA.
+
+Flow:
+ 1. Build + cache TWA APK from the gym-pwa keystore (bundled in repo)
+ 2. Launch android:14 emulator, install the signed TWA APK via pwa_install
+ 3. POST /gym/start/add_item → seeds DB, returns session_id + task prompt
+ 4. Launch TWA app with ?session=<session_id> — no Chrome FRE, no browser UI
+ 5. Agent taps the input, types the item, taps Add
+ 6. GET /gym/evaluate (x-session-id header) → { success, reward }
+ 7. Assert reward == 1.0
+
+The gym REST API (hosted on Modal) is the I/O channel.
+The TWA is signed with android.keystore from the gym-pwa repo; the Modal
+deployment serves the matching fingerprint from /.well-known/assetlinks.json.
+
+Requires:
+ - Java (for Android SDK auto-install + keytool)
+ - Node + npm (for bubblewrap)
+ - gym-pwa repo checked out at GYM_PWA_DIR (defaults to ~/gym-pwa)
+ — only needed for the android.keystore file
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+import pytest
+
+pytestmark = pytest.mark.asyncio
+
+# ── Config ────────────────────────────────────────────────────────────────────
+
+GYM_URL = os.environ.get("GYM_URL", "https://cuaai--todo-gym-web.modal.run")
+GYM_PWA_DIR = Path(os.environ.get("GYM_PWA_DIR", Path.home() / "gym-pwa"))
+TWA_PACKAGE = "com.cuaai.gymtodo"
+TWA_MANIFEST_URL = f"{GYM_URL}/manifest.json"
+GYM_KEYSTORE = GYM_PWA_DIR / "android.keystore"
+BG_COLOR = "#dbe4ff" # light indigo tint — visually distinct without obscuring UI
+
+
+# ── Prereq checks ─────────────────────────────────────────────────────────────
+
+
+def _has_java() -> bool:
+ try:
+ from cua_sandbox.runtime.android_emulator import _java_env
+
+ _java_env()
+ return True
+ except Exception:
+ return False
+
+
+def _has_keystore() -> bool:
+ return GYM_KEYSTORE.exists()
+
+
+# ── Gym API helpers ───────────────────────────────────────────────────────────
+
+
+def _gym_request(
+ method: str, path: str, body: dict | None = None, session_id: str | None = None
+) -> dict:
+ url = f"{GYM_URL}{path}"
+ data = json.dumps(body).encode() if body else None
+ hdrs: dict[str, str] = {}
+ if data:
+ hdrs["Content-Type"] = "application/json"
+ if session_id:
+ hdrs["x-session-id"] = session_id
+ req = urllib.request.Request(url, data=data, method=method, headers=hdrs)
+ with urllib.request.urlopen(req, timeout=15) as r:
+ return json.loads(r.read())
+
+
+# ── Test ──────────────────────────────────────────────────────────────────────
+
+_SKIP_REASON = (
+ "Java not found"
+ if not _has_java()
+ else (
+ f"android.keystore not found at {GYM_KEYSTORE} (clone trycua/android-example-gym-pwa-app)"
+ if not _has_keystore()
+ else None
+ )
+)
+
+
[email protected](_SKIP_REASON is not None, reason=_SKIP_REASON or "")
+async def test_android_local_gym_pwa():
+ from cua_sandbox import Sandbox
+ from cua_sandbox.image import Image
+
+ async with Sandbox.ephemeral(
+ Image.android().pwa_install(
+ TWA_MANIFEST_URL,
+ package_name=TWA_PACKAGE,
+ keystore=str(GYM_KEYSTORE),
+ ),
+ local=True,
+ ) as sb:
+ # ── 1. Seed via gym REST API (creates a fresh session + bg color) ─────
+ start = _gym_request("POST", "/api/gym/start/add_item", body={"bgColor": BG_COLOR})
+ assert start["success"], f"start failed: {start}"
+ assert "Buy groceries" in start["prompt"], f"unexpected prompt: {start['prompt']}"
+ session_id = start["sessionId"]
+
+ session_url = f"{GYM_URL}/?session={session_id}&bg={urllib.parse.quote(BG_COLOR, safe='')}"
+
+ # ── 2. Launch TWA to warm up Chrome / TWA runtime ────────────────────
+ await sb.shell.run(
+ f"am start -n {TWA_PACKAGE}/.LauncherActivity "
+ f"-a android.intent.action.MAIN "
+ f"-c android.intent.category.LAUNCHER"
+ )
+
+ # ── 3. Wait for CDP, then navigate to ?session=<id>&bg=<color> ───────
+ import websockets
+
+ async with sb.tunnel.forward("chrome_devtools_remote") as t:
+ # Poll until Chrome is ready
+ ws_url = None
+ for _ in range(60):
+ try:
+ with urllib.request.urlopen(f"{t.url}/json", timeout=2) as r:
+ targets = json.loads(r.read())
+ if targets and targets[0].get("webSocketDebuggerUrl"):
+ ws_url = targets[0]["webSocketDebuggerUrl"].replace(
+ "localhost/", f"localhost:{t.port}/"
+ )
+ break
+ except Exception:
+ pass
+ await asyncio.sleep(1)
+ assert ws_url, "CDP target never appeared"
+
+ # Navigate to session URL and wait for Page.loadEventFired
+ async with websockets.connect(ws_url) as ws:
+ await ws.send(json.dumps({"id": 1, "method": "Page.enable"}))
+ await ws.send(
+ json.dumps({"id": 2, "method": "Page.navigate", "params": {"url": session_url}})
+ )
+ deadline = asyncio.get_event_loop().time() + 20
+ while asyncio.get_event_loop().time() < deadline:
+ try:
+ msg = json.loads(await asyncio.wait_for(ws.recv(), timeout=2))
+ if msg.get("method") == "Page.loadEventFired":
+ break
+ except asyncio.TimeoutError:
+ continue
+
+ await asyncio.sleep(6) # let React render
+
+ shot = await sb.screenshot()
+ assert shot[:4] == b"\x89PNG"
+ with open("/tmp/gym_pwa_pre_agent.png", "wb") as f:
+ f.write(shot)
+
+ # ── 4. Agent: tap input, type, tap Add ────────────────────────────
+ w, h = await sb.screen.size()
+ await sb.mobile.tap(w // 2, int(h * 0.18))
+ await asyncio.sleep(0.5)
+ await sb.mobile.type_text("Buy groceries")
+ await asyncio.sleep(0.3)
+ await sb.mobile.tap(int(w * 0.85), int(h * 0.18))
+ await asyncio.sleep(1)
+
+ # ── 5. Evaluate ───────────────────────────────────────────────────
+ result = _gym_request("GET", "/api/gym/evaluate", session_id=session_id)
+ assert result[
+ "success"
+ ], f"eval failed: reward={result['reward']}, msg={result['message']}"
+ assert result["reward"] == 1.0, f"expected reward 1.0, got {result['reward']}"
+
+ # ── 6. CDP: verify item appears in DOM ────────────────────────────
+ with urllib.request.urlopen(f"{t.url}/json", timeout=3) as r:
+ targets = json.loads(r.read())
+ assert targets, "CDP: no targets found"
+ ws_url = targets[0]["webSocketDebuggerUrl"].replace(
+ "localhost/", f"localhost:{t.port}/"
+ )
+ async with websockets.connect(ws_url) as ws:
+ await ws.send(
+ json.dumps(
+ {
+ "id": 1,
+ "method": "Runtime.evaluate",
+ "params": {
+ "expression": "Array.from(document.querySelectorAll('li span')).map(e=>e.textContent)",
+ "returnByValue": True,
+ },
+ }
+ )
+ )
+ raw = await asyncio.wait_for(ws.recv(), timeout=10)
+ resp = json.loads(raw)
+ texts = resp.get("result", {}).get("result", {}).get("value", [])
+ assert any(
+ "buy groceries" in item.lower() for item in texts
+ ), f"CDP: 'buy groceries' not found in {texts}"
+
+
+# ── Manual runner ─────────────────────────────────────────────────────────────
+
+
+async def main():
+ from cua_sandbox import Sandbox
+ from cua_sandbox.image import Image
+
+ print(f"Using gym at {GYM_URL}")
+ print(f"Building TWA APK from {TWA_MANIFEST_URL} ...")
+
+ import websockets
+
+ async with Sandbox.ephemeral(
+ Image.android().pwa_install(
+ TWA_MANIFEST_URL,
+ package_name=TWA_PACKAGE,
+ keystore=str(GYM_KEYSTORE),
+ ),
+ local=True,
+ ) as sb:
+ start = _gym_request("POST", "/api/gym/start/add_item", body={"bgColor": BG_COLOR})
+ session_id = start["sessionId"]
+ session_url = f"{GYM_URL}/?session={session_id}&bg={urllib.parse.quote(BG_COLOR, safe='')}"
+ print(f"Task: {start['prompt']} session: {session_id} bg: {BG_COLOR}")
+
+ await sb.shell.run(
+ f"am start -n {TWA_PACKAGE}/.LauncherActivity "
+ f"-a android.intent.action.MAIN "
+ f"-c android.intent.category.LAUNCHER"
+ )
+
+ async with sb.tunnel.forward("chrome_devtools_remote") as t:
+ ws_url = None
+ for _ in range(60):
+ try:
+ with urllib.request.urlopen(f"{t.url}/json", timeout=2) as r:
+ targets = json.loads(r.read())
+ if targets and targets[0].get("webSocketDebuggerUrl"):
+ ws_url = targets[0]["webSocketDebuggerUrl"].replace(
+ "localhost/", f"localhost:{t.port}/"
+ )
+ break
+ except Exception:
+ pass
+ await asyncio.sleep(1)
+
+ async with websockets.connect(ws_url) as ws:
+ await ws.send(json.dumps({"id": 1, "method": "Page.enable"}))
+ await ws.send(
+ json.dumps({"id": 2, "method": "Page.navigate", "params": {"url": session_url}})
+ )
+ deadline = asyncio.get_event_loop().time() + 20
+ while asyncio.get_event_loop().time() < deadline:
+ try:
+ msg = json.loads(await asyncio.wait_for(ws.recv(), timeout=2))
+ if msg.get("method") == "Page.loadEventFired":
+ break
+ except asyncio.TimeoutError:
+ continue
+
+ await asyncio.sleep(3)
+
+ w, h = await sb.screen.size()
+ await sb.mobile.tap(w // 2, int(h * 0.18))
+ await asyncio.sleep(0.5)
+ await sb.mobile.type_text("Buy groceries")
+ await asyncio.sleep(0.3)
+ await sb.mobile.tap(int(w * 0.85), int(h * 0.18))
+ await asyncio.sleep(1)
+
+ shot = await sb.screenshot()
+ with open("/tmp/gym_pwa_after_add.png", "wb") as f:
+ f.write(shot)
+ print("Screenshot saved to /tmp/gym_pwa_after_add.png")
+
+ result = _gym_request("GET", "/api/gym/evaluate", session_id=session_id)
+ print(
+ f"Eval: success={result['success']} reward={result['reward']} msg={result['message']}"
+ )
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/sandboxes/test_android_local_vm.py b/examples/sandboxes/test_android_local_vm.py
new file mode 100644
index 0000000000..cdddd1920a
--- /dev/null
+++ b/examples/sandboxes/test_android_local_vm.py
@@ -0,0 +1,81 @@
+"""Run a local Android VM in Python with the Cua Sandbox SDK.
+
+ async with Sandbox.ephemeral(Image.android("14"), local=True) as sb:
+ screenshot = await sb.screenshot()
+ await sb.mobile.tap(540, 960)
+
+Sandbox.ephemeral() auto-selects AndroidEmulatorRuntime for Android images on a
+local host with Android SDK installed. Use local=True to run on your machine;
+drop it to run on the Cua cloud instead.
+
+The sb.mobile interface provides touch, gesture, and hardware key controls:
+ sb.mobile.tap(x, y)
+ sb.mobile.swipe(x1, y1, x2, y2, duration_ms=300)
+ sb.mobile.home() / sb.mobile.back() / sb.mobile.recents()
+ sb.mobile.type_text("hello")
+
+Contrast:
+ Image.android("14") + local=True -> Android SDK emulator (this file)
+ Image.android("14") + local=False -> Cua cloud Android VM
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+from cua_sandbox import Image, Sandbox
+
+pytestmark = pytest.mark.asyncio
+
+
+def _has_android_sdk() -> bool:
+ try:
+ from cua_sandbox.runtime.android_emulator import _find_bin, _sdk_path
+
+ sdk = _sdk_path()
+ _find_bin(sdk, "emulator")
+ _find_bin(sdk, "adb")
+ return True
+ except Exception:
+ return False
+
+
[email protected](not _has_android_sdk(), reason="Android SDK not available")
+async def test_android_local_vm():
+ async with Sandbox.ephemeral(
+ Image.android("14"),
+ local=True,
+ name="example-android-local-vm",
+ ) as sb:
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+ assert len(screenshot) > 10000
+
+ w, h = await sb.screen.size()
+ assert w > 0 and h > 0
+
+ await sb.mobile.home()
+
+
+async def main():
+ async with Sandbox.ephemeral(
+ Image.android("14"),
+ local=True,
+ name="example-android-local-vm",
+ ) as sb:
+ screenshot = await sb.screenshot()
+ print(f"Screenshot: {len(screenshot)} bytes")
+ with open("/tmp/android_local_vm.png", "wb") as f:
+ f.write(screenshot)
+
+ w, h = await sb.screen.size()
+ print(f"Screen size: {w}x{h}")
+
+ await sb.mobile.tap(w // 2, h // 2)
+ await sb.mobile.home()
+ print("Tap + home: OK")
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/sandboxes/test_linux_cloud_container.py b/examples/sandboxes/test_linux_cloud_container.py
new file mode 100644
index 0000000000..2f83e7da38
--- /dev/null
+++ b/examples/sandboxes/test_linux_cloud_container.py
@@ -0,0 +1,60 @@
+"""Run a cloud Linux container in Python with the Cua Sandbox SDK.
+
+ async with Sandbox.ephemeral(Image.linux()) as sb:
+ await sb.shell.run("uname -a")
+ screenshot = await sb.screenshot()
+
+Sandbox.ephemeral() without local=True provisions a container on the Cua cloud.
+Requires CUA_API_KEY environment variable. No Docker or local runtime needed.
+
+Contrast:
+ Image.linux() + local=False -> Cua cloud container (this file)
+ Image.linux() + local=True -> Docker container on your machine
+ Image.linux(kind="vm") + local=False -> Cua cloud VM
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+
+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_linux_cloud_container():
+ async with Sandbox.ephemeral(
+ Image.linux("ubuntu", "24.04"),
+ name="example-linux-cloud-container",
+ ) as sb:
+ result = await sb.shell.run("uname -s")
+ assert result.success
+ assert "Linux" in result.stdout
+
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+
+
+async def main():
+ async with Sandbox.ephemeral(
+ Image.linux("ubuntu", "24.04"),
+ name="example-linux-cloud-container",
+ ) as sb:
+ result = await sb.shell.run("uname -s")
+ print(f"uname: {result.stdout.strip()}")
+
+ screenshot = await sb.screenshot()
+ print(f"Screenshot: {len(screenshot)} bytes")
+ with open("/tmp/linux_cloud_container.png", "wb") as f:
+ f.write(screenshot)
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/sandboxes/test_linux_cloud_vm.py b/examples/sandboxes/test_linux_cloud_vm.py
new file mode 100644
index 0000000000..07a5013cd4
--- /dev/null
+++ b/examples/sandboxes/test_linux_cloud_vm.py
@@ -0,0 +1,60 @@
+"""Run a cloud Linux VM in Python with the Cua Sandbox SDK.
+
+ async with Sandbox.ephemeral(Image.linux(kind="vm")) as sb:
+ await sb.shell.run("uname -a")
+ screenshot = await sb.screenshot()
+
+Sandbox.ephemeral() without local=True provisions a full Linux VM on the Cua cloud.
+Requires CUA_API_KEY environment variable. No local runtime or Docker needed.
+
+Contrast:
+ Image.linux(kind="vm") + local=False -> Cua cloud VM (this file)
+ Image.linux(kind="vm") + local=True -> QEMU VM on your machine
+ Image.linux() + local=False -> Cua cloud container (lighter)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+
+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_linux_cloud_vm():
+ async with Sandbox.ephemeral(
+ Image.linux("ubuntu", "24.04", kind="vm"),
+ name="example-linux-cloud-vm",
+ ) as sb:
+ result = await sb.shell.run("uname -s")
+ assert result.success
+ assert "Linux" in result.stdout
+
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+
+
+async def main():
+ async with Sandbox.ephemeral(
+ Image.linux("ubuntu", "24.04", kind="vm"),
+ name="example-linux-cloud-vm",
+ ) as sb:
+ result = await sb.shell.run("uname -s")
+ print(f"uname: {result.stdout.strip()}")
+
+ screenshot = await sb.screenshot()
+ print(f"Screenshot: {len(screenshot)} bytes")
+ with open("/tmp/linux_cloud_vm.png", "wb") as f:
+ f.write(screenshot)
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/sandboxes/test_linux_local_container.py b/examples/sandboxes/test_linux_local_container.py
new file mode 100644
index 0000000000..369cac5ab9
--- /dev/null
+++ b/examples/sandboxes/test_linux_local_container.py
@@ -0,0 +1,67 @@
+"""Run a local Linux container in Python with the Cua Sandbox SDK.
+
+ async with Sandbox.ephemeral(Image.linux(), local=True) as sb:
+ await sb.shell.run("uname -a")
+ screenshot = await sb.screenshot()
+
+Sandbox.ephemeral() auto-selects DockerRuntime for container images,
+provisions the environment, and tears it down on exit. Use local=True to run on
+your machine; drop it to run on the Cua cloud instead.
+
+Contrast:
+ Image.linux() + local=True -> Docker container (fast, no VM overhead)
+ Image.linux(kind="vm") + local=True -> QEMU VM (full kernel isolation)
+ Image.linux() + local=False -> Cua cloud container
+"""
+
+from __future__ import annotations
+
+import asyncio
+import subprocess
+
+import pytest
+from cua_sandbox import Image, Sandbox
+
+pytestmark = pytest.mark.asyncio
+
+
+def _has_docker() -> bool:
+ try:
+ subprocess.run(["docker", "info"], capture_output=True, check=True, timeout=10)
+ return True
+ except (subprocess.SubprocessError, FileNotFoundError):
+ return False
+
+
[email protected](not _has_docker(), reason="Docker not available")
+async def test_linux_local_container():
+ async with Sandbox.ephemeral(
+ Image.linux("ubuntu", "24.04"),
+ local=True,
+ name="example-linux-local-container",
+ ) as sb:
+ result = await sb.shell.run("uname -s")
+ assert result.success
+ assert "Linux" in result.stdout
+
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+
+
+async def main():
+ async with Sandbox.ephemeral(
+ Image.linux("ubuntu", "24.04"),
+ local=True,
+ name="example-linux-local-container",
+ ) as sb:
+ result = await sb.shell.run("uname -s")
+ print(f"uname: {result.stdout.strip()}")
+
+ screenshot = await sb.screenshot()
+ print(f"Screenshot: {len(screenshot)} bytes")
+ with open("/tmp/linux_local_container.png", "wb") as f:
+ f.write(screenshot)
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/sandboxes/test_linux_local_osworld_vm.py b/examples/sandboxes/test_linux_local_osworld_vm.py
new file mode 100644
index 0000000000..95838e3653
--- /dev/null
+++ b/examples/sandboxes/test_linux_local_osworld_vm.py
@@ -0,0 +1,91 @@
+"""Run a local Linux VM from a custom qcow2 image with the Cua Sandbox SDK.
+
+ image = Image.from_file("path/to/disk.qcow2", os_type="linux")
+ async with Sandbox.ephemeral(image, local=True) as sb:
+ screenshot = await sb.screenshot()
+ await sb.shell.run("uname -a")
+
+Image.from_file() accepts a local qcow2 path or a remote URL (zip or raw).
+The Cua Sandbox SDK downloads, extracts, and caches it automatically.
+
+Pass agent_type="osworld" to use the OSWorld Flask transport instead of
+computer-server — useful for running OSWorld benchmarks against existing images.
+
+ image = Image.from_file(OSWORLD_URL, os_type="linux", agent_type="osworld")
+
+Contrast:
+ Image.linux() -> managed Cua image, auto-provisioned
+ Image.from_file("disk.qcow2", ...) -> your own disk image, local QEMU
+ Image.from_file(url, agent_type="osworld") -> OSWorld benchmark image
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+from cua_sandbox import Image, Sandbox
+from cua_sandbox.runtime import QEMURuntime
+
+pytestmark = pytest.mark.asyncio
+
+OSWORLD_IMAGE = (
+ "https://huggingface.co/datasets/xlangai/ubuntu_osworld/resolve/main/Ubuntu.qcow2.zip"
+)
+
+
+def _has_osworld_image() -> bool:
+ from pathlib import Path
+
+ cache = Path.home() / ".cua" / "cua-sandbox" / "image-cache"
+ return any(cache.rglob("Ubuntu.qcow2")) if cache.exists() else False
+
+
+def _has_qemu() -> bool:
+ try:
+ from cua_sandbox.runtime.qemu_installer import qemu_bin
+
+ qemu_bin("x86_64")
+ return True
+ except Exception:
+ return False
+
+
[email protected](not _has_qemu(), reason="QEMU not available")
[email protected](not _has_osworld_image(), reason="OSWorld Ubuntu.qcow2 not in image cache")
+async def test_linux_local_osworld_vm():
+ async with Sandbox.ephemeral(
+ Image.from_file(OSWORLD_IMAGE, os_type="linux", agent_type="osworld"),
+ local=True,
+ runtime=QEMURuntime(
+ mode="bare-metal", api_port=18020, vnc_display=20, memory_mb=4096, cpu_count=4
+ ),
+ name="example-linux-local-osworld-vm",
+ ) as sb:
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+
+ w, h = await sb.get_dimensions()
+ assert w == 1920 and h == 1080
+
+
+async def main():
+ async with Sandbox.ephemeral(
+ Image.from_file(OSWORLD_IMAGE, os_type="linux", agent_type="osworld"),
+ local=True,
+ runtime=QEMURuntime(
+ mode="bare-metal", api_port=18020, vnc_display=20, memory_mb=4096, cpu_count=4
+ ),
+ name="example-linux-local-osworld-vm",
+ ) as sb:
+ screenshot = await sb.screenshot()
+ print(f"Screenshot: {len(screenshot)} bytes")
+ with open("/tmp/linux_local_osworld_vm.png", "wb") as f:
+ f.write(screenshot)
+
+ w, h = await sb.get_dimensions()
+ print(f"Screen: {w}x{h}")
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/sandboxes/test_linux_local_registry_vm.py b/examples/sandboxes/test_linux_local_registry_vm.py
new file mode 100644
index 0000000000..fa115ddb18
--- /dev/null
+++ b/examples/sandboxes/test_linux_local_registry_vm.py
@@ -0,0 +1,76 @@
+"""Run a local Linux VM from a trycua OCI registry image with the Cua Sandbox SDK.
+
+ async with Sandbox.ephemeral(
+ Image.from_registry("ghcr.io/trycua/cua-xfce:latest"),
+ local=True,
+ runtime=TartRuntime(),
+ ) as sb:
+ await sb.shell.run("uname -a")
+ screenshot = await sb.screenshot()
+
+TartRuntime uses Apple's Virtualization.framework (via Tart CLI) to run OCI VM images.
+Image.from_registry() is required — TartRuntime only works with OCI registry references.
+
+Contrast:
+ Image.linux("ubuntu", "24.04", kind="vm") + local=True -> QEMU VM, managed Cua image
+ Image.from_registry("ghcr.io/trycua/...") + local=True + TartRuntime -> Tart VM, OCI registry image (macOS only)
+ Image.from_registry("ghcr.io/trycua/...") + local=False -> Cua cloud VM
+"""
+
+from __future__ import annotations
+
+import asyncio
+import platform
+import subprocess
+
+import pytest
+from cua_sandbox import Image, Sandbox
+from cua_sandbox.runtime import TartRuntime
+
+pytestmark = pytest.mark.asyncio
+
+IS_MACOS = platform.system() == "Darwin"
+
+
+def _has_tart() -> bool:
+ try:
+ subprocess.run(["tart", "--version"], capture_output=True, check=True)
+ return True
+ except (subprocess.SubprocessError, FileNotFoundError):
+ return False
+
+
[email protected](not IS_MACOS or not _has_tart(), reason="Tart only on macOS")
+async def test_linux_local_registry_vm():
+ async with Sandbox.ephemeral(
+ Image.from_registry("ghcr.io/trycua/cua-xfce:latest"),
+ local=True,
+ runtime=TartRuntime(),
+ name="example-linux-local-registry-vm",
+ ) as sb:
+ result = await sb.shell.run("uname -s")
+ assert result.success
+ assert "Linux" in result.stdout
+
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+
+
+async def main():
+ async with Sandbox.ephemeral(
+ Image.from_registry("ghcr.io/trycua/cua-xfce:latest"),
+ local=True,
+ runtime=TartRuntime(),
+ name="example-linux-local-registry-vm",
+ ) as sb:
+ result = await sb.shell.run("uname -s")
+ print(f"uname: {result.stdout.strip()}")
+
+ screenshot = await sb.screenshot()
+ print(f"Screenshot: {len(screenshot)} bytes")
+ with open("/tmp/linux_local_registry_vm.png", "wb") as f:
+ f.write(screenshot)
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/sandboxes/test_linux_local_vm.py b/examples/sandboxes/test_linux_local_vm.py
new file mode 100644
index 0000000000..e673147152
--- /dev/null
+++ b/examples/sandboxes/test_linux_local_vm.py
@@ -0,0 +1,67 @@
+"""Run a local Linux VM in Python with the Cua Sandbox SDK.
+
+ async with Sandbox.ephemeral(Image.linux(kind="vm"), local=True) as sb:
+ await sb.shell.run("uname -a")
+ screenshot = await sb.screenshot()
+
+Sandbox.ephemeral() auto-selects QEMURuntime (docker mode) for Linux VMs,
+provisions the environment, and tears it down on exit. Use local=True to run on
+your machine; drop it to run on the Cua cloud instead.
+
+Contrast:
+ Image.linux() + local=True -> Docker container (fast, no VM overhead)
+ Image.linux(kind="vm") + local=True -> QEMU VM (full kernel isolation)
+ Image.linux(kind="vm") + local=False -> Cua cloud VM
+"""
+
+from __future__ import annotations
+
+import asyncio
+import subprocess
+
+import pytest
+from cua_sandbox import Image, Sandbox
+
+pytestmark = pytest.mark.asyncio
+
+
+def _has_docker() -> bool:
+ try:
+ subprocess.run(["docker", "info"], capture_output=True, check=True, timeout=10)
+ return True
+ except (subprocess.SubprocessError, FileNotFoundError):
+ return False
+
+
[email protected](not _has_docker(), reason="Docker not available")
+async def test_linux_local_vm():
+ async with Sandbox.ephemeral(
+ Image.linux("ubuntu", "24.04", kind="vm"),
+ local=True,
+ name="example-linux-local-vm",
+ ) as sb:
+ result = await sb.shell.run("uname -s")
+ assert result.success
+ assert "Linux" in result.stdout
+
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+
+
+async def main():
+ async with Sandbox.ephemeral(
+ Image.linux("ubuntu", "24.04", kind="vm"),
+ local=True,
+ name="example-linux-local-vm",
+ ) as sb:
+ result = await sb.shell.run("uname -s")
+ print(f"uname: {result.stdout.strip()}")
+
+ screenshot = await sb.screenshot()
+ print(f"Screenshot: {len(screenshot)} bytes")
+ with open("/tmp/linux_local_vm.png", "wb") as f:
+ f.write(screenshot)
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/sandboxes/test_macos_cloud_vm.py b/examples/sandboxes/test_macos_cloud_vm.py
new file mode 100644
index 0000000000..ca9b760d4c
--- /dev/null
+++ b/examples/sandboxes/test_macos_cloud_vm.py
@@ -0,0 +1,59 @@
+"""Run a cloud macOS VM in Python with the Cua Sandbox SDK.
+
+ async with Sandbox.ephemeral(Image.macos("26")) as sb:
+ await sb.shell.run("sw_vers")
+ screenshot = await sb.screenshot()
+
+Sandbox.ephemeral() without local=True provisions a macOS VM on the Cua cloud.
+Requires CUA_API_KEY environment variable. Works on any host OS — no Mac needed.
+
+Contrast:
+ Image.macos("26") + local=False -> Cua cloud macOS VM (this file)
+ Image.macos("26") + local=True -> Lume VM, macOS host only
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+
+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_macos_cloud_vm():
+ async with Sandbox.ephemeral(
+ Image.macos("26"),
+ name="example-macos-cloud-vm",
+ ) as sb:
+ result = await sb.shell.run("sw_vers")
+ assert result.success
+ assert "macOS" in result.stdout or "Mac" in result.stdout
+
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+
+
+async def main():
+ async with Sandbox.ephemeral(
+ Image.macos("26"),
+ name="example-macos-cloud-vm",
+ ) as sb:
+ result = await sb.shell.run("sw_vers")
+ print(f"sw_vers: {result.stdout.strip()}")
+
+ screenshot = await sb.screenshot()
+ print(f"Screenshot: {len(screenshot)} bytes")
+ with open("/tmp/macos_cloud_vm.png", "wb") as f:
+ f.write(screenshot)
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/sandboxes/test_macos_local_registry_vm.py b/examples/sandboxes/test_macos_local_registry_vm.py
new file mode 100644
index 0000000000..154b3befe3
--- /dev/null
+++ b/examples/sandboxes/test_macos_local_registry_vm.py
@@ -0,0 +1,72 @@
+"""Run a local macOS VM from a trycua OCI registry image with the Cua Sandbox SDK.
+
+ async with Sandbox.ephemeral(
+ Image.from_registry("ghcr.io/trycua/macos-tahoe-cua:latest"),
+ local=True,
+ ) as sb:
+ await sb.shell.run("sw_vers")
+ screenshot = await sb.screenshot()
+
+Image.from_registry() fetches the OCI manifest to resolve the image kind and OS,
+then auto-selects LumeRuntime for macOS VMs on a macOS host.
+
+Contrast:
+ Image.macos("26") + local=True -> Lume VM, managed Cua image (auto-resolved)
+ Image.from_registry("ghcr.io/trycua/macos-...") + local=True -> Lume VM, trycua registry image (manifest-resolved)
+ Image.from_registry("ghcr.io/trycua/macos-...") + local=False -> Cua cloud VM
+"""
+
+from __future__ import annotations
+
+import asyncio
+import platform
+import subprocess
+
+import pytest
+from cua_sandbox import Image, Sandbox
+
+pytestmark = pytest.mark.asyncio
+
+IS_MACOS = platform.system() == "Darwin"
+
+
+def _has_lume() -> bool:
+ try:
+ subprocess.run(["lume", "--version"], capture_output=True, check=True)
+ return True
+ except (subprocess.SubprocessError, FileNotFoundError):
+ return False
+
+
[email protected](not IS_MACOS or not _has_lume(), reason="Lume only on macOS")
+async def test_macos_local_registry_vm():
+ async with Sandbox.ephemeral(
+ Image.from_registry("ghcr.io/trycua/macos-tahoe-cua:latest"),
+ local=True,
+ name="example-macos-local-registry-vm",
+ ) as sb:
+ result = await sb.shell.run("sw_vers")
+ assert result.success
+ assert "macOS" in result.stdout or "Mac" in result.stdout
+
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+
+
+async def main():
+ async with Sandbox.ephemeral(
+ Image.from_registry("ghcr.io/trycua/macos-tahoe-cua:latest"),
+ local=True,
+ name="example-macos-local-registry-vm",
+ ) as sb:
+ result = await sb.shell.run("sw_vers")
+ print(f"sw_vers: {result.stdout.strip()}")
+
+ screenshot = await sb.screenshot()
+ print(f"Screenshot: {len(screenshot)} bytes")
+ with open("/tmp/macos_local_registry_vm.png", "wb") as f:
+ f.write(screenshot)
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/sandboxes/test_macos_local_vm.py b/examples/sandboxes/test_macos_local_vm.py
new file mode 100644
index 0000000000..c11f736fcd
--- /dev/null
+++ b/examples/sandboxes/test_macos_local_vm.py
@@ -0,0 +1,68 @@
+"""Run a local macOS VM in Python with the Cua Sandbox SDK.
+
+ async with Sandbox.ephemeral(Image.macos("26"), local=True) as sb:
+ await sb.shell.run("sw_vers")
+ screenshot = await sb.screenshot()
+
+Sandbox.ephemeral() auto-selects LumeRuntime for macOS VMs on a macOS host.
+Requires the Lume CLI: https://github.com/trycua/cua/tree/main/libs/lume
+
+Contrast:
+ Image.macos("26") + local=True -> Lume VM on macOS host (this file)
+ Image.macos("26") + local=False -> Cua cloud macOS VM (no Lume needed)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import platform
+import subprocess
+
+import pytest
+from cua_sandbox import Image, Sandbox
+
+pytestmark = pytest.mark.asyncio
+
+IS_MACOS = platform.system() == "Darwin"
+
+
+def _has_lume() -> bool:
+ try:
+ subprocess.run(["lume", "--version"], capture_output=True, check=True)
+ return True
+ except (subprocess.SubprocessError, FileNotFoundError):
+ return False
+
+
[email protected](not IS_MACOS or not _has_lume(), reason="Lume only on macOS")
+async def test_macos_local_vm():
+ async with Sandbox.ephemeral(
+ Image.macos("26"),
+ local=True,
+ name="example-macos-local-vm",
+ ) as sb:
+ result = await sb.shell.run("sw_vers")
+ assert result.success
+ assert "macOS" in result.stdout or "Mac" in result.stdout
+
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+
+
+async def main():
+ async with Sandbox.ephemeral(
+ Image.macos("26"),
+ local=True,
+ name="example-macos-local-vm",
+ ) as sb:
+ result = await sb.shell.run("sw_vers")
+ print(f"sw_vers: {result.stdout.strip()}")
+
+ screenshot = await sb.screenshot()
+ print(f"Screenshot: {len(screenshot)} bytes")
+ with open("/tmp/macos_local_vm.png", "wb") as f:
+ f.write(screenshot)
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/sandboxes/test_windows_cloud_vm.py b/examples/sandboxes/test_windows_cloud_vm.py
new file mode 100644
index 0000000000..1021a34d0b
--- /dev/null
+++ b/examples/sandboxes/test_windows_cloud_vm.py
@@ -0,0 +1,58 @@
+"""Run a cloud Windows VM in Python with the Cua Sandbox SDK.
+
+ async with Sandbox.ephemeral(Image.windows("11")) as sb:
+ await sb.shell.run("ver")
+ screenshot = await sb.screenshot()
+
+Sandbox.ephemeral() without local=True provisions a Windows VM on the Cua cloud.
+Requires CUA_API_KEY environment variable. Works on any host OS — no Windows needed.
+
+Contrast:
+ Image.windows("11") + local=False -> Cua cloud Windows VM (this file)
+ Image.windows("11") + local=True -> Hyper-V or QEMU VM on your machine
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+
+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_windows_cloud_vm():
+ async with Sandbox.ephemeral(
+ Image.windows("11"),
+ name="example-windows-cloud-vm",
+ ) as sb:
+ result = await sb.shell.run("ver")
+ assert result.success or "Windows" in result.stdout
+
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+
+
+async def main():
+ async with Sandbox.ephemeral(
+ Image.windows("11"),
+ name="example-windows-cloud-vm",
+ ) as sb:
+ result = await sb.shell.run("ver")
+ print(f"ver: {result.stdout.strip()}")
+
+ screenshot = await sb.screenshot()
+ print(f"Screenshot: {len(screenshot)} bytes")
+ with open("/tmp/windows_cloud_vm.png", "wb") as f:
+ f.write(screenshot)
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/sandboxes/test_windows_local_vm.py b/examples/sandboxes/test_windows_local_vm.py
new file mode 100644
index 0000000000..209089b575
--- /dev/null
+++ b/examples/sandboxes/test_windows_local_vm.py
@@ -0,0 +1,70 @@
+"""Run a local Windows VM in Python with the Cua Sandbox SDK.
+
+ async with Sandbox.ephemeral(Image.windows("11"), local=True) as sb:
+ await sb.shell.run("ver")
+ screenshot = await sb.screenshot()
+
+Sandbox.ephemeral() auto-selects HyperVRuntime on Windows hosts with Hyper-V,
+or QEMURuntime (bare-metal) as a fallback. Use local=True to run on your machine;
+drop it to run on the Cua cloud instead.
+
+Contrast:
+ Image.windows("11") + local=True -> Hyper-V or QEMU VM (this file)
+ Image.windows("11") + local=False -> Cua cloud Windows VM
+"""
+
+from __future__ import annotations
+
+import asyncio
+import platform
+
+import pytest
+from cua_sandbox import Image, Sandbox
+
+pytestmark = pytest.mark.asyncio
+
+IS_WINDOWS = platform.system() == "Windows"
+
+
+def _has_qemu() -> bool:
+ try:
+ from cua_sandbox.runtime.qemu_installer import qemu_bin
+
+ qemu_bin("x86_64")
+ return True
+ except Exception:
+ return False
+
+
[email protected](not IS_WINDOWS, reason="Windows host only")
[email protected](not _has_qemu(), reason="QEMU not available")
+async def test_windows_local_vm():
+ async with Sandbox.ephemeral(
+ Image.windows("11"),
+ local=True,
+ name="example-windows-local-vm",
+ ) as sb:
+ result = await sb.shell.run("ver")
+ assert result.success or "Windows" in result.stdout
+
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+
+
+async def main():
+ async with Sandbox.ephemeral(
+ Image.windows("11"),
+ local=True,
+ name="example-windows-local-vm",
+ ) as sb:
+ result = await sb.shell.run("ver")
+ print(f"ver: {result.stdout.strip()}")
+
+ screenshot = await sb.screenshot()
+ print(f"Screenshot: {len(screenshot)} bytes")
+ with open("/tmp/windows_local_vm.png", "wb") as f:
+ f.write(screenshot)
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/som_examples.py b/examples/som_examples.py
deleted file mode 100644
index 5cb4567f5f..0000000000
--- a/examples/som_examples.py
+++ /dev/null
@@ -1,440 +0,0 @@
-#!/usr/bin/env python3
-"""
-Example script demonstrating the usage of OmniParser's UI element detection functionality.
-This script shows how to:
-1. Initialize the OmniParser
-2. Load and process images
-3. Visualize detection results
-4. Compare performance between CPU and MPS (Apple Silicon)
-"""
-
-import argparse
-import base64
-import glob
-import io
-import logging
-import os
-import sys
-import time
-from pathlib import Path
-from typing import Any, Dict, List, Optional
-
-import numpy as np
-from PIL import Image
-
-# Load environment variables from .env file
-project_root = Path(__file__).parent.parent
-env_file = project_root / ".env"
-print(f"Loading environment from: {env_file}")
-from dotenv import load_dotenv
-
-load_dotenv(env_file)
-
-# Add paths to sys.path if needed
-pythonpath = os.environ.get("PYTHONPATH", "")
-for path in pythonpath.split(":"):
- if path and path not in sys.path:
- sys.path.append(path)
- print(f"Added to sys.path: {path}")
-
-# Add the libs directory to the path to find som
-libs_path = project_root / "libs"
-if str(libs_path) not in sys.path:
- sys.path.append(str(libs_path))
- print(f"Added to sys.path: {libs_path}")
-
-from som import IconElement, OmniParser, ParseResult, TextElement
-from som.models import BoundingBox, ParserMetadata, UIElement
-
-# Configure logging
-logging.basicConfig(
- level=logging.INFO,
- format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
- datefmt="%Y-%m-%d %H:%M:%S",
-)
-logger = logging.getLogger(__name__)
-
-
-def setup_logging():
- """Configure logging with a nice format."""
- logging.basicConfig(
- level=logging.INFO,
- format="%(asctime)s - %(levelname)s - %(message)s",
- datefmt="%Y-%m-%d %H:%M:%S",
- )
-
-
-class Timer:
- """Enhanced context manager for timing code blocks."""
-
- def __init__(self, name: str, logger):
- self.name = name
- self.logger = logger
- self.start_time: float = 0.0
- self.elapsed_time: float = 0.0
-
- def __enter__(self):
- self.start_time = time.time()
- return self
-
- def __exit__(self, *args):
- self.elapsed_time = time.time() - self.start_time
- self.logger.info(f"{self.name}: {self.elapsed_time:.3f}s")
- return False
-
-
-def image_to_bytes(image: Image.Image) -> bytes:
- """Convert PIL Image to PNG bytes."""
- buf = io.BytesIO()
- image.save(buf, format="PNG")
- return buf.getvalue()
-
-
-def process_image(
- parser: OmniParser, image_path: str, output_dir: Path, use_ocr: bool = False
-) -> None:
- """Process a single image and save the result."""
- try:
- # Load image
- logger.info(f"Processing image: {image_path}")
- image = Image.open(image_path).convert("RGB")
- logger.info(f"Image loaded successfully, size: {image.size}")
-
- # Create output filename
- input_filename = Path(image_path).stem
- output_path = output_dir / f"{input_filename}_analyzed.png"
-
- # Convert image to PNG bytes
- image_bytes = image_to_bytes(image)
-
- # Process image
- with Timer(f"Processing {input_filename}", logger):
- result = parser.parse(image_bytes, use_ocr=use_ocr)
- logger.info(
- f"Found {result.metadata.num_icons} icons and {result.metadata.num_text} text elements"
- )
-
- # Save the annotated image
- logger.info(f"Saving annotated image to: {output_path}")
- try:
- # Save image from base64
- img_data = base64.b64decode(result.annotated_image_base64)
- img = Image.open(io.BytesIO(img_data))
- img.save(output_path)
-
- # Print detailed results
- logger.info("\nDetected Elements:")
- for elem in result.elements:
- if isinstance(elem, IconElement):
- logger.info(
- f"Icon: confidence={elem.confidence:.3f}, bbox={elem.bbox.coordinates}"
- )
- elif isinstance(elem, TextElement):
- logger.info(
- f"Text: '{elem.content}', confidence={elem.confidence:.3f}, bbox={elem.bbox.coordinates}"
- )
-
- # Verify file exists and log size
- if output_path.exists():
- logger.info(
- f"Successfully saved image. File size: {output_path.stat().st_size} bytes"
- )
- else:
- logger.error(f"Failed to verify file at {output_path}")
- except Exception as e:
- logger.error(f"Error saving image: {str(e)}", exc_info=True)
-
- except Exception as e:
- logger.error(f"Error processing image {image_path}: {str(e)}", exc_info=True)
-
-
-def run_detection_benchmark(
- input_path: str,
- output_dir: Path,
- use_ocr: bool = False,
- box_threshold: float = 0.01,
- iou_threshold: float = 0.1,
-):
- """Run detection benchmark on images."""
- logger.info(
- f"Starting benchmark with OCR enabled: {use_ocr}, box_threshold: {box_threshold}, iou_threshold: {iou_threshold}"
- )
-
- try:
- # Initialize parser
- logger.info("Initializing OmniParser...")
- parser = OmniParser()
-
- # Create output directory
- output_dir.mkdir(parents=True, exist_ok=True)
- logger.info(f"Output directory created at: {output_dir}")
-
- # Get list of PNG files
- if os.path.isdir(input_path):
- image_files = glob.glob(os.path.join(input_path, "*.png"))
- else:
- image_files = [input_path]
-
- logger.info(f"Found {len(image_files)} images to process")
-
- # Process each image with specified thresholds
- for image_path in image_files:
- try:
- # Load image
- logger.info(f"Processing image: {image_path}")
- image = Image.open(image_path).convert("RGB")
- logger.info(f"Image loaded successfully, size: {image.size}")
-
- # Create output filename
- input_filename = Path(image_path).stem
- output_path = output_dir / f"{input_filename}_analyzed.png"
-
- # Convert image to PNG bytes
- image_bytes = image_to_bytes(image)
-
- # Process image with specified thresholds
- with Timer(f"Processing {input_filename}", logger):
- result = parser.parse(
- image_bytes,
- use_ocr=use_ocr,
- box_threshold=box_threshold,
- iou_threshold=iou_threshold,
- )
- logger.info(
- f"Found {result.metadata.num_icons} icons and {result.metadata.num_text} text elements"
- )
-
- # Save the annotated image
- logger.info(f"Saving annotated image to: {output_path}")
- try:
- # Save image from base64
- img_data = base64.b64decode(result.annotated_image_base64)
- img = Image.open(io.BytesIO(img_data))
- img.save(output_path)
-
- # Print detailed results
- logger.info("\nDetected Elements:")
- for elem in result.elements:
- if isinstance(elem, IconElement):
- logger.info(
- f"Icon: confidence={elem.confidence:.3f}, bbox={elem.bbox.coordinates}"
- )
- elif isinstance(elem, TextElement):
- logger.info(
- f"Text: '{elem.content}', confidence={elem.confidence:.3f}, bbox={elem.bbox.coordinates}"
- )
-
- # Verify file exists and log size
- if output_path.exists():
- logger.info(
- f"Successfully saved image. File size: {output_path.stat().st_size} bytes"
- )
- else:
- logger.error(f"Failed to verify file at {output_path}")
- except Exception as e:
- logger.error(f"Error saving image: {str(e)}", exc_info=True)
-
- except Exception as e:
- logger.error(f"Error processing image {image_path}: {str(e)}", exc_info=True)
-
- except Exception as e:
- logger.error(f"Benchmark failed: {str(e)}", exc_info=True)
- raise
-
-
-def run_experiments(input_path: str, output_dir: Path, use_ocr: bool = False):
- """Run experiments with different threshold combinations."""
- # Define threshold values to test
- box_thresholds = [0.01, 0.05, 0.1, 0.3]
- iou_thresholds = [0.05, 0.1, 0.2, 0.5]
-
- logger.info("Starting threshold experiments...")
- logger.info("Box thresholds to test: %s", box_thresholds)
- logger.info("IOU thresholds to test: %s", iou_thresholds)
-
- # Create results directory for this experiment
- timestamp = time.strftime("%Y%m%d-%H%M%S")
- ocr_suffix = "_ocr" if use_ocr else "_no_ocr"
- exp_dir = output_dir / f"experiment_{timestamp}{ocr_suffix}"
- exp_dir.mkdir(parents=True, exist_ok=True)
-
- # Create a summary file
- summary_file = exp_dir / "results_summary.txt"
- with open(summary_file, "w") as f:
- f.write("Threshold Experiments Results\n")
- f.write("==========================\n\n")
- f.write(f"Input: {input_path}\n")
- f.write(f"OCR Enabled: {use_ocr}\n")
- f.write(f"Date: {time.strftime('%Y-%m-%d %H:%M:%S')}\n\n")
- f.write("Results:\n")
- f.write("-" * 80 + "\n")
- f.write(
- f"{'Box Thresh':^10} | {'IOU Thresh':^10} | {'Num Icons':^10} | {'Num Text':^10} | {'Time (s)':^10}\n"
- )
- f.write("-" * 80 + "\n")
-
- # Initialize parser once for all experiments
- parser = OmniParser()
-
- # Run experiments with each combination
- for box_thresh in box_thresholds:
- for iou_thresh in iou_thresholds:
- logger.info(f"\nTesting box_threshold={box_thresh}, iou_threshold={iou_thresh}")
-
- # Create directory for this combination
- combo_dir = exp_dir / f"box_{box_thresh}_iou_{iou_thresh}"
- combo_dir.mkdir(exist_ok=True)
-
- try:
- # Process each image
- if os.path.isdir(input_path):
- image_files = glob.glob(os.path.join(input_path, "*.png"))
- else:
- image_files = [input_path]
-
- total_icons = 0
- total_text = 0
- total_time = 0
-
- for image_path in image_files:
- # Load and process image
- image = Image.open(image_path).convert("RGB")
- image_bytes = image_to_bytes(image)
-
- # Process with current thresholds
- with Timer(f"Processing {Path(image_path).stem}", logger) as t:
- result = parser.parse(
- image_bytes,
- use_ocr=use_ocr,
- box_threshold=box_thresh,
- iou_threshold=iou_thresh,
- )
-
- # Save annotated image
- output_path = combo_dir / f"{Path(image_path).stem}_analyzed.png"
- img_data = base64.b64decode(result.annotated_image_base64)
- img = Image.open(io.BytesIO(img_data))
- img.save(output_path)
-
- # Update totals
- total_icons += result.metadata.num_icons
- total_text += result.metadata.num_text
-
- # Log detailed results
- detail_file = combo_dir / f"{Path(image_path).stem}_details.txt"
- with open(detail_file, "w") as detail_f:
- detail_f.write(f"Results for {Path(image_path).name}\n")
- detail_f.write("-" * 40 + "\n")
- detail_f.write(f"Number of icons: {result.metadata.num_icons}\n")
- detail_f.write(
- f"Number of text elements: {result.metadata.num_text}\n\n"
- )
-
- detail_f.write("Icon Detections:\n")
- icon_count = 1
- text_count = (
- result.metadata.num_icons + 1
- ) # Text boxes start after icons
-
- # First list all icons
- for elem in result.elements:
- if isinstance(elem, IconElement):
- detail_f.write(f"Box #{icon_count}: Icon\n")
- detail_f.write(f" - Confidence: {elem.confidence:.3f}\n")
- detail_f.write(
- f" - Coordinates: {elem.bbox.coordinates}\n"
- )
- icon_count += 1
-
- if use_ocr:
- detail_f.write("\nText Detections:\n")
- for elem in result.elements:
- if isinstance(elem, TextElement):
- detail_f.write(f"Box #{text_count}: Text\n")
- detail_f.write(f" - Content: '{elem.content}'\n")
- detail_f.write(
- f" - Confidence: {elem.confidence:.3f}\n"
- )
- detail_f.write(
- f" - Coordinates: {elem.bbox.coordinates}\n"
- )
- text_count += 1
-
- # Update timing totals
- total_time += t.elapsed_time
-
- # Write summary for this combination
- avg_time = total_time / len(image_files)
- f.write(
- f"{box_thresh:^10.3f} | {iou_thresh:^10.3f} | {total_icons:^10d} | {total_text:^10d} | {avg_time:^10.3f}\n"
- )
-
- except Exception as e:
- logger.error(
- f"Error in experiment box={box_thresh}, iou={iou_thresh}: {str(e)}"
- )
- f.write(
- f"{box_thresh:^10.3f} | {iou_thresh:^10.3f} | {'ERROR':^10s} | {'ERROR':^10s} | {'ERROR':^10s}\n"
- )
-
- # Write summary footer
- f.write("-" * 80 + "\n")
- f.write("\nExperiment completed successfully!\n")
-
- logger.info(f"\nExperiment results saved to {exp_dir}")
- logger.info(f"Summary file: {summary_file}")
-
-
-def main():
- """Main entry point."""
- parser = argparse.ArgumentParser(description="Run OmniParser benchmark")
- parser.add_argument("input_path", help="Path to input image or directory containing images")
- parser.add_argument(
- "--output-dir", default="examples/output", help="Output directory for annotated images"
- )
- parser.add_argument(
- "--ocr",
- choices=["none", "easyocr"],
- default="none",
- help="OCR engine to use (default: none)",
- )
- parser.add_argument(
- "--mode",
- choices=["single", "experiment"],
- default="single",
- help="Run mode: single run or threshold experiments (default: single)",
- )
- parser.add_argument(
- "--box-threshold",
- type=float,
- default=0.01,
- help="Confidence threshold for detection (default: 0.01)",
- )
- parser.add_argument(
- "--iou-threshold",
- type=float,
- default=0.1,
- help="IOU threshold for Non-Maximum Suppression (default: 0.1)",
- )
- args = parser.parse_args()
-
- logger.info(f"Starting OmniParser with arguments: {args}")
- use_ocr = args.ocr != "none"
- output_dir = Path(args.output_dir)
-
- try:
- if args.mode == "experiment":
- run_experiments(args.input_path, output_dir, use_ocr)
- else:
- run_detection_benchmark(
- args.input_path, output_dir, use_ocr, args.box_threshold, args.iou_threshold
- )
- except Exception as e:
- logger.error(f"Process failed: {str(e)}", exc_info=True)
- return 1
-
- return 0
-
-
-if __name__ == "__main__":
- sys.exit(main())
diff --git a/examples/tracing_examples.py b/examples/tracing_examples.py
deleted file mode 100644
index f434bbe2d0..0000000000
--- a/examples/tracing_examples.py
+++ /dev/null
@@ -1,384 +0,0 @@
-"""
-Examples demonstrating the Computer.tracing API for recording sessions.
-
-This module shows various use cases for the new Computer.tracing functionality,
-including training data collection, debugging, and compliance recording.
-"""
-
-import asyncio
-import logging
-from pathlib import Path
-
-from agent import ComputerAgent
-from computer import Computer
-
-
-async def basic_tracing_example():
- """
- Basic example showing how to use Computer.tracing for recording a simple session.
- """
- print("=== Basic Tracing Example ===")
-
- # Initialize computer
- computer = Computer(os_type="macos", provider_type="lume")
- await computer.run()
-
- try:
- # Start tracing with basic configuration
- await computer.tracing.start(
- {"screenshots": True, "api_calls": True, "metadata": True, "name": "basic_session"}
- )
-
- print("Tracing started...")
-
- # Perform some computer operations
- await computer.interface.move_cursor(100, 100)
- await computer.interface.left_click()
- await computer.interface.type_text("Hello, tracing!")
- await computer.interface.press_key("enter")
-
- # Add custom metadata
- await computer.tracing.add_metadata("session_type", "basic_demo")
- await computer.tracing.add_metadata("user_notes", "Testing basic functionality")
-
- # Stop tracing and save
- trace_path = await computer.tracing.stop({"format": "zip"})
- print(f"Trace saved to: {trace_path}")
-
- finally:
- await computer.stop()
-
-
-async def agent_tracing_example():
- """
- Example showing how to use tracing with ComputerAgent for enhanced session recording.
- """
- print("=== Agent with Tracing Example ===")
-
- # Initialize computer and agent
- computer = Computer(os_type="macos", provider_type="lume")
- await computer.run()
-
- try:
- # Start comprehensive tracing
- await computer.tracing.start(
- {
- "screenshots": True,
- "api_calls": True,
- "accessibility_tree": True, # Include accessibility data for training
- "metadata": True,
- "name": "agent_session",
- }
- )
-
- # Create agent
- agent = ComputerAgent(
- model="openai/computer-use-preview", tools=[computer], verbosity=logging.INFO
- )
-
- # Add metadata about the agent session
- await computer.tracing.add_metadata("agent_model", "openai/computer-use-preview")
- await computer.tracing.add_metadata("task_type", "web_search")
-
- # Run agent task
- async for message in agent.run(
- "Open a web browser and search for 'computer use automation'"
- ):
- print(f"Agent: {message}")
-
- # Stop tracing
- trace_path = await computer.tracing.stop({"format": "zip"})
- print(f"Agent trace saved to: {trace_path}")
-
- finally:
- await computer.stop()
-
-
-async def custom_agent_tracing_example():
- """
- Example showing tracing with custom agent implementations.
- """
- print("=== Custom Agent Tracing Example ===")
-
- computer = Computer(os_type="macos", provider_type="lume")
- await computer.run()
-
- try:
- # Start tracing with custom path
- trace_dir = Path.cwd() / "custom_traces" / "my_agent_session"
- await computer.tracing.start(
- {
- "screenshots": True,
- "api_calls": True,
- "accessibility_tree": False,
- "metadata": True,
- "path": str(trace_dir),
- }
- )
-
- # Custom agent logic using direct computer calls
- await computer.tracing.add_metadata("session_type", "custom_agent")
- await computer.tracing.add_metadata("purpose", "RPA_workflow")
-
- # Take initial screenshot
- screenshot = await computer.interface.screenshot()
-
- # Simulate RPA workflow
- await computer.interface.move_cursor(500, 300)
- await computer.interface.left_click()
- await computer.interface.type_text("automation workflow test")
-
- # Add workflow checkpoint
- await computer.tracing.add_metadata("checkpoint", "text_input_complete")
-
- await computer.interface.hotkey("command", "a") # Select all
- await computer.interface.hotkey("command", "c") # Copy
-
- # Stop tracing and save as directory
- trace_path = await computer.tracing.stop({"format": "dir"})
- print(f"Custom agent trace saved to: {trace_path}")
-
- finally:
- await computer.stop()
-
-
-async def training_data_collection_example():
- """
- Example for collecting training data with rich context.
- """
- print("=== Training Data Collection Example ===")
-
- computer = Computer(os_type="macos", provider_type="lume")
- await computer.run()
-
- try:
- # Start tracing optimized for training data
- await computer.tracing.start(
- {
- "screenshots": True, # Essential for visual training
- "api_calls": True, # Capture action sequences
- "accessibility_tree": True, # Rich semantic context
- "metadata": True, # Custom annotations
- "name": "training_session",
- }
- )
-
- # Add training metadata
- await computer.tracing.add_metadata("data_type", "training")
- await computer.tracing.add_metadata("task_category", "ui_automation")
- await computer.tracing.add_metadata("difficulty", "intermediate")
- await computer.tracing.add_metadata("annotator", "human_expert")
-
- # Simulate human demonstration
- await computer.interface.screenshot() # Baseline screenshot
-
- # Step 1: Navigate to application
- await computer.tracing.add_metadata("step", "1_navigate_to_app")
- await computer.interface.move_cursor(100, 50)
- await computer.interface.left_click()
-
- # Step 2: Input data
- await computer.tracing.add_metadata("step", "2_input_data")
- await computer.interface.type_text("training example data")
-
- # Step 3: Process
- await computer.tracing.add_metadata("step", "3_process")
- await computer.interface.press_key("tab")
- await computer.interface.press_key("enter")
-
- # Final metadata
- await computer.tracing.add_metadata("success", True)
- await computer.tracing.add_metadata("completion_time", "45_seconds")
-
- trace_path = await computer.tracing.stop()
- print(f"Training data collected: {trace_path}")
-
- finally:
- await computer.stop()
-
-
-async def debugging_session_example():
- """
- Example for debugging agent behavior with detailed tracing.
- """
- print("=== Debugging Session Example ===")
-
- computer = Computer(os_type="macos", provider_type="lume")
- await computer.run()
-
- try:
- # Start tracing for debugging
- await computer.tracing.start(
- {
- "screenshots": True,
- "api_calls": True,
- "accessibility_tree": True,
- "metadata": True,
- "name": "debug_session",
- }
- )
-
- # Debug metadata
- await computer.tracing.add_metadata("session_type", "debugging")
- await computer.tracing.add_metadata("issue", "click_target_detection")
- await computer.tracing.add_metadata("expected_behavior", "click_on_button")
-
- try:
- # Problematic sequence that needs debugging
- await computer.interface.move_cursor(200, 150)
- await computer.interface.left_click()
-
- # This might fail - let's trace it
- await computer.interface.type_text("debug test")
- await computer.tracing.add_metadata("action_result", "successful_typing")
-
- except Exception as e:
- # Record the error in tracing
- await computer.tracing.add_metadata("error_encountered", str(e))
- await computer.tracing.add_metadata("error_type", type(e).__name__)
- print(f"Error occurred: {e}")
-
- # Stop tracing
- trace_path = await computer.tracing.stop()
- print(f"Debug trace saved: {trace_path}")
- print("Use this trace to analyze the failure and improve the agent")
-
- finally:
- await computer.stop()
-
-
-async def human_in_the_loop_example():
- """
- Example for recording mixed human/agent sessions.
- """
- print("=== Human-in-the-Loop Example ===")
-
- computer = Computer(os_type="macos", provider_type="lume")
- await computer.run()
-
- try:
- # Start tracing for hybrid session
- await computer.tracing.start(
- {
- "screenshots": True,
- "api_calls": True,
- "metadata": True,
- "name": "human_agent_collaboration",
- }
- )
-
- # Initial agent phase
- await computer.tracing.add_metadata("phase", "agent_autonomous")
- await computer.tracing.add_metadata("agent_model", "computer-use-preview")
-
- # Agent performs initial task
- await computer.interface.move_cursor(300, 200)
- await computer.interface.left_click()
- await computer.interface.type_text("automated input")
-
- # Transition to human intervention
- await computer.tracing.add_metadata("phase", "human_intervention")
- await computer.tracing.add_metadata("intervention_reason", "complex_ui_element")
-
- print("Human intervention phase - manual actions will be recorded...")
- # At this point, human can take control while tracing continues
-
- # Simulate human input (in practice, this would be actual human interaction)
- await computer.interface.move_cursor(500, 400)
- await computer.interface.double_click()
- await computer.tracing.add_metadata("human_action", "double_click_complex_element")
-
- # Back to agent
- await computer.tracing.add_metadata("phase", "agent_completion")
- await computer.interface.press_key("enter")
-
- trace_path = await computer.tracing.stop()
- print(f"Human-agent collaboration trace saved: {trace_path}")
-
- finally:
- await computer.stop()
-
-
-async def performance_monitoring_example():
- """
- Example for performance monitoring and analysis.
- """
- print("=== Performance Monitoring Example ===")
-
- computer = Computer(os_type="macos", provider_type="lume")
- await computer.run()
-
- try:
- # Start tracing for performance analysis
- await computer.tracing.start(
- {
- "screenshots": False, # Skip screenshots for performance
- "api_calls": True,
- "metadata": True,
- "name": "performance_test",
- }
- )
-
- # Performance test metadata
- await computer.tracing.add_metadata("test_type", "performance_benchmark")
- await computer.tracing.add_metadata("expected_duration", "< 30 seconds")
-
- import time
-
- start_time = time.time()
-
- # Perform a series of rapid actions
- for i in range(10):
- await computer.tracing.add_metadata("iteration", i)
- await computer.interface.move_cursor(100 + i * 50, 100)
- await computer.interface.left_click()
- await computer.interface.type_text(f"Test {i}")
- await computer.interface.press_key("tab")
-
- end_time = time.time()
-
- # Record performance metrics
- await computer.tracing.add_metadata(
- "actual_duration", f"{end_time - start_time:.2f} seconds"
- )
- await computer.tracing.add_metadata(
- "actions_per_second", f"{40 / (end_time - start_time):.2f}"
- )
-
- trace_path = await computer.tracing.stop()
- print(f"Performance trace saved: {trace_path}")
-
- finally:
- await computer.stop()
-
-
-async def main():
- """
- Run all tracing examples.
- """
- print("Computer.tracing API Examples")
- print("=" * 50)
-
- examples = [
- basic_tracing_example,
- agent_tracing_example,
- custom_agent_tracing_example,
- training_data_collection_example,
- debugging_session_example,
- human_in_the_loop_example,
- performance_monitoring_example,
- ]
-
- for example in examples:
- try:
- await example()
- print()
- except Exception as e:
- print(f"Error in {example.__name__}: {e}")
- print()
-
- print("All examples completed!")
-
-
-if __name__ == "__main__":
- asyncio.run(main())
diff --git a/examples/winsandbox_example.py b/examples/winsandbox_example.py
deleted file mode 100644
index 98fa0f44a7..0000000000
--- a/examples/winsandbox_example.py
+++ /dev/null
@@ -1,55 +0,0 @@
-"""Example of using the Windows Sandbox computer provider.
-
-Learn more at: https://learn.microsoft.com/en-us/windows/security/application-security/application-isolation/windows-sandbox/
-"""
-
-import asyncio
-
-from computer import Computer
-
-
-async def main():
- """Test the Windows Sandbox provider."""
-
- # Create a computer instance using Windows Sandbox
- computer = Computer(
- provider_type="winsandbox",
- os_type="windows",
- memory="4GB",
- # ephemeral=True, # Always true for Windows Sandbox
- )
-
- try:
- print("Starting Windows Sandbox...")
- await computer.run()
-
- print("Windows Sandbox is ready!")
- print(f"IP Address: {await computer.get_ip()}")
-
- # Test basic functionality
- print("Testing basic functionality...")
- screenshot = await computer.interface.screenshot()
- print(f"Screenshot taken: {len(screenshot)} bytes")
-
- # Test running a command
- print("Testing command execution...")
- result = await computer.interface.run_command("echo Hello from Windows Sandbox!")
- print(f"Command output: {result.stdout}")
-
- print("Press any key to continue...")
- input()
-
- except Exception as e:
- print(f"Error: {e}")
- import traceback
-
- traceback.print_exc()
-
- finally:
- print("Stopping Windows Sandbox...")
- await computer.stop()
- print("Windows Sandbox stopped.")
-
-
-if __name__ == "__main__":
- asyncio.run(main())
diff --git a/libs/lume/scripts/setup-cua.sh b/libs/lume/scripts/setup-cua.sh
index b2ecd92473..fd063b2718 100755
--- a/libs/lume/scripts/setup-cua.sh
+++ b/libs/lume/scripts/setup-cua.sh
@@ -272,7 +272,7 @@ setup_cua_server() {
echo "Installing cua-computer-server..."
source "$CUA_DIR/venv/bin/activate"
pip install --upgrade pip
- pip install cua-computer-server
+ pip install "cua-computer-server[vnc]"
echo "Installing cua-agent..."
pip install 'cua-agent[all]'
@@ -490,7 +490,7 @@ echo "Updating cua-agent..." >> "$LOG_FILE"
pip install --upgrade --no-input "cua-agent[all]" >> "$LOG_FILE" 2>&1 || true
echo "Updating cua-computer-server..." >> "$LOG_FILE"
-pip install --upgrade --no-input cua-computer-server >> "$LOG_FILE" 2>&1 || true
+pip install --upgrade --no-input "cua-computer-server[vnc]" >> "$LOG_FILE" 2>&1 || true
# Ensure Playwright Firefox
echo "Ensuring Playwright Firefox..." >> "$LOG_FILE"
diff --git a/libs/lume/src/Commands/Pull.swift b/libs/lume/src/Commands/Pull.swift
index da728d38d5..1b77e0ee85 100644
--- a/libs/lume/src/Commands/Pull.swift
+++ b/libs/lume/src/Commands/Pull.swift
@@ -57,5 +57,6 @@ struct Pull: AsyncParsableCommand {
password: password,
force: force
)
+ print()
}
}
diff --git a/libs/lume/src/ContainerRegistry/ImageContainerRegistry.swift b/libs/lume/src/ContainerRegistry/ImageContainerRegistry.swift
index 86b7982595..f35a9ee805 100644
--- a/libs/lume/src/ContainerRegistry/ImageContainerRegistry.swift
+++ b/libs/lume/src/ContainerRegistry/ImageContainerRegistry.swift
@@ -205,6 +205,11 @@ actor ProgressTracker {
private var progressLogger = ProgressLogger(threshold: 0.01)
private var totalFiles: Int = 0
private var completedFiles: Int = 0
+ var onProgress: (@Sendable (Double) -> Void)? = nil
+
+ func setProgressHandler(_ handler: @escaping @Sendable (Double) -> Void) {
+ onProgress = handler
+ }
// Download speed tracking
private var startTime: Date = Date()
@@ -261,6 +266,7 @@ actor ProgressTracker {
let overallAvgSpeed = totalElapsed > 0 ? Double(downloadedBytes) / totalElapsed : 0
let progress = totalBytes > 0 ? Double(downloadedBytes) / Double(totalBytes) : 0.0
+ onProgress?(progress * 100.0)
logSpeedProgress(
current: progress,
currentSpeed: currentSpeed,
@@ -772,6 +778,10 @@ class ImageContainerRegistry: ImageRegistry, @unchecked Sendable {
throw ValidationError("Image name cannot be empty")
}
+ if let handler = progressHandler {
+ await downloadProgress.setProgressHandler(handler)
+ }
+
let home = Home()
// Use provided name or derive from image
@@ -4671,6 +4681,12 @@ class ImageContainerRegistry: ImageRegistry, @unchecked Sendable {
let isChunked = diskLayers.count > 1
|| (diskLayers.count == 1 && diskLayers[0].annotations?[OCIAnnotation.partNumber] != nil)
+ // Set total download size so progress % is meaningful
+ let allLayers = manifest.layers + (manifest.config.map { [$0] } ?? [])
+ let totalDownloadBytes = allLayers.reduce(Int64(0)) { $0 + Int64($1.size) }
+ let totalFiles = allLayers.filter { $0.mediaType != "application/vnd.oci.empty.v1+json" }.count
+ await downloadProgress.setTotal(totalDownloadBytes, files: totalFiles)
+
// ── Download config & aux (shared by both paths) ─────────────────────
var configData: Data?
if let configLayer = manifest.config {
@@ -4710,6 +4726,22 @@ class ImageContainerRegistry: ImageRegistry, @unchecked Sendable {
var vmConfig: VMConfig?
var diskUncompressedSize: UInt64?
+ if let data = configData {
+ Logger.info("Config layer raw JSON: \(String(data: data, encoding: .utf8) ?? "<not utf8>")")
+ }
+ Logger.info("Manifest layers: \(manifest.layers.map { "\($0.mediaType) size=\($0.size)" }.joined(separator: ", "))")
+ Logger.info("Manifest config mediaType: \(manifest.config?.mediaType ?? "nil")")
+
+ if let data = configData {
+ do {
+ let ociCfg = try JSONDecoder().decode(LumeOCIConfig.self, from: data)
+ Logger.info("Decoded LumeOCIConfig: os=\(ociCfg.os) hardwareModel=\(ociCfg.hardwareModel.prefix(20))...")
+ _ = ociCfg // used below in the outer block
+ } catch {
+ Logger.info("WARNING: Failed to decode LumeOCIConfig: \(error)")
+ }
+ }
+
if let data = configData,
let ociCfg = try? JSONDecoder().decode(LumeOCIConfig.self, from: data)
{
@@ -4758,6 +4790,9 @@ class ImageContainerRegistry: ImageRegistry, @unchecked Sendable {
encoder.outputFormatting = .prettyPrinted
let data = try encoder.encode(cfg)
try data.write(to: configDest)
+ Logger.info("Wrote config.json")
+ } else {
+ Logger.info("WARNING: vmConfig is nil, skipping config.json write")
}
// ── Process nvram ────────────────────────────────────────────────────
@@ -4765,6 +4800,8 @@ class ImageContainerRegistry: ImageRegistry, @unchecked Sendable {
let nvramDest = destination.appendingPathComponent("nvram.bin")
try FileManager.default.copyItem(at: nvramPath, to: nvramDest)
Logger.info("Saved nvram.bin")
+ } else {
+ Logger.info("WARNING: nvramBlobPath is nil, skipping nvram.bin write")
}
// ── Process disk ──────────────────────────────────────────────────────
diff --git a/libs/lume/src/FileSystem/VMDirectory.swift b/libs/lume/src/FileSystem/VMDirectory.swift
index 5c8d28c84d..3334ad97f0 100644
--- a/libs/lume/src/FileSystem/VMDirectory.swift
+++ b/libs/lume/src/FileSystem/VMDirectory.swift
@@ -311,7 +311,8 @@ extension VMDirectory {
provisioningOperation: String? = nil,
vncUrl: String?,
ipAddress: String?,
- sshAvailable: Bool? = nil
+ sshAvailable: Bool? = nil,
+ downloadProgress: Double? = nil
) -> VMDetails? {
guard let config = try? loadConfig() else {
return nil
@@ -331,7 +332,8 @@ extension VMDirectory {
sshAvailable: sshAvailable,
locationName: locationName,
sharedDirectories: nil,
- networkMode: config.networkMode.description
+ networkMode: config.networkMode.description,
+ downloadProgress: downloadProgress
)
}
}
diff --git a/libs/lume/src/LumeController.swift b/libs/lume/src/LumeController.swift
index 3af7c8a30c..0aadcc28ae 100644
--- a/libs/lume/src/LumeController.swift
+++ b/libs/lume/src/LumeController.swift
@@ -24,6 +24,44 @@ final class SharedVM {
}
}
+// MARK: - Pull Progress Tracker
+
+/// Tracks async pull progress keyed by VM name. Shared singleton used by
+/// handlePullStart (writer) and handleGetVM (reader) across the same process.
+actor PullProgressTracker {
+ static let shared = PullProgressTracker()
+
+ private var progress: [String: Double] = [:]
+ private var errors: [String: String] = [:]
+
+ func setProgress(_ value: Double, for name: String) {
+ progress[name] = value
+ errors.removeValue(forKey: name)
+ }
+
+ func setError(_ message: String, for name: String) {
+ errors[name] = message
+ progress.removeValue(forKey: name)
+ }
+
+ func complete(for name: String) {
+ progress.removeValue(forKey: name)
+ errors.removeValue(forKey: name)
+ }
+
+ func getProgress(for name: String) -> Double? {
+ return progress[name]
+ }
+
+ func getError(for name: String) -> String? {
+ return errors[name]
+ }
+
+ func isPulling(_ name: String) -> Bool {
+ return progress[name] != nil
+ }
+}
+
/// Entrypoint for Commands and API server
final class LumeController {
// MARK: - Properties
diff --git a/libs/lume/src/Server/Handlers.swift b/libs/lume/src/Server/Handlers.swift
index aae5816e59..61f917c940 100644
--- a/libs/lume/src/Server/Handlers.swift
+++ b/libs/lume/src/Server/Handlers.swift
@@ -26,6 +26,29 @@ extension Server {
// Record telemetry
TelemetryClient.shared.record(event: TelemetryEvent.apiVMGet)
+ // Check if an async pull is in progress for this VM name
+ let pullProgress = await PullProgressTracker.shared.getProgress(for: name)
+ let pullError = await PullProgressTracker.shared.getError(for: name)
+
+ if let errorMsg = pullError {
+ // Pull failed — surface the error
+ return .badRequest(message: "Pull failed for '\(name)': \(errorMsg)")
+ }
+
+ if let progress = pullProgress {
+ // Pull in progress — return a synthetic "pulling" status without hitting disk
+ let responseBody: [String: AnyEncodable] = [
+ "name": AnyEncodable(name),
+ "status": AnyEncodable("pulling"),
+ "downloadProgress": AnyEncodable(progress),
+ ]
+ return try HTTPResponse(
+ statusCode: .ok,
+ headers: ["Content-Type": "application/json"],
+ body: JSONEncoder().encode(responseBody)
+ )
+ }
+
do {
let vmController = LumeController()
// Use getDetails() for consistent status including provisioning state
@@ -36,6 +59,57 @@ extension Server {
}
}
+ func handlePullStart(_ body: Data?) async throws -> HTTPResponse {
+ guard let body = body,
+ let request = try? JSONDecoder().decode(PullRequest.self, from: body)
+ else {
+ return HTTPResponse(
+ statusCode: .badRequest,
+ headers: ["Content-Type": "application/json"],
+ body: try JSONEncoder().encode(APIError(message: "Invalid request body"))
+ )
+ }
+
+ let imageName = request.image.split(separator: ":").first.map(String.init) ?? request.image
+ TelemetryClient.shared.record(event: TelemetryEvent.apiPull, properties: [
+ "image_name": imageName
+ ])
+
+ let vmName = request.name ?? imageName
+ await PullProgressTracker.shared.setProgress(0.0, for: vmName)
+
+ Task.detached { @MainActor @Sendable in
+ do {
+ let vmController = LumeController()
+ try await vmController.pullImage(
+ image: request.image,
+ name: request.name,
+ registry: request.registry,
+ organization: request.organization,
+ storage: request.storage,
+ progressHandler: { pct in
+ Task { await PullProgressTracker.shared.setProgress(pct, for: vmName) }
+ }
+ )
+ await PullProgressTracker.shared.complete(for: vmName)
+ Logger.info("Async pull completed", metadata: ["name": vmName])
+ } catch {
+ await PullProgressTracker.shared.setError(error.localizedDescription, for: vmName)
+ Logger.error("Async pull failed", metadata: ["name": vmName, "error": error.localizedDescription])
+ }
+ }
+
+ return HTTPResponse(
+ statusCode: .accepted,
+ headers: ["Content-Type": "application/json"],
+ body: try JSONEncoder().encode([
+ "message": AnyEncodable("Pull started"),
+ "name": AnyEncodable(vmName),
+ "image": AnyEncodable(request.image),
+ ])
+ )
+ }
+
func handleCreateVM(_ body: Data?) async throws -> HTTPResponse {
guard let body = body,
let request = try? JSONDecoder().decode(CreateVMRequest.self, from: body)
@@ -442,14 +516,20 @@ extension Server {
])
do {
+ let vmName = request.name ?? (request.image.split(separator: ":").first.map(String.init) ?? request.image)
+ await PullProgressTracker.shared.setProgress(0.0, for: vmName)
let vmController = LumeController()
try await vmController.pullImage(
image: request.image,
name: request.name,
registry: request.registry,
organization: request.organization,
- storage: request.storage
+ storage: request.storage,
+ progressHandler: { pct in
+ Task { await PullProgressTracker.shared.setProgress(pct, for: vmName) }
+ }
)
+ await PullProgressTracker.shared.complete(for: vmName)
return HTTPResponse(
statusCode: .ok,
@@ -461,6 +541,8 @@ extension Server {
])
)
} catch {
+ let vmName = request.name ?? (request.image.split(separator: ":").first.map(String.init) ?? request.image)
+ await PullProgressTracker.shared.setError(error.localizedDescription, for: vmName)
return HTTPResponse(
statusCode: .badRequest,
headers: ["Content-Type": "application/json"],
diff --git a/libs/lume/src/Server/Server.swift b/libs/lume/src/Server/Server.swift
index 0ebd92c8bd..9be86b90d9 100644
--- a/libs/lume/src/Server/Server.swift
+++ b/libs/lume/src/Server/Server.swift
@@ -227,6 +227,12 @@ final class Server {
guard let self else { throw HTTPError.internalError }
return try await self.handlePull(request.body)
}),
+ Route(
+ method: "POST", path: "/lume/pull/start",
+ handler: { [weak self] request in
+ guard let self else { throw HTTPError.internalError }
+ return try await self.handlePullStart(request.body)
+ }),
Route(
method: "POST", path: "/lume/prune",
handler: { [weak self] _ in
diff --git a/libs/lume/src/VM/VMDetails.swift b/libs/lume/src/VM/VMDetails.swift
index a30c6d6f2f..e7c51fe67b 100644
--- a/libs/lume/src/VM/VMDetails.swift
+++ b/libs/lume/src/VM/VMDetails.swift
@@ -45,11 +45,13 @@ struct VMDetails: Codable {
let locationName: String
let sharedDirectories: [SharedDirectory]?
let networkMode: String?
+ /// Pull progress percentage (0–100) when status is "pulling", nil otherwise
+ let downloadProgress: Double?
enum CodingKeys: String, CodingKey {
case name, os, cpuCount, memorySize, diskSize, display, status
case provisioningOperation, vncUrl, ipAddress, sshAvailable, locationName, sharedDirectories
- case networkMode
+ case networkMode, downloadProgress
}
init(
@@ -66,7 +68,8 @@ struct VMDetails: Codable {
sshAvailable: Bool? = nil,
locationName: String,
sharedDirectories: [SharedDirectory]? = nil,
- networkMode: String? = nil
+ networkMode: String? = nil,
+ downloadProgress: Double? = nil
) {
self.name = name
self.os = os
@@ -82,6 +85,7 @@ struct VMDetails: Codable {
self.locationName = locationName
self.sharedDirectories = sharedDirectories
self.networkMode = networkMode
+ self.downloadProgress = downloadProgress
}
// Custom encoder to always include optional fields (even when nil)
@@ -101,5 +105,6 @@ struct VMDetails: Codable {
try container.encode(locationName, forKey: .locationName)
try container.encode(sharedDirectories, forKey: .sharedDirectories)
try container.encode(networkMode, forKey: .networkMode)
+ try container.encode(downloadProgress, forKey: .downloadProgress)
}
}
diff --git a/libs/python/computer-server/README.md b/libs/python/computer-server/README.md
index 531b17296d..243911e573 100644
--- a/libs/python/computer-server/README.md
+++ b/libs/python/computer-server/README.md
@@ -11,6 +11,8 @@ The Computer Server exposes multiple interfaces simultaneously:
- **HTTP/WebSocket** - REST API and WebSocket for programmatic access
- **MCP via HTTP** - Model Context Protocol over streamable HTTP at `/mcp` endpoint
+> **Android emulators** also expose the emulator's built-in **EmulatorController gRPC service** on port 8554 (via `-grpc 8554` launch flag). Local Android sandboxes (`AndroidEmulatorRuntime`) use `GRPCEmulatorTransport` to call `getScreenshot()` directly on this service, bypassing the computer-server HTTP layer entirely. Benchmark: p50 ~20ms, ~49 RPS vs ADB-backed HTTP p50 ~519ms, ~1.8 RPS.
+
## Installation
```bash
diff --git a/libs/python/computer-server/computer_server/handlers/android.py b/libs/python/computer-server/computer_server/handlers/android.py
index 33e1d3b68d..1eeaec59ba 100644
--- a/libs/python/computer-server/computer_server/handlers/android.py
+++ b/libs/python/computer-server/computer_server/handlers/android.py
@@ -7,6 +7,7 @@ from typing import Any, Dict, List, Optional, Tuple
import grpc
from google.protobuf import empty_pb2 # noqa: F401 — must be loaded before emulator pb2
+
from ..utils.helpers import CommandExecutor
from .base import (
BaseAccessibilityHandler,
diff --git a/libs/python/computer-server/computer_server/main.py b/libs/python/computer-server/computer_server/main.py
index ac8b1c59fd..c0e896e011 100644
--- a/libs/python/computer-server/computer_server/main.py
+++ b/libs/python/computer-server/computer_server/main.py
@@ -161,6 +161,7 @@ handlers = {
"find_element": accessibility_handler.find_element,
# Shell commands
"run_command": automation_handler.run_command,
+ "multitouch_gesture": automation_handler.multitouch_gesture,
# File system commands
"file_exists": file_handler.file_exists,
"directory_exists": file_handler.directory_exists,
diff --git a/libs/python/cua-cli/cua_cli/commands/do.py b/libs/python/cua-cli/cua_cli/commands/do.py
index 91b0c0661a..1fa4fc22e7 100644
--- a/libs/python/cua-cli/cua_cli/commands/do.py
+++ b/libs/python/cua-cli/cua_cli/commands/do.py
@@ -18,7 +18,6 @@ import sys
import tempfile
from datetime import datetime
from pathlib import Path
-from typing import Any
# Ensure stdout/stderr can handle Unicode emojis on Windows
if sys.platform == "win32":
@@ -41,7 +40,7 @@ _SKIP_WINDOW_TITLES = {
"Chrome Legacy Window",
}
-PROVIDERS = ("cloud", "cloudv2", "lume", "lumier", "docker", "winsandbox", "host")
+PROVIDERS = ("cloud", "cloudv2", "local", "lume", "lumier", "docker", "winsandbox", "host")
_REMOTE_PROVIDERS = ("cloud", "cloudv2", "lume", "lumier", "docker", "winsandbox")
@@ -91,51 +90,37 @@ class _PtyUnavailable(Exception):
async def _get_api_url(provider_type: str, name: str) -> str:
- """Resolve the computer-server API URL for the target VM."""
- from computer.providers.base import VMProviderType
- from computer.providers.factory import VMProviderFactory
-
+ """Resolve the computer-server API URL for the target sandbox."""
if provider_type == "host":
return "http://localhost:8000"
+ if provider_type == "local":
+ from cua_sandbox import sandbox_state
+
+ state = sandbox_state.load(name)
+ if not state:
+ raise ValueError(f"Local sandbox '{name}' not found. Check ~/.cua/sandboxes/")
+ return f"http://{state['host']}:{state['api_port']}"
+
if provider_type in ("cloud", "cloudv2"):
from cua_cli.auth.store import get_api_key
+ from cua_sandbox.transport.cloud import CloudTransport, cloud_get_vm
api_key = get_api_key()
if not api_key:
raise ValueError("Not authenticated. Run 'cua auth login' first")
- ptype = VMProviderType.CLOUDV2 if provider_type == "cloudv2" else VMProviderType.CLOUD
- provider = VMProviderFactory.create_provider(ptype, api_key=api_key)
- async with provider:
- vm = await provider.get_vm(name)
- if not vm:
- raise ValueError(f"VM not found: {name}")
- url = vm.get("api_url") or vm.get("server_url")
- if not url:
- raise ValueError(f"VM '{name}' has no API URL (is it running?)")
- return url
-
- if provider_type == "docker":
- provider = VMProviderFactory.create_provider(VMProviderType.DOCKER)
- async with provider:
- vm = await provider.get_vm(name)
- if vm.get("status") == "not_found":
- raise ValueError(f"Docker container not found: {name}")
- ports = vm.get("ports", {})
- for key in ("8000/tcp", "5000/tcp"):
- if key in ports:
- return f"http://localhost:{ports[key]}"
- return "http://localhost:8000"
-
- if provider_type in ("lume", "lumier"):
- ptype = VMProviderType.LUME if provider_type == "lume" else VMProviderType.LUMIER
- provider = VMProviderFactory.create_provider(ptype)
- async with provider:
- vm = await provider.get_vm(name)
- ip = vm.get("ip_address") or "localhost"
- return f"http://{ip}:8000"
-
- if provider_type == "winsandbox":
+ vm = await cloud_get_vm(name, api_key=api_key)
+ if not vm:
+ raise ValueError(f"VM not found: {name}")
+ return CloudTransport._resolve_endpoint(vm)
+
+ # Legacy local provider types — map to sandbox state file lookup
+ if provider_type in ("lume", "lumier", "docker", "winsandbox"):
+ from cua_sandbox import sandbox_state
+
+ state = sandbox_state.load(name)
+ if state:
+ return f"http://{state['host']}:{state['api_port']}"
return "http://localhost:8000"
raise ValueError(f"Unknown provider: {provider_type}")
@@ -640,63 +625,49 @@ def _cmd_ls(args: argparse.Namespace) -> int:
explicit_provider = getattr(args, "provider", None)
- async def _list_one(ptype: str) -> int:
- from computer.providers.base import VMProviderType
- from computer.providers.factory import VMProviderFactory
-
- if ptype == "host":
- print(" host [local]")
- return 0
-
- kwargs: dict[str, Any] = {}
- if ptype in ("cloud", "cloudv2"):
- from cua_cli.auth.store import get_api_key
+ async def _list_all() -> int:
+ from cua_cli.auth.store import get_api_key
+ from cua_sandbox import Sandbox
- api_key = get_api_key()
- if not api_key:
- return _fail("Not authenticated. Run 'cua auth login' first")
- kwargs["api_key"] = api_key
+ print(" host [local]")
try:
- enum_type = VMProviderType(ptype)
- except ValueError:
- return _fail(f"Unknown provider: {ptype}")
+ local_sandboxes = await Sandbox.list(local=True)
+ for s in local_sandboxes:
+ print(f" {s.name} [{s.status}] {s.source}")
+ except Exception:
+ pass
try:
- provider = VMProviderFactory.create_provider(enum_type, **kwargs)
- async with provider:
- vms = await provider.list_vms()
- except Exception as e:
- return _fail(str(e))
-
- if not vms:
- print(f"No VMs found for provider '{ptype}'")
- return 0
+ api_key = get_api_key()
+ if api_key:
+ cloud_sandboxes = await Sandbox.list(local=False, api_key=api_key)
+ for s in cloud_sandboxes:
+ print(f" {s.name} [{s.status}] cloud")
+ except Exception:
+ pass
- for vm in vms:
- print(f" {vm.get('name', '?')} [{vm.get('status', '?')}]")
return 0
- async def _list_all() -> int:
- from computer.providers.base import VMProviderType
- from computer.providers.factory import VMProviderFactory
+ async def _list_one(ptype: str) -> int:
from cua_cli.auth.store import get_api_key
+ from cua_sandbox import Sandbox
- print(" host [local]")
-
- api_key = get_api_key()
- if api_key:
- try:
- provider = VMProviderFactory.create_provider(
- VMProviderType.CLOUDV2, api_key=api_key
- )
- async with provider:
- vms = await provider.list_vms()
- for vm in vms:
- print(f" {vm.get('name', '?')} [{vm.get('status', '?')}] cloudv2")
- except Exception:
- pass
+ if ptype == "host":
+ print(" host [local]")
+ return 0
+ local = ptype in ("local", "lume", "lumier", "docker", "winsandbox")
+ try:
+ api_key = None if local else get_api_key()
+ sandboxes = await Sandbox.list(local=local, api_key=api_key)
+ if not sandboxes:
+ print(f"No sandboxes found for provider '{ptype}'")
+ return 0
+ for s in sandboxes:
+ print(f" {s.name} [{s.status}]")
+ except Exception as e:
+ return _fail(str(e))
return 0
if explicit_provider:
diff --git a/libs/python/cua-cli/cua_cli/commands/mcp.py b/libs/python/cua-cli/cua_cli/commands/mcp.py
index 376b75fc4a..4ff12d32ea 100644
--- a/libs/python/cua-cli/cua_cli/commands/mcp.py
+++ b/libs/python/cua-cli/cua_cli/commands/mcp.py
@@ -205,25 +205,22 @@ async def _register_sandbox_tools(server: "FastMCP", permissions: set[Permission
@server.tool()
async def sandbox_list(ctx: Context) -> str:
"""List all cloud sandboxes."""
- from computer.providers import VMProviderFactory, VMProviderType
- from cua_cli.auth.store import require_api_key
+ from cua_cli.auth.store import get_api_key
+ from cua_sandbox import Sandbox
- api_key = require_api_key()
- provider = VMProviderFactory.create_provider(VMProviderType.CLOUD, api_key=api_key)
- async with provider:
- vms = await provider.list_vms()
- return json.dumps(
- [
- {
- "name": vm.name,
- "status": vm.status,
- "os_type": vm.os_type,
- "created_at": vm.created_at,
- }
- for vm in vms
- ],
- indent=2,
- )
+ sandboxes = await Sandbox.list(api_key=get_api_key())
+ return json.dumps(
+ [
+ {
+ "name": s.name,
+ "status": s.status,
+ "os_type": s.os_type,
+ "created_at": s.created_at,
+ }
+ for s in sandboxes
+ ],
+ indent=2,
+ )
if Permission.SANDBOX_CREATE in permissions:
@@ -241,22 +238,27 @@ async def _register_sandbox_tools(server: "FastMCP", permissions: set[Permission
size: VM size (small, medium, large, xlarge)
region: Region (north-america, europe, asia)
"""
- from computer.providers import VMProviderFactory, VMProviderType
- from cua_cli.auth.store import require_api_key
+ from cua_cli.auth.store import get_api_key
+ from cua_sandbox import Image, Sandbox
- api_key = require_api_key()
- provider = VMProviderFactory.create_provider(VMProviderType.CLOUD, api_key=api_key)
- async with provider:
- vm = await provider.create_vm(os_type=os_type, size=size, region=region)
- return json.dumps(
- {
- "name": vm.name,
- "status": vm.status,
- "os_type": vm.os_type,
- "message": f"Created sandbox: {vm.name}",
- },
- indent=2,
- )
+ if os_type == "macos":
+ image = Image.macos("26")
+ elif os_type == "windows":
+ image = Image.windows("11")
+ else:
+ image = Image.linux("ubuntu", "24.04")
+ sb = await Sandbox.create(image, api_key=get_api_key(), region=region)
+ name = sb.name
+ await sb.disconnect()
+ return json.dumps(
+ {
+ "name": name,
+ "status": "ready",
+ "os_type": os_type,
+ "message": f"Created sandbox: {name}",
+ },
+ indent=2,
+ )
if Permission.SANDBOX_GET in permissions:
@@ -267,28 +269,22 @@ async def _register_sandbox_tools(server: "FastMCP", permissions: set[Permission
Args:
name: Sandbox name
"""
- from computer.providers import VMProviderFactory, VMProviderType
- from cua_cli.auth.store import require_api_key
-
- api_key = require_api_key()
- provider = VMProviderFactory.create_provider(VMProviderType.CLOUD, api_key=api_key)
- async with provider:
- vm = await provider.get_vm(name)
- if not vm:
- return json.dumps({"error": f"Sandbox not found: {name}"})
+ from cua_cli.auth.store import get_api_key
+ from cua_sandbox import Sandbox
+
+ try:
+ info = await Sandbox.get_info(name, api_key=get_api_key())
return json.dumps(
{
- "name": vm.name,
- "status": vm.status,
- "os_type": vm.os_type,
- "size": getattr(vm, "size", None),
- "region": getattr(vm, "region", None),
- "created_at": vm.created_at,
- "vnc_url": getattr(vm, "vnc_url", None),
- "server_url": getattr(vm, "server_url", None),
+ "name": info.name,
+ "status": info.status,
+ "os_type": info.os_type,
+ "created_at": info.created_at,
},
indent=2,
)
+ except Exception as e:
+ return json.dumps({"error": str(e)})
if Permission.SANDBOX_START in permissions:
@@ -299,14 +295,11 @@ async def _register_sandbox_tools(server: "FastMCP", permissions: set[Permission
Args:
name: Sandbox name
"""
- from computer.providers import VMProviderFactory, VMProviderType
- from cua_cli.auth.store import require_api_key
+ from cua_cli.auth.store import get_api_key
+ from cua_sandbox import Sandbox
- api_key = require_api_key()
- provider = VMProviderFactory.create_provider(VMProviderType.CLOUD, api_key=api_key)
- async with provider:
- await provider.run_vm(name)
- return json.dumps({"success": True, "message": f"Started sandbox: {name}"})
+ await Sandbox.resume(name, api_key=get_api_key())
+ return json.dumps({"success": True, "message": f"Started sandbox: {name}"})
if Permission.SANDBOX_STOP in permissions:
@@ -317,14 +310,11 @@ async def _register_sandbox_tools(server: "FastMCP", permissions: set[Permission
Args:
name: Sandbox name
"""
- from computer.providers import VMProviderFactory, VMProviderType
- from cua_cli.auth.store import require_api_key
+ from cua_cli.auth.store import get_api_key
+ from cua_sandbox import Sandbox
- api_key = require_api_key()
- provider = VMProviderFactory.create_provider(VMProviderType.CLOUD, api_key=api_key)
- async with provider:
- await provider.stop_vm(name)
- return json.dumps({"success": True, "message": f"Stopped sandbox: {name}"})
+ await Sandbox.suspend(name, api_key=get_api_key())
+ return json.dumps({"success": True, "message": f"Stopped sandbox: {name}"})
if Permission.SANDBOX_RESTART in permissions:
@@ -335,14 +325,11 @@ async def _register_sandbox_tools(server: "FastMCP", permissions: set[Permission
Args:
name: Sandbox name
"""
- from computer.providers import VMProviderFactory, VMProviderType
- from cua_cli.auth.store import require_api_key
+ from cua_cli.auth.store import get_api_key
+ from cua_sandbox import Sandbox
- api_key = require_api_key()
- provider = VMProviderFactory.create_provider(VMProviderType.CLOUD, api_key=api_key)
- async with provider:
- await provider.restart_vm(name)
- return json.dumps({"success": True, "message": f"Restarted sandbox: {name}"})
+ await Sandbox.restart(name, api_key=get_api_key())
+ return json.dumps({"success": True, "message": f"Restarted sandbox: {name}"})
if Permission.SANDBOX_SUSPEND in permissions:
@@ -353,14 +340,11 @@ async def _register_sandbox_tools(server: "FastMCP", permissions: set[Permission
Args:
name: Sandbox name
"""
- from computer.providers import VMProviderFactory, VMProviderType
- from cua_cli.auth.store import require_api_key
+ from cua_cli.auth.store import get_api_key
+ from cua_sandbox import Sandbox
- api_key = require_api_key()
- provider = VMProviderFactory.create_provider(VMProviderType.CLOUD, api_key=api_key)
- async with provider:
- await provider.suspend_vm(name)
- return json.dumps({"success": True, "message": f"Suspended sandbox: {name}"})
+ await Sandbox.suspend(name, api_key=get_api_key())
+ return json.dumps({"success": True, "message": f"Suspended sandbox: {name}"})
if Permission.SANDBOX_DELETE in permissions:
@@ -371,14 +355,11 @@ async def _register_sandbox_tools(server: "FastMCP", permissions: set[Permission
Args:
name: Sandbox name
"""
- from computer.providers import VMProviderFactory, VMProviderType
- from cua_cli.auth.store import require_api_key
+ from cua_cli.auth.store import get_api_key
+ from cua_sandbox import Sandbox
- api_key = require_api_key()
- provider = VMProviderFactory.create_provider(VMProviderType.CLOUD, api_key=api_key)
- async with provider:
- await provider.delete_vm(name)
- return json.dumps({"success": True, "message": f"Deleted sandbox: {name}"})
+ await Sandbox.delete(name, api_key=get_api_key())
+ return json.dumps({"success": True, "message": f"Deleted sandbox: {name}"})
if Permission.SANDBOX_VNC in permissions:
@@ -389,19 +370,16 @@ async def _register_sandbox_tools(server: "FastMCP", permissions: set[Permission
Args:
name: Sandbox name
"""
- from computer.providers import VMProviderFactory, VMProviderType
- from cua_cli.auth.store import require_api_key
-
- api_key = require_api_key()
- provider = VMProviderFactory.create_provider(VMProviderType.CLOUD, api_key=api_key)
- async with provider:
- vm = await provider.get_vm(name)
- if not vm:
- return json.dumps({"error": f"Sandbox not found: {name}"})
- vnc_url = getattr(vm, "vnc_url", None)
- if not vnc_url:
- return json.dumps({"error": "VNC URL not available"})
+ from cua_cli.auth.store import get_api_key
+ from cua_sandbox import Sandbox
+
+ try:
+ sb = await Sandbox.connect(name, api_key=get_api_key())
+ vnc_url = await sb.get_display_url(share=True)
+ await sb.disconnect()
return json.dumps({"vnc_url": vnc_url})
+ except Exception as e:
+ return json.dumps({"error": str(e)})
async def _register_computer_tools(
@@ -417,25 +395,18 @@ async def _register_computer_tools(
async def _get_server_url(sandbox_name: str) -> Optional[str]:
"""Get the computer-server URL for a sandbox."""
- from computer.providers import VMProviderFactory, VMProviderType
-
name = sandbox_name or default_sandbox
if not name:
raise ValueError("No sandbox specified. Use --sandbox or set CUA_SANDBOX env var")
-
api_key = get_api_key()
if not api_key:
raise ValueError("Not authenticated. Run 'cua auth login' first")
+ from cua_sandbox.transport.cloud import CloudTransport, cloud_get_vm
- provider = VMProviderFactory.create_provider(VMProviderType.CLOUD, api_key=api_key)
- async with provider:
- vm = await provider.get_vm(name)
- if not vm:
- raise ValueError(f"Sandbox not found: {name}")
- server_url = getattr(vm, "server_url", None)
- if not server_url:
- raise ValueError(f"Sandbox {name} is not running or has no server URL")
- return server_url
+ vm = await cloud_get_vm(name, api_key=api_key)
+ if not vm:
+ raise ValueError(f"Sandbox not found: {name}")
+ return CloudTransport._resolve_endpoint(vm)
async def _send_command(sandbox_name: str, command: str, params: dict) -> dict:
"""Send a command to the computer-server."""
diff --git a/libs/python/cua-cli/cua_cli/commands/sandbox.py b/libs/python/cua-cli/cua_cli/commands/sandbox.py
index 37e7992902..8188490f8e 100644
--- a/libs/python/cua-cli/cua_cli/commands/sandbox.py
+++ b/libs/python/cua-cli/cua_cli/commands/sandbox.py
@@ -4,15 +4,12 @@ import argparse
import asyncio
import base64
import json
-import os
import shutil
import sys
import webbrowser
from typing import Any, Optional
-from urllib.parse import quote
import aiohttp
-from core.http import cua_version_headers
from cua_cli.auth.store import get_api_key, require_api_key
from cua_cli.utils.async_utils import run_async
from cua_cli.utils.output import (
@@ -23,52 +20,158 @@ from cua_cli.utils.output import (
print_table,
)
-DEFAULT_API_BASE = "https://api.cua.ai"
+# ---------------------------------------------------------------------------
+# Image string parsing
+# ---------------------------------------------------------------------------
+
+_REGISTRY_HOSTNAMES = {
+ "ghcr.io",
+ "docker.io",
+ "registry.hub.docker.com",
+ "quay.io",
+ "gcr.io",
+ "registry.cua.ai",
+}
+
+_MACOS_ALIASES = {"macos", "mac", "osx"}
+_LINUX_ALIASES = {"linux", "ubuntu", "debian", "fedora"}
+_WINDOWS_ALIASES = {"windows", "win"}
+_ANDROID_ALIASES = {"android"}
+
+
+def _parse_image(image_str: str, vm: bool = False):
+ """Parse an image string into a cua_sandbox Image object.
+
+ Examples::
+
+ "macos" -> Image.macos("26")
+ "macos:sequoia" -> Image.macos("sequoia")
+ "ubuntu:24.04" -> Image.linux("ubuntu", "24.04")
+ "linux" -> Image.linux("ubuntu", "24.04")
+ "windows:11" -> Image.windows("11")
+ "android:14" -> Image.android("14")
+ "ghcr.io/org/img" -> Image.from_registry("ghcr.io/org/img")
+ """
+ from cua_sandbox import Image
+ # Registry reference: contains '/' or starts with a known registry hostname
+ if "/" in image_str:
+ host = image_str.split("/")[0]
+ if "." in host or host in _REGISTRY_HOSTNAMES:
+ return Image.from_registry(image_str)
+ for rh in _REGISTRY_HOSTNAMES:
+ if image_str.startswith(rh):
+ return Image.from_registry(image_str)
-def _get_api_base() -> str:
- """Get the API base URL."""
- return os.environ.get("CUA_API_BASE", DEFAULT_API_BASE).rstrip("/")
+ # Split on ':'
+ parts = image_str.split(":", 1)
+ base = parts[0].lower()
+ tag = parts[1] if len(parts) > 1 else None
+ if base in _MACOS_ALIASES:
+ version = tag or "26"
+ return Image.macos(version)
-async def _api_request(
- method: str,
- path: str,
- api_key: str,
- json: Optional[dict] = None,
- timeout: int = 30,
-) -> tuple[int, Any]:
- """Make an HTTP request to the CUA API."""
- url = f"{_get_api_base()}{path}"
- headers = {
- "Authorization": f"Bearer {api_key}",
- "Accept": "application/json",
- **cua_version_headers(),
- }
+ if base in _LINUX_ALIASES:
+ distro = base if base != "linux" else "ubuntu"
+ version = tag or "24.04"
+ kind = "vm" if vm else "container"
+ return Image.linux(distro, version, kind=kind)
- if json is not None:
- headers["Content-Type"] = "application/json"
+ if base in _WINDOWS_ALIASES:
+ version = tag or "11"
+ return Image.windows(version)
+
+ if base in _ANDROID_ALIASES:
+ version = tag or "14"
+ return Image.android(version)
+
+ # Unknown — try registry
+ return Image.from_registry(image_str)
+
+
+# ---------------------------------------------------------------------------
+# Memory / disk parsing
+# ---------------------------------------------------------------------------
+
+
+def _parse_memory(s: str) -> int:
+ """Convert a memory string to MB.
+
+ "8GB" -> 8192
+ "8192MB" -> 8192
+ "8" -> 8192 (bare number treated as GB)
+ """
+ s = s.strip()
+ if s.upper().endswith("GB"):
+ return int(float(s[:-2])) * 1024
+ if s.upper().endswith("MB"):
+ return int(float(s[:-2]))
+ # Bare number — treat as GB
+ return int(float(s)) * 1024
+
+
+def _parse_disk(s: str) -> int:
+ """Convert a disk string to GB.
+
+ "50GB" -> 50
+ "50" -> 50
+ "51200MB" -> 50
+ """
+ s = s.strip()
+ if s.upper().endswith("GB"):
+ return int(float(s[:-2]))
+ if s.upper().endswith("MB"):
+ return int(float(s[:-2])) // 1024
+ return int(float(s))
+
+
+# ---------------------------------------------------------------------------
+# Sandbox API URL resolution (for shell / exec)
+# ---------------------------------------------------------------------------
+
+
+async def _get_sandbox_api_url(name: str, local: bool) -> tuple[str, Optional[str]]:
+ """Resolve the computer-server API URL and optional api_key for a sandbox.
+
+ Returns:
+ Tuple of (api_url, api_key_or_none)
+ """
+ if local:
+ from cua_sandbox import sandbox_state
+
+ state = sandbox_state.load(name)
+ if not state:
+ raise ValueError(f"Local sandbox '{name}' not found. Check ~/.cua/sandboxes/")
+ url = f"http://{state['host']}:{state['api_port']}"
+ return url, None
+
+ api_key = require_api_key()
+ from cua_sandbox.transport.cloud import CloudTransport, cloud_get_vm
+
+ vm = await cloud_get_vm(name, api_key=api_key)
+ if not vm:
+ raise ValueError(f"Sandbox '{name}' not found")
+ if vm.get("status") == "not_found":
+ raise ValueError(f"Sandbox '{name}' not found")
+ url = CloudTransport._resolve_endpoint(vm)
+ if not url:
+ raise ValueError(f"Sandbox '{name}' has no API URL (is it running?)")
+ return url, api_key
- async with aiohttp.ClientSession() as session:
- timeout_obj = aiohttp.ClientTimeout(total=timeout)
- async with session.request(
- method, url, headers=headers, json=json, timeout=timeout_obj
- ) as resp:
- try:
- data = await resp.json(content_type=None)
- except Exception:
- data = await resp.text()
- return resp.status, data
+
+# ---------------------------------------------------------------------------
+# Parser registration
+# ---------------------------------------------------------------------------
def register_parser(subparsers: argparse._SubParsersAction) -> None:
"""Register the sandbox command and subcommands."""
- # Register both 'sandbox' and 'sb' as aliases
for cmd_name in ("sandbox", "sb"):
sb_parser = subparsers.add_parser(
cmd_name,
help="Sandbox management commands",
- description="Manage cloud sandboxes (virtual machines)",
+ description="Manage cloud and local sandboxes",
)
sb_subparsers = sb_parser.add_subparsers(
@@ -76,145 +179,155 @@ def register_parser(subparsers: argparse._SubParsersAction) -> None:
help="Sandbox command",
)
- # list command
- list_parser = sb_subparsers.add_parser(
- "list",
- aliases=["ls", "ps"],
- help="List all sandboxes",
+ # -- launch ----------------------------------------------------------
+ launch_parser = sb_subparsers.add_parser(
+ "launch",
+ help="Launch a new sandbox",
)
- list_parser.add_argument(
- "--json",
+ launch_parser.add_argument(
+ "image",
+ help="Image to launch (e.g. macos, ubuntu:24.04, windows:11)",
+ )
+ launch_parser.add_argument(
+ "--local",
action="store_true",
- help="Output as JSON",
+ help="Launch a local sandbox",
+ )
+ launch_parser.add_argument(
+ "--name",
+ default=None,
+ help="Sandbox name",
)
- list_parser.add_argument(
- "--show-passwords",
+ launch_parser.add_argument(
+ "--vm",
action="store_true",
- help="Show sandbox passwords in output",
+ help="Force VM kind for Linux images (default: container)",
)
-
- # create command
- create_parser = sb_subparsers.add_parser(
- "create",
- help="Create a new sandbox",
+ launch_parser.add_argument(
+ "--cpu",
+ type=int,
+ default=None,
+ help="Number of vCPUs",
)
- create_parser.add_argument(
- "--os",
- required=True,
- choices=["linux", "windows", "macos"],
- help="Operating system",
+ launch_parser.add_argument(
+ "--memory",
+ default=None,
+ help="Memory (e.g. 8GB, 4096MB)",
)
- create_parser.add_argument(
- "--size",
- required=True,
- choices=["small", "medium", "large"],
- help="Sandbox size",
+ launch_parser.add_argument(
+ "--disk",
+ default=None,
+ help="Disk size (e.g. 50GB)",
)
- create_parser.add_argument(
+ launch_parser.add_argument(
"--region",
- required=True,
- choices=["north-america", "europe", "asia-pacific", "south-america"],
- help="Region for the sandbox",
+ default=None,
+ help="Cloud region",
)
- create_parser.add_argument(
+ launch_parser.add_argument(
"--json",
action="store_true",
help="Output as JSON",
)
- # get command
- get_parser = sb_subparsers.add_parser(
- "get",
- help="Get sandbox details",
+ # -- ls / list -------------------------------------------------------
+ ls_parser = sb_subparsers.add_parser(
+ "ls",
+ aliases=["list"],
+ help="List sandboxes",
)
- get_parser.add_argument(
- "name",
- help="Sandbox name",
- )
- get_parser.add_argument(
- "--json",
+ ls_parser.add_argument(
+ "--local",
action="store_true",
- help="Output as JSON",
+ help="List local sandboxes",
)
- get_parser.add_argument(
- "--show-passwords",
+ ls_parser.add_argument(
+ "--all",
action="store_true",
- help="Show sandbox password",
+ help="List both local and cloud sandboxes",
)
- get_parser.add_argument(
- "--show-vnc-url",
+ ls_parser.add_argument(
+ "--json",
action="store_true",
- help="Show VNC URL",
+ help="Output as JSON",
)
- # delete command
- delete_parser = sb_subparsers.add_parser(
- "delete",
- help="Delete a sandbox",
+ # -- info ------------------------------------------------------------
+ info_parser = sb_subparsers.add_parser(
+ "info",
+ aliases=["get"],
+ help="Get sandbox details",
)
- delete_parser.add_argument(
+ info_parser.add_argument(
"name",
help="Sandbox name",
)
-
- # start command
- start_parser = sb_subparsers.add_parser(
- "start",
- help="Start a stopped sandbox",
+ info_parser.add_argument(
+ "--local",
+ action="store_true",
+ help="Target a local sandbox",
)
- start_parser.add_argument(
- "name",
- help="Sandbox name",
+ info_parser.add_argument(
+ "--json",
+ action="store_true",
+ help="Output as JSON",
)
- # stop command
- stop_parser = sb_subparsers.add_parser(
- "stop",
- help="Stop a running sandbox",
+ # -- suspend ---------------------------------------------------------
+ suspend_parser = sb_subparsers.add_parser(
+ "suspend",
+ help="Suspend a sandbox (preserves memory state)",
)
- stop_parser.add_argument(
- "name",
- help="Sandbox name",
+ suspend_parser.add_argument("name", help="Sandbox name")
+ suspend_parser.add_argument("--local", action="store_true", help="Target a local sandbox")
+
+ # -- resume ----------------------------------------------------------
+ resume_parser = sb_subparsers.add_parser(
+ "resume",
+ help="Resume a suspended sandbox",
)
+ resume_parser.add_argument("name", help="Sandbox name")
+ resume_parser.add_argument("--local", action="store_true", help="Target a local sandbox")
- # restart command
+ # -- restart ---------------------------------------------------------
restart_parser = sb_subparsers.add_parser(
"restart",
help="Restart a sandbox",
)
- restart_parser.add_argument(
- "name",
- help="Sandbox name",
- )
+ restart_parser.add_argument("name", help="Sandbox name")
+ restart_parser.add_argument("--local", action="store_true", help="Target a local sandbox")
- # suspend command
- suspend_parser = sb_subparsers.add_parser(
- "suspend",
- help="Suspend a sandbox (preserves memory state)",
+ # -- delete ----------------------------------------------------------
+ delete_parser = sb_subparsers.add_parser(
+ "delete",
+ help="Delete a sandbox",
)
- suspend_parser.add_argument(
- "name",
- help="Sandbox name",
+ delete_parser.add_argument("name", help="Sandbox name")
+ delete_parser.add_argument("--local", action="store_true", help="Target a local sandbox")
+ delete_parser.add_argument(
+ "--force",
+ action="store_true",
+ help="Skip confirmation prompt",
)
- # vnc command
+ # -- vnc -------------------------------------------------------------
vnc_parser = sb_subparsers.add_parser(
"vnc",
- aliases=["open"],
- help="Open sandbox in browser (VNC)",
- )
- vnc_parser.add_argument(
- "name",
- help="Sandbox name",
+ help="Open sandbox in browser via VNC",
)
+ vnc_parser.add_argument("name", help="Sandbox name")
+ vnc_parser.add_argument("--local", action="store_true", help="Target a local sandbox")
- # shell command
- # Note: Options must come before 'name' due to argparse REMAINDER behavior
- # Usage: cua sb shell [--cols N] [--rows N] <name> [command...]
+ # -- shell -----------------------------------------------------------
shell_parser = sb_subparsers.add_parser(
"shell",
help="Open interactive shell or run command in sandbox",
)
+ shell_parser.add_argument(
+ "--local",
+ action="store_true",
+ help="Target a local sandbox",
+ )
shell_parser.add_argument(
"--cols",
type=int,
@@ -227,32 +340,29 @@ def register_parser(subparsers: argparse._SubParsersAction) -> None:
default=None,
help="Terminal height (default: auto-detect)",
)
- shell_parser.add_argument(
- "name",
- help="Sandbox name",
- )
+ shell_parser.add_argument("name", help="Sandbox name")
shell_parser.add_argument(
"shell_command",
nargs=argparse.REMAINDER,
help="Command to run (optional, opens interactive shell if omitted)",
)
- # exec command
- # Note: --json must come before 'name' due to argparse REMAINDER behavior
- # Usage: cua sb exec [--json] <name> <command...>
+ # -- exec ------------------------------------------------------------
exec_parser = sb_subparsers.add_parser(
"exec",
help="Execute command in sandbox (non-interactive)",
)
exec_parser.add_argument(
- "--json",
+ "--local",
action="store_true",
- help="Output as JSON",
+ help="Target a local sandbox",
)
exec_parser.add_argument(
- "name",
- help="Sandbox name",
+ "--json",
+ action="store_true",
+ help="Output as JSON",
)
+ exec_parser.add_argument("name", help="Sandbox name")
exec_parser.add_argument(
"exec_command",
nargs=argparse.REMAINDER,
@@ -260,27 +370,30 @@ def register_parser(subparsers: argparse._SubParsersAction) -> None:
)
+# ---------------------------------------------------------------------------
+# execute() dispatcher
+# ---------------------------------------------------------------------------
+
+
def execute(args: argparse.Namespace) -> int:
"""Execute sandbox command based on subcommand."""
cmd = getattr(args, "sandbox_command", None)
- if cmd in ("list", "ls", "ps"):
- return cmd_list(args)
- elif cmd == "create":
- return cmd_create(args)
- elif cmd == "get":
- return cmd_get(args)
- elif cmd == "delete":
- return cmd_delete(args)
- elif cmd == "start":
- return cmd_start(args)
- elif cmd == "stop":
- return cmd_stop(args)
- elif cmd == "restart":
- return cmd_restart(args)
+ if cmd == "launch":
+ return cmd_launch(args)
+ elif cmd in ("ls", "list"):
+ return cmd_ls(args)
+ elif cmd in ("info", "get"):
+ return cmd_info(args)
elif cmd == "suspend":
return cmd_suspend(args)
- elif cmd in ("vnc", "open"):
+ elif cmd == "resume":
+ return cmd_resume(args)
+ elif cmd == "restart":
+ return cmd_restart(args)
+ elif cmd == "delete":
+ return cmd_delete(args)
+ elif cmd == "vnc":
return cmd_vnc(args)
elif cmd == "shell":
return cmd_shell(args)
@@ -288,348 +401,308 @@ def execute(args: argparse.Namespace) -> int:
return cmd_exec(args)
else:
print_error("Usage: cua sandbox <command>")
- print_info(
- "Commands: list, create, get, delete, start, stop, restart, suspend, vnc, shell, exec"
- )
+ print_info("Commands: launch, ls, info, suspend, resume, restart, delete, vnc, shell, exec")
return 1
-def _get_provider():
- """Get a configured CloudProvider instance."""
- from computer.providers.cloud.provider import CloudProvider
-
- api_key = require_api_key()
- return CloudProvider(api_key=api_key)
+# ---------------------------------------------------------------------------
+# Command implementations
+# ---------------------------------------------------------------------------
-def _redact_sensitive(vm: dict) -> dict:
- """Remove password and VNC URL from a VM dict."""
- redacted = {k: v for k, v in vm.items() if k not in ("password", "vnc_url")}
- return redacted
+def cmd_launch(args: argparse.Namespace) -> int:
+ """Launch a new sandbox."""
+ async def _run() -> int:
+ from cua_sandbox import Sandbox
-def cmd_list(args: argparse.Namespace) -> int:
- """List all sandboxes."""
+ image = _parse_image(args.image, vm=getattr(args, "vm", False))
- async def _list():
- async with _get_provider() as provider:
- return await provider.list_vms()
+ memory_mb = _parse_memory(args.memory) if args.memory else None
+ disk_gb = _parse_disk(args.disk) if args.disk else None
- vms = run_async(_list())
+ local = getattr(args, "local", False)
- if args.json:
- data = vms if args.show_passwords else [_redact_sensitive(vm) for vm in vms]
- print_json(data)
- return 0
+ try:
+ if local:
+ sb = await Sandbox.create(
+ image,
+ local=True,
+ name=args.name,
+ )
+ else:
+ create_kwargs: dict[str, Any] = {}
+ if args.name:
+ create_kwargs["name"] = args.name
+ if args.region:
+ create_kwargs["region"] = args.region
+ if getattr(args, "cpu", None):
+ create_kwargs["cpu"] = args.cpu
+ if memory_mb is not None:
+ create_kwargs["memory_mb"] = memory_mb
+ if disk_gb is not None:
+ create_kwargs["disk_gb"] = disk_gb
+ api_key = require_api_key()
+ create_kwargs["api_key"] = api_key
+ sb = await Sandbox.create(image, **create_kwargs)
+
+ name = sb.name
+ await sb.disconnect()
+ except Exception as e:
+ import traceback
+
+ print_error(f"Failed to launch sandbox: {e!r}\n{traceback.format_exc()}")
+ return 1
- if not vms:
- print_info("No sandboxes found.")
+ if getattr(args, "json", False):
+ print_json({"name": name, "status": "ready"})
+ else:
+ print_success(f"Sandbox '{name}' is ready")
return 0
- # Format for table display
- columns = [
- ("name", "NAME"),
- ("status", "STATUS"),
- ("host", "HOST"),
- ]
+ return run_async(_run())
- if args.show_passwords:
- columns.append(("password", "PASSWORD"))
- print_table(vms, columns)
- return 0
+def cmd_ls(args: argparse.Namespace) -> int:
+ """List sandboxes."""
+ async def _run() -> int:
+ from cua_sandbox import Sandbox
-def cmd_create(args: argparse.Namespace) -> int:
- """Create a new sandbox."""
- api_key = require_api_key()
+ show_all = getattr(args, "all", False)
+ local = getattr(args, "local", False)
+ as_json = getattr(args, "json", False)
- async def _create():
- body = {
- "os": args.os,
- "configuration": args.size,
- "region": args.region,
- }
- status_code, data = await _api_request("POST", "/v1/vms", api_key, json=body)
-
- if status_code == 200:
- # Sandbox ready immediately
- return {
- "status": data.get("status", "ready") if isinstance(data, dict) else "ready",
- "name": data.get("name") if isinstance(data, dict) else None,
- "password": data.get("password") if isinstance(data, dict) else None,
- "host": data.get("host") if isinstance(data, dict) else None,
- }
- elif status_code == 202:
- # Provisioning in progress
- return {
- "status": (
- data.get("status", "provisioning") if isinstance(data, dict) else "provisioning"
- ),
- "name": data.get("name") if isinstance(data, dict) else None,
- "job_id": data.get("job_id") if isinstance(data, dict) else None,
- }
- elif status_code == 401:
- return {"status": "unauthorized"}
- elif status_code == 400:
- return {"status": "invalid_request", "message": str(data)}
- else:
- return {"status": "error", "message": str(data)}
+ results: list[dict] = []
- result = run_async(_create())
+ if show_all or local:
+ try:
+ local_list = await Sandbox.list(local=True)
+ for s in local_list:
+ results.append(
+ {
+ "name": s.name,
+ "status": s.status,
+ "source": getattr(s, "source", "local"),
+ }
+ )
+ except Exception:
+ pass
- if args.json:
- print_json(result)
- return 0 if result.get("status") not in ("error", "unauthorized", "invalid_request") else 1
+ if show_all or not local:
+ try:
+ api_key = get_api_key()
+ cloud_list = await Sandbox.list(local=False, api_key=api_key)
+ for s in cloud_list:
+ results.append(
+ {
+ "name": s.name,
+ "status": s.status,
+ "source": "cloud",
+ }
+ )
+ except Exception:
+ pass
- status = result.get("status")
+ if as_json:
+ print_json(results)
+ return 0
- if status in ("error", "unauthorized", "invalid_request"):
- print_error(f"Failed to create sandbox: {result.get('message', status)}")
- return 1
+ if not results:
+ print_info("No sandboxes found.")
+ return 0
- if status == "provisioning":
- print_info(f"Sandbox '{result.get('name')}' is being provisioned...")
- print_info("Use 'cua sb list' to check status.")
- else:
- print_success(f"Sandbox '{result.get('name')}' created!")
- if result.get("password"):
- print_info(f"Password: {result.get('password')}")
- if result.get("host"):
- print_info(f"Host: {result.get('host')}")
+ print_table(
+ results,
+ [("name", "NAME"), ("status", "STATUS"), ("source", "SOURCE")],
+ )
+ return 0
- return 0
+ return run_async(_run())
-def cmd_get(args: argparse.Namespace) -> int:
+def cmd_info(args: argparse.Namespace) -> int:
"""Get sandbox details."""
+ local = getattr(args, "local", False)
- async def _get():
- async with _get_provider() as provider:
- return await provider.get_vm(args.name)
-
- result = run_async(_get())
-
- if args.json:
- data = result if args.show_passwords else _redact_sensitive(result)
- print_json(data)
- return 1 if result.get("status") == "not_found" else 0
-
- if result.get("status") == "not_found":
- print_error(f"Sandbox '{args.name}' not found.")
- return 1
-
- # Display sandbox info
- print_info(f"Name: {result.get('name')}")
- print_info(f"Status: {result.get('status')}")
-
- if result.get("os_type"):
- print_info(f"OS: {result.get('os_type')}")
- if result.get("host"):
- print_info(f"Host: {result.get('host')}")
- if args.show_passwords and result.get("password"):
- print_info(f"Password: {result.get('password')}")
- if args.show_vnc_url and result.get("vnc_url"):
- print_info(f"VNC URL: {result.get('vnc_url')}")
-
- return 0
-
-
-def cmd_delete(args: argparse.Namespace) -> int:
- """Delete a sandbox."""
- api_key = require_api_key()
-
- async def _delete():
- status_code, data = await _api_request("DELETE", f"/v1/vms/{args.name}", api_key)
-
- if status_code in (200, 202, 204):
- body_status = data.get("status") if isinstance(data, dict) else None
- return {"name": args.name, "status": body_status or "deleting"}
- elif status_code == 404:
- return {"name": args.name, "status": "not_found"}
- elif status_code == 401:
- return {"name": args.name, "status": "unauthorized"}
- else:
- return {"name": args.name, "status": "error", "message": str(data)}
+ async def _run() -> int:
+ from cua_sandbox import Sandbox
- result = run_async(_delete())
- status = result.get("status")
+ try:
+ kwargs: dict[str, Any] = {}
+ if not local:
+ kwargs["api_key"] = require_api_key()
+ info = await Sandbox.get_info(args.name, local=local, **kwargs)
+ except Exception as e:
+ print_error(str(e))
+ return 1
- if status == "not_found":
- print_error(f"Sandbox '{args.name}' not found.")
- return 1
- elif status in ("error", "unauthorized"):
- print_error(f"Failed to delete sandbox: {result.get('message', status)}")
- return 1
- else:
- print_success(f"Sandbox '{args.name}' is being deleted.")
+ if getattr(args, "json", False):
+ data = {
+ "name": info.name,
+ "status": info.status,
+ }
+ for attr in ("os_type", "host", "region", "created_at", "cpu", "memory_mb", "disk_gb"):
+ val = getattr(info, attr, None)
+ if val is not None:
+ data[attr] = val
+ print_json(data)
+ return 0
+
+ print_info(f"Name: {info.name}")
+ print_info(f"Status: {info.status}")
+ for attr, label in [
+ ("os_type", "OS"),
+ ("host", "Host"),
+ ("region", "Region"),
+ ("created_at", "Created"),
+ ]:
+ val = getattr(info, attr, None)
+ if val:
+ print_info(f"{label}: {val}")
return 0
+ return run_async(_run())
-def cmd_start(args: argparse.Namespace) -> int:
- """Start a stopped sandbox."""
- async def _start():
- async with _get_provider() as provider:
- return await provider.run_vm(name=args.name)
+def cmd_suspend(args: argparse.Namespace) -> int:
+ """Suspend a sandbox."""
+ local = getattr(args, "local", False)
- result = run_async(_start())
- status = result.get("status")
+ async def _run() -> int:
+ from cua_sandbox import Sandbox
- if status == "not_found":
- print_error(f"Sandbox '{args.name}' not found.")
- return 1
- elif status in ("error", "unauthorized"):
- print_error(f"Failed to start sandbox: {result.get('message', status)}")
- return 1
- else:
- print_success(f"Sandbox '{args.name}' is starting.")
+ try:
+ kwargs: dict[str, Any] = {}
+ if not local:
+ kwargs["api_key"] = require_api_key()
+ await Sandbox.suspend(args.name, local=local, **kwargs)
+ except Exception as e:
+ print_error(f"Failed to suspend sandbox: {e}")
+ return 1
+ print_success(f"Sandbox '{args.name}' is suspending.")
return 0
+ return run_async(_run())
-def cmd_stop(args: argparse.Namespace) -> int:
- """Stop a running sandbox."""
- async def _stop():
- async with _get_provider() as provider:
- return await provider.stop_vm(args.name)
+def cmd_resume(args: argparse.Namespace) -> int:
+ """Resume a suspended sandbox."""
+ local = getattr(args, "local", False)
- result = run_async(_stop())
- status = result.get("status")
+ async def _run() -> int:
+ from cua_sandbox import Sandbox
- if status == "not_found":
- print_error(f"Sandbox '{args.name}' not found.")
- return 1
- elif status in ("error", "unauthorized"):
- print_error(f"Failed to stop sandbox: {result.get('message', status)}")
- return 1
- else:
- print_success(f"Sandbox '{args.name}' is stopping.")
+ try:
+ kwargs: dict[str, Any] = {}
+ if not local:
+ kwargs["api_key"] = require_api_key()
+ await Sandbox.resume(args.name, local=local, **kwargs)
+ except Exception as e:
+ print_error(f"Failed to resume sandbox: {e}")
+ return 1
+ print_success(f"Sandbox '{args.name}' is resuming.")
return 0
+ return run_async(_run())
+
def cmd_restart(args: argparse.Namespace) -> int:
"""Restart a sandbox."""
+ local = getattr(args, "local", False)
- async def _restart():
- async with _get_provider() as provider:
- return await provider.restart_vm(args.name)
-
- result = run_async(_restart())
- status = result.get("status")
+ async def _run() -> int:
+ from cua_sandbox import Sandbox
- if status == "not_found":
- print_error(f"Sandbox '{args.name}' not found.")
- return 1
- elif status in ("error", "unauthorized"):
- print_error(f"Failed to restart sandbox: {result.get('message', status)}")
- return 1
- else:
+ try:
+ kwargs: dict[str, Any] = {}
+ if not local:
+ kwargs["api_key"] = require_api_key()
+ await Sandbox.restart(args.name, local=local, **kwargs)
+ except Exception as e:
+ print_error(f"Failed to restart sandbox: {e}")
+ return 1
print_success(f"Sandbox '{args.name}' is restarting.")
return 0
+ return run_async(_run())
-def cmd_suspend(args: argparse.Namespace) -> int:
- """Suspend a sandbox."""
- api_key = require_api_key()
- async def _suspend():
- status_code, data = await _api_request("POST", f"/v1/vms/{args.name}/suspend", api_key)
-
- if status_code in (200, 202):
- body_status = data.get("status") if isinstance(data, dict) else None
- return {"name": args.name, "status": body_status or "suspending"}
- elif status_code == 404:
- return {"name": args.name, "status": "not_found"}
- elif status_code == 401:
- return {"name": args.name, "status": "unauthorized"}
- elif status_code == 400:
- # Suspend may not be supported for all VM types
- return {"name": args.name, "status": "unsupported", "message": str(data)}
+def cmd_delete(args: argparse.Namespace) -> int:
+ """Delete a sandbox."""
+ local = getattr(args, "local", False)
+ force = getattr(args, "force", False)
+
+ if not force:
+ import sys
+
+ if not sys.stdin.isatty():
+ force = True
else:
- return {"name": args.name, "status": "error", "message": str(data)}
+ try:
+ answer = input(f"Delete sandbox '{args.name}'? [y/N] ").strip().lower()
+ except (EOFError, KeyboardInterrupt):
+ print()
+ return 1
+ if answer not in ("y", "yes"):
+ print_info("Aborted.")
+ return 0
- result = run_async(_suspend())
- status = result.get("status")
+ async def _run() -> int:
+ from cua_sandbox import Sandbox
- if status == "not_found":
- print_error(f"Sandbox '{args.name}' not found.")
- return 1
- elif status == "unsupported":
- print_error(f"Suspend not supported for this sandbox: {result.get('message', '')}")
- return 1
- elif status in ("error", "unauthorized"):
- print_error(f"Failed to suspend sandbox: {result.get('message', status)}")
- return 1
- else:
- print_success(f"Sandbox '{args.name}' is suspending.")
+ try:
+ kwargs: dict[str, Any] = {}
+ if not local:
+ kwargs["api_key"] = require_api_key()
+ await Sandbox.delete(args.name, local=local, **kwargs)
+ except Exception as e:
+ print_error(f"Failed to delete sandbox: {e}")
+ return 1
+ print_success(f"Sandbox '{args.name}' is being deleted.")
return 0
+ return run_async(_run())
+
def cmd_vnc(args: argparse.Namespace) -> int:
"""Open sandbox in browser via VNC."""
+ local = getattr(args, "local", False)
- async def _get_vnc_url():
- async with _get_provider() as provider:
- vms = await provider.list_vms()
- vm_info = next((vm for vm in vms if vm.get("name") == args.name), None)
- return vm_info
+ async def _run() -> int:
+ from cua_sandbox import Sandbox
- vm_info = run_async(_get_vnc_url())
+ try:
+ kwargs: dict[str, Any] = {}
+ if not local:
+ kwargs["api_key"] = require_api_key()
+ sb = await Sandbox.connect(args.name, local=local, **kwargs)
+ vnc_url = await sb.get_display_url(share=True)
+ await sb.disconnect()
+ except Exception as e:
+ print_error(f"Failed to get VNC URL: {e}")
+ return 1
- if not vm_info:
- print_error(f"Sandbox '{args.name}' not found.")
- return 1
+ print_info(f"Opening VNC: {vnc_url}")
+ webbrowser.open(vnc_url)
+ return 0
- # Always construct VNC URL from host (the API's vnc_url may use a stale domain)
- host = vm_info.get("host")
- password = vm_info.get("password")
+ return run_async(_run())
- if host and password:
- encoded_password = quote(password, safe="")
- vnc_url = (
- f"https://{host}/vnc.html?autoconnect=true&password={encoded_password}&show_dot=true"
- )
- else:
- print_error("Could not determine VNC URL. Sandbox may not be ready.")
- return 1
- print_info(f"Opening VNC: {vnc_url}")
- webbrowser.open(vnc_url)
- return 0
+# ---------------------------------------------------------------------------
+# PTY / WebSocket helpers (shell / exec)
+# ---------------------------------------------------------------------------
def _default_shell() -> str:
- """Get the default shell for the platform."""
return "powershell" if sys.platform == "win32" else "bash"
-async def _get_sandbox_api_url(name: str) -> tuple[str, str]:
- """Get the API URL and api_key for a sandbox.
-
- Returns:
- Tuple of (api_url, api_key)
-
- Raises:
- ValueError: If sandbox not found or not ready
- """
- api_key = require_api_key()
- async with _get_provider() as provider:
- vm = await provider.get_vm(name)
- if not vm:
- raise ValueError(f"Sandbox '{name}' not found")
- if vm.get("status") == "not_found":
- raise ValueError(f"Sandbox '{name}' not found")
- api_url = vm.get("api_url")
- if not api_url:
- raise ValueError(f"Sandbox '{name}' has no API URL (is it running?)")
- return api_url, api_key
-
-
async def _shell_interactive(
name: str,
api_url: str,
- api_key: str,
+ api_key: Optional[str],
command: Optional[str],
cols: Optional[int],
rows: Optional[int],
@@ -644,17 +717,17 @@ async def _shell_interactive(
ws_url = api_url.replace("https://", "wss://").replace("http://", "ws://")
- headers = {
- "X-API-Key": api_key,
+ headers: dict[str, str] = {
"X-Container-Name": name,
"Content-Type": "application/json",
}
- ws_params = {
- "api_key": api_key,
+ ws_params: dict[str, str] = {
"container_name": name,
}
+ if api_key:
+ headers["X-API-Key"] = api_key
+ ws_params["api_key"] = api_key
- # Create PTY session
try:
async with aiohttp.ClientSession() as http:
async with http.post(
@@ -788,17 +861,17 @@ async def _shell_interactive(
async def _exec_noninteractive(
name: str,
api_url: str,
- api_key: str,
+ api_key: Optional[str],
command: str,
) -> dict:
"""Execute a command non-interactively and return result."""
- headers = {
- "X-API-Key": api_key,
+ headers: dict[str, str] = {
"X-Container-Name": name,
"Content-Type": "application/json",
}
+ if api_key:
+ headers["X-API-Key"] = api_key
- # Use the /cmd endpoint with run_command for non-interactive execution
async with aiohttp.ClientSession() as http:
async with http.post(
f"{api_url}/cmd",
@@ -809,14 +882,12 @@ async def _exec_noninteractive(
if resp.status == 401:
return {"success": False, "error": "Authentication failed"}
text = await resp.text()
- # Parse SSE-style response
for line in text.splitlines():
if line.startswith("data: "):
try:
return json.loads(line[6:])
except json.JSONDecodeError:
pass
- # Try parsing as plain JSON
try:
return json.loads(text)
except json.JSONDecodeError:
@@ -827,18 +898,17 @@ def cmd_shell(args: argparse.Namespace) -> int:
"""Open interactive shell or run command in sandbox."""
command_parts = getattr(args, "shell_command", [])
command = " ".join(command_parts).strip() if command_parts else None
-
cols: Optional[int] = getattr(args, "cols", None)
rows: Optional[int] = getattr(args, "rows", None)
+ local = getattr(args, "local", False)
async def _run() -> int:
try:
- api_url, api_key = await _get_sandbox_api_url(args.name)
+ api_url, api_key = await _get_sandbox_api_url(args.name, local)
except ValueError as e:
print_error(str(e))
return 1
- # Non-interactive mode when stdin is not a TTY
if not sys.stdin.isatty():
if not command:
print_error("No command provided for non-interactive mode")
@@ -856,7 +926,6 @@ def cmd_shell(args: argparse.Namespace) -> int:
print(stderr, file=sys.stderr)
return returncode
- # Interactive mode
try:
return await _shell_interactive(args.name, api_url, api_key, command, cols, rows)
except ValueError as e:
@@ -870,6 +939,7 @@ def cmd_exec(args: argparse.Namespace) -> int:
"""Execute command in sandbox (non-interactive)."""
command_parts = getattr(args, "exec_command", [])
command = " ".join(command_parts).strip() if command_parts else None
+ local = getattr(args, "local", False)
if not command:
print_error("No command provided")
@@ -878,16 +948,15 @@ def cmd_exec(args: argparse.Namespace) -> int:
async def _run() -> int:
try:
- api_url, api_key = await _get_sandbox_api_url(args.name)
+ api_url, api_key = await _get_sandbox_api_url(args.name, local)
except ValueError as e:
print_error(str(e))
return 1
result = await _exec_noninteractive(args.name, api_url, api_key, command)
- if args.json:
+ if getattr(args, "json", False):
print_json(result)
- # Return the actual exit code from the command
return result.get("returncode") or result.get("return_code") or 0
if not result.get("success", True):
diff --git a/libs/python/cua-cli/cua_cli/commands/skills.py b/libs/python/cua-cli/cua_cli/commands/skills.py
index 8e82767dbc..26e015360c 100644
--- a/libs/python/cua-cli/cua_cli/commands/skills.py
+++ b/libs/python/cua-cli/cua_cli/commands/skills.py
@@ -485,33 +485,28 @@ async def _record_skill_async(args: argparse.Namespace) -> int:
# Build VNC URL with recording parameters
if args.sandbox:
# Get sandbox VNC URL
- from computer.providers.cloud.provider import CloudProvider
from cua_cli.auth.store import require_api_key
+ from cua_sandbox.transport.cloud import cloud_get_vm
- cloud_api_key = require_api_key()
- provider_inst = CloudProvider(api_key=cloud_api_key)
-
- async with provider_inst:
- vms = await provider_inst.list_vms()
- sandbox = next((vm for vm in vms if vm.get("name") == args.sandbox), None)
-
- if not sandbox:
- print_error(f"Sandbox not found: {args.sandbox}")
- server.close()
- return 1
-
- if sandbox.get("status") != "running":
- print_error(f"Sandbox is not running (status: {sandbox.get('status')})")
- server.close()
- return 1
-
- host = sandbox.get("host", f"{args.sandbox}.sandbox.cua.ai")
- password = sandbox.get("password", "")
- from urllib.parse import quote
-
- base_url = (
- f"https://{host}/vnc.html?autoconnect=true&password={quote(password)}&show_dot=true"
- )
+ try:
+ vm = await cloud_get_vm(args.sandbox, api_key=require_api_key())
+ except Exception:
+ vm = None
+ if not vm or vm.get("status") == "not_found":
+ print_error(f"Sandbox not found: {args.sandbox}")
+ server.close()
+ return 1
+ if vm.get("status") != "running":
+ print_error(f"Sandbox is not running (status: {vm.get('status')})")
+ server.close()
+ return 1
+ host = vm.get("host", f"{args.sandbox}.sandbox.cua.ai")
+ password = vm.get("password", "")
+ from urllib.parse import quote
+
+ base_url = (
+ f"https://{host}/vnc.html?autoconnect=true&password={quote(password)}&show_dot=true"
+ )
else:
base_url = args.vnc_url
diff --git a/libs/python/cua-cli/cua_cli/main.py b/libs/python/cua-cli/cua_cli/main.py
index 1b3476104a..7b2d1d9253 100644
--- a/libs/python/cua-cli/cua_cli/main.py
+++ b/libs/python/cua-cli/cua_cli/main.py
@@ -48,7 +48,7 @@ def main() -> int:
# Suppress noisy INFO logs from dependencies (computer, core.telemetry, etc.)
# Must set on specific loggers since they configure their own handlers at import time
logging.basicConfig(level=logging.WARNING)
- for name in ("computer", "core", "core.telemetry"):
+ for name in ("computer", "core", "core.telemetry", "httpx", "httpcore", "cua_sandbox"):
logging.getLogger(name).setLevel(logging.WARNING)
parser = create_parser()
diff --git a/libs/python/cua-sandbox/.bumpversion.cfg b/libs/python/cua-sandbox/.bumpversion.cfg
new file mode 100644
index 0000000000..9f081effc9
--- /dev/null
+++ b/libs/python/cua-sandbox/.bumpversion.cfg
@@ -0,0 +1,10 @@
+[bumpversion]
+current_version = 0.1.0
+commit = True
+tag = True
+tag_name = sandbox-v{new_version}
+message = Bump cua-sandbox to v{new_version}
+
+[bumpversion:file:pyproject.toml]
+search = version = "{current_version}"
+replace = version = "{new_version}"
diff --git a/libs/python/cua-sandbox/README.md b/libs/python/cua-sandbox/README.md
new file mode 100644
index 0000000000..5ee5e6d824
--- /dev/null
+++ b/libs/python/cua-sandbox/README.md
@@ -0,0 +1,79 @@
+# cua-sandbox
+
+Sandboxed VM environments with a unified Python API. Cloud by default.
+
+```bash
+pip install cua-sandbox
+```
+
+## Ephemeral sandbox
+
+Created on enter, destroyed on exit.
+
+```python
+from cua_sandbox import Sandbox, Image
+
+async with Sandbox.ephemeral(Image.linux()) as sb:
+ await sb.shell.run("uname -a")
+ await sb.screenshot()
+```
+
+## Persistent sandbox
+
+Provision a new sandbox that stays alive after your script exits.
+
+```python
+from cua_sandbox import Sandbox, Image
+
+sb = await Sandbox.create(Image.linux())
+await sb.shell.run("uname -a")
+print(sb.name) # save this to reconnect later
+await sb.disconnect()
+```
+
+## Connect to existing sandbox
+
+Attach to a sandbox that's already running. Works as a plain await or context manager.
+
+```python
+from cua_sandbox import Sandbox
+
+# plain await
+sb = await Sandbox.connect("my-sandbox")
+await sb.shell.run("whoami")
+await sb.disconnect()
+
+# context manager — disconnects on exit, sandbox keeps running
+async with Sandbox.connect("my-sandbox") as sb:
+ await sb.shell.run("whoami")
+```
+
+## Destroy a sandbox
+
+```python
+await sb.destroy() # disconnect + permanently delete
+```
+
+## Local VM
+
+Spins up a local VM using QEMU or Lume, destroyed on exit.
+
+```python
+from cua_sandbox import Sandbox, Image
+from cua_sandbox.runtime import QEMURuntime
+
+async with Sandbox.ephemeral(Image.linux(), local=True, runtime=QEMURuntime()) as sb:
+ await sb.shell.run("uname -a")
+```
+
+## Localhost (unsandboxed)
+
+Direct host control — **not sandboxed**, use with caution.
+
+```python
+from cua_sandbox import Localhost
+
+async with Localhost.connect() as host:
+ await host.shell.run("echo hello")
+ await host.screenshot()
+```
diff --git a/libs/python/cua-sandbox/cua_sandbox/__init__.py b/libs/python/cua-sandbox/cua_sandbox/__init__.py
new file mode 100644
index 0000000000..e6387e70cb
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/__init__.py
@@ -0,0 +1,39 @@
+"""cua-sandbox — ephemeral and persistent sandboxed computer environments.
+
+Usage::
+
+ import cua_sandbox as cua
+
+ # Configure API access
+ cua.configure(api_key="sk-...")
+
+ # Local sandbox
+ async with cua.sandbox(local=True) as sb:
+ await sb.screenshot()
+
+ # Localhost (no sandbox, direct host control)
+ async with cua.localhost() as host:
+ await host.mouse.click(100, 200)
+"""
+
+__version__ = "0.1.0"
+
+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.sandbox import Sandbox, SandboxInfo, sandbox
+from cua_sandbox.transport.cloud import CloudTransport
+
+__all__ = [
+ "configure",
+ "login",
+ "whoami",
+ "Image",
+ "Sandbox",
+ "SandboxInfo",
+ "sandbox",
+ "Localhost",
+ "localhost",
+ "CloudTransport",
+]
diff --git a/libs/python/cua-sandbox/cua_sandbox/_auth.py b/libs/python/cua-sandbox/cua_sandbox/_auth.py
new file mode 100644
index 0000000000..114ab437c1
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/_auth.py
@@ -0,0 +1,71 @@
+"""Authentication — login(), whoami(), credential storage.
+
+login() opens a Clerk browser redirect and stores the resulting token
+in ~/.cua/credentials. OAuth device flow deferred to a later stage.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import webbrowser
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import httpx
+
+from cua_sandbox._config import get_api_key, get_base_url
+
+_CUA_DIR = Path.home() / ".cua"
+_CREDENTIALS_FILE = _CUA_DIR / "credentials"
+
+
+def login(*, base_url: Optional[str] = None) -> None:
+ """Open the CUA login page in a browser and store credentials.
+
+ This initiates a Clerk-based browser authentication flow.
+ The user completes login in their browser, and the resulting
+ API key is stored in ~/.cua/credentials.
+ """
+ url = base_url or get_base_url()
+ login_url = f"{url}/auth/login"
+ print(f"Opening {login_url} in your browser...")
+ webbrowser.open(login_url)
+ print("Complete the login in your browser.")
+ print("Then paste the API key you receive below.")
+ api_key = input("API key: ").strip()
+ if not api_key:
+ print("No API key provided. Aborting.")
+ return
+ _save_credentials(api_key=api_key)
+ print("Credentials saved to ~/.cua/credentials")
+
+
+def whoami(*, api_key: Optional[str] = None) -> Dict[str, Any]:
+ """Return info about the authenticated user.
+
+ Returns:
+ Dict with user info (id, email, etc.) from the CUA API.
+ """
+ key = get_api_key(api_key)
+ if not key:
+ raise RuntimeError("Not authenticated. Run cua_sandbox.login() or set CUA_API_KEY.")
+ resp = httpx.get(
+ f"{get_base_url()}/v1/whoami",
+ headers={"Authorization": f"Bearer {key}"},
+ timeout=10,
+ )
+ resp.raise_for_status()
+ return resp.json()
+
+
+def _save_credentials(*, api_key: str) -> None:
+ """Write credentials to ~/.cua/credentials."""
+ _CUA_DIR.mkdir(parents=True, exist_ok=True)
+ _CREDENTIALS_FILE.write_text(f"api_key={api_key}\n")
+ # Restrict permissions on Unix
+ try:
+ _CREDENTIALS_FILE.chmod(0o600)
+ except OSError:
+ pass
diff --git a/libs/python/cua-sandbox/cua_sandbox/_config.py b/libs/python/cua-sandbox/cua_sandbox/_config.py
new file mode 100644
index 0000000000..d96efbb46d
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/_config.py
@@ -0,0 +1,69 @@
+"""Global configuration — configure(api_key, base_url).
+
+Auth priority: per-call > configure() > ~/.cua/credentials > CUA_API_KEY env var.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class _Config:
+ api_key: Optional[str] = None
+ base_url: str = "https://api.cua.ai"
+
+
+_global_config = _Config()
+
+
+def configure(
+ *,
+ api_key: Optional[str] = None,
+ base_url: Optional[str] = None,
+) -> None:
+ """Set global configuration for the CUA SDK.
+
+ Args:
+ api_key: API key for cloud sandboxes.
+ base_url: Base URL for the CUA cloud API.
+ """
+ if api_key is not None:
+ _global_config.api_key = api_key
+ if base_url is not None:
+ _global_config.base_url = base_url
+
+
+def get_api_key(override: Optional[str] = None) -> Optional[str]:
+ """Resolve API key with priority: override > configure() > credentials file > env."""
+ if override:
+ return override
+ if _global_config.api_key:
+ return _global_config.api_key
+ # Try credentials file
+ cred = _read_credentials_key()
+ if cred:
+ return cred
+ return os.environ.get("CUA_API_KEY")
+
+
+def get_base_url() -> str:
+ return _global_config.base_url
+
+
+def _read_credentials_key() -> Optional[str]:
+ """Read API key from ~/.cua/credentials if it exists."""
+ cred_path = os.path.join(os.path.expanduser("~"), ".cua", "credentials")
+ try:
+ with open(cred_path) as f:
+ for line in f:
+ line = line.strip()
+ if line.startswith("api_key="):
+ return line[len("api_key=") :]
+ if line.startswith("api_key ="):
+ return line[len("api_key =") :].strip()
+ except FileNotFoundError:
+ pass
+ return None
diff --git a/libs/python/cua-sandbox/cua_sandbox/agent.py b/libs/python/cua-sandbox/cua_sandbox/agent.py
new file mode 100644
index 0000000000..7edc42aa06
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/agent.py
@@ -0,0 +1,98 @@
+"""Agent integration — adapters that make Sandbox and Localhost work as
+AsyncComputerHandler for the cua-agent ComputerAgent.
+
+Usage::
+
+ from cua_sandbox import Image, Sandbox
+ from cua_sandbox.agent import SandboxHandler, LocalhostHandler
+
+ async with Sandbox.ephemeral(Image.linux(), local=True) as sb:
+ handler = SandboxHandler(sb)
+ agent = ComputerAgent(model="...", tools=[handler])
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+from typing import Any, Dict, List, Literal, Optional, Union
+
+from cua_sandbox.localhost import Localhost
+from cua_sandbox.sandbox import Sandbox
+
+
+class SandboxHandler:
+ """Adapts a Sandbox instance to the AsyncComputerHandler protocol."""
+
+ def __init__(self, sandbox: Sandbox):
+ self._sb = sandbox
+
+ async def get_environment(self) -> Literal["windows", "mac", "linux", "browser"]:
+ env = await self._sb.get_environment()
+ return env # type: ignore[return-value]
+
+ async def get_dimensions(self) -> tuple[int, int]:
+ return await self._sb.get_dimensions()
+
+ async def screenshot(self, text: Optional[str] = None) -> str:
+ raw = await self._sb.screenshot()
+ return base64.b64encode(raw).decode("utf-8")
+
+ async def click(self, x: int, y: int, button: str = "left") -> None:
+ await self._sb.mouse.click(x, y, button)
+
+ async def double_click(self, x: int, y: int) -> None:
+ await self._sb.mouse.double_click(x, y)
+
+ async def scroll(self, x: int, y: int, scroll_x: int, scroll_y: int) -> None:
+ await self._sb.mouse.scroll(x, y, scroll_x, scroll_y)
+
+ async def type(self, text: str) -> None:
+ await self._sb.keyboard.type(text)
+
+ async def wait(self, ms: int = 1000) -> None:
+ await asyncio.sleep(ms / 1000.0)
+
+ async def move(self, x: int, y: int) -> None:
+ await self._sb.mouse.move(x, y)
+
+ async def keypress(self, keys: Union[List[str], str]) -> None:
+ await self._sb.keyboard.keypress(keys)
+
+ async def drag(self, path: List[Dict[str, int]]) -> None:
+ if not path:
+ return
+ start = path[0]
+ await self._sb.mouse.mouse_down(start["x"], start["y"])
+ for point in path[1:]:
+ await self._sb.mouse.move(point["x"], point["y"])
+ end = path[-1]
+ await self._sb.mouse.mouse_up(end["x"], end["y"])
+
+ async def get_current_url(self) -> str:
+ return ""
+
+ async def left_mouse_down(self, x: Optional[int] = None, y: Optional[int] = None) -> None:
+ if x is not None and y is not None:
+ await self._sb.mouse.mouse_down(x, y)
+
+ async def left_mouse_up(self, x: Optional[int] = None, y: Optional[int] = None) -> None:
+ if x is not None and y is not None:
+ await self._sb.mouse.mouse_up(x, y)
+
+
+class LocalhostHandler(SandboxHandler):
+ """Adapts a Localhost instance to the AsyncComputerHandler protocol.
+
+ Localhost exposes the same interface as Sandbox, so we just reuse
+ the SandboxHandler with a Localhost in place of a Sandbox.
+ """
+
+ def __init__(self, host: Localhost):
+ # Localhost has the same interface shape as Sandbox
+ self._sb = host # type: ignore[assignment]
+
+
+def is_sandbox(obj: Any) -> bool:
+ """Check if an object is a Sandbox or Localhost instance."""
+ return isinstance(obj, (Sandbox, Localhost))
diff --git a/libs/python/cua-sandbox/cua_sandbox/builder/__init__.py b/libs/python/cua-sandbox/cua_sandbox/builder/__init__.py
new file mode 100644
index 0000000000..0e8edce11d
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/builder/__init__.py
@@ -0,0 +1,6 @@
+"""Image builder — build QEMU VM images from Image layer specs."""
+
+from cua_sandbox.builder.executor import LayerExecutor
+from cua_sandbox.builder.overlay import create_overlay, IMAGES_DIR
+
+__all__ = ["LayerExecutor", "create_overlay", "IMAGES_DIR"]
diff --git a/libs/python/cua-sandbox/cua_sandbox/builder/__main__.py b/libs/python/cua-sandbox/cua_sandbox/builder/__main__.py
new file mode 100644
index 0000000000..7a54be62fc
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/builder/__main__.py
@@ -0,0 +1,91 @@
+"""CLI for building QEMU VM images.
+
+Usage:
+ python -m cua_sandbox.builder build-base --os windows --version 11
+ python -m cua_sandbox.builder build-base --os windows --version 11 --iso-path /path/to/win11.iso
+ python -m cua_sandbox.builder build --spec '{"os_type":"windows","version":"11","layers":[{"type":"winget_install","packages":["Git.Git"]}]}'
+ python -m cua_sandbox.builder info
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import logging
+import sys
+from pathlib import Path
+
+from cua_sandbox.builder.overlay import IMAGES_DIR, base_image_path
+
+
+def main():
+ logging.basicConfig(level=logging.INFO, format="%(message)s")
+
+ parser = argparse.ArgumentParser(description="CUA Sandbox image builder")
+ sub = parser.add_subparsers(dest="command")
+
+ # build-base
+ bb = sub.add_parser("build-base", help="Build a base image (OS + computer-server)")
+ bb.add_argument("--os", default="windows", help="OS type (windows, linux)")
+ bb.add_argument("--version", default="11", help="OS version")
+ bb.add_argument("--iso-path", help="Path to OS ISO (skip download)")
+ bb.add_argument("--product-key", help="Windows product key")
+ bb.add_argument("--force", action="store_true", help="Rebuild even if cached")
+
+ # build (from Image spec)
+ b = sub.add_parser("build", help="Build a user image from an Image spec JSON")
+ b.add_argument("--spec", required=True, help="Image spec as JSON string or @file.json")
+ b.add_argument("--force", action="store_true")
+
+ # info
+ sub.add_parser("info", help="Show cached images")
+
+ args = parser.parse_args()
+
+ if args.command == "build-base":
+ from cua_sandbox.builder.build import ensure_base_image
+ disk = asyncio.run(ensure_base_image(
+ args.os, args.version,
+ windows_iso=args.iso_path,
+ product_key=args.product_key,
+ force=args.force,
+ ))
+ print(f"Base image: {disk}")
+
+ elif args.command == "build":
+ spec_str = args.spec
+ if spec_str.startswith("@"):
+ spec_str = Path(spec_str[1:]).read_text()
+ spec = json.loads(spec_str)
+
+ from cua_sandbox.image import Image
+ from cua_sandbox.builder.build import build_user_image, ensure_base_image
+
+ image = Image.from_dict(spec)
+ base = asyncio.run(ensure_base_image(image.os_type, image.version))
+ user_disk = asyncio.run(build_user_image(image, base, force=args.force))
+ print(f"User image: {user_disk}")
+
+ elif args.command == "info":
+ if not IMAGES_DIR.exists():
+ print(f"No images directory: {IMAGES_DIR}")
+ return
+ print(f"Images directory: {IMAGES_DIR}\n")
+ for d in sorted(IMAGES_DIR.iterdir()):
+ if d.is_dir():
+ disk = d / "disk.qcow2"
+ meta = d / "disk.json"
+ size = f"{disk.stat().st_size / 1024 / 1024:.0f} MB" if disk.exists() else "no disk"
+ layers = ""
+ if meta.exists():
+ m = json.loads(meta.read_text())
+ layers = f" ({len(m.get('layers', []))} layers)"
+ print(f" {d.name}: {size}{layers}")
+
+ else:
+ parser.print_help()
+
+
+if __name__ == "__main__":
+ main()
diff --git a/libs/python/cua-sandbox/cua_sandbox/builder/build.py b/libs/python/cua-sandbox/cua_sandbox/builder/build.py
new file mode 100644
index 0000000000..932eab43ad
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/builder/build.py
@@ -0,0 +1,363 @@
+"""Build orchestrator — resolve or build base images, apply user layers, create session overlays.
+
+Implements the 3-layer qcow2 chain:
+
+ base (OS + computer-server) → user overlay (layers) → session overlay (ephemeral)
+
+Usage::
+
+ from cua_sandbox.builder.build import resolve_image_disk
+
+ # Returns the disk path to boot — handles base building, layer caching, overlays
+ disk_path = await resolve_image_disk(image, name="my-sandbox")
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from pathlib import Path
+from typing import Optional
+
+from cua_sandbox.builder.overlay import (
+ base_image_path,
+ create_overlay,
+ layers_hash,
+ session_overlay_path,
+ user_image_path,
+)
+from cua_sandbox.image import Image
+
+logger = logging.getLogger(__name__)
+
+# computer-server setup script — ported from setup-cua-server.ps1
+# Runs inside the VM after first boot to install computer-server + scheduled task
+SETUP_COMPUTER_SERVER_PS1 = r'''
+$ErrorActionPreference = 'Continue'
+
+# Install UV
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+$uvPath = Join-Path $env:USERPROFILE ".local\bin"
+$env:Path = "$uvPath;$env:Path"
+
+# Create UV project
+$ProjectDir = Join-Path $env:USERPROFILE "cua-server"
+if (!(Test-Path (Join-Path $ProjectDir "pyproject.toml"))) {
+ New-Item -ItemType Directory -Force -Path $ProjectDir | Out-Null
+ & uv init --vcs none --no-readme --no-workspace --no-pin-python $ProjectDir
+}
+
+# Install cua-computer-server (no agent — VM only needs automation server)
+& uv add --directory $ProjectDir cua-computer-server
+
+# Install playwright + firefox
+& uv add --directory $ProjectDir playwright
+& uv run --directory $ProjectDir playwright install firefox
+
+# Firewall rule for port 8000
+netsh advfirewall firewall add rule name="CUA Computer Server" dir=in action=allow protocol=TCP localport=8000
+
+# Create start script
+$StartScript = Join-Path $ProjectDir "start-server.ps1"
+@"
+`$env:PYTHONUNBUFFERED = '1'
+`$uvPath = Join-Path `$env:USERPROFILE '.local\bin'
+`$env:Path = "`$uvPath;`$env:Path"
+while (`$true) {
+ & uv run --directory '$ProjectDir' python -m computer_server --port 8000
+ Start-Sleep -Seconds 5
+}
+"@ | Set-Content -Path $StartScript -Encoding UTF8
+
+# VBScript wrapper for hidden execution
+$VbsWrapper = Join-Path $ProjectDir "start-server-hidden.vbs"
+@"
+Set objShell = CreateObject("WScript.Shell")
+objShell.Run "powershell.exe -NoProfile -ExecutionPolicy Bypass -File ""$StartScript""", 0, False
+"@ | Set-Content -Path $VbsWrapper -Encoding ASCII
+
+# Scheduled task at logon
+$TaskName = "Cua-Computer-Server"
+$Username = $env:USERNAME
+$existing = Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue
+if ($existing) { Unregister-ScheduledTask -TaskName $TaskName -Confirm:$false }
+
+$Action = New-ScheduledTaskAction -Execute "wscript.exe" -Argument "`"$VbsWrapper`""
+$UserId = "$env:COMPUTERNAME\$Username"
+$Trigger = New-ScheduledTaskTrigger -AtLogOn -User $UserId
+$Principal = New-ScheduledTaskPrincipal -UserId $UserId -LogonType Interactive -RunLevel Highest
+$Settings = New-ScheduledTaskSettingsSet `
+ -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -StartWhenAvailable `
+ -RestartCount 999 -RestartInterval (New-TimeSpan -Minutes 1) `
+ -ExecutionTimeLimit (New-TimeSpan -Days 365) -Hidden
+
+Register-ScheduledTask -TaskName $TaskName -Action $Action -Trigger $Trigger `
+ -Principal $Principal -Settings $Settings -Force | Out-Null
+
+# Start the server now too
+Start-Process wscript.exe -ArgumentList "`"$VbsWrapper`""
+
+Write-Host "CUA Computer Server setup complete"
+'''
+
+# Linux equivalent
+SETUP_COMPUTER_SERVER_SH = r"""#!/bin/bash
+set -e
+
+# Install uv
+curl -LsSf https://astral.sh/uv/install.sh | sh
+export PATH="$HOME/.local/bin:$PATH"
+
+# Create uv project
+mkdir -p ~/cua-server
+cd ~/cua-server
+[ -f pyproject.toml ] || uv init --vcs none --no-readme --no-workspace --no-pin-python .
+
+# Install cua-computer-server
+uv add cua-computer-server "cua-agent[all]"
+
+# Install playwright + firefox
+uv add playwright
+uv run playwright install firefox
+
+# Create systemd service
+sudo tee /etc/systemd/system/cua-computer-server.service > /dev/null <<UNIT
+[Unit]
+Description=CUA Computer Server
+After=network.target
+
+[Service]
+Type=simple
+User=$USER
+WorkingDirectory=$HOME/cua-server
+ExecStart=$HOME/.local/bin/uv run python -m computer_server --port 8000
+Restart=always
+RestartSec=5
+Environment=PYTHONUNBUFFERED=1
+
+[Install]
+WantedBy=multi-user.target
+UNIT
+
+sudo systemctl daemon-reload
+sudo systemctl enable --now cua-computer-server
+
+echo "CUA Computer Server setup complete"
+"""
+
+
+async def ensure_base_image(
+ os_type: str,
+ version: str,
+ *,
+ windows_iso: Optional[str] = None,
+ product_key: Optional[str] = None,
+ force: bool = False,
+) -> Path:
+ """Ensure the base image (OS + computer-server) exists. Build if needed.
+
+ Returns the path to the base qcow2.
+ """
+ base_path = base_image_path(os_type, version)
+
+ _MIN_BASE_SIZE = {
+ "windows": 1 * 1024 * 1024 * 1024, # 1 GB — incomplete install guard
+ "linux": 100 * 1024 * 1024, # 100 MB
+ }
+ if base_path.exists() and not force:
+ min_size = _MIN_BASE_SIZE.get(os_type, 0)
+ if base_path.stat().st_size >= min_size:
+ logger.info(f"Using cached base image: {base_path}")
+ return base_path
+ logger.warning(
+ f"Cached base image {base_path} is too small "
+ f"({base_path.stat().st_size} bytes < {min_size}), rebuilding."
+ )
+ base_path.unlink()
+
+ logger.info(f"Building base image for {os_type} {version}...")
+
+ if os_type == "windows":
+ return await _build_windows_base(version, base_path, windows_iso, product_key)
+ elif os_type == "linux":
+ return await _build_linux_base(version, base_path)
+ else:
+ raise ValueError(f"Cannot build base image for os_type={os_type}")
+
+
+async def _build_windows_base(
+ version: str,
+ base_path: Path,
+ windows_iso: Optional[str],
+ product_key: Optional[str],
+) -> Path:
+ """Build Windows base: unattend install + computer-server."""
+ from cua_sandbox.registry.qemu_builder import (
+ QEMUImageConfig,
+ build_image,
+ )
+
+ config = QEMUImageConfig(guest_os="windows", version=version)
+ work_dir = base_path.parent / "build"
+
+ # Phase 1: Unattended Windows install
+ raw_disk = build_image(
+ config, windows_iso=windows_iso, work_dir=work_dir, product_key=product_key
+ )
+
+ # Phase 2: Boot and install computer-server
+ logger.info("Installing computer-server into base image...")
+ # Boot the raw disk to install computer-server
+ # First we need to boot without expecting computer-server (it's not installed yet)
+ # We use a temporary overlay so we can retry if needed
+ import shutil
+
+ temp_disk = work_dir / "temp-boot.qcow2"
+ shutil.copy2(raw_disk, temp_disk)
+
+ # Boot and wait for Windows to be accessible (but not computer-server — it's not installed)
+ # We need to wait for Windows to boot then run the setup script
+ # This is tricky because we don't have computer-server yet...
+ # Use QMP or VNC to inject the setup script, or use the virtio-serial approach
+ #
+ # For now: the Autounattend.xml should include a FirstLogonCommand that
+ # downloads and runs the setup script. Let's add that to the builder.
+ logger.info(
+ "Base image built at %s. Computer-server must be installed via "
+ "Autounattend FirstLogonCommand or manual VNC session.",
+ raw_disk,
+ )
+
+ # Move the built disk to the base path
+ base_path.parent.mkdir(parents=True, exist_ok=True)
+ shutil.move(str(raw_disk), str(base_path))
+
+ return base_path
+
+
+async def _build_linux_base(version: str, base_path: Path) -> Path:
+ """Build Linux base: install from cloud image + computer-server."""
+ raise NotImplementedError("Linux base image building not yet implemented")
+
+
+async def build_user_image(
+ image: Image,
+ base_path: Path,
+ *,
+ force: bool = False,
+) -> Path:
+ """Build a user image by applying Image layers on top of the base.
+
+ Creates a qcow2 overlay backed by base_path, boots it, runs all layers
+ via computer-server, then shuts down. The overlay is the user image.
+
+ Returns the path to the user image qcow2.
+ """
+ if not image._layers:
+ # No user layers — just use the base
+ return base_path
+
+ lhash = layers_hash(list(image._layers))
+ user_path = user_image_path(image.os_type, image.version, lhash)
+
+ if user_path.exists() and not force:
+ logger.info(f"Using cached user image: {user_path} (hash={lhash})")
+ return user_path
+
+ logger.info(f"Building user image (hash={lhash}, {len(image._layers)} layers)...")
+
+ # Create overlay on top of base
+ create_overlay(base_path, user_path)
+
+ # Boot the overlay and execute layers
+ from cua_sandbox.runtime.qemu import QEMUBaremetalRuntime
+
+ runtime = QEMUBaremetalRuntime(api_port=18098, memory_mb=8192, cpu_count=4)
+
+ build_image = Image.from_file(str(user_path), os_type=image.os_type)
+ try:
+ info = await runtime.start(build_image, f"cua-build-{lhash}")
+
+ # Execute layers via computer-server
+ from cua_sandbox.builder.executor import LayerExecutor
+
+ executor = LayerExecutor(f"http://{info.host}:{info.api_port}")
+ await executor.execute_layers(list(image._layers))
+
+ # Shut down cleanly
+ logger.info("Layers applied, shutting down build VM...")
+ try:
+ await executor.run_command(
+ "shutdown /s /t 5" if image.os_type == "windows" else "sudo shutdown -h now"
+ )
+ except Exception:
+ pass
+ await asyncio.sleep(10)
+ finally:
+ await runtime.stop(f"cua-build-{lhash}")
+
+ logger.info(f"User image built: {user_path}")
+
+ # Save layer metadata
+ meta_path = user_path.with_suffix(".json")
+ meta_path.write_text(
+ json.dumps(
+ {
+ "os_type": image.os_type,
+ "version": image.version,
+ "layers": list(image._layers),
+ "base": str(base_path),
+ "hash": lhash,
+ },
+ indent=2,
+ )
+ )
+
+ return user_path
+
+
+async def create_session_disk(
+ image: Image,
+ name: str,
+ *,
+ base_disk: Optional[Path] = None,
+) -> Path:
+ """Create a session overlay for a sandbox run.
+
+ If the image has layers and a cached user image exists, overlay on that.
+ Otherwise overlay on the base image. If no base exists, returns the
+ image's _disk_path directly (no overlay).
+
+ Returns the disk path to boot.
+ """
+ # If image has a direct disk path and no layers, use it directly
+ if image._disk_path and not image._layers:
+ return Path(image._disk_path)
+
+ # Determine the backing disk
+ if base_disk:
+ backing = base_disk
+ elif image._disk_path:
+ backing = Path(image._disk_path)
+ else:
+ # Auto-build base if it doesn't exist
+ backing = await ensure_base_image(image.os_type, image.version)
+
+ # If there are user layers, check for cached user image
+ if image._layers:
+ lhash = layers_hash(list(image._layers))
+ user_disk = user_image_path(image.os_type, image.version, lhash)
+ if user_disk.exists():
+ backing = user_disk
+ else:
+ # Need to build the user image first
+ backing = await build_user_image(image, backing)
+
+ # Create ephemeral session overlay
+ session_disk = session_overlay_path(name)
+ if session_disk.exists():
+ session_disk.unlink()
+ create_overlay(backing, session_disk)
+
+ return session_disk
diff --git a/libs/python/cua-sandbox/cua_sandbox/builder/executor.py b/libs/python/cua-sandbox/cua_sandbox/builder/executor.py
new file mode 100644
index 0000000000..9b1ab002d5
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/builder/executor.py
@@ -0,0 +1,123 @@
+"""Layer executor — boots a QEMU VM and 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.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+class LayerExecutor:
+ """Execute Image layer specs against a running computer-server."""
+
+ def __init__(self, base_url: str, timeout: float = 600):
+ self.base_url = base_url.rstrip("/")
+ self.timeout = timeout
+
+ async def run_command(self, command: str, timeout: float | None = None) -> dict:
+ """Run a shell command via computer-server and return the result."""
+ t = timeout or self.timeout
+ async with httpx.AsyncClient(timeout=t) as client:
+ # 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)},
+ timeout=t,
+ )
+ resp.raise_for_status()
+
+ # Parse SSE response — collect all data lines
+ 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):
+ 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"]
+ handler = getattr(self, f"_exec_{lt}", None)
+ if handler is None:
+ raise ValueError(f"Unknown layer type: {lt}")
+ return await handler(layer)
+
+ async def execute_layers(self, layers: list[dict]) -> list[dict]:
+ """Execute all layers sequentially. Raises on first failure."""
+ results = []
+ for i, layer in enumerate(layers):
+ 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):
+ logger.error(f"Layer {lt} failed (rc={rc}): {result.get('stderr', '')}")
+ raise RuntimeError(
+ f"Layer {i + 1} ({lt}) failed with exit code {rc}: "
+ f"{result.get('stderr', '')}"
+ )
+ logger.info(f"Layer {lt} completed successfully")
+ results.append(result)
+ return results
+
+ # ── Per-layer-type handlers ──────────────────────────────────────────
+
+ async def _exec_run(self, layer: dict) -> dict:
+ return await self.run_command(layer["command"])
+
+ 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}")
+
+ async def _exec_brew_install(self, layer: dict) -> dict:
+ pkgs = " ".join(layer["packages"])
+ return await self.run_command(f"brew install {pkgs}")
+
+ async def _exec_choco_install(self, layer: dict) -> dict:
+ pkgs = " ".join(layer["packages"])
+ return await self.run_command(f"choco install -y {pkgs}", timeout=900)
+
+ async def _exec_winget_install(self, layer: dict) -> dict:
+ cmds = []
+ for pkg in layer["packages"]:
+ cmds.append(
+ f"winget install --accept-source-agreements "
+ f"--accept-package-agreements -e --id {pkg}"
+ )
+ combined = " && ".join(cmds)
+ return await self.run_command(combined, timeout=900)
+
+ async def _exec_uv_install(self, layer: dict) -> dict:
+ pkgs = " ".join(layer["packages"])
+ return await self.run_command(
+ f"uv add --directory %USERPROFILE%\\cua-server {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)
+
+ 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}
+
+ 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)")
diff --git a/libs/python/cua-sandbox/cua_sandbox/builder/overlay.py b/libs/python/cua-sandbox/cua_sandbox/builder/overlay.py
new file mode 100644
index 0000000000..5b80f249d5
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/builder/overlay.py
@@ -0,0 +1,84 @@
+"""QEMU qcow2 overlay (backing file) management.
+
+Provides the 3-layer chain:
+ Layer 0 (base): windows-11-base.qcow2 — unattend + computer-server
+ Layer 1 (user): {hash}.qcow2 — user's .winget_install()/.run() etc
+ Layer 2 (session): session-{uuid}.qcow2 — ephemeral sandbox runtime
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+IMAGES_DIR = Path.home() / ".cua" / "cua-sandbox" / "images"
+
+
+def _qemu_img() -> str:
+ """Resolve qemu-img binary."""
+ import shutil
+ found = shutil.which("qemu-img")
+ if found:
+ return found
+ from cua_sandbox.runtime.qemu_installer import qemu_bin
+ parent = Path(qemu_bin("x86_64")).parent
+ for name in ["qemu-img", "qemu-img.exe"]:
+ p = parent / name
+ if p.exists():
+ return str(p)
+ raise RuntimeError("qemu-img not found")
+
+
+def create_overlay(backing: Path, overlay: Path) -> Path:
+ """Create a qcow2 overlay with the given backing file."""
+ overlay.parent.mkdir(parents=True, exist_ok=True)
+ cmd = [
+ _qemu_img(), "create", "-q",
+ "-f", "qcow2",
+ "-b", str(backing), "-F", "qcow2",
+ str(overlay),
+ ]
+ subprocess.run(cmd, check=True, capture_output=True)
+ logger.info(f"Created overlay: {overlay} (backing: {backing})")
+ return overlay
+
+
+def commit_overlay(overlay: Path) -> None:
+ """Commit an overlay's changes into its backing file (flattens one level)."""
+ cmd = [_qemu_img(), "commit", "-q", str(overlay)]
+ subprocess.run(cmd, check=True, capture_output=True)
+ logger.info(f"Committed overlay: {overlay}")
+
+
+def rebase_standalone(disk: Path) -> None:
+ """Remove backing file reference, making the disk standalone."""
+ cmd = [_qemu_img(), "rebase", "-u", "-b", "", str(disk)]
+ subprocess.run(cmd, check=True, capture_output=True)
+ logger.info(f"Rebased standalone: {disk}")
+
+
+def layers_hash(layers: list[dict]) -> str:
+ """Compute a stable hash for a list of Image layers."""
+ raw = json.dumps(layers, sort_keys=True).encode()
+ return hashlib.sha256(raw).hexdigest()[:16]
+
+
+def base_image_path(os_type: str, version: str) -> Path:
+ """Path to the cached base image (OS + computer-server installed)."""
+ return IMAGES_DIR / f"{os_type}-{version}-base" / "disk.qcow2"
+
+
+def user_image_path(os_type: str, version: str, layer_hash: str) -> Path:
+ """Path to a cached user layer image."""
+ return IMAGES_DIR / f"{os_type}-{version}-{layer_hash}" / "disk.qcow2"
+
+
+def session_overlay_path(name: str) -> Path:
+ """Path to an ephemeral session overlay."""
+ return IMAGES_DIR / "sessions" / f"{name}.qcow2"
diff --git a/libs/python/cua-sandbox/cua_sandbox/builder/windows_unattend.py b/libs/python/cua-sandbox/cua_sandbox/builder/windows_unattend.py
new file mode 100644
index 0000000000..0b5f3d1547
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/builder/windows_unattend.py
@@ -0,0 +1,375 @@
+"""Shared Windows unattended install helpers.
+
+Used by both the QEMU builder and Hyper-V runtime to create Windows images
+from scratch via Autounattend.xml + CUA server setup script.
+"""
+
+from __future__ import annotations
+
+import logging
+import shutil
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+# ── Download helpers ────────────────────────────────────────────────────────
+
+
+def download_file(url: str, dest: Path, description: str = "") -> Path:
+ """Download a file with progress, skipping if it already exists."""
+ if dest.exists():
+ logger.info(f"Already downloaded: {dest}")
+ return dest
+ dest.parent.mkdir(parents=True, exist_ok=True)
+ logger.info(f"Downloading {description or url} → {dest}")
+ import urllib.request
+ urllib.request.urlretrieve(url, str(dest))
+ logger.info(f"Downloaded {dest.stat().st_size / 1024 / 1024:.0f} MB")
+ return dest
+
+
+def download_windows_iso(
+ version: str = "11",
+ dest: Optional[Path] = None,
+ iso_path: Optional[str] = None,
+) -> Path:
+ """Get a Windows ISO. If iso_path is given, use it directly."""
+ if iso_path:
+ p = Path(iso_path)
+ if not p.exists():
+ raise FileNotFoundError(f"Windows ISO not found: {iso_path}")
+ return p
+
+ dest_dir = dest or Path.home() / ".cua" / "cua-sandbox" / "iso"
+ dest_dir.mkdir(parents=True, exist_ok=True)
+ iso_file = dest_dir / f"windows-{version}.iso"
+
+ if iso_file.exists():
+ logger.info(f"Using cached ISO: {iso_file}")
+ return iso_file
+
+ if version == "11":
+ url = "https://go.microsoft.com/fwlink/?linkid=2334167&clcid=0x409"
+ elif version == "10":
+ url = "https://go.microsoft.com/fwlink/?LinkId=691209"
+ else:
+ raise ValueError(
+ f"Cannot auto-download Windows {version}. "
+ f"Provide --iso-path to use your own ISO."
+ )
+
+ logger.info(f"Downloading Windows {version} Enterprise Evaluation ISO...")
+ logger.info("This is ~6GB and may take a while.")
+ return download_file(url, iso_file, f"Windows {version} ISO")
+
+
+# ── Autounattend.xml generation ─────────────────────────────────────────────
+
+
+def generate_autounattend_xml(
+ product_key: Optional[str] = None,
+ *,
+ include_virtio_drivers: bool = True,
+) -> str:
+ """Generate a Windows 11 Autounattend.xml for unattended installation.
+
+ Args:
+ product_key: Windows product key. Defaults to Win11 Pro generic key.
+ include_virtio_drivers: Include VirtIO driver paths in WinPE pass.
+ Set False for Hyper-V (has enlightened drivers built-in).
+ """
+ key_section = ""
+ if product_key:
+ key_section = f"""<ProductKey>
+ <Key>{product_key}</Key>
+ </ProductKey>"""
+ else:
+ key_section = """<ProductKey>
+ <Key>VK7JG-NPHTM-C97JM-9MPGT-3V66T</Key>
+ </ProductKey>"""
+
+ virtio_section = ""
+ if include_virtio_drivers:
+ virtio_section = """
+ <component name="Microsoft-Windows-PnpCustomizationsWinPE" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="nonSxS">
+ <DriverPaths>
+ <PathAndCredentials wcm:action="add" wcm:keyValue="1">
+ <Path>D:\\viostor\\w11\\amd64</Path>
+ </PathAndCredentials>
+ <PathAndCredentials wcm:action="add" wcm:keyValue="2">
+ <Path>E:\\viostor\\w11\\amd64</Path>
+ </PathAndCredentials>
+ <PathAndCredentials wcm:action="add" wcm:keyValue="3">
+ <Path>F:\\viostor\\w11\\amd64</Path>
+ </PathAndCredentials>
+ <PathAndCredentials wcm:action="add" wcm:keyValue="4">
+ <Path>D:\\NetKVM\\w11\\amd64</Path>
+ </PathAndCredentials>
+ <PathAndCredentials wcm:action="add" wcm:keyValue="5">
+ <Path>E:\\NetKVM\\w11\\amd64</Path>
+ </PathAndCredentials>
+ <PathAndCredentials wcm:action="add" wcm:keyValue="6">
+ <Path>F:\\NetKVM\\w11\\amd64</Path>
+ </PathAndCredentials>
+ </DriverPaths>
+ </component>"""
+
+ return f"""<?xml version="1.0" encoding="utf-8"?>
+<unattend xmlns="urn:schemas-microsoft-com:unattend" xmlns:wcm="http://schemas.microsoft.com/WMIConfig/2002/State">
+ <settings pass="windowsPE">
+ <component name="Microsoft-Windows-International-Core-WinPE" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="nonSxS">
+ <SetupUILanguage>
+ <UILanguage>en-US</UILanguage>
+ </SetupUILanguage>
+ <InputLocale>0409:00000409</InputLocale>
+ <SystemLocale>en-US</SystemLocale>
+ <UILanguage>en-US</UILanguage>
+ <UserLocale>en-US</UserLocale>
+ </component>{virtio_section}
+ <component name="Microsoft-Windows-Setup" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="nonSxS">
+ <DiskConfiguration>
+ <Disk wcm:action="add">
+ <DiskID>0</DiskID>
+ <WillWipeDisk>true</WillWipeDisk>
+ <CreatePartitions>
+ <CreatePartition wcm:action="add">
+ <Order>1</Order>
+ <Type>EFI</Type>
+ <Size>128</Size>
+ </CreatePartition>
+ <CreatePartition wcm:action="add">
+ <Order>2</Order>
+ <Type>MSR</Type>
+ <Size>128</Size>
+ </CreatePartition>
+ <CreatePartition wcm:action="add">
+ <Order>3</Order>
+ <Type>Primary</Type>
+ <Extend>true</Extend>
+ </CreatePartition>
+ </CreatePartitions>
+ <ModifyPartitions>
+ <ModifyPartition wcm:action="add">
+ <Order>1</Order>
+ <PartitionID>1</PartitionID>
+ <Label>System</Label>
+ <Format>FAT32</Format>
+ </ModifyPartition>
+ <ModifyPartition wcm:action="add">
+ <Order>2</Order>
+ <PartitionID>2</PartitionID>
+ </ModifyPartition>
+ <ModifyPartition wcm:action="add">
+ <Order>3</Order>
+ <PartitionID>3</PartitionID>
+ <Label>Windows</Label>
+ <Letter>C</Letter>
+ <Format>NTFS</Format>
+ </ModifyPartition>
+ </ModifyPartitions>
+ </Disk>
+ </DiskConfiguration>
+ <ImageInstall>
+ <OSImage>
+ <InstallTo>
+ <DiskID>0</DiskID>
+ <PartitionID>3</PartitionID>
+ </InstallTo>
+ <InstallToAvailablePartition>false</InstallToAvailablePartition>
+ </OSImage>
+ </ImageInstall>
+ <UserData>
+ <AcceptEula>true</AcceptEula>
+ <FullName>User</FullName>
+ <Organization>CUA</Organization>
+ {key_section}
+ </UserData>
+ <EnableFirewall>false</EnableFirewall>
+ <RunSynchronous>
+ <RunSynchronousCommand wcm:action="add">
+ <Order>1</Order>
+ <Path>reg.exe add "HKLM\\SYSTEM\\Setup\\LabConfig" /v BypassTPMCheck /t REG_DWORD /d 1 /f</Path>
+ </RunSynchronousCommand>
+ <RunSynchronousCommand wcm:action="add">
+ <Order>2</Order>
+ <Path>reg.exe add "HKLM\\SYSTEM\\Setup\\LabConfig" /v BypassSecureBootCheck /t REG_DWORD /d 1 /f</Path>
+ </RunSynchronousCommand>
+ <RunSynchronousCommand wcm:action="add">
+ <Order>3</Order>
+ <Path>reg.exe add "HKLM\\SYSTEM\\Setup\\LabConfig" /v BypassRAMCheck /t REG_DWORD /d 1 /f</Path>
+ </RunSynchronousCommand>
+ <RunSynchronousCommand wcm:action="add">
+ <Order>4</Order>
+ <Path>reg.exe add "HKLM\\SYSTEM\\Setup\\MoSetup" /v AllowUpgradesWithUnsupportedTPMOrCPU /t REG_DWORD /d 1 /f</Path>
+ </RunSynchronousCommand>
+ </RunSynchronous>
+ </component>
+ </settings>
+ <settings pass="offlineServicing">
+ <component name="Microsoft-Windows-LUA-Settings" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="nonSxS">
+ <EnableLUA>false</EnableLUA>
+ </component>
+ </settings>
+ <settings pass="specialize">
+ <component name="Microsoft-Windows-Deployment" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="nonSxS">
+ <RunSynchronous>
+ <RunSynchronousCommand wcm:action="add">
+ <Order>1</Order>
+ <Path>reg.exe add "HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\OOBE" /v BypassNRO /t REG_DWORD /d 1 /f</Path>
+ </RunSynchronousCommand>
+ </RunSynchronous>
+ </component>
+ <component name="Microsoft-Windows-TerminalServices-LocalSessionManager" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="nonSxS">
+ <fDenyTSConnections>false</fDenyTSConnections>
+ </component>
+ <component name="Microsoft-Windows-TerminalServices-RDP-WinStationExtensions" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="nonSxS">
+ <UserAuthentication>0</UserAuthentication>
+ </component>
+ <component name="Networking-MPSSVC-Svc" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="nonSxS">
+ <FirewallGroups>
+ <FirewallGroup wcm:action="add" wcm:keyValue="RemoteDesktop">
+ <Active>true</Active>
+ <Profile>all</Profile>
+ <Group>@FirewallAPI.dll,-28752</Group>
+ </FirewallGroup>
+ </FirewallGroups>
+ </component>
+ </settings>
+ <settings pass="oobeSystem">
+ <component name="Microsoft-Windows-Shell-Setup" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="nonSxS">
+ <UserAccounts>
+ <LocalAccounts>
+ <LocalAccount wcm:action="add">
+ <Name>User</Name>
+ <Group>Administrators</Group>
+ <Password>
+ <Value />
+ <PlainText>true</PlainText>
+ </Password>
+ </LocalAccount>
+ </LocalAccounts>
+ </UserAccounts>
+ <AutoLogon>
+ <Username>User</Username>
+ <Enabled>true</Enabled>
+ <LogonCount>65432</LogonCount>
+ <Password>
+ <Value />
+ <PlainText>true</PlainText>
+ </Password>
+ </AutoLogon>
+ <Display>
+ <ColorDepth>32</ColorDepth>
+ <HorizontalResolution>1280</HorizontalResolution>
+ <VerticalResolution>720</VerticalResolution>
+ </Display>
+ <OOBE>
+ <HideEULAPage>true</HideEULAPage>
+ <HideLocalAccountScreen>true</HideLocalAccountScreen>
+ <HideOEMRegistrationScreen>true</HideOEMRegistrationScreen>
+ <HideOnlineAccountScreens>true</HideOnlineAccountScreens>
+ <HideWirelessSetupInOOBE>true</HideWirelessSetupInOOBE>
+ <NetworkLocation>Home</NetworkLocation>
+ <ProtectYourPC>3</ProtectYourPC>
+ <SkipUserOOBE>true</SkipUserOOBE>
+ <SkipMachineOOBE>true</SkipMachineOOBE>
+ </OOBE>
+ <FirstLogonCommands>
+ <SynchronousCommand wcm:action="add">
+ <Order>1</Order>
+ <CommandLine>cmd /C POWERCFG -H OFF</CommandLine>
+ <Description>Disable Hibernation</Description>
+ </SynchronousCommand>
+ <SynchronousCommand wcm:action="add">
+ <Order>2</Order>
+ <CommandLine>cmd /C POWERCFG -X -monitor-timeout-ac 0</CommandLine>
+ <Description>Disable monitor blanking</Description>
+ </SynchronousCommand>
+ <SynchronousCommand wcm:action="add">
+ <Order>3</Order>
+ <CommandLine>cmd /C POWERCFG -X -standby-timeout-ac 0</CommandLine>
+ <Description>Disable Sleep</Description>
+ </SynchronousCommand>
+ <SynchronousCommand wcm:action="add">
+ <Order>4</Order>
+ <CommandLine>reg.exe add "HKLM\\SOFTWARE\\Policies\\Microsoft\\Windows\\WindowsUpdate\\AU" /v "NoAutoUpdate" /t REG_DWORD /d 1 /f</CommandLine>
+ <Description>Disable Windows Update</Description>
+ </SynchronousCommand>
+ <SynchronousCommand wcm:action="add">
+ <Order>5</Order>
+ <CommandLine>powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "foreach ($d in [System.IO.DriveInfo]::GetDrives()) {{ $f = Join-Path $d.Name 'setup-cua-server.ps1'; if (Test-Path $f) {{ &amp; $f; break }} }}"</CommandLine>
+ <Description>Install CUA Computer Server</Description>
+ </SynchronousCommand>
+ </FirstLogonCommands>
+ </component>
+ </settings>
+</unattend>"""
+
+
+def create_unattend_iso(
+ work_dir: Path,
+ product_key: Optional[str] = None,
+ *,
+ include_virtio_drivers: bool = True,
+ include_startup_nsh: bool = True,
+) -> Path:
+ """Create a small data-only ISO containing Autounattend.xml + setup script.
+
+ Args:
+ include_virtio_drivers: Include VirtIO driver paths (QEMU needs them, Hyper-V doesn't).
+ include_startup_nsh: Include UEFI shell startup.nsh (QEMU/OVMF needs it, Hyper-V doesn't).
+ """
+ unattend_iso = work_dir / "unattend.iso"
+ if unattend_iso.exists():
+ logger.info(f"Using cached unattend ISO: {unattend_iso}")
+ return unattend_iso
+
+ xml = generate_autounattend_xml(product_key, include_virtio_drivers=include_virtio_drivers)
+ xml_path = work_dir / "Autounattend.xml"
+ xml_path.write_text(xml, encoding="utf-8")
+
+ from cua_sandbox.builder.build import SETUP_COMPUTER_SERVER_PS1
+ setup_path = work_dir / "setup-cua-server.ps1"
+ setup_path.write_text(SETUP_COMPUTER_SERVER_PS1, encoding="utf-8")
+
+ iso_src = work_dir / "unattend-iso"
+ iso_src.mkdir(parents=True, exist_ok=True)
+ shutil.copy2(xml_path, iso_src / "Autounattend.xml")
+ shutil.copy2(setup_path, iso_src / "setup-cua-server.ps1")
+
+ if include_startup_nsh:
+ startup_nsh = work_dir / "startup.nsh"
+ startup_nsh.write_text("FS0:\\EFI\\BOOT\\BOOTX64.EFI\n", encoding="utf-8")
+ shutil.copy2(startup_nsh, iso_src / "startup.nsh")
+
+ _create_data_iso(iso_src, unattend_iso, "OEMDRV")
+ logger.info(f"Created unattend ISO: {unattend_iso}")
+ return unattend_iso
+
+
+def _create_data_iso(src_dir: Path, dest_iso: Path, label: str = "OEMDRV") -> None:
+ """Create a data-only ISO using pycdlib (pure Python, cross-platform)."""
+ import pycdlib
+
+ iso = pycdlib.PyCdlib()
+ iso.new(joliet=3, vol_ident=label)
+
+ for f in src_dir.iterdir():
+ if not f.is_file():
+ continue
+ iso_name = f.name.upper().replace("-", "_")
+ if "." in iso_name:
+ base, ext = iso_name.rsplit(".", 1)
+ iso9660_name = f"/{base[:8]}.{ext[:3]};1"
+ else:
+ iso9660_name = f"/{iso_name[:8]}.;1"
+ iso.add_file(
+ str(f),
+ iso_path=iso9660_name,
+ joliet_path=f"/{f.name}",
+ )
+
+ iso.write(str(dest_iso))
+ iso.close()
diff --git a/libs/python/cua-sandbox/cua_sandbox/image.py b/libs/python/cua-sandbox/cua_sandbox/image.py
new file mode 100644
index 0000000000..5b266d861d
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/image.py
@@ -0,0 +1,421 @@
+"""Image builder — pure-data immutable chained builder for sandbox images.
+
+Supports Linux, macOS, and Windows constructors. Serializes to a spec dict
+for cloud API or cloud-init consumption.
+
+Usage::
+
+ from cua_sandbox import Image
+
+ img = (
+ Image.linux("ubuntu", "24.04")
+ .apt_install("curl", "git", "build-essential")
+ .pip_install("numpy", "pandas")
+ .env(MY_VAR="hello")
+ .run("echo 'setup complete'")
+ .expose(8080)
+ )
+
+ spec = img.to_dict()
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+_IMAGE_CACHE = Path.home() / ".cua" / "cua-sandbox" / "image-cache"
+
+
+def _download_image(url: str) -> str:
+ """Download an image URL to the local cache, extract if zipped.
+
+ Returns the path to the final disk image (qcow2, img, etc.).
+ Skips download if the file already exists in the cache.
+ """
+ import hashlib
+ import urllib.request
+
+ _IMAGE_CACHE.mkdir(parents=True, exist_ok=True)
+
+ # Determine filename from URL
+ url_filename = url.rsplit("/", 1)[-1].split("?")[0]
+ # Use hash prefix to avoid collisions
+ url_hash = hashlib.sha256(url.encode()).hexdigest()[:12]
+ download_path = _IMAGE_CACHE / f"{url_hash}_{url_filename}"
+
+ # Check if we already have the extracted result
+ if download_path.suffix.lower() == ".zip":
+ # Look for an already-extracted disk image
+ extracted = _find_disk_image(_IMAGE_CACHE / url_hash)
+ if extracted:
+ logger.info(f"Using cached image: {extracted}")
+ return str(extracted)
+
+ if not download_path.exists():
+ logger.info(f"Downloading {url} → {download_path}")
+ urllib.request.urlretrieve(url, str(download_path))
+ logger.info(f"Download complete: {download_path}")
+
+ # Extract zip files
+ if download_path.suffix.lower() == ".zip":
+ import zipfile
+
+ extract_dir = _IMAGE_CACHE / url_hash
+ extract_dir.mkdir(parents=True, exist_ok=True)
+ logger.info(f"Extracting {download_path} → {extract_dir}")
+ with zipfile.ZipFile(download_path) as zf:
+ zf.extractall(extract_dir)
+ # Find the disk image inside
+ disk = _find_disk_image(extract_dir)
+ if not disk:
+ raise FileNotFoundError(
+ f"No disk image found in {download_path}. "
+ f"Contents: {[f.name for f in extract_dir.rglob('*') if f.is_file()]}"
+ )
+ logger.info(f"Extracted disk image: {disk}")
+ return str(disk)
+
+ return str(download_path)
+
+
+def _find_disk_image(directory: Path) -> Optional[Path]:
+ """Find a disk image file in a directory."""
+ for ext in (".qcow2", ".img", ".raw", ".vhdx", ".vmdk"):
+ for f in directory.rglob(f"*{ext}"):
+ return f
+ return None
+
+
+_INSTALL_OS_MAP: Dict[str, Tuple[str, ...]] = {
+ "apt_install": ("linux",),
+ "brew_install": ("macos",),
+ "choco_install": ("windows",),
+ "winget_install": ("windows",),
+ "apk_install": ("android",),
+ "pwa_install": ("android",),
+}
+
+
+@dataclass(frozen=True)
+class Image:
+ """Immutable, chainable image specification.
+
+ Each mutation method returns a new Image instance so that builders
+ can be forked at any point.
+ """
+
+ os_type: str # "linux" | "macos" | "windows" | "android"
+ distro: str # e.g. "ubuntu", "macos", "windows"
+ version: str # e.g. "24.04", "15", "11"
+ kind: Optional[str] = None # "container" | "vm" | None (resolved after registry pull)
+ _layers: Tuple[Dict[str, Any], ...] = ()
+ _env: Tuple[Tuple[str, str], ...] = ()
+ _ports: Tuple[int, ...] = ()
+ _files: Tuple[Tuple[str, str], ...] = () # (src, dst)
+ _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
+
+ # ── Constructors ─────────────────────────────────────────────────────
+
+ @classmethod
+ def linux(
+ cls, distro: str = "ubuntu", version: str = "24.04", kind: str = "container"
+ ) -> Image:
+ """Linux image. Defaults to 'container' (Docker/XFCE). Use kind='vm' for QEMU."""
+ return cls(os_type="linux", distro=distro, version=version, kind=kind)
+
+ @classmethod
+ def macos(cls, version: str = "26", kind: str = "vm") -> Image:
+ """macOS image. Always a VM (Apple Virtualization / Lume).
+
+ Supported versions: ``"15"`` / ``"sequoia"``, ``"26"`` / ``"tahoe"``.
+ """
+ from cua_sandbox.runtime.images import MACOS_VERSION_IMAGES
+
+ if version not in MACOS_VERSION_IMAGES:
+ supported = ", ".join(f'"{v}"' for v in MACOS_VERSION_IMAGES)
+ raise ValueError(f"Unsupported macOS version {version!r}. Supported: {supported}")
+ return cls(os_type="macos", distro="macos", version=version, kind=kind)
+
+ @classmethod
+ def windows(cls, version: str = "11", kind: str = "vm") -> Image:
+ """Windows image. Always a VM (QEMU or Hyper-V)."""
+ return cls(os_type="windows", distro="windows", version=version, kind=kind)
+
+ @classmethod
+ def android(cls, version: str = "14", kind: str = "vm") -> Image:
+ """Android image. Always a VM (QEMU emulator)."""
+ return cls(os_type="android", distro="android", version=version, kind=kind)
+
+ @classmethod
+ def from_registry(cls, ref: str) -> Image:
+ """Create an image from a registry reference. kind is resolved after pull."""
+ return cls(os_type="linux", distro="registry", version="latest", kind=None, _registry=ref)
+
+ @classmethod
+ def from_file(
+ cls,
+ path: str,
+ *,
+ os_type: str = "windows",
+ kind: str = "vm",
+ agent_type: Optional[str] = None,
+ ) -> Image:
+ """Create an image from a local disk, ISO file, or URL.
+
+ Supported formats: qcow2, vhdx, raw, img, iso.
+ URLs (http/https) are downloaded automatically. Zip files are extracted.
+ For ISOs, the runtime will create a qcow2 disk and attach the ISO
+ as a CD-ROM for installation/boot.
+
+ Args:
+ path: Local file path or URL (http/https).
+ os_type: OS type hint ("linux", "windows", "macos", "android").
+ kind: "vm" or "container".
+ agent_type: Agent type hint (e.g. "osworld" for OSWorld Flask server).
+ """
+ if path.startswith(("http://", "https://")):
+ path = _download_image(path)
+ return cls(
+ os_type=os_type,
+ distro="local",
+ version="local",
+ kind=kind,
+ _disk_path=path,
+ _agent_type=agent_type,
+ )
+
+ @classmethod
+ def from_dict(cls, data: Dict[str, Any]) -> Image:
+ """Reconstruct an Image from a serialized spec dict."""
+ img = cls(
+ os_type=data["os_type"],
+ distro=data["distro"],
+ version=data["version"],
+ kind=data.get("kind"),
+ _registry=data.get("registry"),
+ )
+ # Replay layers
+ for layer in data.get("layers", []):
+ img = img._add_layer(layer)
+ for k, v in data.get("env", {}).items():
+ img = img.env(**{k: v})
+ for p in data.get("ports", []):
+ img = img.expose(p)
+ for src, dst in data.get("files", []):
+ img = img.copy(src, dst)
+ return img
+
+ def _check_os(self, layer_type: str) -> None:
+ """Raise ValueError if this install method is incompatible with os_type."""
+ allowed = _INSTALL_OS_MAP.get(layer_type)
+ if allowed and self.os_type not in allowed:
+ raise ValueError(
+ f"{layer_type} is not supported on {self.os_type!r} images. "
+ f"Supported OS types: {', '.join(allowed)}"
+ )
+
+ # ── Chainable mutations (return new Image) ───────────────────────────
+
+ def _add_layer(self, layer: Dict[str, Any]) -> Image:
+ return Image(
+ os_type=self.os_type,
+ distro=self.distro,
+ version=self.version,
+ kind=self.kind,
+ _layers=self._layers + (layer,),
+ _env=self._env,
+ _ports=self._ports,
+ _files=self._files,
+ _registry=self._registry,
+ _disk_path=self._disk_path,
+ _agent_type=self._agent_type,
+ )
+
+ def _with(self, **kwargs) -> Image:
+ """Return a new Image with specific fields overridden."""
+ fields = {
+ "os_type": self.os_type,
+ "distro": self.distro,
+ "version": self.version,
+ "kind": self.kind,
+ "_layers": self._layers,
+ "_env": self._env,
+ "_ports": self._ports,
+ "_files": self._files,
+ "_registry": self._registry,
+ "_disk_path": self._disk_path,
+ "_agent_type": self._agent_type,
+ }
+ fields.update(kwargs)
+ return Image(**fields)
+
+ def apt_install(self, *packages: str) -> Image:
+ """Install packages via apt (Linux only)."""
+ self._check_os("apt_install")
+ return self._add_layer({"type": "apt_install", "packages": list(packages)})
+
+ def brew_install(self, *packages: str) -> Image:
+ """Install packages via Homebrew (macOS)."""
+ self._check_os("brew_install")
+ return self._add_layer({"type": "brew_install", "packages": list(packages)})
+
+ def choco_install(self, *packages: str) -> Image:
+ """Install packages via Chocolatey (Windows)."""
+ self._check_os("choco_install")
+ return self._add_layer({"type": "choco_install", "packages": list(packages)})
+
+ def winget_install(self, *packages: str) -> Image:
+ """Install packages via winget (Windows)."""
+ self._check_os("winget_install")
+ return self._add_layer({"type": "winget_install", "packages": list(packages)})
+
+ def apk_install(self, *apk_paths: str) -> Image:
+ """Install APK files via adb (Android only)."""
+ self._check_os("apk_install")
+ return self._add_layer({"type": "apk_install", "packages": list(apk_paths)})
+
+ def pwa_install(
+ self,
+ manifest_url: str,
+ package_name: Optional[str] = None,
+ keystore: Optional[str] = None,
+ keystore_alias: str = "android",
+ keystore_password: str = "android",
+ ) -> "Image":
+ """Build an APK from a PWA manifest URL via Bubblewrap and install it (Android only).
+
+ Bubblewrap reads the Web App Manifest at *manifest_url*, generates a
+ Trusted Web Activity (TWA) APK signed with *keystore*, and installs it
+ via adb. The keystore's SHA-256 fingerprint must match what the server
+ serves from ``/.well-known/assetlinks.json`` so Chrome trusts the TWA
+ and skips the browser UI entirely.
+
+ Args:
+ manifest_url: Full URL to the PWA's ``manifest.json``.
+ Example: ``"http://10.0.2.2:3000/manifest.json"``
+ package_name: Android package ID. Defaults to a reversed-hostname
+ derivation (e.g. ``"com.example.app"``).
+ keystore: Path to a ``*.keystore`` / ``*.jks`` file. When
+ omitted a fresh keystore is generated and cached under
+ ``~/.cua/cua-sandbox/pwa-cache/``. Pass the keystore
+ bundled with your PWA repo so the fingerprint is
+ deterministic and pre-loaded into ``assetlinks.json``.
+ keystore_alias: Key alias inside the keystore (default ``"android"``).
+ keystore_password: Password for both the store and the key
+ (default ``"android"``).
+ """
+ self._check_os("pwa_install")
+ layer: dict = {"type": "pwa_install", "manifest_url": manifest_url}
+ if package_name:
+ layer["package_name"] = package_name
+ if keystore:
+ layer["keystore"] = keystore
+ layer["keystore_alias"] = keystore_alias
+ layer["keystore_password"] = keystore_password
+ return self._add_layer(layer)
+
+ def uv_install(self, *packages: str) -> Image:
+ """Install Python packages via uv add into the cua-server project."""
+ return self._add_layer({"type": "uv_install", "packages": list(packages)})
+
+ def pip_install(self, *packages: str) -> Image:
+ """Install Python packages via pip."""
+ return self._add_layer({"type": "pip_install", "packages": list(packages)})
+
+ def run(self, command: str) -> Image:
+ """Run a shell command during image build."""
+ return self._add_layer({"type": "run", "command": command})
+
+ def env(self, **variables: str) -> Image:
+ """Set environment variables."""
+ new_env = self._env + tuple(variables.items())
+ return self._with(_env=new_env)
+
+ def copy(self, src: str, dst: str) -> Image:
+ """Copy a file into the image."""
+ new_files = self._files + ((src, dst),)
+ return self._with(_files=new_files)
+
+ def expose(self, port: int) -> Image:
+ """Expose a port."""
+ new_ports = self._ports + (port,)
+ return self._with(_ports=new_ports)
+
+ # ── Serialization ────────────────────────────────────────────────────
+
+ def to_dict(self) -> Dict[str, Any]:
+ """Serialize to a plain dict suitable for JSON or cloud API."""
+ d: Dict[str, Any] = {
+ "os_type": self.os_type,
+ "distro": self.distro,
+ "version": self.version,
+ "kind": self.kind,
+ "layers": list(self._layers),
+ }
+ if self._env:
+ d["env"] = dict(self._env)
+ if self._ports:
+ d["ports"] = list(self._ports)
+ if self._files:
+ d["files"] = [list(f) for f in self._files]
+ if self._registry:
+ d["registry"] = self._registry
+ return d
+
+ def to_cloud_init(self) -> str:
+ """Generate a cloud-init user-data script from the image layers."""
+ lines = ["#!/bin/bash", "set -e"]
+ for k, v in self._env:
+ lines.append(f"export {k}={v!r}")
+ for layer in self._layers:
+ lt = layer["type"]
+ if lt == "apt_install":
+ pkgs = " ".join(layer["packages"])
+ lines.append(f"apt-get update && apt-get install -y {pkgs}")
+ elif lt == "brew_install":
+ pkgs = " ".join(layer["packages"])
+ lines.append(f"brew install {pkgs}")
+ elif lt == "winget_install":
+ for pkg in layer["packages"]:
+ lines.append(
+ f"winget install --accept-source-agreements --accept-package-agreements -e --id {pkg}"
+ )
+ elif lt == "uv_install":
+ pkgs = " ".join(layer["packages"])
+ lines.append(f"uv add --directory ~/cua-server {pkgs}")
+ elif lt == "choco_install":
+ pkgs = " ".join(layer["packages"])
+ lines.append(f"choco install -y {pkgs}")
+ elif lt == "pip_install":
+ pkgs = " ".join(layer["packages"])
+ lines.append(f"pip install {pkgs}")
+ elif lt == "apk_install":
+ for apk in layer["packages"]:
+ lines.append(f"adb install {apk}")
+ elif lt == "pwa_install":
+ manifest_url = layer["manifest_url"]
+ lines.append(
+ # Install bubblewrap CLI (once), init a TWA project from the
+ # manifest URL, build a debug APK, then install it via adb.
+ f"npm install -g @bubblewrap/cli 2>/dev/null || true\n"
+ f"_BWW_DIR=$(mktemp -d)\n"
+ f"(cd \"$_BWW_DIR\" && bubblewrap init --manifest '{manifest_url}' --directory . --skipPwaValidation && bubblewrap build --skipSigning)\n"
+ f'adb install "$_BWW_DIR/app-release-unsigned.apk"'
+ )
+ elif lt == "run":
+ lines.append(layer["command"])
+ return "\n".join(lines) + "\n"
+
+ def __repr__(self) -> str:
+ reg = f", registry={self._registry!r}" if self._registry else ""
+ return (
+ f"Image({self.os_type}/{self.distro}:{self.version}, "
+ f"kind={self.kind}, {len(self._layers)} layers{reg})"
+ )
diff --git a/libs/python/cua-sandbox/cua_sandbox/interfaces/__init__.py b/libs/python/cua-sandbox/cua_sandbox/interfaces/__init__.py
new file mode 100644
index 0000000000..7f1d2e0ac9
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/interfaces/__init__.py
@@ -0,0 +1,22 @@
+from cua_sandbox.interfaces.clipboard import Clipboard
+from cua_sandbox.interfaces.keyboard import Keyboard
+from cua_sandbox.interfaces.mobile import Mobile
+from cua_sandbox.interfaces.mouse import Mouse
+from cua_sandbox.interfaces.screen import Screen
+from cua_sandbox.interfaces.shell import Shell
+from cua_sandbox.interfaces.terminal import Terminal
+from cua_sandbox.interfaces.tunnel import Tunnel, TunnelInfo
+from cua_sandbox.interfaces.window import Window
+
+__all__ = [
+ "Clipboard",
+ "Keyboard",
+ "Mobile",
+ "Mouse",
+ "Screen",
+ "Shell",
+ "Terminal",
+ "Tunnel",
+ "TunnelInfo",
+ "Window",
+]
diff --git a/libs/python/cua-sandbox/cua_sandbox/interfaces/clipboard.py b/libs/python/cua-sandbox/cua_sandbox/interfaces/clipboard.py
new file mode 100644
index 0000000000..8e1a6052e7
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/interfaces/clipboard.py
@@ -0,0 +1,20 @@
+"""Clipboard interface, backed by a Transport."""
+
+from __future__ import annotations
+
+from cua_sandbox.transport.base import Transport
+
+
+class Clipboard:
+ """Clipboard read/write."""
+
+ def __init__(self, transport: Transport):
+ self._t = transport
+
+ async def get(self) -> str:
+ """Return the current clipboard text."""
+ return await self._t.send("copy_to_clipboard")
+
+ async def set(self, text: str) -> None:
+ """Set the clipboard text."""
+ await self._t.send("set_clipboard", text=text)
diff --git a/libs/python/cua-sandbox/cua_sandbox/interfaces/keyboard.py b/libs/python/cua-sandbox/cua_sandbox/interfaces/keyboard.py
new file mode 100644
index 0000000000..70c4957ad7
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/interfaces/keyboard.py
@@ -0,0 +1,30 @@
+"""Keyboard interface — type text and press keys, backed by a Transport."""
+
+from __future__ import annotations
+
+from typing import List, Union
+
+from cua_sandbox.transport.base import Transport
+
+
+class Keyboard:
+ """Keyboard control."""
+
+ def __init__(self, transport: Transport):
+ self._t = transport
+
+ async def type(self, text: str) -> None:
+ """Type a string of text."""
+ await self._t.send("type_text", text=text)
+
+ async def keypress(self, keys: Union[List[str], str]) -> None:
+ """Press a key combination (e.g. ["ctrl", "c"] or "enter")."""
+ if isinstance(keys, str):
+ keys = [keys]
+ await self._t.send("hotkey", keys=keys)
+
+ async def key_down(self, key: str) -> None:
+ await self._t.send("key_down", key=key)
+
+ async def key_up(self, key: str) -> None:
+ await self._t.send("key_up", key=key)
diff --git a/libs/python/cua-sandbox/cua_sandbox/interfaces/mobile.py b/libs/python/cua-sandbox/cua_sandbox/interfaces/mobile.py
new file mode 100644
index 0000000000..208087a90f
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/interfaces/mobile.py
@@ -0,0 +1,191 @@
+"""Mobile interface — touch, gestures, and hardware keys via ADB, backed by a Transport."""
+
+from __future__ import annotations
+
+import asyncio
+
+from cua_sandbox.transport.base import Transport
+
+
+class Mobile:
+ """Mobile (Android) touch and hardware-key control.
+
+ 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.
+ """
+
+ def __init__(self, transport: Transport):
+ self._t = transport
+
+ async def _shell(self, command: str) -> None:
+ await self._t.send("shell", command=command)
+
+ # ── Touch ─────────────────────────────────────────────────────────────
+
+ async def tap(self, x: int, y: int) -> None:
+ await self._shell(f"input tap {x} {y}")
+
+ async def long_press(self, x: int, y: int, duration_ms: int = 1000) -> None:
+ await self._shell(f"input swipe {x} {y} {x} {y} {duration_ms}")
+
+ async def double_tap(self, x: int, y: int, delay: float = 0.1) -> None:
+ await self._shell(f"input tap {x} {y}")
+ await asyncio.sleep(delay)
+ await self._shell(f"input tap {x} {y}")
+
+ async def type_text(self, text: str) -> None:
+ encoded = text.replace(" ", "%s")
+ await self._shell(f"input text '{encoded}'")
+
+ # ── Gestures ──────────────────────────────────────────────────────────
+
+ async def swipe(self, x1: int, y1: int, x2: int, y2: int, duration_ms: int = 300) -> None:
+ await self._shell(f"input swipe {x1} {y1} {x2} {y2} {duration_ms}")
+
+ async def scroll_up(self, x: int, y: int, distance: int = 600, duration_ms: int = 400) -> None:
+ await self._shell(f"input swipe {x} {y + distance} {x} {y} {duration_ms}")
+
+ async def scroll_down(
+ self, x: int, y: int, distance: int = 600, duration_ms: int = 400
+ ) -> None:
+ await self._shell(f"input swipe {x} {y} {x} {y + distance} {duration_ms}")
+
+ async def scroll_left(
+ self, x: int, y: int, distance: int = 400, duration_ms: int = 300
+ ) -> None:
+ await self._shell(f"input swipe {x + distance} {y} {x} {y} {duration_ms}")
+
+ async def scroll_right(
+ self, x: int, y: int, distance: int = 400, duration_ms: int = 300
+ ) -> None:
+ await self._shell(f"input swipe {x} {y} {x + distance} {y} {duration_ms}")
+
+ async def fling(self, x1: int, y1: int, x2: int, y2: int) -> None:
+ await self.swipe(x1, y1, x2, y2, duration_ms=80)
+
+ async def _get_screen_size(self) -> tuple[int, int]:
+ """Return ``(width, height)`` in screen pixels via ``wm size``."""
+ result = await self._t.send("shell", command="wm size")
+ output = result.get("stdout", "").strip()
+ for line in output.splitlines():
+ if "size" in line.lower():
+ dims = line.split(":")[-1].strip()
+ w, h = dims.split("x")
+ return int(w), int(h)
+ return 32768, 32768 # fallback: 1:1 mapping
+
+ async def gesture(
+ self,
+ *finger_paths: tuple[int, int],
+ duration_ms: int = 400,
+ steps: int = 0,
+ ) -> None:
+ """Inject an arbitrary N-finger gesture via MT Protocol B ``sendevent``.
+
+ Each positional argument is a sequence of ``(x, y)`` waypoints for one
+ finger. Pass an even number of ``(x, y)`` tuples and they are paired
+ into start/end positions per finger::
+
+ # two-finger pinch-out
+ await mobile.gesture(
+ (cx - 20, cy), (cx - 200, cy), # finger 0
+ (cx + 20, cy), (cx + 200, cy), # finger 1
+ )
+
+ Delegates to the ``multitouch_gesture`` transport action, which uses
+ ``adb root`` + MT Protocol B ``sendevent`` for reliable injection on
+ both local ADB and cloud HTTP transports.
+
+ Args:
+ *finger_paths: Alternating start/end ``(x, y)`` tuples, two per finger.
+ Must have an even length >= 4 (at least 2 fingers × 2 points).
+ duration_ms: Total gesture duration in milliseconds.
+ steps: Interpolation steps (0 = auto: duration_ms // 20, min 5).
+ """
+ if len(finger_paths) < 4 or len(finger_paths) % 2 != 0:
+ raise ValueError(
+ "gesture() requires an even number of (x, y) tuples, two per finger "
+ f"(start + end). Got {len(finger_paths)} tuples."
+ )
+
+ # Pair waypoints into per-finger (start, end) tuples
+ fingers_pairs: list[tuple[tuple[int, int], tuple[int, int]]] = []
+ for i in range(0, len(finger_paths), 2):
+ fingers_pairs.append((finger_paths[i], finger_paths[i + 1]))
+
+ sw, sh = await self._get_screen_size()
+ n_steps = steps if steps > 0 else max(5, duration_ms // 20)
+
+ # Structured params for the server-side multitouch_gesture action
+ fingers_payload = [{"start": list(start), "end": list(end)} for start, end in fingers_pairs]
+ await self._t.send(
+ "multitouch_gesture",
+ fingers=fingers_payload,
+ screen_w=sw,
+ screen_h=sh,
+ duration_ms=duration_ms,
+ steps=n_steps,
+ )
+
+ async def pinch_in(self, cx: int, cy: int, spread: int = 300, duration_ms: int = 400) -> None:
+ """Pinch-in (zoom out) with two real simultaneous fingers."""
+ await self.gesture(
+ (cx - spread, cy),
+ (cx - 20, cy),
+ (cx + spread, cy),
+ (cx + 20, cy),
+ duration_ms=duration_ms,
+ )
+
+ async def pinch_out(self, cx: int, cy: int, spread: int = 300, duration_ms: int = 400) -> None:
+ """Pinch-out (zoom in) with two real simultaneous fingers."""
+ await self.gesture(
+ (cx - 20, cy),
+ (cx - spread, cy),
+ (cx + 20, cy),
+ (cx + spread, cy),
+ duration_ms=duration_ms,
+ )
+
+ # ── Hardware keys ─────────────────────────────────────────────────────
+
+ async def key(self, keycode: int) -> None:
+ await self._shell(f"input keyevent {keycode}")
+
+ async def home(self) -> None:
+ await self.key(3)
+
+ async def back(self) -> None:
+ await self.key(4)
+
+ async def recents(self) -> None:
+ await self.key(187)
+
+ async def power(self) -> None:
+ await self.key(26)
+
+ async def volume_up(self) -> None:
+ await self.key(24)
+
+ async def volume_down(self) -> None:
+ await self.key(25)
+
+ async def enter(self) -> None:
+ await self.key(66)
+
+ async def backspace(self) -> None:
+ await self.key(67)
+
+ # ── System ────────────────────────────────────────────────────────────
+
+ async def wake(self) -> None:
+ await self.key(224)
+
+ async def notifications(self) -> None:
+ await self._shell("service call statusbar 1")
+
+ async def close_notifications(self) -> None:
+ await self._shell("service call statusbar 2")
diff --git a/libs/python/cua-sandbox/cua_sandbox/interfaces/mouse.py b/libs/python/cua-sandbox/cua_sandbox/interfaces/mouse.py
new file mode 100644
index 0000000000..3835c51478
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/interfaces/mouse.py
@@ -0,0 +1,42 @@
+"""Mouse interface — click, move, drag, scroll, backed by a Transport."""
+
+from __future__ import annotations
+
+from typing import Dict, List
+
+from cua_sandbox.transport.base import Transport
+
+
+class Mouse:
+ """Mouse control."""
+
+ def __init__(self, transport: Transport):
+ self._t = transport
+
+ async def click(self, x: int, y: int, button: str = "left") -> None:
+ await self._t.send("left_click", x=x, y=y, button=button)
+
+ async def right_click(self, x: int, y: int) -> None:
+ await self._t.send("right_click", x=x, y=y)
+
+ async def double_click(self, x: int, y: int) -> None:
+ await self._t.send("double_click", x=x, y=y)
+
+ async def move(self, x: int, y: int) -> None:
+ await self._t.send("move_cursor", x=x, y=y)
+
+ async def scroll(self, x: int, y: int, scroll_x: int = 0, scroll_y: int = 3) -> None:
+ await self._t.send("scroll", x=x, y=y, scroll_x=scroll_x, scroll_y=scroll_y)
+
+ async def mouse_down(self, x: int, y: int, button: str = "left") -> None:
+ await self._t.send("mouse_down", x=x, y=y, button=button)
+
+ async def mouse_up(self, x: int, y: int, button: str = "left") -> None:
+ await self._t.send("mouse_up", x=x, y=y, button=button)
+
+ async def drag(
+ 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
+ )
diff --git a/libs/python/cua-sandbox/cua_sandbox/interfaces/screen.py b/libs/python/cua-sandbox/cua_sandbox/interfaces/screen.py
new file mode 100644
index 0000000000..b7e33d8a50
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/interfaces/screen.py
@@ -0,0 +1,34 @@
+"""Screen interface — screenshots and screen info, backed by a Transport."""
+
+from __future__ import annotations
+
+import base64
+from typing import Tuple
+
+from cua_sandbox.transport.base import Transport
+
+
+class Screen:
+ """Screen capture and info."""
+
+ def __init__(self, transport: Transport):
+ self._t = transport
+
+ async def screenshot(self, format: str = "png", quality: int = 95) -> bytes:
+ """Capture a screenshot and return raw image bytes.
+
+ Args:
+ format: "png" (lossless, default) or "jpeg" (lossy, ~5-10x smaller).
+ quality: JPEG quality 1-95, ignored for PNG.
+ """
+ return await self._t.screenshot(format=format, quality=quality)
+
+ async def screenshot_base64(self, format: str = "png", quality: int = 95) -> str:
+ """Capture a screenshot and return as a base64-encoded string."""
+ raw = await self._t.screenshot(format=format, quality=quality)
+ return base64.b64encode(raw).decode("ascii")
+
+ async def size(self) -> Tuple[int, int]:
+ """Return (width, height) of the screen."""
+ d = await self._t.get_screen_size()
+ return d["width"], d["height"]
diff --git a/libs/python/cua-sandbox/cua_sandbox/interfaces/shell.py b/libs/python/cua-sandbox/cua_sandbox/interfaces/shell.py
new file mode 100644
index 0000000000..37c7c0f955
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/interfaces/shell.py
@@ -0,0 +1,43 @@
+"""Shell interface — run commands, backed by a Transport."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from cua_sandbox.transport.base import Transport
+
+
+@dataclass
+class CommandResult:
+ stdout: str
+ stderr: str
+ returncode: int
+
+ @property
+ def success(self) -> bool:
+ return self.returncode == 0
+
+
+class Shell:
+ """Shell command execution."""
+
+ def __init__(self, transport: Transport):
+ self._t = transport
+
+ async def run(self, command: str, timeout: int = 30) -> CommandResult:
+ """Run a shell command and return the result."""
+ result = await self._t.send("run_command", command=command, timeout=timeout)
+ if isinstance(result, dict):
+ rc = result.get("returncode", result.get("return_code", -1))
+ return CommandResult(
+ stdout=result.get("stdout", ""),
+ stderr=result.get("stderr", ""),
+ returncode=rc if rc is not None else 0,
+ )
+ # LocalTransport returns cua_auto.shell.CommandResult directly
+ return CommandResult(
+ stdout=getattr(result, "stdout", ""),
+ stderr=getattr(result, "stderr", ""),
+ returncode=getattr(result, "returncode", -1),
+ )
diff --git a/libs/python/cua-sandbox/cua_sandbox/interfaces/terminal.py b/libs/python/cua-sandbox/cua_sandbox/interfaces/terminal.py
new file mode 100644
index 0000000000..44d1436f0c
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/interfaces/terminal.py
@@ -0,0 +1,30 @@
+"""Terminal (PTY) interface, backed by a Transport."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from cua_sandbox.transport.base import Transport
+
+
+class Terminal:
+ """PTY terminal sessions."""
+
+ def __init__(self, transport: Transport):
+ self._t = transport
+
+ async def create(self, shell: str = "bash", cols: int = 80, rows: int = 24) -> dict:
+ """Create a new PTY session. Returns {"pid": int, "cols": int, "rows": int}."""
+ return await self._t.send("terminal_create", shell=shell, cols=cols, rows=rows)
+
+ async def send_input(self, pid: int, data: str) -> None:
+ """Send input to a PTY session."""
+ await self._t.send("terminal_send", pid=pid, data=data)
+
+ async def resize(self, pid: int, cols: int, rows: int) -> None:
+ """Resize a PTY session."""
+ await self._t.send("terminal_resize", pid=pid, cols=cols, rows=rows)
+
+ async def close(self, pid: int) -> Optional[int]:
+ """Close a PTY session. Returns exit code."""
+ return await self._t.send("terminal_close", pid=pid)
diff --git a/libs/python/cua-sandbox/cua_sandbox/interfaces/tunnel.py b/libs/python/cua-sandbox/cua_sandbox/interfaces/tunnel.py
new file mode 100644
index 0000000000..7d7f27a136
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/interfaces/tunnel.py
@@ -0,0 +1,115 @@
+"""Tunnel interface — forward a port from the sandbox to the host.
+
+Usage::
+
+ # Async context manager (port released on exit)
+ async with sb.tunnel.forward(9222) as t:
+ print(t.url) # "http://localhost:49823"
+ print(t.host, t.port) # "localhost", 49823
+
+ # Plain await (caller must call .close())
+ t = await sb.tunnel.forward(9222)
+ await t.close()
+
+ # Multiple ports — returns dict[sandbox_port, TunnelInfo]
+ async with sb.tunnel.forward(9222, 8080) as tunnels:
+ devtools = tunnels[9222].url
+ app = tunnels[8080].url
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Dict, List, Optional, Union
+
+from cua_sandbox.transport.base import Transport
+
+
+class TunnelInfo:
+ """A single forwarded port."""
+
+ def __init__(self, host: str, port: int, sandbox_port: int) -> None:
+ self.host = host
+ self.port = port # host-side port
+ self.sandbox_port = sandbox_port # original port inside sandbox
+ self._closer: Optional[object] = None # Callable[[TunnelInfo], Coroutine]
+
+ @property
+ def url(self) -> str:
+ return f"http://{self.host}:{self.port}"
+
+ async def close(self) -> None:
+ """Close this tunnel (no-op if already closed or inside a context manager)."""
+ if self._closer is not None:
+ await self._closer(self) # type: ignore[operator]
+ self._closer = None
+
+ def __repr__(self) -> str:
+ return f"TunnelInfo(host={self.host!r}, port={self.port}, sandbox_port={self.sandbox_port})"
+
+
+class _TunnelContext:
+ """Returned by Tunnel.forward() — supports both await and async with."""
+
+ def __init__(self, transport: Transport, ports: tuple[int | str, ...]):
+ self._t = transport
+ self._ports = ports
+ self._infos: List[TunnelInfo] = []
+
+ # ── awaitable ─────────────────────────────────────────────────────────────
+
+ def __await__(self):
+ return self._open().__await__()
+
+ async def _open(self) -> Union[TunnelInfo, Dict[int | str, TunnelInfo]]:
+ for p in self._ports:
+ info = await self._t.forward_tunnel(p)
+ info._closer = self._close_one
+ self._infos.append(info)
+ return self._result()
+
+ def _result(self) -> Union[TunnelInfo, Dict[int | str, TunnelInfo]]:
+ if len(self._infos) == 1:
+ return self._infos[0]
+ return {i.sandbox_port: i for i in self._infos}
+
+ # ── async context manager ─────────────────────────────────────────────────
+
+ async def __aenter__(self) -> Union[TunnelInfo, Dict[int, TunnelInfo]]:
+ return await self._open()
+
+ async def __aexit__(self, *_) -> None:
+ await asyncio.gather(*(self._t.close_tunnel(i) for i in self._infos))
+ self._infos.clear()
+
+ async def _close_one(self, info: TunnelInfo) -> None:
+ await self._t.close_tunnel(info)
+ self._infos = [i for i in self._infos if i is not info]
+
+
+class Tunnel:
+ """Port-forwarding interface — exposes sandbox ports on the host."""
+
+ def __init__(self, transport: Transport):
+ self._t = transport
+
+ def forward(self, *ports: int | str) -> _TunnelContext:
+ """Forward one or more sandbox ports (or abstract sockets) to the host.
+
+ *ports* may be:
+ - ``int`` — TCP port inside the sandbox (e.g. ``8080``)
+ - ``str`` — Android abstract socket name (e.g. ``"chrome_devtools_remote"``)
+
+ 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
+
+ Example — Chrome DevTools over ADB::
+
+ async with sb.tunnel.forward("chrome_devtools_remote") as t:
+ # http://localhost:<random>/json lists CDP targets
+ print(t.url)
+ """
+ if not ports:
+ raise ValueError("forward() requires at least one port or socket name")
+ return _TunnelContext(self._t, ports)
diff --git a/libs/python/cua-sandbox/cua_sandbox/interfaces/window.py b/libs/python/cua-sandbox/cua_sandbox/interfaces/window.py
new file mode 100644
index 0000000000..ca7700561b
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/interfaces/window.py
@@ -0,0 +1,16 @@
+"""Window interface, backed by a Transport."""
+
+from __future__ import annotations
+
+from cua_sandbox.transport.base import Transport
+
+
+class Window:
+ """Window management."""
+
+ def __init__(self, transport: Transport):
+ self._t = transport
+
+ async def get_active_title(self) -> str:
+ """Return the title of the currently focused window."""
+ return await self._t.send("get_active_window_title")
diff --git a/libs/python/cua-sandbox/cua_sandbox/localhost.py b/libs/python/cua-sandbox/cua_sandbox/localhost.py
new file mode 100644
index 0000000000..b30c89d3d1
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/localhost.py
@@ -0,0 +1,100 @@
+"""Localhost — wraps cua_auto directly. No sandbox, no computer-server.
+
+All cua_auto calls are sync; async wrappers use asyncio.to_thread().
+
+Usage::
+
+ from cua_sandbox import localhost
+
+ async with localhost() as host:
+ await host.mouse.click(100, 200)
+ img = await host.screen.screenshot()
+"""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from typing import AsyncIterator, Optional
+
+from cua_sandbox.interfaces import (
+ Clipboard,
+ Keyboard,
+ Mouse,
+ Screen,
+ Shell,
+ Terminal,
+ Window,
+)
+from cua_sandbox.sandbox import _ConnectResult
+from cua_sandbox.transport.local import LocalTransport
+
+
+class Localhost:
+ """Direct host control via cua_auto — no sandboxing."""
+
+ def __init__(self) -> None:
+ self._transport = LocalTransport()
+ self.screen = Screen(self._transport)
+ self.mouse = Mouse(self._transport)
+ self.keyboard = Keyboard(self._transport)
+ self.clipboard = Clipboard(self._transport)
+ self.shell = Shell(self._transport)
+ self.window = Window(self._transport)
+ self.terminal = Terminal(self._transport)
+
+ async def _connect(self) -> None:
+ await self._transport.connect()
+
+ async def disconnect(self) -> None:
+ await self._transport.disconnect()
+
+ async def screenshot(self, text: Optional[str] = None) -> bytes:
+ return await self._transport.screenshot()
+
+ async def screenshot_base64(self, text: Optional[str] = None) -> str:
+ return await self.screen.screenshot_base64()
+
+ async def get_environment(self) -> str:
+ return await self._transport.get_environment()
+
+ async def get_dimensions(self) -> tuple[int, int]:
+ return await self.screen.size()
+
+ @classmethod
+ def connect(cls) -> "_ConnectResult":
+ """Connect to the local machine.
+
+ Supports both ``await`` and ``async with``.
+
+ Examples::
+
+ # plain await
+ host = await Localhost.connect()
+ await host.shell.run("echo hello")
+ await host.disconnect()
+
+ # context manager
+ async with Localhost.connect() as host:
+ await host.shell.run("echo hello")
+ """
+
+ async def _factory() -> "Localhost":
+ host = cls()
+ await host._connect()
+ return host
+
+ return _ConnectResult(_factory)
+
+ def __repr__(self) -> str:
+ return "Localhost()"
+
+
+@asynccontextmanager
+async def localhost() -> AsyncIterator[Localhost]:
+ """Async context manager yielding a Localhost instance.
+
+ .. deprecated::
+ Prefer ``Localhost.connect()`` instead.
+ """
+ async with Localhost.connect() as host:
+ yield host
diff --git a/libs/python/cua-sandbox/cua_sandbox/registry/__init__.py b/libs/python/cua-sandbox/cua_sandbox/registry/__init__.py
new file mode 100644
index 0000000000..1f6ce615b8
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/registry/__init__.py
@@ -0,0 +1,19 @@
+from cua_sandbox.registry.manifest import get_manifest, detect_kind, detect_format, detect_os_from_config, ImageFormat
+from cua_sandbox.registry.resolve import resolve_image_kind, pull_image
+from cua_sandbox.registry.cache import ImageCache
+from cua_sandbox.registry.qemu_builder import QEMUImageConfig, push_image as push_qemu_image, pull_qemu_image, build_image as build_qemu_image
+
+__all__ = [
+ "get_manifest",
+ "detect_kind",
+ "detect_format",
+ "detect_os_from_config",
+ "ImageFormat",
+ "resolve_image_kind",
+ "pull_image",
+ "ImageCache",
+ "QEMUImageConfig",
+ "push_qemu_image",
+ "pull_qemu_image",
+ "build_qemu_image",
+]
diff --git a/libs/python/cua-sandbox/cua_sandbox/registry/cache.py b/libs/python/cua-sandbox/cua_sandbox/registry/cache.py
new file mode 100644
index 0000000000..98c9c1b00a
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/registry/cache.py
@@ -0,0 +1,59 @@
+"""Local image cache at ~/.cua/cua-sandbox/images/."""
+
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+from typing import Optional
+
+CACHE_ROOT = Path.home() / ".cua" / "cua-sandbox" / "images"
+
+
+class ImageCache:
+ """Manages locally cached VM/container images."""
+
+ def __init__(self, root: Optional[Path] = None):
+ self.root = root or CACHE_ROOT
+ self.root.mkdir(parents=True, exist_ok=True)
+
+ def image_dir(self, registry: str, org: str, name: str, tag: str) -> Path:
+ return self.root / registry / org / name / tag
+
+ def is_cached(self, registry: str, org: str, name: str, tag: str) -> bool:
+ return (self.image_dir(registry, org, name, tag) / "manifest.json").exists()
+
+ def save_manifest(self, registry: str, org: str, name: str, tag: str, manifest: dict) -> Path:
+ d = self.image_dir(registry, org, name, tag)
+ d.mkdir(parents=True, exist_ok=True)
+ p = d / "manifest.json"
+ p.write_text(json.dumps(manifest, indent=2))
+ return d
+
+ def get_manifest(self, registry: str, org: str, name: str, tag: str) -> Optional[dict]:
+ p = self.image_dir(registry, org, name, tag) / "manifest.json"
+ if p.exists():
+ return json.loads(p.read_text())
+ return None
+
+ def list_images(self) -> list[dict]:
+ images = []
+ for p in self.root.rglob("manifest.json"):
+ try:
+ parts = p.relative_to(self.root).parts
+ if len(parts) >= 4:
+ images.append({
+ "registry": parts[0], "org": parts[1],
+ "name": parts[2], "tag": parts[3],
+ "path": str(p.parent),
+ })
+ except Exception:
+ pass
+ return images
+
+ def remove(self, registry: str, org: str, name: str, tag: str) -> bool:
+ d = self.image_dir(registry, org, name, tag)
+ if d.exists():
+ shutil.rmtree(d)
+ return True
+ return False
diff --git a/libs/python/cua-sandbox/cua_sandbox/registry/manifest.py b/libs/python/cua-sandbox/cua_sandbox/registry/manifest.py
new file mode 100644
index 0000000000..88bb6614a9
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/registry/manifest.py
@@ -0,0 +1,270 @@
+"""Fetch and classify OCI manifests using oras-py.
+
+This is the single entry point for inspecting any OCI image — VM or container.
+All runtime/pull logic delegates here first to figure out what the image is.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Optional
+
+import oras.provider
+from cua_sandbox.registry.media_types import (
+ CONTAINER_CONFIG_TYPES,
+ CONTAINER_LAYER_TYPES,
+ LEGACY_DISK_CHUNK,
+ OCI_VM_CONFIG,
+ OCI_VM_CONFIG_LEGACY,
+ OCI_VM_DISK,
+ OCI_VM_DISK_LEGACY,
+ QEMU_CONFIG,
+ QEMU_DISK,
+ QEMU_DISK_GZIP,
+ TART_CONFIG,
+ TART_DISK,
+ VM_MEDIA_TYPES,
+)
+from cua_sandbox.registry.ref import parse_ref
+
+
+class ImageFormat(Enum):
+ """Format of a VM image in the registry."""
+
+ OCI_LAYERED = "oci-layered" # agoda media types, gzip chunks with part annotations
+ LEGACY_LZ4 = "legacy-lz4" # trycua LZ4-chunked
+ CHUNKED_PARTS = "chunked-parts" # standard OCI layer type with ;part.number= in media type
+ TART = "tart" # Cirrus Labs Tart VM disk chunks
+ QEMU = "qemu" # trycua QEMU qcow2 disk + config
+ CONTAINER = "container" # standard Docker/OCI container
+ UNKNOWN = "unknown"
+
+
+def get_manifest(ref: str, platform: Optional[str] = None) -> dict:
+ """Fetch the OCI manifest for an image reference.
+
+ If the manifest is a multi-arch index, resolves to the best platform match.
+
+ Args:
+ ref: Full or short image reference, e.g.
+ 'ghcr.io/trycua/macos-sequoia-cua-sparse:latest-oci-layered'
+ 'trycua/cua-xfce:latest'
+ platform: Platform filter e.g. "linux/amd64". Auto-detected if None.
+ """
+ import platform as _plat
+
+ r = oras.provider.Registry()
+ registry, org, name, tag = parse_ref(ref)
+ full = f"{registry}/{org}/{name}:{tag}"
+ manifest = r.get_manifest(full)
+
+ # If it's a manifest index, resolve to a specific platform manifest
+ if manifest.get("manifests"):
+ arch_map = {"x86_64": "amd64", "AMD64": "amd64", "aarch64": "arm64", "ARM64": "arm64"}
+ if platform:
+ want_os, want_arch = platform.split("/", 1)
+ else:
+ want_os = "linux"
+ machine = _plat.machine()
+ want_arch = arch_map.get(machine, machine.lower())
+
+ # Find best match
+ for m in manifest["manifests"]:
+ p = m.get("platform", {})
+ if p.get("os") == want_os and p.get("architecture") == want_arch:
+ # Skip attestation manifests
+ annot = m.get("annotations", {})
+ if "attestation" in annot.get("vnd.docker.reference.type", ""):
+ continue
+ digest = m["digest"]
+ full_repo = f"{registry}/{org}/{name}"
+ return r.get_manifest(f"{full_repo}@{digest}")
+
+ # Fallback: first non-attestation manifest
+ for m in manifest["manifests"]:
+ annot = m.get("annotations", {})
+ if "attestation" not in annot.get("vnd.docker.reference.type", ""):
+ digest = m["digest"]
+ full_repo = f"{registry}/{org}/{name}"
+ return r.get_manifest(f"{full_repo}@{digest}")
+
+ return manifest
+
+
+def detect_format(manifest: dict) -> ImageFormat:
+ """Determine the image format from a manifest dict."""
+ layers = manifest.get("layers", [])
+ config = manifest.get("config", {})
+ config_mt = config.get("mediaType", "")
+
+ # OCI-layered (lume/agoda): config or disk layers use trycua.lume or legacy agoda types
+ if config_mt in (OCI_VM_CONFIG, OCI_VM_CONFIG_LEGACY):
+ return ImageFormat.OCI_LAYERED
+ if any(layer.get("mediaType") in (OCI_VM_DISK, OCI_VM_DISK_LEGACY) for layer in layers):
+ return ImageFormat.OCI_LAYERED
+
+ # Legacy LZ4
+ if config_mt in (LEGACY_DISK_CHUNK,):
+ return ImageFormat.LEGACY_LZ4
+ if any(layer.get("mediaType") == LEGACY_DISK_CHUNK for layer in layers):
+ return ImageFormat.LEGACY_LZ4
+
+ # Chunked-parts: standard OCI layer type but with ;part.number= suffix
+ for layer in layers:
+ mt = layer.get("mediaType", "")
+ if "part.number=" in mt:
+ return ImageFormat.CHUNKED_PARTS
+
+ # QEMU (cua): trycua.qemu config or disk layers
+ if config_mt == QEMU_CONFIG:
+ return ImageFormat.QEMU
+ if any(layer.get("mediaType") in (QEMU_DISK, QEMU_DISK_GZIP) for layer in layers):
+ return ImageFormat.QEMU
+
+ # Tart (Cirrus Labs): OCI config but cirruslabs disk layers
+ if any(layer.get("mediaType") in (TART_DISK, TART_CONFIG) for layer in layers):
+ return ImageFormat.TART
+
+ # Standard container
+ if config_mt in CONTAINER_CONFIG_TYPES:
+ return ImageFormat.CONTAINER
+ if any(layer.get("mediaType") in CONTAINER_LAYER_TYPES for layer in layers):
+ return ImageFormat.CONTAINER
+
+ return ImageFormat.UNKNOWN
+
+
+def detect_kind(manifest: dict) -> str:
+ """Classify manifest as 'vm' or 'container'."""
+ fmt = detect_format(manifest)
+ if fmt in (
+ ImageFormat.OCI_LAYERED,
+ ImageFormat.LEGACY_LZ4,
+ ImageFormat.CHUNKED_PARTS,
+ ImageFormat.TART,
+ ImageFormat.QEMU,
+ ):
+ return "vm"
+ if fmt == ImageFormat.CONTAINER:
+ return "container"
+ # Fallback: check if any layer has a VM media type
+ layers = manifest.get("layers", [])
+ config_mt = manifest.get("config", {}).get("mediaType", "")
+ if config_mt in VM_MEDIA_TYPES or any(
+ layer.get("mediaType") in VM_MEDIA_TYPES for layer in layers
+ ):
+ return "vm"
+ return "container"
+
+
+def detect_os(manifest: dict) -> Optional[str]:
+ """Try to infer OS from manifest annotations or media types."""
+ # Check top-level annotations
+ annot = manifest.get("annotations", {})
+ os_val = annot.get("org.trycua.lume.os", "").lower()
+ if os_val:
+ if "macos" in os_val or "mac" in os_val:
+ return "macos"
+ if "windows" in os_val:
+ return "windows"
+ if "linux" in os_val:
+ return "linux"
+
+ # lume/agoda media types → macOS
+ config_mt = manifest.get("config", {}).get("mediaType", "")
+ if config_mt in (OCI_VM_CONFIG, OCI_VM_CONFIG_LEGACY):
+ return "macos"
+ if any(
+ layer.get("mediaType") in (OCI_VM_DISK, OCI_VM_DISK_LEGACY)
+ for layer in manifest.get("layers", [])
+ ):
+ return "macos"
+
+ return None
+
+
+def detect_os_from_config(ref: str, manifest: dict) -> Optional[str]:
+ """Fetch the OCI config blob and read the 'os' field.
+
+ This handles images (like Tart) where OS info is in the config blob
+ rather than manifest annotations. Falls back to detect_os() first.
+ """
+ os_type = detect_os(manifest)
+ if os_type:
+ return os_type
+
+ config = manifest.get("config", {})
+ digest = config.get("digest")
+ if not digest:
+ return None
+
+ r = oras.provider.Registry()
+ registry, org, name, _tag = parse_ref(ref)
+ full_repo = f"{registry}/{org}/{name}"
+
+ try:
+ resp = r.get_blob(full_repo, digest)
+ data = resp.json() if hasattr(resp, "json") else {}
+ # Standard OCI: "os" field; QEMU: "guest_os" field
+ os_val = (data.get("os") or data.get("guest_os") or "").lower()
+ if os_val in ("linux", "windows"):
+ return os_val
+ if os_val in ("darwin", "macos"):
+ return "macos"
+ except Exception:
+ pass
+
+ # Also check tart config layer
+ for layer in manifest.get("layers", []):
+ if layer.get("mediaType") == TART_CONFIG:
+ try:
+ resp = r.get_blob(full_repo, layer["digest"])
+ data = resp.json() if hasattr(resp, "json") else {}
+ os_val = (data.get("os") or "").lower()
+ if os_val in ("linux", "windows"):
+ return os_val
+ if os_val in ("darwin", "macos"):
+ return "macos"
+ except Exception:
+ pass
+
+ return None
+
+
+def get_layer_info(manifest: dict) -> list[dict]:
+ """Extract structured layer info from a manifest.
+
+ Returns a list of dicts with keys: mediaType, digest, size, title,
+ part_number, part_total, uncompressed_size.
+ """
+ result = []
+ for layer in manifest.get("layers", []):
+ annot = layer.get("annotations", {})
+ mt = layer.get("mediaType", "")
+
+ # Parse part info from either annotations or media type string
+ part_number = annot.get("org.trycua.lume.part.number")
+ part_total = annot.get("org.trycua.lume.part.total")
+ if part_number is None and "part.number=" in mt:
+ # Parse from media type: "...;part.number=1;part.total=164"
+ for segment in mt.split(";"):
+ if segment.startswith("part.number="):
+ part_number = segment.split("=", 1)[1]
+ elif segment.startswith("part.total="):
+ part_total = segment.split("=", 1)[1]
+
+ result.append(
+ {
+ "mediaType": mt,
+ "digest": layer.get("digest", ""),
+ "size": layer.get("size", 0),
+ "title": annot.get("org.opencontainers.image.title", ""),
+ "part_number": int(part_number) if part_number is not None else None,
+ "part_total": int(part_total) if part_total is not None else None,
+ "uncompressed_size": int(
+ annot.get("com.agoda.macosvz.content.uncompressed-size", 0)
+ )
+ or None,
+ }
+ )
+ return result
diff --git a/libs/python/cua-sandbox/cua_sandbox/registry/media_types.py b/libs/python/cua-sandbox/cua_sandbox/registry/media_types.py
new file mode 100644
index 0000000000..06780c5302
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/registry/media_types.py
@@ -0,0 +1,82 @@
+"""OCI media type constants for VM and container image detection.
+
+VM image formats in the wild:
+
+ OCI-layered (agoda): gzip-compressed disk chunks, agoda media types,
+ annotations with part.number/offset/total
+ Legacy Lume (LZ4): LZ4-chunked disk, trycua media types
+ Chunked-parts: standard OCI layer type with ;part.number= in media type string
+ Tart (Cirrus Labs): compressed disk chunks, cirruslabs media types,
+ OCI config with os/architecture fields
+ QEMU (cua): qcow2 disk chunks, trycua.qemu media types,
+ config with guest_os/cpu/ram/tpm
+
+Standard container images use OCI/Docker layer media types.
+"""
+
+# ── QEMU VM (cua) ────────────────────────────────────────────────────────────
+
+QEMU_CONFIG = "application/vnd.trycua.qemu.config.v1+json"
+QEMU_DISK = "application/vnd.trycua.qemu.disk.v1"
+QEMU_DISK_GZIP = "application/vnd.trycua.qemu.disk.v1+gzip"
+
+# ── Tart (Cirrus Labs) ───────────────────────────────────────────────────────
+
+TART_CONFIG = "application/vnd.cirruslabs.tart.config.v1"
+TART_DISK = "application/vnd.cirruslabs.tart.disk.v2"
+TART_NVRAM = "application/vnd.cirruslabs.tart.nvram.v1"
+
+# ── OCI-compliant VM (agoda / kubelet) ──────────────────────────────────────
+
+OCI_VM_CONFIG = "application/vnd.agoda.macosvz.config.v1+json"
+OCI_VM_DISK = "application/vnd.agoda.macosvz.disk.image.v1"
+OCI_VM_AUX = "application/vnd.agoda.macosvz.aux.image.v1"
+
+# Backward-compat: existing images on ghcr.io still use the agoda media types
+OCI_VM_CONFIG_LEGACY = "application/vnd.agoda.macosvz.config.v1+json"
+OCI_VM_DISK_LEGACY = "application/vnd.agoda.macosvz.disk.image.v1"
+OCI_VM_AUX_LEGACY = "application/vnd.agoda.macosvz.aux.image.v1"
+
+# ── Legacy Lume (LZ4-chunked) ──────────────────────────────────────────────
+
+LEGACY_DISK_CHUNK = "application/vnd.trycua.lume.disk.chunk.lz4"
+LEGACY_AUX = "application/vnd.trycua.lume.aux.image.v1"
+LEGACY_CONFIG = "application/vnd.trycua.lume.config.v1+json"
+
+# ── Standard OCI / Docker container ────────────────────────────────────────
+
+OCI_IMAGE_LAYER = "application/vnd.oci.image.layer.v1.tar+gzip"
+OCI_IMAGE_LAYER_NONDIST = "application/vnd.oci.image.layer.nondistributable.v1.tar+gzip"
+DOCKER_IMAGE_LAYER = "application/vnd.docker.image.rootfs.diff.tar.gzip"
+OCI_IMAGE_CONFIG = "application/vnd.oci.image.config.v1+json"
+DOCKER_IMAGE_CONFIG = "application/vnd.docker.container.image.v1+json"
+
+# ── Sets ────────────────────────────────────────────────────────────────────
+
+VM_MEDIA_TYPES = frozenset(
+ {
+ QEMU_CONFIG,
+ QEMU_DISK,
+ QEMU_DISK_GZIP,
+ OCI_VM_CONFIG,
+ OCI_VM_DISK,
+ OCI_VM_AUX,
+ OCI_VM_CONFIG_LEGACY,
+ OCI_VM_DISK_LEGACY,
+ OCI_VM_AUX_LEGACY,
+ LEGACY_DISK_CHUNK,
+ LEGACY_AUX,
+ LEGACY_CONFIG,
+ TART_CONFIG,
+ TART_DISK,
+ TART_NVRAM,
+ }
+)
+
+CONTAINER_LAYER_TYPES = frozenset({
+ OCI_IMAGE_LAYER, OCI_IMAGE_LAYER_NONDIST, DOCKER_IMAGE_LAYER,
+})
+
+CONTAINER_CONFIG_TYPES = frozenset({
+ OCI_IMAGE_CONFIG, DOCKER_IMAGE_CONFIG,
+})
diff --git a/libs/python/cua-sandbox/cua_sandbox/registry/qemu_builder.py b/libs/python/cua-sandbox/cua_sandbox/registry/qemu_builder.py
new file mode 100644
index 0000000000..9affc0f044
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/registry/qemu_builder.py
@@ -0,0 +1,874 @@
+"""Build QEMU Windows VM images and push/pull as OCI artifacts.
+
+Workflow:
+ 1. Download Windows ISO from Microsoft (or use a provided path)
+ 2. Download virtio-win.iso from Fedora
+ 3. Create qcow2 disk + unattended install ISO
+ 4. Run unattended Windows install via QEMU
+ 5. Package the resulting qcow2 as an OCI image and push to registry
+
+Usage:
+ python -m cua_sandbox.registry.qemu_builder build \\
+ --ref ghcr.io/trycua/cua-qemu-windows-vm:latest \\
+ --windows-version 11 \\
+ --disk-size 64
+
+ python -m cua_sandbox.registry.qemu_builder push \\
+ --ref ghcr.io/trycua/cua-qemu-windows-vm:latest \\
+ --disk /path/to/disk.qcow2
+"""
+
+from __future__ import annotations
+
+import gzip
+import hashlib
+import json
+import logging
+import shutil
+import subprocess
+import tempfile
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Optional
+
+from cua_sandbox.builder.windows_unattend import (
+ create_unattend_iso,
+ download_file,
+ download_windows_iso,
+)
+
+logger = logging.getLogger(__name__)
+
+WORK_DIR = Path.home() / ".cua" / "cua-sandbox" / "qemu-builder"
+VIRTIO_ISO_URL = (
+ "https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/stable-virtio/virtio-win.iso"
+)
+CHUNK_SIZE = 500 * 1024 * 1024 # 500 MB chunks for OCI layers
+
+
+@dataclass
+class QEMUImageConfig:
+ """VM configuration stored as the OCI config blob."""
+
+ guest_os: str = "windows"
+ version: str = "11"
+ cpu: int = 4
+ ram_mb: int = 8192
+ disk_size_gb: int = 64
+ disk_format: str = "qcow2"
+ tpm: bool = True
+ architecture: str = "x86_64"
+ display: dict = field(default_factory=lambda: {"width": 1920, "height": 1080})
+
+
+# ── Download helpers ────────────────────────────────────────────────────────
+
+
+def download_virtio_iso(work_dir: Optional[Path] = None) -> Path:
+ """Download virtio-win.iso from Fedora."""
+ dest = (work_dir or WORK_DIR) / "virtio-win.iso"
+ return download_file(VIRTIO_ISO_URL, dest, "virtio-win.iso")
+
+
+# ── Disk creation ───────────────────────────────────────────────────────────
+
+
+def create_qcow2(path: Path, size_gb: int) -> Path:
+ """Create a qcow2 disk image."""
+ path.parent.mkdir(parents=True, exist_ok=True)
+ cmd = [
+ "qemu-img",
+ "create",
+ "-q",
+ "-f",
+ "qcow2",
+ "-o",
+ "lazy_refcounts=on,preallocation=off",
+ str(path),
+ f"{size_gb}G",
+ ]
+ # Try system qemu-img first, then portable
+ try:
+ subprocess.run(cmd, check=True, capture_output=True)
+ except FileNotFoundError:
+ from cua_sandbox.runtime.qemu_installer import qemu_bin
+
+ cmd[0] = str(Path(qemu_bin("x86_64")).parent / "qemu-img")
+ if not Path(cmd[0]).exists():
+ cmd[0] = str(Path(qemu_bin("x86_64")).parent / "qemu-img.exe")
+ subprocess.run(cmd, check=True, capture_output=True)
+ logger.info(f"Created {size_gb}G qcow2 disk: {path}")
+ return path
+
+
+# ── WSL2 build helper ──────────────────────────────────────────────────────
+
+
+def _win_to_wsl(p: Path | str) -> str:
+ """Convert a Windows path to WSL /mnt/... path."""
+ s = str(p).replace("\\", "/")
+ if len(s) >= 2 and s[1] == ":":
+ return f"/mnt/{s[0].lower()}{s[2:]}"
+ return s
+
+
+def _build_image_wsl2(
+ config: QEMUImageConfig,
+ cmd: list[str],
+ disk_path: Path,
+ work_dir: Path,
+ proc_port: int = 18000,
+) -> Path:
+ """Run QEMU build inside WSL2 with KVM acceleration.
+
+ Converts all Windows paths in the QEMU command to WSL /mnt/... paths,
+ uses the WSL2 qemu-system-x86_64 with -enable-kvm and -cpu host.
+ """
+ import socket
+ import threading
+ import time
+ import urllib.request
+
+ def _convert_arg(arg: str) -> str:
+ """Convert Windows paths in a QEMU argument to WSL paths."""
+ if len(arg) >= 3 and arg[1] == ":" and arg[2] in ("/", "\\"):
+ return _win_to_wsl(arg)
+ if "=" in arg and (":\\" in arg or ":/" in arg):
+ parts = arg.split(",")
+ converted = []
+ for part in parts:
+ if "=" in part:
+ k, v = part.split("=", 1)
+ if len(v) >= 3 and v[1] == ":" and v[2] in ("/", "\\"):
+ v = _win_to_wsl(v)
+ converted.append(f"{k}={v}")
+ else:
+ converted.append(part)
+ return ",".join(converted)
+ return arg
+
+ # Build WSL2 command: replace binary, convert paths, use native OVMF
+ wsl_cmd = ["qemu-system-x86_64"]
+ skip_next = False
+ for i, arg in enumerate(cmd[1:], 1):
+ if skip_next:
+ skip_next = False
+ continue
+
+ # Replace -cpu with host passthrough
+ if arg == "-cpu":
+ wsl_cmd += ["-cpu", "host"]
+ skip_next = True
+ continue
+
+ # Replace OVMF pflash with WSL2 native paths
+ if (
+ arg == "-drive" and i + 1 <= len(cmd) and "if=pflash" in cmd[i]
+ if i < len(cmd)
+ else False
+ ):
+ pass # handled below
+ if "if=pflash" in arg:
+ if "readonly=on" in arg:
+ # OVMF code — use WSL2 native
+ wsl_cmd.append(
+ "if=pflash,format=raw,readonly=on,file=/usr/share/OVMF/OVMF_CODE_4M.fd"
+ )
+ else:
+ # EFI vars — create from WSL2 native template (must match OVMF_CODE_4M size)
+ wsl_efivars = _win_to_wsl(work_dir / "efivars-wsl.fd")
+ wsl_cmd.append(f"if=pflash,format=raw,file={wsl_efivars}")
+ continue
+
+ wsl_cmd.append(_convert_arg(arg))
+
+ wsl_cmd.append("-enable-kvm")
+
+ # Bind QMP and network to 0.0.0.0 so Windows host can reach them
+ for i, a in enumerate(wsl_cmd):
+ if "tcp:127.0.0.1:4444" in a:
+ wsl_cmd[i] = a.replace("127.0.0.1", "0.0.0.0")
+ if "hostfwd=tcp::" in a:
+ wsl_cmd[i] = a.replace("hostfwd=tcp::", "hostfwd=tcp:0.0.0.0:")
+
+ # Create WSL2-compatible EFI vars from WSL native template
+ wsl_efivars_win = work_dir / "efivars-wsl.fd"
+ if not wsl_efivars_win.exists():
+ subprocess.run(
+ [
+ "wsl",
+ "-e",
+ "bash",
+ "-c",
+ f"cp /usr/share/OVMF/OVMF_VARS_4M.fd '{_win_to_wsl(wsl_efivars_win)}'",
+ ],
+ check=True,
+ capture_output=True,
+ )
+
+ shell_cmd = " ".join(wsl_cmd)
+ logger.info(f"WSL2 QEMU command: {shell_cmd}")
+
+ # Launch QEMU in WSL2
+ proc = subprocess.Popen(
+ ["wsl", "-e", "bash", "-c", shell_cmd],
+ stdout=subprocess.DEVNULL,
+ stderr=subprocess.PIPE,
+ )
+ logger.info(f"QEMU WSL2 install running as PID {proc.pid}. Monitor via VNC on port 5900.")
+
+ def _qmp_cmd(cmd_json: bytes):
+ try:
+ s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+ s.settimeout(3)
+ s.connect(("127.0.0.1", 4444))
+ s.recv(4096)
+ s.sendall(b'{"execute":"qmp_capabilities"}\n')
+ s.recv(4096)
+ s.sendall(cmd_json + b"\n")
+ s.recv(4096)
+ s.close()
+ return True
+ except Exception:
+ return False
+
+ def _boot_and_monitor():
+ # Phase 1: boot keypresses (fewer needed with KVM — faster boot)
+ for i in range(15):
+ time.sleep(2)
+ if _qmp_cmd(
+ b'{"execute":"send-key","arguments":{"keys":[{"type":"qcode","data":"ret"}]}}'
+ ):
+ logger.info(f"Sent boot keypress ({i+1}/15)")
+
+ # Phase 2: wait for CUA server (KVM is much faster, ~15-30 min)
+ logger.info(f"Waiting for CUA computer-server on port {proc_port}...")
+ for i in range(180): # 180 * 10s = 30 min
+ time.sleep(10)
+ try:
+ r = urllib.request.urlopen(f"http://127.0.0.1:{proc_port}/", timeout=5)
+ if r.status == 200:
+ logger.info("CUA computer-server is running! Sending ACPI shutdown...")
+ break
+ except Exception:
+ if i % 6 == 0:
+ logger.info(f"Still waiting... ({i * 10 // 60} min elapsed)")
+ else:
+ logger.warning("Timed out waiting for CUA server. Shutting down anyway.")
+
+ # Phase 3: ACPI shutdown
+ time.sleep(5)
+ _qmp_cmd(b'{"execute":"system_powerdown"}')
+ for _ in range(12):
+ time.sleep(10)
+ if proc.poll() is not None:
+ return
+ _qmp_cmd(b'{"execute":"system_powerdown"}')
+ logger.warning("ACPI shutdown did not work, terminating.")
+ proc.terminate()
+
+ t = threading.Thread(target=_boot_and_monitor, daemon=True)
+ t.start()
+
+ logger.info("Waiting for QEMU WSL2 to exit (15-30 min with KVM)...")
+ proc.wait()
+ if proc.returncode != 0:
+ stderr = proc.stderr.read().decode() if proc.stderr else ""
+ raise RuntimeError(f"QEMU WSL2 install failed (exit {proc.returncode}): {stderr}")
+
+ logger.info(f"Windows install complete. Disk image: {disk_path}")
+ config_path = work_dir / "config.json"
+ config_path.write_text(json.dumps(asdict(config), indent=2))
+ return disk_path
+
+
+# ── Full build ──────────────────────────────────────────────────────────────
+
+
+def build_image(
+ config: Optional[QEMUImageConfig] = None,
+ *,
+ windows_iso: Optional[str] = None,
+ work_dir: Optional[Path] = None,
+ product_key: Optional[str] = None,
+ use_wsl2: bool = False,
+) -> Path:
+ """Build a Windows qcow2 image via unattended QEMU install.
+
+ Returns the path to the completed qcow2 disk.
+
+ This is a long-running operation (30-60 minutes for Windows install).
+ """
+ config = config or QEMUImageConfig()
+ work_dir = work_dir or WORK_DIR / f"windows-{config.version}"
+ work_dir.mkdir(parents=True, exist_ok=True)
+
+ disk_path = work_dir / "disk.qcow2"
+ if disk_path.exists():
+ logger.info(f"Disk already exists: {disk_path}")
+ return disk_path
+
+ # Step 1: Get ISOs
+ win_iso = download_windows_iso(config.version, work_dir, windows_iso)
+ virtio_iso = download_virtio_iso(work_dir)
+ # Create a small data-only ISO with Autounattend.xml + setup script.
+ # Windows Setup searches all drives for Autounattend.xml automatically,
+ # so we keep the original Windows ISO unchanged (it's UEFI-bootable).
+ unattend_iso = create_unattend_iso(work_dir, product_key)
+
+ # Step 2: Create disk
+ create_qcow2(disk_path, config.disk_size_gb)
+
+ # Step 3: Run QEMU install
+ logger.info("Starting unattended Windows install via QEMU...")
+ logger.info("This will take 30-60 minutes. Monitor via VNC on port 5900.")
+
+ import platform as _plat
+
+ from cua_sandbox.runtime.qemu_installer import qemu_bin
+
+ qemu = qemu_bin(config.architecture)
+ qemu_dir = Path(qemu).parent
+
+ # Locate OVMF UEFI firmware (required for Windows 10/11)
+ ovmf_code = None
+ for candidate in [
+ qemu_dir / "share" / "edk2-x86_64-code.fd",
+ qemu_dir.parent / "share" / "qemu" / "edk2-x86_64-code.fd", # Homebrew: bin/../share/qemu/
+ Path("/usr/share/OVMF/OVMF_CODE.fd"),
+ Path("/usr/share/ovmf/OVMF_CODE.fd"),
+ Path("/usr/share/qemu/edk2-x86_64-code.fd"),
+ ]:
+ if candidate.exists():
+ ovmf_code = candidate
+ break
+
+ if not ovmf_code:
+ raise RuntimeError(
+ "OVMF UEFI firmware not found. Windows 11 requires UEFI boot. "
+ "Expected edk2-x86_64-code.fd in QEMU share directory."
+ )
+
+ # Create EFI vars file (writable copy for this install)
+ efivars = work_dir / "efivars.fd"
+ if not efivars.exists():
+ vars_template = qemu_dir / "share" / "edk2-i386-vars.fd"
+ if not vars_template.exists():
+ vars_template = qemu_dir.parent / "share" / "qemu" / "edk2-i386-vars.fd"
+ if vars_template.exists():
+ shutil.copy2(vars_template, efivars)
+ else:
+ efivars.write_bytes(b"\x00" * (256 * 1024))
+
+ cmd = [
+ qemu,
+ "-name",
+ "windows-install",
+ "-machine",
+ "q35,smm=off",
+ "-m",
+ str(config.ram_mb),
+ "-smp",
+ str(config.cpu),
+ "-cpu",
+ "qemu64,+ssse3,+sse4.1,+sse4.2,+popcnt",
+ # UEFI firmware
+ "-drive",
+ f"if=pflash,format=raw,readonly=on,file={ovmf_code}",
+ "-drive",
+ f"if=pflash,format=raw,file={efivars}",
+ # Main disk — virtio-blk (bootindex=0 so after reboot it boots from disk)
+ "-drive",
+ f"file={disk_path},id=disk0,format=qcow2,if=none",
+ "-device",
+ "virtio-blk-pci,drive=disk0,bootindex=0",
+ # AHCI controller for all CDROMs (Q35 built-in IDE only supports 1 unit)
+ "-device",
+ "ich9-ahci,id=sata",
+ # Windows ISO — bootindex=0 so OVMF boots from it first
+ "-drive",
+ f"file={win_iso},if=none,media=cdrom,readonly=on,id=cd0",
+ "-device",
+ "ide-cd,drive=cd0,bus=sata.0,bootindex=1",
+ # Unattend ISO (data-only: Autounattend.xml + setup script + startup.nsh)
+ "-drive",
+ f"file={unattend_iso},if=none,media=cdrom,readonly=on,id=cd1",
+ "-device",
+ "ide-cd,drive=cd1,bus=sata.1",
+ # VirtIO drivers ISO
+ "-drive",
+ f"file={virtio_iso},if=none,media=cdrom,readonly=on,id=cd2",
+ "-device",
+ "ide-cd,drive=cd2,bus=sata.2",
+ "-vnc",
+ ":0",
+ # QMP monitor for sending keypresses (bypass "press any key to boot from CD")
+ "-qmp",
+ "tcp:127.0.0.1:4444,server,nowait",
+ # Network (localhost only, no firewall prompt)
+ "-netdev",
+ "user,id=net0,hostfwd=tcp::18000-:8000",
+ "-device",
+ "virtio-net-pci,netdev=net0,mac=52:55:00:d1:55:01",
+ # Disable S3/S4 (avoids ACPI sleep issues during install) — same as dockur
+ "-global",
+ "ICH9-LPC.disable_s3=1",
+ "-global",
+ "ICH9-LPC.disable_s4=1",
+ # RTC base localtime for Windows
+ "-rtc",
+ "base=localtime",
+ ]
+
+ # TPM (requires swtpm — not available on Windows)
+ if config.tpm and shutil.which("swtpm") and _plat.system() != "Windows":
+ tpm_dir = work_dir / "tpm"
+ tpm_dir.mkdir(exist_ok=True)
+ cmd += [
+ "-chardev",
+ f"socket,id=chrtpm,path={tpm_dir}/swtpm-sock",
+ "-tpmdev",
+ "emulator,id=tpm0,chardev=chrtpm",
+ "-device",
+ "tpm-tis,tpmdev=tpm0",
+ ]
+ subprocess.Popen(
+ [
+ "swtpm",
+ "socket",
+ "--tpmstate",
+ f"dir={tpm_dir}",
+ "--ctrl",
+ f"type=unixio,path={tpm_dir}/swtpm-sock",
+ "--tpm2",
+ "--log",
+ f"file={tpm_dir}/swtpm.log",
+ ]
+ )
+
+ # Hardware acceleration
+ if use_wsl2:
+ # WSL2 path: rewrite entire command for WSL2 with KVM
+ return _build_image_wsl2(
+ config,
+ cmd,
+ disk_path,
+ work_dir,
+ proc_port=18000,
+ )
+
+ # WHPX on Windows has MMIO emulation bugs with OVMF pflash drives,
+ # so we use TCG (software emulation) on Windows for UEFI builds.
+ if _plat.system() == "Windows":
+ cmd += ["-accel", "tcg"]
+ elif shutil.which("kvm-ok"):
+ r = subprocess.run(["kvm-ok"], capture_output=True)
+ if r.returncode == 0:
+ cmd.append("-enable-kvm")
+ elif Path("/dev/kvm").exists():
+ cmd.append("-enable-kvm")
+
+ # Run QEMU install
+ logger.info(f"QEMU command: {' '.join(cmd)}")
+ if _plat.system() == "Windows":
+ proc = subprocess.Popen(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE)
+ logger.info(f"QEMU install running as PID {proc.pid}. Monitor via VNC on port 5900.")
+
+ # Background thread: send boot keypresses, then health-check server, then shutdown
+ import socket
+ import threading
+ import time
+ import urllib.request
+
+ def _qmp_cmd(cmd_json: bytes):
+ """Send a QMP command and return."""
+ try:
+ s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+ s.settimeout(3)
+ s.connect(("127.0.0.1", 4444))
+ s.recv(4096) # QMP greeting
+ s.sendall(b'{"execute":"qmp_capabilities"}\n')
+ s.recv(4096)
+ s.sendall(cmd_json + b"\n")
+ s.recv(4096)
+ s.close()
+ return True
+ except Exception:
+ return False
+
+ def _boot_and_monitor():
+ """Phase 1: send Enter keys for 30s to bypass boot prompts.
+ Phase 2: poll CUA server on port 18000 until it responds.
+ Phase 3: send ACPI shutdown via QMP."""
+ # Phase 1: boot keypresses
+ for i in range(15):
+ time.sleep(2)
+ if _qmp_cmd(
+ b'{"execute":"send-key","arguments":{"keys":[{"type":"qcode","data":"ret"}]}}'
+ ):
+ logger.info(f"Sent boot keypress ({i+1}/15)")
+
+ # Phase 2: wait for CUA server (up to 90 min for TCG installs)
+ logger.info("Waiting for CUA computer-server to become available on port 18000...")
+ for i in range(540): # 540 * 10s = 90 min
+ time.sleep(10)
+ try:
+ r = urllib.request.urlopen("http://127.0.0.1:18000/", timeout=5)
+ if r.status == 200:
+ logger.info("CUA computer-server is running! Sending ACPI shutdown...")
+ break
+ except Exception:
+ if i % 6 == 0:
+ logger.info(f"Still waiting for CUA server... ({i * 10 // 60} min elapsed)")
+ else:
+ logger.warning("Timed out waiting for CUA server (90 min). Shutting down anyway.")
+
+ # Phase 3: ACPI shutdown
+ time.sleep(5)
+ _qmp_cmd(b'{"execute":"system_powerdown"}')
+ # Wait and retry if needed
+ for _ in range(12):
+ time.sleep(10)
+ if proc.poll() is not None:
+ return
+ _qmp_cmd(b'{"execute":"system_powerdown"}')
+ logger.warning("ACPI shutdown did not work, terminating QEMU.")
+ proc.terminate()
+
+ t = threading.Thread(target=_boot_and_monitor, daemon=True)
+ t.start()
+
+ logger.info("Waiting for QEMU to exit (this takes 30-60 minutes)...")
+ proc.wait()
+ if proc.returncode != 0:
+ stderr = proc.stderr.read().decode() if proc.stderr else ""
+ raise RuntimeError(f"QEMU install failed (exit {proc.returncode}): {stderr}")
+ else:
+ result = subprocess.run(cmd)
+ if result.returncode != 0:
+ raise RuntimeError(f"QEMU install failed with exit code {result.returncode}")
+
+ logger.info(f"Windows install complete. Disk image: {disk_path}")
+
+ # Save config alongside disk
+ config_path = work_dir / "config.json"
+ config_path.write_text(json.dumps(asdict(config), indent=2))
+
+ return disk_path
+
+
+# ── OCI push/pull ───────────────────────────────────────────────────────────
+
+
+def _sha256_file(path: Path) -> str:
+ h = hashlib.sha256()
+ with open(path, "rb") as f:
+ for chunk in iter(lambda: f.read(8 * 1024 * 1024), b""):
+ h.update(chunk)
+ return h.hexdigest()
+
+
+def push_image(
+ disk_path: str | Path,
+ ref: str,
+ config: Optional[QEMUImageConfig] = None,
+) -> None:
+ """Push a qcow2 disk image to an OCI registry.
+
+ Chunks the disk into gzip-compressed ~500MB layers with part annotations.
+ """
+ import oras.provider
+ from cua_sandbox.registry.media_types import QEMU_CONFIG, QEMU_DISK_GZIP
+ from cua_sandbox.registry.ref import parse_ref
+
+ disk_path = Path(disk_path)
+ if not disk_path.exists():
+ raise FileNotFoundError(f"Disk image not found: {disk_path}")
+
+ config = config or QEMUImageConfig()
+ registry, org, name, tag = parse_ref(ref)
+ full_repo = f"{registry}/{org}/{name}"
+
+ r = oras.provider.Registry()
+
+ with tempfile.TemporaryDirectory() as tmp:
+ tmp_dir = Path(tmp)
+
+ # Create config blob
+ config_data = json.dumps(asdict(config)).encode()
+ config_digest = f"sha256:{hashlib.sha256(config_data).hexdigest()}"
+ config_path = tmp_dir / "config.json"
+ config_path.write_bytes(config_data)
+
+ # Chunk the disk into gzip-compressed parts
+ disk_size = disk_path.stat().st_size
+ part_total = (disk_size + CHUNK_SIZE - 1) // CHUNK_SIZE
+ layers = []
+
+ logger.info(f"Chunking {disk_size / 1024 / 1024:.0f} MB disk into {part_total} parts...")
+
+ with open(disk_path, "rb") as f:
+ for part_num in range(1, part_total + 1):
+ chunk_data = f.read(CHUNK_SIZE)
+ if not chunk_data:
+ break
+
+ # Gzip compress
+ compressed = gzip.compress(chunk_data, compresslevel=6)
+ chunk_path = tmp_dir / f"disk.part.{part_num:04d}.gz"
+ chunk_path.write_bytes(compressed)
+
+ chunk_digest = f"sha256:{hashlib.sha256(compressed).hexdigest()}"
+
+ layers.append(
+ {
+ "mediaType": QEMU_DISK_GZIP,
+ "digest": chunk_digest,
+ "size": len(compressed),
+ "annotations": {
+ "org.trycua.qemu.part.number": str(part_num),
+ "org.trycua.qemu.part.total": str(part_total),
+ "org.trycua.qemu.uncompressed-size": str(len(chunk_data)),
+ "org.opencontainers.image.title": f"disk.qcow2.part.{part_num:04d}",
+ },
+ }
+ )
+
+ logger.info(
+ f" part {part_num}/{part_total}: {len(compressed) / 1024 / 1024:.1f} MB compressed"
+ )
+
+ # Push blob
+ r.push_blob(full_repo, chunk_path, chunk_digest)
+
+ # Push config blob
+ r.push_blob(full_repo, config_path, config_digest)
+
+ # Create and push manifest
+ manifest = {
+ "schemaVersion": 2,
+ "mediaType": "application/vnd.oci.image.manifest.v1+json",
+ "config": {
+ "mediaType": QEMU_CONFIG,
+ "digest": config_digest,
+ "size": len(config_data),
+ },
+ "layers": layers,
+ "annotations": {
+ "org.trycua.qemu.guest-os": config.guest_os,
+ "org.trycua.qemu.version": config.version,
+ "org.trycua.qemu.disk-format": config.disk_format,
+ "org.trycua.qemu.uncompressed-disk-size": str(disk_size),
+ },
+ }
+
+ r.put_manifest(f"{full_repo}:{tag}", json.dumps(manifest))
+ logger.info(f"Pushed {ref} ({part_total} layers, {disk_size / 1024 / 1024:.0f} MB)")
+
+
+def pull_qemu_image(ref: str, dest_dir: Optional[Path] = None) -> tuple[QEMUImageConfig, Path]:
+ """Pull a QEMU VM image from an OCI registry.
+
+ Downloads gzip-compressed disk chunks, decompresses, and reassembles
+ into a qcow2 disk image.
+
+ Returns (config, disk_path).
+ """
+ import oras.provider
+ from cua_sandbox.registry.cache import ImageCache
+ from cua_sandbox.registry.manifest import get_manifest
+ from cua_sandbox.registry.media_types import QEMU_DISK, QEMU_DISK_GZIP
+ from cua_sandbox.registry.ref import parse_ref
+
+ registry, org, name, tag = parse_ref(ref)
+ full_repo = f"{registry}/{org}/{name}"
+
+ cache = ImageCache()
+ if dest_dir is None:
+ dest_dir = cache.image_dir(registry, org, name, tag)
+ dest_dir.mkdir(parents=True, exist_ok=True)
+
+ disk_path = dest_dir / "disk.qcow2"
+ config_path = dest_dir / "config.json"
+
+ # Check cache
+ if disk_path.exists() and config_path.exists():
+ logger.info(f"Using cached QEMU image: {dest_dir}")
+ data = json.loads(config_path.read_text())
+ return (
+ QEMUImageConfig(
+ **{k: v for k, v in data.items() if k in QEMUImageConfig.__dataclass_fields__}
+ ),
+ disk_path,
+ )
+
+ manifest = get_manifest(ref)
+ r = oras.provider.Registry()
+
+ # Download config
+ config_blob = manifest.get("config", {})
+ if config_blob.get("digest"):
+ resp = r.get_blob(full_repo, config_blob["digest"])
+ config_path.write_bytes(resp.content)
+ config_data = resp.json() if hasattr(resp, "json") else {}
+ else:
+ config_data = {}
+
+ config = QEMUImageConfig(
+ **{k: v for k, v in config_data.items() if k in QEMUImageConfig.__dataclass_fields__}
+ )
+
+ # Download and reassemble disk parts
+ layers = manifest.get("layers", [])
+ disk_parts: list[tuple[int, dict]] = []
+
+ for layer in layers:
+ mt = layer.get("mediaType", "")
+ annot = layer.get("annotations", {})
+
+ if mt in (QEMU_DISK, QEMU_DISK_GZIP):
+ part_num = int(annot.get("org.trycua.qemu.part.number", 1))
+ disk_parts.append((part_num, layer))
+
+ if not disk_parts:
+ raise RuntimeError(f"No QEMU disk layers found in manifest for {ref}")
+
+ disk_parts.sort(key=lambda x: x[0])
+ total = len(disk_parts)
+ logger.info(f"Downloading {total} disk parts for {ref}...")
+
+ with open(disk_path, "wb") as f:
+ for part_num, layer in disk_parts:
+ mt = layer.get("mediaType", "")
+ digest = layer["digest"]
+ size = layer.get("size", 0)
+ logger.info(f" part {part_num}/{total}: {size / 1024 / 1024:.1f} MB")
+
+ resp = r.get_blob(full_repo, digest)
+ data = resp.content
+
+ # Decompress gzip if needed
+ if mt == QEMU_DISK_GZIP or mt.endswith("+gzip"):
+ data = gzip.decompress(data)
+
+ f.write(data)
+
+ logger.info(f"Assembled disk: {disk_path} ({disk_path.stat().st_size / 1024 / 1024:.0f} MB)")
+
+ # Save manifest
+ cache.save_manifest(registry, org, name, tag, manifest)
+
+ return config, disk_path
+
+
+# ── CLI entry point ─────────────────────────────────────────────────────────
+
+
+def main():
+ import argparse
+
+ logging.basicConfig(level=logging.INFO, format="%(message)s")
+
+ parser = argparse.ArgumentParser(description="Build and push QEMU VM images as OCI artifacts")
+ sub = parser.add_subparsers(dest="command")
+
+ # build
+ build_p = sub.add_parser("build", help="Build a Windows VM image")
+ build_p.add_argument("--windows-version", default="11", help="Windows version (10 or 11)")
+ build_p.add_argument("--iso-path", help="Path to Windows ISO (skip download)")
+ build_p.add_argument("--disk-size", type=int, default=64, help="Disk size in GB")
+ build_p.add_argument("--ram", type=int, default=8192, help="RAM in MB")
+ build_p.add_argument("--cpu", type=int, default=4, help="CPU cores")
+ build_p.add_argument("--no-tpm", action="store_true", help="Disable TPM")
+ build_p.add_argument("--work-dir", type=Path, help="Working directory")
+ build_p.add_argument("--product-key", help="Windows product key")
+ build_p.add_argument(
+ "--wsl2", action="store_true", help="Run QEMU inside WSL2 with KVM acceleration"
+ )
+
+ # push
+ push_p = sub.add_parser("push", help="Push a qcow2 disk as OCI image")
+ push_p.add_argument(
+ "--ref", required=True, help="OCI reference (e.g. ghcr.io/trycua/win11:latest)"
+ )
+ push_p.add_argument("--disk", required=True, help="Path to qcow2 disk")
+ push_p.add_argument("--guest-os", default="windows")
+ push_p.add_argument("--version", default="11")
+ push_p.add_argument("--disk-size", type=int, default=64)
+ push_p.add_argument("--ram", type=int, default=8192)
+ push_p.add_argument("--cpu", type=int, default=4)
+ push_p.add_argument("--no-tpm", action="store_true")
+
+ # pull
+ pull_p = sub.add_parser("pull", help="Pull a QEMU VM image from registry")
+ pull_p.add_argument("--ref", required=True, help="OCI reference")
+ pull_p.add_argument("--dest", type=Path, help="Destination directory")
+
+ # build-and-push
+ bp_p = sub.add_parser("build-and-push", help="Build then push")
+ bp_p.add_argument("--ref", required=True)
+ bp_p.add_argument("--windows-version", default="11")
+ bp_p.add_argument("--iso-path", help="Path to Windows ISO")
+ bp_p.add_argument("--disk-size", type=int, default=64)
+ bp_p.add_argument("--ram", type=int, default=8192)
+ bp_p.add_argument("--cpu", type=int, default=4)
+ bp_p.add_argument("--no-tpm", action="store_true")
+ bp_p.add_argument("--product-key")
+ bp_p.add_argument("--wsl2", action="store_true")
+
+ args = parser.parse_args()
+
+ if args.command == "build":
+ cfg = QEMUImageConfig(
+ guest_os="windows",
+ version=args.windows_version,
+ cpu=args.cpu,
+ ram_mb=args.ram,
+ disk_size_gb=args.disk_size,
+ tpm=not args.no_tpm,
+ )
+ disk = build_image(
+ cfg,
+ windows_iso=args.iso_path,
+ work_dir=args.work_dir,
+ product_key=args.product_key,
+ use_wsl2=args.wsl2,
+ )
+ print(f"Built: {disk}")
+
+ elif args.command == "push":
+ cfg = QEMUImageConfig(
+ guest_os=args.guest_os,
+ version=args.version,
+ cpu=args.cpu,
+ ram_mb=args.ram,
+ disk_size_gb=args.disk_size,
+ tpm=not args.no_tpm,
+ )
+ push_image(args.disk, args.ref, cfg)
+
+ elif args.command == "pull":
+ cfg, disk = pull_qemu_image(args.ref, args.dest)
+ print(f"Pulled: {disk}")
+ print(f"Config: {json.dumps(asdict(cfg), indent=2)}")
+
+ elif args.command == "build-and-push":
+ cfg = QEMUImageConfig(
+ guest_os="windows",
+ version=args.windows_version,
+ cpu=args.cpu,
+ ram_mb=args.ram,
+ disk_size_gb=args.disk_size,
+ tpm=not args.no_tpm,
+ )
+ disk = build_image(
+ cfg, windows_iso=args.iso_path, product_key=args.product_key, use_wsl2=args.wsl2
+ )
+ push_image(disk, args.ref, cfg)
+
+ else:
+ parser.print_help()
+
+
+if __name__ == "__main__":
+ main()
diff --git a/libs/python/cua-sandbox/cua_sandbox/registry/ref.py b/libs/python/cua-sandbox/cua_sandbox/registry/ref.py
new file mode 100644
index 0000000000..b13bac55f8
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/registry/ref.py
@@ -0,0 +1,39 @@
+"""Parse OCI image references into (registry, org, name, tag)."""
+
+from __future__ import annotations
+
+
+def parse_ref(ref: str) -> tuple[str, str, str, str]:
+ """Parse a full or short image reference.
+
+ Handles:
+ ghcr.io/trycua/macos-sequoia-cua:latest → (ghcr.io, trycua, macos-sequoia-cua, latest)
+ trycua/cua-xfce:latest → (ghcr.io, trycua, cua-xfce, latest)
+ cua-xfce:latest → (ghcr.io, trycua, cua-xfce, latest)
+ cua-xfce → (ghcr.io, trycua, cua-xfce, latest)
+ """
+ if ":" in ref:
+ ref_no_tag, tag = ref.rsplit(":", 1)
+ else:
+ ref_no_tag, tag = ref, "latest"
+
+ parts = ref_no_tag.split("/")
+
+ if len(parts) >= 3:
+ registry = parts[0]
+ org = parts[1]
+ name = "/".join(parts[2:])
+ elif len(parts) == 2:
+ registry = "ghcr.io"
+ org = parts[0]
+ name = parts[1]
+ else:
+ registry = "ghcr.io"
+ org = "trycua"
+ name = parts[0]
+
+ # Docker Hub: docker.io → registry-1.docker.io (the actual API host)
+ if registry == "docker.io":
+ registry = "registry-1.docker.io"
+
+ return registry, org, name, tag
diff --git a/libs/python/cua-sandbox/cua_sandbox/registry/resolve.py b/libs/python/cua-sandbox/cua_sandbox/registry/resolve.py
new file mode 100644
index 0000000000..4d9b42d8d2
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/registry/resolve.py
@@ -0,0 +1,196 @@
+"""Resolve image kind from registry manifest and coordinate pulls.
+
+Uses oras-py for manifest fetching. Delegates actual image pull to:
+ - docker pull (for containers)
+ - lume pull (for macOS VMs on macOS hosts)
+ - self-managed download (for VM disk images on other hosts)
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Optional
+
+from cua_sandbox.image import Image
+from cua_sandbox.registry.cache import ImageCache
+from cua_sandbox.registry.manifest import (
+ ImageFormat,
+ detect_format,
+ detect_kind,
+ detect_os,
+ detect_os_from_config,
+ get_manifest,
+)
+from cua_sandbox.registry.ref import parse_ref
+
+logger = logging.getLogger(__name__)
+
+
+def resolve_image_kind(image: Image) -> Image:
+ """Fetch manifest for a registry image and return a new Image with kind/os resolved.
+
+ If kind is already set, returns unchanged.
+ """
+ if image.kind is not None:
+ return image
+ if not image._registry:
+ raise ValueError("Cannot resolve kind: image has no registry reference")
+
+ manifest = get_manifest(image._registry)
+ kind = detect_kind(manifest)
+ os_type = detect_os_from_config(image._registry, manifest) or image.os_type
+
+ return Image(
+ os_type=os_type,
+ distro=image.distro,
+ version=image.version,
+ kind=kind,
+ _layers=image._layers,
+ _env=image._env,
+ _ports=image._ports,
+ _files=image._files,
+ _registry=image._registry,
+ _disk_path=image._disk_path,
+ )
+
+
+def pull_image(
+ image: Image,
+ *,
+ cache: Optional[ImageCache] = None,
+ force: bool = False,
+) -> tuple[Image, Path]:
+ """Pull an image and return (resolved_image, local_path).
+
+ Resolves kind from manifest, then delegates pull to the appropriate backend:
+ - container → docker pull (returns the image ref, caller uses DockerRuntime)
+ - vm + macOS host → lume pull
+ - vm + other host → download blobs via oras
+ """
+ if not image._registry:
+ raise ValueError("Cannot pull: image has no registry reference")
+
+ cache = cache or ImageCache()
+ registry, org, name, tag = parse_ref(image._registry)
+
+ # Fetch manifest (always via oras — lightweight)
+ manifest = get_manifest(image._registry)
+ kind = detect_kind(manifest)
+ os_type = detect_os_from_config(image._registry, manifest) or image.os_type
+ fmt = detect_format(manifest)
+
+ resolved = Image(
+ os_type=os_type,
+ distro=image.distro,
+ version=image.version,
+ kind=kind,
+ _layers=image._layers,
+ _env=image._env,
+ _ports=image._ports,
+ _files=image._files,
+ _registry=image._registry,
+ _disk_path=image._disk_path,
+ )
+
+ # Cache the manifest
+ dest_dir = cache.save_manifest(registry, org, name, tag, manifest)
+
+ if kind == "container":
+ # For containers, docker pull handles everything — just return the ref
+ logger.info(f"Container image {image._registry} — use docker pull")
+ return resolved, dest_dir
+
+ # QEMU format — use dedicated pull
+ if fmt == ImageFormat.QEMU:
+ from cua_sandbox.registry.qemu_builder import pull_qemu_image
+ disk_path = dest_dir / "disk.qcow2"
+ if not force and disk_path.exists():
+ logger.info(f"Using cached QEMU image at {dest_dir}")
+ return resolved, dest_dir
+ logger.info(f"Pulling QEMU image {image._registry}")
+ pull_qemu_image(image._registry, dest_dir)
+ return resolved, dest_dir
+
+ # Other VM formats — check cache
+ disk_path = dest_dir / "disk.img"
+ if not force and disk_path.exists():
+ logger.info(f"Using cached VM image at {dest_dir}")
+ return resolved, dest_dir
+
+ # Pull VM image blobs
+ logger.info(f"Pulling VM image {image._registry} ({fmt.value}, {kind})")
+ _pull_vm_blobs(image._registry, manifest, dest_dir)
+
+ return resolved, dest_dir
+
+
+def _pull_vm_blobs(ref: str, manifest: dict, dest_dir: Path) -> None:
+ """Download VM disk blobs using oras and reassemble."""
+ import oras.provider
+
+ registry, org, name, tag = parse_ref(ref)
+ full_repo = f"{registry}/{org}/{name}"
+
+ r = oras.provider.Registry()
+ layers = manifest.get("layers", [])
+
+ # Separate disk parts from other layers (aux, etc.)
+ disk_parts: list[tuple[int, dict]] = []
+ other_layers: list[dict] = []
+
+ for layer in layers:
+ mt = layer.get("mediaType", "")
+ annot = layer.get("annotations", {})
+
+ # Detect part number from annotations or media type
+ part_num = annot.get("org.trycua.lume.part.number")
+ if part_num is None and "part.number=" in mt:
+ for seg in mt.split(";"):
+ if seg.startswith("part.number="):
+ part_num = seg.split("=", 1)[1]
+
+ if part_num is not None:
+ disk_parts.append((int(part_num), layer))
+ else:
+ other_layers.append(layer)
+
+ # Download and reassemble disk parts
+ if disk_parts:
+ disk_parts.sort(key=lambda x: x[0])
+ disk_path = dest_dir / "disk.img"
+ logger.info(f" downloading {len(disk_parts)} disk parts...")
+
+ with open(disk_path, "wb") as f:
+ for part_num, layer in disk_parts:
+ digest = layer["digest"]
+ size = layer.get("size", 0)
+ logger.info(f" part {part_num}/{disk_parts[-1][0]}: {size} bytes")
+
+ resp = r.get_blob(full_repo, digest)
+ f.write(resp.content)
+
+ logger.info(f" disk image: {disk_path} ({disk_path.stat().st_size} bytes)")
+
+ # Download other layers (aux image, etc.)
+ for layer in other_layers:
+ mt = layer.get("mediaType", "")
+ digest = layer["digest"]
+ title = layer.get("annotations", {}).get("org.opencontainers.image.title", "")
+
+ if "aux" in mt.lower() or "aux" in title.lower():
+ out = dest_dir / "aux.img"
+ elif title:
+ out = dest_dir / title
+ else:
+ out = dest_dir / f"blob_{digest[:16]}"
+
+ logger.info(f" downloading {title or mt} ({layer.get('size', '?')} bytes)")
+ resp = r.get_blob(full_repo, digest)
+ out.write_bytes(resp.content)
+
+ # Download config
+ config = manifest.get("config", {})
+ if config.get("digest"):
+ resp = r.get_blob(full_repo, config["digest"])
+ (dest_dir / "config.json").write_bytes(resp.content)
diff --git a/libs/python/cua-sandbox/cua_sandbox/runtime/__init__.py b/libs/python/cua-sandbox/cua_sandbox/runtime/__init__.py
new file mode 100644
index 0000000000..d078a4ab9f
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/runtime/__init__.py
@@ -0,0 +1,26 @@
+from cua_sandbox.runtime.android_emulator import AndroidEmulatorRuntime
+from cua_sandbox.runtime.base import Runtime, RuntimeInfo
+from cua_sandbox.runtime.docker import DockerRuntime
+from cua_sandbox.runtime.hyperv import HyperVRuntime
+from cua_sandbox.runtime.lume import LumeRuntime
+from cua_sandbox.runtime.qemu import (
+ QEMUBaremetalRuntime,
+ QEMUDockerRuntime,
+ QEMURuntime,
+ QEMUWSL2Runtime,
+)
+from cua_sandbox.runtime.tart import TartRuntime
+
+__all__ = [
+ "Runtime",
+ "RuntimeInfo",
+ "DockerRuntime",
+ "QEMURuntime",
+ "QEMUDockerRuntime",
+ "QEMUBaremetalRuntime",
+ "QEMUWSL2Runtime",
+ "LumeRuntime",
+ "HyperVRuntime",
+ "AndroidEmulatorRuntime",
+ "TartRuntime",
+]
diff --git a/libs/python/cua-sandbox/cua_sandbox/runtime/_bw_init.js b/libs/python/cua-sandbox/cua_sandbox/runtime/_bw_init.js
new file mode 100644
index 0000000000..12c4e44b8c
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/runtime/_bw_init.js
@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/**
+ * Non-interactive bubblewrap project initialiser.
+ *
+ * Usage:
+ * node _bw_init.js <manifest_url> <output_dir> <package_id> \
+ * [keystore_path [keystore_alias [keystore_password [fetch_url]]]]
+ *
+ * manifest_url: The TWA origin URL (used in twa-manifest.json host field).
+ * fetch_url: Optional URL to fetch the Web App Manifest from (defaults to
+ * manifest_url). Use this when manifest_url is an
+ * emulator-internal address like http://10.0.2.2:3000 that is
+ * not reachable from the host — pass the host-accessible URL
+ * (e.g. http://127.0.0.1:3000) as fetch_url while keeping
+ * manifest_url as the in-emulator origin for assetlinks.json.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { execSync } = require('child_process');
+
+const npmPrefix = execSync('npm root -g').toString().trim();
+const BW_CLI = path.join(npmPrefix, '@bubblewrap', 'cli');
+const corePath = path.join(BW_CLI, 'node_modules', '@bubblewrap', 'core');
+const { TwaManifest } = require(path.join(corePath, 'dist/lib/TwaManifest'));
+
+const [
+ ,
+ ,
+ manifestUrl,
+ outputDir,
+ packageId,
+ keystorePath,
+ keystoreAlias,
+ keystorePassword,
+ fetchUrl,
+] = process.argv;
+
+if (!manifestUrl || !outputDir || !packageId) {
+ console.error(
+ 'Usage: node _bw_init.js <manifest_url> <output_dir> <package_id> [keystore_path [alias [password [fetch_url]]]]'
+ );
+ process.exit(1);
+}
+
+const KEYSTORE = keystorePath || path.join(outputDir, 'android.keystore');
+const KEYSTORE_ALIAS = keystoreAlias || 'android';
+const KEYSTORE_PASS = keystorePassword || 'android';
+
+// If the manifest URL uses an emulator-internal host (10.0.2.2), replace it
+// with 127.0.0.1 for fetching from the host machine.
+const resolvedFetchUrl =
+ fetchUrl || manifestUrl.replace('10.0.2.2', '127.0.0.1').replace('10.0.3.2', '127.0.0.1');
+
+(async () => {
+ try {
+ console.log(`Fetching web manifest from: ${resolvedFetchUrl}`);
+ const twa = await TwaManifest.fromWebManifest(resolvedFetchUrl);
+
+ // Override host with the in-emulator origin so assetlinks.json is verified
+ // against the address Chrome will actually use inside the emulator.
+ const originUrl = new URL(manifestUrl);
+ twa.packageId = packageId;
+ twa.host = originUrl.host; // e.g. "cuaai--todo-gym-web.modal.run"
+ // startUrl comes from Web App Manifest start_url (already parsed by fromWebManifest).
+ // Do NOT override it with the manifest file path — that would open manifest.json.
+ twa.manifestUrl = manifestUrl;
+ twa.signingKey = { path: KEYSTORE, alias: KEYSTORE_ALIAS };
+
+ const outFile = path.join(outputDir, 'twa-manifest.json');
+ const json = twa.toJson();
+ json.signingKey = {
+ path: KEYSTORE,
+ alias: KEYSTORE_ALIAS,
+ keypassword: KEYSTORE_PASS,
+ password: KEYSTORE_PASS,
+ };
+ fs.writeFileSync(outFile, JSON.stringify(json, null, 2));
+ console.log(`twa-manifest.json written to ${outFile}`);
+ console.log(` host: ${json.host} package: ${json.packageId}`);
+ } catch (e) {
+ console.error('Error:', e.message || e);
+ process.exit(1);
+ }
+})();
diff --git a/libs/python/cua-sandbox/cua_sandbox/runtime/android_emulator.py b/libs/python/cua-sandbox/cua_sandbox/runtime/android_emulator.py
new file mode 100644
index 0000000000..d833a7c871
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/runtime/android_emulator.py
@@ -0,0 +1,837 @@
+"""Android Emulator runtime — uses the official Android SDK emulator.
+
+Follows the docker-android pattern:
+ 1. Auto-installs Android command-line tools + SDK if needed
+ 2. Creates an AVD (Android Virtual Device)
+ 3. Launches the emulator with `-no-boot-anim -no-window -no-snapshot`
+ 4. Waits for `sys.boot_completed == 1` via ADB
+ 5. Supports APK installation via ADB
+
+On Apple Silicon Macs, uses ARM64 system images with HVF acceleration.
+On x86_64 hosts, uses x86_64 system images with KVM/HAXM.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import platform as _plat
+import shutil
+import socket
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+from cua_sandbox.image import Image
+from cua_sandbox.runtime.base import Runtime, RuntimeInfo
+
+logger = logging.getLogger(__name__)
+
+# ── SDK paths ────────────────────────────────────────────────────────────────
+
+_SDK_ROOT = Path.home() / ".cua" / "android-sdk"
+_AVD_HOME = Path.home() / ".cua" / "android-avd"
+_CMDLINE_TOOLS_VERSION = "11076708" # Latest as of 2024
+
+
+def _java_env() -> dict:
+ """Return env dict with JAVA_HOME set if needed."""
+ env = os.environ.copy()
+ if env.get("JAVA_HOME"):
+ return env
+ # Try Homebrew OpenJDK (macOS)
+ brew_jdk = Path("/opt/homebrew/opt/openjdk/libexec/openjdk.jdk/Contents/Home")
+ if not brew_jdk.exists():
+ # Intel Mac
+ brew_jdk = Path("/usr/local/opt/openjdk/libexec/openjdk.jdk/Contents/Home")
+ if brew_jdk.exists():
+ env["JAVA_HOME"] = str(brew_jdk)
+ env["PATH"] = f"{brew_jdk / 'bin'}:{env.get('PATH', '')}"
+ return env
+ # Check if java works without JAVA_HOME
+ try:
+ result = subprocess.run(["java", "-version"], capture_output=True, timeout=5)
+ if result.returncode == 0:
+ return env
+ except (subprocess.SubprocessError, FileNotFoundError):
+ pass
+ raise RuntimeError("Java not found. Install via: brew install openjdk")
+
+
+def _sdk_path() -> Path:
+ """Return the Android SDK root, preferring existing installations."""
+ for env in ("ANDROID_HOME", "ANDROID_SDK_ROOT"):
+ val = os.environ.get(env)
+ if val and Path(val).exists():
+ return Path(val)
+ # Check common install locations
+ common = [
+ Path.home() / "Library" / "Android" / "sdk", # Android Studio (macOS)
+ Path("/opt/android"), # docker-android
+ Path.home() / "Android" / "Sdk", # Linux
+ ]
+ for p in common:
+ if (p / "emulator").exists():
+ return p
+ return _SDK_ROOT
+
+
+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"
+
+ if emulator_bin.exists() and adb_bin.exists():
+ return sdk
+
+ logger.info(f"Android SDK not found. Installing to {sdk} ...")
+ sdk.mkdir(parents=True, exist_ok=True)
+
+ # Download command-line tools
+ if not sdkmanager_bin.exists():
+ system = _plat.system().lower()
+ if system == "darwin":
+ 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"
+ else:
+ raise RuntimeError(
+ "Android SDK auto-install not supported on Windows. Install Android Studio manually."
+ )
+
+ import urllib.request
+ import zipfile
+
+ zip_path = sdk / "cmdline-tools.zip"
+ logger.info("Downloading Android command-line tools ...")
+ urllib.request.urlretrieve(tools_url, str(zip_path))
+ with zipfile.ZipFile(zip_path) as zf:
+ zf.extractall(sdk / "cmdline-tools")
+ # Move to expected path
+ extracted = sdk / "cmdline-tools" / "cmdline-tools"
+ dest = sdk / "cmdline-tools" / "latest"
+ if extracted.exists() and not dest.exists():
+ extracted.rename(dest)
+ zip_path.unlink()
+ # Ensure scripts are executable
+ for f in (sdk / "cmdline-tools" / "latest" / "bin").iterdir():
+ f.chmod(0o755)
+
+ sdkmanager_bin = sdk / "cmdline-tools" / "latest" / "bin" / "sdkmanager"
+ if not sdkmanager_bin.exists():
+ raise RuntimeError(f"sdkmanager not found at {sdkmanager_bin}")
+
+ env = _java_env()
+
+ # Accept licenses
+ logger.info("Accepting Android SDK licenses ...")
+ subprocess.run(
+ [str(sdkmanager_bin), f"--sdk_root={sdk}", "--licenses"],
+ input=b"y\ny\ny\ny\ny\ny\ny\ny\n",
+ capture_output=True,
+ timeout=120,
+ env=env,
+ )
+
+ # Install emulator, platform-tools, and system image
+ arch = "arm64-v8a" if _plat.machine() in ("arm64", "aarch64") else "x86_64"
+ api_level = "34"
+ img_type = "google_apis"
+ package = f"system-images;android-{api_level};{img_type};{arch}"
+ platform = f"platforms;android-{api_level}"
+
+ logger.info(f"Installing Android SDK packages: {package} ...")
+ result = subprocess.run(
+ [
+ str(sdkmanager_bin),
+ f"--sdk_root={sdk}",
+ "--install",
+ package,
+ platform,
+ "platform-tools",
+ "emulator",
+ ],
+ capture_output=True,
+ text=True,
+ timeout=600,
+ env=env,
+ )
+ if result.returncode != 0:
+ raise RuntimeError(f"sdkmanager install failed: {result.stderr}")
+
+ logger.info("Android SDK installation complete.")
+ return sdk
+
+
+def _find_free_emulator_port() -> int:
+ """Return a free odd adb_port (console_port = adb_port - 1, must be even).
+
+ Scans even console ports 5554–5682; returns the first pair where both
+ console_port and adb_port are not in use (TCP bind check).
+ """
+ for console_port in range(5554, 5684, 2): # 5554, 5556, ..., 5682
+ adb_port = console_port + 1
+ free = True
+ for port in (console_port, adb_port):
+ try:
+ with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+ s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+ s.bind(("127.0.0.1", port))
+ except OSError:
+ free = False
+ break
+ if free:
+ return adb_port
+ raise RuntimeError("No free Android emulator port pair found in range 5554–5682")
+
+
+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,
+ ]
+ for c in candidates:
+ if c.exists():
+ return str(c)
+ # Fall back to PATH
+ found = shutil.which(name)
+ if found:
+ return found
+ raise FileNotFoundError(f"{name} not found in SDK at {sdk}")
+
+
+class AndroidEmulatorRuntime(Runtime):
+ """Android emulator runtime using the official Android SDK.
+
+ Creates an AVD and launches the Android emulator, following the
+ docker-android pattern. Uses ADB for boot detection, APK install,
+ and shell commands.
+ """
+
+ def __init__(
+ self,
+ *,
+ api_level: int = 34,
+ img_type: str = "google_apis",
+ device_id: str = "pixel",
+ memory_mb: int = 4096,
+ cpu_count: int = 4,
+ adb_port: Optional[int] = None,
+ no_boot_anim: bool = True,
+ gpu_mode: str = "swiftshader_indirect",
+ headless: bool = True,
+ grpc_port: Optional[int] = None,
+ ):
+ self.api_level = api_level
+ self.img_type = img_type
+ self.device_id = device_id
+ self.memory_mb = memory_mb
+ self.cpu_count = cpu_count
+ self.adb_port = adb_port
+ self.no_boot_anim = no_boot_anim
+ self.gpu_mode = gpu_mode
+ self.headless = headless
+ self.grpc_port = grpc_port
+ self._proc: Optional[subprocess.Popen] = None
+ self._avd_name: Optional[str] = None
+ self._sdk: Optional[Path] = None
+
+ async def start(self, image: Image, name: str, **opts) -> RuntimeInfo:
+ self._sdk = _ensure_sdk()
+ self._avd_name = name
+
+ # Resolve port lazily so callers don't need to pick one
+ if self.adb_port is None:
+ self.adb_port = _find_free_emulator_port()
+ logger.info(
+ f"Auto-selected emulator port: console={self.adb_port - 1}, adb={self.adb_port}"
+ )
+
+ arch = "arm64-v8a" if _plat.machine() in ("arm64", "aarch64") else "x86_64"
+ package = f"system-images;android-{self.api_level};{self.img_type};{arch}"
+ abi = f"{self.img_type}/{arch}"
+
+ avdmanager = _find_bin(self._sdk, "avdmanager")
+ emulator = _find_bin(self._sdk, "emulator")
+ adb = _find_bin(self._sdk, "adb")
+
+ # Set AVD home
+ _AVD_HOME.mkdir(parents=True, exist_ok=True)
+ env = _java_env()
+ env["ANDROID_SDK_ROOT"] = str(self._sdk)
+ env["ANDROID_AVD_HOME"] = str(_AVD_HOME)
+ env["ANDROID_EMULATOR_WAIT_TIME_BEFORE_KILL"] = "10"
+
+ # Create AVD if it doesn't exist
+ avd_dir = _AVD_HOME / f"{name}.avd"
+ if not avd_dir.exists():
+ logger.info(f"Creating AVD '{name}' with {package} ...")
+ result = subprocess.run(
+ [
+ avdmanager,
+ "create",
+ "avd",
+ "--force",
+ "--name",
+ name,
+ "--abi",
+ abi,
+ "--package",
+ package,
+ "--device",
+ self.device_id,
+ ],
+ input="no\n",
+ capture_output=True,
+ text=True,
+ env=env,
+ timeout=60,
+ )
+ if result.returncode != 0:
+ raise RuntimeError(f"AVD creation failed: {result.stderr}\n{result.stdout}")
+ logger.info(f"AVD '{name}' created.")
+
+ # Start ADB server
+ subprocess.run([adb, "start-server"], capture_output=True, env=env)
+
+ # Launch emulator
+ cmd = [
+ emulator,
+ "-avd",
+ name,
+ "-gpu",
+ self.gpu_mode,
+ "-memory",
+ str(self.memory_mb),
+ "-cores",
+ str(self.cpu_count),
+ *(["-no-window"] if self.headless else []),
+ "-no-snapshot",
+ "-skip-adb-auth",
+ "-port",
+ str(self.adb_port - 1), # console port = adb_port - 1
+ ]
+ if self.no_boot_anim:
+ cmd.append("-no-boot-anim")
+
+ # gRPC service: defaults to console_port+3000 if not specified
+ resolved_grpc_port = self.grpc_port or (self.adb_port - 1 + 3000)
+ cmd += ["-grpc", str(resolved_grpc_port)]
+
+ logger.info(f"Starting Android emulator: {' '.join(cmd)}")
+ self._proc = subprocess.Popen(
+ cmd,
+ stdout=subprocess.DEVNULL,
+ stderr=subprocess.PIPE,
+ env=env,
+ )
+
+ # Brief check that it didn't crash immediately
+ await asyncio.sleep(3)
+ if self._proc.poll() is not None:
+ stderr = self._proc.stderr.read().decode() if self._proc.stderr else ""
+ raise RuntimeError(f"Emulator crashed on launch: {stderr}")
+
+ info = RuntimeInfo(
+ host="localhost",
+ api_port=self.adb_port,
+ name=name,
+ environment="android",
+ grpc_port=resolved_grpc_port,
+ )
+
+ # Install APKs from image layers
+ await self.is_ready(info)
+ await self._apply_layers(image, adb, env)
+
+ return info
+
+ 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}"
+ for layer in image._layers:
+ lt = layer["type"]
+ if lt == "apk_install":
+ for apk in layer["packages"]:
+ # Download URL-based APKs
+ local_apk = await self._resolve_apk(apk)
+ logger.info(f"Installing APK: {local_apk}")
+ result = subprocess.run(
+ [adb, "-s", serial, "install", "-r", str(local_apk)],
+ capture_output=True,
+ text=True,
+ env=env,
+ timeout=120,
+ )
+ if result.returncode != 0:
+ logger.warning(f"APK install failed: {result.stderr}")
+ else:
+ logger.info(f"APK installed: {result.stdout.strip()}")
+ elif lt == "pwa_install":
+ 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")
+ apk_path, fingerprint = await self._build_pwa_apk(
+ manifest_url, pkg, ks, ks_alias, ks_pass
+ )
+ logger.info(
+ f"PWA APK signing fingerprint (SHA-256): {fingerprint}\n"
+ " → Set TWA_SHA256_FINGERPRINT env var on your server to this value\n"
+ f" so /.well-known/assetlinks.json is trusted by Chrome."
+ )
+ logger.info(f"Installing PWA APK: {apk_path}")
+ result = subprocess.run(
+ [adb, "-s", serial, "install", "-r", str(apk_path)],
+ capture_output=True,
+ text=True,
+ env=env,
+ timeout=120,
+ )
+ if result.returncode != 0:
+ logger.warning(f"PWA APK install failed: {result.stderr}")
+ else:
+ logger.info(f"PWA APK installed: {result.stdout.strip()}")
+ # Suppress Chrome first-run wizard so the TWA opens immediately.
+ # set-debug-app makes Chrome honour the chrome-command-line file.
+ 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",
+ ]:
+ subprocess.run(
+ [adb, "-s", serial, "shell", cmd],
+ capture_output=True,
+ env=env,
+ timeout=10,
+ )
+ elif lt == "run":
+ cmd = layer["command"]
+ logger.info(f"Running: {cmd}")
+ subprocess.run(
+ [adb, "-s", serial, "shell", cmd],
+ capture_output=True,
+ text=True,
+ env=env,
+ timeout=60,
+ )
+ elif lt == "pip_install":
+ # pip install via termux or similar — skip for now
+ logger.warning("pip_install not supported on Android emulator, skipping")
+
+ @staticmethod
+ async def _build_pwa_apk(
+ manifest_url: str,
+ package_name: Optional[str] = None,
+ keystore_path: Optional[Path] = None,
+ keystore_alias: str = "android",
+ keystore_password: str = "android",
+ ) -> tuple[Path, str]:
+ """Build a signed APK from a PWA manifest URL using Bubblewrap.
+
+ Auto-installs bubblewrap if not on PATH and auto-configures
+ ``~/.bubblewrap/config.json`` from the already-known JDK and SDK paths,
+ so no manual interactive setup is required.
+
+ Returns ``(apk_path, sha256_fingerprint)`` where ``sha256_fingerprint``
+ is the colon-separated hex digest of the signing certificate — ready to
+ embed in the server's ``/.well-known/assetlinks.json``.
+ """
+ import hashlib
+ import json as _json
+ from urllib.parse import urlparse
+
+ env = _java_env()
+ java_home = env.get("JAVA_HOME", "")
+ # Prefer Java 21 for Gradle compatibility (bubblewrap uses Gradle 8.x)
+ for _j21 in (
+ Path("/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home"),
+ Path("/usr/local/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home"),
+ ):
+ if _j21.exists():
+ java_home = str(_j21)
+ env["JAVA_HOME"] = java_home
+ env["PATH"] = f"{_j21 / 'bin'}:{env.get('PATH', '')}"
+ break
+ jdk_bin = Path(java_home) / "bin" if java_home else Path(".")
+ keytool = str(jdk_bin / "keytool") if (jdk_bin / "keytool").exists() else "keytool"
+
+ # ── 1. Ensure bubblewrap CLI is on PATH ──────────────────────────────
+ bw = shutil.which("bubblewrap")
+ if not bw:
+ node = shutil.which("node")
+ npm = shutil.which("npm")
+ if not node or not npm:
+ raise RuntimeError(
+ "node/npm not found on PATH; required for pwa_install.\n"
+ "Install Node.js: https://nodejs.org/"
+ )
+ logger.info("Installing @bubblewrap/cli …")
+ subprocess.run(
+ [npm, "install", "-g", "@bubblewrap/cli"],
+ check=True,
+ capture_output=True,
+ timeout=300,
+ )
+ bw = shutil.which("bubblewrap")
+ if not bw:
+ raise RuntimeError(
+ "bubblewrap still not found after npm install -g @bubblewrap/cli.\n"
+ "Ensure npm global bin is on PATH."
+ )
+
+ # ── 2. Auto-configure ~/.bubblewrap/config.json ──────────────────────
+ # bubblewrap expects jdkPath to be the .jdk bundle root on macOS
+ # (it appends Contents/Home internally). Gradle also requires Java ≤ 21.
+ def _bubblewrap_jdk_path() -> str:
+ """Return the .jdk bundle path suitable for bubblewrap's jdkPath.
+
+ Prefers openjdk@21 (Gradle-compatible) over newer versions.
+ On macOS returns the .jdk bundle root; elsewhere the JDK home.
+ """
+ candidates = [
+ # Prefer Java 21 — Gradle 8.x supports up to Java 21
+ Path("/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk"),
+ Path("/usr/local/opt/openjdk@21/libexec/openjdk.jdk"),
+ Path("/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk"),
+ # Fall back to whatever _java_env() found
+ Path(java_home).parent.parent if java_home.endswith("Contents/Home") else None,
+ Path(java_home) if java_home else None,
+ ]
+ for c in candidates:
+ if c and c.exists():
+ return str(c)
+ return java_home # last resort
+
+ bw_config = Path.home() / ".bubblewrap" / "config.json"
+ bw_config.parent.mkdir(parents=True, exist_ok=True)
+ if not bw_config.exists() or not _json.loads(bw_config.read_text()).get("jdkPath"):
+ sdk = _sdk_path()
+ cfg = {
+ "jdkPath": _bubblewrap_jdk_path(),
+ "androidSdkPath": str(sdk),
+ }
+ bw_config.write_text(_json.dumps(cfg, indent=2))
+ logger.info(f"Wrote ~/.bubblewrap/config.json: jdkPath={cfg['jdkPath']}")
+ else:
+ cfg = _json.loads(bw_config.read_text())
+ # Patch androidSdkPath if it no longer exists
+ if not Path(cfg.get("androidSdkPath", "")).exists():
+ cfg["androidSdkPath"] = str(_sdk_path())
+ bw_config.write_text(_json.dumps(cfg, indent=2))
+
+ # ── 2b. Ensure build-tools + tools stub (both required by bubblewrap) ─
+ sdk = Path(cfg["androidSdkPath"])
+ sdkmanager = sdk / "cmdline-tools" / "latest" / "bin" / "sdkmanager"
+ if sdkmanager.exists() and not any(
+ (sdk / "build-tools").iterdir() if (sdk / "build-tools").exists() else []
+ ):
+ logger.info("Installing Android build-tools (required by bubblewrap) …")
+ subprocess.run(
+ [str(sdkmanager), f"--sdk_root={sdk}", "build-tools;34.0.0"],
+ input=b"y\n",
+ capture_output=True,
+ timeout=300,
+ env=env,
+ )
+ # bubblewrap validates SDK by checking for tools/ or bin/ at sdk root
+ (sdk / "tools").mkdir(exist_ok=True)
+
+ # ── 3. Determine package ID and cache directory ──────────────────────
+ if not package_name:
+ 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"
+
+ cache_key = hashlib.sha256(f"{manifest_url}|{package_name}".encode()).hexdigest()[:12]
+ cache_dir = Path.home() / ".cua" / "cua-sandbox" / "pwa-cache" / cache_key
+ fingerprint_file = cache_dir / "sha256.fingerprint"
+ signed_apk = cache_dir / "app-release-signed.apk"
+
+ if signed_apk.exists() and fingerprint_file.exists():
+ fingerprint = fingerprint_file.read_text().strip()
+ logger.info(f"Using cached PWA APK: {signed_apk} fingerprint: {fingerprint}")
+ return signed_apk, fingerprint
+
+ cache_dir.mkdir(parents=True, exist_ok=True)
+
+ # ── 4. Resolve keystore ──────────────────────────────────────────────
+ if keystore_path:
+ keystore = Path(keystore_path)
+ if not keystore.exists():
+ raise RuntimeError(f"Keystore not found: {keystore}")
+ else:
+ keystore = cache_dir / "android.keystore"
+ if not keystore.exists():
+ logger.info("Generating signing keystore …")
+ subprocess.run(
+ [
+ keytool,
+ "-genkeypair",
+ "-v",
+ "-keystore",
+ str(keystore),
+ "-alias",
+ keystore_alias,
+ "-keyalg",
+ "RSA",
+ "-keysize",
+ "2048",
+ "-validity",
+ "10000",
+ "-storepass",
+ keystore_password,
+ "-keypass",
+ keystore_password,
+ "-dname",
+ "CN=CUA PWA, OU=Dev, O=CUA, L=SF, S=CA, C=US",
+ ],
+ check=True,
+ capture_output=True,
+ timeout=30,
+ )
+
+ # ── 5. Extract SHA-256 fingerprint from the keystore ─────────────────
+ fp_result = subprocess.run(
+ [
+ keytool,
+ "-list",
+ "-v",
+ "-keystore",
+ str(keystore),
+ "-alias",
+ keystore_alias,
+ "-storepass",
+ keystore_password,
+ ],
+ capture_output=True,
+ text=True,
+ timeout=15,
+ )
+ fingerprint = ""
+ for line in fp_result.stdout.splitlines():
+ if "SHA256:" in line:
+ fingerprint = line.split("SHA256:", 1)[1].strip()
+ break
+ if not fingerprint:
+ raise RuntimeError(
+ f"Could not extract SHA-256 fingerprint from keystore.\nkeytool output:\n{fp_result.stdout}"
+ )
+ fingerprint_file.write_text(fingerprint)
+ logger.info(f"Keystore SHA-256 fingerprint: {fingerprint}")
+
+ # ── 6. Generate twa-manifest.json via _bw_init.js ────────────────────
+ bw_init_js = Path(__file__).parent / "_bw_init.js"
+ node = shutil.which("node")
+ if not node:
+ raise RuntimeError("node not found on PATH; required for pwa_install")
+
+ logger.info(f"Generating twa-manifest.json for {manifest_url} …")
+ init_result = subprocess.run(
+ [
+ node,
+ str(bw_init_js),
+ manifest_url,
+ str(cache_dir),
+ package_name,
+ str(keystore),
+ keystore_alias,
+ keystore_password,
+ ],
+ capture_output=True,
+ text=True,
+ timeout=60,
+ )
+ if init_result.returncode != 0:
+ raise RuntimeError(f"_bw_init.js failed for {manifest_url}:\n{init_result.stderr}")
+
+ # ── 7. bubblewrap update → Android project ───────────────────────────
+ logger.info("Running bubblewrap update (generates Android project) …")
+ update_result = subprocess.run(
+ [bw, "update", "--skipPwaValidation"],
+ capture_output=True,
+ text=True,
+ cwd=str(cache_dir),
+ timeout=300,
+ )
+ if update_result.returncode != 0:
+ raise RuntimeError(f"bubblewrap update failed:\n{update_result.stderr}")
+
+ # ── 8. bubblewrap build → signed APK ─────────────────────────────────
+ # JAVA_HOME for gradle must point to Contents/Home, not the .jdk bundle.
+ jdk_bundle = Path(cfg.get("jdkPath", java_home))
+ contents_home = jdk_bundle / "Contents" / "Home"
+ gradle_java_home = str(contents_home) if contents_home.exists() else str(jdk_bundle)
+ bw_env = {
+ **os.environ,
+ "JAVA_HOME": gradle_java_home,
+ "BUBBLEWRAP_KEYSTORE_PASSWORD": keystore_password,
+ "BUBBLEWRAP_KEY_PASSWORD": keystore_password,
+ }
+ logger.info("Running bubblewrap build …")
+ build_result = subprocess.run(
+ [bw, "build"],
+ capture_output=True,
+ text=True,
+ cwd=str(cache_dir),
+ env=bw_env,
+ timeout=600,
+ )
+ if build_result.returncode != 0:
+ raise RuntimeError(f"bubblewrap build failed:\n{build_result.stderr}")
+
+ apks = list(cache_dir.rglob("*.apk"))
+ if not apks:
+ raise RuntimeError(
+ f"bubblewrap build succeeded but no .apk found in {cache_dir}\n"
+ f"stdout: {build_result.stdout}"
+ )
+ logger.info(f"PWA APK built: {apks[0]}")
+ return apks[0], fingerprint
+
+ @staticmethod
+ async def _resolve_apk(apk_path: str) -> Path:
+ """If apk_path is a URL, download it. Otherwise return as-is."""
+ if apk_path.startswith(("http://", "https://")):
+ import hashlib
+ import urllib.request
+
+ cache = Path.home() / ".cua" / "cua-sandbox" / "apk-cache"
+ cache.mkdir(parents=True, exist_ok=True)
+ filename = apk_path.rsplit("/", 1)[-1].split("?")[0]
+ url_hash = hashlib.sha256(apk_path.encode()).hexdigest()[:8]
+ local = cache / f"{url_hash}_{filename}"
+ if not local.exists():
+ logger.info(f"Downloading APK: {apk_path}")
+ urllib.request.urlretrieve(apk_path, str(local))
+ return local
+ return Path(apk_path)
+
+ async def is_ready(self, info: RuntimeInfo, timeout: float = 300) -> bool:
+ """Wait for `sys.boot_completed == 1` via ADB, like docker-android."""
+ sdk = self._sdk or _sdk_path()
+ adb = _find_bin(sdk, "adb")
+ serial = f"emulator-{self.adb_port - 1}"
+ env = os.environ.copy()
+ env["ANDROID_SDK_ROOT"] = str(sdk)
+
+ logger.info(f"Waiting for Android boot (timeout={timeout}s) ...")
+
+ # First wait for ADB device
+ deadline = asyncio.get_event_loop().time() + timeout
+ while asyncio.get_event_loop().time() < deadline:
+ result = subprocess.run(
+ [adb, "-s", serial, "shell", "getprop", "sys.boot_completed"],
+ capture_output=True,
+ text=True,
+ env=env,
+ timeout=10,
+ )
+ value = result.stdout.strip()
+ if value == "1":
+ logger.info(f"Android emulator {info.name} boot completed.")
+
+ # Disable animations for faster interaction (docker-android pattern)
+ for prop in [
+ "settings put global window_animation_scale 0.0",
+ "settings put global transition_animation_scale 0.0",
+ "settings put global animator_duration_scale 0.0",
+ ]:
+ subprocess.run(
+ [adb, "-s", serial, "shell", prop],
+ capture_output=True,
+ env=env,
+ )
+
+ return True
+ await asyncio.sleep(5)
+
+ raise TimeoutError(f"Android emulator {info.name} did not boot within {timeout}s")
+
+ async def list(self) -> list[dict]:
+ """List known Android emulator sandboxes from state files, checking if alive."""
+ import subprocess
+
+ from cua_sandbox import sandbox_state
+
+ states = [s for s in sandbox_state.list_all() if s.get("runtime_type") == "androidemulator"]
+ result = []
+ for s in states:
+ name = s["name"]
+ status = s.get("status", "unknown")
+ if status == "running":
+ try:
+ alive = (
+ subprocess.run(
+ ["pgrep", "-f", f"qemu.*-avd {name}"],
+ capture_output=True,
+ ).returncode
+ == 0
+ )
+ if not alive:
+ status = "stopped"
+ sandbox_state.update(name, status="stopped")
+ except FileNotFoundError:
+ pass
+ result.append(
+ {
+ "name": name,
+ "status": status,
+ "runtime_type": "androidemulator",
+ "host": s.get("host"),
+ "api_port": s.get("api_port"),
+ "os_type": s.get("os_type"),
+ }
+ )
+ return result
+
+ async def stop(self, name: str) -> None:
+ if self._proc and self._proc.poll() is None:
+ self._proc.terminate()
+ try:
+ self._proc.wait(timeout=15)
+ except subprocess.TimeoutExpired:
+ self._proc.kill()
+ self._proc = None
+
+ # Also try ADB kill
+ try:
+ sdk = self._sdk or _sdk_path()
+ adb = _find_bin(sdk, "adb")
+ subprocess.run(
+ [adb, "-s", f"emulator-{self.adb_port - 1}", "emu", "kill"],
+ capture_output=True,
+ timeout=10,
+ )
+ except Exception:
+ pass
+
+ async def take_screenshot(self) -> bytes:
+ """Take a screenshot via ADB screencap."""
+ sdk = self._sdk or _sdk_path()
+ adb = _find_bin(sdk, "adb")
+ serial = f"emulator-{self.adb_port - 1}"
+
+ # screencap to file, then pull
+ subprocess.run(
+ [adb, "-s", serial, "shell", "screencap", "-p", "/sdcard/screenshot.png"],
+ capture_output=True,
+ timeout=15,
+ )
+ result = subprocess.run(
+ [adb, "-s", serial, "exec-out", "cat", "/sdcard/screenshot.png"],
+ capture_output=True,
+ timeout=15,
+ )
+ if result.returncode == 0 and result.stdout[:4] == b"\x89PNG":
+ return result.stdout
+ raise RuntimeError("Failed to take screenshot via ADB")
diff --git a/libs/python/cua-sandbox/cua_sandbox/runtime/base.py b/libs/python/cua-sandbox/cua_sandbox/runtime/base.py
new file mode 100644
index 0000000000..5a6739c80a
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/runtime/base.py
@@ -0,0 +1,68 @@
+"""Abstract runtime — starts a VM or container from an Image spec and returns connection info."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Optional
+
+from cua_sandbox.image import Image
+
+if TYPE_CHECKING:
+ pass
+
+
+@dataclass
+class RuntimeInfo:
+ """Connection info returned after a runtime spins up."""
+
+ host: str
+ api_port: int
+ vnc_port: Optional[int] = None
+ api_key: Optional[str] = None
+ container_id: Optional[str] = None
+ name: Optional[str] = None
+ qmp_port: Optional[int] = None # Set when QMP transport should be used
+ environment: Optional[str] = None # OS type hint for QMP transport
+ agent_type: Optional[str] = None # e.g. "osworld" for OSWorld Flask server
+ guest_server_port: int = 8000 # Port the guest server listens on
+ ssh_port: Optional[int] = None # SSH port on the guest
+ ssh_username: Optional[str] = None
+ ssh_password: Optional[str] = None
+ ssh_key_filename: Optional[str] = None
+ vnc_host: Optional[str] = None # VNC host (if different from host, e.g. localhost for Tart)
+ vnc_password: Optional[str] = None
+ grpc_port: Optional[int] = (
+ None # Set when gRPC transport should be used (emulator gRPC service)
+ )
+
+
+class Runtime(ABC):
+ """Base class for local runtimes that create VMs/containers from an Image."""
+
+ @abstractmethod
+ async def start(self, image: Image, name: str, **opts) -> RuntimeInfo:
+ """Start a VM/container and return connection info."""
+
+ @abstractmethod
+ async def stop(self, name: str) -> None:
+ """Stop and clean up a VM/container."""
+
+ @abstractmethod
+ async def is_ready(self, info: RuntimeInfo, timeout: float = 120) -> bool:
+ """Wait until the computer-server inside is reachable."""
+
+ async def suspend(self, name: str) -> None:
+ """Suspend (pause/save state of) a running VM."""
+ raise NotImplementedError(f"{type(self).__name__} does not support suspend()")
+
+ async def resume(self, image: "Image", name: str, **opts) -> RuntimeInfo:
+ """Resume a suspended VM and return its RuntimeInfo."""
+ raise NotImplementedError(f"{type(self).__name__} does not support resume()")
+
+ async def list(self) -> list[dict]:
+ """List known VMs managed by this runtime.
+
+ Returns a list of dicts with at minimum: name, status.
+ """
+ raise NotImplementedError(f"{type(self).__name__} does not support list()")
diff --git a/libs/python/cua-sandbox/cua_sandbox/runtime/docker.py b/libs/python/cua-sandbox/cua_sandbox/runtime/docker.py
new file mode 100644
index 0000000000..c57aef46c5
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/runtime/docker.py
@@ -0,0 +1,254 @@
+"""Docker runtime — spins up containers with computer-server."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import subprocess
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+ from cua_sandbox.image import Image
+
+import httpx
+from cua_sandbox.image import Image
+from cua_sandbox.runtime.base import Runtime, RuntimeInfo
+from cua_sandbox.runtime.images import (
+ DEFAULT_API_PORT,
+ DEFAULT_VNC_PORT,
+ internal_ports,
+ resolve_image,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _find_free_port(start: int = 8000, end: int = 9000) -> int:
+ """Return the first TCP port in [start, end) not currently bound."""
+ import socket
+
+ for port in range(start, end):
+ with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+ s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+ try:
+ s.bind(("", port))
+ return port
+ except OSError:
+ continue
+ raise RuntimeError(f"No free port found in range {start}–{end}")
+
+
+def _has_docker() -> bool:
+ try:
+ subprocess.run(["docker", "info"], capture_output=True, check=True, timeout=10)
+ return True
+ except (subprocess.SubprocessError, FileNotFoundError):
+ return False
+
+
+def _has_kvm() -> bool:
+ """Check if /dev/kvm is available (Linux/WSL2 only)."""
+ import platform
+
+ if platform.system() != "Linux":
+ return False
+ from pathlib import Path
+
+ return Path("/dev/kvm").exists()
+
+
+class DockerRuntime(Runtime):
+ """Runs containers via ``docker run``."""
+
+ def __init__(
+ self,
+ *,
+ api_port: int = DEFAULT_API_PORT,
+ vnc_port: int = DEFAULT_VNC_PORT,
+ ephemeral: bool = True,
+ volumes: Optional[list[str]] = None,
+ environment: Optional[dict[str, str]] = None,
+ devices: Optional[list[str]] = None,
+ platform: Optional[str] = None,
+ privileged: bool = False,
+ stop_timeout: int = 120,
+ ):
+ self.api_port = api_port
+ self.vnc_port = vnc_port
+ self.ephemeral = ephemeral
+ self.volumes = volumes or []
+ self.environment = environment or {}
+ self.devices = devices or []
+ self.platform = platform
+ self.privileged = privileged
+ self.stop_timeout = stop_timeout
+
+ async def start(self, image: Image, name: str, **opts) -> RuntimeInfo:
+ if not _has_docker():
+ raise RuntimeError("Docker is not installed or not running")
+
+ docker_image = resolve_image(image.os_type, image._registry)
+ internal_api, internal_vnc = internal_ports(docker_image)
+ extra_flags: list[str] = []
+
+ if "qemu" in docker_image:
+ extra_flags += ["--cap-add", "NET_ADMIN"]
+
+ # Volume mounts
+ for v in self.volumes:
+ extra_flags += ["-v", v]
+
+ # Environment variables
+ for k, val in self.environment.items():
+ extra_flags += ["-e", f"{k}={val}"]
+
+ # Devices (e.g. /dev/kvm)
+ for d in self.devices:
+ extra_flags += ["--device", d]
+
+ # Platform (e.g. linux/amd64)
+ if self.platform:
+ extra_flags += ["--platform", self.platform]
+
+ # Privileged mode
+ if self.privileged:
+ extra_flags.append("--privileged")
+
+ # Stop timeout
+ extra_flags += ["--stop-timeout", str(self.stop_timeout)]
+
+ # Remove existing container with same name
+ 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",
+ "run",
+ "-d",
+ "--name",
+ name,
+ "--label",
+ "cua.sandbox=true",
+ "--label",
+ f"cua.sandbox.name={name}",
+ "-p",
+ f"{api_port}:{internal_api}",
+ "-p",
+ f"{vnc_port}:{internal_vnc}",
+ *extra_flags,
+ docker_image,
+ ]
+ logger.info(f"Starting container: {' '.join(cmd)}")
+ result = subprocess.run(cmd, capture_output=True, text=True)
+ if result.returncode != 0:
+ raise RuntimeError(f"docker run failed: {result.stderr}")
+
+ container_id = result.stdout.strip()[:12]
+ info = RuntimeInfo(
+ host="localhost",
+ api_port=api_port,
+ vnc_port=vnc_port,
+ container_id=container_id,
+ name=name,
+ )
+ await self.is_ready(info)
+ return info
+
+ async def stop(self, name: str) -> None:
+ subprocess.run(["docker", "stop", name], capture_output=True)
+ if self.ephemeral:
+ 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)
+
+ 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)
+ # Inspect to get mapped ports
+ result = subprocess.run(
+ [
+ "docker",
+ "inspect",
+ "--format",
+ '{{(index (index .NetworkSettings.Ports "8000/tcp") 0).HostPort}}',
+ name,
+ ],
+ capture_output=True,
+ text=True,
+ )
+ api_port = int(result.stdout.strip()) if result.stdout.strip().isdigit() else self.api_port
+ result2 = subprocess.run(
+ [
+ "docker",
+ "inspect",
+ "--format",
+ '{{(index (index .NetworkSettings.Ports "5900/tcp") 0).HostPort}}',
+ name,
+ ],
+ capture_output=True,
+ text=True,
+ )
+ vnc_port = (
+ int(result2.stdout.strip()) if result2.stdout.strip().isdigit() else self.vnc_port
+ )
+ info = RuntimeInfo(host="localhost", api_port=api_port, vnc_port=vnc_port, name=name)
+ await self.is_ready(info)
+ return info
+
+ async def list(self) -> list[dict]:
+ """List Docker containers with the cua.sandbox=true label."""
+ result = subprocess.run(
+ [
+ "docker",
+ "ps",
+ "-a",
+ "--filter",
+ "label=cua.sandbox=true",
+ "--format",
+ "{{.Names}}\t{{.Status}}",
+ ],
+ capture_output=True,
+ text=True,
+ )
+ rows = []
+ for line in result.stdout.strip().splitlines():
+ if not line:
+ continue
+ parts = line.split("\t", 1)
+ name_col = parts[0].strip()
+ raw_status = parts[1].strip() if len(parts) > 1 else ""
+ if raw_status.startswith("Up"):
+ status = "running"
+ elif raw_status.startswith("Paused") or "(Paused)" in raw_status:
+ status = "suspended"
+ elif raw_status.startswith("Exited"):
+ status = "stopped"
+ else:
+ status = raw_status.lower()
+ rows.append({"name": name_col, "status": status, "runtime_type": "docker"})
+ return rows
+
+ async def is_ready(self, info: RuntimeInfo, timeout: float = 120) -> bool:
+ url = f"http://{info.host}:{info.api_port}/status"
+ deadline = asyncio.get_event_loop().time() + timeout
+ async with httpx.AsyncClient(timeout=5) as client:
+ while asyncio.get_event_loop().time() < deadline:
+ try:
+ resp = await client.get(url)
+ if resp.status_code == 200:
+ logger.info(f"Container {info.name} is ready")
+ return True
+ except (
+ httpx.ConnectError,
+ httpx.ReadTimeout,
+ httpx.RemoteProtocolError,
+ httpx.ConnectTimeout,
+ httpx.ReadError,
+ ):
+ pass
+ await asyncio.sleep(2)
+ raise TimeoutError(f"Container {info.name} not ready after {timeout}s")
diff --git a/libs/python/cua-sandbox/cua_sandbox/runtime/hyperv.py b/libs/python/cua-sandbox/cua_sandbox/runtime/hyperv.py
new file mode 100644
index 0000000000..de9333277b
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/runtime/hyperv.py
@@ -0,0 +1,370 @@
+"""Hyper-V runtime — Windows VMs built from ISO via unattended install.
+
+Builds a Windows image from scratch using Hyper-V Gen2 VMs (hardware-accelerated),
+with the same Autounattend.xml + CUA server install as the QEMU builder.
+
+Layer chain (all VHDX, cached):
+ Layer 0 (base): base-windows-{ver}.vhdx — Windows + CUA server (built from ISO)
+ Layer 1 (user): user-{hash}.vhdx — user's .winget_install()/.run() etc
+ Layer 2 (session): session-{name}.vhdx — ephemeral per-sandbox run
+
+Requires Windows Pro/Enterprise/Education with Hyper-V enabled.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import logging
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+import httpx
+from cua_sandbox.builder.windows_unattend import (
+ create_unattend_iso,
+ download_windows_iso,
+)
+from cua_sandbox.image import Image
+from cua_sandbox.runtime.base import Runtime, RuntimeInfo
+from cua_sandbox.runtime.images import DEFAULT_API_PORT
+
+logger = logging.getLogger(__name__)
+
+CACHE_DIR = Path.home() / ".cua" / "cua-sandbox" / "hyperv"
+
+
+def _has_hyperv() -> bool:
+ try:
+ result = subprocess.run(
+ ["powershell", "-Command", "Get-Command New-VM -ErrorAction Stop"],
+ capture_output=True,
+ text=True,
+ )
+ return result.returncode == 0
+ except (subprocess.SubprocessError, FileNotFoundError):
+ return False
+
+
+def _ps(cmd: str) -> str:
+ """Run a PowerShell command and return stdout. Raises on failure."""
+ result = subprocess.run(
+ ["powershell", "-NoProfile", "-Command", cmd],
+ capture_output=True,
+ text=True,
+ )
+ if result.returncode != 0:
+ raise RuntimeError(f"PowerShell error: {result.stderr.strip()}")
+ return result.stdout.strip()
+
+
+def _create_diff_vhdx(parent: Path, child: Path) -> Path:
+ """Create a differencing VHDX with the given parent."""
+ child.parent.mkdir(parents=True, exist_ok=True)
+ _ps(f"New-VHD -ParentPath '{parent}' -Path '{child}' -Differencing")
+ logger.info(f"Created differencing VHDX: {child} (parent: {parent})")
+ return child
+
+
+class HyperVRuntime(Runtime):
+ """Runs Windows VMs via Hyper-V with layered VHDX caching.
+
+ On first use, builds a base Windows image from ISO using unattended
+ install (same Autounattend.xml as the QEMU builder). The base image
+ includes CUA computer-server pre-installed. This is cached and reused.
+
+ Each sandbox session gets its own ephemeral differencing disk on top.
+ """
+
+ def __init__(
+ self,
+ *,
+ api_port: int = DEFAULT_API_PORT,
+ switch_name: str = "Default Switch",
+ memory_mb: int = 4096,
+ cpu_count: int = 4,
+ disk_size_gb: int = 64,
+ cache_dir: Optional[Path] = None,
+ windows_iso: Optional[str] = None,
+ product_key: Optional[str] = None,
+ ):
+ self.api_port = api_port
+ self.switch_name = switch_name
+ self.memory_mb = memory_mb
+ self.cpu_count = cpu_count
+ self.disk_size_gb = disk_size_gb
+ self.cache_dir = cache_dir or CACHE_DIR
+ self.windows_iso = windows_iso
+ self.product_key = product_key
+
+ async def start(self, image: Image, name: str, **opts) -> RuntimeInfo:
+ if not _has_hyperv():
+ raise RuntimeError(
+ "Hyper-V is not available. Enable it via: "
+ "Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All"
+ )
+
+ memory = opts.get("memory_mb", self.memory_mb)
+ cpus = opts.get("cpu_count", self.cpu_count)
+ switch = opts.get("switch_name", self.switch_name)
+
+ # Build the layered VHDX chain
+ session_disk = await self._resolve_session_disk(image, name)
+
+ # Clean up any existing VM with this name
+ self._cleanup_vm(name)
+
+ logger.info(f"Creating Hyper-V VM {name} from {session_disk}")
+ _ps(
+ f"New-VM -Name '{name}' "
+ f"-MemoryStartupBytes {memory * 1024 * 1024} "
+ f"-VHDPath '{session_disk}' "
+ f"-SwitchName '{switch}' "
+ f"-Generation 2"
+ )
+ _ps(f"Set-VM -Name '{name}' -ProcessorCount {cpus}")
+ _ps(f"Set-VMFirmware -VMName '{name}' -EnableSecureBoot Off")
+ _ps(f"Start-VM -Name '{name}'")
+
+ ip = await self._wait_for_ip(name)
+ info = RuntimeInfo(host=ip, api_port=self.api_port, name=name)
+ await self.is_ready(info)
+ return info
+
+ async def _resolve_session_disk(self, image: Image, name: str) -> Path:
+ """Build the VHDX layer chain and return the session disk path.
+
+ Layer 0: base-windows-{ver}.vhdx (Windows + CUA server, cached)
+ Layer 1: user-{hash}.vhdx (user layers applied, cached) — only if image has layers
+ Layer 2: session-{name}.vhdx (ephemeral)
+ """
+ self.cache_dir.mkdir(parents=True, exist_ok=True)
+
+ version = image.version or "11"
+
+ # Layer 0: Base image (Windows + CUA server installed from ISO)
+ base = await self._ensure_base_image(version)
+
+ # Layer 1: User layers (cached, if any)
+ if image._layers:
+ layer_hash = hashlib.sha256(
+ json.dumps(list(image._layers), sort_keys=True).encode()
+ ).hexdigest()[:16]
+ user_layer = self.cache_dir / f"user-{layer_hash}.vhdx"
+ if not user_layer.exists():
+ user_layer = await self._build_user_layer(image, base, user_layer)
+ backing = user_layer
+ else:
+ backing = base
+
+ # Layer 2: Ephemeral session disk
+ sessions_dir = self.cache_dir / "sessions"
+ session_disk = sessions_dir / f"{name}.vhdx"
+ if session_disk.exists():
+ session_disk.unlink()
+ _create_diff_vhdx(backing, session_disk)
+
+ return session_disk
+
+ async def _ensure_base_image(self, version: str = "11") -> Path:
+ """Build or return cached base Windows image with CUA server installed."""
+ base_vhdx = self.cache_dir / f"base-windows-{version}.vhdx"
+ if base_vhdx.exists():
+ logger.info(f"Using cached base image: {base_vhdx}")
+ return base_vhdx
+
+ logger.info(
+ "Building base Windows image (first-time setup, ~15-30 min with Hyper-V acceleration)..."
+ )
+
+ work_dir = self.cache_dir / "build"
+ work_dir.mkdir(parents=True, exist_ok=True)
+
+ # Get Windows ISO
+ win_iso = download_windows_iso(version, work_dir, self.windows_iso)
+
+ # Create unattend ISO (no virtio drivers needed, no startup.nsh needed)
+ unattend_iso = create_unattend_iso(
+ work_dir,
+ self.product_key,
+ include_virtio_drivers=False,
+ include_startup_nsh=False,
+ )
+
+ # Create VHDX disk
+ build_vhdx = work_dir / "build-disk.vhdx"
+ if build_vhdx.exists():
+ build_vhdx.unlink()
+ _ps(f"New-VHD -Path '{build_vhdx}' -SizeBytes {self.disk_size_gb}GB -Dynamic")
+
+ vm_name = "cua-hyperv-build"
+ self._cleanup_vm(vm_name)
+
+ try:
+ # Create Gen2 VM
+ _ps(
+ f"New-VM -Name '{vm_name}' "
+ f"-MemoryStartupBytes {self.memory_mb * 1024 * 1024} "
+ f"-VHDPath '{build_vhdx}' "
+ f"-SwitchName '{self.switch_name}' "
+ f"-Generation 2"
+ )
+ _ps(f"Set-VM -Name '{vm_name}' -ProcessorCount {self.cpu_count}")
+ _ps(f"Set-VMFirmware -VMName '{vm_name}' -EnableSecureBoot Off")
+
+ # Attach Windows ISO as DVD
+ _ps(f"Add-VMDvdDrive -VMName '{vm_name}' -Path '{win_iso}'")
+ # Attach unattend ISO as second DVD
+ _ps(f"Add-VMDvdDrive -VMName '{vm_name}' -Path '{unattend_iso}'")
+
+ # Set boot order: DVD first (Windows installer), then hard drive
+ _ps(
+ f"$dvd = Get-VMDvdDrive -VMName '{vm_name}' | Where-Object {{ $_.Path -eq '{win_iso}' }}; "
+ f"Set-VMFirmware -VMName '{vm_name}' -FirstBootDevice $dvd"
+ )
+
+ # Start the VM — Windows Setup finds Autounattend.xml automatically
+ logger.info("Starting Windows unattended install via Hyper-V...")
+ _ps(f"Start-VM -Name '{vm_name}'")
+
+ # Wait for CUA server to come up (Windows install + first login + setup script)
+ ip = await self._wait_for_ip(vm_name, timeout=600)
+ logger.info(f"Build VM got IP: {ip}")
+
+ info = RuntimeInfo(host=ip, api_port=self.api_port, name=vm_name)
+ await self.is_ready(info, timeout=2700) # 45 min max
+ logger.info("CUA computer-server installed and verified!")
+
+ # Shut down cleanly
+ _ps(f"Stop-VM -Name '{vm_name}' -Force")
+ await asyncio.sleep(5)
+
+ finally:
+ # Remove DVD drives and VM definition (keep the disk)
+ try:
+ _ps(f"Get-VMDvdDrive -VMName '{vm_name}' | Remove-VMDvdDrive")
+ except RuntimeError:
+ pass
+ try:
+ _ps(f"Remove-VM -Name '{vm_name}' -Force")
+ except RuntimeError:
+ pass
+
+ # Move build disk to final cached location
+ build_vhdx.rename(base_vhdx)
+ logger.info(f"Base image cached: {base_vhdx}")
+ return base_vhdx
+
+ async def _build_user_layer(self, image: Image, parent: Path, user_layer: Path) -> Path:
+ """Apply user Image layers on top of the base image."""
+ logger.info(f"Building user layer ({len(image._layers)} layers)...")
+
+ build_disk = user_layer.with_suffix(".build.vhdx")
+ if build_disk.exists():
+ build_disk.unlink()
+ _create_diff_vhdx(parent, build_disk)
+
+ vm_name = "cua-hyperv-build-user"
+ self._cleanup_vm(vm_name)
+
+ _ps(
+ f"New-VM -Name '{vm_name}' "
+ f"-MemoryStartupBytes {self.memory_mb * 1024 * 1024} "
+ f"-VHDPath '{build_disk}' "
+ f"-SwitchName '{self.switch_name}' "
+ f"-Generation 2"
+ )
+ _ps(f"Set-VM -Name '{vm_name}' -ProcessorCount {self.cpu_count}")
+ _ps(f"Set-VMFirmware -VMName '{vm_name}' -EnableSecureBoot Off")
+ _ps(f"Start-VM -Name '{vm_name}'")
+
+ try:
+ ip = await self._wait_for_ip(vm_name, timeout=300)
+ info = RuntimeInfo(host=ip, api_port=self.api_port, name=vm_name)
+ await self.is_ready(info, timeout=300)
+
+ from cua_sandbox.builder.executor import LayerExecutor
+
+ executor = LayerExecutor(f"http://{ip}:{self.api_port}")
+ await executor.execute_layers(list(image._layers))
+
+ logger.info("User layers applied, shutting down build VM...")
+ _ps(f"Stop-VM -Name '{vm_name}' -Force")
+ await asyncio.sleep(5)
+ finally:
+ self._cleanup_vm(vm_name)
+
+ build_disk.rename(user_layer)
+ meta = user_layer.with_suffix(".json")
+ meta.write_text(
+ json.dumps(
+ {
+ "os_type": image.os_type,
+ "layers": list(image._layers),
+ "parent": str(parent),
+ },
+ indent=2,
+ )
+ )
+
+ logger.info(f"User layer cached: {user_layer}")
+ return user_layer
+
+ async def _wait_for_ip(self, name: str, timeout: float = 180) -> str:
+ deadline = asyncio.get_event_loop().time() + timeout
+ while asyncio.get_event_loop().time() < deadline:
+ try:
+ ip = _ps(
+ f"(Get-VM -Name '{name}' | Get-VMNetworkAdapter).IPAddresses "
+ f"| Where-Object {{ $_ -match '\\d+\\.\\d+\\.\\d+\\.\\d+' }} "
+ f"| Select-Object -First 1"
+ )
+ if ip and not ip.startswith("0.0.0.0"):
+ return ip
+ except RuntimeError:
+ pass
+ await asyncio.sleep(3)
+ raise TimeoutError(f"Hyper-V VM {name} did not get an IP within {timeout}s")
+
+ def _cleanup_vm(self, name: str) -> None:
+ """Stop and remove a VM if it exists."""
+ try:
+ exists = _ps(
+ f"Get-VM -Name '{name}' -ErrorAction SilentlyContinue "
+ f"| Select-Object -ExpandProperty Name"
+ )
+ if exists == name:
+ _ps(f"Stop-VM -Name '{name}' -Force -ErrorAction SilentlyContinue")
+ _ps(f"Remove-VM -Name '{name}' -Force")
+ except RuntimeError:
+ pass
+
+ async def stop(self, name: str) -> None:
+ """Stop the VM, remove it, and delete the ephemeral session disk."""
+ self._cleanup_vm(name)
+ session_disk = self.cache_dir / "sessions" / f"{name}.vhdx"
+ if session_disk.exists():
+ session_disk.unlink()
+ logger.info(f"Deleted session disk: {session_disk}")
+
+ async def is_ready(self, info: RuntimeInfo, timeout: float = 120) -> bool:
+ url = f"http://{info.host}:{info.api_port}/status"
+ deadline = asyncio.get_event_loop().time() + timeout
+ async with httpx.AsyncClient(timeout=5) as client:
+ while asyncio.get_event_loop().time() < deadline:
+ try:
+ resp = await client.get(url)
+ if resp.status_code == 200:
+ logger.info(f"Hyper-V VM {info.name} computer-server is ready")
+ return True
+ except (
+ httpx.ConnectError,
+ httpx.ReadTimeout,
+ httpx.RemoteProtocolError,
+ httpx.ConnectTimeout,
+ httpx.ReadError,
+ ):
+ pass
+ await asyncio.sleep(3)
+ raise TimeoutError(f"Hyper-V VM {info.name} computer-server not ready after {timeout}s")
diff --git a/libs/python/cua-sandbox/cua_sandbox/runtime/images.py b/libs/python/cua-sandbox/cua_sandbox/runtime/images.py
new file mode 100644
index 0000000000..bd5e787ff8
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/runtime/images.py
@@ -0,0 +1,60 @@
+"""Docker image tags, port mappings, and runtime constants."""
+
+# ── Docker image tags ────────────────────────────────────────────────────────
+
+UBUNTU_XFCE = "trycua/cua-xfce:latest"
+QEMU_LINUX = "trycua/cua-qemu-linux:latest"
+QEMU_WINDOWS = "trycua/cua-qemu-windows:latest"
+QEMU_ANDROID = "trycua/cua-qemu-android:latest"
+MACOS_SEQUOIA = "trycua/macos-sequoia:latest"
+
+# ── macOS version → OCI image ref ────────────────────────────────────────────
+# Maps macOS version strings (and codename aliases) to ghcr.io image refs.
+# Codenames: Sequoia = 15, Tahoe = 26
+MACOS_VERSION_IMAGES: dict[str, str] = {
+ "15": "ghcr.io/trycua/macos-sequoia-cua:latest",
+ "sequoia": "ghcr.io/trycua/macos-sequoia-cua:latest",
+ "26": "ghcr.io/trycua/macos-tahoe-cua:latest",
+ "tahoe": "ghcr.io/trycua/macos-tahoe-cua:latest",
+}
+
+# ── Internal ports (inside the container) ────────────────────────────────────
+
+XFCE_API_PORT = 8000
+XFCE_VNC_PORT = 6901
+
+QEMU_API_PORT = 5000
+QEMU_VNC_PORT = 8006
+
+ANDROID_API_PORT = 8000
+ANDROID_VNC_PORT = 6080
+
+LUME_API_PORT = 8443
+LUME_PROVIDER_PORT = 7777
+
+# ── Default host-side ports ──────────────────────────────────────────────────
+
+DEFAULT_API_PORT = 8000
+DEFAULT_VNC_PORT = 6901
+
+
+def resolve_image(os_type: str, registry: str | None = None) -> str:
+ """Map an os_type to a default Docker image tag."""
+ if registry:
+ return registry
+ return {
+ "linux": UBUNTU_XFCE,
+ "windows": QEMU_WINDOWS,
+ "macos": MACOS_SEQUOIA,
+ "android": QEMU_ANDROID,
+ }.get(os_type, UBUNTU_XFCE)
+
+
+def internal_ports(docker_image: str) -> tuple[int, int]:
+ """Return (api_port, vnc_port) for the given Docker image."""
+ img = docker_image.lower()
+ if "qemu-android" in img:
+ return ANDROID_API_PORT, ANDROID_VNC_PORT
+ if "qemu" in img:
+ return QEMU_API_PORT, QEMU_VNC_PORT
+ return XFCE_API_PORT, XFCE_VNC_PORT
diff --git a/libs/python/cua-sandbox/cua_sandbox/runtime/lume.py b/libs/python/cua-sandbox/cua_sandbox/runtime/lume.py
new file mode 100644
index 0000000000..a034076a4d
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/runtime/lume.py
@@ -0,0 +1,418 @@
+"""Lume runtime — macOS VMs via Apple Virtualization.framework (macOS hosts only).
+
+Requires the Lume CLI running on the host (default port 7777).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import sys
+from typing import TYPE_CHECKING
+
+import httpx
+from cua_sandbox.image import Image
+
+if TYPE_CHECKING:
+ pass
+from cua_sandbox.runtime.base import Runtime, RuntimeInfo
+from cua_sandbox.runtime.images import (
+ LUME_API_PORT,
+ LUME_PROVIDER_PORT,
+ MACOS_SEQUOIA,
+ MACOS_VERSION_IMAGES,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _lume_path() -> str | None:
+ """Return the path to the lume binary, or None if not found."""
+ # Check PATH first
+ import shutil
+
+ if shutil.which("lume"):
+ return "lume"
+ # Common install location not always in PATH (e.g. ~/.local/bin)
+ local_bin = os.path.expanduser("~/.local/bin/lume")
+ if os.path.isfile(local_bin) and os.access(local_bin, os.X_OK):
+ return local_bin
+ return None
+
+
+def _has_lume() -> bool:
+ return _lume_path() is not None
+
+
+class LumeRuntime(Runtime):
+ """Runs macOS VMs via the Lume CLI / API."""
+
+ def __init__(
+ self,
+ *,
+ lume_host: str = "localhost",
+ lume_port: int = LUME_PROVIDER_PORT,
+ api_port: int = LUME_API_PORT,
+ ):
+ self.lume_host = lume_host
+ self.lume_port = lume_port
+ self.api_port = api_port
+
+ async def start(self, image: Image, name: str, **opts) -> RuntimeInfo:
+ if not _has_lume():
+ raise RuntimeError(
+ "Lume CLI is not installed. "
+ "Install from https://github.com/trycua/cua/tree/main/libs/lume"
+ )
+
+ 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/{name}")
+ 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
+ )
+ 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.
+ try:
+ start_resp = await client.post(
+ f"{lume_url}/lume/pull/start",
+ json=pull_payload,
+ timeout=30,
+ )
+ 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,
+ )
+ 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..."
+ )
+ try:
+ pull_resp = await client.post(
+ f"{lume_url}/lume/pull",
+ json=pull_payload,
+ timeout=1800,
+ )
+ 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..."
+ )
+ 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:
+ try:
+ detail = start_resp.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,
+ )
+ 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)
+
+ 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
+
+ async def _deliver_vnc_config(self, name: str, lume_url: str) -> None:
+ """Write the current VNC port/password into ~/.vnc.env inside the VM.
+
+ Lume v0.3.x doesn't auto-deliver VNC config via VirtioFS, so the
+ computer-server inside the VM may use a stale cached port from a
+ previous run. We push the live values via `lume ssh` so the
+ computer-server always connects to the correct VNC endpoint.
+ """
+ try:
+ async with httpx.AsyncClient(timeout=10) as client:
+ resp = await client.get(f"{lume_url}/lume/vms/{name}")
+ data = resp.json()
+ vnc_url = data.get("vncUrl") or data.get("vnc_url")
+ if not vnc_url:
+ return # no VNC info — nothing to deliver
+ # Parse vnc://:PASSWORD@HOST:PORT
+ import re
+
+ m = re.match(r"vnc://:([^@]*)@[^:]+:(\d+)", vnc_url)
+ if not m:
+ return
+ password, port = m.group(1), m.group(2)
+ vnc_env = f"VNC_PORT={port}\\nVNC_PASSWORD={password}"
+ # Write vnc.env and kill the computer-server process so launchd
+ # revives it with the new config. launchctl kickstart -k fails
+ # silently from a non-GUI SSH session, so pkill is more reliable.
+ proc = await asyncio.create_subprocess_exec(
+ _lume_path() or "lume",
+ "ssh",
+ name,
+ "--",
+ f"printf '{vnc_env}' > ~/.vnc.env && "
+ "pkill -f 'python.*computer_server' 2>/dev/null || true",
+ stdout=asyncio.subprocess.DEVNULL,
+ stderr=asyncio.subprocess.DEVNULL,
+ )
+ await asyncio.wait_for(proc.wait(), timeout=30)
+ logger.info(f"Delivered VNC config to '{name}' (port {port})")
+ except Exception as exc:
+ logger.debug(f"VNC config delivery skipped for '{name}': {exc}")
+
+ async def _wait_for_ip(self, name: str, lume_url: str, timeout: float = 300) -> str:
+ deadline = asyncio.get_event_loop().time() + timeout
+ async with httpx.AsyncClient(timeout=10) as client:
+ while asyncio.get_event_loop().time() < deadline:
+ resp = await client.get(f"{lume_url}/lume/vms/{name}")
+ data = resp.json()
+ status = data.get("status", "")
+ if status == "stopped":
+ raise RuntimeError(f"Lume VM '{name}' is stopped — failed to start")
+ ip = data.get("ip_address") or data.get("ipAddress")
+ if ip and ip != "unknown" and not ip.startswith("0.0.0.0"):
+ return ip
+ await asyncio.sleep(3)
+ raise TimeoutError(f"Lume VM {name} did not get an IP within {timeout}s")
+
+ async def suspend(self, name: str) -> None:
+ """Stop (save state of) a Lume VM."""
+ lume_url = f"http://{self.lume_host}:{self.lume_port}"
+ async with httpx.AsyncClient(timeout=30) as client:
+ await client.post(f"{lume_url}/lume/vms/{name}/stop")
+
+ async def resume(self, image: "Image", name: str, **opts) -> RuntimeInfo:
+ """Start a stopped Lume VM and return its RuntimeInfo."""
+ lume_url = f"http://{self.lume_host}:{self.lume_port}"
+ async with httpx.AsyncClient(timeout=120) as client:
+ await client.post(
+ f"{lume_url}/lume/vms/{name}/run",
+ json={
+ "noDisplay": opts.get("no_display", True),
+ "sharedDirectories": opts.get("shared_directories", []),
+ },
+ timeout=120,
+ )
+ 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)
+ return info
+
+ async def list(self) -> list[dict]:
+ """List all Lume VMs."""
+ lume_url = f"http://{self.lume_host}:{self.lume_port}"
+ try:
+ async with httpx.AsyncClient(timeout=10) as client:
+ resp = await client.get(f"{lume_url}/lume/vms")
+ vms = resp.json()
+ if isinstance(vms, dict):
+ vms = vms.get("vms", [])
+ except Exception:
+ return []
+ result = []
+ for vm in vms:
+ raw = vm.get("status", "").lower()
+ if raw == "running":
+ status = "running"
+ elif raw in ("stopped", "stop"):
+ status = "suspended"
+ else:
+ status = raw
+ result.append(
+ {
+ "name": vm.get("name", ""),
+ "status": status,
+ "runtime_type": "lume",
+ "os_type": "macos",
+ "ip_address": vm.get("ip_address") or vm.get("ipAddress"),
+ }
+ )
+ return result
+
+ async def stop(self, name: str) -> None:
+ lume_url = f"http://{self.lume_host}:{self.lume_port}"
+ async with httpx.AsyncClient(timeout=30) as client:
+ await client.post(f"{lume_url}/lume/vms/{name}/stop")
+
+ async def delete(self, name: str) -> None:
+ """Stop and permanently delete a Lume VM."""
+ lume_url = f"http://{self.lume_host}:{self.lume_port}"
+ async with httpx.AsyncClient(timeout=60) as client:
+ # Stop first (ignore errors — VM may already be stopped)
+ await client.post(f"{lume_url}/lume/vms/{name}/stop")
+ await client.delete(f"{lume_url}/lume/vms/{name}")
+
+ async def is_ready(self, info: RuntimeInfo, timeout: float = 120) -> bool:
+ url = f"http://{info.host}:{info.api_port}/status"
+ deadline = asyncio.get_event_loop().time() + timeout
+ async with httpx.AsyncClient(timeout=5) as client:
+ while asyncio.get_event_loop().time() < deadline:
+ try:
+ resp = await client.get(url)
+ if resp.status_code == 200:
+ logger.info(f"Lume VM {info.name} computer-server is ready")
+ return True
+ except (
+ httpx.ConnectError,
+ httpx.ReadTimeout,
+ httpx.ConnectTimeout,
+ httpx.ReadError,
+ ):
+ pass
+ await asyncio.sleep(3)
+ raise TimeoutError(f"Lume VM {info.name} computer-server not ready after {timeout}s")
diff --git a/libs/python/cua-sandbox/cua_sandbox/runtime/qemu.py b/libs/python/cua-sandbox/cua_sandbox/runtime/qemu.py
new file mode 100644
index 0000000000..d081c83cd1
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/runtime/qemu.py
@@ -0,0 +1,1005 @@
+"""QEMU runtime — bare-metal or Docker-wrapped QEMU VMs.
+
+Two modes:
+ QEMURuntime(mode="docker") — default, uses trycua/cua-qemu-* Docker images
+ QEMURuntime(mode="bare-metal") — launches qemu-system-* directly on the host
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json as _json
+import logging
+import platform as _plat
+import shutil
+import subprocess
+from pathlib import Path
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+ from cua_sandbox.image import Image
+
+import httpx
+from cua_sandbox.image import Image
+from cua_sandbox.runtime.base import Runtime, RuntimeInfo
+from cua_sandbox.runtime.docker import DockerRuntime, _has_kvm
+from cua_sandbox.runtime.images import (
+ DEFAULT_API_PORT,
+ QEMU_VNC_PORT,
+)
+
+logger = logging.getLogger(__name__)
+
+# ── Storage directory for QEMU disk images ──────────────────────────────────
+
+QEMU_STORAGE_ROOT = Path.home() / ".cua" / "cua-sandbox" / "qemu-storage"
+
+
+async def _qmp_command(
+ host: str, port: int, command: str, arguments: Optional[dict] = None
+) -> dict:
+ """Send a single QMP command and return the response."""
+ reader, writer = await asyncio.open_connection(host, port)
+ try:
+ # Read greeting
+ await asyncio.wait_for(reader.readline(), timeout=5)
+ # Negotiate capabilities
+ writer.write(b'{"execute":"qmp_capabilities"}\n')
+ await writer.drain()
+ await asyncio.wait_for(reader.readline(), timeout=5)
+ # Send command
+ msg: dict = {"execute": command}
+ if arguments:
+ msg["arguments"] = arguments
+ writer.write((_json.dumps(msg) + "\n").encode())
+ await writer.drain()
+ raw = await asyncio.wait_for(reader.readline(), timeout=30)
+ return _json.loads(raw)
+ finally:
+ writer.close()
+ try:
+ await writer.wait_closed()
+ except Exception:
+ pass
+
+
+class QEMUDockerRuntime(DockerRuntime):
+ """QEMU inside Docker — delegates to DockerRuntime with QEMU image tags.
+
+ For Windows QEMU images, automatically:
+ - Creates a /storage volume mount for the QEMU disk
+ - Sets KVM=N if /dev/kvm is not available
+ - Mounts an existing cached disk image if available
+ """
+
+ def __init__(
+ self,
+ *,
+ api_port: int = DEFAULT_API_PORT,
+ vnc_port: int = QEMU_VNC_PORT,
+ ephemeral: bool = True,
+ storage_dir: Optional[str | Path] = None,
+ memory_mb: int = 8192,
+ cpu_count: int = 4,
+ ):
+ self._storage_dir = Path(storage_dir) if storage_dir else None
+ self._memory_mb = memory_mb
+ self._cpu_count = cpu_count
+ super().__init__(api_port=api_port, vnc_port=vnc_port, ephemeral=ephemeral)
+
+ async def start(self, image: Image, name: str, **opts) -> RuntimeInfo:
+ # Resolve storage directory
+ storage = self._storage_dir or QEMU_STORAGE_ROOT / name
+ storage.mkdir(parents=True, exist_ok=True)
+
+ # Volume: host storage dir → /storage in container
+ self.volumes = [f"{storage}:/storage"]
+
+ # Environment
+ self.environment = {
+ "RAM_SIZE": f"{self._memory_mb // 1024}G",
+ "CPU_CORES": str(self._cpu_count),
+ }
+
+ # KVM handling
+ if _has_kvm():
+ self.devices = ["/dev/kvm"]
+ else:
+ self.environment["KVM"] = "N"
+
+ # Platform — QEMU Windows/Android images are linux/amd64
+ if image.os_type in ("windows", "android"):
+ self.platform = "linux/amd64"
+
+ # Android: forward ADB port (5555) in addition to API
+ if image.os_type == "android":
+ self.environment["ADB_PORT"] = "5555"
+
+ # Longer boot timeout for Windows/Android VMs
+ opts.pop("boot_timeout", None)
+
+ info = await super().start(image, name, **opts)
+ return info
+
+ async def is_ready(self, info: RuntimeInfo, timeout: float = 300) -> bool:
+ """Wait for the QEMU VM's computer-server to come up.
+
+ Windows VMs take longer to boot (3-5 min), so default timeout is 300s.
+ """
+ return await super().is_ready(info, timeout=timeout)
+
+ async def suspend(self, name: str) -> None:
+ """Pause the Docker container running this QEMU VM."""
+ subprocess.run(["docker", "pause", name], capture_output=True)
+
+ async def resume(self, image: "Image", name: str, **opts) -> RuntimeInfo:
+ """Unpause the Docker container and return RuntimeInfo."""
+ subprocess.run(["docker", "unpause", name], capture_output=True)
+ result = subprocess.run(
+ [
+ "docker",
+ "inspect",
+ "--format",
+ '{{(index (index .NetworkSettings.Ports "8000/tcp") 0).HostPort}}',
+ name,
+ ],
+ capture_output=True,
+ text=True,
+ )
+ api_port = int(result.stdout.strip()) if result.stdout.strip().isdigit() else self.api_port
+ info = RuntimeInfo(host="localhost", api_port=api_port, vnc_port=self.vnc_port, name=name)
+ await self.is_ready(info)
+ return info
+
+
+class QEMUBaremetalRuntime(Runtime):
+ """Bare-metal QEMU — launches qemu-system-* directly on the host.
+
+ Requires:
+ - qemu-system-x86_64 (or qemu-system-aarch64) on PATH
+ - A disk image (qcow2/vhdx/raw) with computer-server pre-installed,
+ provided via Image.from_file('/path/to/disk.qcow2')
+ """
+
+ def __init__(
+ self,
+ *,
+ api_port: int = DEFAULT_API_PORT,
+ vnc_display: int = 0,
+ memory_mb: int = 4096,
+ cpu_count: int = 2,
+ arch: str = "x86_64",
+ qmp_port: int = 4444,
+ use_qmp_transport: bool = False,
+ extra_args: Optional[list[str]] = None,
+ ):
+ self.api_port = api_port
+ self.vnc_display = vnc_display
+ self.memory_mb = memory_mb
+ self.cpu_count = cpu_count
+ self.arch = arch
+ self.qmp_port = qmp_port
+ self.use_qmp_transport = use_qmp_transport
+ self.extra_args = extra_args or []
+ self._processes: dict[str, subprocess.Popen] = {}
+
+ def _qemu_bin(self) -> str:
+ from cua_sandbox.runtime.qemu_installer import qemu_bin
+
+ return qemu_bin(self.arch)
+
+ @staticmethod
+ def _create_disk_for_iso(name: str, size_gb: int = 32) -> Path:
+ """Create a qcow2 disk image for ISO-based installations.
+
+ The disk is stored alongside other QEMU storage and reused across sessions.
+ """
+ disk_dir = QEMU_STORAGE_ROOT / name
+ disk_dir.mkdir(parents=True, exist_ok=True)
+ disk_path = disk_dir / "disk.qcow2"
+ if not disk_path.exists():
+ result = subprocess.run(
+ ["qemu-img", "create", "-f", "qcow2", str(disk_path), f"{size_gb}G"],
+ capture_output=True,
+ text=True,
+ )
+ if result.returncode != 0:
+ raise RuntimeError(f"qemu-img create failed: {result.stderr}")
+ return disk_path
+
+ async def start(self, image: Image, name: str, **opts) -> RuntimeInfo:
+ ephemeral = opts.pop("ephemeral", True)
+
+ # If image has layers or no direct disk path, use the builder to resolve
+ if not opts.get("disk_path") and not image._disk_path and image.kind == "vm":
+ from cua_sandbox.builder.build import create_session_disk
+
+ disk_path = str(await create_session_disk(image, name))
+ elif image._layers and (image._disk_path or opts.get("disk_path")):
+ # Has a base disk AND user layers — build user image + session overlay
+ from cua_sandbox.builder.build import create_session_disk
+
+ base = Path(opts.get("disk_path") or image._disk_path)
+ disk_path = str(await create_session_disk(image, name, base_disk=base))
+ else:
+ disk_path = opts.get("disk_path") or image._disk_path
+
+ if not disk_path:
+ raise ValueError(
+ "Bare-metal QEMU requires a disk image path. "
+ "Use Image.from_file('/path/to/disk.qcow2') or pass disk_path='...'"
+ )
+
+ # Handle ISO files — create a qcow2 disk and boot from ISO as CD-ROM
+ self._iso_path: Optional[str] = None
+ if Path(disk_path).suffix.lower() == ".iso":
+ self._iso_path = disk_path
+ disk_path = str(self._create_disk_for_iso(name, opts.get("disk_size_gb", 32)))
+ logger.info(f"Created qcow2 disk for ISO install: {disk_path}")
+
+ self._session_disk = Path(disk_path) if ephemeral else None
+
+ from cua_sandbox.runtime.docker import _find_free_port
+
+ memory = opts.get("memory_mb", self.memory_mb)
+ cpus = opts.get("cpu_count", self.cpu_count)
+ vnc_display = opts.get("vnc_display", self.vnc_display)
+ hostfwd_port = opts.get("api_port") or _find_free_port(self.api_port)
+ enable_kvm = opts.get("enable_kvm", True)
+
+ # Detect guest server port from transport hint
+ guest_port = 5000 if image._agent_type == "osworld" else 8000
+
+ # Detect disk format from extension
+ disk_ext = Path(disk_path).suffix.lower()
+ disk_fmt = {".qcow2": "qcow2", ".vhdx": "vhdx", ".raw": "raw", ".img": "raw"}.get(
+ disk_ext, "raw"
+ )
+
+ # Locate OVMF UEFI firmware for Windows VMs
+ qemu_dir = Path(self._qemu_bin()).parent
+ ovmf_code = None
+ if image.os_type == "windows":
+ for candidate in [
+ qemu_dir / "share" / "edk2-x86_64-code.fd",
+ Path("/usr/share/OVMF/OVMF_CODE.fd"),
+ Path("/usr/share/qemu/edk2-x86_64-code.fd"),
+ ]:
+ if candidate.exists():
+ ovmf_code = candidate
+ break
+
+ # EFI vars — look next to disk or copy template
+ efivars = Path(disk_path).parent / "efivars.fd"
+ if ovmf_code and not efivars.exists():
+ import shutil as _shutil
+
+ vars_template = qemu_dir / "share" / "edk2-i386-vars.fd"
+ if vars_template.exists():
+ _shutil.copy2(vars_template, efivars)
+ else:
+ efivars.write_bytes(b"\x00" * (256 * 1024))
+
+ # Build QEMU command — Android gets different machine/device config
+ is_android = image.os_type == "android"
+
+ if is_android:
+ cmd = self._build_android_cmd(
+ name,
+ disk_path,
+ disk_fmt,
+ memory,
+ cpus,
+ hostfwd_port,
+ vnc_display,
+ enable_kvm,
+ )
+ else:
+ cmd = [
+ self._qemu_bin(),
+ "-name",
+ name,
+ "-machine",
+ "q35,smm=off",
+ "-m",
+ str(memory),
+ "-smp",
+ str(cpus),
+ "-cpu",
+ "qemu64,+ssse3,+sse4.1,+sse4.2,+popcnt",
+ ]
+
+ # UEFI firmware (Windows requires this)
+ if ovmf_code:
+ cmd += [
+ "-drive",
+ f"if=pflash,format=raw,readonly=on,file={ovmf_code}",
+ "-drive",
+ f"if=pflash,format=raw,file={efivars}",
+ ]
+
+ cmd += [
+ "-drive",
+ f"file={disk_path},format={disk_fmt},if=virtio",
+ "-netdev",
+ f"user,id=net0,restrict=on,hostfwd=tcp:127.0.0.1:{hostfwd_port}-:{guest_port}",
+ "-device",
+ "virtio-net-pci,netdev=net0,mac=52:55:00:d1:55:01",
+ "-vnc",
+ f":{vnc_display}",
+ ]
+
+ # -daemonize not supported on Windows
+ if _plat.system() != "Windows":
+ cmd.append("-daemonize")
+
+ if enable_kvm:
+ if _plat.system() == "Darwin":
+ host_arm = _plat.machine() in ("arm64", "aarch64")
+ guest_x86 = self.arch == "x86_64"
+ if host_arm and guest_x86:
+ # Apple Silicon can't HVF-accelerate x86_64 guests
+ cmd += ["-accel", "tcg"]
+ else:
+ cmd += ["-accel", "hvf"]
+ elif _plat.system() != "Windows":
+ cmd.append("-enable-kvm")
+ elif ovmf_code:
+ # WHPX has MMIO bugs with OVMF pflash — use TCG for UEFI VMs
+ cmd += ["-accel", "tcg"]
+ else:
+ cmd += ["-accel", "whpx"]
+
+ # QMP socket — always enabled for VM management (suspend/resume)
+ cmd += ["-qmp", f"tcp:127.0.0.1:{self.qmp_port},server,nowait"]
+
+ # Attach ISO as CD-ROM if booting from an ISO file
+ if self._iso_path:
+ cmd += ["-cdrom", self._iso_path, "-boot", "d"]
+
+ cmd.extend(self.extra_args)
+
+ logger.info(f"Starting bare-metal QEMU: {' '.join(cmd)}")
+ if "-daemonize" in cmd:
+ # daemonize mode: QEMU forks to background and parent exits immediately
+ result = subprocess.run(cmd, capture_output=True, text=True)
+ if result.returncode != 0:
+ raise RuntimeError(f"QEMU launch failed: {result.stderr}")
+ else:
+ # Popen mode: keep reference to the process (Windows, or when -daemonize removed)
+ proc = subprocess.Popen(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE)
+ self._processes[name] = proc
+ import time
+
+ time.sleep(2)
+ if proc.poll() is not None:
+ stderr = proc.stderr.read().decode() if proc.stderr else ""
+ raise RuntimeError(f"QEMU launch failed (exit {proc.returncode}): {stderr}")
+
+ use_qmp = is_android or self.use_qmp_transport
+ info = RuntimeInfo(
+ host="localhost",
+ api_port=hostfwd_port,
+ vnc_port=5900 + vnc_display,
+ name=name,
+ qmp_port=self.qmp_port if use_qmp else None,
+ environment=image.os_type if use_qmp else None,
+ agent_type=image._agent_type,
+ guest_server_port=guest_port if not is_android else 8000,
+ )
+
+ # For ISO boots, send Enter key via QMP to skip GRUB countdown
+ if self._iso_path and use_qmp:
+ await self._send_boot_key(info)
+
+ # Windows and Android need much longer to boot (3–10 min)
+ boot_timeout = 600 if image.os_type in ("windows", "android") else 120
+ await self.is_ready(info, timeout=boot_timeout)
+
+ if not ephemeral:
+ from cua_sandbox import sandbox_state
+
+ sandbox_state.save(
+ name,
+ runtime_type="qemu-baremetal",
+ image=image.to_dict(),
+ host="localhost",
+ api_port=hostfwd_port,
+ vnc_port=5900 + vnc_display,
+ qmp_port=self.qmp_port,
+ disk_path=str(disk_path) if disk_path else None,
+ os_type=image.os_type,
+ vnc_display=vnc_display,
+ memory_mb=memory,
+ cpu_count=cpus,
+ arch=self.arch,
+ status="running",
+ )
+
+ return info
+
+ async def _send_boot_key(self, info: RuntimeInfo) -> None:
+ """Send Enter key via QMP repeatedly to skip GRUB/bootloader countdown.
+
+ GRUB may not be ready immediately after QEMU starts (especially with TCG),
+ so we send Enter multiple times over several seconds to ensure it lands.
+ """
+
+ for attempt in range(15):
+ try:
+ reader, writer = await asyncio.open_connection(info.host, info.qmp_port)
+ await asyncio.wait_for(reader.readline(), timeout=3)
+ writer.write(b'{"execute":"qmp_capabilities"}\n')
+ await writer.drain()
+ await asyncio.wait_for(reader.readline(), timeout=3)
+ # Send Enter key several times with delays to catch GRUB at the right moment
+ for i in range(5):
+ writer.write(
+ b'{"execute":"send-key","arguments":{"keys":[{"type":"qcode","data":"ret"}]}}\n'
+ )
+ await writer.drain()
+ await asyncio.wait_for(reader.readline(), timeout=3)
+ await asyncio.sleep(2)
+ writer.close()
+ await writer.wait_closed()
+ logger.info(f"Sent boot Enter keys to {info.name}")
+ return
+ except (ConnectionRefusedError, OSError, asyncio.TimeoutError):
+ await asyncio.sleep(2)
+ logger.warning(f"Could not send boot keys to {info.name}")
+
+ def _build_android_cmd(
+ self,
+ name: str,
+ disk_path: str,
+ disk_fmt: str,
+ memory: int,
+ cpus: int,
+ hostfwd_port: int,
+ vnc_display: int,
+ enable_kvm: bool,
+ ) -> list[str]:
+ """Build QEMU command for Android x86_64 VM.
+
+ Android-x86 boots from a disk image with GRUB, uses virtio for
+ disk/net, and needs a GPU (virtio-gpu or std) for the display.
+ Port-forwards host:hostfwd_port -> guest:8000 for the computer-server
+ API, and host:5555 -> guest:5555 for ADB.
+ """
+ cmd = [
+ self._qemu_bin(),
+ "-name",
+ name,
+ "-machine",
+ "q35,smm=off",
+ "-m",
+ str(memory),
+ "-smp",
+ str(cpus),
+ ]
+
+ # CPU config — use HVF on macOS (aarch64 only), KVM on Linux, TCG fallback
+ if _plat.system() == "Darwin":
+ # HVF only works when host and guest arch match.
+ # Apple Silicon (arm64) can't HVF-accelerate x86_64 guests.
+ host_arm = _plat.machine() in ("arm64", "aarch64")
+ guest_x86 = self.arch == "x86_64"
+ if enable_kvm and not (host_arm and guest_x86):
+ cmd += ["-cpu", "host", "-accel", "hvf"]
+ else:
+ cmd += ["-cpu", "max", "-accel", "tcg"]
+ elif enable_kvm and _plat.system() != "Windows":
+ cmd += ["-cpu", "host", "-enable-kvm"]
+ else:
+ cmd += ["-cpu", "qemu64,+ssse3,+sse4.1,+sse4.2,+popcnt"]
+
+ # Disk — Android-x86 image
+ cmd += ["-drive", f"file={disk_path},format={disk_fmt},if=virtio"]
+
+ # Networking — forward API (8000); ADB forwarded on api_port+1
+ adb_port = hostfwd_port + 1
+ cmd += [
+ "-netdev",
+ (
+ f"user,id=net0,"
+ f"hostfwd=tcp:127.0.0.1:{hostfwd_port}-:8000,"
+ f"hostfwd=tcp:127.0.0.1:{adb_port}-:5555"
+ ),
+ "-device",
+ "virtio-net-pci,netdev=net0",
+ ]
+
+ # Display — std VGA for broad compatibility (virtio-gpu hangs on Apple Silicon TCG)
+ cmd += [
+ "-vga",
+ "std",
+ "-vnc",
+ f":{vnc_display}",
+ "-display",
+ "none",
+ ]
+
+ # USB tablet for absolute pointer (touch input)
+ cmd += ["-usb", "-device", "usb-tablet"]
+
+ # QMP socket for direct VM control (mouse/keyboard/screenshot without guest agent)
+ cmd += ["-qmp", f"tcp:127.0.0.1:{self.qmp_port},server,nowait"]
+
+ # Daemonize on Unix
+ if _plat.system() != "Windows":
+ cmd.append("-daemonize")
+
+ return cmd
+
+ async def stop(self, name: str) -> None:
+ # Try to kill tracked process first
+ proc = self._processes.pop(name, None)
+ if proc and proc.poll() is None:
+ proc.terminate()
+ try:
+ proc.wait(timeout=10)
+ except subprocess.TimeoutExpired:
+ proc.kill()
+ else:
+ # Fallback: find by name
+ try:
+ if shutil.which("pkill"):
+ # Match both standard QEMU VMs (-name {name}) and Android emulators (-avd {name})
+ subprocess.run(["pkill", "-f", f"qemu.*-name {name}"], capture_output=True)
+ subprocess.run(["pkill", "-f", f"qemu.*-avd {name}"], capture_output=True)
+ else:
+ subprocess.run(
+ ["taskkill", "/F", "/FI", f"WINDOWTITLE eq {name}*"],
+ capture_output=True,
+ )
+ except Exception as e:
+ logger.warning(f"Failed to stop QEMU VM {name}: {e}")
+
+ # Clean up ephemeral session disk
+ session_disk = getattr(self, "_session_disk", None)
+ if session_disk and session_disk.exists() and "sessions" in str(session_disk):
+ try:
+ session_disk.unlink()
+ logger.info(f"Removed session disk: {session_disk}")
+ except OSError:
+ pass
+
+ from cua_sandbox import sandbox_state
+
+ sandbox_state.delete(name)
+
+ async def is_ready(self, info: RuntimeInfo, timeout: float = 120) -> bool:
+ if info.qmp_port and not info.agent_type:
+ return await self._is_ready_qmp(info, timeout)
+ # For OSWorld, check the Flask server; for computer-server, check /status
+ endpoint = "/screenshot" if info.agent_type == "osworld" else "/status"
+ url = f"http://{info.host}:{info.api_port}{endpoint}"
+ deadline = asyncio.get_event_loop().time() + timeout
+ async with httpx.AsyncClient(timeout=10) as client:
+ while asyncio.get_event_loop().time() < deadline:
+ try:
+ resp = await client.get(url)
+ if resp.status_code == 200:
+ logger.info(f"Bare-metal QEMU VM {info.name} is ready")
+ return True
+ except (
+ httpx.ConnectError,
+ httpx.ReadTimeout,
+ httpx.ReadError,
+ httpx.RemoteProtocolError,
+ httpx.ConnectTimeout,
+ ):
+ pass
+ await asyncio.sleep(3)
+ raise TimeoutError(f"Bare-metal QEMU VM {info.name} not ready after {timeout}s")
+
+ async def suspend(self, name: str) -> None:
+ """Save VM state via QMP savevm then quit QEMU."""
+ from cua_sandbox import sandbox_state
+
+ state = sandbox_state.load(name)
+ qmp_port = state["qmp_port"] if state else self.qmp_port
+ try:
+ await _qmp_command("localhost", qmp_port, "stop")
+ await _qmp_command("localhost", qmp_port, "savevm", {"name": "cua-snapshot"})
+ await _qmp_command("localhost", qmp_port, "quit")
+ except Exception as e:
+ logger.warning(f"QMP savevm failed for {name}: {e}")
+ raise
+ sandbox_state.update(name, status="suspended")
+
+ async def resume(self, image: "Image", name: str, **opts) -> RuntimeInfo:
+ """Relaunch QEMU with -loadvm to restore saved state."""
+ from cua_sandbox import sandbox_state
+
+ state = sandbox_state.load(name)
+ if state is None:
+ raise ValueError(f"No state file found for sandbox '{name}'. Cannot resume.")
+
+ # Reconstruct runtime params from state
+ disk_path = state.get("disk_path")
+ if not disk_path:
+ raise ValueError(
+ f"State for '{name}' has no disk_path — cannot resume bare-metal QEMU."
+ )
+
+ api_port = state.get("api_port", self.api_port)
+ vnc_display = state.get("vnc_display", self.vnc_display)
+ memory = state.get("memory_mb", self.memory_mb)
+ cpus = state.get("cpu_count", self.cpu_count)
+ qmp_port = state.get("qmp_port", self.qmp_port)
+
+ # Rebuild minimal QEMU command with -loadvm
+ cmd = [
+ self._qemu_bin(),
+ "-name",
+ name,
+ "-machine",
+ "q35,smm=off",
+ "-m",
+ str(memory),
+ "-smp",
+ str(cpus),
+ "-cpu",
+ "qemu64,+ssse3,+sse4.1,+sse4.2,+popcnt",
+ ]
+
+ import platform as _platform
+
+ disk_ext = Path(disk_path).suffix.lower()
+ disk_fmt = {".qcow2": "qcow2", ".vhdx": "vhdx", ".raw": "raw", ".img": "raw"}.get(
+ disk_ext, "raw"
+ )
+ guest_port = 8000
+
+ cmd += [
+ "-drive",
+ f"file={disk_path},format={disk_fmt},if=virtio",
+ "-netdev",
+ f"user,id=net0,restrict=on,hostfwd=tcp:127.0.0.1:{api_port}-:{guest_port}",
+ "-device",
+ "virtio-net-pci,netdev=net0,mac=52:55:00:d1:55:01",
+ "-vnc",
+ f":{vnc_display}",
+ "-qmp",
+ f"tcp:127.0.0.1:{qmp_port},server,nowait",
+ "-loadvm",
+ "cua-snapshot",
+ ]
+
+ if _platform.system() != "Windows":
+ cmd.append("-daemonize")
+
+ # Acceleration
+ if _platform.system() == "Darwin":
+ host_arm = _platform.machine() in ("arm64", "aarch64")
+ if host_arm and self.arch == "x86_64":
+ cmd += ["-accel", "tcg"]
+ else:
+ cmd += ["-accel", "hvf"]
+ elif _platform.system() != "Windows":
+ cmd.append("-enable-kvm")
+
+ logger.info(f"Resuming bare-metal QEMU from snapshot: {' '.join(cmd)}")
+ if "-daemonize" in cmd:
+ result = subprocess.run(cmd, capture_output=True, text=True)
+ if result.returncode != 0:
+ raise RuntimeError(f"QEMU resume failed: {result.stderr}")
+ else:
+ proc = subprocess.Popen(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE)
+ self._processes[name] = proc
+ import time
+
+ time.sleep(2)
+ if proc.poll() is not None:
+ stderr = proc.stderr.read().decode() if proc.stderr else ""
+ raise RuntimeError(f"QEMU resume failed (exit {proc.returncode}): {stderr}")
+
+ info = RuntimeInfo(
+ host="localhost",
+ api_port=api_port,
+ vnc_port=5900 + vnc_display,
+ name=name,
+ )
+ await self.is_ready(info)
+ sandbox_state.update(name, status="running")
+ return info
+
+ async def list(self) -> list[dict]:
+ """List known bare-metal QEMU sandboxes from state files, checking if alive."""
+ from cua_sandbox import sandbox_state
+
+ states = [s for s in sandbox_state.list_all() if s.get("runtime_type") == "qemu-baremetal"]
+ result = []
+ for s in states:
+ name = s["name"]
+ status = s.get("status", "unknown")
+ # Verify QEMU process is still running (standard VMs use -name, Android uses -avd)
+ if status == "running":
+ try:
+ alive = (
+ subprocess.run(
+ ["pgrep", "-f", f"qemu.*-name {name}"], capture_output=True
+ ).returncode
+ == 0
+ or subprocess.run(
+ ["pgrep", "-f", f"qemu.*-avd {name}"], capture_output=True
+ ).returncode
+ == 0
+ )
+ if not alive:
+ status = "stopped"
+ sandbox_state.update(name, status="stopped")
+ except FileNotFoundError:
+ pass
+ result.append(
+ {
+ "name": name,
+ "status": status,
+ "runtime_type": "qemu-baremetal",
+ "os_type": s.get("os_type"),
+ "host": s.get("host"),
+ "api_port": s.get("api_port"),
+ }
+ )
+ return result
+
+ async def _is_ready_qmp(self, info: RuntimeInfo, timeout: float = 120) -> bool:
+ """Wait until QMP socket is responsive (for VMs without computer-server)."""
+ import json as _json
+
+ deadline = asyncio.get_event_loop().time() + timeout
+ while asyncio.get_event_loop().time() < deadline:
+ try:
+ reader, writer = await asyncio.open_connection(info.host, info.qmp_port)
+ # Read QMP greeting
+ greeting = await asyncio.wait_for(reader.readline(), timeout=3)
+ if greeting:
+ data = _json.loads(greeting)
+ if "QMP" in data:
+ writer.close()
+ await writer.wait_closed()
+ logger.info(f"Bare-metal QEMU VM {info.name} QMP ready")
+ return True
+ writer.close()
+ await writer.wait_closed()
+ except (ConnectionRefusedError, OSError, asyncio.TimeoutError):
+ pass
+ await asyncio.sleep(2)
+ raise TimeoutError(f"Bare-metal QEMU VM {info.name} QMP not ready after {timeout}s")
+
+
+def _win_to_wsl(p: Path | str) -> str:
+ """Convert a Windows path to WSL /mnt/... path."""
+ s = str(p).replace("\\", "/")
+ # C:/foo → /mnt/c/foo
+ if len(s) >= 2 and s[1] == ":":
+ return f"/mnt/{s[0].lower()}{s[2:]}"
+ return s
+
+
+class QEMUWSL2Runtime(Runtime):
+ """QEMU via WSL2 with KVM hardware acceleration.
+
+ Runs qemu-system-x86_64 inside WSL2 where /dev/kvm is available,
+ while keeping disk images on the Windows filesystem. Windows paths
+ are automatically converted to /mnt/c/... paths for WSL access.
+
+ This is the fastest way to run QEMU on Windows — native KVM speeds
+ vs TCG software emulation (bare-metal Windows) or Hyper-V (needs admin).
+ """
+
+ def __init__(
+ self,
+ *,
+ api_port: int = DEFAULT_API_PORT,
+ vnc_display: int = 0,
+ memory_mb: int = 4096,
+ cpu_count: int = 4,
+ arch: str = "x86_64",
+ extra_args: Optional[list[str]] = None,
+ ):
+ self.api_port = api_port
+ self.vnc_display = vnc_display
+ self.memory_mb = memory_mb
+ self.cpu_count = cpu_count
+ self.arch = arch
+ self.extra_args = extra_args or []
+ self._processes: dict[str, subprocess.Popen] = {}
+
+ @staticmethod
+ def _wsl(cmd: str, timeout: float = 30) -> str:
+ """Run a command inside WSL2 and return stdout."""
+ r = subprocess.run(
+ ["wsl", "-e", "bash", "-c", cmd],
+ capture_output=True,
+ text=True,
+ timeout=timeout,
+ )
+ if r.returncode != 0:
+ raise RuntimeError(f"WSL command failed: {r.stderr.strip()}")
+ return r.stdout.strip()
+
+ @staticmethod
+ def available() -> bool:
+ """Check if WSL2 + QEMU + KVM are available."""
+ try:
+ r = subprocess.run(
+ ["wsl", "-e", "bash", "-c", "test -e /dev/kvm && which qemu-system-x86_64"],
+ capture_output=True,
+ timeout=10,
+ )
+ return r.returncode == 0
+ except (subprocess.SubprocessError, FileNotFoundError):
+ return False
+
+ async def start(self, image: Image, name: str, **opts) -> RuntimeInfo:
+ ephemeral = opts.pop("ephemeral", True)
+
+ # Resolve disk path
+ if not opts.get("disk_path") and not image._disk_path and image.kind == "vm":
+ from cua_sandbox.builder.build import create_session_disk
+
+ disk_path = str(await create_session_disk(image, name))
+ elif image._layers and (image._disk_path or opts.get("disk_path")):
+ from cua_sandbox.builder.build import create_session_disk
+
+ base = Path(opts.get("disk_path") or image._disk_path)
+ disk_path = str(await create_session_disk(image, name, base_disk=base))
+ else:
+ disk_path = opts.get("disk_path") or image._disk_path
+
+ if not disk_path:
+ raise ValueError(
+ "WSL2 QEMU requires a disk image path. "
+ "Use Image.from_file('/path/to/disk.qcow2') or pass disk_path='...'"
+ )
+
+ self._session_disk = Path(disk_path) if ephemeral else None
+
+ memory = opts.get("memory_mb", self.memory_mb)
+ cpus = opts.get("cpu_count", self.cpu_count)
+ vnc_display = opts.get("vnc_display", self.vnc_display)
+ hostfwd_port = opts.get("api_port", self.api_port)
+
+ # Convert Windows paths to WSL paths
+ wsl_disk = _win_to_wsl(disk_path)
+ disk_ext = Path(disk_path).suffix.lower()
+ disk_fmt = {".qcow2": "qcow2", ".vhdx": "vhdx", ".raw": "raw", ".img": "raw"}.get(
+ disk_ext, "raw"
+ )
+
+ # Locate OVMF inside WSL
+ ovmf_code = None
+ if image.os_type == "windows":
+ for candidate in [
+ "/usr/share/OVMF/OVMF_CODE_4M.fd",
+ "/usr/share/OVMF/OVMF_CODE.fd",
+ "/usr/share/qemu/edk2-x86_64-code.fd",
+ ]:
+ try:
+ self._wsl(f"test -f {candidate}")
+ ovmf_code = candidate
+ break
+ except RuntimeError:
+ pass
+
+ # EFI vars — create in same dir as disk (WSL path)
+ efivars_win = Path(disk_path).parent / "efivars.fd"
+ wsl_efivars = _win_to_wsl(efivars_win)
+ if ovmf_code and not efivars_win.exists():
+ # Copy OVMF vars template via WSL
+ for vars_candidate in [
+ "/usr/share/OVMF/OVMF_VARS_4M.fd",
+ "/usr/share/OVMF/OVMF_VARS.fd",
+ "/usr/share/qemu/edk2-i386-vars.fd",
+ ]:
+ try:
+ self._wsl(f"test -f {vars_candidate} && cp {vars_candidate} '{wsl_efivars}'")
+ break
+ except RuntimeError:
+ continue
+ else:
+ # Create empty vars file
+ efivars_win.write_bytes(b"\x00" * (256 * 1024))
+
+ # Build QEMU command (runs inside WSL)
+ parts = [
+ f"qemu-system-{self.arch}",
+ f"-name {name}",
+ "-machine q35,smm=off",
+ f"-m {memory}",
+ f"-smp {cpus}",
+ "-cpu host",
+ "-enable-kvm",
+ ]
+
+ if ovmf_code:
+ parts += [
+ f"-drive if=pflash,format=raw,readonly=on,file={ovmf_code}",
+ f"-drive if=pflash,format=raw,file={wsl_efivars}",
+ ]
+
+ parts += [
+ f"-drive file={wsl_disk},format={disk_fmt},if=virtio",
+ f"-netdev user,id=net0,hostfwd=tcp:0.0.0.0:{hostfwd_port}-:8000",
+ "-device virtio-net-pci,netdev=net0,mac=52:55:00:d1:55:01",
+ f"-vnc :{vnc_display}",
+ "-daemonize",
+ ]
+
+ for arg in self.extra_args:
+ parts.append(arg)
+
+ qemu_cmd = " ".join(parts)
+ logger.info(f"Starting QEMU in WSL2: {qemu_cmd}")
+
+ # Launch QEMU inside WSL2 (daemonize means it returns immediately)
+ result = subprocess.run(
+ ["wsl", "-e", "bash", "-c", qemu_cmd],
+ capture_output=True,
+ text=True,
+ timeout=30,
+ )
+ if result.returncode != 0:
+ raise RuntimeError(f"QEMU WSL2 launch failed: {result.stderr}")
+
+ info = RuntimeInfo(
+ host="localhost",
+ api_port=hostfwd_port,
+ vnc_port=5900 + vnc_display,
+ name=name,
+ )
+ await self.is_ready(info)
+ return info
+
+ async def stop(self, name: str) -> None:
+ try:
+ subprocess.run(
+ ["wsl", "-e", "bash", "-c", f"pkill -f 'qemu.*-name {name}'"],
+ capture_output=True,
+ timeout=10,
+ )
+ except Exception as e:
+ logger.warning(f"Failed to stop QEMU VM {name} in WSL2: {e}")
+
+ session_disk = getattr(self, "_session_disk", None)
+ if session_disk and session_disk.exists() and "sessions" in str(session_disk):
+ try:
+ session_disk.unlink()
+ logger.info(f"Removed session disk: {session_disk}")
+ except OSError:
+ pass
+
+ async def is_ready(self, info: RuntimeInfo, timeout: float = 120) -> bool:
+ url = f"http://{info.host}:{info.api_port}/status"
+ deadline = asyncio.get_event_loop().time() + timeout
+ async with httpx.AsyncClient(timeout=5) as client:
+ while asyncio.get_event_loop().time() < deadline:
+ try:
+ resp = await client.get(url)
+ if resp.status_code == 200:
+ logger.info(f"WSL2 QEMU VM {info.name} is ready")
+ return True
+ except (
+ httpx.ConnectError,
+ httpx.ReadTimeout,
+ httpx.RemoteProtocolError,
+ httpx.ConnectTimeout,
+ ):
+ pass
+ await asyncio.sleep(2)
+ raise TimeoutError(f"WSL2 QEMU VM {info.name} not ready after {timeout}s")
+
+
+def QEMURuntime(mode: str = "docker", **kwargs) -> Runtime:
+ """Factory that returns the appropriate QEMU runtime.
+
+ Args:
+ mode: "docker" (default), "bare-metal", or "wsl2"
+ """
+ if mode == "wsl2":
+ return QEMUWSL2Runtime(**kwargs)
+ if mode == "bare-metal":
+ return QEMUBaremetalRuntime(**kwargs)
+ return QEMUDockerRuntime(**kwargs)
diff --git a/libs/python/cua-sandbox/cua_sandbox/runtime/qemu_installer.py b/libs/python/cua-sandbox/cua_sandbox/runtime/qemu_installer.py
new file mode 100644
index 0000000000..163818d4ab
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/runtime/qemu_installer.py
@@ -0,0 +1,159 @@
+"""Auto-download and manage QEMU portable + wimlib for Windows."""
+
+from __future__ import annotations
+
+import logging
+import os
+import platform
+import shutil
+import tempfile
+import zipfile
+from pathlib import Path
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+QEMU_PORTABLE_URL = (
+ "https://github.com/ganarcasas/qemu-portable/releases/download/20241220/"
+ "qemu-portable-20241220.zip"
+)
+QEMU_DIR = Path.home() / ".cua" / "cua-sandbox" / "qemu"
+QEMU_INNER_DIR = "qemu-portable-20241220"
+
+WIMLIB_URL = "https://wimlib.net/downloads/wimlib-1.14.5-windows-x86_64-bin.zip"
+WIMLIB_DIR = Path.home() / ".cua" / "cua-sandbox" / "wimlib"
+
+
+def qemu_bin(arch: str = "x86_64") -> str:
+ """Return the path to qemu-system-{arch}, installing if needed on Windows.
+
+ Resolution order:
+ 1. Already on PATH → use it
+ 2. Common macOS Homebrew/MacPorts install locations (may not be on PATH)
+ 3. Already downloaded to ~/.cua/cua-sandbox/qemu/ → use it
+ 4. Windows only: download portable zip → extract → use it
+ 5. Raise RuntimeError with install instructions
+ """
+ binary = f"qemu-system-{arch}"
+
+ # 1. On PATH
+ found = shutil.which(binary)
+ if found:
+ return found
+
+ # 2. Common macOS install locations not always on PATH in subprocess envs
+ if platform.system() == "Darwin":
+ for prefix in (
+ "/opt/homebrew/bin", # Homebrew on Apple Silicon
+ "/usr/local/bin", # Homebrew on Intel
+ "/opt/local/bin", # MacPorts
+ ):
+ candidate = os.path.join(prefix, binary)
+ if os.path.isfile(candidate) and os.access(candidate, os.X_OK):
+ return candidate
+
+ # 3. Portable install
+ exe_name = f"{binary}.exe" if platform.system() == "Windows" else binary
+ local_bin = QEMU_DIR / QEMU_INNER_DIR / exe_name
+ if local_bin.exists():
+ return str(local_bin)
+
+ # 4. Auto-download (Windows only)
+ if platform.system() == "Windows":
+ _download_portable()
+ if local_bin.exists():
+ return str(local_bin)
+
+ if platform.system() == "Darwin":
+ raise RuntimeError(
+ f"{binary} not found. Install QEMU via Homebrew or MacPorts:\n\n"
+ f" brew install qemu\n"
+ f" — or —\n"
+ f" sudo port install qemu\n"
+ )
+
+ raise RuntimeError(
+ f"{binary} not found. Install QEMU or, on Windows, let cua-sandbox "
+ f"download it automatically (failed to find {local_bin})."
+ )
+
+
+def wimlib_imagex() -> str:
+ """Return path to wimlib-imagex, installing if needed on Windows.
+
+ Resolution order:
+ 1. Already on PATH → use it
+ 2. Already downloaded to ~/.cua/cua-sandbox/wimlib/ → use it
+ 3. Windows only: download zip → extract → use it
+ 4. Raise RuntimeError
+ """
+ # 1. On PATH
+ found = shutil.which("wimlib-imagex")
+ if found:
+ return found
+
+ # 2. Local install
+ local_bin = WIMLIB_DIR / "wimlib-imagex.exe"
+ if local_bin.exists():
+ return str(local_bin)
+
+ # 3. Auto-download (Windows only)
+ if platform.system() == "Windows":
+ _download_wimlib()
+ if local_bin.exists():
+ return str(local_bin)
+
+ raise RuntimeError(
+ "wimlib-imagex not found. Install wimlib or, on Windows, let cua-sandbox "
+ "download it automatically."
+ )
+
+
+def _download_zip(url: str, dest_dir: Path, description: str) -> None:
+ """Download and extract a zip to dest_dir."""
+ dest_dir.mkdir(parents=True, exist_ok=True)
+
+ logger.info(f"Downloading {description} from {url} ...")
+ tmp = tempfile.mktemp(suffix=".zip")
+ try:
+ with httpx.Client(follow_redirects=True, timeout=300) as client:
+ with client.stream("GET", url) as resp:
+ resp.raise_for_status()
+ total = int(resp.headers.get("content-length", 0))
+ downloaded = 0
+ with open(tmp, "wb") as f:
+ for chunk in resp.iter_bytes(chunk_size=1024 * 256):
+ f.write(chunk)
+ downloaded += len(chunk)
+ if total:
+ pct = downloaded * 100 // total
+ print(f"\r downloading {description} … {pct}%", end="", flush=True)
+ print()
+
+ logger.info(f"Extracting to {dest_dir} ...")
+ with zipfile.ZipFile(tmp) as zf:
+ zf.extractall(dest_dir)
+
+ logger.info(f"{description} installed successfully")
+ finally:
+ try:
+ os.unlink(tmp)
+ except OSError:
+ pass
+
+
+def _download_portable() -> None:
+ """Download and extract QEMU portable to ~/.cua/cua-sandbox/qemu/."""
+ marker = QEMU_DIR / QEMU_INNER_DIR / "qemu-system-x86_64.exe"
+ if marker.exists():
+ return
+ _download_zip(QEMU_PORTABLE_URL, QEMU_DIR, "QEMU portable")
+
+
+def _download_wimlib() -> None:
+ """Download and extract wimlib to ~/.cua/cua-sandbox/wimlib/."""
+ marker = WIMLIB_DIR / "wimlib-imagex.exe"
+ if marker.exists():
+ return
+ _download_zip(WIMLIB_URL, WIMLIB_DIR, "wimlib")
diff --git a/libs/python/cua-sandbox/cua_sandbox/runtime/tart.py b/libs/python/cua-sandbox/cua_sandbox/runtime/tart.py
new file mode 100644
index 0000000000..9f2d8a011d
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/runtime/tart.py
@@ -0,0 +1,271 @@
+"""Tart runtime — uses Cirrus Labs' Tart CLI for Apple VZ framework VMs.
+
+Tart manages macOS and Linux VMs using Apple's Virtualization.framework.
+It supports pulling OCI images from registries (ghcr.io, etc.), running
+headless VMs with VNC on the host side, and SSH into the guest.
+
+Default SSH credentials for Tart VMs: admin/admin.
+VNC is exposed on a random localhost port with a random password (parsed from stderr).
+
+Usage::
+
+ from cua_sandbox.runtime import TartRuntime
+
+ async with sandbox(
+ local=True,
+ image=Image.from_registry("ghcr.io/cirruslabs/macos-tahoe-base:latest"),
+ runtime=TartRuntime(),
+ name="my-macos-vm",
+ ) as sb:
+ await sb.shell.run("uname -a")
+ screenshot = await sb.screenshot()
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+import shutil
+from typing import Optional
+
+from cua_sandbox.image import Image
+from cua_sandbox.runtime.base import Runtime, RuntimeInfo
+
+logger = logging.getLogger(__name__)
+
+TART_DEFAULT_USERNAME = "admin"
+TART_DEFAULT_PASSWORD = "admin"
+
+
+def _has_tart() -> bool:
+ return shutil.which("tart") is not None
+
+
+class TartRuntime(Runtime):
+ """Apple Virtualization.framework runtime via Tart CLI.
+
+ Uses VNC (host-side, random port) for screenshots and SSH for shell commands.
+ """
+
+ def __init__(
+ self,
+ *,
+ ephemeral: bool = True,
+ cpu_count: Optional[int] = None,
+ memory_mb: Optional[int] = None,
+ disk_gb: Optional[int] = None,
+ display: str = "1024x768",
+ ssh_username: str = TART_DEFAULT_USERNAME,
+ ssh_password: str = TART_DEFAULT_PASSWORD,
+ ):
+ self.ephemeral = ephemeral
+ self.cpu_count = cpu_count
+ self.memory_mb = memory_mb
+ self.disk_gb = disk_gb
+ self.display = display
+ self.ssh_username = ssh_username
+ self.ssh_password = ssh_password
+ self._proc: Optional[asyncio.subprocess.Process] = None
+ self._vm_name: Optional[str] = None
+ self.vnc_host: Optional[str] = None
+ self.vnc_port: Optional[int] = None
+ self.vnc_password: Optional[str] = None
+
+ async def start(self, image: Image, name: str, **opts) -> RuntimeInfo:
+ if not _has_tart():
+ raise RuntimeError("Tart CLI not found. Install via: brew install cirruslabs/cli/tart")
+
+ registry_ref = image._registry
+ if not registry_ref:
+ raise ValueError(
+ "TartRuntime requires an OCI registry image. "
+ "Use Image.from_registry('ghcr.io/...') to specify one."
+ )
+
+ # Pull the image
+ logger.info(f"Pulling {registry_ref} ...")
+ pull = await asyncio.create_subprocess_exec(
+ "tart",
+ "pull",
+ registry_ref,
+ stdout=asyncio.subprocess.PIPE,
+ stderr=asyncio.subprocess.PIPE,
+ )
+ _, stderr = await pull.communicate()
+ if pull.returncode != 0:
+ raise RuntimeError(f"tart pull failed: {stderr.decode()}")
+
+ # Clone for ephemeral use
+ self._vm_name = name
+ if self.ephemeral:
+ del_proc = await asyncio.create_subprocess_exec(
+ "tart",
+ "delete",
+ name,
+ stdout=asyncio.subprocess.DEVNULL,
+ stderr=asyncio.subprocess.DEVNULL,
+ )
+ await del_proc.communicate()
+
+ clone = await asyncio.create_subprocess_exec(
+ "tart",
+ "clone",
+ registry_ref,
+ name,
+ stdout=asyncio.subprocess.PIPE,
+ stderr=asyncio.subprocess.PIPE,
+ )
+ _, stderr = await clone.communicate()
+ if clone.returncode != 0:
+ raise RuntimeError(f"tart clone failed: {stderr.decode()}")
+
+ # Configure VM resources
+ set_args = []
+ if self.cpu_count:
+ set_args += ["--cpu", str(self.cpu_count)]
+ if self.memory_mb:
+ set_args += ["--memory", str(self.memory_mb)]
+ if self.disk_gb:
+ set_args += ["--disk-size", str(self.disk_gb)]
+ if self.display:
+ set_args += ["--display", self.display]
+ if set_args:
+ set_proc = await asyncio.create_subprocess_exec(
+ "tart",
+ "set",
+ name,
+ *set_args,
+ stdout=asyncio.subprocess.PIPE,
+ stderr=asyncio.subprocess.PIPE,
+ )
+ await set_proc.communicate()
+
+ # Start VM headless with VNC
+ run_cmd = ["tart", "run", name, "--no-graphics", "--vnc-experimental"]
+ logger.info(f"Starting VM: {' '.join(run_cmd)}")
+ self._proc = await asyncio.create_subprocess_exec(
+ *run_cmd,
+ stdout=asyncio.subprocess.PIPE,
+ stderr=asyncio.subprocess.PIPE,
+ )
+
+ # Parse VNC URL from stdout (e.g. "vnc://:[email protected]:61777")
+ vnc_line = await self._read_vnc_line(timeout=10)
+ if vnc_line:
+ m = re.search(r"vnc://:([^@]+)@([^:]+):(\d+)", vnc_line)
+ if m:
+ self.vnc_password = m.group(1)
+ self.vnc_host = m.group(2)
+ self.vnc_port = int(m.group(3))
+ logger.info(f"VNC available at {self.vnc_host}:{self.vnc_port}")
+
+ if not self.vnc_port:
+ raise RuntimeError("Could not parse VNC port from tart output")
+
+ # Brief check that it didn't crash
+ if self._proc.returncode is not None:
+ err = await self._proc.stderr.read() if self._proc.stderr else b""
+ raise RuntimeError(f"Tart VM crashed on launch: {err.decode()}")
+
+ # Get VM IP for SSH
+ ip = await self._get_ip(name, timeout=120)
+ if not ip:
+ raise RuntimeError(f"Could not get IP for Tart VM {name}")
+
+ env = "mac" if "macos" in registry_ref.lower() or "mac" in registry_ref.lower() else "linux"
+
+ return RuntimeInfo(
+ host=ip,
+ api_port=22,
+ vnc_port=self.vnc_port,
+ vnc_host=self.vnc_host or "127.0.0.1",
+ vnc_password=self.vnc_password,
+ ssh_port=22,
+ ssh_username=self.ssh_username,
+ ssh_password=self.ssh_password,
+ name=name,
+ environment=env,
+ )
+
+ async def _read_vnc_line(self, timeout: float = 10) -> Optional[str]:
+ """Read stdout lines until we find the VNC URL."""
+ if not self._proc or not self._proc.stdout:
+ return None
+ try:
+ deadline = asyncio.get_event_loop().time() + timeout
+ while asyncio.get_event_loop().time() < deadline:
+ line = await asyncio.wait_for(
+ self._proc.stdout.readline(),
+ timeout=max(0.1, deadline - asyncio.get_event_loop().time()),
+ )
+ text = line.decode().strip()
+ if "vnc://" in text.lower():
+ return text
+ except (asyncio.TimeoutError, Exception):
+ pass
+ return None
+
+ async def _get_ip(self, name: str, timeout: int = 120) -> Optional[str]:
+ try:
+ proc = await asyncio.create_subprocess_exec(
+ "tart",
+ "ip",
+ name,
+ "--wait",
+ str(timeout),
+ stdout=asyncio.subprocess.PIPE,
+ stderr=asyncio.subprocess.PIPE,
+ )
+ stdout, _ = await asyncio.wait_for(proc.communicate(), timeout=timeout + 10)
+ ip = stdout.decode().strip()
+ if ip:
+ logger.info(f"VM {name} IP: {ip}")
+ return ip
+ except (asyncio.TimeoutError, Exception) as e:
+ logger.warning(f"Could not get VM IP: {e}")
+ return None
+
+ async def is_ready(self, info: RuntimeInfo, timeout: float = 120) -> bool:
+ """Wait until SSH is reachable."""
+ import socket
+
+ deadline = asyncio.get_event_loop().time() + timeout
+ while asyncio.get_event_loop().time() < deadline:
+ try:
+ sock = socket.create_connection((info.host, 22), timeout=5)
+ sock.close()
+ logger.info(f"Tart VM {info.name} SSH is reachable")
+ return True
+ except (ConnectionRefusedError, OSError, socket.timeout):
+ pass
+ await asyncio.sleep(3)
+ raise TimeoutError(f"Tart VM {info.name} SSH not ready within {timeout}s")
+
+ async def stop(self, name: str) -> None:
+ stop = await asyncio.create_subprocess_exec(
+ "tart",
+ "stop",
+ name,
+ stdout=asyncio.subprocess.DEVNULL,
+ stderr=asyncio.subprocess.DEVNULL,
+ )
+ await stop.communicate()
+
+ if self._proc and self._proc.returncode is None:
+ self._proc.terminate()
+ try:
+ await asyncio.wait_for(self._proc.communicate(), timeout=10)
+ except asyncio.TimeoutError:
+ self._proc.kill()
+ self._proc = None
+
+ if self.ephemeral:
+ await asyncio.create_subprocess_exec(
+ "tart",
+ "delete",
+ name,
+ stdout=asyncio.subprocess.DEVNULL,
+ stderr=asyncio.subprocess.DEVNULL,
+ )
+ logger.info(f"Deleted ephemeral VM: {name}")
diff --git a/libs/python/cua-sandbox/cua_sandbox/sandbox.py b/libs/python/cua-sandbox/cua_sandbox/sandbox.py
new file mode 100644
index 0000000000..6a59d079f6
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/sandbox.py
@@ -0,0 +1,1328 @@
+"""Sandbox class — the primary entry point for sandboxed environments.
+
+Exposes .mouse, .keyboard, .screen, .clipboard, .shell, .window, .terminal
+as interface objects backed by a Transport.
+
+Usage::
+
+ from cua_sandbox import Sandbox, Image
+
+ # Provision a new persistent sandbox
+ sb = await Sandbox.create(Image.desktop("ubuntu"))
+ await sb.shell.run("uname -a")
+ await sb.disconnect()
+
+ # Connect to an existing sandbox by name (plain await or async with)
+ sb = await Sandbox.connect("my-sandbox")
+ await sb.screenshot()
+ await sb.disconnect()
+
+ async with Sandbox.connect("my-sandbox") as sb: # disconnects on exit
+ await sb.screenshot()
+
+ # Ephemeral — auto-destroyed on exit
+ async with Sandbox.ephemeral(Image.desktop("ubuntu")) as sb:
+ await sb.shell.run("whoami")
+"""
+
+from __future__ import annotations
+
+import random
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from typing import (
+ TYPE_CHECKING,
+ Any,
+ AsyncIterator,
+ Callable,
+ Coroutine,
+ Optional,
+ TypeVar,
+)
+
+from cua_sandbox.image import Image
+from cua_sandbox.interfaces import (
+ Clipboard,
+ Keyboard,
+ Mobile,
+ Mouse,
+ Screen,
+ Shell,
+ Terminal,
+ Tunnel,
+ Window,
+)
+from cua_sandbox.transport.base import Transport
+from cua_sandbox.transport.cloud import CloudTransport
+from cua_sandbox.transport.http import HTTPTransport
+from cua_sandbox.transport.websocket import WebSocketTransport
+
+if TYPE_CHECKING:
+ from cua_sandbox.runtime.base import Runtime, RuntimeInfo
+
+_T = TypeVar("_T")
+
+
+@dataclass
+class SandboxInfo:
+ """Metadata for a local or cloud sandbox."""
+
+ name: str
+ status: str # "running" | "suspended" | "stopped" | "provisioning"
+ source: str # "cloud" | "lume" | "docker" | "qemu-baremetal" | "qemu-docker"
+ os_type: Optional[str] = None
+ host: Optional[str] = None
+ vnc_url: Optional[str] = None
+ api_url: Optional[str] = None
+ created_at: Optional[str] = None
+
+
+class _ConnectResult:
+ """Returned by connect() — supports both ``await`` and ``async with``.
+
+ Usage::
+
+ # plain await
+ sb = await Sandbox.connect("name")
+
+ # context manager — disconnects on exit (sandbox keeps running)
+ async with Sandbox.connect("name") as sb:
+ ...
+ """
+
+ __slots__ = ("_factory", "_instance")
+
+ def __init__(self, factory: Callable[[], Coroutine[Any, Any, _T]]) -> None:
+ self._factory = factory
+ self._instance: Any = None
+
+ def __await__(self) -> Any:
+ return self._factory().__await__()
+
+ async def __aenter__(self) -> Any:
+ self._instance = await self._factory()
+ return self._instance
+
+ async def __aexit__(self, *exc: Any) -> None:
+ if self._instance is not None:
+ await self._instance.disconnect()
+
+
+def _auto_runtime(image: Image) -> "Runtime":
+ """Pick a runtime automatically based on image.os_type and image.kind."""
+ import platform as _plat
+
+ if image.kind is None:
+ raise ValueError(
+ "Cannot auto-select runtime: image kind is unresolved. "
+ "Either use Image.linux()/windows()/macos() which set kind automatically, "
+ "or pass runtime= explicitly for registry images."
+ )
+
+ if image.kind == "container":
+ from cua_sandbox.runtime.docker import DockerRuntime
+
+ return DockerRuntime(ephemeral=True)
+
+ # kind == "vm"
+ if image.os_type == "macos":
+ from cua_sandbox.runtime.lume import LumeRuntime
+
+ return LumeRuntime()
+
+ if image.os_type == "android":
+ from cua_sandbox.runtime.android_emulator import AndroidEmulatorRuntime
+
+ return AndroidEmulatorRuntime()
+
+ if image.os_type == "windows" and _plat.system() == "Windows":
+ from cua_sandbox.runtime.hyperv import _has_hyperv
+
+ if _has_hyperv():
+ from cua_sandbox.runtime.hyperv import HyperVRuntime
+
+ return HyperVRuntime()
+
+ # If image has a disk path (from_file), use bare-metal QEMU
+ if image._disk_path:
+ from cua_sandbox.runtime.qemu import QEMURuntime
+
+ return QEMURuntime(mode="bare-metal")
+
+ # Linux VM or Windows VM → prefer Docker-wrapped QEMU; fall back to bare-metal
+ from cua_sandbox.runtime.qemu import QEMURuntime
+
+ if image.os_type == "windows":
+ # Windows bare-metal QEMU works on any host with qemu-system-x86_64
+ try:
+ from cua_sandbox.runtime.docker import _has_docker
+
+ if not _has_docker():
+ return QEMURuntime(mode="bare-metal")
+ except Exception:
+ pass
+
+ return QEMURuntime(mode="docker")
+
+
+class Sandbox:
+ """A sandboxed computer environment.
+
+ Provides programmatic control of a VM or container through a unified
+ interface: ``.mouse``, ``.keyboard``, ``.screen``, ``.clipboard``,
+ ``.shell``, ``.window``, and ``.terminal``.
+
+ Sandboxes are always isolated — they never control the host machine
+ directly. For unsandboxed host control, use :func:`cua_sandbox.localhost`.
+
+ There are three ways to obtain a Sandbox:
+
+ 1. **Persistent** — provision and keep alive after the script exits::
+
+ sb = await Sandbox.create(Image.desktop("ubuntu"))
+ await sb.shell.run("whoami")
+ await sb.disconnect()
+
+ 2. **Connect** — attach to an already-running sandbox by name::
+
+ sb = await Sandbox.connect("my-sandbox")
+ await sb.screenshot()
+ await sb.disconnect()
+
+ 3. **Ephemeral** — auto-destroyed when the ``async with`` block exits::
+
+ async with Sandbox.ephemeral(Image.desktop("ubuntu")) as sb:
+ await sb.shell.run("whoami")
+ """
+
+ def __init__(
+ self,
+ transport: Transport,
+ name: Optional[str] = None,
+ _runtime: Optional[Runtime] = None,
+ _runtime_info: Optional[RuntimeInfo] = None,
+ _ephemeral: Optional[bool] = None,
+ ):
+ self._transport = transport
+ self.name = name
+ self._runtime = _runtime
+ self._runtime_info = _runtime_info
+ self._ephemeral = _ephemeral
+ self.screen = Screen(transport)
+ self.mouse = Mouse(transport)
+ self.keyboard = Keyboard(transport)
+ self.clipboard = Clipboard(transport)
+ self.shell = Shell(transport)
+ self.window = Window(transport)
+ self.terminal = Terminal(transport)
+ self.mobile = Mobile(transport)
+ self.tunnel = Tunnel(transport)
+
+ async def _connect(self) -> None:
+ await self._transport.connect()
+ # Update name from transport (e.g. CloudTransport resolves name after creating a VM)
+ if self.name is None and isinstance(self._transport, CloudTransport):
+ self.name = self._transport.name
+
+ async def disconnect(self) -> None:
+ """Drop the transport connection. The sandbox keeps running."""
+ await self._transport.disconnect()
+
+ async def destroy(self) -> None:
+ """Disconnect and permanently delete the sandbox (VM/container)."""
+ await self._transport.disconnect()
+ 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")
+
+ async def screenshot(
+ self, text: Optional[str] = None, format: str = "png", quality: int = 95
+ ) -> bytes:
+ _MAGIC: dict[bytes, str] = {b"\x89PNG": "png", b"\xff\xd8\xff": "jpeg"}
+ data = await self._transport.screenshot(format=format, quality=quality)
+ got_format = next(
+ (fmt for magic, fmt in _MAGIC.items() if data.startswith(magic)), "unknown"
+ )
+ expected = "jpeg" if format.lower() in ("jpeg", "jpg") else format.lower()
+ if got_format != expected:
+ raise ValueError(
+ f"requested {format!r} but got {got_format!r} (magic bytes: {data[:4].hex()})"
+ )
+ return data
+
+ async def screenshot_base64(
+ self, text: Optional[str] = None, format: str = "png", quality: int = 95
+ ) -> str:
+ return await self.screen.screenshot_base64(format=format, quality=quality)
+
+ async def get_environment(self) -> str:
+ return await self._transport.get_environment()
+
+ async def get_display_url(self, *, share: bool = False) -> str:
+ """Return a URL to view this sandbox's display.
+
+ Args:
+ share: If True, return a public link with embedded credentials
+ (cloud only). If False, return a direct connection URL.
+ """
+ return await self._transport.get_display_url(share=share)
+
+ async def get_dimensions(self) -> tuple[int, int]:
+ return await self.screen.size()
+
+ # ── Async context manager ────────────────────────────────────────────
+
+ async def __aenter__(self) -> Sandbox:
+ await self._connect()
+ return self
+
+ async def __aexit__(self, *exc: Any) -> None:
+ await self.disconnect()
+
+ # ── Public factory methods ───────────────────────────────────────────
+
+ @classmethod
+ async def create(
+ cls,
+ image: Image,
+ *,
+ name: Optional[str] = None,
+ api_key: Optional[str] = None,
+ local: bool = False,
+ runtime: Optional["Runtime"] = None,
+ cpu: Optional[int] = None,
+ memory_mb: Optional[int] = None,
+ disk_gb: Optional[int] = None,
+ region: str = "us-east-1",
+ ) -> "Sandbox":
+ """Provision a new persistent sandbox and return it connected.
+
+ The sandbox is kept alive after your script exits — call ``close()``
+ when you are done, or use :meth:`ephemeral` if you want it destroyed
+ automatically.
+
+ Args:
+ image: Image to run (e.g. ``Image.desktop("ubuntu")``).
+ name: Optional name to assign to the sandbox.
+ api_key: CUA API key for cloud sandboxes.
+ local: Use a local runtime instead of cloud.
+ runtime: Explicit runtime backend (DockerRuntime, QEMURuntime, etc.).
+ cpu: Number of CPUs for the cloud sandbox.
+ memory_mb: Memory in MB for the cloud sandbox.
+ disk_gb: Disk size in GB for the cloud sandbox.
+ region: Cloud region (default ``"us-east-1"``).
+
+ Example::
+
+ sb = await Sandbox.create(Image.desktop("ubuntu"))
+ await sb.shell.run("uname -a")
+ print(sb.name) # save to reconnect later
+ await sb.disconnect()
+ """
+ return await cls._create(
+ image=image,
+ name=name,
+ ephemeral=False,
+ api_key=api_key,
+ local=local,
+ runtime=runtime,
+ cpu=cpu,
+ memory_mb=memory_mb,
+ disk_gb=disk_gb,
+ region=region,
+ )
+
+ @classmethod
+ def connect(
+ cls,
+ name: str,
+ *,
+ api_key: Optional[str] = None,
+ local: bool = False,
+ ws_url: Optional[str] = None,
+ http_url: Optional[str] = None,
+ container_name: Optional[str] = None,
+ cpu: Optional[int] = None,
+ memory_mb: Optional[int] = None,
+ disk_gb: Optional[int] = None,
+ region: str = "us-east-1",
+ ) -> "_ConnectResult":
+ """Connect to an existing sandbox by name.
+
+ Supports both ``await`` and ``async with``. When used as a context
+ manager, ``disconnect()`` is called on exit — the sandbox keeps running.
+
+ Args:
+ name: Name of the existing sandbox.
+ api_key: CUA API key for cloud sandboxes.
+ ws_url: WebSocket URL for a remote computer-server.
+ http_url: HTTP base URL for a remote computer-server.
+ container_name: Container name for cloud auth (HTTP transport).
+ region: Cloud region (default ``"us-east-1"``).
+
+ Examples::
+
+ # plain await
+ sb = await Sandbox.connect("my-sandbox")
+ await sb.screenshot()
+ await sb.disconnect()
+
+ # context manager — disconnects on exit, sandbox keeps running
+ async with Sandbox.connect("my-sandbox") as sb:
+ await sb.screenshot()
+ """
+
+ async def _factory() -> "Sandbox":
+ return await cls._create(
+ name=name,
+ ephemeral=False,
+ local=local,
+ api_key=api_key,
+ ws_url=ws_url,
+ http_url=http_url,
+ container_name=container_name,
+ cpu=cpu,
+ memory_mb=memory_mb,
+ disk_gb=disk_gb,
+ region=region,
+ )
+
+ return _ConnectResult(_factory)
+
+ @classmethod
+ @asynccontextmanager
+ async def ephemeral(
+ cls,
+ image: Image,
+ *,
+ name: Optional[str] = None,
+ api_key: Optional[str] = None,
+ local: bool = False,
+ runtime: Optional["Runtime"] = None,
+ cpu: Optional[int] = None,
+ memory_mb: Optional[int] = None,
+ disk_gb: Optional[int] = None,
+ region: str = "us-east-1",
+ ) -> AsyncIterator["Sandbox"]:
+ """Create an ephemeral sandbox that is automatically destroyed on exit.
+
+ Args:
+ image: Image to run (e.g. ``Image.desktop("ubuntu")``).
+ name: Optional name to assign to the sandbox.
+ api_key: CUA API key for cloud sandboxes.
+ local: Use a local runtime instead of cloud.
+ runtime: Explicit runtime backend (DockerRuntime, QEMURuntime, etc.).
+ cpu: Number of CPUs for the cloud sandbox.
+ memory_mb: Memory in MB for the cloud sandbox.
+ disk_gb: Disk size in GB for the cloud sandbox.
+ region: Cloud region (default ``"us-east-1"``).
+
+ Example::
+
+ async with Sandbox.ephemeral(Image.desktop("ubuntu")) as sb:
+ await sb.shell.run("whoami")
+ # sandbox is destroyed here
+ """
+ sb = await cls._create(
+ image=image,
+ name=name,
+ ephemeral=True,
+ api_key=api_key,
+ local=local,
+ runtime=runtime,
+ cpu=cpu,
+ memory_mb=memory_mb,
+ disk_gb=disk_gb,
+ region=region,
+ )
+ try:
+ yield sb
+ finally:
+ await sb.destroy()
+
+ # ── Lifecycle management ─────────────────────────────────────────────
+
+ @classmethod
+ async def list(
+ cls,
+ *,
+ local: bool = False,
+ api_key: Optional[str] = None,
+ ) -> "list[SandboxInfo]":
+ """List running and suspended sandboxes.
+
+ Args:
+ local: If True, list local sandboxes (Lume, Docker, QEMU).
+ If False, list cloud sandboxes.
+ api_key: CUA API key for cloud sandboxes.
+ """
+ if local:
+ return await cls._list_local()
+ return await cls._list_cloud(api_key=api_key)
+
+ @classmethod
+ async def _list_local(cls) -> "list[SandboxInfo]":
+ import asyncio
+
+ from cua_sandbox.runtime.android_emulator import AndroidEmulatorRuntime
+ from cua_sandbox.runtime.docker import DockerRuntime
+ from cua_sandbox.runtime.lume import LumeRuntime
+ from cua_sandbox.runtime.qemu import QEMUBaremetalRuntime
+
+ async def _list_baremetal():
+ return await QEMUBaremetalRuntime().list()
+
+ async def _list_docker():
+ try:
+ return await DockerRuntime().list()
+ except Exception:
+ return []
+
+ async def _list_lume():
+ try:
+ return await LumeRuntime().list()
+ except Exception:
+ return []
+
+ async def _list_android():
+ try:
+ return await AndroidEmulatorRuntime().list()
+ except Exception:
+ return []
+
+ baremetal_vms, docker_vms, lume_vms, android_vms = await asyncio.gather(
+ _list_baremetal(), _list_docker(), _list_lume(), _list_android()
+ )
+
+ results: list[SandboxInfo] = []
+ for vm in baremetal_vms:
+ results.append(
+ SandboxInfo(
+ name=vm["name"],
+ status=vm["status"],
+ source="qemu-baremetal",
+ os_type=vm.get("os_type"),
+ host=vm.get("host"),
+ api_url=(
+ f"http://{vm['host']}:{vm['api_port']}"
+ if vm.get("host") and vm.get("api_port")
+ else None
+ ),
+ )
+ )
+ for vm in docker_vms:
+ results.append(
+ SandboxInfo(
+ name=vm["name"],
+ status=vm["status"],
+ source=vm.get("runtime_type", "docker"),
+ host="localhost",
+ )
+ )
+ for vm in lume_vms:
+ results.append(
+ SandboxInfo(
+ name=vm["name"],
+ status=vm["status"],
+ source="lume",
+ os_type=vm.get("os_type"),
+ host=vm.get("ip_address"),
+ )
+ )
+ for vm in android_vms:
+ results.append(
+ SandboxInfo(
+ name=vm["name"],
+ status=vm["status"],
+ source="androidemulator",
+ os_type=vm.get("os_type"),
+ host=vm.get("host"),
+ api_url=(
+ f"http://{vm['host']}:{vm['api_port']}"
+ if vm.get("host") and vm.get("api_port")
+ else None
+ ),
+ )
+ )
+ return results
+
+ @classmethod
+ async def _list_cloud(cls, *, api_key: Optional[str] = None) -> "list[SandboxInfo]":
+ from cua_sandbox.transport.cloud import cloud_list_vms
+
+ vms = await cloud_list_vms(api_key=api_key)
+ results = []
+ for vm in vms:
+ raw_status = vm.get("status", "unknown")
+ results.append(
+ SandboxInfo(
+ name=vm.get("name", ""),
+ status=raw_status,
+ source="cloud",
+ os_type=vm.get("os_type") or vm.get("os"),
+ created_at=vm.get("created_at"),
+ )
+ )
+ return results
+
+ @classmethod
+ async def get_info(
+ cls,
+ name: str,
+ *,
+ local: bool = False,
+ api_key: Optional[str] = None,
+ ) -> "SandboxInfo":
+ """Get metadata for a specific sandbox.
+
+ Args:
+ name: Sandbox name.
+ local: If True, look up in local runtimes.
+ api_key: CUA API key for cloud.
+ """
+ if local:
+ sandboxes = await cls._list_local()
+ match = next((s for s in sandboxes if s.name == name), None)
+ if match:
+ return match
+ # Fall back to state file
+ from cua_sandbox import sandbox_state
+
+ state = sandbox_state.load(name)
+ if state:
+ return SandboxInfo(
+ name=name,
+ status=state.get("status", "unknown"),
+ source=state.get("runtime_type", "unknown"),
+ os_type=state.get("os_type"),
+ host=state.get("host"),
+ api_url=(
+ f"http://{state['host']}:{state['api_port']}"
+ if state.get("host") and state.get("api_port")
+ else None
+ ),
+ )
+ raise ValueError(f"Local sandbox '{name}' not found.")
+ from cua_sandbox.transport.cloud import cloud_get_vm
+
+ vm = await cloud_get_vm(name, api_key=api_key)
+ return SandboxInfo(
+ name=vm.get("name", name),
+ status=vm.get("status", "unknown"),
+ source="cloud",
+ os_type=vm.get("os_type") or vm.get("os"),
+ created_at=vm.get("created_at"),
+ )
+
+ @classmethod
+ async def suspend(
+ cls,
+ name: str,
+ *,
+ local: bool = False,
+ api_key: Optional[str] = None,
+ ) -> None:
+ """Suspend a running sandbox (save state).
+
+ For local QEMU bare-metal: saves a QMP snapshot then quits the process.
+ For local Docker/QEMU-docker: pauses the container.
+ For local Lume: stops the Lume VM (Lume persists state).
+ For cloud: calls POST /v1/vms/{name}/stop.
+
+ Args:
+ name: Sandbox name.
+ local: If True, operate on a local sandbox.
+ api_key: CUA API key for cloud.
+ """
+ if local:
+ await cls._suspend_local(name)
+ return
+ from cua_sandbox.transport.cloud import cloud_vm_action
+
+ await cloud_vm_action(name, "stop", api_key=api_key)
+
+ @classmethod
+ async def _suspend_local(cls, name: str) -> None:
+ from cua_sandbox import sandbox_state
+ from cua_sandbox.runtime.lume import LumeRuntime
+
+ state = sandbox_state.load(name)
+ runtime_type = state.get("runtime_type") if state else None
+ if runtime_type == "lume":
+ await LumeRuntime().suspend(name)
+ elif runtime_type == "qemu-baremetal":
+ from cua_sandbox.runtime.qemu import QEMUBaremetalRuntime
+
+ rt = QEMUBaremetalRuntime()
+ if state:
+ rt.qmp_port = state.get("qmp_port", rt.qmp_port)
+ await rt.suspend(name)
+ elif runtime_type in ("docker", "qemu-docker"):
+ import subprocess
+
+ subprocess.run(["docker", "pause", name], capture_output=True)
+ sandbox_state.update(name, status="suspended")
+ else:
+ # Try docker pause as fallback
+ import subprocess
+
+ subprocess.run(["docker", "pause", name], capture_output=True)
+
+ @classmethod
+ async def resume(
+ cls,
+ name: str,
+ *,
+ local: bool = False,
+ api_key: Optional[str] = None,
+ ) -> "Sandbox":
+ """Resume a suspended sandbox and return a connected Sandbox.
+
+ Args:
+ name: Sandbox name.
+ local: If True, resume a local sandbox.
+ api_key: CUA API key for cloud.
+
+ Returns:
+ A connected Sandbox ready to use.
+ """
+ if local:
+ return await cls._resume_local(name)
+ from cua_sandbox.transport.cloud import cloud_vm_action
+
+ await cloud_vm_action(name, "run", api_key=api_key)
+ # Connect to the now-running cloud sandbox
+ sb = await cls._create(name=name, ephemeral=False, api_key=api_key)
+ return sb
+
+ @classmethod
+ async def _resume_local(cls, name: str) -> "Sandbox":
+ from cua_sandbox import sandbox_state
+ from cua_sandbox.transport.http import HTTPTransport
+
+ state = sandbox_state.load(name)
+ if state is None:
+ raise ValueError(f"No local sandbox named '{name}' found in state files.")
+ runtime_type = state.get("runtime_type")
+ if runtime_type == "lume":
+ from cua_sandbox.image import Image
+ from cua_sandbox.runtime.lume import LumeRuntime
+
+ image = Image.from_dict(state["image"])
+ rt = LumeRuntime()
+ rt_info = await rt.resume(image, name)
+ elif runtime_type == "qemu-baremetal":
+ from cua_sandbox.image import Image
+ from cua_sandbox.runtime.qemu import QEMUBaremetalRuntime
+
+ image = Image.from_dict(state["image"])
+ rt = QEMUBaremetalRuntime(
+ api_port=state.get("api_port", 8000),
+ vnc_display=state.get("vnc_display", 0),
+ memory_mb=state.get("memory_mb", 4096),
+ cpu_count=state.get("cpu_count", 2),
+ arch=state.get("arch", "x86_64"),
+ qmp_port=state.get("qmp_port", 4444),
+ )
+ rt_info = await rt.resume(image, name)
+ elif runtime_type in ("docker", "qemu-docker"):
+ import subprocess
+
+ subprocess.run(["docker", "unpause", name], capture_output=True)
+ api_port = state.get("api_port", 8000)
+ sandbox_state.update(name, status="running")
+ rt_info = None
+ transport = HTTPTransport(f"http://localhost:{api_port}")
+ sb = cls(transport, name=name, _ephemeral=False)
+ await sb._connect()
+ return sb
+ else:
+ raise ValueError(
+ f"Cannot resume sandbox '{name}': unknown runtime_type '{runtime_type}'"
+ )
+ transport = HTTPTransport(f"http://{rt_info.host}:{rt_info.api_port}")
+ sb = cls(transport, name=name, _ephemeral=False)
+ await sb._connect()
+ return sb
+
+ @classmethod
+ async def restart(
+ cls,
+ name: str,
+ *,
+ local: bool = False,
+ api_key: Optional[str] = None,
+ ) -> "Sandbox":
+ """Restart a sandbox (suspend then resume) and return a connected Sandbox.
+
+ Args:
+ name: Sandbox name.
+ local: If True, restart a local sandbox.
+ api_key: CUA API key for cloud.
+
+ Returns:
+ A connected Sandbox ready to use.
+ """
+ if local:
+ await cls._suspend_local(name)
+ return await cls._resume_local(name)
+ from cua_sandbox.transport.cloud import cloud_vm_action
+
+ await cloud_vm_action(name, "restart", api_key=api_key)
+ sb = await cls._create(name=name, ephemeral=False, api_key=api_key)
+ return sb
+
+ @classmethod
+ async def delete(
+ cls,
+ name: str,
+ *,
+ local: bool = False,
+ api_key: Optional[str] = None,
+ ) -> None:
+ """Permanently delete a sandbox.
+
+ For local sandboxes, stops the VM and removes the state file.
+ For cloud sandboxes, calls DELETE /v1/vms/{name}.
+
+ Args:
+ name: Sandbox name.
+ local: If True, delete a local sandbox.
+ api_key: CUA API key for cloud.
+ """
+ if local:
+ await cls._delete_local(name)
+ return
+ from cua_sandbox.transport.cloud import cloud_vm_action
+
+ await cloud_vm_action(name, "delete", api_key=api_key)
+
+ @classmethod
+ async def _delete_local(cls, name: str) -> None:
+ from cua_sandbox import sandbox_state
+
+ state = sandbox_state.load(name)
+ runtime_type = state.get("runtime_type") if state else None
+ if runtime_type == "lume":
+ from cua_sandbox.runtime.lume import LumeRuntime
+
+ await LumeRuntime().delete(name)
+ elif runtime_type == "qemu-baremetal":
+ from cua_sandbox.runtime.qemu import QEMUBaremetalRuntime
+
+ await QEMUBaremetalRuntime().stop(name) # stop() already deletes state file
+ return
+ elif runtime_type == "androidemulator":
+ from cua_sandbox.runtime.android_emulator import AndroidEmulatorRuntime
+
+ await AndroidEmulatorRuntime().stop(name)
+ elif runtime_type in ("docker", "qemu-docker"):
+ import subprocess
+
+ subprocess.run(["docker", "stop", name], capture_output=True)
+ subprocess.run(["docker", "rm", name], capture_output=True)
+ sandbox_state.delete(name)
+
+ # ── Internal factory ─────────────────────────────────────────────────
+
+ @classmethod
+ async def _create(
+ cls,
+ *,
+ local: bool = False,
+ ws_url: Optional[str] = None,
+ http_url: Optional[str] = None,
+ api_key: Optional[str] = None,
+ container_name: Optional[str] = None,
+ image: Optional[Image] = None,
+ runtime: Optional["Runtime"] = None,
+ name: Optional[str] = None,
+ ephemeral: Optional[bool] = None,
+ cpu: Optional[int] = None,
+ memory_mb: Optional[int] = None,
+ disk_gb: Optional[int] = None,
+ region: str = "us-east-1",
+ ) -> "Sandbox":
+ """Internal workhorse — all public factories delegate here."""
+ if ephemeral is None:
+ ephemeral = bool(image)
+
+ rt_info = None
+ if image and image.kind is None and image._registry:
+ from cua_sandbox.registry.resolve import resolve_image_kind
+
+ image = resolve_image_kind(image)
+
+ # Local connect by name — read state file
+ if name and not image and local and not ws_url and not http_url:
+ from cua_sandbox import sandbox_state
+
+ state = sandbox_state.load(name)
+ if state is None:
+ raise ValueError(
+ f"No local sandbox named '{name}' found. "
+ f"Check ~/.cua/sandboxes/ or create it with Sandbox.create()."
+ )
+ if state.get("os_type") == "android":
+ grpc_port = state.get("grpc_port")
+ adb_serial = state.get("adb_serial") or f"emulator-{state['api_port'] - 1}"
+ sdk_root = state.get("sdk_root")
+ if grpc_port:
+ from cua_sandbox.transport.grpc_emulator import (
+ GRPCEmulatorTransport,
+ )
+ from google.protobuf import empty_pb2 # noqa: F401
+
+ transport = GRPCEmulatorTransport(
+ host=state["host"],
+ grpc_port=grpc_port,
+ serial=adb_serial,
+ sdk_root=sdk_root,
+ )
+ else:
+ from cua_sandbox.transport.adb import ADBTransport
+
+ transport = ADBTransport(serial=adb_serial, sdk_root=sdk_root)
+ else:
+ api_url = f"http://{state['host']}:{state['api_port']}"
+ transport = HTTPTransport(api_url)
+ sb = cls(transport, name=name, _ephemeral=False)
+ await sb._connect()
+ return sb
+
+ if image and not runtime and local:
+ # local=True with no runtime → auto-select based on image type
+ runtime = _auto_runtime(image)
+ if image and not runtime and not local:
+ # image without runtime and not local → cloud creation
+ if not any([ws_url, http_url]):
+ transport = CloudTransport(
+ name=name,
+ api_key=api_key,
+ image=image,
+ cpu=cpu,
+ memory_mb=memory_mb,
+ disk_gb=disk_gb,
+ region=region,
+ )
+ sb = cls(transport, name=name, _ephemeral=ephemeral)
+ await sb._connect()
+ return sb
+ runtime = _auto_runtime(image)
+ if image and runtime:
+ sb_name = name or _random_name()
+ rt_info = await runtime.start(image, sb_name)
+ if rt_info.environment == "android" and not rt_info.qmp_port:
+ if rt_info.grpc_port:
+ from cua_sandbox.transport.grpc_emulator import (
+ GRPCEmulatorTransport,
+ )
+
+ adb_serial = f"emulator-{rt_info.api_port - 1}"
+ sdk_root = None
+ if hasattr(runtime, "_sdk") and runtime._sdk:
+ sdk_root = str(runtime._sdk)
+ transport = GRPCEmulatorTransport(
+ host=rt_info.host,
+ grpc_port=rt_info.grpc_port,
+ serial=adb_serial,
+ sdk_root=sdk_root,
+ )
+ else:
+ from cua_sandbox.transport.adb import ADBTransport
+
+ adb_serial = f"emulator-{rt_info.api_port - 1}"
+ sdk_root = None
+ if hasattr(runtime, "_sdk") and runtime._sdk:
+ sdk_root = str(runtime._sdk)
+ transport = ADBTransport(serial=adb_serial, sdk_root=sdk_root)
+ elif rt_info.agent_type == "osworld":
+ from cua_sandbox.transport.osworld import OSWorldTransport
+
+ transport = OSWorldTransport(
+ f"http://{rt_info.host}:{rt_info.api_port}",
+ )
+ elif rt_info.vnc_port and rt_info.ssh_port:
+ from cua_sandbox.transport.vncssh import VNCSSHTransport
+
+ await runtime.is_ready(rt_info)
+ transport = VNCSSHTransport(
+ ssh_host=rt_info.host,
+ ssh_port=rt_info.ssh_port,
+ ssh_username=rt_info.ssh_username or "admin",
+ ssh_password=rt_info.ssh_password or "admin",
+ vnc_host=rt_info.vnc_host or rt_info.host,
+ vnc_port=rt_info.vnc_port,
+ vnc_password=rt_info.vnc_password,
+ environment=rt_info.environment or image.os_type,
+ )
+ elif rt_info.vnc_port and not rt_info.qmp_port and not rt_info.api_port:
+ # VNC-only transport: QEMU VMs without a computer-server HTTP API.
+ # When api_port is also set (e.g. Docker containers, Lume VMs), prefer HTTP.
+ from cua_sandbox.transport.vnc import VNCTransport
+
+ transport = VNCTransport(
+ host=rt_info.host,
+ port=rt_info.vnc_port,
+ environment=rt_info.environment or image.os_type,
+ )
+ elif rt_info.qmp_port:
+ from cua_sandbox.transport.qmp import QMPTransport
+
+ transport = QMPTransport(
+ qmp_host=rt_info.host,
+ qmp_port=rt_info.qmp_port,
+ environment=rt_info.environment or image.os_type,
+ )
+ else:
+ transport = HTTPTransport(
+ f"http://{rt_info.host}:{rt_info.api_port}",
+ api_key=api_key,
+ container_name=container_name,
+ )
+ else:
+ transport = _make_transport(
+ ws_url=ws_url,
+ http_url=http_url,
+ api_key=api_key,
+ container_name=container_name,
+ name=name,
+ cpu=cpu,
+ memory_mb=memory_mb,
+ disk_gb=disk_gb,
+ region=region,
+ )
+ # Write persistent state for local (non-ephemeral) sandboxes
+ if not ephemeral and rt_info and local:
+ from cua_sandbox import sandbox_state
+
+ runtime_type = type(runtime).__name__.lower().replace("runtime", "")
+ # Normalize to known types
+ _rt_map = {
+ "lume": "lume",
+ "docker": "docker",
+ "qemudocker": "qemu-docker",
+ "qemubaremetal": "qemu-baremetal",
+ "qemuwsl2": "qemu-wsl2",
+ }
+ rt_key = _rt_map.get(runtime_type, runtime_type)
+ _adb_serial = None
+ _sdk_root = None
+ if image.os_type == "android":
+ _adb_serial = f"emulator-{rt_info.api_port - 1}"
+ if hasattr(runtime, "_sdk") and runtime._sdk:
+ _sdk_root = str(runtime._sdk)
+ sandbox_state.save(
+ sb_name,
+ runtime_type=rt_key,
+ image=image.to_dict(),
+ host=rt_info.host,
+ api_port=rt_info.api_port,
+ vnc_port=rt_info.vnc_port,
+ qmp_port=rt_info.qmp_port,
+ grpc_port=rt_info.grpc_port if hasattr(rt_info, "grpc_port") else None,
+ adb_serial=_adb_serial,
+ sdk_root=_sdk_root,
+ os_type=image.os_type,
+ status="running",
+ )
+
+ resolved_name = (rt_info.name if rt_info else None) or name
+ sb = cls(
+ transport,
+ name=resolved_name,
+ _runtime=runtime,
+ _runtime_info=rt_info,
+ _ephemeral=ephemeral,
+ )
+ await sb._connect()
+ return sb
+
+ def __repr__(self) -> str:
+ tname = type(self._transport).__name__
+ return f"Sandbox(name={self.name!r}, transport={tname})"
+
+
+_ADJECTIVES = [
+ "amber",
+ "bold",
+ "calm",
+ "deft",
+ "eager",
+ "fast",
+ "glad",
+ "hazy",
+ "idle",
+ "jade",
+ "keen",
+ "lazy",
+ "mild",
+ "neat",
+ "odd",
+ "pale",
+ "quiet",
+ "rapid",
+ "soft",
+ "tidy",
+ "vast",
+ "warm",
+ "zany",
+ "agile",
+ "brave",
+ "crisp",
+ "dusty",
+ "elfin",
+ "fizzy",
+ "grim",
+ "hardy",
+ "icy",
+ "jolly",
+ "kinky",
+ "lofty",
+ "misty",
+ "noble",
+ "oaken",
+ "prim",
+ "quirky",
+ "rosy",
+ "stark",
+ "trim",
+ "umber",
+ "vivid",
+ "witty",
+ "xenial",
+ "young",
+ "zippy",
+ "arcane",
+ "brisk",
+ "chilly",
+ "dim",
+ "eerie",
+ "fleet",
+ "gnarly",
+ "hushed",
+ "inky",
+ "jumpy",
+ "knotty",
+ "lithe",
+ "murky",
+ "nifty",
+ "ornate",
+ "plush",
+ "quaint",
+ "ruddy",
+ "spry",
+ "tacit",
+ "ultra",
+ "vague",
+ "wily",
+ "exact",
+ "yare",
+ "zesty",
+ "arid",
+ "blunt",
+ "cobalt",
+ "dense",
+ "ember",
+ "faint",
+ "gaunt",
+ "hollow",
+ "irked",
+ "jaded",
+ "lunar",
+ "muted",
+ "nimble",
+ "opaque",
+ "prime",
+ "quiet",
+ "ringed",
+ "sable",
+ "tawny",
+ "upset",
+ "vexed",
+ "wooly",
+ "xenon",
+ "yonder",
+ "zingy",
+]
+_NOUNS = [
+ "bear",
+ "crane",
+ "deer",
+ "eagle",
+ "finch",
+ "gecko",
+ "hawk",
+ "ibis",
+ "jay",
+ "kite",
+ "lark",
+ "mink",
+ "newt",
+ "orca",
+ "puma",
+ "quail",
+ "raven",
+ "seal",
+ "toad",
+ "vole",
+ "wren",
+ "yak",
+ "zebra",
+ "ant",
+ "bison",
+ "carp",
+ "dingo",
+ "elk",
+ "fox",
+ "gull",
+ "heron",
+ "iguana",
+ "jackal",
+ "kudu",
+ "lemur",
+ "moose",
+ "narwhal",
+ "ocelot",
+ "parrot",
+ "quokka",
+ "rhino",
+ "swan",
+ "tapir",
+ "urial",
+ "viper",
+ "walrus",
+ "xerus",
+ "yabby",
+ "zorilla",
+ "alpaca",
+ "beetle",
+ "cobra",
+ "dugong",
+ "emu",
+ "ferret",
+ "gibbon",
+ "hyena",
+ "impala",
+ "junco",
+ "kakapo",
+ "lynx",
+ "marmot",
+ "numbat",
+ "osprey",
+ "possum",
+ "quetzal",
+ "rabbit",
+ "skunk",
+ "thrush",
+ "urubu",
+ "vulture",
+ "wombat",
+ "xenops",
+ "yaffle",
+ "zonkey",
+ "addax",
+ "booby",
+ "condor",
+ "dhole",
+ "egret",
+ "fossa",
+ "gannet",
+ "hoopoe",
+ "indri",
+ "jabiru",
+ "kookaburra",
+ "loris",
+ "magpie",
+ "nene",
+ "olm",
+ "pipit",
+ "quagga",
+ "roller",
+ "shrew",
+ "teal",
+ "uakari",
+ "vervet",
+ "weevil",
+ "xeme",
+ "yellowjacket",
+ "zorach",
+]
+
+
+def _random_name() -> str:
+ return f"{random.choice(_ADJECTIVES)}-{random.choice(_NOUNS)}"
+
+
+def _make_transport(
+ *,
+ ws_url: Optional[str] = None,
+ http_url: Optional[str] = None,
+ api_key: Optional[str] = None,
+ container_name: Optional[str] = None,
+ name: Optional[str] = None,
+ cpu: Optional[int] = None,
+ memory_mb: Optional[int] = None,
+ disk_gb: Optional[int] = None,
+ region: str = "us-east-1",
+) -> Transport:
+ if ws_url:
+ return WebSocketTransport(ws_url, api_key=api_key)
+ if http_url:
+ return HTTPTransport(http_url, api_key=api_key, container_name=container_name)
+ return CloudTransport(
+ name=name,
+ api_key=api_key,
+ cpu=cpu,
+ memory_mb=memory_mb,
+ disk_gb=disk_gb,
+ region=region,
+ )
+
+
+@asynccontextmanager
+async def sandbox(
+ *,
+ local: bool = False,
+ ws_url: Optional[str] = None,
+ http_url: Optional[str] = None,
+ api_key: Optional[str] = None,
+ container_name: Optional[str] = None,
+ image: Optional[Image] = None,
+ runtime: Optional["Runtime"] = None,
+ name: Optional[str] = None,
+ ephemeral: Optional[bool] = None,
+ cpu: Optional[int] = None,
+ memory_mb: Optional[int] = None,
+ disk_gb: Optional[int] = None,
+ region: str = "us-east-1",
+) -> AsyncIterator[Sandbox]:
+ """Async context manager for a sandboxed environment.
+
+ .. deprecated::
+ Prefer ``Sandbox.create()``, ``Sandbox.connect()``, or
+ ``Sandbox.ephemeral()`` instead.
+ """
+ sb = await Sandbox._create(
+ local=local,
+ ws_url=ws_url,
+ http_url=http_url,
+ api_key=api_key,
+ container_name=container_name,
+ image=image,
+ runtime=runtime,
+ name=name,
+ ephemeral=ephemeral,
+ cpu=cpu,
+ memory_mb=memory_mb,
+ disk_gb=disk_gb,
+ region=region,
+ )
+ try:
+ yield sb
+ finally:
+ if sb._ephemeral:
+ await sb.destroy()
+ else:
+ await sb.disconnect()
diff --git a/libs/python/cua-sandbox/cua_sandbox/sandbox_state.py b/libs/python/cua-sandbox/cua_sandbox/sandbox_state.py
new file mode 100644
index 0000000000..5898ef9193
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/sandbox_state.py
@@ -0,0 +1,105 @@
+"""Persistent state tracking for local sandboxes.
+
+Each running local sandbox writes a JSON file at ~/.cua/sandboxes/{name}.json.
+This allows Sandbox.connect(name, local=True), Sandbox.list(local=True), etc.
+to work across Python process restarts.
+
+State files are written by Sandbox.create() for local runtimes and deleted by
+Sandbox.delete(). Ephemeral sandboxes never write state files.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+SANDBOX_STATE_DIR = Path.home() / ".cua" / "sandboxes"
+
+
+def _state_path(name: str) -> Path:
+ return SANDBOX_STATE_DIR / f"{name}.json"
+
+
+def save(
+ name: str,
+ *,
+ runtime_type: str,
+ image: dict,
+ host: str,
+ api_port: int,
+ vnc_port: Optional[int] = None,
+ qmp_port: Optional[int] = None,
+ grpc_port: Optional[int] = None,
+ adb_serial: Optional[str] = None,
+ sdk_root: Optional[str] = None,
+ disk_path: Optional[str] = None,
+ os_type: Optional[str] = None,
+ vnc_display: Optional[int] = None,
+ memory_mb: Optional[int] = None,
+ cpu_count: Optional[int] = None,
+ arch: Optional[str] = None,
+ status: str = "running",
+) -> None:
+ """Write or overwrite the state file for a local sandbox."""
+ SANDBOX_STATE_DIR.mkdir(parents=True, exist_ok=True)
+ data: dict[str, Any] = {
+ "name": name,
+ "runtime_type": runtime_type,
+ "image": image,
+ "host": host,
+ "api_port": api_port,
+ "vnc_port": vnc_port,
+ "qmp_port": qmp_port,
+ "grpc_port": grpc_port,
+ "adb_serial": adb_serial,
+ "sdk_root": sdk_root,
+ "disk_path": disk_path,
+ "os_type": os_type,
+ "vnc_display": vnc_display,
+ "memory_mb": memory_mb,
+ "cpu_count": cpu_count,
+ "arch": arch,
+ "status": status,
+ "created_at": datetime.now(timezone.utc).isoformat(),
+ }
+ _state_path(name).write_text(json.dumps(data, indent=2))
+
+
+def load(name: str) -> Optional[dict]:
+ """Load state for a named sandbox, or None if not found."""
+ p = _state_path(name)
+ if not p.exists():
+ return None
+ try:
+ return json.loads(p.read_text())
+ except (json.JSONDecodeError, OSError):
+ return None
+
+
+def update(name: str, **fields: Any) -> None:
+ """Update specific fields in an existing state file."""
+ data = load(name)
+ if data is None:
+ return
+ data.update(fields)
+ _state_path(name).write_text(json.dumps(data, indent=2))
+
+
+def delete(name: str) -> None:
+ """Remove the state file for a sandbox."""
+ _state_path(name).unlink(missing_ok=True)
+
+
+def list_all() -> list[dict]:
+ """Return all state file contents."""
+ if not SANDBOX_STATE_DIR.exists():
+ return []
+ result = []
+ for p in SANDBOX_STATE_DIR.glob("*.json"):
+ try:
+ result.append(json.loads(p.read_text()))
+ except (json.JSONDecodeError, OSError):
+ pass
+ return result
diff --git a/libs/python/cua-sandbox/cua_sandbox/sync/__init__.py b/libs/python/cua-sandbox/cua_sandbox/sync/__init__.py
new file mode 100644
index 0000000000..8d38d77b68
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/sync/__init__.py
@@ -0,0 +1,102 @@
+"""Synchronous API wrappers for scripts and notebooks.
+
+Usage::
+
+ from cua_sandbox.sync import sandbox, localhost, Image
+
+ # Blocking sandbox
+ with sandbox(local=True) as sb:
+ sb.mouse.click(100, 200)
+ img = sb.screenshot()
+
+ # Blocking localhost
+ with localhost() as host:
+ host.mouse.click(100, 200)
+"""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import contextmanager
+from typing import Any, Iterator, Optional
+
+from cua_sandbox.image import Image
+from cua_sandbox.localhost import Localhost as _AsyncLocalhost
+from cua_sandbox.sandbox import Sandbox as _AsyncSandbox
+
+
+def _get_or_create_loop() -> asyncio.AbstractEventLoop:
+ """Get the running event loop, or create a new one."""
+ try:
+ loop = asyncio.get_running_loop()
+ return loop
+ except RuntimeError:
+ loop = asyncio.new_event_loop()
+ asyncio.set_event_loop(loop)
+ return loop
+
+
+def _run(coro: Any) -> Any:
+ """Run a coroutine synchronously."""
+ try:
+ asyncio.get_running_loop()
+ # We're inside an existing event loop (e.g. Jupyter) — use nest_asyncio pattern
+ import nest_asyncio
+
+ nest_asyncio.apply()
+ return asyncio.get_event_loop().run_until_complete(coro)
+ except RuntimeError:
+ return asyncio.run(coro)
+
+
+class _SyncProxy:
+ """Wraps an async object and makes attribute access synchronous."""
+
+ def __init__(self, async_obj: Any):
+ self._async_obj = async_obj
+
+ def __getattr__(self, name: str) -> Any:
+ attr = getattr(self._async_obj, name)
+ if asyncio.iscoroutinefunction(attr):
+
+ def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+ return _run(attr(*args, **kwargs))
+
+ return sync_wrapper
+ # If the attribute is an interface object, wrap it too
+ if hasattr(attr, "_t"): # Interface objects have _t (transport)
+ return _SyncProxy(attr)
+ return attr
+
+ def __repr__(self) -> str:
+ return f"Sync({self._async_obj!r})"
+
+
+@contextmanager
+def sandbox(
+ *,
+ local: bool = False,
+ ws_url: Optional[str] = None,
+ api_key: Optional[str] = None,
+ image: Optional[Image] = None,
+ name: Optional[str] = None,
+) -> Iterator[_SyncProxy]:
+ """Synchronous context manager yielding a sync-wrapped Sandbox."""
+ sb = _run(_AsyncSandbox._create(local=local, ws_url=ws_url, api_key=api_key, name=name))
+ proxy = _SyncProxy(sb)
+ try:
+ yield proxy
+ finally:
+ _run(sb.disconnect())
+
+
+@contextmanager
+def localhost() -> Iterator[_SyncProxy]:
+ """Synchronous context manager yielding a sync-wrapped Localhost."""
+ host = _AsyncLocalhost()
+ _run(host._connect())
+ proxy = _SyncProxy(host)
+ try:
+ yield proxy
+ finally:
+ _run(host.disconnect())
diff --git a/libs/python/cua-sandbox/cua_sandbox/transport/__init__.py b/libs/python/cua-sandbox/cua_sandbox/transport/__init__.py
new file mode 100644
index 0000000000..8339174d02
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/transport/__init__.py
@@ -0,0 +1,25 @@
+from cua_sandbox.transport.adb import ADBTransport
+from cua_sandbox.transport.base import Transport
+from cua_sandbox.transport.cloud import CloudTransport
+from cua_sandbox.transport.http import HTTPTransport
+from cua_sandbox.transport.local import LocalTransport
+from cua_sandbox.transport.osworld import OSWorldTransport
+from cua_sandbox.transport.qmp import QMPTransport
+from cua_sandbox.transport.ssh import SSHTransport
+from cua_sandbox.transport.vnc import VNCTransport
+from cua_sandbox.transport.vncssh import VNCSSHTransport
+from cua_sandbox.transport.websocket import WebSocketTransport
+
+__all__ = [
+ "Transport",
+ "LocalTransport",
+ "WebSocketTransport",
+ "HTTPTransport",
+ "CloudTransport",
+ "QMPTransport",
+ "OSWorldTransport",
+ "ADBTransport",
+ "VNCTransport",
+ "VNCSSHTransport",
+ "SSHTransport",
+]
diff --git a/libs/python/cua-sandbox/cua_sandbox/transport/_grpc_emulator/__init__.py b/libs/python/cua-sandbox/cua_sandbox/transport/_grpc_emulator/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/libs/python/cua-sandbox/cua_sandbox/transport/_grpc_emulator/emulator_controller_pb2.py b/libs/python/cua-sandbox/cua_sandbox/transport/_grpc_emulator/emulator_controller_pb2.py
new file mode 100644
index 0000000000..194652032e
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/transport/_grpc_emulator/emulator_controller_pb2.py
@@ -0,0 +1,215 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler. DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: emulator_controller.proto
+# Protobuf Python Version: 6.31.1
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+
+_runtime_version.ValidateProtobufRuntimeVersion(
+ _runtime_version.Domain.PUBLIC, 6, 31, 1, "", "emulator_controller.proto"
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(
+ b'\n\x19\x65mulator_controller.proto\x12\x19\x61ndroid.emulation.control\x1a\x1bgoogle/protobuf/empty.proto"\xf9\x01\n\nVmRunState\x12=\n\x05state\x18\x01 \x01(\x0e\x32..android.emulation.control.VmRunState.RunState"\xab\x01\n\x08RunState\x12\x0b\n\x07UNKNOWN\x10\x00\x12\x0b\n\x07RUNNING\x10\x01\x12\x0e\n\nRESTORE_VM\x10\x02\x12\n\n\x06PAUSED\x10\x03\x12\x0b\n\x07SAVE_VM\x10\x04\x12\x0c\n\x08SHUTDOWN\x10\x05\x12\r\n\tTERMINATE\x10\x07\x12\t\n\x05RESET\x10\t\x12\x12\n\x0eINTERNAL_ERROR\x10\n\x12\x0b\n\x07RESTART\x10\x0b\x12\t\n\x05START\x10\x0c\x12\x08\n\x04STOP\x10\r""\n\x0eParameterValue\x12\x10\n\x04\x64\x61ta\x18\x01 \x03(\x02\x42\x02\x10\x01"\x80\x05\n\x12PhysicalModelValue\x12J\n\x06target\x18\x01 \x01(\x0e\x32:.android.emulation.control.PhysicalModelValue.PhysicalType\x12\x43\n\x06status\x18\x02 \x01(\x0e\x32\x33.android.emulation.control.PhysicalModelValue.State\x12\x38\n\x05value\x18\x03 \x01(\x0b\x32).android.emulation.control.ParameterValue"U\n\x05State\x12\x06\n\x02OK\x10\x00\x12\x17\n\nNO_SERVICE\x10\xfd\xff\xff\xff\xff\xff\xff\xff\xff\x01\x12\x15\n\x08\x44ISABLED\x10\xfe\xff\xff\xff\xff\xff\xff\xff\xff\x01\x12\x14\n\x07UNKNOWN\x10\xff\xff\xff\xff\xff\xff\xff\xff\xff\x01"\xc7\x02\n\x0cPhysicalType\x12\x0c\n\x08POSITION\x10\x00\x12\x0c\n\x08ROTATION\x10\x01\x12\x12\n\x0eMAGNETIC_FIELD\x10\x02\x12\x0f\n\x0bTEMPERATURE\x10\x03\x12\r\n\tPROXIMITY\x10\x04\x12\t\n\x05LIGHT\x10\x05\x12\x0c\n\x08PRESSURE\x10\x06\x12\x0c\n\x08HUMIDITY\x10\x07\x12\x0c\n\x08VELOCITY\x10\x08\x12\x12\n\x0e\x41MBIENT_MOTION\x10\t\x12\x10\n\x0cHINGE_ANGLE0\x10\n\x12\x10\n\x0cHINGE_ANGLE1\x10\x0b\x12\x10\n\x0cHINGE_ANGLE2\x10\x0c\x12\r\n\tROLLABLE0\x10\r\x12\r\n\tROLLABLE1\x10\x0e\x12\r\n\tROLLABLE2\x10\x0f\x12\x0b\n\x07POSTURE\x10\x10\x12\x0e\n\nHEART_RATE\x10\x11\x12\x0e\n\nRGBC_LIGHT\x10\x12\x12\x0e\n\nWRIST_TILT\x10\x13"\xc4\x04\n\x0bSensorValue\x12\x41\n\x06target\x18\x01 \x01(\x0e\x32\x31.android.emulation.control.SensorValue.SensorType\x12<\n\x06status\x18\x02 \x01(\x0e\x32,.android.emulation.control.SensorValue.State\x12\x38\n\x05value\x18\x03 \x01(\x0b\x32).android.emulation.control.ParameterValue"U\n\x05State\x12\x06\n\x02OK\x10\x00\x12\x17\n\nNO_SERVICE\x10\xfd\xff\xff\xff\xff\xff\xff\xff\xff\x01\x12\x15\n\x08\x44ISABLED\x10\xfe\xff\xff\xff\xff\xff\xff\xff\xff\x01\x12\x14\n\x07UNKNOWN\x10\xff\xff\xff\xff\xff\xff\xff\xff\xff\x01"\xa2\x02\n\nSensorType\x12\x10\n\x0c\x41\x43\x43\x45LERATION\x10\x00\x12\r\n\tGYROSCOPE\x10\x01\x12\x12\n\x0eMAGNETIC_FIELD\x10\x02\x12\x0f\n\x0bORIENTATION\x10\x03\x12\x0f\n\x0bTEMPERATURE\x10\x04\x12\r\n\tPROXIMITY\x10\x05\x12\t\n\x05LIGHT\x10\x06\x12\x0c\n\x08PRESSURE\x10\x07\x12\x0c\n\x08HUMIDITY\x10\x08\x12\x1f\n\x1bMAGNETIC_FIELD_UNCALIBRATED\x10\t\x12\x1a\n\x16GYROSCOPE_UNCALIBRATED\x10\n\x12\x0e\n\nHEART_RATE\x10\x0e\x12\x0e\n\nRGBC_LIGHT\x10\x0f\x12\x1d\n\x19\x41\x43\x43\x45LERATION_UNCALIBRATED\x10\x11\x12\x0b\n\x07HEADING\x10\x12"\x96\x01\n\x0f\x42rightnessValue\x12\x44\n\x06target\x18\x01 \x01(\x0e\x32\x34.android.emulation.control.BrightnessValue.LightType\x12\r\n\x05value\x18\x02 \x01(\r".\n\tLightType\x12\x07\n\x03LCD\x10\x00\x12\x0c\n\x08KEYBOARD\x10\x01\x12\n\n\x06\x42UTTON\x10\x02"I\n\x0b\x44isplayMode\x12:\n\x05value\x18\x01 \x01(\x0e\x32+.android.emulation.control.DisplayModeValue"\xae\x01\n\tXrOptions\x12\x45\n\x0b\x65nvironment\x18\x01 \x01(\x0e\x32\x30.android.emulation.control.XrOptions.Environment\x12\x1f\n\x17passthrough_coefficient\x18\x02 \x01(\x02"9\n\x0b\x45nvironment\x12\x13\n\x0fLIVING_ROOM_DAY\x10\x00\x12\x15\n\x11LIVING_ROOM_NIGHT\x10\x01"\xda\x01\n\nLogMessage\x12\x10\n\x08\x63ontents\x18\x01 \x01(\t\x12\x11\n\x05start\x18\x02 \x01(\x03\x42\x02\x18\x01\x12\x10\n\x04next\x18\x03 \x01(\x03\x42\x02\x18\x01\x12;\n\x04sort\x18\x04 \x01(\x0e\x32-.android.emulation.control.LogMessage.LogType\x12\x37\n\x07\x65ntries\x18\x05 \x03(\x0b\x32&.android.emulation.control.LogcatEntry"\x1f\n\x07LogType\x12\x08\n\x04Text\x10\x00\x12\n\n\x06Parsed\x10\x01"\x86\x02\n\x0bLogcatEntry\x12\x11\n\ttimestamp\x18\x01 \x01(\x04\x12\x0b\n\x03pid\x18\x02 \x01(\r\x12\x0b\n\x03tid\x18\x03 \x01(\r\x12>\n\x05level\x18\x04 \x01(\x0e\x32/.android.emulation.control.LogcatEntry.LogLevel\x12\x0b\n\x03tag\x18\x05 \x01(\t\x12\x0b\n\x03msg\x18\x06 \x01(\t"p\n\x08LogLevel\x12\x0b\n\x07UNKNOWN\x10\x00\x12\x0b\n\x07\x44\x45\x46\x41ULT\x10\x01\x12\x0b\n\x07VERBOSE\x10\x02\x12\t\n\x05\x44\x45\x42UG\x10\x03\x12\x08\n\x04INFO\x10\x04\x12\x08\n\x04WARN\x10\x05\x12\x07\n\x03\x45RR\x10\x06\x12\t\n\x05\x46\x41TAL\x10\x07\x12\n\n\x06SILENT\x10\x08"\xf5\x01\n\x0fVmConfiguration\x12S\n\x0ehypervisorType\x18\x01 \x01(\x0e\x32;.android.emulation.control.VmConfiguration.VmHypervisorType\x12\x18\n\x10numberOfCpuCores\x18\x02 \x01(\x05\x12\x14\n\x0cramSizeBytes\x18\x03 \x01(\x03"]\n\x10VmHypervisorType\x12\x0b\n\x07UNKNOWN\x10\x00\x12\x08\n\x04NONE\x10\x01\x12\x07\n\x03KVM\x10\x02\x12\x0c\n\x04HAXM\x10\x03\x1a\x02\x08\x01\x12\x07\n\x03HVF\x10\x04\x12\x08\n\x04WHPX\x10\x05\x12\x08\n\x04\x41\x45HD\x10\x06"\x18\n\x08\x43lipData\x12\x0c\n\x04text\x18\x01 \x01(\t"\x8f\x02\n\x05Touch\x12\t\n\x01x\x18\x01 \x01(\x05\x12\t\n\x01y\x18\x02 \x01(\x05\x12\x12\n\nidentifier\x18\x03 \x01(\x05\x12\x10\n\x08pressure\x18\x04 \x01(\x05\x12\x13\n\x0btouch_major\x18\x05 \x01(\x05\x12\x13\n\x0btouch_minor\x18\x06 \x01(\x05\x12\x44\n\nexpiration\x18\x07 \x01(\x0e\x32\x30.android.emulation.control.Touch.EventExpiration\x12\x13\n\x0borientation\x18\x08 \x01(\x05"E\n\x0f\x45ventExpiration\x12 \n\x1c\x45VENT_EXPIRATION_UNSPECIFIED\x10\x00\x12\x10\n\x0cNEVER_EXPIRE\x10\x01"i\n\x03Pen\x12\x32\n\x08location\x18\x01 \x01(\x0b\x32 .android.emulation.control.Touch\x12\x16\n\x0e\x62utton_pressed\x18\x02 \x01(\x08\x12\x16\n\x0erubber_pointer\x18\x03 \x01(\x08"P\n\nTouchEvent\x12\x31\n\x07touches\x18\x01 \x03(\x0b\x32 .android.emulation.control.Touch\x12\x0f\n\x07\x64isplay\x18\x02 \x01(\x05"T\n\rTouchpadEvent\x12\x31\n\x07touches\x18\x01 \x03(\x0b\x32 .android.emulation.control.Touch\x12\x10\n\x08touchpad\x18\x02 \x01(\x05"K\n\x08PenEvent\x12.\n\x06\x65vents\x18\x01 \x03(\x0b\x32\x1e.android.emulation.control.Pen\x12\x0f\n\x07\x64isplay\x18\x02 \x01(\x05"D\n\nMouseEvent\x12\t\n\x01x\x18\x01 \x01(\x05\x12\t\n\x01y\x18\x02 \x01(\x05\x12\x0f\n\x07\x62uttons\x18\x03 \x01(\x05\x12\x0f\n\x07\x64isplay\x18\x04 \x01(\x05"5\n\nWheelEvent\x12\n\n\x02\x64x\x18\x01 \x01(\x05\x12\n\n\x02\x64y\x18\x02 \x01(\x05\x12\x0f\n\x07\x64isplay\x18\x03 \x01(\x05"\xc1\x02\n\rKeyboardEvent\x12\x46\n\x08\x63odeType\x18\x01 \x01(\x0e\x32\x34.android.emulation.control.KeyboardEvent.KeyCodeType\x12H\n\teventType\x18\x02 \x01(\x0e\x32\x35.android.emulation.control.KeyboardEvent.KeyEventType\x12\x0f\n\x07keyCode\x18\x03 \x01(\x05\x12\x0b\n\x03key\x18\x04 \x01(\t\x12\x0c\n\x04text\x18\x05 \x01(\t"<\n\x0bKeyCodeType\x12\x07\n\x03Usb\x10\x00\x12\t\n\x05\x45vdev\x10\x01\x12\x07\n\x03XKB\x10\x02\x12\x07\n\x03Win\x10\x03\x12\x07\n\x03Mac\x10\x04"4\n\x0cKeyEventType\x12\x0b\n\x07keydown\x10\x00\x12\t\n\x05keyup\x10\x01\x12\x0c\n\x08keypress\x10\x02"`\n\tXrCommand\x12;\n\x06\x61\x63tion\x18\x01 \x01(\x0e\x32+.android.emulation.control.XrCommand.Action"\x16\n\x06\x41\x63tion\x12\x0c\n\x08RECENTER\x10\x00"\xbc\x07\n\nInputEvent\x12=\n\tkey_event\x18\x01 \x01(\x0b\x32(.android.emulation.control.KeyboardEventH\x00\x12<\n\x0btouch_event\x18\x02 \x01(\x0b\x32%.android.emulation.control.TouchEventH\x00\x12<\n\x0bmouse_event\x18\x03 \x01(\x0b\x32%.android.emulation.control.MouseEventH\x00\x12@\n\randroid_event\x18\x04 \x01(\x0b\x32\'.android.emulation.control.AndroidEventH\x00\x12\x38\n\tpen_event\x18\x05 \x01(\x0b\x32#.android.emulation.control.PenEventH\x00\x12<\n\x0bwheel_event\x18\x06 \x01(\x0b\x32%.android.emulation.control.WheelEventH\x00\x12>\n\rxr_hand_event\x18\x07 \x01(\x0b\x32%.android.emulation.control.MouseEventH\x00\x12=\n\x0cxr_eye_event\x18\x08 \x01(\x0b\x32%.android.emulation.control.MouseEventH\x00\x12:\n\nxr_command\x18\t \x01(\x0b\x32$.android.emulation.control.XrCommandH\x00\x12K\n\x16xr_head_rotation_event\x18\n \x01(\x0b\x32).android.emulation.control.RotationRadianH\x00\x12H\n\x16xr_head_movement_event\x18\x0b \x01(\x0b\x32&.android.emulation.control.TranslationH\x00\x12T\n\x1exr_head_angular_velocity_event\x18\x0c \x01(\x0b\x32*.android.emulation.control.AngularVelocityH\x00\x12\x45\n\x16xr_head_velocity_event\x18\r \x01(\x0b\x32#.android.emulation.control.VelocityH\x00\x12\x42\n\x0etouchpad_event\x18\x0e \x01(\x0b\x32(.android.emulation.control.TouchpadEventH\x00\x42\x06\n\x04type"J\n\x0c\x41ndroidEvent\x12\x0c\n\x04type\x18\x01 \x01(\x05\x12\x0c\n\x04\x63ode\x18\x02 \x01(\x05\x12\r\n\x05value\x18\x03 \x01(\x05\x12\x0f\n\x07\x64isplay\x18\x04 \x01(\x05"2\n\x0b\x46ingerprint\x12\x12\n\nisTouching\x18\x01 \x01(\x08\x12\x0f\n\x07touchId\x18\x02 \x01(\x05"\x8c\x01\n\x08GpsState\x12\x15\n\rpassiveUpdate\x18\x01 \x01(\x08\x12\x10\n\x08latitude\x18\x02 \x01(\x01\x12\x11\n\tlongitude\x18\x03 \x01(\x01\x12\r\n\x05speed\x18\x04 \x01(\x01\x12\x0f\n\x07\x62\x65\x61ring\x18\x05 \x01(\x01\x12\x10\n\x08\x61ltitude\x18\x06 \x01(\x01\x12\x12\n\nsatellites\x18\x07 \x01(\x05"\x87\x04\n\x0c\x42\x61tteryState\x12\x12\n\nhasBattery\x18\x01 \x01(\x08\x12\x11\n\tisPresent\x18\x02 \x01(\x08\x12G\n\x07\x63harger\x18\x03 \x01(\x0e\x32\x36.android.emulation.control.BatteryState.BatteryCharger\x12\x13\n\x0b\x63hargeLevel\x18\x04 \x01(\x05\x12\x45\n\x06health\x18\x05 \x01(\x0e\x32\x35.android.emulation.control.BatteryState.BatteryHealth\x12\x45\n\x06status\x18\x06 \x01(\x0e\x32\x35.android.emulation.control.BatteryState.BatteryStatus"W\n\rBatteryStatus\x12\x0b\n\x07UNKNOWN\x10\x00\x12\x0c\n\x08\x43HARGING\x10\x01\x12\x0f\n\x0b\x44ISCHARGING\x10\x02\x12\x10\n\x0cNOT_CHARGING\x10\x03\x12\x08\n\x04\x46ULL\x10\x04"9\n\x0e\x42\x61tteryCharger\x12\x08\n\x04NONE\x10\x00\x12\x06\n\x02\x41\x43\x10\x01\x12\x07\n\x03USB\x10\x02\x12\x0c\n\x08WIRELESS\x10\x03"P\n\rBatteryHealth\x12\x08\n\x04GOOD\x10\x00\x12\n\n\x06\x46\x41ILED\x10\x01\x12\x08\n\x04\x44\x45\x41\x44\x10\x02\x12\x0f\n\x0bOVERVOLTAGE\x10\x03\x12\x0e\n\nOVERHEATED\x10\x04"\xae\x01\n\x0eImageTransport\x12K\n\x07\x63hannel\x18\x01 \x01(\x0e\x32:.android.emulation.control.ImageTransport.TransportChannel\x12\x0e\n\x06handle\x18\x02 \x01(\t"?\n\x10TransportChannel\x12!\n\x1dTRANSPORT_CHANNEL_UNSPECIFIED\x10\x00\x12\x08\n\x04MMAP\x10\x01"P\n\rFoldedDisplay\x12\r\n\x05width\x18\x01 \x01(\r\x12\x0e\n\x06height\x18\x02 \x01(\r\x12\x0f\n\x07xOffset\x18\x03 \x01(\r\x12\x0f\n\x07yOffset\x18\x04 \x01(\r"\xa7\x03\n\x0bImageFormat\x12@\n\x06\x66ormat\x18\x01 \x01(\x0e\x32\x30.android.emulation.control.ImageFormat.ImgFormat\x12\x35\n\x08rotation\x18\x02 \x01(\x0b\x32#.android.emulation.control.Rotation\x12\r\n\x05width\x18\x03 \x01(\r\x12\x0e\n\x06height\x18\x04 \x01(\r\x12\x0f\n\x07\x64isplay\x18\x05 \x01(\r\x12<\n\ttransport\x18\x06 \x01(\x0b\x32).android.emulation.control.ImageTransport\x12?\n\rfoldedDisplay\x18\x07 \x01(\x0b\x32(.android.emulation.control.FoldedDisplay\x12@\n\x0b\x64isplayMode\x18\x08 \x01(\x0e\x32+.android.emulation.control.DisplayModeValue".\n\tImgFormat\x12\x07\n\x03PNG\x10\x00\x12\x0c\n\x08RGBA8888\x10\x01\x12\n\n\x06RGB888\x10\x02"\x97\x01\n\x05Image\x12\x36\n\x06\x66ormat\x18\x01 \x01(\x0b\x32&.android.emulation.control.ImageFormat\x12\x11\n\x05width\x18\x02 \x01(\rB\x02\x18\x01\x12\x12\n\x06height\x18\x03 \x01(\rB\x02\x18\x01\x12\r\n\x05image\x18\x04 \x01(\x0c\x12\x0b\n\x03seq\x18\x05 \x01(\r\x12\x13\n\x0btimestampUs\x18\x06 \x01(\x04"\xd5\x01\n\x08Rotation\x12\x42\n\x08rotation\x18\x01 \x01(\x0e\x32\x30.android.emulation.control.Rotation.SkinRotation\x12\r\n\x05xAxis\x18\x02 \x01(\x01\x12\r\n\x05yAxis\x18\x03 \x01(\x01\x12\r\n\x05zAxis\x18\x04 \x01(\x01"X\n\x0cSkinRotation\x12\x0c\n\x08PORTRAIT\x10\x00\x12\r\n\tLANDSCAPE\x10\x01\x12\x14\n\x10REVERSE_PORTRAIT\x10\x02\x12\x15\n\x11REVERSE_LANDSCAPE\x10\x03"\xf4\x01\n\tPhoneCall\x12\x41\n\toperation\x18\x01 \x01(\x0e\x32..android.emulation.control.PhoneCall.Operation\x12\x0e\n\x06number\x18\x02 \x01(\t"\x93\x01\n\tOperation\x12\x0c\n\x08InitCall\x10\x00\x12\x0e\n\nAcceptCall\x10\x01\x12\x16\n\x12RejectCallExplicit\x10\x02\x12\x12\n\x0eRejectCallBusy\x10\x03\x12\x12\n\x0e\x44isconnectCall\x10\x04\x12\x13\n\x0fPlaceCallOnHold\x10\x05\x12\x13\n\x0fTakeCallOffHold\x10\x06"\xbc\x01\n\rPhoneResponse\x12\x43\n\x08response\x18\x01 \x01(\x0e\x32\x31.android.emulation.control.PhoneResponse.Response"f\n\x08Response\x12\x06\n\x02OK\x10\x00\x12\x10\n\x0c\x42\x61\x64Operation\x10\x01\x12\r\n\tBadNumber\x10\x02\x12\x11\n\rInvalidAction\x10\x03\x12\x10\n\x0c\x41\x63tionFailed\x10\x04\x12\x0c\n\x08RadioOff\x10\x05"#\n\x05\x45ntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t"<\n\tEntryList\x12/\n\x05\x65ntry\x18\x01 \x03(\x0b\x32 .android.emulation.control.Entry"\xd5\x02\n\x0e\x45mulatorStatus\x12\x0f\n\x07version\x18\x01 \x01(\t\x12\x0e\n\x06uptime\x18\x02 \x01(\x04\x12\x0e\n\x06\x62ooted\x18\x03 \x01(\x08\x12<\n\x08vmConfig\x18\x04 \x01(\x0b\x32*.android.emulation.control.VmConfiguration\x12<\n\x0ehardwareConfig\x18\x05 \x01(\x0b\x32$.android.emulation.control.EntryList\x12\x11\n\theartbeat\x18\x06 \x01(\x04\x12O\n\x0bguestConfig\x18\x07 \x03(\x0b\x32:.android.emulation.control.EmulatorStatus.GuestConfigEntry\x1a\x32\n\x10GuestConfigEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t:\x02\x38\x01"\xfb\x02\n\x0b\x41udioFormat\x12\x14\n\x0csamplingRate\x18\x01 \x01(\x04\x12\x41\n\x08\x63hannels\x18\x02 \x01(\x0e\x32/.android.emulation.control.AudioFormat.Channels\x12\x43\n\x06\x66ormat\x18\x03 \x01(\x0e\x32\x33.android.emulation.control.AudioFormat.SampleFormat\x12\x41\n\x04mode\x18\x04 \x01(\x0e\x32\x33.android.emulation.control.AudioFormat.DeliveryMode"/\n\x0cSampleFormat\x12\x0e\n\nAUD_FMT_U8\x10\x00\x12\x0f\n\x0b\x41UD_FMT_S16\x10\x01" \n\x08\x43hannels\x12\x08\n\x04Mono\x10\x00\x12\n\n\x06Stereo\x10\x01"8\n\x0c\x44\x65liveryMode\x12\x14\n\x10MODE_UNSPECIFIED\x10\x00\x12\x12\n\x0eMODE_REAL_TIME\x10\x01"g\n\x0b\x41udioPacket\x12\x36\n\x06\x66ormat\x18\x01 \x01(\x0b\x32&.android.emulation.control.AudioFormat\x12\x11\n\ttimestamp\x18\x02 \x01(\x04\x12\r\n\x05\x61udio\x18\x03 \x01(\x0c".\n\nSmsMessage\x12\x12\n\nsrcAddress\x18\x01 \x01(\t\x12\x0c\n\x04text\x18\x02 \x01(\t"\xcb\x02\n\x14\x44isplayConfiguration\x12\r\n\x05width\x18\x01 \x01(\r\x12\x0e\n\x06height\x18\x02 \x01(\r\x12\x0b\n\x03\x64pi\x18\x03 \x01(\r\x12\r\n\x05\x66lags\x18\x04 \x01(\r\x12\x0f\n\x07\x64isplay\x18\x05 \x01(\r"\xe6\x01\n\x0c\x44isplayFlags\x12\x1c\n\x18\x44ISPLAYFLAGS_UNSPECIFIED\x10\x00\x12\x1f\n\x1bVIRTUAL_DISPLAY_FLAG_PUBLIC\x10\x01\x12%\n!VIRTUAL_DISPLAY_FLAG_PRESENTATION\x10\x02\x12\x1f\n\x1bVIRTUAL_DISPLAY_FLAG_SECURE\x10\x04\x12)\n%VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY\x10\x08\x12$\n VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR\x10\x10"\x89\x01\n\x15\x44isplayConfigurations\x12\x41\n\x08\x64isplays\x18\x01 \x03(\x0b\x32/.android.emulation.control.DisplayConfiguration\x12\x18\n\x10userConfigurable\x18\x02 \x01(\r\x12\x13\n\x0bmaxDisplays\x18\x03 \x01(\r"\x9b\x04\n\x0cNotification\x12K\n\x12\x63\x61meraNotification\x18\x02 \x01(\x0b\x32-.android.emulation.control.CameraNotificationH\x00\x12w\n(displayConfigurationsChangedNotification\x18\x03 \x01(\x0b\x32\x43.android.emulation.control.DisplayConfigurationsChangedNotificationH\x00\x12\x35\n\x07posture\x18\x04 \x01(\x0b\x32".android.emulation.control.PostureH\x00\x12\x46\n\x06\x62ooted\x18\x05 \x01(\x0b\x32\x34.android.emulation.control.BootCompletedNotificationH\x00\x12@\n\nbrightness\x18\x06 \x01(\x0b\x32*.android.emulation.control.BrightnessValueH\x00\x12\x41\n\rtextViewFocus\x18\x07 \x01(\x0b\x32(.android.emulation.control.TextViewFocusH\x00\x12\x39\n\txrOptions\x18\x08 \x01(\x0b\x32$.android.emulation.control.XrOptionsH\x00\x42\x06\n\x04type")\n\x19\x42ootCompletedNotification\x12\x0c\n\x04time\x18\x01 \x01(\x05"5\n\x12\x43\x61meraNotification\x12\x0e\n\x06\x61\x63tive\x18\x01 \x01(\x08\x12\x0f\n\x07\x64isplay\x18\x02 \x01(\x05":\n\rTextViewFocus\x12\x18\n\x10textViewHasFocus\x18\x01 \x01(\x08\x12\x0f\n\x07\x64isplay\x18\x02 \x01(\x05"{\n(DisplayConfigurationsChangedNotification\x12O\n\x15\x64isplayConfigurations\x18\x01 \x01(\x0b\x32\x30.android.emulation.control.DisplayConfigurations"1\n\x0eRotationRadian\x12\t\n\x01x\x18\x01 \x01(\x02\x12\t\n\x01y\x18\x02 \x01(\x02\x12\t\n\x01z\x18\x03 \x01(\x02"@\n\x0bTranslation\x12\x0f\n\x07\x64\x65lta_x\x18\x01 \x01(\x02\x12\x0f\n\x07\x64\x65lta_y\x18\x02 \x01(\x02\x12\x0f\n\x07\x64\x65lta_z\x18\x03 \x01(\x02"D\n\x0f\x41ngularVelocity\x12\x0f\n\x07omega_x\x18\x01 \x01(\x02\x12\x0f\n\x07omega_y\x18\x02 \x01(\x02\x12\x0f\n\x07omega_z\x18\x03 \x01(\x02"+\n\x08Velocity\x12\t\n\x01x\x18\x01 \x01(\x02\x12\t\n\x01y\x18\x02 \x01(\x02\x12\t\n\x01z\x18\x03 \x01(\x02"\xe8\x01\n\x07Posture\x12>\n\x05value\x18\x03 \x01(\x0e\x32/.android.emulation.control.Posture.PostureValue"\x9c\x01\n\x0cPostureValue\x12\x13\n\x0fPOSTURE_UNKNOWN\x10\x00\x12\x12\n\x0ePOSTURE_CLOSED\x10\x01\x12\x17\n\x13POSTURE_HALF_OPENED\x10\x02\x12\x12\n\x0ePOSTURE_OPENED\x10\x03\x12\x13\n\x0fPOSTURE_FLIPPED\x10\x04\x12\x10\n\x0cPOSTURE_TENT\x10\x05\x12\x0f\n\x0bPOSTURE_MAX\x10\x06"\x1d\n\x0bPhoneNumber\x12\x0e\n\x06number\x18\x01 \x01(\t*D\n\x10\x44isplayModeValue\x12\t\n\x05PHONE\x10\x00\x12\x0c\n\x08\x46OLDABLE\x10\x01\x12\n\n\x06TABLET\x10\x02\x12\x0b\n\x07\x44\x45SKTOP\x10\x03\x32\xa6\x1e\n\x12\x45mulatorController\x12\x62\n\x0cstreamSensor\x12&.android.emulation.control.SensorValue\x1a&.android.emulation.control.SensorValue"\x00\x30\x01\x12]\n\tgetSensor\x12&.android.emulation.control.SensorValue\x1a&.android.emulation.control.SensorValue"\x00\x12M\n\tsetSensor\x12&.android.emulation.control.SensorValue\x1a\x16.google.protobuf.Empty"\x00\x12[\n\x10setPhysicalModel\x12-.android.emulation.control.PhysicalModelValue\x1a\x16.google.protobuf.Empty"\x00\x12r\n\x10getPhysicalModel\x12-.android.emulation.control.PhysicalModelValue\x1a-.android.emulation.control.PhysicalModelValue"\x00\x12w\n\x13streamPhysicalModel\x12-.android.emulation.control.PhysicalModelValue\x1a-.android.emulation.control.PhysicalModelValue"\x00\x30\x01\x12M\n\x0csetClipboard\x12#.android.emulation.control.ClipData\x1a\x16.google.protobuf.Empty"\x00\x12M\n\x0cgetClipboard\x12\x16.google.protobuf.Empty\x1a#.android.emulation.control.ClipData"\x00\x12R\n\x0fstreamClipboard\x12\x16.google.protobuf.Empty\x1a#.android.emulation.control.ClipData"\x00\x30\x01\x12O\n\nsetBattery\x12\'.android.emulation.control.BatteryState\x1a\x16.google.protobuf.Empty"\x00\x12O\n\ngetBattery\x12\x16.google.protobuf.Empty\x1a\'.android.emulation.control.BatteryState"\x00\x12G\n\x06setGps\x12#.android.emulation.control.GpsState\x1a\x16.google.protobuf.Empty"\x00\x12G\n\x06getGps\x12\x16.google.protobuf.Empty\x1a#.android.emulation.control.GpsState"\x00\x12S\n\x0fsendFingerprint\x12&.android.emulation.control.Fingerprint\x1a\x16.google.protobuf.Empty"\x00\x12M\n\x07sendKey\x12(.android.emulation.control.KeyboardEvent\x1a\x16.google.protobuf.Empty"\x00\x12L\n\tsendTouch\x12%.android.emulation.control.TouchEvent\x1a\x16.google.protobuf.Empty"\x00\x12L\n\tsendMouse\x12%.android.emulation.control.MouseEvent\x1a\x16.google.protobuf.Empty"\x00\x12P\n\x0binjectWheel\x12%.android.emulation.control.WheelEvent\x1a\x16.google.protobuf.Empty"\x00(\x01\x12U\n\x10streamInputEvent\x12%.android.emulation.control.InputEvent\x1a\x16.google.protobuf.Empty"\x00(\x01\x12]\n\tsendPhone\x12$.android.emulation.control.PhoneCall\x1a(.android.emulation.control.PhoneResponse"\x00\x12\\\n\x07sendSms\x12%.android.emulation.control.SmsMessage\x1a(.android.emulation.control.PhoneResponse"\x00\x12\x64\n\x0esetPhoneNumber\x12&.android.emulation.control.PhoneNumber\x1a(.android.emulation.control.PhoneResponse"\x00\x12P\n\tgetStatus\x12\x16.google.protobuf.Empty\x1a).android.emulation.control.EmulatorStatus"\x00\x12[\n\rgetScreenshot\x12&.android.emulation.control.ImageFormat\x1a .android.emulation.control.Image"\x00\x12`\n\x10streamScreenshot\x12&.android.emulation.control.ImageFormat\x1a .android.emulation.control.Image"\x00\x30\x01\x12\x61\n\x0bstreamAudio\x12&.android.emulation.control.AudioFormat\x1a&.android.emulation.control.AudioPacket"\x00\x30\x01\x12Q\n\x0binjectAudio\x12&.android.emulation.control.AudioPacket\x1a\x16.google.protobuf.Empty"\x00(\x01\x12^\n\tgetLogcat\x12%.android.emulation.control.LogMessage\x1a%.android.emulation.control.LogMessage"\x03\x88\x02\x01\x12`\n\x0cstreamLogcat\x12%.android.emulation.control.LogMessage\x1a%.android.emulation.control.LogMessage"\x00\x30\x01\x12M\n\nsetVmState\x12%.android.emulation.control.VmRunState\x1a\x16.google.protobuf.Empty"\x00\x12M\n\ngetVmState\x12\x16.google.protobuf.Empty\x1a%.android.emulation.control.VmRunState"\x00\x12\x80\x01\n\x18setDisplayConfigurations\x12\x30.android.emulation.control.DisplayConfigurations\x1a\x30.android.emulation.control.DisplayConfigurations"\x00\x12\x66\n\x18getDisplayConfigurations\x12\x16.google.protobuf.Empty\x1a\x30.android.emulation.control.DisplayConfigurations"\x00\x12Y\n\x12streamNotification\x12\x16.google.protobuf.Empty\x1a\'.android.emulation.control.Notification"\x00\x30\x01\x12_\n\x18rotateVirtualSceneCamera\x12).android.emulation.control.RotationRadian\x1a\x16.google.protobuf.Empty"\x00\x12^\n\x1dsetVirtualSceneCameraVelocity\x12#.android.emulation.control.Velocity\x1a\x16.google.protobuf.Empty"\x00\x12J\n\nsetPosture\x12".android.emulation.control.Posture\x1a\x16.google.protobuf.Empty"\x00\x12i\n\rgetBrightness\x12*.android.emulation.control.BrightnessValue\x1a*.android.emulation.control.BrightnessValue"\x00\x12U\n\rsetBrightness\x12*.android.emulation.control.BrightnessValue\x1a\x16.google.protobuf.Empty"\x00\x12R\n\x0egetDisplayMode\x12\x16.google.protobuf.Empty\x1a&.android.emulation.control.DisplayMode"\x00\x12R\n\x0esetDisplayMode\x12&.android.emulation.control.DisplayMode\x1a\x16.google.protobuf.Empty"\x00\x12N\n\x0csetXrOptions\x12$.android.emulation.control.XrOptions\x1a\x16.google.protobuf.Empty"\x00\x12N\n\x0cgetXrOptions\x12\x16.google.protobuf.Empty\x1a$.android.emulation.control.XrOptions"\x00\x42&\n\x1c\x63om.android.emulator.controlP\x01\xa2\x02\x03\x41\x45\x43\x62\x06proto3'
+)
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, "emulator_controller_pb2", _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+ _globals["DESCRIPTOR"]._loaded_options = None
+ _globals["DESCRIPTOR"]._serialized_options = (
+ b"\n\034com.android.emulator.controlP\001\242\002\003AEC"
+ )
+ _globals["_PARAMETERVALUE"].fields_by_name["data"]._loaded_options = None
+ _globals["_PARAMETERVALUE"].fields_by_name["data"]._serialized_options = b"\020\001"
+ _globals["_LOGMESSAGE"].fields_by_name["start"]._loaded_options = None
+ _globals["_LOGMESSAGE"].fields_by_name["start"]._serialized_options = b"\030\001"
+ _globals["_LOGMESSAGE"].fields_by_name["next"]._loaded_options = None
+ _globals["_LOGMESSAGE"].fields_by_name["next"]._serialized_options = b"\030\001"
+ _globals["_VMCONFIGURATION_VMHYPERVISORTYPE"].values_by_name["HAXM"]._loaded_options = None
+ _globals["_VMCONFIGURATION_VMHYPERVISORTYPE"].values_by_name[
+ "HAXM"
+ ]._serialized_options = b"\010\001"
+ _globals["_IMAGE"].fields_by_name["width"]._loaded_options = None
+ _globals["_IMAGE"].fields_by_name["width"]._serialized_options = b"\030\001"
+ _globals["_IMAGE"].fields_by_name["height"]._loaded_options = None
+ _globals["_IMAGE"].fields_by_name["height"]._serialized_options = b"\030\001"
+ _globals["_EMULATORSTATUS_GUESTCONFIGENTRY"]._loaded_options = None
+ _globals["_EMULATORSTATUS_GUESTCONFIGENTRY"]._serialized_options = b"8\001"
+ _globals["_EMULATORCONTROLLER"].methods_by_name["getLogcat"]._loaded_options = None
+ _globals["_EMULATORCONTROLLER"].methods_by_name[
+ "getLogcat"
+ ]._serialized_options = b"\210\002\001"
+ _globals["_DISPLAYMODEVALUE"]._serialized_start = 9957
+ _globals["_DISPLAYMODEVALUE"]._serialized_end = 10025
+ _globals["_VMRUNSTATE"]._serialized_start = 86
+ _globals["_VMRUNSTATE"]._serialized_end = 335
+ _globals["_VMRUNSTATE_RUNSTATE"]._serialized_start = 164
+ _globals["_VMRUNSTATE_RUNSTATE"]._serialized_end = 335
+ _globals["_PARAMETERVALUE"]._serialized_start = 337
+ _globals["_PARAMETERVALUE"]._serialized_end = 371
+ _globals["_PHYSICALMODELVALUE"]._serialized_start = 374
+ _globals["_PHYSICALMODELVALUE"]._serialized_end = 1014
+ _globals["_PHYSICALMODELVALUE_STATE"]._serialized_start = 599
+ _globals["_PHYSICALMODELVALUE_STATE"]._serialized_end = 684
+ _globals["_PHYSICALMODELVALUE_PHYSICALTYPE"]._serialized_start = 687
+ _globals["_PHYSICALMODELVALUE_PHYSICALTYPE"]._serialized_end = 1014
+ _globals["_SENSORVALUE"]._serialized_start = 1017
+ _globals["_SENSORVALUE"]._serialized_end = 1597
+ _globals["_SENSORVALUE_STATE"]._serialized_start = 599
+ _globals["_SENSORVALUE_STATE"]._serialized_end = 684
+ _globals["_SENSORVALUE_SENSORTYPE"]._serialized_start = 1307
+ _globals["_SENSORVALUE_SENSORTYPE"]._serialized_end = 1597
+ _globals["_BRIGHTNESSVALUE"]._serialized_start = 1600
+ _globals["_BRIGHTNESSVALUE"]._serialized_end = 1750
+ _globals["_BRIGHTNESSVALUE_LIGHTTYPE"]._serialized_start = 1704
+ _globals["_BRIGHTNESSVALUE_LIGHTTYPE"]._serialized_end = 1750
+ _globals["_DISPLAYMODE"]._serialized_start = 1752
+ _globals["_DISPLAYMODE"]._serialized_end = 1825
+ _globals["_XROPTIONS"]._serialized_start = 1828
+ _globals["_XROPTIONS"]._serialized_end = 2002
+ _globals["_XROPTIONS_ENVIRONMENT"]._serialized_start = 1945
+ _globals["_XROPTIONS_ENVIRONMENT"]._serialized_end = 2002
+ _globals["_LOGMESSAGE"]._serialized_start = 2005
+ _globals["_LOGMESSAGE"]._serialized_end = 2223
+ _globals["_LOGMESSAGE_LOGTYPE"]._serialized_start = 2192
+ _globals["_LOGMESSAGE_LOGTYPE"]._serialized_end = 2223
+ _globals["_LOGCATENTRY"]._serialized_start = 2226
+ _globals["_LOGCATENTRY"]._serialized_end = 2488
+ _globals["_LOGCATENTRY_LOGLEVEL"]._serialized_start = 2376
+ _globals["_LOGCATENTRY_LOGLEVEL"]._serialized_end = 2488
+ _globals["_VMCONFIGURATION"]._serialized_start = 2491
+ _globals["_VMCONFIGURATION"]._serialized_end = 2736
+ _globals["_VMCONFIGURATION_VMHYPERVISORTYPE"]._serialized_start = 2643
+ _globals["_VMCONFIGURATION_VMHYPERVISORTYPE"]._serialized_end = 2736
+ _globals["_CLIPDATA"]._serialized_start = 2738
+ _globals["_CLIPDATA"]._serialized_end = 2762
+ _globals["_TOUCH"]._serialized_start = 2765
+ _globals["_TOUCH"]._serialized_end = 3036
+ _globals["_TOUCH_EVENTEXPIRATION"]._serialized_start = 2967
+ _globals["_TOUCH_EVENTEXPIRATION"]._serialized_end = 3036
+ _globals["_PEN"]._serialized_start = 3038
+ _globals["_PEN"]._serialized_end = 3143
+ _globals["_TOUCHEVENT"]._serialized_start = 3145
+ _globals["_TOUCHEVENT"]._serialized_end = 3225
+ _globals["_TOUCHPADEVENT"]._serialized_start = 3227
+ _globals["_TOUCHPADEVENT"]._serialized_end = 3311
+ _globals["_PENEVENT"]._serialized_start = 3313
+ _globals["_PENEVENT"]._serialized_end = 3388
+ _globals["_MOUSEEVENT"]._serialized_start = 3390
+ _globals["_MOUSEEVENT"]._serialized_end = 3458
+ _globals["_WHEELEVENT"]._serialized_start = 3460
+ _globals["_WHEELEVENT"]._serialized_end = 3513
+ _globals["_KEYBOARDEVENT"]._serialized_start = 3516
+ _globals["_KEYBOARDEVENT"]._serialized_end = 3837
+ _globals["_KEYBOARDEVENT_KEYCODETYPE"]._serialized_start = 3723
+ _globals["_KEYBOARDEVENT_KEYCODETYPE"]._serialized_end = 3783
+ _globals["_KEYBOARDEVENT_KEYEVENTTYPE"]._serialized_start = 3785
+ _globals["_KEYBOARDEVENT_KEYEVENTTYPE"]._serialized_end = 3837
+ _globals["_XRCOMMAND"]._serialized_start = 3839
+ _globals["_XRCOMMAND"]._serialized_end = 3935
+ _globals["_XRCOMMAND_ACTION"]._serialized_start = 3913
+ _globals["_XRCOMMAND_ACTION"]._serialized_end = 3935
+ _globals["_INPUTEVENT"]._serialized_start = 3938
+ _globals["_INPUTEVENT"]._serialized_end = 4894
+ _globals["_ANDROIDEVENT"]._serialized_start = 4896
+ _globals["_ANDROIDEVENT"]._serialized_end = 4970
+ _globals["_FINGERPRINT"]._serialized_start = 4972
+ _globals["_FINGERPRINT"]._serialized_end = 5022
+ _globals["_GPSSTATE"]._serialized_start = 5025
+ _globals["_GPSSTATE"]._serialized_end = 5165
+ _globals["_BATTERYSTATE"]._serialized_start = 5168
+ _globals["_BATTERYSTATE"]._serialized_end = 5687
+ _globals["_BATTERYSTATE_BATTERYSTATUS"]._serialized_start = 5459
+ _globals["_BATTERYSTATE_BATTERYSTATUS"]._serialized_end = 5546
+ _globals["_BATTERYSTATE_BATTERYCHARGER"]._serialized_start = 5548
+ _globals["_BATTERYSTATE_BATTERYCHARGER"]._serialized_end = 5605
+ _globals["_BATTERYSTATE_BATTERYHEALTH"]._serialized_start = 5607
+ _globals["_BATTERYSTATE_BATTERYHEALTH"]._serialized_end = 5687
+ _globals["_IMAGETRANSPORT"]._serialized_start = 5690
+ _globals["_IMAGETRANSPORT"]._serialized_end = 5864
+ _globals["_IMAGETRANSPORT_TRANSPORTCHANNEL"]._serialized_start = 5801
+ _globals["_IMAGETRANSPORT_TRANSPORTCHANNEL"]._serialized_end = 5864
+ _globals["_FOLDEDDISPLAY"]._serialized_start = 5866
+ _globals["_FOLDEDDISPLAY"]._serialized_end = 5946
+ _globals["_IMAGEFORMAT"]._serialized_start = 5949
+ _globals["_IMAGEFORMAT"]._serialized_end = 6372
+ _globals["_IMAGEFORMAT_IMGFORMAT"]._serialized_start = 6326
+ _globals["_IMAGEFORMAT_IMGFORMAT"]._serialized_end = 6372
+ _globals["_IMAGE"]._serialized_start = 6375
+ _globals["_IMAGE"]._serialized_end = 6526
+ _globals["_ROTATION"]._serialized_start = 6529
+ _globals["_ROTATION"]._serialized_end = 6742
+ _globals["_ROTATION_SKINROTATION"]._serialized_start = 6654
+ _globals["_ROTATION_SKINROTATION"]._serialized_end = 6742
+ _globals["_PHONECALL"]._serialized_start = 6745
+ _globals["_PHONECALL"]._serialized_end = 6989
+ _globals["_PHONECALL_OPERATION"]._serialized_start = 6842
+ _globals["_PHONECALL_OPERATION"]._serialized_end = 6989
+ _globals["_PHONERESPONSE"]._serialized_start = 6992
+ _globals["_PHONERESPONSE"]._serialized_end = 7180
+ _globals["_PHONERESPONSE_RESPONSE"]._serialized_start = 7078
+ _globals["_PHONERESPONSE_RESPONSE"]._serialized_end = 7180
+ _globals["_ENTRY"]._serialized_start = 7182
+ _globals["_ENTRY"]._serialized_end = 7217
+ _globals["_ENTRYLIST"]._serialized_start = 7219
+ _globals["_ENTRYLIST"]._serialized_end = 7279
+ _globals["_EMULATORSTATUS"]._serialized_start = 7282
+ _globals["_EMULATORSTATUS"]._serialized_end = 7623
+ _globals["_EMULATORSTATUS_GUESTCONFIGENTRY"]._serialized_start = 7573
+ _globals["_EMULATORSTATUS_GUESTCONFIGENTRY"]._serialized_end = 7623
+ _globals["_AUDIOFORMAT"]._serialized_start = 7626
+ _globals["_AUDIOFORMAT"]._serialized_end = 8005
+ _globals["_AUDIOFORMAT_SAMPLEFORMAT"]._serialized_start = 7866
+ _globals["_AUDIOFORMAT_SAMPLEFORMAT"]._serialized_end = 7913
+ _globals["_AUDIOFORMAT_CHANNELS"]._serialized_start = 7915
+ _globals["_AUDIOFORMAT_CHANNELS"]._serialized_end = 7947
+ _globals["_AUDIOFORMAT_DELIVERYMODE"]._serialized_start = 7949
+ _globals["_AUDIOFORMAT_DELIVERYMODE"]._serialized_end = 8005
+ _globals["_AUDIOPACKET"]._serialized_start = 8007
+ _globals["_AUDIOPACKET"]._serialized_end = 8110
+ _globals["_SMSMESSAGE"]._serialized_start = 8112
+ _globals["_SMSMESSAGE"]._serialized_end = 8158
+ _globals["_DISPLAYCONFIGURATION"]._serialized_start = 8161
+ _globals["_DISPLAYCONFIGURATION"]._serialized_end = 8492
+ _globals["_DISPLAYCONFIGURATION_DISPLAYFLAGS"]._serialized_start = 8262
+ _globals["_DISPLAYCONFIGURATION_DISPLAYFLAGS"]._serialized_end = 8492
+ _globals["_DISPLAYCONFIGURATIONS"]._serialized_start = 8495
+ _globals["_DISPLAYCONFIGURATIONS"]._serialized_end = 8632
+ _globals["_NOTIFICATION"]._serialized_start = 8635
+ _globals["_NOTIFICATION"]._serialized_end = 9174
+ _globals["_BOOTCOMPLETEDNOTIFICATION"]._serialized_start = 9176
+ _globals["_BOOTCOMPLETEDNOTIFICATION"]._serialized_end = 9217
+ _globals["_CAMERANOTIFICATION"]._serialized_start = 9219
+ _globals["_CAMERANOTIFICATION"]._serialized_end = 9272
+ _globals["_TEXTVIEWFOCUS"]._serialized_start = 9274
+ _globals["_TEXTVIEWFOCUS"]._serialized_end = 9332
+ _globals["_DISPLAYCONFIGURATIONSCHANGEDNOTIFICATION"]._serialized_start = 9334
+ _globals["_DISPLAYCONFIGURATIONSCHANGEDNOTIFICATION"]._serialized_end = 9457
+ _globals["_ROTATIONRADIAN"]._serialized_start = 9459
+ _globals["_ROTATIONRADIAN"]._serialized_end = 9508
+ _globals["_TRANSLATION"]._serialized_start = 9510
+ _globals["_TRANSLATION"]._serialized_end = 9574
+ _globals["_ANGULARVELOCITY"]._serialized_start = 9576
+ _globals["_ANGULARVELOCITY"]._serialized_end = 9644
+ _globals["_VELOCITY"]._serialized_start = 9646
+ _globals["_VELOCITY"]._serialized_end = 9689
+ _globals["_POSTURE"]._serialized_start = 9692
+ _globals["_POSTURE"]._serialized_end = 9924
+ _globals["_POSTURE_POSTUREVALUE"]._serialized_start = 9768
+ _globals["_POSTURE_POSTUREVALUE"]._serialized_end = 9924
+ _globals["_PHONENUMBER"]._serialized_start = 9926
+ _globals["_PHONENUMBER"]._serialized_end = 9955
+ _globals["_EMULATORCONTROLLER"]._serialized_start = 10028
+ _globals["_EMULATORCONTROLLER"]._serialized_end = 13906
+# @@protoc_insertion_point(module_scope)
diff --git a/libs/python/cua-sandbox/cua_sandbox/transport/_grpc_emulator/emulator_controller_pb2_grpc.py b/libs/python/cua-sandbox/cua_sandbox/transport/_grpc_emulator/emulator_controller_pb2_grpc.py
new file mode 100644
index 0000000000..a317714338
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/transport/_grpc_emulator/emulator_controller_pb2_grpc.py
@@ -0,0 +1,2568 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+
+import grpc
+from google.protobuf import empty_pb2 as google_dot_protobuf_dot_empty__pb2
+
+from . import emulator_controller_pb2 as emulator__controller__pb2
+
+GRPC_GENERATED_VERSION = "1.78.0"
+GRPC_VERSION = grpc.__version__
+_version_not_supported = False
+
+try:
+ from grpc._utilities import first_version_is_lower
+
+ _version_not_supported = first_version_is_lower(GRPC_VERSION, GRPC_GENERATED_VERSION)
+except ImportError:
+ _version_not_supported = True
+
+if _version_not_supported:
+ raise RuntimeError(
+ f"The grpc package installed is at version {GRPC_VERSION},"
+ + " but the generated code in emulator_controller_pb2_grpc.py depends on"
+ + f" grpcio>={GRPC_GENERATED_VERSION}."
+ + f" Please upgrade your grpc module to grpcio>={GRPC_GENERATED_VERSION}"
+ + f" or downgrade your generated code using grpcio-tools<={GRPC_VERSION}."
+ )
+
+
+class EmulatorControllerStub(object):
+ """An EmulatorController service lets you control the emulator.
+ Note that this is currently an experimental feature, and that the
+ service definition might change without notice. Use at your own risk!
+
+ We use the following rough conventions:
+
+ streamXXX --> streams values XXX (usually for emulator lifetime). Values
+ are updated as soon as they become available.
+ getXXX --> gets a single value XXX
+ setXXX --> sets a single value XXX, does not returning state, these
+ usually have an observable lasting side effect.
+ sendXXX --> send a single event XXX, possibly returning state information.
+ android usually responds to these events.
+ """
+
+ def __init__(self, channel):
+ """Constructor.
+
+ Args:
+ channel: A grpc.Channel.
+ """
+ self.streamSensor = channel.unary_stream(
+ "/android.emulation.control.EmulatorController/streamSensor",
+ request_serializer=emulator__controller__pb2.SensorValue.SerializeToString,
+ response_deserializer=emulator__controller__pb2.SensorValue.FromString,
+ _registered_method=True,
+ )
+ self.getSensor = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/getSensor",
+ request_serializer=emulator__controller__pb2.SensorValue.SerializeToString,
+ response_deserializer=emulator__controller__pb2.SensorValue.FromString,
+ _registered_method=True,
+ )
+ self.setSensor = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/setSensor",
+ request_serializer=emulator__controller__pb2.SensorValue.SerializeToString,
+ response_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ _registered_method=True,
+ )
+ self.setPhysicalModel = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/setPhysicalModel",
+ request_serializer=emulator__controller__pb2.PhysicalModelValue.SerializeToString,
+ response_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ _registered_method=True,
+ )
+ self.getPhysicalModel = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/getPhysicalModel",
+ request_serializer=emulator__controller__pb2.PhysicalModelValue.SerializeToString,
+ response_deserializer=emulator__controller__pb2.PhysicalModelValue.FromString,
+ _registered_method=True,
+ )
+ self.streamPhysicalModel = channel.unary_stream(
+ "/android.emulation.control.EmulatorController/streamPhysicalModel",
+ request_serializer=emulator__controller__pb2.PhysicalModelValue.SerializeToString,
+ response_deserializer=emulator__controller__pb2.PhysicalModelValue.FromString,
+ _registered_method=True,
+ )
+ self.setClipboard = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/setClipboard",
+ request_serializer=emulator__controller__pb2.ClipData.SerializeToString,
+ response_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ _registered_method=True,
+ )
+ self.getClipboard = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/getClipboard",
+ request_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ response_deserializer=emulator__controller__pb2.ClipData.FromString,
+ _registered_method=True,
+ )
+ self.streamClipboard = channel.unary_stream(
+ "/android.emulation.control.EmulatorController/streamClipboard",
+ request_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ response_deserializer=emulator__controller__pb2.ClipData.FromString,
+ _registered_method=True,
+ )
+ self.setBattery = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/setBattery",
+ request_serializer=emulator__controller__pb2.BatteryState.SerializeToString,
+ response_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ _registered_method=True,
+ )
+ self.getBattery = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/getBattery",
+ request_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ response_deserializer=emulator__controller__pb2.BatteryState.FromString,
+ _registered_method=True,
+ )
+ self.setGps = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/setGps",
+ request_serializer=emulator__controller__pb2.GpsState.SerializeToString,
+ response_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ _registered_method=True,
+ )
+ self.getGps = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/getGps",
+ request_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ response_deserializer=emulator__controller__pb2.GpsState.FromString,
+ _registered_method=True,
+ )
+ self.sendFingerprint = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/sendFingerprint",
+ request_serializer=emulator__controller__pb2.Fingerprint.SerializeToString,
+ response_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ _registered_method=True,
+ )
+ self.sendKey = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/sendKey",
+ request_serializer=emulator__controller__pb2.KeyboardEvent.SerializeToString,
+ response_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ _registered_method=True,
+ )
+ self.sendTouch = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/sendTouch",
+ request_serializer=emulator__controller__pb2.TouchEvent.SerializeToString,
+ response_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ _registered_method=True,
+ )
+ self.sendMouse = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/sendMouse",
+ request_serializer=emulator__controller__pb2.MouseEvent.SerializeToString,
+ response_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ _registered_method=True,
+ )
+ self.injectWheel = channel.stream_unary(
+ "/android.emulation.control.EmulatorController/injectWheel",
+ request_serializer=emulator__controller__pb2.WheelEvent.SerializeToString,
+ response_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ _registered_method=True,
+ )
+ self.streamInputEvent = channel.stream_unary(
+ "/android.emulation.control.EmulatorController/streamInputEvent",
+ request_serializer=emulator__controller__pb2.InputEvent.SerializeToString,
+ response_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ _registered_method=True,
+ )
+ self.sendPhone = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/sendPhone",
+ request_serializer=emulator__controller__pb2.PhoneCall.SerializeToString,
+ response_deserializer=emulator__controller__pb2.PhoneResponse.FromString,
+ _registered_method=True,
+ )
+ self.sendSms = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/sendSms",
+ request_serializer=emulator__controller__pb2.SmsMessage.SerializeToString,
+ response_deserializer=emulator__controller__pb2.PhoneResponse.FromString,
+ _registered_method=True,
+ )
+ self.setPhoneNumber = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/setPhoneNumber",
+ request_serializer=emulator__controller__pb2.PhoneNumber.SerializeToString,
+ response_deserializer=emulator__controller__pb2.PhoneResponse.FromString,
+ _registered_method=True,
+ )
+ self.getStatus = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/getStatus",
+ request_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ response_deserializer=emulator__controller__pb2.EmulatorStatus.FromString,
+ _registered_method=True,
+ )
+ self.getScreenshot = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/getScreenshot",
+ request_serializer=emulator__controller__pb2.ImageFormat.SerializeToString,
+ response_deserializer=emulator__controller__pb2.Image.FromString,
+ _registered_method=True,
+ )
+ self.streamScreenshot = channel.unary_stream(
+ "/android.emulation.control.EmulatorController/streamScreenshot",
+ request_serializer=emulator__controller__pb2.ImageFormat.SerializeToString,
+ response_deserializer=emulator__controller__pb2.Image.FromString,
+ _registered_method=True,
+ )
+ self.streamAudio = channel.unary_stream(
+ "/android.emulation.control.EmulatorController/streamAudio",
+ request_serializer=emulator__controller__pb2.AudioFormat.SerializeToString,
+ response_deserializer=emulator__controller__pb2.AudioPacket.FromString,
+ _registered_method=True,
+ )
+ self.injectAudio = channel.stream_unary(
+ "/android.emulation.control.EmulatorController/injectAudio",
+ request_serializer=emulator__controller__pb2.AudioPacket.SerializeToString,
+ response_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ _registered_method=True,
+ )
+ self.getLogcat = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/getLogcat",
+ request_serializer=emulator__controller__pb2.LogMessage.SerializeToString,
+ response_deserializer=emulator__controller__pb2.LogMessage.FromString,
+ _registered_method=True,
+ )
+ self.streamLogcat = channel.unary_stream(
+ "/android.emulation.control.EmulatorController/streamLogcat",
+ request_serializer=emulator__controller__pb2.LogMessage.SerializeToString,
+ response_deserializer=emulator__controller__pb2.LogMessage.FromString,
+ _registered_method=True,
+ )
+ self.setVmState = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/setVmState",
+ request_serializer=emulator__controller__pb2.VmRunState.SerializeToString,
+ response_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ _registered_method=True,
+ )
+ self.getVmState = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/getVmState",
+ request_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ response_deserializer=emulator__controller__pb2.VmRunState.FromString,
+ _registered_method=True,
+ )
+ self.setDisplayConfigurations = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/setDisplayConfigurations",
+ request_serializer=emulator__controller__pb2.DisplayConfigurations.SerializeToString,
+ response_deserializer=emulator__controller__pb2.DisplayConfigurations.FromString,
+ _registered_method=True,
+ )
+ self.getDisplayConfigurations = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/getDisplayConfigurations",
+ request_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ response_deserializer=emulator__controller__pb2.DisplayConfigurations.FromString,
+ _registered_method=True,
+ )
+ self.streamNotification = channel.unary_stream(
+ "/android.emulation.control.EmulatorController/streamNotification",
+ request_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ response_deserializer=emulator__controller__pb2.Notification.FromString,
+ _registered_method=True,
+ )
+ self.rotateVirtualSceneCamera = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/rotateVirtualSceneCamera",
+ request_serializer=emulator__controller__pb2.RotationRadian.SerializeToString,
+ response_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ _registered_method=True,
+ )
+ self.setVirtualSceneCameraVelocity = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/setVirtualSceneCameraVelocity",
+ request_serializer=emulator__controller__pb2.Velocity.SerializeToString,
+ response_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ _registered_method=True,
+ )
+ self.setPosture = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/setPosture",
+ request_serializer=emulator__controller__pb2.Posture.SerializeToString,
+ response_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ _registered_method=True,
+ )
+ self.getBrightness = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/getBrightness",
+ request_serializer=emulator__controller__pb2.BrightnessValue.SerializeToString,
+ response_deserializer=emulator__controller__pb2.BrightnessValue.FromString,
+ _registered_method=True,
+ )
+ self.setBrightness = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/setBrightness",
+ request_serializer=emulator__controller__pb2.BrightnessValue.SerializeToString,
+ response_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ _registered_method=True,
+ )
+ self.getDisplayMode = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/getDisplayMode",
+ request_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ response_deserializer=emulator__controller__pb2.DisplayMode.FromString,
+ _registered_method=True,
+ )
+ self.setDisplayMode = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/setDisplayMode",
+ request_serializer=emulator__controller__pb2.DisplayMode.SerializeToString,
+ response_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ _registered_method=True,
+ )
+ self.setXrOptions = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/setXrOptions",
+ request_serializer=emulator__controller__pb2.XrOptions.SerializeToString,
+ response_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ _registered_method=True,
+ )
+ self.getXrOptions = channel.unary_unary(
+ "/android.emulation.control.EmulatorController/getXrOptions",
+ request_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ response_deserializer=emulator__controller__pb2.XrOptions.FromString,
+ _registered_method=True,
+ )
+
+
+class EmulatorControllerServicer(object):
+ """An EmulatorController service lets you control the emulator.
+ Note that this is currently an experimental feature, and that the
+ service definition might change without notice. Use at your own risk!
+
+ We use the following rough conventions:
+
+ streamXXX --> streams values XXX (usually for emulator lifetime). Values
+ are updated as soon as they become available.
+ getXXX --> gets a single value XXX
+ setXXX --> sets a single value XXX, does not returning state, these
+ usually have an observable lasting side effect.
+ sendXXX --> send a single event XXX, possibly returning state information.
+ android usually responds to these events.
+ """
+
+ def streamSensor(self, request, context):
+ """set/get/stream the sensor data
+ This RPC is not implemented in EmulatorController and will return an unimplemented error.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def getSensor(self, request, context):
+ """Gets the current value of a specified sensor.
+
+ The following gRPC error codes can be returned:
+ - INTERNAL (code 13) if `getSensorSize` fails to retrieve sensor dimensions.
+
+ The `status` field in the `SensorValue` reply indicates the operational state:
+ - `OK` (0): Sensor data retrieved successfully.
+ - `UNKNOWN` (2): Unknown sensor type (should not happen if using valid `SensorType`).
+ - `DISABLED` (3): The sensor is disabled.
+ - `NO_SERVICE` (4): The `qemud` service responsible for sensors is not available or initiated.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def setSensor(self, request, context):
+ """Sets the override value for a specified sensor. This operation is asynchronous
+ and executed on the emulator's main looper. An immediate subsequent `getSensor`
+ call might not reflect the newly set value.
+
+ This method returns `OK` (code 0) upon successful asynchronous scheduling of the operation.
+ No specific gRPC error codes are returned by this method itself, but underlying
+ operations might log warnings if the sensor agent is unavailable.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def setPhysicalModel(self, request, context):
+ """set/get/stream the physical model, this is likely the one you are
+ looking for when you wish to modify the device state.
+
+ This operation is asynchronous and executed on the emulator's main looper. An immediate subsequent `getPhysicalModel`
+ call might not reflect the newly set value. The `interpolation` field from the request is used to determine the
+ physical interpolation method, mapped using `abs((static_cast<int>(physicalValue.interpolation())) - 1)`.
+
+ This method returns `OK` (code 0) upon successful asynchronous scheduling of the operation.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def getPhysicalModel(self, request, context):
+ """Gets the current value of a specified physical model parameter.
+
+ The `status` field in the `PhysicalModelValue` reply indicates the operational state:
+ - `OK` (0): Physical model data retrieved successfully.
+ - `UNKNOWN` (2): Unknown physical type (should not happen if using valid `PhysicalType`).
+ - `NO_SERVICE` (3): The `qemud` service responsible for physical parameters is not available or initiated.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def streamPhysicalModel(self, request, context):
+ """This RPC is not implemented in EmulatorController and will return an unimplemented error."""
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def setClipboard(self, request, context):
+ """Atomically sets the current primary clipboard data. This operation is asynchronous
+ and executed on the emulator's main looper. It triggers a `ClipboardEvent`
+ to all listeners (except the originating channel) indicating the new content.
+
+ This method returns `OK` (code 0) upon successful asynchronous scheduling of the operation.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def getClipboard(self, request, context):
+ """Retrieves the current primary clipboard data. This is a synchronous operation.
+
+ This method returns `OK` (code 0) and the current `ClipData` upon success.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def streamClipboard(self, request, context):
+ """Streams real-time updates of the clipboard content. Upon subscription,
+ it immediately sends the current clipboard state. Subsequent updates are
+ streamed as new content becomes available from the guest or is set via `setClipboard`
+ from a different client. Events originating from the same client that initiated
+ the stream are filtered out to prevent echoing.
+
+ It is possible to miss very rapid clipboard updates. The stream will block
+ awaiting new events after the initial state is sent.
+
+ This method returns a server-side streaming reactor.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def setBattery(self, request, context):
+ """Sets the emulator's battery state to the provided values. This operation is
+ executed asynchronously on the main looper.
+
+ This method returns `OK` (code 0) upon successful asynchronous scheduling
+ of the operation. No explicit gRPC error codes are returned by this method.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def getBattery(self, request, context):
+ """Retrieves the current battery state from the emulator. This is a
+ synchronous operation that waits for completion.
+
+ This method returns `OK` (code 0) and populates the `BatteryState` reply
+ with the current information upon success. No explicit gRPC error codes
+ are returned by this method.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def setGps(self, request, context):
+ """Sets the state of the GPS in the emulator. This operation is asynchronous
+ and executed on the main looper. It updates the emulator's GPS location
+ (latitude, longitude, altitude, speed, bearing, and satellites) and sets
+ the timestamp.
+
+ Note: Setting the GPS position will not be immediately reflected in the user
+ interface. Android typically samples GPS at 1 Hz.
+ This method returns `OK` (code 0) upon successful asynchronous scheduling
+ of the operation.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def getGps(self, request, context):
+ """Gets the latest GPS state as reported by the emulator. This includes data
+ delivered by previous `setGps` calls or from the location UI if active.
+ This is a synchronous operation that waits for completion.
+
+ Note: The returned GPS state is not necessarily the exact coordinate
+ visible at the time due to Android's typical 1 Hz GPS sample frequency.
+
+ This method returns `OK` (code 0) and populates the `GpsState` reply
+ with the retrieved information upon success. No explicit gRPC error codes
+ are returned by this method.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def sendFingerprint(self, request, context):
+ """Simulates a touch event on the fingerprint sensor. This operation is
+ executed asynchronously on the main looper.
+
+ The `isTouching` field indicates whether the fingerprint sensor is being
+ touched, and `touchId` specifies the identifier of the registered
+ fingerprint. The `setTouch` agent function is used to apply these values.
+
+ This method returns `OK` (code 0) upon successful asynchronous scheduling
+ of the operation. No explicit gRPC error codes are returned by this method.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def sendKey(self, request, context):
+ """Sends a keyboard event to the emulator. This operation is asynchronous
+ and executed on the main looper.
+
+ The `KeyboardEvent` message allows specifying input using `keyCode`, `key` (W3C standard string), or `text` (UTF-8 string).
+ The `KeyEventSender` prioritizes `key`, then `keyCode`, then `text`.
+ - If `key` is a non-printable W3C key string (e.g., "Backspace", "ArrowUp"), it's translated to an evdev keycode and sent.
+ - If `key` is a printable Unicode character, it's converted to a sequence of evdev keydown/keyup events, handling modifiers.
+ - If `keyCode` is provided, it's translated from its `codeType` (Usb, Evdev, XKB, Win, Mac) to an evdev keycode and sent as keydown/keyup pairs.
+ - If `text` is provided, each UTF-8 character is converted to evdev keypress (keydown then keyup) events.
+
+ This method returns `OK` (code 0) upon successful asynchronous scheduling of the operation.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def sendTouch(self, request, context):
+ """Sends touch events to the emulator. This operation is asynchronous and executed on the main looper.
+
+ The `TouchEvent` contains a list of `Touch` objects, each with `x`, `y` coordinates, `identifier`, `pressure`, `touch_major`, `touch_minor`, `expiration`, and `orientation`.
+ Coordinates are scaled to the emulator's display resolution. Each `Touch` `identifier` is mapped to an internal Linux multitouch slot.
+ Expiration handling ensures that inactive touch events are properly "lifted" after 120 seconds.
+
+ This method returns `OK` (code 0) upon successful asynchronous scheduling of the operation. Warnings are logged if no touch slots are available.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def sendMouse(self, request, context):
+ """Sends mouse events to the emulator. This operation is asynchronous and executed on the main looper.
+
+ The `MouseEvent` specifies `x`, `y` coordinates, `buttons` state (bitmask: 1 for left, 2 for right), and `display` ID.
+ In certain virtual input configurations (VirtioInput enabled, but VirtioMouse and VirtioTablet disabled), `buttons` may be masked to only consider the primary button.
+ The event is sent to the emulator's `user_event_agent`.
+
+ This method returns `OK` (code 0) upon successful asynchronous scheduling of the operation.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def injectWheel(self, request_iterator, context):
+ """Injects a stream of wheel events into the emulator. This is a server-side streaming RPC.
+
+ Each `WheelEvent` contains `dx`, `dy` (delta values, `dy` is pre-multiplied by 120 for scroll clicks), and `display` ID.
+ If the emulator's input device has rotary capabilities (e.g., AVD_WEAR flavor), `dy` is scaled and sent as a rotary event.
+ Otherwise, it's sent as a standard mouse wheel event.
+
+ This method returns a server-side streaming reactor.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def streamInputEvent(self, request_iterator, context):
+ """Streams a series of generic input events to the emulator. The events are processed in the order they arrive.
+ This is a server-side streaming RPC that supports various input types encapsulated within `InputEvent`'s `oneof type` field.
+
+ Supported input types:
+ - `key_event` (KeyboardEvent): Processed by `KeyEventSender` as described in `sendKey`.
+ - `touch_event` (TouchEvent): Processed by `TouchEventSender` as described in `sendTouch`.
+ - `mouse_event` (MouseEvent): Processed by `MouseEventSender` as described in `sendMouse`.
+ - `android_event` (AndroidEvent): Raw Linux input events (`type`, `code`, `value`) sent directly to the kernel.
+ - `pen_event` (PenEvent): Processed by `PenEventSender` for pen input, including pressure, orientation, and button state.
+ - `wheel_event` (WheelEvent): Processed by `WheelEventSender` as described in `injectWheel`.
+ - `xr_command` (XrCommand): Executes XR-specific commands (e.g., `RECENTER` to recenter the viewport). Unknown actions are logged as warnings.
+ - `xr_head_rotation_event` (RotationRadian): Sends head rotation data in radians. Logs an error if the agent call fails.
+ - `xr_head_movement_event` (Translation): Sends head movement data in meters. Logs an error if the agent call fails.
+ - `xr_head_angular_velocity_event` (AngularVelocity): Sends head angular velocity data in radians per second. Logs an error if the agent call fails.
+ - `xr_head_velocity_event` (Velocity): Sends head velocity data in meters per second. Logs an error if the agent call fails.
+ - `touchpad_event` (TouchpadEvent): Processed by `TouchpadEventSender` for touchpad input, similar to touch events but for a touchpad device.
+
+ All underlying input sending operations for XR events are executed asynchronously on the main looper.
+
+ Returns `INVALID_ARGUMENT` (code 3) if an unrecognized input event type is received, indicating a potential out-of-date emulator.
+ The stream reactor automatically deletes itself upon completion.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def sendPhone(self, request, context):
+ """Initiates or manipulates a phone call in the emulator. This is a synchronous
+ operation executed on the main looper.
+
+ The `PhoneCall` message specifies the `operation` (e.g., InitCall, AcceptCall)
+ and the target phone `number`. The `telephonyCmd` agent function handles the
+ actual call action.
+
+ Returns a `PhoneResponse` indicating the outcome:
+ - `OK` (0): The operation was successful.
+ - `BadOperation` (1): The provided `operation` enum is out of range.
+ - `BadNumber` (2): The provided `number` is malformed.
+ - `InvalidAction` (3): The requested `operation` is invalid given the current call state (e.g., disconnecting when no call is active).
+ - `ActionFailed` (4): An internal error occurred, typically if the modem agent is unavailable.
+ - `RadioOff` (5): The emulator's radio is turned off.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def sendSms(self, request, context):
+ """Sends an SMS message to the emulator. This is a synchronous operation.
+
+ The `SmsMessage` contains the `srcAddress` (source phone number) and the `text` of the message.
+ The `srcAddress` is validated for GSM formatting. The message `text` is converted into SMS PDUs
+ (Protocol Data Units) and delivered via the modem agent.
+
+ Returns a `PhoneResponse` indicating the outcome:
+ - `OK` (0): The SMS message was successfully delivered.
+ - `BadNumber` (2): The `srcAddress` is malformed.
+ - `ActionFailed` (4): An internal error occurred, e.g., if the modem agent is unavailable or PDU creation fails.
+
+ Other error cases from PDU creation (e.g., invalid characters in text) also result in `ActionFailed`.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def setPhoneNumber(self, request, context):
+ """Sets the emulator's phone number. This is a synchronous operation.
+
+ The `PhoneNumber` message contains the new `number` to be set. The modem agent's
+ `amodem_update_phone_number` function is used for this update.
+
+ Returns a `PhoneResponse` indicating the outcome:
+ - `OK` (0): The phone number was successfully updated.
+ - `BadNumber` (2): The provided `number` is invalid for the modem.
+ - `ActionFailed` (4): An internal error occurred, typically if the modem agent is unavailable.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def getStatus(self, request, context):
+ """Retrieves the current status of the emulator. This includes comprehensive
+ information about the virtual machine's configuration and the guest operating system's state.
+
+ The `EmulatorStatus` reply contains:
+ - `version`: The emulator version string.
+ - `uptime`: The time the emulator has been active in milliseconds.
+ - `booted`: A boolean indicating if the device has completed booting.
+ - `vmConfig`: Detailed `VmConfiguration` (hypervisor type, CPU cores, RAM size).
+ - `hardwareConfig`: Key-value pairs describing the emulator's hardware configuration.
+ - `heartbeat`: A monotonically increasing number indicating guest activity (incremented approximately once per second).
+ - `guestConfig`: A map of key-value pairs with guest-specific configurations, including:
+ - "multidisplay": "available" or "unavailable" based on display pipe readiness.
+ - "androidVersion": The Android version of the guest OS.
+ - "hypervisorVersion": The hypervisor version used by the guest.
+
+ This method returns `OK` (code 0) upon successful retrieval of the emulator status.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def getScreenshot(self, request, context):
+ """Retrieves a single screenshot in the desired format.
+
+ The image will be scaled to the `desiredWidth` and `desiredHeight` specified in `ImageFormat`, while maintaining
+ the aspect ratio. If `width` or `height` are 0, the device's current display dimensions are used.
+ The returned image will never exceed the device's actual display resolution, but can be smaller.
+
+ The `display` field in `ImageFormat` specifies the target display; 0 (or omitted) indicates the main display.
+ For folded Pixel Fold devices, the display ID might be internally remapped, and `foldedDisplay` information will be populated.
+ The resulting image is properly oriented based on the device's coarse-grained orientation, derived from sensor state.
+
+ The `transport` field in `ImageFormat` can specify `MMAP` for shared memory delivery, but if the shared memory region
+ is too small, a `FAILED_PRECONDITION` error will be returned.
+
+ This method returns:
+ - `OK` (code 0) and an `Image` object upon success.
+ - `INVALID_ARGUMENT` (code 3) if the specified `display` ID is invalid or disabled.
+ - `CANCELLED` (code 1) if the gRPC context is cancelled during the operation (an expensive operation).
+ - `FAILED_PRECONDITION` (code 9) if the guest has not posted a new frame yet (for non-PNG formats when fast path is used).
+
+ This method will return an image with width 0 and height 0 if the display is not visible.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def streamScreenshot(self, request, context):
+ """Streams a series of screenshots in the desired format. This is a server-side streaming RPC.
+
+ A new frame is delivered whenever the device produces a new frame or when sensor changes occur.
+ Initial state: The first frame delivered might be an empty image (width 0, height 0) if the display is inactive.
+ Subsequent frames are delivered when new content is available or a sensor event triggers an update.
+ If the display becomes inactive, an empty image will be delivered again. Images resume when the display becomes active.
+
+ `ImageFormat` parameters (format, width, height, display) behave as described in `getScreenshot`.
+ The `transport` field in `ImageFormat` can specify `MMAP` for shared memory delivery. If `MMAP` is used and the
+ provided shared memory handle is valid and mapped, pixel data will be written directly to it.
+ The `image` field in the `Image` reply will be empty if `MMAP` transport is used.
+
+ Performance considerations:
+ - Streaming can produce a significant amount of data.
+ - `PNG` format is CPU-intensive due to encoding overhead.
+ - Using `MMAP` transport can significantly reduce gRPC overhead for pixel data.
+
+ This method returns:
+ - A server-side streaming reactor.
+ - `INVALID_ARGUMENT` (code 3) if the specified `display` ID is invalid or disabled.
+ - `CANCELLED` (code 1) if the gRPC context is cancelled during the operation.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def streamAudio(self, request, context):
+ """Streams a series of audio packets in the desired format. This is a server-side streaming RPC.
+ A new frame is delivered approximately every 20-30ms when the emulated device produces audio.
+ If `samplingRate` is 0, it defaults to 44100 Hz.
+ The stream may block indefinitely if the emulator ceases to produce audio.
+ Packets are allocated with a buffer size calculated based on the audio format and a 30ms frame time.
+
+ This method returns `OK` (code 0) upon successful streaming initiation.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def injectAudio(self, request_iterator, context):
+ """Injects a series of audio packets into the Android microphone. This is a client-side streaming RPC.
+ Audio packets are processed at a rate determined by the emulator's request for frames.
+ An internal buffer can hold approximately 300ms of audio.
+
+ Notes:
+ - Only the `AudioFormat` from the first received packet is honored. Subsequent `AudioFormat` changes are ignored.
+ - `MODE_REAL_TIME` is experimental: incoming data may overwrite existing data if the client does not control timing properly.
+ - The circular buffer attempts to deliver all queued samples upon stream closure by writing silence for up to 300ms.
+
+ Returns the following gRPC error codes:
+ - `FAILED_PRECONDITION` (code 9): If another microphone is already active, or if unable to register the microphone.
+ - `INVALID_ARGUMENT` (code 3): If the desired `samplingRate` exceeds 48kHz, or if an `AudioPacket` is too large for the internal buffer.
+
+ This method returns `OK` (code 0) upon successful completion of the stream.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def getLogcat(self, request, context):
+ """Deprecated, please use the streamLogcat method instead."""
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def streamLogcat(self, request, context):
+ """Streams the logcat output from the emulator in real-time. This is a server-side streaming RPC.
+ The stream sources its data from the `logcat` command executed via `AdbShellStream` in the Android guest.
+ Log lines are processed individually as they arrive.
+
+ The `LogMessage.sort` field determines the output format:
+ - If `LogMessage.sort` is `Parsed`, each incoming log line is parsed into a structured `LogcatEntry` object,
+ and these entries are returned in the `LogMessage.entries` field. Structured parsing is typically
+ available for Android API Level 23 (Marshmallow) and later.
+ - If `LogMessage.sort` is `Text` (or unspecified), the raw log line is returned in the `LogMessage.contents` field.
+
+ The stream continues as long as the underlying `logcat` process is running and the client is connected.
+ The stream will naturally terminate if the `logcat` process stops or the connection is lost.
+ No explicit gRPC error codes are returned by this method during active streaming.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def setVmState(self, request, context):
+ """Transitions the virtual machine to the desired state. This operation is asynchronous
+ and executed on the QEMU looper to handle necessary IO locks. Note that some states
+ (e.g., `UNKNOWN`, `RESTORE_VM`, `SAVE_VM`, `INTERNAL_ERROR`) are purely observable
+ and cannot be set directly.
+
+ The `VmRunState.state` field triggers specific VM operations:
+ - `RESET`: Calls `vmReset()` to reset the VM.
+ - `SHUTDOWN`: Calls `skin_winsys_quit_request()` for a graceful shutdown, similar to closing the emulator GUI.
+ - `TERMINATE`: Forcefully kills the emulator process. This can lead to system corruption and should be used with extreme caution.
+ - `PAUSED`: Calls `vmPause()` to pause the VM, halting CPU cycles.
+ - `RUNNING`: Calls `vmResume()` to resume the VM.
+ - `RESTART`: Calls `ui->requestRestart()` to perform a full emulator restart.
+ - `START`: Calls `vmStart()` to resume a stopped emulator.
+ - `STOP`: Calls `vmStop()` to stop (pause) a running emulator.
+
+ This method returns `OK` (code 0) upon successful asynchronous scheduling of the operation.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def getVmState(self, request, context):
+ """Retrieves the current run state of the virtual machine. This is a synchronous operation.
+
+ Internal QEMU run states are mapped to `VmRunState.RunState` as follows:
+ - `QEMU_RUN_STATE_PAUSED` and `QEMU_RUN_STATE_SUSPENDED` map to `PAUSED`.
+ - `QEMU_RUN_STATE_RESTORE_VM` maps to `RESTORE_VM`.
+ - `QEMU_RUN_STATE_RUNNING` maps to `RUNNING`.
+ - `QEMU_RUN_STATE_SAVE_VM` maps to `SAVE_VM`.
+ - `QEMU_RUN_STATE_SHUTDOWN` maps to `SHUTDOWN`.
+ - `QEMU_RUN_STATE_GUEST_PANICKED`, `QEMU_RUN_STATE_INTERNAL_ERROR`, and `QEMU_RUN_STATE_IO_ERROR` map to `INTERNAL_ERROR`.
+ - Any other states default to `UNKNOWN`.
+
+ This method returns `OK` (code 0) and populates the `VmRunState` reply with the current VM state.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def setDisplayConfigurations(self, request, context):
+ """Atomically changes the current multi-display configuration. This operation applies
+ the provided `DisplayConfigurations`, with special handling for secondary displays.
+ Display ID 0 (the primary display) cannot be modified via this RPC.
+
+ Preconditions:
+ - The `android::featurecontrol::MultiDisplay` feature must be enabled.
+
+ Input Validation:
+ - `INVALID_ARGUMENT` (code 3): If duplicate `display` IDs are found in the request.
+ - `INVALID_ARGUMENT` (code 3): If any `DisplayConfiguration` (width, height, dpi, flags)
+ is outside valid ranges as determined by `multiDisplayParamValidate`.
+ - `INVALID_ARGUMENT` (code 3): If any `display` ID is outside the configurable range
+ `[1, userConfigurable]`.
+
+ Atomic Update and Rollback:
+ The system attempts to apply each display configuration. If any update fails
+ (e.g., after multiple retries for transient pipe errors), a rollback mechanism
+ is initiated: successfully updated displays are reverted to their previous state,
+ and newly added displays are deleted. In such cases, an `INTERNAL` error is returned.
+
+ Deletion of Unrequested Displays:
+ Any displays that were active before this call but are not present in the new
+ `request.displays` (and are not display ID 0) will be deleted.
+
+ Notifications:
+ Upon successful completion, `notifyDisplayChanges()` is called to inform
+ third-party subscribers.
+
+ Returns the following gRPC error codes:
+ - `OK` (code 0): Upon successful application of all configurations, returning the final active `DisplayConfigurations`.
+ - `FAILED_PRECONDITION` (code 9): If the multi-display feature is not available.
+ - `INTERNAL` (code 13): If an internal emulator failure occurs during display modification or rollback.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def getDisplayConfigurations(self, request, context):
+ """Returns all currently valid logical displays configured in the emulator. This is a synchronous operation.
+
+ Preconditions:
+ - The `android::featurecontrol::MultiDisplay` feature must be enabled.
+
+ The `DisplayConfigurations` reply contains:
+ - `displays`: A repeated field of `DisplayConfiguration` objects, each detailing
+ the width, height, DPI, flags, and ID of an active display.
+ For Pixel Fold devices, only the main display configuration might be relevant.
+ - `userConfigurable`: The maximum number of user-configurable displays (IDs from 1 up to this value).
+ - `maxDisplays`: The total maximum number of displays the emulator supports.
+
+ This method returns:
+ - `OK` (code 0) and the current `DisplayConfigurations` upon success.
+ - `FAILED_PRECONDITION` (code 9): If the AVD does not support the multi-display feature.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def streamNotification(self, request, context):
+ """Notifies the client of various emulator state changes in real-time. This is a server-side streaming RPC.
+ Upon subscription, the current states of virtual scene camera, foldable posture, boot completion,
+ and XR options are immediately sent. The stream then continuously delivers new notifications
+ when relevant events occur. `UniqueEventStreamWriter` ensures that only distinct state changes are streamed.
+
+ Notifications include:
+ - `CameraNotification`: Reports virtual scene camera activation/deactivation and associated display.
+ - `DisplayConfigurationsChangedNotification`: Triggered when display configurations are modified via the extended UI. Does not fire for changes made through console or gRPC.
+ - `Posture`: Reports changes in the device's foldable posture.
+ - `BootCompletedNotification`: Indicates when the emulator has finished booting.
+ - `BrightnessValue`: Reports changes in backlight brightness (LCD, keyboard, or button).
+ - `TextViewFocus`: Sent when a text view gains or loses focus, or immediately on subscription.
+ - `XrOptions`: Reports changes in XR-related settings (environment, passthrough coefficient), or immediately on subscription.
+
+ This method returns a server-side streaming reactor.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def rotateVirtualSceneCamera(self, request, context):
+ """Rotates the virtual scene camera relative to its current orientation. This operation is asynchronous
+ and executed on the main looper.
+
+ The `RotationRadian` message specifies angles in radians around the x, y, and z axes. The z component of rotation is currently unused.
+ The coordinate system is right-handed: x-axis points right, y-axis points up, and z-axis points towards the viewer.
+ This operation only succeeds if the virtual scene camera is actively connected.
+
+ This method returns `OK` (code 0) upon successful asynchronous scheduling of the operation.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def setVirtualSceneCameraVelocity(self, request, context):
+ """Sets the absolute velocity of the virtual scene camera. This operation is asynchronous
+ and executed on the main looper.
+
+ The `Velocity` message specifies components in meters per second along the x, y, and z axes.
+ The coordinate system is right-handed: x-axis points right, y-axis points up, and z-axis points towards the viewer.
+ The transition to these target velocity values may be smoothed over time by the implementation.
+ This operation only succeeds if the virtual scene camera is actively connected.
+
+ This method returns `OK` (code 0) upon successful asynchronous scheduling of the operation.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def setPosture(self, request, context):
+ """Sets the foldable posture of the device. This operation is asynchronous
+ and executed on the main looper.
+
+ The `Posture` message contains a `PostureValue` enum, defining the desired
+ physical configuration of the foldable device.
+
+ Returns the following gRPC error codes:
+ - `OK` (code 0): Upon successful asynchronous scheduling of the operation.
+ - `FAILED_PRECONDITION` (code 9): If the emulator is unable to set the specified posture.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def getBrightness(self, request, context):
+ """Retrieves the current backlight brightness for a specified light type. This is a synchronous operation.
+
+ The `BrightnessValue.target` field (e.g., `LCD`, `KEYBOARD`, `BUTTON`) determines which light's brightness is queried.
+ Internal mapping converts these to string names like "lcd_backlight".
+
+ Returns the following gRPC error codes:
+ - `OK` (code 0): Upon successful retrieval, populating the `BrightnessValue` reply with the `target` and current `value`.
+ - `FAILED_PRECONDITION` (code 9): If the AVD does not support the `hw-control` agent or its `getBrightness` function is unavailable.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def setBrightness(self, request, context):
+ """Sets the backlight brightness for a specified light type. This operation is asynchronous
+ and executed on the main looper.
+
+ The `BrightnessValue.target` field (e.g., `LCD`, `KEYBOARD`, `BUTTON`) determines which light's brightness is set.
+ The `BrightnessValue.value` specifies the desired intensity, ranging from 0 to 255.
+ Internal mapping converts `LightType` to string names like "lcd_backlight".
+
+ Returns the following gRPC error codes:
+ - `OK` (code 0): Upon successful asynchronous scheduling of the operation.
+ - `FAILED_PRECONDITION` (code 9): If the AVD does not support the `hw-control` agent or its `setBrightness` function is unavailable.
+ - `INVALID_ARGUMENT` (code 3): If the `brightness` value exceeds the valid range (0-255).
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def getDisplayMode(self, request, context):
+ """Returns the current mode of the primary display of a resizable AVD. This is a synchronous operation.
+
+ Preconditions:
+ - The AVD must be configured to support resizable displays (`resizableEnabled()` must be true).
+
+ The `DisplayMode.value` field will be populated with the current `DisplayModeValue`,
+ derived from the `getResizableActiveConfigId()`.
+
+ Returns the following gRPC error codes:
+ - `OK` (code 0): Upon successful retrieval of the display mode.
+ - `FAILED_PRECONDITION` (code 9): If the AVD is not resizable.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def setDisplayMode(self, request, context):
+ """Sets the size of the primary display of a resizable AVD to the specified `DisplayModeValue`. This operation is asynchronous
+ and executed on the main looper.
+
+ Preconditions:
+ - The AVD must be configured to support resizable displays (`resizableEnabled()` must be true).
+ - The emulator's `changeResizableDisplay` agent function must be available.
+
+ The `DisplayMode.value` field specifies the desired display configuration (e.g., `PHONE`, `FOLDABLE`, `TABLET`, `DESKTOP`).
+
+ Returns the following gRPC error codes:
+ - `OK` (code 0): Upon successful asynchronous scheduling of the operation.
+ - `FAILED_PRECONDITION` (code 9): If the AVD is not resizable.
+ - `INTERNAL` (code 13): If the internal window agent function `changeResizableDisplay` is not available.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def setXrOptions(self, request, context):
+ """Changes the XR-related settings of the emulator. This operation is asynchronous
+ and executed on the main looper.
+
+ The `XrOptions` message specifies the `environment` (e.g., `LIVING_ROOM_DAY`, `LIVING_ROOM_NIGHT`)
+ and `passthrough_coefficient` (a float between 0.0 and 1.0 for real/artificial environment visibility).
+ Values for `passthrough_coefficient` outside [0.0, 1.0] are ignored.
+
+ Returns the following gRPC error codes:
+ - `OK` (code 0): Upon successful asynchronous scheduling of the operation.
+ - `FAILED_PRECONDITION` (code 9): If the `setXrOptions` agent function fails (e.g., if XR is not supported).
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+ def getXrOptions(self, request, context):
+ """Retrieves the current state of XR-related settings from the emulator. This is a synchronous operation.
+
+ Preconditions:
+ - XR mode must be supported in the current AVD (`isXrGuestOs()` must be true).
+ (Note: Current implementation of `isXrGuestOs()` always returns true).
+
+ The `XrOptions` reply contains the current `environment` and `passthrough_coefficient`.
+
+ Returns the following gRPC error codes:
+ - `OK` (code 0): Upon successful retrieval of the XR options.
+ - `FAILED_PRECONDITION` (code 9): If XR mode is not supported in the current AVD or if the `getXrOptions` agent function fails.
+ """
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+
+def add_EmulatorControllerServicer_to_server(servicer, server):
+ rpc_method_handlers = {
+ "streamSensor": grpc.unary_stream_rpc_method_handler(
+ servicer.streamSensor,
+ request_deserializer=emulator__controller__pb2.SensorValue.FromString,
+ response_serializer=emulator__controller__pb2.SensorValue.SerializeToString,
+ ),
+ "getSensor": grpc.unary_unary_rpc_method_handler(
+ servicer.getSensor,
+ request_deserializer=emulator__controller__pb2.SensorValue.FromString,
+ response_serializer=emulator__controller__pb2.SensorValue.SerializeToString,
+ ),
+ "setSensor": grpc.unary_unary_rpc_method_handler(
+ servicer.setSensor,
+ request_deserializer=emulator__controller__pb2.SensorValue.FromString,
+ response_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ ),
+ "setPhysicalModel": grpc.unary_unary_rpc_method_handler(
+ servicer.setPhysicalModel,
+ request_deserializer=emulator__controller__pb2.PhysicalModelValue.FromString,
+ response_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ ),
+ "getPhysicalModel": grpc.unary_unary_rpc_method_handler(
+ servicer.getPhysicalModel,
+ request_deserializer=emulator__controller__pb2.PhysicalModelValue.FromString,
+ response_serializer=emulator__controller__pb2.PhysicalModelValue.SerializeToString,
+ ),
+ "streamPhysicalModel": grpc.unary_stream_rpc_method_handler(
+ servicer.streamPhysicalModel,
+ request_deserializer=emulator__controller__pb2.PhysicalModelValue.FromString,
+ response_serializer=emulator__controller__pb2.PhysicalModelValue.SerializeToString,
+ ),
+ "setClipboard": grpc.unary_unary_rpc_method_handler(
+ servicer.setClipboard,
+ request_deserializer=emulator__controller__pb2.ClipData.FromString,
+ response_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ ),
+ "getClipboard": grpc.unary_unary_rpc_method_handler(
+ servicer.getClipboard,
+ request_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ response_serializer=emulator__controller__pb2.ClipData.SerializeToString,
+ ),
+ "streamClipboard": grpc.unary_stream_rpc_method_handler(
+ servicer.streamClipboard,
+ request_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ response_serializer=emulator__controller__pb2.ClipData.SerializeToString,
+ ),
+ "setBattery": grpc.unary_unary_rpc_method_handler(
+ servicer.setBattery,
+ request_deserializer=emulator__controller__pb2.BatteryState.FromString,
+ response_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ ),
+ "getBattery": grpc.unary_unary_rpc_method_handler(
+ servicer.getBattery,
+ request_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ response_serializer=emulator__controller__pb2.BatteryState.SerializeToString,
+ ),
+ "setGps": grpc.unary_unary_rpc_method_handler(
+ servicer.setGps,
+ request_deserializer=emulator__controller__pb2.GpsState.FromString,
+ response_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ ),
+ "getGps": grpc.unary_unary_rpc_method_handler(
+ servicer.getGps,
+ request_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ response_serializer=emulator__controller__pb2.GpsState.SerializeToString,
+ ),
+ "sendFingerprint": grpc.unary_unary_rpc_method_handler(
+ servicer.sendFingerprint,
+ request_deserializer=emulator__controller__pb2.Fingerprint.FromString,
+ response_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ ),
+ "sendKey": grpc.unary_unary_rpc_method_handler(
+ servicer.sendKey,
+ request_deserializer=emulator__controller__pb2.KeyboardEvent.FromString,
+ response_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ ),
+ "sendTouch": grpc.unary_unary_rpc_method_handler(
+ servicer.sendTouch,
+ request_deserializer=emulator__controller__pb2.TouchEvent.FromString,
+ response_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ ),
+ "sendMouse": grpc.unary_unary_rpc_method_handler(
+ servicer.sendMouse,
+ request_deserializer=emulator__controller__pb2.MouseEvent.FromString,
+ response_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ ),
+ "injectWheel": grpc.stream_unary_rpc_method_handler(
+ servicer.injectWheel,
+ request_deserializer=emulator__controller__pb2.WheelEvent.FromString,
+ response_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ ),
+ "streamInputEvent": grpc.stream_unary_rpc_method_handler(
+ servicer.streamInputEvent,
+ request_deserializer=emulator__controller__pb2.InputEvent.FromString,
+ response_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ ),
+ "sendPhone": grpc.unary_unary_rpc_method_handler(
+ servicer.sendPhone,
+ request_deserializer=emulator__controller__pb2.PhoneCall.FromString,
+ response_serializer=emulator__controller__pb2.PhoneResponse.SerializeToString,
+ ),
+ "sendSms": grpc.unary_unary_rpc_method_handler(
+ servicer.sendSms,
+ request_deserializer=emulator__controller__pb2.SmsMessage.FromString,
+ response_serializer=emulator__controller__pb2.PhoneResponse.SerializeToString,
+ ),
+ "setPhoneNumber": grpc.unary_unary_rpc_method_handler(
+ servicer.setPhoneNumber,
+ request_deserializer=emulator__controller__pb2.PhoneNumber.FromString,
+ response_serializer=emulator__controller__pb2.PhoneResponse.SerializeToString,
+ ),
+ "getStatus": grpc.unary_unary_rpc_method_handler(
+ servicer.getStatus,
+ request_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ response_serializer=emulator__controller__pb2.EmulatorStatus.SerializeToString,
+ ),
+ "getScreenshot": grpc.unary_unary_rpc_method_handler(
+ servicer.getScreenshot,
+ request_deserializer=emulator__controller__pb2.ImageFormat.FromString,
+ response_serializer=emulator__controller__pb2.Image.SerializeToString,
+ ),
+ "streamScreenshot": grpc.unary_stream_rpc_method_handler(
+ servicer.streamScreenshot,
+ request_deserializer=emulator__controller__pb2.ImageFormat.FromString,
+ response_serializer=emulator__controller__pb2.Image.SerializeToString,
+ ),
+ "streamAudio": grpc.unary_stream_rpc_method_handler(
+ servicer.streamAudio,
+ request_deserializer=emulator__controller__pb2.AudioFormat.FromString,
+ response_serializer=emulator__controller__pb2.AudioPacket.SerializeToString,
+ ),
+ "injectAudio": grpc.stream_unary_rpc_method_handler(
+ servicer.injectAudio,
+ request_deserializer=emulator__controller__pb2.AudioPacket.FromString,
+ response_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ ),
+ "getLogcat": grpc.unary_unary_rpc_method_handler(
+ servicer.getLogcat,
+ request_deserializer=emulator__controller__pb2.LogMessage.FromString,
+ response_serializer=emulator__controller__pb2.LogMessage.SerializeToString,
+ ),
+ "streamLogcat": grpc.unary_stream_rpc_method_handler(
+ servicer.streamLogcat,
+ request_deserializer=emulator__controller__pb2.LogMessage.FromString,
+ response_serializer=emulator__controller__pb2.LogMessage.SerializeToString,
+ ),
+ "setVmState": grpc.unary_unary_rpc_method_handler(
+ servicer.setVmState,
+ request_deserializer=emulator__controller__pb2.VmRunState.FromString,
+ response_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ ),
+ "getVmState": grpc.unary_unary_rpc_method_handler(
+ servicer.getVmState,
+ request_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ response_serializer=emulator__controller__pb2.VmRunState.SerializeToString,
+ ),
+ "setDisplayConfigurations": grpc.unary_unary_rpc_method_handler(
+ servicer.setDisplayConfigurations,
+ request_deserializer=emulator__controller__pb2.DisplayConfigurations.FromString,
+ response_serializer=emulator__controller__pb2.DisplayConfigurations.SerializeToString,
+ ),
+ "getDisplayConfigurations": grpc.unary_unary_rpc_method_handler(
+ servicer.getDisplayConfigurations,
+ request_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ response_serializer=emulator__controller__pb2.DisplayConfigurations.SerializeToString,
+ ),
+ "streamNotification": grpc.unary_stream_rpc_method_handler(
+ servicer.streamNotification,
+ request_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ response_serializer=emulator__controller__pb2.Notification.SerializeToString,
+ ),
+ "rotateVirtualSceneCamera": grpc.unary_unary_rpc_method_handler(
+ servicer.rotateVirtualSceneCamera,
+ request_deserializer=emulator__controller__pb2.RotationRadian.FromString,
+ response_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ ),
+ "setVirtualSceneCameraVelocity": grpc.unary_unary_rpc_method_handler(
+ servicer.setVirtualSceneCameraVelocity,
+ request_deserializer=emulator__controller__pb2.Velocity.FromString,
+ response_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ ),
+ "setPosture": grpc.unary_unary_rpc_method_handler(
+ servicer.setPosture,
+ request_deserializer=emulator__controller__pb2.Posture.FromString,
+ response_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ ),
+ "getBrightness": grpc.unary_unary_rpc_method_handler(
+ servicer.getBrightness,
+ request_deserializer=emulator__controller__pb2.BrightnessValue.FromString,
+ response_serializer=emulator__controller__pb2.BrightnessValue.SerializeToString,
+ ),
+ "setBrightness": grpc.unary_unary_rpc_method_handler(
+ servicer.setBrightness,
+ request_deserializer=emulator__controller__pb2.BrightnessValue.FromString,
+ response_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ ),
+ "getDisplayMode": grpc.unary_unary_rpc_method_handler(
+ servicer.getDisplayMode,
+ request_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ response_serializer=emulator__controller__pb2.DisplayMode.SerializeToString,
+ ),
+ "setDisplayMode": grpc.unary_unary_rpc_method_handler(
+ servicer.setDisplayMode,
+ request_deserializer=emulator__controller__pb2.DisplayMode.FromString,
+ response_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ ),
+ "setXrOptions": grpc.unary_unary_rpc_method_handler(
+ servicer.setXrOptions,
+ request_deserializer=emulator__controller__pb2.XrOptions.FromString,
+ response_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ ),
+ "getXrOptions": grpc.unary_unary_rpc_method_handler(
+ servicer.getXrOptions,
+ request_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ response_serializer=emulator__controller__pb2.XrOptions.SerializeToString,
+ ),
+ }
+ generic_handler = grpc.method_handlers_generic_handler(
+ "android.emulation.control.EmulatorController", rpc_method_handlers
+ )
+ server.add_generic_rpc_handlers((generic_handler,))
+ server.add_registered_method_handlers(
+ "android.emulation.control.EmulatorController", rpc_method_handlers
+ )
+
+
+# This class is part of an EXPERIMENTAL API.
+class EmulatorController(object):
+ """An EmulatorController service lets you control the emulator.
+ Note that this is currently an experimental feature, and that the
+ service definition might change without notice. Use at your own risk!
+
+ We use the following rough conventions:
+
+ streamXXX --> streams values XXX (usually for emulator lifetime). Values
+ are updated as soon as they become available.
+ getXXX --> gets a single value XXX
+ setXXX --> sets a single value XXX, does not returning state, these
+ usually have an observable lasting side effect.
+ sendXXX --> send a single event XXX, possibly returning state information.
+ android usually responds to these events.
+ """
+
+ @staticmethod
+ def streamSensor(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_stream(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/streamSensor",
+ emulator__controller__pb2.SensorValue.SerializeToString,
+ emulator__controller__pb2.SensorValue.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def getSensor(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/getSensor",
+ emulator__controller__pb2.SensorValue.SerializeToString,
+ emulator__controller__pb2.SensorValue.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def setSensor(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/setSensor",
+ emulator__controller__pb2.SensorValue.SerializeToString,
+ google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def setPhysicalModel(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/setPhysicalModel",
+ emulator__controller__pb2.PhysicalModelValue.SerializeToString,
+ google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def getPhysicalModel(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/getPhysicalModel",
+ emulator__controller__pb2.PhysicalModelValue.SerializeToString,
+ emulator__controller__pb2.PhysicalModelValue.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def streamPhysicalModel(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_stream(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/streamPhysicalModel",
+ emulator__controller__pb2.PhysicalModelValue.SerializeToString,
+ emulator__controller__pb2.PhysicalModelValue.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def setClipboard(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/setClipboard",
+ emulator__controller__pb2.ClipData.SerializeToString,
+ google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def getClipboard(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/getClipboard",
+ google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ emulator__controller__pb2.ClipData.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def streamClipboard(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_stream(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/streamClipboard",
+ google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ emulator__controller__pb2.ClipData.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def setBattery(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/setBattery",
+ emulator__controller__pb2.BatteryState.SerializeToString,
+ google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def getBattery(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/getBattery",
+ google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ emulator__controller__pb2.BatteryState.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def setGps(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/setGps",
+ emulator__controller__pb2.GpsState.SerializeToString,
+ google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def getGps(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/getGps",
+ google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ emulator__controller__pb2.GpsState.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def sendFingerprint(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/sendFingerprint",
+ emulator__controller__pb2.Fingerprint.SerializeToString,
+ google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def sendKey(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/sendKey",
+ emulator__controller__pb2.KeyboardEvent.SerializeToString,
+ google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def sendTouch(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/sendTouch",
+ emulator__controller__pb2.TouchEvent.SerializeToString,
+ google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def sendMouse(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/sendMouse",
+ emulator__controller__pb2.MouseEvent.SerializeToString,
+ google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def injectWheel(
+ request_iterator,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.stream_unary(
+ request_iterator,
+ target,
+ "/android.emulation.control.EmulatorController/injectWheel",
+ emulator__controller__pb2.WheelEvent.SerializeToString,
+ google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def streamInputEvent(
+ request_iterator,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.stream_unary(
+ request_iterator,
+ target,
+ "/android.emulation.control.EmulatorController/streamInputEvent",
+ emulator__controller__pb2.InputEvent.SerializeToString,
+ google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def sendPhone(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/sendPhone",
+ emulator__controller__pb2.PhoneCall.SerializeToString,
+ emulator__controller__pb2.PhoneResponse.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def sendSms(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/sendSms",
+ emulator__controller__pb2.SmsMessage.SerializeToString,
+ emulator__controller__pb2.PhoneResponse.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def setPhoneNumber(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/setPhoneNumber",
+ emulator__controller__pb2.PhoneNumber.SerializeToString,
+ emulator__controller__pb2.PhoneResponse.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def getStatus(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/getStatus",
+ google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ emulator__controller__pb2.EmulatorStatus.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def getScreenshot(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/getScreenshot",
+ emulator__controller__pb2.ImageFormat.SerializeToString,
+ emulator__controller__pb2.Image.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def streamScreenshot(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_stream(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/streamScreenshot",
+ emulator__controller__pb2.ImageFormat.SerializeToString,
+ emulator__controller__pb2.Image.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def streamAudio(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_stream(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/streamAudio",
+ emulator__controller__pb2.AudioFormat.SerializeToString,
+ emulator__controller__pb2.AudioPacket.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def injectAudio(
+ request_iterator,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.stream_unary(
+ request_iterator,
+ target,
+ "/android.emulation.control.EmulatorController/injectAudio",
+ emulator__controller__pb2.AudioPacket.SerializeToString,
+ google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def getLogcat(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/getLogcat",
+ emulator__controller__pb2.LogMessage.SerializeToString,
+ emulator__controller__pb2.LogMessage.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def streamLogcat(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_stream(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/streamLogcat",
+ emulator__controller__pb2.LogMessage.SerializeToString,
+ emulator__controller__pb2.LogMessage.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def setVmState(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/setVmState",
+ emulator__controller__pb2.VmRunState.SerializeToString,
+ google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def getVmState(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/getVmState",
+ google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ emulator__controller__pb2.VmRunState.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def setDisplayConfigurations(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/setDisplayConfigurations",
+ emulator__controller__pb2.DisplayConfigurations.SerializeToString,
+ emulator__controller__pb2.DisplayConfigurations.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def getDisplayConfigurations(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/getDisplayConfigurations",
+ google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ emulator__controller__pb2.DisplayConfigurations.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def streamNotification(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_stream(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/streamNotification",
+ google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ emulator__controller__pb2.Notification.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def rotateVirtualSceneCamera(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/rotateVirtualSceneCamera",
+ emulator__controller__pb2.RotationRadian.SerializeToString,
+ google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def setVirtualSceneCameraVelocity(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/setVirtualSceneCameraVelocity",
+ emulator__controller__pb2.Velocity.SerializeToString,
+ google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def setPosture(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/setPosture",
+ emulator__controller__pb2.Posture.SerializeToString,
+ google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def getBrightness(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/getBrightness",
+ emulator__controller__pb2.BrightnessValue.SerializeToString,
+ emulator__controller__pb2.BrightnessValue.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def setBrightness(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/setBrightness",
+ emulator__controller__pb2.BrightnessValue.SerializeToString,
+ google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def getDisplayMode(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/getDisplayMode",
+ google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ emulator__controller__pb2.DisplayMode.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def setDisplayMode(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/setDisplayMode",
+ emulator__controller__pb2.DisplayMode.SerializeToString,
+ google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def setXrOptions(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/setXrOptions",
+ emulator__controller__pb2.XrOptions.SerializeToString,
+ google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
+
+ @staticmethod
+ def getXrOptions(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/android.emulation.control.EmulatorController/getXrOptions",
+ google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+ emulator__controller__pb2.XrOptions.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
diff --git a/libs/python/cua-sandbox/cua_sandbox/transport/adb.py b/libs/python/cua-sandbox/cua_sandbox/transport/adb.py
new file mode 100644
index 0000000000..cd838e7edc
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/transport/adb.py
@@ -0,0 +1,229 @@
+"""ADBTransport — communicates with Android emulator via ADB.
+
+Screenshots via `adb exec-out screencap -p`, shell via `adb shell`,
+screen size via `adb shell wm size`.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Dict, Optional
+
+if TYPE_CHECKING:
+ from cua_sandbox.interfaces.tunnel import TunnelInfo
+
+from cua_sandbox.transport.base import Transport
+
+
+class ADBTransport(Transport):
+ """Transport backed by ADB (Android Debug Bridge)."""
+
+ def __init__(self, serial: str = "emulator-5554", sdk_root: Optional[str] = None):
+ self._serial = serial
+ self._sdk_root = sdk_root
+ self._adb: Optional[str] = None
+
+ def _find_adb(self) -> str:
+ if self._sdk_root:
+ candidate = Path(self._sdk_root) / "platform-tools" / "adb"
+ if candidate.exists():
+ return str(candidate)
+ found = shutil.which("adb")
+ if found:
+ return found
+ raise FileNotFoundError("adb not found. Install the Android SDK or set ANDROID_HOME.")
+
+ async def connect(self) -> None:
+ self._adb = self._find_adb()
+ env = self._env()
+ subprocess.run([self._adb, "start-server"], capture_output=True, env=env)
+
+ async def disconnect(self) -> None:
+ pass
+
+ def _env(self) -> dict:
+ env = os.environ.copy()
+ if self._sdk_root:
+ env["ANDROID_SDK_ROOT"] = self._sdk_root
+ return env
+
+ def _adb_cmd(self, *args: str, timeout: float = 15) -> subprocess.CompletedProcess:
+ assert self._adb is not None, "Transport not connected"
+ return subprocess.run(
+ [self._adb, "-s", self._serial, *args],
+ capture_output=True,
+ env=self._env(),
+ timeout=timeout,
+ )
+
+ async def _adb_cmd_async(self, *args: str, timeout: float = 15) -> subprocess.CompletedProcess:
+ """Run _adb_cmd in a thread executor so the event loop stays responsive."""
+ import asyncio
+ import functools
+
+ loop = asyncio.get_event_loop()
+ return await loop.run_in_executor(
+ None, functools.partial(self._adb_cmd, *args, timeout=timeout)
+ )
+
+ async def send(self, action: str, **params: Any) -> Any:
+ if action in ("shell", "execute", "run_command"):
+ cmd = params.get("command", "")
+ result = await self._adb_cmd_async("shell", cmd)
+ return {
+ "stdout": result.stdout.decode(errors="replace"),
+ "stderr": result.stderr.decode(errors="replace"),
+ "returncode": result.returncode,
+ }
+ if action == "multitouch_gesture":
+ return self._multitouch_gesture(**params)
+ raise ValueError(f"Unknown action: {action}")
+
+ def _multitouch_gesture(
+ self,
+ fingers: list,
+ screen_w: int,
+ screen_h: int,
+ duration_ms: int = 400,
+ steps: int = 0,
+ ) -> Any:
+ """Inject multi-touch via MT Protocol B sendevent (local ADB).
+
+ Calls ``adb root`` to restart adbd as root so plain ``sendevent``
+ works without ``su`` inside the Android shell.
+ """
+ import re
+ import time
+
+ # Restart adbd as root
+ self._adb_cmd("root", timeout=10)
+ time.sleep(1.0) # wait for adbd to restart
+
+ # Find touch device
+ dev_result = self._adb_cmd(
+ "shell",
+ "for f in /dev/input/event*; do "
+ " getevent -p \"$f\" 2>/dev/null | grep -q '0035' "
+ ' && echo "$f" && break; '
+ "done",
+ )
+ dev = dev_result.stdout.decode(errors="replace").strip() or "/dev/input/event1"
+
+ # Detect axis max
+ axis_max = 32767
+ gp_result = self._adb_cmd("shell", f"getevent -p {dev} 2>/dev/null | grep '0035'")
+ gp_out = gp_result.stdout.decode(errors="replace")
+ m = re.search(r"max\s+(\d+)", gp_out)
+ if m:
+ axis_max = int(m.group(1))
+
+ n_steps = steps if steps > 0 else max(5, duration_ms // 20)
+ step_delay = (duration_ms / 1000) / n_steps
+
+ EV_SYN, EV_KEY, EV_ABS = 0, 1, 3
+ SYN_REPORT, BTN_TOUCH = 0, 330
+ SLOT, TID, MTX, MTY, PRESS = 47, 57, 53, 54, 58
+ TID_NONE = 4294967295
+
+ def px_to_raw(px: int, dim: int) -> int:
+ return max(0, min(axis_max, int(px * axis_max / dim)))
+
+ def se(t: int, c: int, v: int) -> str:
+ return f"sendevent {dev} {t} {c} {v}"
+
+ cmds: list[str] = []
+ for idx, finger in enumerate(fingers):
+ x1, y1 = finger["start"]
+ cmds += [
+ se(EV_ABS, SLOT, idx),
+ se(EV_ABS, TID, idx),
+ se(EV_ABS, MTX, px_to_raw(x1, screen_w)),
+ se(EV_ABS, MTY, px_to_raw(y1, screen_h)),
+ se(EV_ABS, PRESS, 64),
+ ]
+ cmds += [se(EV_KEY, BTN_TOUCH, 1), se(EV_SYN, SYN_REPORT, 0)]
+
+ for i in range(1, n_steps + 1):
+ t = i / n_steps
+ for idx, finger in enumerate(fingers):
+ x1, y1 = finger["start"]
+ x2, y2 = finger["end"]
+ cmds += [
+ se(EV_ABS, SLOT, idx),
+ se(EV_ABS, MTX, px_to_raw(int(x1 + (x2 - x1) * t), screen_w)),
+ se(EV_ABS, MTY, px_to_raw(int(y1 + (y2 - y1) * t), screen_h)),
+ ]
+ cmds += [se(EV_SYN, SYN_REPORT, 0), f"sleep {step_delay:.3f}"]
+
+ for idx in range(len(fingers)):
+ cmds += [se(EV_ABS, SLOT, idx), se(EV_ABS, TID, TID_NONE)]
+ cmds += [se(EV_KEY, BTN_TOUCH, 0), se(EV_SYN, SYN_REPORT, 0)]
+
+ result = self._adb_cmd("shell", " && ".join(cmds), timeout=60)
+ return {
+ "stdout": result.stdout.decode(errors="replace"),
+ "returncode": result.returncode,
+ }
+
+ async def screenshot(self, format: str = "png", quality: int = 95) -> bytes:
+ assert self._adb is not None, "Transport not connected"
+ # exec-out screencap -p returns PNG; PNG compresses on the emulator side
+ # so less data is transferred over ADB than raw RGBA.
+ result = await self._adb_cmd_async("exec-out", "screencap", "-p", timeout=15)
+ if not (result.returncode == 0 and result.stdout[:4] == b"\x89PNG"):
+ raise RuntimeError(f"ADB screenshot failed: {result.stderr.decode(errors='replace')}")
+
+ if format.lower() in ("jpeg", "jpg"):
+ from io import BytesIO
+
+ from PIL import Image as PILImage
+
+ img = PILImage.open(BytesIO(result.stdout)).convert("RGB")
+ buf = BytesIO()
+ img.save(buf, format="JPEG", quality=quality, optimize=True)
+ return buf.getvalue()
+
+ return result.stdout
+
+ async def get_screen_size(self) -> Dict[str, int]:
+ result = await self._adb_cmd_async("shell", "wm", "size")
+ # Output: "Physical size: 1080x1920"
+ output = result.stdout.decode().strip()
+ for line in output.splitlines():
+ if "size" in line.lower():
+ parts = line.split(":")[-1].strip()
+ w, h = parts.split("x")
+ return {"width": int(w), "height": int(h)}
+ raise RuntimeError(f"Could not parse screen size: {output}")
+
+ async def get_environment(self) -> str:
+ return "android"
+
+ # ── Tunnel ────────────────────────────────────────────────────────────────
+
+ async def forward_tunnel(self, sandbox_port: int | str) -> "TunnelInfo":
+ """Forward a sandbox TCP port or abstract socket to a free host port.
+
+ - ``int`` → ``adb forward tcp:0 tcp:<sandbox_port>``
+ - ``str`` → ``adb forward tcp:0 localabstract:<sandbox_port>``
+ (e.g. ``"chrome_devtools_remote"`` for Chrome DevTools)
+ """
+ from cua_sandbox.interfaces.tunnel import TunnelInfo
+
+ target = (
+ f"localabstract:{sandbox_port}"
+ if isinstance(sandbox_port, str)
+ else f"tcp:{sandbox_port}"
+ )
+ result = await self._adb_cmd_async("forward", "tcp:0", target)
+ if result.returncode != 0:
+ raise RuntimeError(f"adb forward failed: {result.stderr.decode(errors='replace')}")
+ host_port = int(result.stdout.decode().strip())
+ return TunnelInfo(host="localhost", port=host_port, sandbox_port=sandbox_port)
+
+ async def close_tunnel(self, info: "TunnelInfo") -> None:
+ """Remove the adb forward rule for *info.sandbox_port*."""
+ await self._adb_cmd_async("forward", "--remove", f"tcp:{info.port}")
diff --git a/libs/python/cua-sandbox/cua_sandbox/transport/base.py b/libs/python/cua-sandbox/cua_sandbox/transport/base.py
new file mode 100644
index 0000000000..86e87736f7
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/transport/base.py
@@ -0,0 +1,95 @@
+"""Abstract transport protocol.
+
+A Transport moves commands and data between the sandbox client and the
+underlying computer (local host, WebSocket to computer-server, or cloud API).
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any, Dict
+
+if TYPE_CHECKING:
+ from cua_sandbox.interfaces.tunnel import TunnelInfo
+
+
+def convert_screenshot(png_bytes: bytes, format: str, quality: int) -> bytes:
+ """Convert raw PNG bytes to the requested format.
+
+ Args:
+ png_bytes: Raw PNG image bytes.
+ format: "png", "jpeg", or "jpg".
+ quality: JPEG quality (1-95), ignored for PNG.
+ """
+ fmt = format.lower()
+ if fmt in ("jpeg", "jpg"):
+ from io import BytesIO
+
+ from PIL import Image as PILImage
+
+ img = PILImage.open(BytesIO(png_bytes)).convert("RGB")
+ buf = BytesIO()
+ img.save(buf, format="JPEG", quality=quality)
+ return buf.getvalue()
+ return png_bytes
+
+
+class Transport(ABC):
+ """Base class for all transports."""
+
+ @abstractmethod
+ async def connect(self) -> None:
+ """Establish the transport connection."""
+
+ @abstractmethod
+ async def disconnect(self) -> None:
+ """Tear down the transport connection."""
+
+ @abstractmethod
+ async def send(self, action: str, **params: Any) -> Any:
+ """Send a command and return the result."""
+
+ @abstractmethod
+ async def screenshot(self, format: str = "png", quality: int = 95) -> bytes:
+ """Capture a screenshot and return raw image bytes.
+
+ Args:
+ format: "png" (lossless, default) or "jpeg" (lossy, ~5-10x smaller).
+ quality: JPEG quality 1-95, ignored for PNG.
+ """
+
+ @abstractmethod
+ async def get_screen_size(self) -> Dict[str, int]:
+ """Return {"width": ..., "height": ...}."""
+
+ @abstractmethod
+ async def get_environment(self) -> str:
+ """Return 'windows', 'mac', 'linux', or 'browser'."""
+
+ async def forward_tunnel(self, sandbox_port: int | str) -> "TunnelInfo":
+ """Forward *sandbox_port* to an available host port and return info.
+
+ Subclasses that support tunnelling must override this method.
+ The returned :class:`~cua_sandbox.interfaces.tunnel.TunnelInfo` must
+ have ``host`` and ``port`` set to the host-side address.
+ """
+ raise NotImplementedError(
+ f"{type(self).__name__} does not support port forwarding. "
+ "Supported transports: ADBTransport, GRPCEmulatorTransport, SSHTransport."
+ )
+
+ async def close_tunnel(self, info: "TunnelInfo") -> None:
+ """Release a previously forwarded port or socket. No-op by default."""
+
+ async def get_display_url(self, *, share: bool = False) -> str:
+ """Return a URL to view this sandbox's display.
+
+ Args:
+ share: If True, return a public link with embedded credentials
+ (cloud only). If False, return a direct connection URL
+ (localhost VNC for local runtimes; auth-gated URL for cloud).
+
+ Raises NotImplementedError for transports that don't expose a display
+ (e.g. HTTP, ADB).
+ """
+ raise NotImplementedError(f"{type(self).__name__} does not support get_display_url().")
diff --git a/libs/python/cua-sandbox/cua_sandbox/transport/cloud.py b/libs/python/cua-sandbox/cua_sandbox/transport/cloud.py
new file mode 100644
index 0000000000..3e1f6c2bd5
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/transport/cloud.py
@@ -0,0 +1,402 @@
+"""CloudTransport — connects to a CUA cloud VM via the platform API.
+
+Resolves VM connection info from the API, optionally creates a new VM,
+then delegates all computer control to an inner HTTPTransport pointed at
+the VM's computer-server endpoint.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any, Dict, Optional
+
+import httpx
+from cua_sandbox._config import get_api_key, get_base_url
+from cua_sandbox.transport.base import Transport
+from cua_sandbox.transport.http import HTTPTransport
+
+logger = logging.getLogger(__name__)
+
+_POLL_INTERVAL = 2.0 # seconds between status polls
+_POLL_TIMEOUT = 600.0 # max seconds to wait for VM to be running
+
+
+class CloudTransport(Transport):
+ """Transport that provisions / connects to a CUA cloud VM."""
+
+ _DEFAULT_CPU = 1
+ _DEFAULT_MEMORY_MB = 4096
+ _DEFAULT_DISK_GB = 64
+
+ def __init__(
+ self,
+ name: Optional[str] = None,
+ *,
+ api_key: Optional[str] = None,
+ base_url: Optional[str] = None,
+ # Creation params (used only when creating a new VM)
+ image: Optional[Any] = None,
+ cpu: Optional[int] = None,
+ memory_mb: Optional[int] = None,
+ disk_gb: Optional[int] = None,
+ region: str = "us-east-1",
+ ):
+ self._name = name
+ self._api_key_override = api_key
+ self._base_url = base_url or get_base_url()
+ self._image = image
+ self._cpu = cpu
+ self._memory_mb = memory_mb
+ self._disk_gb = disk_gb
+ self._region = region
+ self._inner: Optional[HTTPTransport] = None
+ self._api_client: Optional[httpx.AsyncClient] = None
+
+ # ── Connection lifecycle ────────────────────────────────────────────
+
+ async def connect(self) -> None:
+ api_key = get_api_key(self._api_key_override)
+ if not api_key:
+ raise ValueError(
+ "No CUA API key found. Cloud sandboxes are the default — to use one, provide an API key via:\n"
+ " 1. cua.configure(api_key='sk-...')\n"
+ " 2. Set the CUA_API_KEY environment variable\n"
+ " 3. Run cua.login() to authenticate via browser\n"
+ " 4. Pass api_key='sk-...' directly to sandbox()\n"
+ "\n"
+ "For local-only usage (no cloud), use sandbox(local=True) instead."
+ )
+
+ self._api_client = httpx.AsyncClient(
+ base_url=self._base_url,
+ headers={"Authorization": f"Bearer {api_key}"},
+ timeout=30.0,
+ )
+
+ if self._name:
+ logger.debug("[cloud] getting VM info for %r", self._name)
+ vm_info = await self._get_vm(self._name)
+ logger.debug("[cloud] VM info: status=%r", vm_info.get("status"))
+ else:
+ logger.debug("[cloud] creating new VM")
+ vm_info = await self._create_vm()
+ self._name = vm_info["name"]
+ logger.debug("[cloud] created VM %r", self._name)
+
+ # Poll until running
+ logger.debug(
+ "[cloud] waiting for VM %r to be running (status=%r)", self._name, vm_info.get("status")
+ )
+ 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
+ cs_url = self._resolve_endpoint(vm_info)
+ 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")
+ await self._inner.connect()
+ logger.debug("[cloud] HTTPTransport connected")
+
+ # Wait for computer-server to be reachable (it may lag behind VM "running" status)
+ logger.debug("[cloud] waiting for computer-server to be ready")
+ 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:
+ logger.debug("[cloud] applying image layers")
+ await self._apply_image_layers()
+
+ async def disconnect(self) -> None:
+ if self._inner:
+ await self._inner.disconnect()
+ self._inner = None
+ if self._api_client:
+ await self._api_client.aclose()
+ self._api_client = None
+
+ async def delete_vm(self) -> None:
+ """Delete the cloud VM via the platform API."""
+ api_key = get_api_key(self._api_key_override)
+ if not api_key or not self._name:
+ return
+ async with httpx.AsyncClient(
+ base_url=self._base_url,
+ headers={"Authorization": f"Bearer {api_key}"},
+ timeout=30.0,
+ ) as client:
+ await client.delete(f"/v1/vms/{self._name}")
+
+ async def suspend_vm(self) -> None:
+ """Stop (suspend) the cloud VM."""
+ if not self._name:
+ return
+ assert self._api_client
+ await self._api_client.post(f"/v1/vms/{self._name}/stop")
+
+ async def resume_vm(self) -> None:
+ """Start (resume) the cloud VM."""
+ if not self._name:
+ return
+ assert self._api_client
+ await self._api_client.post(f"/v1/vms/{self._name}/run")
+
+ async def restart_vm(self) -> None:
+ """Restart the cloud VM."""
+ if not self._name:
+ return
+ assert self._api_client
+ await self._api_client.post(f"/v1/vms/{self._name}/restart")
+
+ # ── Delegated methods ───────────────────────────────────────────────
+
+ async def send(self, action: str, **params: Any) -> Any:
+ assert self._inner, "Transport not connected"
+ return await self._inner.send(action, **params)
+
+ async def screenshot(self, format: str = "png", quality: int = 95) -> bytes:
+ assert self._inner, "Transport not connected"
+ return await self._inner.screenshot(format=format, quality=quality)
+
+ async def get_screen_size(self) -> Dict[str, int]:
+ assert self._inner, "Transport not connected"
+ return await self._inner.get_screen_size()
+
+ async def get_environment(self) -> str:
+ assert self._inner, "Transport not connected"
+ return await self._inner.get_environment()
+
+ async def get_display_url(self, *, share: bool = False) -> str:
+ 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}"
+ vm_info = await self._get_vm(self._name)
+ password = vm_info.get("password", "")
+ for ep in vm_info.get("endpoints", []):
+ if ep.get("name") == "vnc":
+ host = ep["host"]
+ url = f"https://{host}"
+ if password:
+ url += f"/?password={password}"
+ return url
+ raise ValueError(
+ f"VM '{self._name}' has no VNC endpoint. "
+ "Only Android and desktop VMs expose a VNC endpoint."
+ )
+
+ # ── Helpers ─────────────────────────────────────────────────────────
+
+ @property
+ def name(self) -> Optional[str]:
+ return self._name
+
+ async def _get_vm(self, name: str) -> dict:
+ assert self._api_client
+ resp = await self._api_client.get(f"/v1/vms/{name}")
+ resp.raise_for_status()
+ return resp.json()
+
+ async def _create_vm(self) -> dict:
+ assert self._api_client
+ if not self._image:
+ raise ValueError(
+ "Cannot create a cloud VM without an image. Use:\n"
+ " 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')"
+ )
+ os_type = getattr(self._image, "os_type", None)
+ if not os_type:
+ raise ValueError(
+ "Image must have an os_type. Use Image.linux(), Image.windows(), or Image.macos()."
+ )
+ body: Dict[str, Any] = {
+ "os": os_type,
+ "region": self._region,
+ }
+ # If any resource spec is provided, send explicit specs (defaulting missing to small).
+ # Otherwise, send configuration="small" for backwards compat with legacy API.
+ if any(v is not None for v in (self._cpu, self._memory_mb, self._disk_gb)):
+ body["cpu"] = self._cpu or self._DEFAULT_CPU
+ body["memoryMb"] = self._memory_mb or self._DEFAULT_MEMORY_MB
+ body["diskGb"] = self._disk_gb or self._DEFAULT_DISK_GB
+ else:
+ body["configuration"] = "small"
+ resp = await self._api_client.post("/v1/vms", json=body)
+ resp.raise_for_status()
+ return resp.json()
+
+ async def _wait_for_running(self, vm_info: dict) -> dict:
+ """Poll until the VM status is 'running' (or 'ready')."""
+ elapsed = 0.0
+ while vm_info.get("status") not in ("running", "ready"):
+ if elapsed >= _POLL_TIMEOUT:
+ raise TimeoutError(
+ f"VM {self._name!r} did not become running within {_POLL_TIMEOUT}s "
+ f"(last status: {vm_info.get('status')})"
+ )
+ await asyncio.sleep(_POLL_INTERVAL)
+ elapsed += _POLL_INTERVAL
+ vm_info = await self._get_vm(self._name) # type: ignore[arg-type]
+ logger.debug(
+ "[cloud] _wait_for_running: elapsed=%.0fs status=%r", elapsed, vm_info.get("status")
+ )
+ return vm_info
+
+ async def _wait_for_server_ready(self) -> None:
+ """Poll the computer-server until it responds (retries on connection/HTTP errors)."""
+ assert self._inner
+ elapsed = 0.0
+ last_err: Optional[Exception] = None
+ while elapsed < _POLL_TIMEOUT:
+ try:
+ await self._inner.get_screen_size()
+ return # Server is ready
+ except httpx.HTTPStatusError as e:
+ if e.response.status_code < 500:
+ raise # 4xx errors are not transient — fail fast
+ last_err = e
+ logger.debug("[cloud] _wait_for_server_ready: elapsed=%.0fs err=%r", elapsed, e)
+ await asyncio.sleep(_POLL_INTERVAL)
+ elapsed += _POLL_INTERVAL
+ except Exception as e:
+ last_err = e
+ logger.debug("[cloud] _wait_for_server_ready: elapsed=%.0fs err=%r", elapsed, e)
+ await asyncio.sleep(_POLL_INTERVAL)
+ elapsed += _POLL_INTERVAL
+ raise TimeoutError(
+ f"Computer-server for VM {self._name!r} not reachable within {_POLL_TIMEOUT}s: {last_err}"
+ )
+
+ async def _apply_image_layers(self) -> None:
+ """Apply image layers (APK installs, shell commands) after the VM is ready."""
+ import base64
+ import hashlib
+ import urllib.request
+ from pathlib import Path
+
+ assert self._inner
+ 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,
+ )
+ elif lt == "run":
+ await self._inner.send("run_command", command=layer["command"], timeout=60)
+
+ @staticmethod
+ def _resolve_endpoint(vm_info: dict) -> str:
+ """Build the computer-server HTTP URL from VM info."""
+ # Prefer explicit endpoints array (Incus VMs)
+ for ep in vm_info.get("endpoints", []):
+ if ep.get("name") in ("computer-server", "api"):
+ host = ep["host"]
+ # cua.sh hosts are behind a reverse proxy — don't append port
+ if host.endswith(".cua.sh"):
+ return f"https://{host}"
+ return f"http://{host}:{ep['port']}"
+
+ # Fallback: legacy host-based URL
+ host = vm_info.get("host")
+ if not host:
+ raise ValueError(f"Cannot resolve computer-server endpoint from VM info: {vm_info}")
+ return f"http://{host}:8000"
+
+
+async def cloud_list_vms(
+ *, api_key: Optional[str] = None, base_url: Optional[str] = None
+) -> list[dict]:
+ """List all cloud VMs. Returns raw VM dicts from the API."""
+ from cua_sandbox._config import get_api_key, get_base_url
+
+ key = get_api_key(api_key)
+ if not key:
+ raise ValueError("No CUA API key. Set CUA_API_KEY or run cua.login().")
+ url = base_url or get_base_url()
+ async with httpx.AsyncClient(
+ base_url=url,
+ headers={"Authorization": f"Bearer {key}"},
+ timeout=30.0,
+ ) as client:
+ resp = await client.get("/v1/vms")
+ resp.raise_for_status()
+ data = resp.json()
+ return data if isinstance(data, list) else data.get("vms", [])
+
+
+async def cloud_get_vm(
+ name: str, *, api_key: Optional[str] = None, base_url: Optional[str] = None
+) -> dict:
+ """Get info for a single cloud VM by name."""
+ from cua_sandbox._config import get_api_key, get_base_url
+
+ key = get_api_key(api_key)
+ if not key:
+ raise ValueError("No CUA API key. Set CUA_API_KEY or run cua.login().")
+ url = base_url or get_base_url()
+ async with httpx.AsyncClient(
+ base_url=url,
+ headers={"Authorization": f"Bearer {key}"},
+ timeout=30.0,
+ ) as client:
+ resp = await client.get(f"/v1/vms/{name}")
+ resp.raise_for_status()
+ return resp.json()
+
+
+async def cloud_vm_action(
+ name: str,
+ action: str,
+ *,
+ api_key: Optional[str] = None,
+ base_url: Optional[str] = None,
+) -> None:
+ """POST /v1/vms/{name}/{action}. action is 'stop', 'run', 'restart', or 'delete'."""
+ from cua_sandbox._config import get_api_key, get_base_url
+
+ key = get_api_key(api_key)
+ if not key:
+ raise ValueError("No CUA API key. Set CUA_API_KEY or run cua.login().")
+ url = base_url or get_base_url()
+ async with httpx.AsyncClient(
+ base_url=url,
+ headers={"Authorization": f"Bearer {key}"},
+ timeout=30.0,
+ ) as client:
+ if action == "delete":
+ await client.delete(f"/v1/vms/{name}")
+ else:
+ await client.post(f"/v1/vms/{name}/{action}")
diff --git a/libs/python/cua-sandbox/cua_sandbox/transport/grpc_emulator.py b/libs/python/cua-sandbox/cua_sandbox/transport/grpc_emulator.py
new file mode 100644
index 0000000000..6a50c293fd
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/transport/grpc_emulator.py
@@ -0,0 +1,285 @@
+"""GRPCEmulatorTransport — screenshots and input via the Android emulator's gRPC service.
+
+The emulator exposes an EmulatorController gRPC service on console_port+3000
+(default 8554 for an emulator on console port 5554). This bypasses ADB entirely,
+reducing screenshot latency from ~500ms to ~20ms.
+
+Launch the emulator with -grpc <port> or rely on the default console_port+3000.
+
+Uses the synchronous grpc channel (not grpc.aio) so the stub is safe to call
+from any event loop via run_in_executor — avoids the "Future attached to a
+different loop" error that grpc.aio channels produce in pytest session fixtures.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import shutil
+import subprocess
+from io import BytesIO
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+import grpc
+
+# google.protobuf must be imported before the emulator pb2 stubs — do not reorder.
+from google.protobuf import empty_pb2 # noqa: F401 isort: skip
+
+# isort: split
+from cua_sandbox.transport._grpc_emulator import emulator_controller_pb2 as pb2
+from cua_sandbox.transport._grpc_emulator import (
+ emulator_controller_pb2_grpc as pb2_grpc,
+)
+from cua_sandbox.transport.base import Transport
+
+if TYPE_CHECKING:
+ from cua_sandbox.interfaces.tunnel import TunnelInfo
+
+
+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)
+ found = shutil.which("adb")
+ if found:
+ return found
+ raise FileNotFoundError("adb not found. Install the Android SDK or set ANDROID_HOME.")
+
+
+class GRPCEmulatorTransport(Transport):
+ """Transport backed by the Android emulator's gRPC EmulatorController service.
+
+ Uses a synchronous gRPC channel so it is safe across multiple event loops
+ (e.g. pytest session fixtures). All blocking RPC calls are offloaded to a
+ thread executor.
+ """
+
+ def __init__(
+ self,
+ host: str = "localhost",
+ grpc_port: int = 8554,
+ serial: str = "emulator-5554",
+ sdk_root: Optional[str] = None,
+ ):
+ self._host = host
+ self._grpc_port = grpc_port
+ self._serial = serial
+ self._sdk_root = sdk_root
+ self._adb: Optional[str] = None
+ self._channel: Optional[grpc.Channel] = None
+ self._stub: Optional[pb2_grpc.EmulatorControllerStub] = None
+
+ # ── Lifecycle ─────────────────────────────────────────────────────────────
+
+ async def connect(self) -> None:
+ self._adb = _find_adb(self._sdk_root)
+ self._channel = grpc.insecure_channel(
+ f"{self._host}:{self._grpc_port}",
+ options=[
+ ("grpc.max_receive_message_length", 32 * 1024 * 1024),
+ ("grpc.max_send_message_length", 32 * 1024 * 1024),
+ ],
+ )
+ self._stub = pb2_grpc.EmulatorControllerStub(self._channel)
+
+ async def disconnect(self) -> None:
+ if self._channel:
+ self._channel.close()
+ self._channel = None
+ self._stub = None
+
+ # ── Helpers ───────────────────────────────────────────────────────────────
+
+ async def _rpc(self, fn, *args, **kwargs):
+ """Run a synchronous gRPC call in the thread executor."""
+ loop = asyncio.get_event_loop()
+ return await loop.run_in_executor(None, functools.partial(fn, *args, **kwargs))
+
+ async def _send_touch(self, event: pb2.TouchEvent) -> None:
+ await self._rpc(self._stub.sendTouch, event)
+
+ # ── Transport interface ───────────────────────────────────────────────────
+
+ async def screenshot(self, format: str = "png", quality: int = 95) -> bytes:
+ assert self._stub is not None, "Transport not connected"
+ fmt = format.lower()
+
+ if fmt in ("jpeg", "jpg"):
+ img_fmt = pb2.ImageFormat(format=pb2.ImageFormat.RGB888)
+ response = await self._rpc(self._stub.getScreenshot, img_fmt)
+ w, h = response.format.width, response.format.height
+ from PIL import Image as PILImage
+
+ img = PILImage.frombytes("RGB", (w, h), bytes(response.image))
+ buf = BytesIO()
+ img.save(buf, format="JPEG", quality=quality, optimize=True)
+ return buf.getvalue()
+
+ img_fmt = pb2.ImageFormat(format=pb2.ImageFormat.PNG)
+ response = await self._rpc(self._stub.getScreenshot, img_fmt)
+ return bytes(response.image)
+
+ async def get_screen_size(self) -> Dict[str, int]:
+ assert self._stub is not None, "Transport not connected"
+ img_fmt = pb2.ImageFormat(format=pb2.ImageFormat.PNG)
+ response = await self._rpc(self._stub.getScreenshot, img_fmt)
+ return {"width": response.format.width, "height": response.format.height}
+
+ async def get_environment(self) -> str:
+ return "android"
+
+ async def send(self, action: str, **params: Any) -> Any:
+ assert self._stub is not None, "Transport not connected"
+
+ if action in ("left_click", "right_click", "double_click"):
+ x, y = int(params["x"]), int(params["y"])
+ n_taps = 2 if action == "double_click" else 1
+ for _ in range(n_taps):
+ await self._send_touch(
+ pb2.TouchEvent(touches=[pb2.Touch(x=x, y=y, identifier=0, pressure=1)])
+ )
+ await self._send_touch(
+ pb2.TouchEvent(touches=[pb2.Touch(x=x, y=y, identifier=0, pressure=0)])
+ )
+ return {}
+
+ if action == "mouse_down":
+ x, y = int(params["x"]), int(params["y"])
+ await self._send_touch(
+ pb2.TouchEvent(touches=[pb2.Touch(x=x, y=y, identifier=0, pressure=1)])
+ )
+ return {}
+
+ if action == "mouse_up":
+ x, y = int(params["x"]), int(params["y"])
+ await self._send_touch(
+ pb2.TouchEvent(touches=[pb2.Touch(x=x, y=y, identifier=0, pressure=0)])
+ )
+ return {}
+
+ if action == "move_cursor":
+ return {}
+
+ if action in ("shell", "execute", "run_command"):
+ assert self._adb is not None, "Transport not connected"
+ cmd = params.get("command", "")
+ timeout = float(params.get("timeout", 15))
+ loop = asyncio.get_event_loop()
+ result = await loop.run_in_executor(
+ None,
+ functools.partial(
+ subprocess.run,
+ [self._adb, "-s", self._serial, "shell", cmd],
+ capture_output=True,
+ timeout=timeout,
+ check=False,
+ ),
+ )
+ return {
+ "stdout": result.stdout.decode(errors="replace"),
+ "stderr": result.stderr.decode(errors="replace"),
+ "returncode": result.returncode,
+ }
+
+ if action == "multitouch_gesture":
+ # Send all fingers simultaneously per frame via sendTouch.
+ fingers: List[Dict] = params["fingers"]
+ steps: int = max(1, int(params.get("steps", 10)))
+ duration_ms: float = float(params.get("duration_ms", 400))
+ delay = (duration_ms / 1000.0) / steps
+
+ # Press all fingers simultaneously
+ await self._send_touch(
+ pb2.TouchEvent(
+ touches=[
+ pb2.Touch(
+ x=int(f["start"][0]),
+ y=int(f["start"][1]),
+ identifier=i,
+ pressure=1,
+ )
+ for i, f in enumerate(fingers)
+ ]
+ )
+ )
+
+ # Interpolate movement frames
+ for step in range(1, steps + 1):
+ t = step / steps
+ await self._send_touch(
+ pb2.TouchEvent(
+ touches=[
+ pb2.Touch(
+ x=int(f["start"][0] + t * (f["end"][0] - f["start"][0])),
+ y=int(f["start"][1] + t * (f["end"][1] - f["start"][1])),
+ identifier=i,
+ pressure=1,
+ )
+ for i, f in enumerate(fingers)
+ ]
+ )
+ )
+ await asyncio.sleep(delay)
+
+ # Release all fingers simultaneously
+ await self._send_touch(
+ pb2.TouchEvent(
+ touches=[
+ pb2.Touch(
+ x=int(f["end"][0]),
+ y=int(f["end"][1]),
+ identifier=i,
+ pressure=0,
+ )
+ for i, f in enumerate(fingers)
+ ]
+ )
+ )
+ return {}
+
+ raise NotImplementedError(f"GRPCEmulatorTransport.send({action!r}) not implemented")
+
+ # ── Tunnel ────────────────────────────────────────────────────────────────
+
+ async def forward_tunnel(self, sandbox_port: int | str) -> "TunnelInfo":
+ """Forward a sandbox TCP port or abstract socket to a free host port.
+
+ - ``int`` → ``adb forward tcp:0 tcp:<sandbox_port>``
+ - ``str`` → ``adb forward tcp:0 localabstract:<sandbox_port>``
+ (e.g. ``"chrome_devtools_remote"`` for Chrome DevTools)
+ """
+ from cua_sandbox.interfaces.tunnel import TunnelInfo
+
+ target = (
+ f"localabstract:{sandbox_port}"
+ if isinstance(sandbox_port, str)
+ else f"tcp:{sandbox_port}"
+ )
+ loop = asyncio.get_event_loop()
+ result = await loop.run_in_executor(
+ None,
+ functools.partial(
+ subprocess.run,
+ [self._adb, "-s", self._serial, "forward", "tcp:0", target],
+ capture_output=True,
+ check=False,
+ ),
+ )
+ if result.returncode != 0:
+ raise RuntimeError(f"adb forward failed: {result.stderr.decode(errors='replace')}")
+ host_port = int(result.stdout.decode().strip())
+ return TunnelInfo(host="localhost", port=host_port, sandbox_port=sandbox_port)
+
+ async def close_tunnel(self, info: "TunnelInfo") -> None:
+ loop = asyncio.get_event_loop()
+ await loop.run_in_executor(
+ None,
+ functools.partial(
+ subprocess.run,
+ [self._adb, "-s", self._serial, "forward", "--remove", f"tcp:{info.port}"],
+ capture_output=True,
+ check=False,
+ ),
+ )
diff --git a/libs/python/cua-sandbox/cua_sandbox/transport/http.py b/libs/python/cua-sandbox/cua_sandbox/transport/http.py
new file mode 100644
index 0000000000..5a33663172
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/transport/http.py
@@ -0,0 +1,116 @@
+"""HTTPTransport — REST fallback for computer-server's POST /cmd endpoint.
+
+The computer-server /cmd endpoint accepts JSON ``{"command": ..., "params": {...}}``
+and returns an SSE stream with a single ``data: {...}`` frame containing the result.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from typing import Any, Dict, Optional
+
+import httpx
+from cua_sandbox.transport.base import Transport
+
+
+class HTTPTransport(Transport):
+ """Transport that communicates with computer-server over HTTP POST /cmd (SSE)."""
+
+ def __init__(
+ self,
+ base_url: str,
+ *,
+ api_key: Optional[str] = None,
+ container_name: Optional[str] = None,
+ timeout: float = 30.0,
+ ):
+ """
+ Args:
+ base_url: Base URL of the computer-server, e.g. "http://localhost:8000".
+ api_key: Optional API key (X-API-Key header) for cloud auth.
+ container_name: Optional container name (X-Container-Name header) for cloud auth.
+ timeout: HTTP request timeout in seconds.
+ """
+ self._base_url = base_url.rstrip("/")
+ self._api_key = api_key
+ self._container_name = container_name
+ self._timeout = timeout
+ self._client: Optional[httpx.AsyncClient] = None
+
+ async def connect(self) -> None:
+ headers: Dict[str, str] = {}
+ if self._api_key:
+ headers["X-API-Key"] = self._api_key
+ headers["Authorization"] = f"Bearer {self._api_key}"
+ if self._container_name:
+ headers["X-Container-Name"] = self._container_name
+ self._client = httpx.AsyncClient(
+ base_url=self._base_url,
+ headers=headers,
+ timeout=self._timeout,
+ )
+
+ async def disconnect(self) -> None:
+ if self._client:
+ await self._client.aclose()
+ self._client = None
+
+ async def _cmd(self, command: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+ """Send a command to POST /cmd and parse the SSE response."""
+ assert self._client is not None, "Transport not connected"
+ body = {"command": command}
+ if params:
+ body["params"] = params
+ resp = await self._client.post("/cmd", json=body)
+ resp.raise_for_status()
+ return self._parse_sse(resp.text)
+
+ @staticmethod
+ def _parse_sse(text: str) -> Dict[str, Any]:
+ """Extract the first ``data: {...}`` frame from an SSE response."""
+ for line in text.splitlines():
+ if line.startswith("data: "):
+ payload = json.loads(line[6:])
+ if isinstance(payload, dict) and not payload.get("success", True):
+ raise RuntimeError(f"Remote error: {payload.get('error', 'unknown')}")
+ return payload
+ raise RuntimeError(f"No SSE data frame in response: {text[:200]}")
+
+ async def send(self, action: str, **params: Any) -> Any:
+ result = await self._cmd(action, params if params else None)
+ return result.get("result", result)
+
+ async def screenshot(self, format: str = "png", quality: int = 95) -> bytes:
+ params = None if format == "png" else {"format": format, "quality": quality}
+ result = await self._cmd("screenshot", params)
+ # computer-server returns {"success": true, "image_data": "..."}
+ b64 = result.get("image_data", result.get("base64_image", result.get("result", "")))
+ if isinstance(b64, dict):
+ b64 = b64.get("image_data", b64.get("base64_image", b64.get("base64", "")))
+ return base64.b64decode(b64)
+
+ async def get_screen_size(self) -> Dict[str, int]:
+ result = await self._cmd("get_screen_size")
+ # Flatten nested responses and normalize key names
+ data = result
+ if isinstance(data, dict):
+ # Unwrap nested: {"result": {...}}, {"size": {...}}
+ data = data.get("size", data.get("result", data))
+ if isinstance(data, dict):
+ w = data.get("width") or data.get("screen_width") or data.get("w")
+ h = data.get("height") or data.get("screen_height") or data.get("h")
+ if w is not None and h is not None:
+ return {"width": int(w), "height": int(h)}
+ raise KeyError(f"Cannot extract screen size from response: {result}")
+
+ async def get_environment(self) -> str:
+ # computer-server doesn't have a dedicated endpoint; use /status
+ try:
+ assert self._client is not None
+ resp = await self._client.get("/status")
+ resp.raise_for_status()
+ data = resp.json()
+ return data.get("os_type", data.get("platform", "linux"))
+ except Exception:
+ return "linux"
diff --git a/libs/python/cua-sandbox/cua_sandbox/transport/local.py b/libs/python/cua-sandbox/cua_sandbox/transport/local.py
new file mode 100644
index 0000000000..65a8b205ce
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/transport/local.py
@@ -0,0 +1,100 @@
+"""LocalTransport — delegates to cua_auto for direct host control.
+
+All cua_auto calls are synchronous; we use asyncio.to_thread() to avoid
+blocking the event loop.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import platform
+from typing import Any, Dict
+
+from cua_sandbox.transport.base import Transport
+
+
+class LocalTransport(Transport):
+ """Transport that routes commands directly to cua_auto modules."""
+
+ async def connect(self) -> None:
+ pass # no-op for local
+
+ async def disconnect(self) -> None:
+ pass # no-op for local
+
+ async def send(self, action: str, **params: Any) -> Any:
+ """Dispatch a named command to the appropriate cua_auto module."""
+ return await asyncio.to_thread(self._dispatch, action, params)
+
+ def _dispatch(self, command: str, params: dict) -> Any:
+ import cua_auto.clipboard as clipboard
+ import cua_auto.keyboard as keyboard
+ import cua_auto.mouse as mouse
+ import cua_auto.shell as shell
+ import cua_auto.window as window
+
+ dispatch = {
+ # Mouse
+ "left_click": lambda p: mouse.click(p["x"], p["y"], p.get("button", "left")),
+ "right_click": lambda p: mouse.right_click(p["x"], p["y"]),
+ "double_click": lambda p: mouse.double_click(p["x"], p["y"]),
+ "move_cursor": lambda p: mouse.move_to(p["x"], p["y"]),
+ "scroll": lambda p: (
+ mouse.move_to(p.get("x", 0), p.get("y", 0)),
+ mouse.scroll(p.get("scroll_x", 0), p.get("scroll_y", 3)),
+ ),
+ "mouse_down": lambda p: mouse.mouse_down(
+ 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")
+ ),
+ # Keyboard
+ "type_text": lambda p: keyboard.type_text(p["text"]),
+ "hotkey": lambda p: keyboard.hotkey(
+ p["keys"] if isinstance(p["keys"], list) else [p["keys"]]
+ ),
+ "key_down": lambda p: keyboard.key_down(p["key"]),
+ "key_up": lambda p: keyboard.key_up(p["key"]),
+ # Clipboard
+ "copy_to_clipboard": lambda p: clipboard.get(),
+ "set_clipboard": lambda p: clipboard.set(p["text"]),
+ # Shell
+ "run_command": lambda p: shell.run(p["command"], p.get("timeout", 30)),
+ # Window
+ "get_active_window_title": lambda p: window.get_active_window_title(),
+ }
+
+ handler = dispatch.get(command)
+ if handler is None:
+ raise ValueError(f"Unknown local command: {command}")
+ return handler(params)
+
+ async def screenshot(self, format: str = "png", quality: int = 95) -> bytes:
+ png = await asyncio.to_thread(self._screenshot_sync)
+ from cua_sandbox.transport.base import convert_screenshot
+
+ return convert_screenshot(png, format, quality)
+
+ def _screenshot_sync(self) -> bytes:
+ import cua_auto.screen as screen
+
+ return screen.screenshot_bytes()
+
+ async def get_screen_size(self) -> Dict[str, int]:
+ return await asyncio.to_thread(self._screen_size_sync)
+
+ def _screen_size_sync(self) -> Dict[str, int]:
+ import cua_auto.screen as screen
+
+ w, h = screen.screen_size()
+ return {"width": w, "height": h}
+
+ async def get_environment(self) -> str:
+ system = platform.system()
+ if system == "Darwin":
+ return "mac"
+ if system == "Windows":
+ return "windows"
+ return "linux"
diff --git a/libs/python/cua-sandbox/cua_sandbox/transport/osworld.py b/libs/python/cua-sandbox/cua_sandbox/transport/osworld.py
new file mode 100644
index 0000000000..e6dfbde8a4
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/transport/osworld.py
@@ -0,0 +1,75 @@
+"""OSWorldTransport — speaks the OSWorld Flask server API (port 5000).
+
+The OSWorld computer-server exposes:
+ GET /screenshot → raw PNG bytes
+ POST /screen_size → {"width": ..., "height": ...}
+ POST /execute → {"command": [...], "shell": false} → {"output": ...}
+ POST /run_bash_script → {"script": ..., "timeout": ...} → {"status": ..., "output": ..., "error": ..., "returncode": ...}
+ GET /accessibility → {"AT": ...}
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+import httpx
+from cua_sandbox.transport.base import Transport
+
+
+class OSWorldTransport(Transport):
+ """Transport for VMs running the OSWorld Flask server (pyautogui-based)."""
+
+ def __init__(
+ self,
+ base_url: str,
+ *,
+ timeout: float = 30.0,
+ ):
+ self._base_url = base_url.rstrip("/")
+ self._timeout = timeout
+ self._client: Optional[httpx.AsyncClient] = None
+
+ async def connect(self) -> None:
+ self._client = httpx.AsyncClient(
+ base_url=self._base_url,
+ timeout=self._timeout,
+ )
+
+ async def disconnect(self) -> None:
+ if self._client:
+ await self._client.aclose()
+ self._client = None
+
+ async def send(self, action: str, **params: Any) -> Any:
+ assert self._client is not None, "Transport not connected"
+ if action in ("execute", "run_bash_script", "run_python"):
+ resp = await self._client.post(f"/{action}", json=params)
+ resp.raise_for_status()
+ return resp.json()
+ if action == "accessibility":
+ resp = await self._client.get("/accessibility")
+ resp.raise_for_status()
+ return resp.json()
+ if action == "terminal":
+ resp = await self._client.get("/terminal")
+ resp.raise_for_status()
+ return resp.json()
+ raise ValueError(f"Unknown action: {action}")
+
+ async def screenshot(self, format: str = "png", quality: int = 95) -> bytes:
+ assert self._client is not None, "Transport not connected"
+ resp = await self._client.get("/screenshot")
+ resp.raise_for_status()
+ from cua_sandbox.transport.base import convert_screenshot
+
+ return convert_screenshot(resp.content, format, quality)
+
+ async def get_screen_size(self) -> Dict[str, int]:
+ assert self._client is not None, "Transport not connected"
+ resp = await self._client.post("/screen_size")
+ resp.raise_for_status()
+ data = resp.json()
+ return {"width": int(data["width"]), "height": int(data["height"])}
+
+ async def get_environment(self) -> str:
+ return "linux"
diff --git a/libs/python/cua-sandbox/cua_sandbox/transport/qmp.py b/libs/python/cua-sandbox/cua_sandbox/transport/qmp.py
new file mode 100644
index 0000000000..bdbcd34a3c
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/transport/qmp.py
@@ -0,0 +1,477 @@
+"""QMPTransport — control a QEMU VM directly via QMP (no guest agent required).
+
+Uses the QEMU Machine Protocol to provide mouse, keyboard, and screenshot
+control without needing computer-server installed inside the guest OS.
+This enables sandboxing of stock OS images (e.g. Android-x86, raw Linux ISOs).
+
+QMP commands used:
+ - screendump → screenshot (PNG via PPM conversion)
+ - input-send-event → mouse move, click, scroll
+ - send-key → keyboard input
+ - query-status → VM status checks
+
+For shell access, this transport uses QEMU Guest Agent (QGA) over virtio-serial
+when available, or raises NotImplementedError for raw VMs without an agent.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import struct
+import tempfile
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from cua_sandbox.transport.base import Transport
+
+logger = logging.getLogger(__name__)
+
+# ── QMP key name mapping ─────────────────────────────────────────────────────
+# Maps common key names to QEMU QCode values.
+# Full list: https://github.com/qemu/qemu/blob/master/ui/input-keymap-qcode-to-qnum.c
+
+_KEY_MAP: Dict[str, str] = {
+ # Letters
+ **{c: c for c in "abcdefghijklmnopqrstuvwxyz"},
+ # Numbers
+ **{str(i): str(i) for i in range(10)},
+ # Special keys
+ "enter": "ret",
+ "return": "ret",
+ "ret": "ret",
+ "escape": "esc",
+ "esc": "esc",
+ "tab": "tab",
+ "space": "spc",
+ " ": "spc",
+ "backspace": "backspace",
+ "delete": "delete",
+ "del": "delete",
+ "insert": "insert",
+ "ins": "insert",
+ "home": "home",
+ "end": "end",
+ "pageup": "pgup",
+ "page_up": "pgup",
+ "pgup": "pgup",
+ "pagedown": "pgdn",
+ "page_down": "pgdn",
+ "pgdn": "pgdn",
+ "up": "up",
+ "down": "down",
+ "left": "left",
+ "right": "right",
+ # Modifiers
+ "shift": "shift",
+ "ctrl": "ctrl",
+ "control": "ctrl",
+ "alt": "alt",
+ "meta": "meta_l",
+ "super": "meta_l",
+ "command": "meta_l",
+ "cmd": "meta_l",
+ "win": "meta_l",
+ # Function keys
+ **{f"f{i}": f"f{i}" for i in range(1, 13)},
+ # Punctuation
+ "-": "minus",
+ "=": "equal",
+ "[": "bracket_left",
+ "]": "bracket_right",
+ "\\": "backslash",
+ ";": "semicolon",
+ "'": "apostrophe",
+ ",": "comma",
+ ".": "dot",
+ "/": "slash",
+ "`": "grave_accent",
+}
+
+# Mouse button mapping
+_BTN_MAP: Dict[str, int] = {"left": 0, "middle": 1, "right": 2}
+
+
+class QMPTransport(Transport):
+ """Transport that controls a QEMU VM via QMP socket.
+
+ Provides screenshot, mouse, and keyboard control without any guest agent.
+ Shell commands require QEMU Guest Agent (virtio-serial) in the guest.
+ """
+
+ def __init__(
+ self,
+ qmp_host: str = "127.0.0.1",
+ qmp_port: int = 4444,
+ *,
+ guest_agent_port: Optional[int] = None,
+ screen_width: int = 1280,
+ screen_height: int = 720,
+ environment: str = "linux",
+ ):
+ self._host = qmp_host
+ self._port = qmp_port
+ self._ga_port = guest_agent_port
+ self._screen_w = screen_width
+ self._screen_h = screen_height
+ self._environment = environment
+ self._reader: Optional[asyncio.StreamReader] = None
+ self._writer: Optional[asyncio.StreamWriter] = None
+ self._tmpdir = Path(tempfile.mkdtemp(prefix="cua-qmp-"))
+
+ # ── Connection lifecycle ──────────────────────────────────────────────
+
+ async def connect(self) -> None:
+ self._reader, self._writer = await asyncio.open_connection(self._host, self._port)
+ # QMP greeting — read and discard
+ await self._read_response()
+ # Negotiate capabilities
+ await self._execute("qmp_capabilities")
+ logger.info(f"QMP connected to {self._host}:{self._port}")
+
+ async def disconnect(self) -> None:
+ if self._writer:
+ self._writer.close()
+ try:
+ await self._writer.wait_closed()
+ except Exception:
+ pass
+ self._writer = None
+ self._reader = None
+ # Clean up temp files
+ import shutil
+
+ shutil.rmtree(self._tmpdir, ignore_errors=True)
+
+ # ── Low-level QMP protocol ────────────────────────────────────────────
+
+ async def _execute(self, command: str, arguments: Optional[Dict] = None) -> Dict:
+ """Send a QMP command and return the response."""
+ assert self._writer and self._reader, "QMP not connected"
+ msg: Dict[str, Any] = {"execute": command}
+ if arguments:
+ msg["arguments"] = arguments
+ payload = json.dumps(msg).encode() + b"\n"
+ self._writer.write(payload)
+ await self._writer.drain()
+ return await self._read_response()
+
+ async def _read_response(self) -> Dict:
+ """Read a single QMP JSON response, skipping async events."""
+ assert self._reader
+ while True:
+ line = await self._reader.readline()
+ if not line:
+ raise ConnectionError("QMP connection closed")
+ data = json.loads(line)
+ # Skip async events ({"event": ...}), return commands/greetings
+ if "event" not in data:
+ if "error" in data:
+ raise RuntimeError(f"QMP error: {data['error']}")
+ return data
+
+ # ── Transport interface ───────────────────────────────────────────────
+
+ async def send(self, action: str, **params: Any) -> Any:
+ """Dispatch interface actions to QMP commands."""
+ handler = _ACTION_DISPATCH.get(action)
+ if handler:
+ return await handler(self, **params)
+ raise NotImplementedError(
+ f"QMP transport does not support action {action!r}. "
+ f"Supported: {', '.join(sorted(_ACTION_DISPATCH.keys()))}"
+ )
+
+ async def screenshot(self, format: str = "png", quality: int = 95) -> bytes:
+ """Capture a screenshot via QMP screendump → PPM → PNG."""
+ ppm_path = str(self._tmpdir / "screen.ppm")
+ await self._execute("screendump", {"filename": ppm_path})
+ # Give QEMU a moment to write the file
+ await asyncio.sleep(0.1)
+ ppm_file = Path(ppm_path)
+ if not ppm_file.exists():
+ raise RuntimeError(f"screendump failed — {ppm_path} not created")
+ png_bytes = _ppm_to_png(ppm_file.read_bytes())
+ # Update screen dimensions from the PPM
+ w, h = _ppm_dimensions(ppm_file.read_bytes())
+ if w and h:
+ self._screen_w = w
+ self._screen_h = h
+ from cua_sandbox.transport.base import convert_screenshot
+
+ return convert_screenshot(png_bytes, format, quality)
+
+ async def get_screen_size(self) -> Dict[str, int]:
+ return {"width": self._screen_w, "height": self._screen_h}
+
+ async def get_environment(self) -> str:
+ return self._environment
+
+ # ── Mouse actions ─────────────────────────────────────────────────────
+
+ async def _mouse_move(self, x: int, y: int, **_: Any) -> None:
+ """Move the mouse to absolute coordinates via input-send-event."""
+ await self._execute(
+ "input-send-event",
+ {
+ "events": [
+ {"type": "abs", "data": {"axis": "x", "value": _abs_coord(x, self._screen_w)}},
+ {"type": "abs", "data": {"axis": "y", "value": _abs_coord(y, self._screen_h)}},
+ ]
+ },
+ )
+
+ async def _mouse_click(self, x: int, y: int, button: str = "left", **_: Any) -> None:
+ """Move to (x,y) then press+release a mouse button."""
+ btn = _BTN_MAP.get(button, 0)
+ await self._execute(
+ "input-send-event",
+ {
+ "events": [
+ {"type": "abs", "data": {"axis": "x", "value": _abs_coord(x, self._screen_w)}},
+ {"type": "abs", "data": {"axis": "y", "value": _abs_coord(y, self._screen_h)}},
+ {"type": "btn", "data": {"down": True, "button": _qmp_btn(btn)}},
+ {"type": "btn", "data": {"down": False, "button": _qmp_btn(btn)}},
+ ]
+ },
+ )
+
+ async def _mouse_double_click(self, x: int, y: int, **_: Any) -> None:
+ await self._mouse_click(x, y, "left")
+ await asyncio.sleep(0.05)
+ await self._mouse_click(x, y, "left")
+
+ async def _mouse_right_click(self, x: int, y: int, **_: Any) -> None:
+ await self._mouse_click(x, y, "right")
+
+ async def _mouse_down(self, x: int, y: int, button: str = "left", **_: Any) -> None:
+ btn = _BTN_MAP.get(button, 0)
+ await self._execute(
+ "input-send-event",
+ {
+ "events": [
+ {"type": "abs", "data": {"axis": "x", "value": _abs_coord(x, self._screen_w)}},
+ {"type": "abs", "data": {"axis": "y", "value": _abs_coord(y, self._screen_h)}},
+ {"type": "btn", "data": {"down": True, "button": _qmp_btn(btn)}},
+ ]
+ },
+ )
+
+ async def _mouse_up(self, x: int, y: int, button: str = "left", **_: Any) -> None:
+ btn = _BTN_MAP.get(button, 0)
+ await self._execute(
+ "input-send-event",
+ {
+ "events": [
+ {"type": "abs", "data": {"axis": "x", "value": _abs_coord(x, self._screen_w)}},
+ {"type": "abs", "data": {"axis": "y", "value": _abs_coord(y, self._screen_h)}},
+ {"type": "btn", "data": {"down": False, "button": _qmp_btn(btn)}},
+ ]
+ },
+ )
+
+ async def _mouse_scroll(
+ self, x: int, y: int, scroll_x: int = 0, scroll_y: int = 3, **_: Any
+ ) -> None:
+ """Scroll via button 4/5 (up/down) presses."""
+ # Move to position first
+ await self._mouse_move(x, y)
+ # QMP wheel: positive scroll_y = scroll up (button 4), negative = down (button 5)
+ if scroll_y > 0:
+ btn_name = "wheel-up"
+ elif scroll_y < 0:
+ btn_name = "wheel-down"
+ else:
+ return
+ for _ in range(abs(scroll_y)):
+ await self._execute(
+ "input-send-event",
+ {
+ "events": [
+ {"type": "btn", "data": {"down": True, "button": btn_name}},
+ {"type": "btn", "data": {"down": False, "button": btn_name}},
+ ]
+ },
+ )
+
+ async def _drag(
+ self, start_x: int, start_y: int, end_x: int, end_y: int, button: str = "left", **_: Any
+ ) -> None:
+ await self._mouse_down(start_x, start_y, button)
+ await asyncio.sleep(0.05)
+ # Interpolate a few intermediate points for smoother drag
+ steps = 10
+ for i in range(1, steps + 1):
+ ix = start_x + (end_x - start_x) * i // steps
+ iy = start_y + (end_y - start_y) * i // steps
+ await self._mouse_move(ix, iy)
+ await asyncio.sleep(0.01)
+ await self._mouse_up(end_x, end_y, button)
+
+ # ── Keyboard actions ──────────────────────────────────────────────────
+
+ async def _type_text(self, text: str, **_: Any) -> None:
+ """Type text character by character via send-key."""
+ for ch in text:
+ qcode = _KEY_MAP.get(ch.lower())
+ if qcode is None:
+ logger.warning(f"QMP: unmapped character {ch!r}, skipping")
+ continue
+ keys: List[Dict] = []
+ if ch.isupper() or ch in '~!@#$%^&*()_+{}|:"<>?':
+ keys.append({"type": "qcode", "data": "shift"})
+ keys.append({"type": "qcode", "data": qcode})
+ await self._execute("send-key", {"keys": keys, "hold-time": 50})
+ await asyncio.sleep(0.02)
+
+ async def _hotkey(self, keys: List[str], **_: Any) -> None:
+ """Press a key combination via send-key."""
+ qcodes = []
+ for k in keys:
+ qcode = _KEY_MAP.get(k.lower())
+ if qcode is None:
+ raise ValueError(f"Unknown key {k!r}")
+ qcodes.append({"type": "qcode", "data": qcode})
+ await self._execute("send-key", {"keys": qcodes, "hold-time": 100})
+
+ async def _key_down(self, key: str, **_: Any) -> None:
+ qcode = _KEY_MAP.get(key.lower())
+ if qcode is None:
+ raise ValueError(f"Unknown key {key!r}")
+ await self._execute(
+ "input-send-event",
+ {
+ "events": [
+ {
+ "type": "key",
+ "data": {"down": True, "key": {"type": "qcode", "data": qcode}},
+ },
+ ]
+ },
+ )
+
+ async def _key_up(self, key: str, **_: Any) -> None:
+ qcode = _KEY_MAP.get(key.lower())
+ if qcode is None:
+ raise ValueError(f"Unknown key {key!r}")
+ await self._execute(
+ "input-send-event",
+ {
+ "events": [
+ {
+ "type": "key",
+ "data": {"down": False, "key": {"type": "qcode", "data": qcode}},
+ },
+ ]
+ },
+ )
+
+ # ── Shell (via QEMU Guest Agent if available) ─────────────────────────
+
+ async def _run_command(self, command: str, timeout: int = 30, **_: Any) -> Dict:
+ """Execute a shell command via QEMU Guest Agent (QGA).
+
+ Requires virtio-serial guest agent running inside the VM.
+ Falls back to a helpful error if QGA is not available.
+ """
+ raise NotImplementedError(
+ "Shell commands require QEMU Guest Agent (virtio-serial) inside the guest. "
+ "QMPTransport currently supports screenshot, mouse, and keyboard only. "
+ "For shell access, use an image with computer-server installed."
+ )
+
+
+# ── Action dispatch table ─────────────────────────────────────────────────
+
+_ACTION_DISPATCH: Dict[str, Any] = {
+ # Mouse
+ "left_click": QMPTransport._mouse_click,
+ "right_click": QMPTransport._mouse_right_click,
+ "double_click": QMPTransport._mouse_double_click,
+ "move_cursor": QMPTransport._mouse_move,
+ "scroll": QMPTransport._mouse_scroll,
+ "mouse_down": QMPTransport._mouse_down,
+ "mouse_up": QMPTransport._mouse_up,
+ "drag": QMPTransport._drag,
+ # Keyboard
+ "type_text": QMPTransport._type_text,
+ "hotkey": QMPTransport._hotkey,
+ "key_down": QMPTransport._key_down,
+ "key_up": QMPTransport._key_up,
+ # Shell
+ "run_command": QMPTransport._run_command,
+}
+
+
+# ── PPM → PNG conversion (pure-Python, no Pillow dependency) ──────────────
+
+
+def _ppm_dimensions(data: bytes) -> Tuple[int, int]:
+ """Parse width and height from a PPM (P6) header."""
+ try:
+ # P6\n<width> <height>\n<maxval>\n<pixels>
+ header_end = data.index(b"\n", data.index(b"\n") + 1)
+ parts = data[:header_end].split()
+ return int(parts[1]), int(parts[2])
+ except (ValueError, IndexError):
+ return 0, 0
+
+
+def _ppm_to_png(ppm_data: bytes) -> bytes:
+ """Convert a PPM P6 file to PNG using zlib (no external deps)."""
+ import zlib
+
+ # Parse PPM header
+ idx = 0
+ # Magic
+ assert ppm_data[:2] == b"P6", "Not a PPM P6 file"
+ idx = ppm_data.index(b"\n", idx) + 1
+ # Skip comments
+ while ppm_data[idx : idx + 1] == b"#":
+ idx = ppm_data.index(b"\n", idx) + 1
+ # Width Height
+ line_end = ppm_data.index(b"\n", idx)
+ dims = ppm_data[idx:line_end].split()
+ width, height = int(dims[0]), int(dims[1])
+ idx = line_end + 1
+ # Max value
+ line_end = ppm_data.index(b"\n", idx)
+ idx = line_end + 1
+ # Pixel data (RGB, 3 bytes per pixel)
+ pixels = ppm_data[idx:]
+
+ # Build PNG
+ def _png_chunk(chunk_type: bytes, data: bytes) -> bytes:
+ c = chunk_type + data
+ crc = struct.pack(">I", zlib.crc32(c) & 0xFFFFFFFF)
+ return struct.pack(">I", len(data)) + c + crc
+
+ # IHDR
+ ihdr = struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0) # 8-bit RGB
+ # IDAT — build raw image data with filter byte 0 per row
+ raw = bytearray()
+ stride = width * 3
+ for y in range(height):
+ raw.append(0) # filter: None
+ raw.extend(pixels[y * stride : (y + 1) * stride])
+ compressed = zlib.compress(bytes(raw))
+
+ png = b"\x89PNG\r\n\x1a\n"
+ png += _png_chunk(b"IHDR", ihdr)
+ png += _png_chunk(b"IDAT", compressed)
+ png += _png_chunk(b"IEND", b"")
+ return png
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────
+
+
+def _abs_coord(pixel: int, screen_max: int) -> int:
+ """Convert pixel coordinate to QMP absolute input value (0–32767)."""
+ return max(0, min(32767, pixel * 32767 // max(screen_max, 1)))
+
+
+def _qmp_btn(idx: int) -> str:
+ """Map button index to QMP button name."""
+ return {0: "left", 1: "middle", 2: "right"}.get(idx, "left")
diff --git a/libs/python/cua-sandbox/cua_sandbox/transport/ssh.py b/libs/python/cua-sandbox/cua_sandbox/transport/ssh.py
new file mode 100644
index 0000000000..332cfa9f2d
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/transport/ssh.py
@@ -0,0 +1,212 @@
+"""SSH transport — shell commands and file transfer over SSH.
+
+Screenshots are not natively supported; pair with VNCSSHTransport for
+full desktop interaction over SSH-tunneled VNC.
+"""
+
+from __future__ import annotations
+
+import logging
+import socket
+import threading
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+if TYPE_CHECKING:
+ from cua_sandbox.interfaces.tunnel import TunnelInfo
+
+import paramiko
+from cua_sandbox.transport.base import Transport
+
+logger = logging.getLogger(__name__)
+
+
+class SSHTransport(Transport):
+ """Transport that executes commands over SSH using paramiko."""
+
+ def __init__(
+ self,
+ host: str,
+ port: int = 22,
+ username: str = "admin",
+ password: Optional[str] = "admin",
+ key_filename: Optional[str] = None,
+ environment: str = "linux",
+ ):
+ self._host = host
+ self._port = port
+ self._username = username
+ self._password = password
+ self._key_filename = key_filename
+ self._environment = environment
+ self._client: Optional[paramiko.SSHClient] = None
+ self._tunnels: List[_SSHTunnel] = []
+
+ async def connect(self) -> None:
+ import asyncio
+
+ loop = asyncio.get_event_loop()
+ self._client = paramiko.SSHClient()
+ self._client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
+ await loop.run_in_executor(
+ None,
+ lambda: self._client.connect(
+ self._host,
+ port=self._port,
+ username=self._username,
+ password=self._password,
+ key_filename=self._key_filename,
+ timeout=30,
+ look_for_keys=False,
+ allow_agent=False,
+ ),
+ )
+ logger.info(f"SSH connected to {self._host}:{self._port}")
+
+ async def disconnect(self) -> None:
+ for t in list(self._tunnels):
+ t.stop()
+ self._tunnels.clear()
+ if self._client:
+ self._client.close()
+ self._client = None
+
+ async def send(self, action: str, **params: Any) -> Any:
+ import asyncio
+
+ if not self._client:
+ raise RuntimeError("SSH not connected")
+
+ if action in ("shell", "run_command"):
+ command = params.get("command", "")
+ loop = asyncio.get_event_loop()
+ _, stdout, stderr = await loop.run_in_executor(
+ None, lambda: self._client.exec_command(command, timeout=params.get("timeout", 30))
+ )
+ out = await loop.run_in_executor(None, stdout.read)
+ err = await loop.run_in_executor(None, stderr.read)
+ exit_code = stdout.channel.recv_exit_status()
+ return {
+ "stdout": out.decode(errors="replace"),
+ "stderr": err.decode(errors="replace"),
+ "returncode": exit_code,
+ }
+ raise NotImplementedError(f"SSH transport does not support action: {action}")
+
+ async def screenshot(self, format: str = "png", quality: int = 95) -> bytes:
+ raise NotImplementedError(
+ "SSH transport does not support screenshots. "
+ "Use VNCSSHTransport for screenshot support over SSH-tunneled VNC."
+ )
+
+ async def get_screen_size(self) -> Dict[str, int]:
+ raise NotImplementedError("SSH transport does not support screen size queries.")
+
+ async def get_environment(self) -> str:
+ return self._environment
+
+ # ── Tunnel ────────────────────────────────────────────────────────────────
+
+ async def forward_tunnel(self, sandbox_port: int) -> "TunnelInfo":
+ """Open an SSH local-forward from a free host port to *sandbox_port* on the remote."""
+ import asyncio
+
+ from cua_sandbox.interfaces.tunnel import TunnelInfo
+
+ if not self._client:
+ raise RuntimeError("SSH not connected")
+
+ loop = asyncio.get_event_loop()
+ tunnel = await loop.run_in_executor(
+ None, lambda: _SSHTunnel.start(self._client, "localhost", sandbox_port)
+ )
+ self._tunnels.append(tunnel)
+ info = TunnelInfo(host="localhost", port=tunnel.local_port, sandbox_port=sandbox_port)
+ return info
+
+ async def close_tunnel(self, info: "TunnelInfo") -> None:
+ import asyncio
+
+ to_close = [t for t in self._tunnels if t.local_port == info.port]
+ loop = asyncio.get_event_loop()
+ for t in to_close:
+ await loop.run_in_executor(None, t.stop)
+ self._tunnels.remove(t)
+
+
+class _SSHTunnel:
+ """Minimal SSH local-forward: binds a random localhost port, pipes to remote."""
+
+ def __init__(self, local_port: int, server_sock: socket.socket):
+ self.local_port = local_port
+ self._server_sock = server_sock
+ self._stop_event = threading.Event()
+ self._thread = threading.Thread(target=self._serve, daemon=True)
+
+ @classmethod
+ def start(
+ cls,
+ ssh_client: paramiko.SSHClient,
+ remote_host: str,
+ remote_port: int,
+ ) -> "_SSHTunnel":
+ server_sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+ server_sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+ server_sock.bind(("127.0.0.1", 0))
+ local_port = server_sock.getsockname()[1]
+ server_sock.listen(5)
+ server_sock.settimeout(1.0)
+
+ tunnel = cls(local_port, server_sock)
+ tunnel._ssh_client = ssh_client
+ tunnel._remote_host = remote_host
+ tunnel._remote_port = remote_port
+ tunnel._thread.start()
+ return tunnel
+
+ def stop(self) -> None:
+ self._stop_event.set()
+ self._server_sock.close()
+
+ def _serve(self) -> None:
+ while not self._stop_event.is_set():
+ try:
+ client_sock, _ = self._server_sock.accept()
+ except OSError:
+ break
+ transport = self._ssh_client.get_transport()
+ if transport is None:
+ client_sock.close()
+ break
+ try:
+ channel = transport.open_channel(
+ "direct-tcpip",
+ (self._remote_host, self._remote_port),
+ client_sock.getpeername(),
+ )
+ except Exception:
+ client_sock.close()
+ continue
+ threading.Thread(target=self._pipe, args=(client_sock, channel), daemon=True).start()
+
+ @staticmethod
+ def _pipe(sock: socket.socket, channel: paramiko.Channel) -> None:
+ import select
+
+ channel.setblocking(False)
+ sock.setblocking(False)
+ try:
+ while True:
+ r, _, _ = select.select([sock, channel], [], [], 1.0)
+ if sock in r:
+ data = sock.recv(4096)
+ if not data:
+ break
+ channel.sendall(data)
+ if channel in r:
+ data = channel.recv(4096)
+ if not data:
+ break
+ sock.sendall(data)
+ finally:
+ sock.close()
+ channel.close()
diff --git a/libs/python/cua-sandbox/cua_sandbox/transport/vnc.py b/libs/python/cua-sandbox/cua_sandbox/transport/vnc.py
new file mode 100644
index 0000000000..2af24700d2
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/transport/vnc.py
@@ -0,0 +1,107 @@
+"""VNC transport — uses vncdotool for screenshots and input over VNC.
+
+Used by the Tart runtime for headless VMs that expose VNC but don't
+run computer-server.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import tempfile
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from cua_sandbox.transport.base import Transport
+
+logger = logging.getLogger(__name__)
+
+
+class VNCTransport(Transport):
+ """Transport that connects to a VM over VNC using vncdotool."""
+
+ def __init__(
+ self,
+ host: str = "127.0.0.1",
+ port: int = 5900,
+ password: Optional[str] = None,
+ environment: str = "linux",
+ ):
+ self._host = host
+ self._port = port
+ self._password = password
+ self._environment = environment
+ self._client: Any = None
+
+ async def connect(self) -> None:
+ from vncdotool import api as vnc_api
+
+ loop = asyncio.get_event_loop()
+ self._client = await loop.run_in_executor(
+ None,
+ lambda: vnc_api.connect(
+ f"{self._host}::{self._port}",
+ password=self._password,
+ ),
+ )
+ logger.info(f"VNC connected to {self._host}:{self._port}")
+
+ async def get_display_url(self, *, share: bool = False) -> str:
+ if share:
+ raise NotImplementedError("share=True is not supported for local VNC transports.")
+ return f"vnc://{self._host}:{self._port}"
+
+ async def disconnect(self) -> None:
+ if self._client:
+ try:
+ loop = asyncio.get_event_loop()
+ await asyncio.wait_for(
+ loop.run_in_executor(None, self._client.disconnect),
+ timeout=5,
+ )
+ except Exception:
+ pass
+ self._client = None
+ # Shut down the Twisted reactor thread used by vncdotool
+ try:
+ from vncdotool import api as vnc_api
+
+ loop = asyncio.get_event_loop()
+ await asyncio.wait_for(
+ loop.run_in_executor(None, vnc_api.shutdown),
+ timeout=5,
+ )
+ except Exception:
+ pass
+
+ async def send(self, action: str, **params: Any) -> Any:
+ if action == "shell":
+ raise NotImplementedError("Shell commands not supported over VNC")
+ raise NotImplementedError(f"VNC transport does not support action: {action}")
+
+ async def screenshot(self, format: str = "png", quality: int = 95) -> bytes:
+ if not self._client:
+ raise RuntimeError("VNC not connected")
+
+ loop = asyncio.get_event_loop()
+ with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as tmp:
+ tmp_path = tmp.name
+
+ await loop.run_in_executor(None, self._client.captureScreen, tmp_path)
+ data = Path(tmp_path).read_bytes()
+ Path(tmp_path).unlink(missing_ok=True)
+ from cua_sandbox.transport.base import convert_screenshot
+
+ return convert_screenshot(data, format, quality)
+
+ async def get_screen_size(self) -> Dict[str, int]:
+ if not self._client:
+ raise RuntimeError("VNC not connected")
+ # vncdotool exposes screen dimensions via the client
+ return {
+ "width": self._client.screen.width,
+ "height": self._client.screen.height,
+ }
+
+ async def get_environment(self) -> str:
+ return self._environment
diff --git a/libs/python/cua-sandbox/cua_sandbox/transport/vncssh.py b/libs/python/cua-sandbox/cua_sandbox/transport/vncssh.py
new file mode 100644
index 0000000000..009eab0d21
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/transport/vncssh.py
@@ -0,0 +1,157 @@
+"""VNC + SSH transport — screenshots via VNC, shell commands via SSH.
+
+VNC and SSH connect independently to the VM. No tunneling.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import tempfile
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import paramiko
+from cua_sandbox.transport.base import Transport
+
+logger = logging.getLogger(__name__)
+
+
+class VNCSSHTransport(Transport):
+ """Transport using SSH for commands and VNC for screenshots."""
+
+ def __init__(
+ self,
+ *,
+ ssh_host: str,
+ ssh_port: int = 22,
+ ssh_username: str = "admin",
+ ssh_password: Optional[str] = "admin",
+ ssh_key_filename: Optional[str] = None,
+ vnc_host: str = "127.0.0.1",
+ vnc_port: int = 5900,
+ vnc_password: Optional[str] = None,
+ environment: str = "linux",
+ ):
+ self._ssh_host = ssh_host
+ self._ssh_port = ssh_port
+ self._ssh_username = ssh_username
+ self._ssh_password = ssh_password
+ self._ssh_key_filename = ssh_key_filename
+ self._vnc_host = vnc_host
+ self._vnc_port = vnc_port
+ self._vnc_password = vnc_password
+ self._environment = environment
+ self._ssh_client: Optional[paramiko.SSHClient] = None
+ self._vnc_client: Any = None
+
+ async def connect(self) -> None:
+ loop = asyncio.get_event_loop()
+
+ # Connect SSH
+ self._ssh_client = paramiko.SSHClient()
+ self._ssh_client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
+ await loop.run_in_executor(
+ None,
+ lambda: self._ssh_client.connect(
+ self._ssh_host,
+ port=self._ssh_port,
+ username=self._ssh_username,
+ password=self._ssh_password,
+ key_filename=self._ssh_key_filename,
+ timeout=30,
+ look_for_keys=False,
+ allow_agent=False,
+ ),
+ )
+ logger.info(f"SSH connected to {self._ssh_host}:{self._ssh_port}")
+
+ # Connect VNC directly
+ from vncdotool import api as vnc_api
+
+ self._vnc_client = await loop.run_in_executor(
+ None,
+ lambda: vnc_api.connect(
+ f"{self._vnc_host}::{self._vnc_port}",
+ password=self._vnc_password,
+ ),
+ )
+ logger.info(f"VNC connected to {self._vnc_host}:{self._vnc_port}")
+
+ async def get_display_url(self, *, share: bool = False) -> str:
+ if share:
+ raise NotImplementedError("share=True is not supported for local VNC transports.")
+ return f"vnc://{self._vnc_host}:{self._vnc_port}"
+
+ async def disconnect(self) -> None:
+ if self._vnc_client:
+ try:
+ loop = asyncio.get_event_loop()
+ await asyncio.wait_for(
+ loop.run_in_executor(None, self._vnc_client.disconnect),
+ timeout=5,
+ )
+ except Exception:
+ pass
+ self._vnc_client = None
+ # Shut down the Twisted reactor thread used by vncdotool
+ try:
+ from vncdotool import api as vnc_api
+
+ loop = asyncio.get_event_loop()
+ await asyncio.wait_for(
+ loop.run_in_executor(None, vnc_api.shutdown),
+ timeout=5,
+ )
+ except Exception:
+ pass
+ if self._ssh_client:
+ self._ssh_client.close()
+ self._ssh_client = None
+
+ async def send(self, action: str, **params: Any) -> Any:
+ if not self._ssh_client:
+ raise RuntimeError("SSH not connected")
+
+ if action in ("shell", "run_command"):
+ command = params.get("command", "")
+ loop = asyncio.get_event_loop()
+ _, stdout, stderr = await loop.run_in_executor(
+ None,
+ lambda: self._ssh_client.exec_command(command, timeout=params.get("timeout", 30)),
+ )
+ out = await loop.run_in_executor(None, stdout.read)
+ err = await loop.run_in_executor(None, stderr.read)
+ exit_code = stdout.channel.recv_exit_status()
+ return {
+ "stdout": out.decode(errors="replace"),
+ "stderr": err.decode(errors="replace"),
+ "returncode": exit_code,
+ }
+ raise NotImplementedError(f"VNCSSHTransport does not support action: {action}")
+
+ async def screenshot(self, format: str = "png", quality: int = 95) -> bytes:
+ if not self._vnc_client:
+ raise RuntimeError("VNC not connected")
+
+ loop = asyncio.get_event_loop()
+ with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as tmp:
+ tmp_path = tmp.name
+
+ await loop.run_in_executor(None, self._vnc_client.captureScreen, tmp_path)
+ data = Path(tmp_path).read_bytes()
+ Path(tmp_path).unlink(missing_ok=True)
+ from cua_sandbox.transport.base import convert_screenshot
+
+ return convert_screenshot(data, format, quality)
+
+ async def get_screen_size(self) -> Dict[str, int]:
+ if not self._vnc_client:
+ raise RuntimeError("VNC not connected")
+ return {
+ "width": self._vnc_client.screen.width,
+ "height": self._vnc_client.screen.height,
+ }
+
+ async def get_environment(self) -> str:
+ return self._environment
diff --git a/libs/python/cua-sandbox/cua_sandbox/transport/websocket.py b/libs/python/cua-sandbox/cua_sandbox/transport/websocket.py
new file mode 100644
index 0000000000..518c29d724
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/transport/websocket.py
@@ -0,0 +1,71 @@
+"""WebSocketTransport — connects to a computer-server instance via WebSocket.
+
+The computer-server exposes a WebSocket endpoint that accepts JSON commands
+and returns JSON responses. Screenshots are returned as base64-encoded PNG.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from typing import Any, Dict, Optional
+
+import websockets
+from cua_sandbox.transport.base import Transport
+from websockets.asyncio.client import ClientConnection
+
+
+class WebSocketTransport(Transport):
+ """Transport that communicates with computer-server over WebSocket."""
+
+ def __init__(self, url: str, api_key: Optional[str] = None):
+ """
+ Args:
+ url: WebSocket URL, e.g. "ws://localhost:8000/ws"
+ api_key: Optional API key for authentication.
+ """
+ self._url = url
+ self._api_key = api_key
+ self._ws: Optional[ClientConnection] = None
+
+ async def connect(self) -> None:
+ headers = {}
+ if self._api_key:
+ headers["Authorization"] = f"Bearer {self._api_key}"
+ self._ws = await websockets.connect(self._url, additional_headers=headers)
+
+ async def disconnect(self) -> None:
+ if self._ws:
+ await self._ws.close()
+ self._ws = None
+
+ async def _request(self, payload: dict) -> Any:
+ assert self._ws is not None, "Transport not connected"
+ await self._ws.send(json.dumps(payload))
+ raw = await self._ws.recv()
+ return json.loads(raw)
+
+ async def send(self, action: str, **params: Any) -> Any:
+ resp = await self._request({"command": action, **params})
+ if isinstance(resp, dict) and resp.get("error"):
+ raise RuntimeError(f"Remote error: {resp['error']}")
+ return resp.get("result") if isinstance(resp, dict) else resp
+
+ async def screenshot(self, format: str = "png", quality: int = 95) -> bytes:
+ resp = await self._request({"command": "screenshot"})
+ b64 = resp.get("result", resp.get("screenshot", ""))
+ if isinstance(b64, dict):
+ b64 = b64.get("base64", "")
+ png = base64.b64decode(b64)
+ from cua_sandbox.transport.base import convert_screenshot
+
+ return convert_screenshot(png, format, quality)
+
+ async def get_screen_size(self) -> Dict[str, int]:
+ resp = await self._request({"command": "get_screen_size"})
+ result = resp.get("result", resp)
+ return {"width": result["width"], "height": result["height"]}
+
+ async def get_environment(self) -> str:
+ resp = await self._request({"command": "get_environment"})
+ return resp.get("result", "linux")
diff --git a/libs/python/cua-sandbox/pyproject.toml b/libs/python/cua-sandbox/pyproject.toml
new file mode 100644
index 0000000000..531868ee6a
--- /dev/null
+++ b/libs/python/cua-sandbox/pyproject.toml
@@ -0,0 +1,92 @@
+[project]
+name = "cua-sandbox"
+version = "0.1.0"
+description = "CUA Sandbox — ephemeral and persistent sandboxed computer environments"
+readme = "README.md"
+license = "MIT"
+authors = [
+ { name = "TryCua", email = "[email protected]" }
+]
+keywords = [
+ "sandbox",
+ "computer-use",
+ "automation",
+ "vm",
+ "container",
+]
+classifiers = [
+ "Development Status :: 3 - Alpha",
+ "Intended Audience :: Developers",
+ "License :: OSI Approved :: MIT License",
+ "Operating System :: OS Independent",
+ "Programming Language :: Python :: 3",
+ "Programming Language :: Python :: 3.11",
+ "Programming Language :: Python :: 3.12",
+ "Programming Language :: Python :: 3.13",
+ "Topic :: Software Development :: Libraries",
+]
+requires-python = ">=3.11,<3.14"
+
+dependencies = [
+ "cua-auto>=0.1.2",
+ "websockets>=12.0",
+ "httpx>=0.27.0",
+ "oras>=0.2.40",
+ "vncdotool>=1.2.0",
+ "paramiko>=4.0.0",
+ "grpcio==1.78.0",
+ "protobuf==6.31.1",
+ "pycdlib>=1.14.0",
+]
+
+[project.optional-dependencies]
+auth = [
+ "webbrowser-open>=0.0.1",
+]
+dev = [
+ "pytest>=8.0.0",
+ "pytest-asyncio>=0.23.0",
+ "ruff>=0.1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/trycua/cua"
+Repository = "https://github.com/trycua/cua"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build]
+include = [
+ "cua_sandbox/**",
+ "README.md",
+ "LICENSE",
+]
+exclude = [
+ "cua_sandbox/**/__pycache__",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["cua_sandbox"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = [
+ "tests",
+ "../../../examples/sandboxes",
+]
+
+[dependency-groups]
+dev = [
+ "pytest>=9.0.2",
+ "pytest-asyncio>=1.3.0",
+]
diff --git a/libs/python/cua-sandbox/tests/__init__.py b/libs/python/cua-sandbox/tests/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/libs/python/cua-sandbox/tests/conftest.py b/libs/python/cua-sandbox/tests/conftest.py
new file mode 100644
index 0000000000..ae1b71dc24
--- /dev/null
+++ b/libs/python/cua-sandbox/tests/conftest.py
@@ -0,0 +1,153 @@
+"""Shared fixtures for cua-sandbox integration tests.
+
+Each transport/runtime is exposed as a pytest fixture. Tests that need a
+specific backend request the fixture by name; parametrized tests pull from
+all available backends.
+
+Environment variables control which backends are exercised:
+
+ CUA_TEST_LOCAL=1 Enable localhost/local-sandbox tests (default: on)
+ CUA_TEST_WS_URL=ws://... Enable WebSocket transport tests
+ CUA_TEST_HTTP_URL=http://... Enable HTTP transport tests
+ CUA_TEST_API_KEY=sk-... API key for remote transports
+ CUA_TEST_CONTAINER_NAME=... Container name for HTTP cloud auth
+"""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+import pytest_asyncio
+from cua_sandbox.localhost import Localhost
+from cua_sandbox.sandbox import Sandbox
+from cua_sandbox.transport.http import HTTPTransport
+from cua_sandbox.transport.local import LocalTransport
+from cua_sandbox.transport.websocket import WebSocketTransport
+
+# ---------------------------------------------------------------------------
+# Helper: read env config
+# ---------------------------------------------------------------------------
+
+
+def _env_bool(key: str, default: bool = False) -> bool:
+ val = os.environ.get(key, "")
+ if not val:
+ return default
+ return val.lower() in ("1", "true", "yes")
+
+
+LOCAL_ENABLED = _env_bool("CUA_TEST_LOCAL", default=True)
+WS_URL = os.environ.get("CUA_TEST_WS_URL")
+HTTP_URL = os.environ.get("CUA_TEST_HTTP_URL")
+API_KEY = os.environ.get("CUA_TEST_API_KEY")
+CONTAINER_NAME = os.environ.get("CUA_TEST_CONTAINER_NAME")
+
+
+# ---------------------------------------------------------------------------
+# Transport fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest_asyncio.fixture
+async def local_transport():
+ t = LocalTransport()
+ await t.connect()
+ yield t
+ await t.disconnect()
+
+
+@pytest_asyncio.fixture
+async def ws_transport():
+ if not WS_URL:
+ pytest.skip("CUA_TEST_WS_URL not set")
+ t = WebSocketTransport(WS_URL, api_key=API_KEY)
+ await t.connect()
+ yield t
+ await t.disconnect()
+
+
+@pytest_asyncio.fixture
+async def http_transport():
+ if not HTTP_URL:
+ pytest.skip("CUA_TEST_HTTP_URL not set")
+ t = HTTPTransport(HTTP_URL, api_key=API_KEY, container_name=CONTAINER_NAME)
+ await t.connect()
+ yield t
+ await t.disconnect()
+
+
+# ---------------------------------------------------------------------------
+# Sandbox fixtures (one per transport)
+# ---------------------------------------------------------------------------
+
+
+@pytest_asyncio.fixture
+async def local_sandbox():
+ if not LOCAL_ENABLED:
+ pytest.skip("CUA_TEST_LOCAL disabled")
+ async with Localhost.connect() as host:
+ yield host
+
+
+@pytest_asyncio.fixture
+async def ws_sandbox():
+ if not WS_URL:
+ pytest.skip("CUA_TEST_WS_URL not set")
+ sb = await Sandbox._create(ws_url=WS_URL, api_key=API_KEY, name="test-ws")
+ yield sb
+ await sb.disconnect()
+
+
+@pytest_asyncio.fixture
+async def http_sandbox():
+ if not HTTP_URL:
+ pytest.skip("CUA_TEST_HTTP_URL not set")
+ sb = await Sandbox._create(
+ http_url=HTTP_URL,
+ api_key=API_KEY,
+ container_name=CONTAINER_NAME,
+ name="test-http",
+ )
+ yield sb
+ await sb.disconnect()
+
+
+@pytest_asyncio.fixture
+async def localhost_instance():
+ if not LOCAL_ENABLED:
+ pytest.skip("CUA_TEST_LOCAL disabled")
+ async with Localhost.connect() as host:
+ yield host
+
+
+# ---------------------------------------------------------------------------
+# Parametrized "any sandbox" fixture — runs test against every available backend
+# ---------------------------------------------------------------------------
+
+
+def _sandbox_params():
+ params = []
+ if LOCAL_ENABLED:
+ params.append("local_sandbox")
+ if WS_URL:
+ params.append("ws_sandbox")
+ if HTTP_URL:
+ params.append("http_sandbox")
+ if not params:
+ params.append("local_sandbox") # fallback
+ return params
+
+
[email protected](params=_sandbox_params())
+def any_sandbox_name(request):
+ """Returns the fixture name; used by any_sandbox."""
+ return request.param
+
+
+@pytest_asyncio.fixture
+async def any_sandbox(any_sandbox_name, request):
+ """Yields a Sandbox connected via whichever transport is being parametrized."""
+ # Dynamically request the named fixture
+ sb = request.getfixturevalue(any_sandbox_name)
+ return sb
diff --git a/libs/python/cua-sandbox/tests/test_android_multitouch.py b/libs/python/cua-sandbox/tests/test_android_multitouch.py
new file mode 100644
index 0000000000..9330b8ef71
--- /dev/null
+++ b/libs/python/cua-sandbox/tests/test_android_multitouch.py
@@ -0,0 +1,463 @@
+"""
+Android multi-touch integration tests.
+
+Verifies the full touch action space — single-touch gestures, SDK pinch helpers,
+and true two-finger MT Protocol B injection — against the TouchTest APK running
+on an Android VM.
+
+Layout
+──────
+ TestAndroidMultitouchLocal bare-metal AndroidEmulatorRuntime via Sandbox.ephemeral()
+ TestAndroidMultitouchCloud cloud Android VM via Sandbox.ephemeral()
+
+Usage
+─────
+ # Local only (default):
+ pytest tests/test_android_multitouch.py -v
+
+ # Cloud (once implemented):
+ CUA_TEST_API_KEY=sk-... pytest tests/test_android_multitouch.py -v -k cloud
+
+Environment variables
+─────────────────────
+ CUA_ANDROID_TEST_APK path or URL to a pre-built TouchTest debug APK
+ default: latest release from
+ https://github.com/trycua/android-touch-test-app
+ CUA_TEST_API_KEY Anthropic API key (cloud tests only)
+ CUA_ANDROID_API_LEVEL Android API level to boot (default: 34)
+ CUA_ANDROID_AVD_NAME AVD name (default: cua-multitouch-test)
+
+APK source
+──────────
+ The TouchTest APK is built and released from:
+ https://github.com/trycua/android-touch-test-app
+
+ Latest release download:
+ https://github.com/trycua/android-touch-test-app/releases/latest/download/app-debug.apk
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import re
+import urllib.request
+from pathlib import Path
+
+import pytest
+import pytest_asyncio
+from cua_sandbox.image import Image
+from cua_sandbox.runtime.android_emulator import AndroidEmulatorRuntime
+from cua_sandbox.sandbox import Sandbox
+
+# ── Config ─────────────────────────────────────────────────────────────────
+
+_APK_RELEASE_URL = (
+ "https://github.com/trycua/android-touch-test-app" "/releases/latest/download/app-debug.apk"
+)
+_APK_ENV = os.environ.get("CUA_ANDROID_TEST_APK", "")
+# If env var is a local path use it directly; otherwise download from releases.
+_APK_PATH = Path(_APK_ENV) if _APK_ENV and not _APK_ENV.startswith("http") else None
+_APK_PACKAGE = "com.cuatest.touchtest"
+_APK_ACTIVITY = "com.cuatest.touchtest/.MainActivity"
+_LOG_TAG = "TouchTest"
+_RESET_ACTION = "com.cuatest.touchtest.RESET_LOG"
+
+_API_LEVEL = int(os.environ.get("CUA_ANDROID_API_LEVEL", "34"))
+_AVD_NAME = os.environ.get("CUA_ANDROID_AVD_NAME", "cua-multitouch-test")
+_API_KEY = os.environ.get("CUA_TEST_API_KEY")
+_SETTLE_S = 0.6
+_LAUNCH_WAIT_S = 3.0
+
+# ── Helpers ────────────────────────────────────────────────────────────────
+
+
+def _get_apk() -> Path:
+ """Return path to the TouchTest APK, downloading from GitHub Releases if needed."""
+ if _APK_PATH is not None:
+ if _APK_PATH.exists():
+ return _APK_PATH
+ raise FileNotFoundError(f"CUA_ANDROID_TEST_APK set but file not found: {_APK_PATH}")
+
+ # Download from latest release
+ cache = Path("/tmp/cua-touch-test-app-debug.apk")
+ if not cache.exists():
+ url = os.environ.get("CUA_ANDROID_TEST_APK", _APK_RELEASE_URL)
+ print(f"\n[setup] Downloading TouchTest APK from {url} …")
+ urllib.request.urlretrieve(url, cache)
+ return cache
+
+
+def _parse_touch_events(logcat_stdout: str) -> list[dict]:
+ events = []
+ for line in logcat_stdout.splitlines():
+ m = re.search(r"TouchTest:\s+(\{.*\})", line)
+ if m:
+ try:
+ obj = json.loads(m.group(1))
+ if "action" in obj:
+ events.append(obj)
+ except json.JSONDecodeError:
+ pass
+ return events
+
+
+def _max_pointer_count(events: list[dict]) -> int:
+ return max((e.get("pointer_count", 0) for e in events), default=0)
+
+
+def _has_action(events: list[dict], action: str) -> bool:
+ return any(e.get("action") == action for e in events)
+
+
+async def _read_events(sb: Sandbox) -> list[dict]:
+ result = await sb.shell.run(f"logcat -d -s {_LOG_TAG}", timeout=10)
+ return _parse_touch_events(result.stdout)
+
+
+async def _reset(sb: Sandbox) -> None:
+ await sb.shell.run("logcat -c")
+ await sb.shell.run(f"am broadcast -a {_RESET_ACTION}")
+ await asyncio.sleep(0.2)
+
+
+# ── Session-scoped event loop (required for session-scoped async fixtures) ──
+
+
+@pytest_asyncio.fixture(scope="session")
+def event_loop():
+ loop = asyncio.new_event_loop()
+ yield loop
+ loop.close()
+
+
+# ── Session fixture: one emulator for the entire local test run ─────────────
+
+
+@pytest_asyncio.fixture(scope="session", loop_scope="session")
+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.
+ """
+ apk = _get_apk()
+
+ runtime = AndroidEmulatorRuntime(
+ api_level=_API_LEVEL,
+ memory_mb=4096,
+ headless=True,
+ no_boot_anim=True,
+ )
+
+ image = Image.android(str(_API_LEVEL)).apk_install(str(apk))
+
+ async with Sandbox.ephemeral(image, runtime=runtime, name=_AVD_NAME) as sb:
+ # Launch app
+ await sb.shell.run(f"am start -n {_APK_ACTIVITY}")
+ await asyncio.sleep(_LAUNCH_WAIT_S)
+
+ yield 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."""
+ if "local_android_sb" not in request.fixturenames:
+ yield
+ return
+ await _reset(local_android_sb)
+ yield
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# Shared test logic (mixin)
+# ══════════════════════════════════════════════════════════════════════════════
+
+
+class _MultitouchTests:
+ """
+ Full touch action suite. Subclasses must expose a ``sb`` fixture that
+ yields a ready Sandbox with the TouchTest APK installed and running.
+ """
+
+ # ── Single-touch ──────────────────────────────────────────────────────
+
+ async def test_tap(self, sb: Sandbox):
+ w, h = await sb.get_dimensions()
+ await sb.mobile.tap(w // 2, h // 2)
+ await asyncio.sleep(_SETTLE_S)
+
+ te = await _read_events(sb)
+ assert te, "No touch events received"
+ assert _has_action(te, "ACTION_DOWN")
+ assert _has_action(te, "ACTION_UP")
+ assert _max_pointer_count(te) == 1
+
+ async def test_long_press(self, sb: Sandbox):
+ w, h = await sb.get_dimensions()
+ await sb.mobile.long_press(w // 2, h // 2, duration_ms=800)
+ await asyncio.sleep(_SETTLE_S)
+
+ te = await _read_events(sb)
+ assert _has_action(te, "ACTION_DOWN")
+ assert _has_action(te, "ACTION_UP")
+ assert _max_pointer_count(te) == 1
+
+ async def test_double_tap(self, sb: Sandbox):
+ w, h = await sb.get_dimensions()
+ await sb.mobile.double_tap(w // 2, h // 2, delay=0.12)
+ await asyncio.sleep(_SETTLE_S)
+
+ te = await _read_events(sb)
+ downs = [e for e in te if e.get("action") == "ACTION_DOWN"]
+ ups = [e for e in te if e.get("action") == "ACTION_UP"]
+ assert len(downs) >= 2, f"Expected 2 ACTION_DOWNs, got {len(downs)}"
+ assert len(ups) >= 2, f"Expected 2 ACTION_UPs, got {len(ups)}"
+ assert _max_pointer_count(te) == 1
+
+ async def test_swipe(self, sb: Sandbox):
+ w, h = await sb.get_dimensions()
+ await sb.mobile.swipe(w // 2, h * 3 // 4, w // 2, h // 4, duration_ms=300)
+ await asyncio.sleep(_SETTLE_S)
+
+ te = await _read_events(sb)
+ assert _has_action(te, "ACTION_DOWN")
+ assert _has_action(te, "ACTION_MOVE"), "Swipe produced no MOVE events"
+ assert _has_action(te, "ACTION_UP")
+ assert _max_pointer_count(te) == 1
+
+ async def test_fling(self, sb: Sandbox):
+ w, h = await sb.get_dimensions()
+ await sb.mobile.fling(w // 2, h * 3 // 4, w // 2, h // 4)
+ await asyncio.sleep(_SETTLE_S)
+
+ te = await _read_events(sb)
+ assert _has_action(te, "ACTION_DOWN")
+ assert _has_action(te, "ACTION_UP")
+ assert _max_pointer_count(te) == 1
+
+ async def test_scroll_up(self, sb: Sandbox):
+ w, h = await sb.get_dimensions()
+ await sb.mobile.scroll_up(w // 2, h // 2, distance=400, duration_ms=300)
+ await asyncio.sleep(_SETTLE_S)
+ te = await _read_events(sb)
+ assert _has_action(te, "ACTION_DOWN") and _has_action(te, "ACTION_UP")
+
+ async def test_scroll_down(self, sb: Sandbox):
+ w, h = await sb.get_dimensions()
+ await sb.mobile.scroll_down(w // 2, h // 2, distance=400, duration_ms=300)
+ await asyncio.sleep(_SETTLE_S)
+ te = await _read_events(sb)
+ assert _has_action(te, "ACTION_DOWN") and _has_action(te, "ACTION_UP")
+
+ async def test_scroll_left(self, sb: Sandbox):
+ w, h = await sb.get_dimensions()
+ await sb.mobile.scroll_left(w // 2, h // 2, distance=300, duration_ms=300)
+ await asyncio.sleep(_SETTLE_S)
+ te = await _read_events(sb)
+ assert _has_action(te, "ACTION_DOWN") and _has_action(te, "ACTION_UP")
+
+ async def test_scroll_right(self, sb: Sandbox):
+ w, h = await sb.get_dimensions()
+ await sb.mobile.scroll_right(w // 2, h // 2, distance=300, duration_ms=300)
+ await asyncio.sleep(_SETTLE_S)
+ te = await _read_events(sb)
+ assert _has_action(te, "ACTION_DOWN") and _has_action(te, "ACTION_UP")
+
+ # ── SDK pinch (MT Protocol B via sendevent) ────────────────────────────
+
+ async def test_pinch_in(self, sb: Sandbox):
+ """sb.mobile.pinch_in delivers genuine pointer_count == 2 events."""
+ w, h = await sb.get_dimensions()
+ await sb.mobile.pinch_in(w // 2, h // 2, spread=200, duration_ms=400)
+ await asyncio.sleep(_SETTLE_S)
+
+ te = await _read_events(sb)
+ assert te, "No events received"
+ assert (
+ _max_pointer_count(te) >= 2
+ ), f"pinch_in: expected pointer_count >= 2, got {_max_pointer_count(te)}"
+ assert _has_action(
+ te, "ACTION_POINTER_DOWN"
+ ), f"Missing ACTION_POINTER_DOWN — actions: {[e.get('action') for e in te]}"
+
+ async def test_pinch_out(self, sb: Sandbox):
+ """sb.mobile.pinch_out delivers genuine pointer_count == 2 events."""
+ w, h = await sb.get_dimensions()
+ await sb.mobile.pinch_out(w // 2, h // 2, spread=200, duration_ms=400)
+ await asyncio.sleep(_SETTLE_S)
+
+ te = await _read_events(sb)
+ assert te, "No events received"
+ assert (
+ _max_pointer_count(te) >= 2
+ ), f"pinch_out: expected pointer_count >= 2, got {_max_pointer_count(te)}"
+ assert _has_action(te, "ACTION_POINTER_DOWN")
+
+ # ── SDK gesture() — arbitrary multi-finger paths ──────────────────────
+
+ async def test_gesture_pinch_out(self, sb: Sandbox):
+ """sb.mobile.gesture() with two finger paths produces pointer_count == 2."""
+ w, h = await sb.get_dimensions()
+ cx, cy, spread = w // 2, h // 2, 200
+ await sb.mobile.gesture(
+ (cx - 20, cy),
+ (cx - spread, cy), # finger 0: start → end
+ (cx + 20, cy),
+ (cx + spread, cy), # finger 1: start → end
+ )
+ await asyncio.sleep(_SETTLE_S)
+
+ te = await _read_events(sb)
+ assert te, "No events received from gesture()"
+ assert _max_pointer_count(te) >= 2
+ assert _has_action(te, "ACTION_POINTER_DOWN")
+
+ async def test_gesture_two_finger_swipe(self, sb: Sandbox):
+ """Two parallel fingers moving down together."""
+ w, h = await sb.get_dimensions()
+ offset = 150
+ await sb.mobile.gesture(
+ (w // 2 - offset, h // 4),
+ (w // 2 - offset, h * 3 // 4),
+ (w // 2 + offset, h // 4),
+ (w // 2 + offset, h * 3 // 4),
+ )
+ await asyncio.sleep(_SETTLE_S)
+
+ te = await _read_events(sb)
+ assert te, "No events received"
+ move_two = [
+ e for e in te if e.get("action") == "ACTION_MOVE" and e.get("pointer_count", 0) >= 2
+ ]
+ assert move_two, "No ACTION_MOVE events with pointer_count >= 2"
+
+ # ── True multi-touch via MT Protocol B (server-side injection) ───────────
+
+ async def test_true_multitouch_pinch_in(self, sb: Sandbox):
+ """MT Protocol B pinch-in via the multitouch_gesture server action."""
+ w, h = await sb.get_dimensions()
+ cx, cy, spread = w // 2, h // 2, 250
+ await sb.mobile.gesture(
+ (cx - spread, cy),
+ (cx - 30, cy),
+ (cx + spread, cy),
+ (cx + 30, cy),
+ )
+ await asyncio.sleep(_SETTLE_S)
+
+ te = await _read_events(sb)
+ assert te, "No touch events"
+ assert _max_pointer_count(te) >= 2
+ assert _has_action(te, "ACTION_POINTER_DOWN")
+
+ async def test_true_multitouch_pinch_out(self, sb: Sandbox):
+ """MT Protocol B pinch-out via the multitouch_gesture server action."""
+ w, h = await sb.get_dimensions()
+ cx, cy, spread = w // 2, h // 2, 250
+ await sb.mobile.gesture(
+ (cx - 30, cy),
+ (cx - spread, cy),
+ (cx + 30, cy),
+ (cx + spread, cy),
+ )
+ await asyncio.sleep(_SETTLE_S)
+
+ te = await _read_events(sb)
+ assert te, "No touch events"
+ assert _max_pointer_count(te) >= 2
+
+ async def test_true_multitouch_two_finger_swipe(self, sb: Sandbox):
+ """Two parallel fingers moving in the same direction."""
+ w, h = await sb.get_dimensions()
+ offset = 150
+ await sb.mobile.gesture(
+ (w // 2 - offset, h * 3 // 4),
+ (w // 2 - offset, h // 4),
+ (w // 2 + offset, h * 3 // 4),
+ (w // 2 + offset, h // 4),
+ duration_ms=300,
+ steps=15,
+ )
+ await asyncio.sleep(_SETTLE_S)
+
+ te = await _read_events(sb)
+ assert te, "No touch events"
+ move_with_two = [
+ e for e in te if e.get("action") == "ACTION_MOVE" and e.get("pointer_count", 0) >= 2
+ ]
+ assert move_with_two, "No ACTION_MOVE events with pointer_count >= 2"
+
+ async def test_pointer_ids_are_distinct(self, sb: Sandbox):
+ """Each finger in a two-finger gesture must carry a unique pointer id."""
+ w, h = await sb.get_dimensions()
+ cx, cy = w // 2, h // 2
+ await sb.mobile.gesture(
+ (cx - 200, cy),
+ (cx - 50, cy),
+ (cx + 200, cy),
+ (cx + 50, cy),
+ steps=8,
+ )
+ await asyncio.sleep(_SETTLE_S)
+
+ te = await _read_events(sb)
+ two_ptr = [e for e in te if e.get("pointer_count", 0) >= 2]
+ assert two_ptr, "No two-pointer events found"
+ for ev in two_ptr:
+ ids = {p["id"] for p in ev.get("pointers", [])}
+ assert len(ids) >= 2, f"Duplicate pointer ids in event: {ev}"
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# Local tests
+# ══════════════════════════════════════════════════════════════════════════════
+
+
+class TestAndroidMultitouchLocal(_MultitouchTests):
+ """Full touch action suite against a bare-metal AndroidEmulatorRuntime."""
+
+ @pytest_asyncio.fixture(loop_scope="session")
+ async def sb(self, local_android_sb: Sandbox):
+ await _reset(local_android_sb)
+ return local_android_sb
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# Cloud tests
+# ══════════════════════════════════════════════════════════════════════════════
+
+skip_no_api_key = pytest.mark.skipif(not _API_KEY, reason="CUA_TEST_API_KEY not set")
+
+
+@pytest_asyncio.fixture(scope="session", loop_scope="session")
+async def cloud_android_sb():
+ """
+ Spin up an ephemeral cloud Android VM, install the TouchTest APK, escalate
+ to root, launch the app, and yield the ready Sandbox.
+ Shared across all cloud tests so we only pay the boot cost once.
+ """
+ if not _API_KEY:
+ pytest.skip("CUA_TEST_API_KEY not set — cloud tests skipped")
+
+ image = Image.android("14").apk_install(_APK_RELEASE_URL)
+ async with Sandbox.ephemeral(image, api_key=_API_KEY) as sb:
+ # Launch app
+ await sb.shell.run(f"am start -n {_APK_ACTIVITY}")
+ await asyncio.sleep(_LAUNCH_WAIT_S)
+
+ yield sb
+
+
[email protected](loop_scope="session")
[email protected](not _API_KEY, reason="CUA_TEST_API_KEY not set")
+class TestAndroidMultitouchCloud(_MultitouchTests):
+ """Full touch action suite against a cloud-hosted Android VM."""
+
+ @pytest_asyncio.fixture(loop_scope="session")
+ async def sb(self, cloud_android_sb: Sandbox):
+ await _reset(cloud_android_sb)
+ return cloud_android_sb
diff --git a/libs/python/cua-sandbox/tests/test_cloud.py b/libs/python/cua-sandbox/tests/test_cloud.py
new file mode 100644
index 0000000000..7b6e25336b
--- /dev/null
+++ b/libs/python/cua-sandbox/tests/test_cloud.py
@@ -0,0 +1,124 @@
+"""Integration tests — cloud sandbox via CUA API.
+
+ CUA_API_KEY=sk-... pytest tests/test_cloud.py -v -s
+
+Requires a running cloud VM. Set CUA_TEST_CLOUD_VM_NAME to the VM name.
+"""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+from cua_sandbox import Image, Sandbox
+
+pytestmark = pytest.mark.asyncio
+
+API_KEY = os.environ.get("CUA_API_KEY")
+VM_NAME = os.environ.get("CUA_TEST_CLOUD_VM_NAME", "steady-bluebird")
+
+skip_no_key = pytest.mark.skipif(not API_KEY, reason="CUA_API_KEY not set")
+
+
+@skip_no_key
+async def test_cloud_connect_by_name():
+ """Connect to an existing cloud VM by name and take a screenshot."""
+ sb = await Sandbox.connect(VM_NAME, api_key=API_KEY)
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+ assert len(screenshot) > 1000
+ await sb.disconnect()
+
+
+@skip_no_key
+async def test_cloud_shell():
+ """Run a shell command on a cloud VM."""
+ sb = await Sandbox.connect(VM_NAME, api_key=API_KEY)
+ result = await sb.shell.run("echo hello-cloud")
+ assert result.success
+ assert "hello-cloud" in result.stdout
+ await sb.disconnect()
+
+
+@skip_no_key
+async def test_cloud_screen_size():
+ """Get screen dimensions from a cloud VM."""
+ sb = await Sandbox.connect(VM_NAME, api_key=API_KEY)
+ w, h = await sb.get_dimensions()
+ assert w > 0
+ assert h > 0
+ await sb.disconnect()
+
+
+@skip_no_key
+async def test_cloud_keyboard_mouse():
+ """Basic keyboard and mouse operations on a cloud VM."""
+ sb = await Sandbox.connect(VM_NAME, api_key=API_KEY)
+ await sb.mouse.move(100, 100)
+ await sb.mouse.click(100, 100)
+ await sb.keyboard.type("hello")
+ await sb.disconnect()
+
+
+@skip_no_key
+async def test_cloud_environment():
+ """Get environment info from a cloud VM."""
+ sb = await Sandbox.connect(VM_NAME, api_key=API_KEY)
+ env = await sb.get_environment()
+ assert env in ("windows", "mac", "linux", "browser")
+ await sb.disconnect()
+
+
+async def test_cloud_no_api_key_errors():
+ """Connecting with no API key gives a clear error."""
+ old = os.environ.pop("CUA_API_KEY", None)
+ try:
+ with pytest.raises(ValueError, match="No CUA API key found"):
+ await Sandbox.connect("anything")
+ finally:
+ if old:
+ os.environ["CUA_API_KEY"] = old
+
+
+async def test_cloud_no_image_no_name_errors():
+ """Creating without an image raises a clear error."""
+ with pytest.raises((ValueError, TypeError)):
+ await Sandbox._create(api_key="sk-test-fake-key")
+
+
+@skip_no_key
+async def test_cloud_ephemeral_linux():
+ """Create an ephemeral cloud Linux VM, use it, and destroy on exit."""
+ async with Sandbox.ephemeral(Image.linux(), api_key=API_KEY) as sb:
+ assert sb.name is not None
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+ assert len(screenshot) > 1000
+ result = await sb.shell.run("echo ephemeral-test")
+ assert result.success
+ assert "ephemeral-test" in result.stdout
+
+
+@skip_no_key
+async def test_cloud_ephemeral_android():
+ """Create an ephemeral Android cloud VM, verify screenshot and display URL."""
+ async with Sandbox.ephemeral(Image.android("14"), api_key=API_KEY) as sb:
+ assert sb.name is not None
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+ assert len(screenshot) > 1000
+ env = await sb.get_environment()
+ assert env == "android"
+ display_url = await sb.get_display_url(share=True)
+ assert ".cua.sh" in display_url
+ assert "password=" in display_url
+
+
+@skip_no_key
+async def test_cloud_invalid_api_key_errors():
+ """An invalid (reversed) API key should get an HTTP error from the API."""
+ reversed_key = API_KEY[::-1]
+ with pytest.raises(Exception):
+ sb = await Sandbox.connect(VM_NAME, api_key=reversed_key)
+ await sb.screenshot()
+ await sb.disconnect()
diff --git a/libs/python/cua-sandbox/tests/test_config.py b/libs/python/cua-sandbox/tests/test_config.py
new file mode 100644
index 0000000000..128cff5b96
--- /dev/null
+++ b/libs/python/cua-sandbox/tests/test_config.py
@@ -0,0 +1,32 @@
+"""Unit tests for config and auth modules."""
+
+import os
+import pytest
+from cua_sandbox._config import configure, get_api_key, get_base_url, _global_config
+
+
+class TestConfig:
+ def setup_method(self):
+ _global_config.api_key = None
+ _global_config.base_url = "https://api.trycua.com"
+
+ def test_configure_api_key(self):
+ configure(api_key="sk-test-123")
+ assert get_api_key() == "sk-test-123"
+
+ def test_configure_base_url(self):
+ configure(base_url="http://localhost:9000")
+ assert get_base_url() == "http://localhost:9000"
+
+ def test_override_takes_priority(self):
+ configure(api_key="sk-global")
+ assert get_api_key("sk-override") == "sk-override"
+
+ def test_env_var_fallback(self, monkeypatch):
+ monkeypatch.setenv("CUA_API_KEY", "sk-env")
+ assert get_api_key() == "sk-env"
+
+ def test_configure_overrides_env(self, monkeypatch):
+ monkeypatch.setenv("CUA_API_KEY", "sk-env")
+ configure(api_key="sk-configured")
+ assert get_api_key() == "sk-configured"
diff --git a/libs/python/cua-sandbox/tests/test_image.py b/libs/python/cua-sandbox/tests/test_image.py
new file mode 100644
index 0000000000..99f1db9954
--- /dev/null
+++ b/libs/python/cua-sandbox/tests/test_image.py
@@ -0,0 +1,218 @@
+"""Unit tests for the Image builder (no runtime needed)."""
+
+import pytest
+from cua_sandbox.image import Image
+
+
+class TestImageBuilder:
+ def test_linux_defaults(self):
+ img = Image.linux()
+ assert img.os_type == "linux"
+ assert img.distro == "ubuntu"
+ assert img.version == "24.04"
+
+ def test_macos(self):
+ img = Image.macos("15")
+ assert img.os_type == "macos"
+
+ def test_windows(self):
+ img = Image.windows("11")
+ assert img.os_type == "windows"
+
+ def test_chaining_is_immutable(self):
+ base = Image.linux()
+ with_curl = base.apt_install("curl")
+ with_git = base.apt_install("git")
+ assert len(base._layers) == 0
+ assert len(with_curl._layers) == 1
+ assert len(with_git._layers) == 1
+ assert with_curl._layers[0]["packages"] == ["curl"]
+ assert with_git._layers[0]["packages"] == ["git"]
+
+ def test_full_chain(self):
+ img = (
+ Image.linux("debian", "12")
+ .apt_install("curl", "git")
+ .pip_install("numpy")
+ .env(FOO="bar", BAZ="qux")
+ .run("echo hello")
+ .copy("/local/file", "/remote/file")
+ .expose(8080)
+ .expose(3000)
+ )
+ d = img.to_dict()
+ assert d["os_type"] == "linux"
+ assert d["distro"] == "debian"
+ assert len(d["layers"]) == 3 # apt, pip, run
+ assert d["env"] == {"FOO": "bar", "BAZ": "qux"}
+ assert d["ports"] == [8080, 3000]
+ assert d["files"] == [["/local/file", "/remote/file"]]
+
+ def test_roundtrip(self):
+ img = Image.linux().apt_install("curl").env(X="1").expose(80)
+ d = img.to_dict()
+ img2 = Image.from_dict(d)
+ assert img2.to_dict() == d
+
+ def test_cloud_init(self):
+ img = (
+ Image.linux().apt_install("curl", "git").pip_install("flask").run("systemctl start app")
+ )
+ script = img.to_cloud_init()
+ assert "#!/bin/bash" in script
+ assert "apt-get" in script
+ assert "pip install flask" in script
+ assert "systemctl start app" in script
+
+ def test_from_registry(self):
+ img = Image.from_registry("cua/ubuntu-desktop:24.04")
+ assert img._registry == "cua/ubuntu-desktop:24.04"
+ d = img.to_dict()
+ assert d["registry"] == "cua/ubuntu-desktop:24.04"
+
+ def test_repr(self):
+ img = Image.linux().apt_install("curl")
+ r = repr(img)
+ assert "linux" in r
+ assert "1 layers" in r
+
+ def test_brew_and_choco(self):
+ mac = Image.macos().brew_install("wget")
+ win = Image.windows().choco_install("firefox")
+ assert mac._layers[0]["type"] == "brew_install"
+ assert win._layers[0]["type"] == "choco_install"
+
+
+class TestApkInstall:
+ def test_android_apk_install(self):
+ img = Image.android().apk_install("/path/to/app.apk")
+ assert len(img._layers) == 1
+ assert img._layers[0]["type"] == "apk_install"
+ assert img._layers[0]["packages"] == ["/path/to/app.apk"]
+
+ def test_android_apk_install_multiple(self):
+ img = Image.android().apk_install("app1.apk", "app2.apk", "app3.apk")
+ assert img._layers[0]["packages"] == ["app1.apk", "app2.apk", "app3.apk"]
+
+ def test_android_apk_install_cloud_init(self):
+ img = Image.android().apk_install("app.apk").run("echo done")
+ script = img.to_cloud_init()
+ assert "adb install app.apk" in script
+ assert "echo done" in script
+
+ def test_android_chaining(self):
+ img = (
+ Image.android("14")
+ .apk_install("browser.apk")
+ .env(ADB_HOST="localhost")
+ .run("adb shell settings put global window_animation_scale 0.0")
+ )
+ assert len(img._layers) == 2 # apk_install + run
+ assert img._env == (("ADB_HOST", "localhost"),)
+
+
+class TestFromFileWithLayers:
+ def test_osworld_apt_install(self):
+ img = Image.from_file("/tmp/fake.qcow2", os_type="linux", agent_type="osworld").apt_install(
+ "curl", "git"
+ )
+ assert img._disk_path == "/tmp/fake.qcow2"
+ assert img._agent_type == "osworld"
+ assert len(img._layers) == 1
+ assert img._layers[0]["type"] == "apt_install"
+
+ def test_osworld_full_chain(self):
+ img = (
+ Image.from_file("/tmp/fake.qcow2", os_type="linux", agent_type="osworld")
+ .apt_install("curl", "git")
+ .pip_install("numpy")
+ .env(DISPLAY=":0")
+ .run("systemctl restart app")
+ )
+ assert len(img._layers) == 3 # apt, pip, run
+ assert img._disk_path == "/tmp/fake.qcow2"
+ assert img._agent_type == "osworld"
+ d = img.to_dict()
+ assert d["os_type"] == "linux"
+
+ def test_from_file_android_apk(self):
+ img = Image.from_file("/tmp/android.qcow2", os_type="android").apk_install("myapp.apk")
+ assert img._layers[0]["type"] == "apk_install"
+ assert img._disk_path == "/tmp/android.qcow2"
+
+ def test_from_file_preserves_agent_type_through_chain(self):
+ img = (
+ Image.from_file("/tmp/fake.qcow2", os_type="linux", agent_type="osworld")
+ .apt_install("curl")
+ .pip_install("flask")
+ .run("echo hi")
+ )
+ assert img._agent_type == "osworld"
+ assert img._disk_path == "/tmp/fake.qcow2"
+
+
+class TestOsCompatibilityErrors:
+ """Verify that install methods raise ValueError for wrong OS types."""
+
+ def test_apt_install_on_windows(self):
+ with pytest.raises(ValueError, match="apt_install is not supported on 'windows'"):
+ Image.windows().apt_install("curl")
+
+ def test_apt_install_on_macos(self):
+ with pytest.raises(ValueError, match="apt_install is not supported on 'macos'"):
+ Image.macos().apt_install("curl")
+
+ def test_apt_install_on_android(self):
+ with pytest.raises(ValueError, match="apt_install is not supported on 'android'"):
+ Image.android().apt_install("curl")
+
+ def test_winget_install_on_linux(self):
+ with pytest.raises(ValueError, match="winget_install is not supported on 'linux'"):
+ Image.linux().winget_install("Firefox")
+
+ def test_winget_install_on_macos(self):
+ with pytest.raises(ValueError, match="winget_install is not supported on 'macos'"):
+ Image.macos().winget_install("Firefox")
+
+ def test_choco_install_on_linux(self):
+ with pytest.raises(ValueError, match="choco_install is not supported on 'linux'"):
+ Image.linux().choco_install("firefox")
+
+ def test_brew_install_on_windows(self):
+ with pytest.raises(ValueError, match="brew_install is not supported on 'windows'"):
+ Image.windows().brew_install("wget")
+
+ def test_brew_install_on_linux(self):
+ with pytest.raises(ValueError, match="brew_install is not supported on 'linux'"):
+ Image.linux().brew_install("wget")
+
+ def test_apk_install_on_linux(self):
+ with pytest.raises(ValueError, match="apk_install is not supported on 'linux'"):
+ Image.linux().apk_install("app.apk")
+
+ def test_apk_install_on_windows(self):
+ with pytest.raises(ValueError, match="apk_install is not supported on 'windows'"):
+ Image.windows().apk_install("app.apk")
+
+ def test_apk_install_on_macos(self):
+ with pytest.raises(ValueError, match="apk_install is not supported on 'macos'"):
+ Image.macos().apk_install("app.apk")
+
+ def test_from_file_wrong_os(self):
+ """from_file with os_type='windows' should reject apt_install."""
+ with pytest.raises(ValueError, match="apt_install is not supported on 'windows'"):
+ Image.from_file("/tmp/win.qcow2", os_type="windows").apt_install("curl")
+
+ def test_pip_and_uv_allowed_on_all(self):
+ """pip_install and uv_install are cross-platform — no OS restriction."""
+ Image.linux().pip_install("flask")
+ Image.windows().pip_install("flask")
+ Image.macos().pip_install("flask")
+ Image.android().pip_install("flask")
+ Image.linux().uv_install("flask")
+
+ def test_run_and_env_allowed_on_all(self):
+ """run() and env() are cross-platform."""
+ Image.linux().run("echo hi").env(X="1")
+ Image.windows().run("echo hi").env(X="1")
+ Image.android().run("echo hi").env(X="1")
diff --git a/libs/python/cua-sandbox/tests/test_integration_agent.py b/libs/python/cua-sandbox/tests/test_integration_agent.py
new file mode 100644
index 0000000000..b8538522da
--- /dev/null
+++ b/libs/python/cua-sandbox/tests/test_integration_agent.py
@@ -0,0 +1,80 @@
+"""Integration tests for agent handler adapters."""
+
+from __future__ import annotations
+
+import pytest
+
+from cua_sandbox.agent import SandboxHandler, LocalhostHandler, is_sandbox
+from cua_sandbox.sandbox import Sandbox
+from cua_sandbox.localhost import Localhost
+
+pytestmark = pytest.mark.asyncio
+
+
+class TestSandboxHandler:
+ async def test_screenshot(self, local_sandbox):
+ handler = SandboxHandler(local_sandbox)
+ b64 = await handler.screenshot()
+ assert isinstance(b64, str)
+ assert len(b64) > 100
+
+ async def test_get_environment(self, local_sandbox):
+ handler = SandboxHandler(local_sandbox)
+ env = await handler.get_environment()
+ assert env in ("windows", "mac", "linux", "browser")
+
+ async def test_get_dimensions(self, local_sandbox):
+ handler = SandboxHandler(local_sandbox)
+ w, h = await handler.get_dimensions()
+ assert w > 0 and h > 0
+
+ async def test_click(self, local_sandbox):
+ handler = SandboxHandler(local_sandbox)
+ await handler.click(100, 100)
+
+ async def test_type(self, local_sandbox):
+ handler = SandboxHandler(local_sandbox)
+ await handler.type("test")
+
+ async def test_keypress(self, local_sandbox):
+ handler = SandboxHandler(local_sandbox)
+ await handler.keypress(["ctrl", "a"])
+
+ async def test_scroll(self, local_sandbox):
+ handler = SandboxHandler(local_sandbox)
+ await handler.scroll(100, 100, 0, 3)
+
+ async def test_move(self, local_sandbox):
+ handler = SandboxHandler(local_sandbox)
+ await handler.move(200, 200)
+
+ async def test_drag(self, local_sandbox):
+ handler = SandboxHandler(local_sandbox)
+ await handler.drag([{"x": 100, "y": 100}, {"x": 200, "y": 200}])
+
+ async def test_wait(self, local_sandbox):
+ handler = SandboxHandler(local_sandbox)
+ await handler.wait(10) # 10ms
+
+
+class TestLocalhostHandler:
+ async def test_screenshot(self, localhost_instance):
+ handler = LocalhostHandler(localhost_instance)
+ b64 = await handler.screenshot()
+ assert isinstance(b64, str)
+
+ async def test_click(self, localhost_instance):
+ handler = LocalhostHandler(localhost_instance)
+ await handler.click(50, 50)
+
+
+class TestIsSandbox:
+ async def test_sandbox_detected(self, local_sandbox):
+ assert is_sandbox(local_sandbox)
+
+ async def test_localhost_detected(self, localhost_instance):
+ assert is_sandbox(localhost_instance)
+
+ def test_other_not_detected(self):
+ assert not is_sandbox("not a sandbox")
+ assert not is_sandbox(42)
diff --git a/libs/python/cua-sandbox/tests/test_integration_interfaces.py b/libs/python/cua-sandbox/tests/test_integration_interfaces.py
new file mode 100644
index 0000000000..db8ce147fe
--- /dev/null
+++ b/libs/python/cua-sandbox/tests/test_integration_interfaces.py
@@ -0,0 +1,163 @@
+"""Integration tests — exercise every interface method against every available transport.
+
+Run with:
+ pytest tests/test_integration_interfaces.py -v
+
+By default only local transport is tested. Set env vars to enable remote:
+ CUA_TEST_WS_URL=ws://host:8000/ws
+ CUA_TEST_HTTP_URL=http://host:8000
+"""
+
+from __future__ import annotations
+
+import asyncio
+import pytest
+
+pytestmark = pytest.mark.asyncio
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Screen
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class TestScreen:
+ async def test_screenshot_returns_png_bytes(self, any_sandbox):
+ data = await any_sandbox.screenshot()
+ assert isinstance(data, bytes)
+ assert len(data) > 100
+ # PNG magic bytes
+ assert data[:4] == b"\x89PNG"
+
+ async def test_screenshot_base64(self, any_sandbox):
+ b64 = await any_sandbox.screenshot_base64()
+ assert isinstance(b64, str)
+ assert len(b64) > 100
+
+ async def test_screen_size(self, any_sandbox):
+ w, h = await any_sandbox.get_dimensions()
+ assert isinstance(w, int)
+ assert isinstance(h, int)
+ assert w > 0
+ assert h > 0
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Mouse
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class TestMouse:
+ async def test_move(self, any_sandbox):
+ await any_sandbox.mouse.move(100, 100)
+
+ async def test_click(self, any_sandbox):
+ await any_sandbox.mouse.click(100, 100)
+
+ async def test_right_click(self, any_sandbox):
+ await any_sandbox.mouse.right_click(200, 200)
+
+ async def test_double_click(self, any_sandbox):
+ await any_sandbox.mouse.double_click(150, 150)
+
+ async def test_scroll(self, any_sandbox):
+ await any_sandbox.mouse.scroll(100, 100, scroll_y=3)
+
+ async def test_mouse_down_up(self, any_sandbox):
+ await any_sandbox.mouse.mouse_down(100, 100)
+ await any_sandbox.mouse.mouse_up(200, 200)
+
+ async def test_drag(self, any_sandbox):
+ await any_sandbox.mouse.drag(100, 100, 300, 300)
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Keyboard
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class TestKeyboard:
+ async def test_type_text(self, any_sandbox):
+ await any_sandbox.keyboard.type("hello")
+
+ async def test_keypress_single(self, any_sandbox):
+ await any_sandbox.keyboard.keypress("enter")
+
+ async def test_keypress_combo(self, any_sandbox):
+ await any_sandbox.keyboard.keypress(["ctrl", "a"])
+
+ async def test_key_down_up(self, any_sandbox):
+ await any_sandbox.keyboard.key_down("shift")
+ await any_sandbox.keyboard.key_up("shift")
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Clipboard
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class TestClipboard:
+ async def test_set_and_get(self, any_sandbox):
+ await any_sandbox.clipboard.set("cua-sandbox-test")
+ result = await any_sandbox.clipboard.get()
+ assert result == "cua-sandbox-test"
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Shell
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class TestShell:
+ async def test_run_echo(self, any_sandbox):
+ result = await any_sandbox.shell.run("echo hello-sandbox")
+ assert result.success
+ assert "hello-sandbox" in result.stdout
+
+ async def test_run_failure(self, any_sandbox):
+ result = await any_sandbox.shell.run("exit 1")
+ assert not result.success
+ assert result.returncode != 0
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Window
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class TestWindow:
+ async def test_get_active_title(self, any_sandbox):
+ title = await any_sandbox.window.get_active_title()
+ assert isinstance(title, str)
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Environment / Dimensions
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class TestEnvironment:
+ async def test_get_environment(self, any_sandbox):
+ env = await any_sandbox.get_environment()
+ assert env in ("windows", "mac", "linux", "browser")
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Localhost (separate from sandbox parametrization)
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class TestLocalhost:
+ async def test_screenshot(self, localhost_instance):
+ data = await localhost_instance.screenshot()
+ assert data[:4] == b"\x89PNG"
+
+ async def test_mouse_click(self, localhost_instance):
+ await localhost_instance.mouse.click(50, 50)
+
+ async def test_keyboard_type(self, localhost_instance):
+ await localhost_instance.keyboard.type("x")
+
+ async def test_shell_run(self, localhost_instance):
+ result = await localhost_instance.shell.run("echo localhost-test")
+ assert result.success
+
+ async def test_environment(self, localhost_instance):
+ env = await localhost_instance.get_environment()
+ assert env in ("windows", "mac", "linux")
+
+ async def test_dimensions(self, localhost_instance):
+ w, h = await localhost_instance.get_dimensions()
+ assert w > 0 and h > 0
diff --git a/libs/python/cua-sandbox/tests/test_integration_sync.py b/libs/python/cua-sandbox/tests/test_integration_sync.py
new file mode 100644
index 0000000000..d2c575aaa6
--- /dev/null
+++ b/libs/python/cua-sandbox/tests/test_integration_sync.py
@@ -0,0 +1,32 @@
+"""Integration tests for the synchronous API wrappers."""
+
+from __future__ import annotations
+
+from cua_sandbox.sync import localhost
+
+
+class TestSyncLocalhost:
+ def test_screenshot(self):
+ with localhost() as host:
+ data = host.screenshot()
+ assert isinstance(data, bytes)
+ assert data[:4] == b"\x89PNG"
+
+ def test_mouse_click(self):
+ with localhost() as host:
+ host.mouse.click(50, 50)
+
+ def test_shell_run(self):
+ with localhost() as host:
+ result = host.shell.run("echo sync-test")
+ assert result.success
+ assert "sync-test" in result.stdout
+
+ def test_keyboard_type(self):
+ with localhost() as host:
+ host.keyboard.type("x")
+
+ def test_dimensions(self):
+ with localhost() as host:
+ w, h = host.get_dimensions()
+ assert w > 0 and h > 0
diff --git a/libs/python/cua-sandbox/tests/test_oci.py b/libs/python/cua-sandbox/tests/test_oci.py
new file mode 100644
index 0000000000..406ae5e054
--- /dev/null
+++ b/libs/python/cua-sandbox/tests/test_oci.py
@@ -0,0 +1,232 @@
+"""OCI registry tests — manifest inspection, kind detection, image formats.
+
+ pytest tests/test_oci.py -v -s
+
+Unit tests use synthetic manifests. Integration tests (marked `oci_live`)
+fetch real manifests from ghcr.io and require network access.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from cua_sandbox.registry.manifest import (
+ ImageFormat,
+ detect_format,
+ detect_kind,
+ detect_os,
+ get_layer_info,
+)
+from cua_sandbox.registry.media_types import (
+ DOCKER_IMAGE_CONFIG,
+ DOCKER_IMAGE_LAYER,
+ LEGACY_DISK_CHUNK,
+ OCI_IMAGE_CONFIG,
+ OCI_IMAGE_LAYER,
+ OCI_VM_AUX,
+ OCI_VM_CONFIG,
+ OCI_VM_DISK,
+ QEMU_CONFIG,
+ QEMU_DISK_GZIP,
+)
+from cua_sandbox.registry.ref import parse_ref
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+# parse_ref
+# ═════════════════════════════════════════════════════════════════════════════
+
+class TestParseRef:
+ def test_full_ref(self):
+ assert parse_ref("ghcr.io/trycua/macos-sequoia-cua:latest") == (
+ "ghcr.io", "trycua", "macos-sequoia-cua", "latest"
+ )
+
+ def test_org_name(self):
+ assert parse_ref("trycua/cua-xfce:v2") == (
+ "ghcr.io", "trycua", "cua-xfce", "v2"
+ )
+
+ def test_short_name(self):
+ assert parse_ref("cua-xfce") == (
+ "ghcr.io", "trycua", "cua-xfce", "latest"
+ )
+
+ def test_short_name_with_tag(self):
+ assert parse_ref("cua-xfce:nightly") == (
+ "ghcr.io", "trycua", "cua-xfce", "nightly"
+ )
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+# detect_format / detect_kind — synthetic manifests
+# ═════════════════════════════════════════════════════════════════════════════
+
+def _make_manifest(config_mt: str, layer_mts: list[str], **kwargs) -> dict:
+ m = {
+ "config": {"mediaType": config_mt, "digest": "sha256:aaa", "size": 100},
+ "layers": [
+ {"mediaType": mt, "digest": f"sha256:{i:03x}", "size": 1000}
+ for i, mt in enumerate(layer_mts)
+ ],
+ }
+ m.update(kwargs)
+ return m
+
+
+class TestDetectFormat:
+ def test_oci_layered_by_config(self):
+ m = _make_manifest(OCI_VM_CONFIG, [OCI_VM_DISK, OCI_VM_AUX])
+ assert detect_format(m) == ImageFormat.OCI_LAYERED
+
+ def test_oci_layered_by_layer(self):
+ m = _make_manifest("application/json", [OCI_VM_DISK])
+ assert detect_format(m) == ImageFormat.OCI_LAYERED
+
+ def test_legacy_lz4_by_layer(self):
+ m = _make_manifest("application/json", [LEGACY_DISK_CHUNK, LEGACY_DISK_CHUNK])
+ assert detect_format(m) == ImageFormat.LEGACY_LZ4
+
+ def test_chunked_parts(self):
+ m = _make_manifest("application/json", [
+ f"{OCI_IMAGE_LAYER};part.number=1;part.total=3",
+ f"{OCI_IMAGE_LAYER};part.number=2;part.total=3",
+ f"{OCI_IMAGE_LAYER};part.number=3;part.total=3",
+ ])
+ assert detect_format(m) == ImageFormat.CHUNKED_PARTS
+
+ def test_container_oci(self):
+ m = _make_manifest(OCI_IMAGE_CONFIG, [OCI_IMAGE_LAYER])
+ assert detect_format(m) == ImageFormat.CONTAINER
+
+ def test_container_docker(self):
+ m = _make_manifest(DOCKER_IMAGE_CONFIG, [DOCKER_IMAGE_LAYER])
+ assert detect_format(m) == ImageFormat.CONTAINER
+
+ def test_qemu_by_config(self):
+ m = _make_manifest(QEMU_CONFIG, [QEMU_DISK_GZIP])
+ assert detect_format(m) == ImageFormat.QEMU
+
+ def test_qemu_by_layer(self):
+ m = _make_manifest("application/json", [QEMU_DISK_GZIP])
+ assert detect_format(m) == ImageFormat.QEMU
+
+ def test_unknown(self):
+ m = _make_manifest("application/json", ["application/octet-stream"])
+ assert detect_format(m) == ImageFormat.UNKNOWN
+
+
+class TestDetectKind:
+ def test_vm_oci_layered(self):
+ m = _make_manifest(OCI_VM_CONFIG, [OCI_VM_DISK])
+ assert detect_kind(m) == "vm"
+
+ def test_vm_legacy(self):
+ m = _make_manifest("application/json", [LEGACY_DISK_CHUNK])
+ assert detect_kind(m) == "vm"
+
+ def test_vm_chunked(self):
+ m = _make_manifest("application/json", [
+ f"{OCI_IMAGE_LAYER};part.number=1;part.total=2",
+ ])
+ assert detect_kind(m) == "vm"
+
+ def test_vm_qemu(self):
+ m = _make_manifest(QEMU_CONFIG, [QEMU_DISK_GZIP])
+ assert detect_kind(m) == "vm"
+
+ def test_container(self):
+ m = _make_manifest(OCI_IMAGE_CONFIG, [OCI_IMAGE_LAYER])
+ assert detect_kind(m) == "container"
+
+
+class TestDetectOs:
+ def test_agoda_is_macos(self):
+ m = _make_manifest(OCI_VM_CONFIG, [OCI_VM_DISK])
+ assert detect_os(m) == "macos"
+
+ def test_annotation_linux(self):
+ m = _make_manifest("application/json", [], annotations={
+ "org.trycua.lume.os": "Linux",
+ })
+ assert detect_os(m) == "linux"
+
+ def test_no_os(self):
+ m = _make_manifest(OCI_IMAGE_CONFIG, [OCI_IMAGE_LAYER])
+ assert detect_os(m) is None
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+# get_layer_info
+# ═════════════════════════════════════════════════════════════════════════════
+
+class TestGetLayerInfo:
+ def test_part_from_annotations(self):
+ m = {
+ "layers": [{
+ "mediaType": OCI_VM_DISK,
+ "digest": "sha256:abc",
+ "size": 500_000_000,
+ "annotations": {
+ "org.trycua.lume.part.number": "3",
+ "org.trycua.lume.part.total": "10",
+ "org.opencontainers.image.title": "disk.img.003",
+ },
+ }],
+ }
+ info = get_layer_info(m)
+ assert len(info) == 1
+ assert info[0]["part_number"] == 3
+ assert info[0]["part_total"] == 10
+ assert info[0]["title"] == "disk.img.003"
+
+ def test_part_from_mediatype(self):
+ mt = f"{OCI_IMAGE_LAYER};part.number=7;part.total=164"
+ m = {"layers": [{"mediaType": mt, "digest": "sha256:def", "size": 100}]}
+ info = get_layer_info(m)
+ assert info[0]["part_number"] == 7
+ assert info[0]["part_total"] == 164
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+# Live registry tests (require network)
+# ═════════════════════════════════════════════════════════════════════════════
+
+oci_live = pytest.mark.skipif(
+ not pytest.importorskip("oras", reason="oras-py not installed"),
+ reason="oras-py not installed",
+)
+
+
+@oci_live
+class TestLiveRegistry:
+ """Fetch real manifests from ghcr.io. Requires network + oras."""
+
+ def test_macos_sparse_oci_layered(self):
+ from cua_sandbox.registry.manifest import get_manifest
+
+ manifest = get_manifest("ghcr.io/trycua/macos-sequoia-cua-sparse:latest-oci-layered")
+ assert detect_format(manifest) == ImageFormat.OCI_LAYERED
+ assert detect_kind(manifest) == "vm"
+ assert detect_os(manifest) == "macos"
+
+ info = get_layer_info(manifest)
+ assert len(info) > 0
+ # Should have disk layers with part numbers
+ disk_parts = [l for l in info if l["part_number"] is not None]
+ assert len(disk_parts) > 0
+
+ def test_macos_chunked_parts(self):
+ from cua_sandbox.registry.manifest import get_manifest
+
+ manifest = get_manifest("ghcr.io/trycua/macos-sequoia-cua:latest")
+ fmt = detect_format(manifest)
+ assert fmt in (ImageFormat.CHUNKED_PARTS, ImageFormat.OCI_LAYERED, ImageFormat.LEGACY_LZ4)
+ assert detect_kind(manifest) == "vm"
+
+ def test_ubuntu_container(self):
+ from cua_sandbox.registry.manifest import get_manifest
+
+ manifest = get_manifest("docker.io/trycua/cua-xfce:latest")
+ assert detect_format(manifest) == ImageFormat.CONTAINER
+ assert detect_kind(manifest) == "container"
diff --git a/libs/python/cua-sandbox/tests/test_runtime.py b/libs/python/cua-sandbox/tests/test_runtime.py
new file mode 100644
index 0000000000..e2282e8cd6
--- /dev/null
+++ b/libs/python/cua-sandbox/tests/test_runtime.py
@@ -0,0 +1,611 @@
+"""Integration tests — runtime scenarios.
+
+ pytest tests/test_runtime.py -v -s
+
+Skips automatically when the required runtime isn't available.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import subprocess
+from pathlib import Path
+
+import pytest
+from cua_sandbox import Image, Sandbox
+
+pytestmark = pytest.mark.asyncio
+
+IS_WINDOWS = platform.system() == "Windows"
+IS_MACOS = platform.system() == "Darwin"
+
+
+def _has_cua_api_key() -> bool:
+ return bool(os.environ.get("CUA_API_KEY"))
+
+
+# ── Helpers ──────────────────────────────────────────────────────────────────
+
+
+def _has_docker() -> bool:
+ try:
+ subprocess.run(["docker", "info"], capture_output=True, check=True, timeout=10)
+ return True
+ except (subprocess.SubprocessError, FileNotFoundError):
+ return False
+
+
+def _has_lume() -> bool:
+ try:
+ subprocess.run(["lume", "--version"], capture_output=True, check=True)
+ return True
+ except (subprocess.SubprocessError, FileNotFoundError):
+ return False
+
+
+def _has_hyperv() -> bool:
+ if not IS_WINDOWS:
+ return False
+ try:
+ from cua_sandbox.runtime.hyperv import _has_hyperv as check
+
+ return check()
+ except Exception:
+ return False
+
+
+def _has_qemu() -> bool:
+ """Check if QEMU is available (on PATH or portable)."""
+ try:
+ from cua_sandbox.runtime.qemu_installer import qemu_bin
+
+ qemu_bin("x86_64")
+ return True
+ except (RuntimeError, Exception):
+ return False
+
+
+def _has_android_image() -> bool:
+ """Check if an Android-x86 disk image is available for bare-metal QEMU."""
+ from pathlib import Path
+
+ storage = Path.home() / ".cua" / "cua-sandbox" / "qemu-storage" / "android-x86.qcow2"
+ return storage.exists()
+
+
+# ── 1. Linux container (Docker) ─────────────────────────────────────────────
+
+
[email protected](not _has_docker(), reason="Docker not available")
+async def test_linux_container():
+ from cua_sandbox.runtime import DockerRuntime
+
+ async with Sandbox.ephemeral(
+ Image.linux("ubuntu", "24.04"),
+ local=True,
+ runtime=DockerRuntime(api_port=18000, vnc_port=16901, ephemeral=True),
+ name="cua-test-linux-container",
+ ) as sb:
+ result = await sb.shell.run("cat /etc/os-release")
+ assert result.success
+ assert "ubuntu" in result.stdout.lower()
+
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+
+
+# ── 2. Linux VM (QEMU-in-Docker) ────────────────────────────────────────────
+
+
[email protected](not _has_docker(), reason="Docker not available")
+async def test_linux_vm():
+ from cua_sandbox.runtime import QEMURuntime
+
+ async with Sandbox.ephemeral(
+ Image.linux("ubuntu", "24.04"),
+ local=True,
+ runtime=QEMURuntime(mode="docker", api_port=18001, vnc_port=18006, ephemeral=True),
+ name="cua-test-linux-vm",
+ ) as sb:
+ result = await sb.shell.run("uname -a")
+ assert result.success
+ assert "Linux" in result.stdout
+
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+
+
+# ── 3. Windows VM (bare-metal QEMU on Windows host) ─────────────────────────
+
+
[email protected](not IS_WINDOWS, reason="Windows host only")
[email protected](not _has_qemu(), reason="QEMU not available")
+async def test_windows_vm():
+ from cua_sandbox.runtime import QEMURuntime
+
+ async with Sandbox.ephemeral(
+ Image.windows("11"),
+ local=True,
+ runtime=QEMURuntime(mode="bare-metal", api_port=18002),
+ name="cua-test-windows-vm",
+ ) as sb:
+ result = await sb.shell.run("ver")
+ assert result.success or "Windows" in result.stdout
+
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+
+
+# ── 3b. Windows VM (Hyper-V) ────────────────────────────────────────────────
+
+
[email protected](not _has_hyperv(), reason="Hyper-V not available")
+async def test_windows_hyperv():
+ from cua_sandbox.runtime import HyperVRuntime
+
+ async with Sandbox.ephemeral(
+ Image.windows("11"),
+ local=True,
+ runtime=HyperVRuntime(api_port=18003),
+ name="cua-test-hyperv",
+ ) as sb:
+ result = await sb.shell.run("ver")
+ assert result.success or "Windows" in result.stdout
+
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+
+
+# ── 4. macOS VM (Lume) ──────────────────────────────────────────────────────
+
+
[email protected](not IS_MACOS or not _has_lume(), reason="Lume only on macOS")
+async def test_macos_vm():
+ from cua_sandbox.runtime import LumeRuntime
+
+ async with Sandbox.ephemeral(
+ Image.macos("26"),
+ local=True,
+ runtime=LumeRuntime(),
+ name="cua-test-macos-vm",
+ ) as sb:
+ result = await sb.shell.run("sw_vers")
+ assert result.success
+ assert "macOS" in result.stdout or "Mac" in result.stdout
+
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+
+
+# ── 5. Android VM (bare-metal QEMU) ──────────────────────────────────────────
+
+
+def _has_android_iso() -> bool:
+ """Check if an Android-x86 ISO is available in ~/Downloads."""
+ from pathlib import Path
+
+ return any(Path.home().glob("Downloads/android-x86*.iso"))
+
+
+def _get_android_iso() -> str:
+ from pathlib import Path
+
+ isos = sorted(Path.home().glob("Downloads/android-x86*.iso"))
+ return str(isos[0]) if isos else ""
+
+
[email protected](not _has_qemu(), reason="QEMU not available")
+ not _has_android_image(),
+ reason="Android-x86 qcow2 not available at ~/.cua/cua-sandbox/qemu-storage/android-x86.qcow2",
+)
+async def test_android_vm_baremetal():
+ """Test Android VM via bare-metal QEMU with a pre-built qcow2."""
+ from pathlib import Path
+
+ from cua_sandbox.runtime import QEMURuntime
+
+ android_disk = str(Path.home() / ".cua" / "cua-sandbox" / "qemu-storage" / "android-x86.qcow2")
+ async with Sandbox.ephemeral(
+ Image.from_file(android_disk, os_type="android", kind="vm"),
+ local=True,
+ runtime=QEMURuntime(
+ mode="bare-metal", api_port=18010, vnc_display=10, memory_mb=4096, cpu_count=4
+ ),
+ name="cua-test-android-vm",
+ ) as sb:
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+ assert len(screenshot) > 1000
+
+
[email protected](not _has_qemu(), reason="QEMU not available")
[email protected](not _has_android_iso(), reason="No android-x86*.iso in ~/Downloads")
+async def test_android_vm_from_iso():
+ """Test Android VM booted from an ISO file via bare-metal QEMU.
+
+ The runtime auto-creates a qcow2 disk and attaches the ISO as CD-ROM.
+ Uses QMP transport (no computer-server required).
+ """
+ from cua_sandbox.runtime import QEMURuntime
+
+ iso_path = _get_android_iso()
+ async with Sandbox.ephemeral(
+ Image.from_file(iso_path, os_type="android", kind="vm"),
+ local=True,
+ runtime=QEMURuntime(
+ mode="bare-metal",
+ api_port=18030,
+ vnc_display=30,
+ qmp_port=4460,
+ memory_mb=2048,
+ cpu_count=2,
+ ),
+ name="cua-test-android-iso3",
+ ) as sb:
+ # Wait for boot to progress past GRUB (Enter keys are sent during start())
+ import asyncio
+
+ await asyncio.sleep(15)
+
+ # With QMP transport, we can take screenshots even without computer-server
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+ assert len(screenshot) > 100
+
+ # Save screenshot for inspection
+ with open("/tmp/android-boot-screenshot.png", "wb") as f:
+ f.write(screenshot)
+
+
+# ── 5b. Android VM (QEMU-in-Docker) ──────────────────────────────────────────
+
+
[email protected](not _has_docker(), reason="Docker not available")
+async def test_android_vm_docker():
+ """Test Android VM via QEMU inside Docker."""
+ from cua_sandbox.runtime import QEMURuntime
+
+ async with Sandbox.ephemeral(
+ Image.android("14"),
+ local=True,
+ runtime=QEMURuntime(mode="docker", api_port=18011, vnc_port=18080, ephemeral=True),
+ name="cua-test-android-docker",
+ ) as sb:
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+ assert len(screenshot) > 1000
+
+
+# ── 6. QEMU bare-metal error on missing binary ───────────────────────────────
+
+
+def _has_osworld_image() -> bool:
+ """Check if the OSWorld Ubuntu qcow2 is available in the image cache."""
+ cache = Path.home() / ".cua" / "cua-sandbox" / "image-cache"
+ return any(cache.rglob("Ubuntu.qcow2")) if cache.exists() else False
+
+
[email protected](not _has_qemu(), reason="QEMU not available")
[email protected](not _has_osworld_image(), reason="OSWorld Ubuntu.qcow2 not in image cache")
+async def test_osworld_ubuntu_vm():
+ """Test OSWorld Ubuntu VM via bare-metal QEMU with OSWorld transport."""
+ from cua_sandbox.runtime import QEMURuntime
+
+ async with Sandbox.ephemeral(
+ Image.from_file(
+ "https://huggingface.co/datasets/xlangai/ubuntu_osworld/resolve/main/Ubuntu.qcow2.zip",
+ os_type="linux",
+ agent_type="osworld",
+ ),
+ local=True,
+ runtime=QEMURuntime(
+ mode="bare-metal", api_port=18020, vnc_display=20, memory_mb=4096, cpu_count=4
+ ),
+ name="cua-test-osworld",
+ ) as sb:
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+
+ w, h = await sb.get_dimensions()
+ assert w == 1920 and h == 1080
+
+
+# ── 7. Android Emulator (SDK) ────────────────────────────────────────────────
+
+
+def _has_android_sdk() -> bool:
+ """Check if Android SDK emulator is available."""
+ try:
+ from cua_sandbox.runtime.android_emulator import _find_bin, _sdk_path
+
+ sdk = _sdk_path()
+ _find_bin(sdk, "emulator")
+ _find_bin(sdk, "adb")
+ return True
+ except (FileNotFoundError, Exception):
+ return False
+
+
[email protected](not _has_android_sdk(), reason="Android SDK not available")
+async def test_android_emulator():
+ """Test Android emulator boots to homescreen."""
+ from cua_sandbox.runtime import AndroidEmulatorRuntime
+
+ async with Sandbox.ephemeral(
+ Image.android("14"),
+ local=True,
+ runtime=AndroidEmulatorRuntime(memory_mb=4096, cpu_count=4, adb_port=5559),
+ name="cua-test-android-sdk",
+ ) as sb:
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+ assert len(screenshot) > 10000
+
+
[email protected](not _has_android_sdk(), reason="Android SDK not available")
+async def test_android_emulator_apk_install():
+ """Test Android emulator with F-Droid APK installed from URL."""
+ from cua_sandbox.runtime import AndroidEmulatorRuntime
+
+ img = Image.android("14").apk_install("https://f-droid.org/F-Droid.apk")
+ async with Sandbox.ephemeral(
+ img,
+ local=True,
+ runtime=AndroidEmulatorRuntime(memory_mb=4096, cpu_count=4, adb_port=5561),
+ name="cua-test-android-apk",
+ ) as sb:
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+
+ # Verify F-Droid is installed
+ result = await sb._transport.send("shell", command="pm list packages | grep fdroid")
+ assert "org.fdroid.fdroid" in result["output"]
+
+
+# ── 8. Tart (Apple VZ) ────────────────────────────────────────────────────────
+
+
+def _has_tart() -> bool:
+ import shutil
+
+ return shutil.which("tart") is not None
+
+
[email protected](not IS_MACOS, reason="Tart only on macOS")
[email protected](not _has_tart(), reason="Tart CLI not available")
+async def test_tart_ubuntu():
+ """Test Ubuntu VM via Tart (Apple VZ)."""
+ from cua_sandbox.runtime import TartRuntime
+
+ async with Sandbox.ephemeral(
+ Image.from_registry("ghcr.io/cirruslabs/ubuntu:latest"),
+ local=True,
+ runtime=TartRuntime(ephemeral=True, display="1024x768"),
+ name="cua-test-tart-ubuntu",
+ ) as sb:
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+ assert len(screenshot) > 1000
+
+ result = await sb.shell.run("uname -a")
+ assert result.success
+ assert "Linux" in result.stdout
+
+
[email protected](not IS_MACOS, reason="Tart only on macOS")
[email protected](not _has_tart(), reason="Tart CLI not available")
+async def test_tart_macos_tahoe():
+ """Test macOS Tahoe VM via Tart (Apple VZ)."""
+ from cua_sandbox.runtime import TartRuntime
+
+ async with Sandbox.ephemeral(
+ Image.from_registry("ghcr.io/cirruslabs/macos-tahoe-base:latest"),
+ local=True,
+ runtime=TartRuntime(ephemeral=True),
+ name="cua-test-tart-tahoe",
+ ) as sb:
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+ assert len(screenshot) > 1000
+
+
[email protected](not IS_MACOS, reason="Tart only on macOS")
[email protected](not _has_tart(), reason="Tart CLI not available")
+async def test_tart_macos_sequoia_cua():
+ """Test CUA macOS Sequoia sparse image via Tart."""
+ from cua_sandbox.runtime import TartRuntime
+
+ async with Sandbox.ephemeral(
+ Image.from_registry("ghcr.io/trycua/macos-sequoia-cua-sparse:latest-oci-layered"),
+ local=True,
+ runtime=TartRuntime(ephemeral=True),
+ name="cua-test-tart-sequoia",
+ ) as sb:
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+ assert len(screenshot) > 1000
+
+
[email protected](not IS_MACOS or not _has_lume(), reason="Lume only on macOS")
+async def test_lume_macos_tahoe_cua():
+ """Test CUA macOS Tahoe image via Lume from ghcr.io/trycua/macos-tahoe-cua:latest."""
+ from cua_sandbox.runtime import LumeRuntime
+
+ async with Sandbox.ephemeral(
+ Image.from_registry("ghcr.io/trycua/macos-tahoe-cua:latest"),
+ local=True,
+ runtime=LumeRuntime(),
+ name="cua-test-lume-tahoe",
+ ) as sb:
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+ assert len(screenshot) > 1000
+
+
+
+# ── 9. QEMU bare-metal error on missing binary ───────────────────────────────
+
+
+def test_qemu_baremetal_missing_binary_error():
+ """When QEMU isn't installed, bare-metal runtime should give a helpful error."""
+ import shutil
+
+ if shutil.which("qemu-system-x86_64"):
+ pytest.skip("QEMU is installed — cannot test missing-binary error")
+
+ with pytest.raises(RuntimeError, match="brew install qemu|not found"):
+ from cua_sandbox.runtime.qemu_installer import qemu_bin
+
+ qemu_bin("x86_64")
+
+
+# ── 10. Auto-runtime (local=True, no explicit runtime) ───────────────────────
+
+
[email protected](not _has_docker(), reason="Docker not available")
+async def test_auto_runtime_linux_container():
+ """local=True with no runtime auto-selects DockerRuntime for linux container images."""
+ async with Sandbox.ephemeral(
+ Image.linux("ubuntu", "24.04"), # kind="container" by default
+ local=True,
+ name="cua-test-auto-linux-container",
+ ) as sb:
+ result = await sb.shell.run("uname -s")
+ assert result.success
+ assert "Linux" in result.stdout
+
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+
+
[email protected](not _has_docker(), reason="Docker not available")
+async def test_auto_runtime_linux_vm():
+ """local=True with no runtime auto-selects QEMURuntime(docker) for linux vm images."""
+ async with Sandbox.ephemeral(
+ Image.linux("ubuntu", "24.04", kind="vm"),
+ local=True,
+ name="cua-test-auto-linux-vm",
+ ) as sb:
+ result = await sb.shell.run("uname -s")
+ assert result.success
+ assert "Linux" in result.stdout
+
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+
+
[email protected](not IS_MACOS or not _has_lume(), reason="Lume only on macOS")
+async def test_auto_runtime_macos():
+ """local=True with no runtime auto-selects LumeRuntime for macOS images."""
+ async with Sandbox.ephemeral(
+ Image.macos("26"),
+ local=True,
+ name="cua-test-auto-macos",
+ ) as sb:
+ result = await sb.shell.run("sw_vers")
+ assert result.success
+ assert "macOS" in result.stdout or "Mac" in result.stdout
+
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+
+
[email protected](not _has_android_sdk(), reason="Android SDK not available")
+async def test_auto_runtime_android():
+ """local=True with no runtime auto-selects AndroidEmulatorRuntime for android images."""
+ async with Sandbox.ephemeral(
+ Image.android("14"),
+ local=True,
+ name="cua-test-auto-android",
+ ) as sb:
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+ assert len(screenshot) > 10000
+
+
[email protected](not IS_WINDOWS, reason="Windows host only")
[email protected](not _has_qemu(), reason="QEMU not available")
+async def test_auto_runtime_windows():
+ """local=True with no runtime auto-selects HyperV or QEMU for Windows images."""
+ async with Sandbox.ephemeral(
+ Image.windows("11"),
+ local=True,
+ name="cua-test-auto-windows",
+ ) as sb:
+ result = await sb.shell.run("ver")
+ assert result.success or "Windows" in result.stdout
+
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+
+
+# ── 11. Cloud sandboxes (local=False) ────────────────────────────────────────
+
+
[email protected](not _has_cua_api_key(), reason="CUA_API_KEY not set")
+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
+ assert "Linux" in result.stdout
+
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+
+
[email protected](not _has_cua_api_key(), reason="CUA_API_KEY not set")
+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"
+ assert len(screenshot) > 1000
+
+
+# ── 12. Sandbox.create (persistent) ─────────────────────────────────────────
+
+
[email protected](not _has_docker(), reason="Docker not available")
+async def test_create_persistent_linux():
+ """Sandbox.create provisions a persistent sandbox that survives disconnect."""
+ from cua_sandbox.runtime import DockerRuntime
+
+ sb = await Sandbox.create(
+ Image.linux("ubuntu", "24.04"),
+ local=True,
+ runtime=DockerRuntime(api_port=18090, vnc_port=18091, ephemeral=True),
+ name="cua-test-create-linux",
+ )
+ try:
+ result = await sb.shell.run("echo persistent")
+ assert result.success
+ assert "persistent" in result.stdout
+
+ screenshot = await sb.screenshot()
+ assert screenshot[:4] == b"\x89PNG"
+ finally:
+ await sb.disconnect()
+
+
[email protected](not _has_cua_api_key(), reason="CUA_API_KEY not set")
+async def test_create_persistent_cloud_linux():
+ """Sandbox.create provisions a persistent cloud sandbox."""
+ sb = await Sandbox.create(
+ Image.linux("ubuntu", "24.04"),
+ name="cua-test-create-cloud-linux",
+ )
+ try:
+ result = await sb.shell.run("echo persistent")
+ assert result.success
+ assert "persistent" in result.stdout
+ finally:
+ await sb.disconnect()
diff --git a/libs/python/cua-sandbox/tests/test_transport_http.py b/libs/python/cua-sandbox/tests/test_transport_http.py
new file mode 100644
index 0000000000..048d71d592
--- /dev/null
+++ b/libs/python/cua-sandbox/tests/test_transport_http.py
@@ -0,0 +1,64 @@
+"""Integration tests specifically for the HTTP transport against a running computer-server.
+
+Skipped unless CUA_TEST_HTTP_URL is set.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+pytestmark = pytest.mark.asyncio
+
+
+class TestHTTPTransport:
+ async def test_screenshot(self, http_transport):
+ data = await http_transport.screenshot()
+ assert isinstance(data, bytes)
+ assert data[:4] == b"\x89PNG"
+
+ async def test_screen_size(self, http_transport):
+ size = await http_transport.get_screen_size()
+ assert size["width"] > 0
+ assert size["height"] > 0
+
+ async def test_get_environment(self, http_transport):
+ env = await http_transport.get_environment()
+ assert env in ("windows", "mac", "linux", "browser")
+
+ async def test_send_click(self, http_transport):
+ result = await http_transport.send("left_click", x=100, y=100)
+ # Should not raise
+
+ async def test_send_type(self, http_transport):
+ result = await http_transport.send("type_text", text="hello")
+
+ async def test_send_get_screen_size(self, http_transport):
+ result = await http_transport.send("get_screen_size")
+ assert "width" in result or isinstance(result, dict)
+
+
+class TestHTTPSandboxFullInterface:
+ """Same interface tests as the main suite, but explicitly via HTTP sandbox."""
+
+ async def test_screenshot(self, http_sandbox):
+ data = await http_sandbox.screenshot()
+ assert data[:4] == b"\x89PNG"
+
+ async def test_mouse_click(self, http_sandbox):
+ await http_sandbox.mouse.click(100, 100)
+
+ async def test_keyboard_type(self, http_sandbox):
+ await http_sandbox.keyboard.type("http-test")
+
+ async def test_clipboard(self, http_sandbox):
+ await http_sandbox.clipboard.set("http-clip")
+ val = await http_sandbox.clipboard.get()
+ assert val == "http-clip"
+
+ async def test_shell(self, http_sandbox):
+ result = await http_sandbox.shell.run("echo http-shell")
+ assert result.success
+
+ async def test_window_title(self, http_sandbox):
+ title = await http_sandbox.window.get_active_title()
+ assert isinstance(title, str)
diff --git a/libs/python/cua-sandbox/uv.lock b/libs/python/cua-sandbox/uv.lock
new file mode 100644
index 0000000000..206f25d72f
--- /dev/null
+++ b/libs/python/cua-sandbox/uv.lock
@@ -0,0 +1,3695 @@
+version = 1
+revision = 2
+requires-python = ">=3.11, <3.14"
+
+[[package]]
+name = "anyio"
+version = "4.12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "idna" },
+ { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/96/f0/5eb65b2bb0d09ac6776f2eb54adee6abe8228ea05b20a5ad0e4945de8aac/anyio-4.12.1.tar.gz", hash = "sha256:41cfcc3a4c85d3f05c932da7c26d0201ac36f72abd4435ba90d0464a3ffed703", size = 228685, upload-time = "2026-01-06T11:45:21.246Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/38/0e/27be9fdef66e72d64c0cdc3cc2823101b80585f8119b5c112c2e8f5f7dab/anyio-4.12.1-py3-none-any.whl", hash = "sha256:d405828884fc140aa80a3c667b8beed277f1dfedec42ba031bd6ac3db606ab6c", size = 113592, upload-time = "2026-01-06T11:45:19.497Z" },
+]
+
+[[package]]
+name = "attrs"
+version = "25.4.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/6b/5c/685e6633917e101e5dcb62b9dd76946cbb57c26e133bae9e0cd36033c0a9/attrs-25.4.0.tar.gz", hash = "sha256:16d5969b87f0859ef33a48b35d55ac1be6e42ae49d5e853b597db70c35c57e11", size = 934251, upload-time = "2025-10-06T13:54:44.725Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/3a/2a/7cc015f5b9f5db42b7d48157e23356022889fc354a2813c15934b7cb5c0e/attrs-25.4.0-py3-none-any.whl", hash = "sha256:adcf7e2a1fb3b36ac48d97835bb6d8ade15b8dcce26aba8bf1d14847b57a3373", size = 67615, upload-time = "2025-10-06T13:54:43.17Z" },
+]
+
+[[package]]
+name = "automat"
+version = "25.4.16"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e3/0f/d40bbe294bbf004d436a8bcbcfaadca8b5140d39ad0ad3d73d1a8ba15f14/automat-25.4.16.tar.gz", hash = "sha256:0017591a5477066e90d26b0e696ddc143baafd87b588cfac8100bc6be9634de0", size = 129977, upload-time = "2025-04-16T20:12:16.002Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/02/ff/1175b0b7371e46244032d43a56862d0af455823b5280a50c63d99cc50f18/automat-25.4.16-py3-none-any.whl", hash = "sha256:04e9bce696a8d5671ee698005af6e5a9fa15354140a87f4870744604dcdd3ba1", size = 42842, upload-time = "2025-04-16T20:12:14.447Z" },
+]
+
+[[package]]
+name = "bcrypt"
+version = "5.0.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d4/36/3329e2518d70ad8e2e5817d5a4cac6bba05a47767ec416c7d020a965f408/bcrypt-5.0.0.tar.gz", hash = "sha256:f748f7c2d6fd375cc93d3fba7ef4a9e3a092421b8dbf34d8d4dc06be9492dfdd", size = 25386, upload-time = "2025-09-25T19:50:47.829Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/13/85/3e65e01985fddf25b64ca67275bb5bdb4040bd1a53b66d355c6c37c8a680/bcrypt-5.0.0-cp313-cp313t-macosx_10_12_universal2.whl", hash = "sha256:f3c08197f3039bec79cee59a606d62b96b16669cff3949f21e74796b6e3cd2be", size = 481806, upload-time = "2025-09-25T19:49:05.102Z" },
+ { url = "https://files.pythonhosted.org/packages/44/dc/01eb79f12b177017a726cbf78330eb0eb442fae0e7b3dfd84ea2849552f3/bcrypt-5.0.0-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:200af71bc25f22006f4069060c88ed36f8aa4ff7f53e67ff04d2ab3f1e79a5b2", size = 268626, upload-time = "2025-09-25T19:49:06.723Z" },
+ { url = "https://files.pythonhosted.org/packages/8c/cf/e82388ad5959c40d6afd94fb4743cc077129d45b952d46bdc3180310e2df/bcrypt-5.0.0-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:baade0a5657654c2984468efb7d6c110db87ea63ef5a4b54732e7e337253e44f", size = 271853, upload-time = "2025-09-25T19:49:08.028Z" },
+ { url = "https://files.pythonhosted.org/packages/ec/86/7134b9dae7cf0efa85671651341f6afa695857fae172615e960fb6a466fa/bcrypt-5.0.0-cp313-cp313t-manylinux_2_28_aarch64.whl", hash = "sha256:c58b56cdfb03202b3bcc9fd8daee8e8e9b6d7e3163aa97c631dfcfcc24d36c86", size = 269793, upload-time = "2025-09-25T19:49:09.727Z" },
+ { url = "https://files.pythonhosted.org/packages/cc/82/6296688ac1b9e503d034e7d0614d56e80c5d1a08402ff856a4549cb59207/bcrypt-5.0.0-cp313-cp313t-manylinux_2_28_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:4bfd2a34de661f34d0bda43c3e4e79df586e4716ef401fe31ea39d69d581ef23", size = 289930, upload-time = "2025-09-25T19:49:11.204Z" },
+ { url = "https://files.pythonhosted.org/packages/d1/18/884a44aa47f2a3b88dd09bc05a1e40b57878ecd111d17e5bba6f09f8bb77/bcrypt-5.0.0-cp313-cp313t-manylinux_2_28_x86_64.whl", hash = "sha256:ed2e1365e31fc73f1825fa830f1c8f8917ca1b3ca6185773b349c20fd606cec2", size = 272194, upload-time = "2025-09-25T19:49:12.524Z" },
+ { url = "https://files.pythonhosted.org/packages/0e/8f/371a3ab33c6982070b674f1788e05b656cfbf5685894acbfef0c65483a59/bcrypt-5.0.0-cp313-cp313t-manylinux_2_34_aarch64.whl", hash = "sha256:83e787d7a84dbbfba6f250dd7a5efd689e935f03dd83b0f919d39349e1f23f83", size = 269381, upload-time = "2025-09-25T19:49:14.308Z" },
+ { url = "https://files.pythonhosted.org/packages/b1/34/7e4e6abb7a8778db6422e88b1f06eb07c47682313997ee8a8f9352e5a6f1/bcrypt-5.0.0-cp313-cp313t-manylinux_2_34_x86_64.whl", hash = "sha256:137c5156524328a24b9fac1cb5db0ba618bc97d11970b39184c1d87dc4bf1746", size = 271750, upload-time = "2025-09-25T19:49:15.584Z" },
+ { url = "https://files.pythonhosted.org/packages/c0/1b/54f416be2499bd72123c70d98d36c6cd61a4e33d9b89562c22481c81bb30/bcrypt-5.0.0-cp313-cp313t-musllinux_1_1_aarch64.whl", hash = "sha256:38cac74101777a6a7d3b3e3cfefa57089b5ada650dce2baf0cbdd9d65db22a9e", size = 303757, upload-time = "2025-09-25T19:49:17.244Z" },
+ { url = "https://files.pythonhosted.org/packages/13/62/062c24c7bcf9d2826a1a843d0d605c65a755bc98002923d01fd61270705a/bcrypt-5.0.0-cp313-cp313t-musllinux_1_1_x86_64.whl", hash = "sha256:d8d65b564ec849643d9f7ea05c6d9f0cd7ca23bdd4ac0c2dbef1104ab504543d", size = 306740, upload-time = "2025-09-25T19:49:18.693Z" },
+ { url = "https://files.pythonhosted.org/packages/d5/c8/1fdbfc8c0f20875b6b4020f3c7dc447b8de60aa0be5faaf009d24242aec9/bcrypt-5.0.0-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:741449132f64b3524e95cd30e5cd3343006ce146088f074f31ab26b94e6c75ba", size = 334197, upload-time = "2025-09-25T19:49:20.523Z" },
+ { url = "https://files.pythonhosted.org/packages/a6/c1/8b84545382d75bef226fbc6588af0f7b7d095f7cd6a670b42a86243183cd/bcrypt-5.0.0-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:212139484ab3207b1f0c00633d3be92fef3c5f0af17cad155679d03ff2ee1e41", size = 352974, upload-time = "2025-09-25T19:49:22.254Z" },
+ { url = "https://files.pythonhosted.org/packages/10/a6/ffb49d4254ed085e62e3e5dd05982b4393e32fe1e49bb1130186617c29cd/bcrypt-5.0.0-cp313-cp313t-win32.whl", hash = "sha256:9d52ed507c2488eddd6a95bccee4e808d3234fa78dd370e24bac65a21212b861", size = 148498, upload-time = "2025-09-25T19:49:24.134Z" },
+ { url = "https://files.pythonhosted.org/packages/48/a9/259559edc85258b6d5fc5471a62a3299a6aa37a6611a169756bf4689323c/bcrypt-5.0.0-cp313-cp313t-win_amd64.whl", hash = "sha256:f6984a24db30548fd39a44360532898c33528b74aedf81c26cf29c51ee47057e", size = 145853, upload-time = "2025-09-25T19:49:25.702Z" },
+ { url = "https://files.pythonhosted.org/packages/2d/df/9714173403c7e8b245acf8e4be8876aac64a209d1b392af457c79e60492e/bcrypt-5.0.0-cp313-cp313t-win_arm64.whl", hash = "sha256:9fffdb387abe6aa775af36ef16f55e318dcda4194ddbf82007a6f21da29de8f5", size = 139626, upload-time = "2025-09-25T19:49:26.928Z" },
+ { url = "https://files.pythonhosted.org/packages/84/29/6237f151fbfe295fe3e074ecc6d44228faa1e842a81f6d34a02937ee1736/bcrypt-5.0.0-cp38-abi3-macosx_10_12_universal2.whl", hash = "sha256:fc746432b951e92b58317af8e0ca746efe93e66555f1b40888865ef5bf56446b", size = 494553, upload-time = "2025-09-25T19:49:49.006Z" },
+ { url = "https://files.pythonhosted.org/packages/45/b6/4c1205dde5e464ea3bd88e8742e19f899c16fa8916fb8510a851fae985b5/bcrypt-5.0.0-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:c2388ca94ffee269b6038d48747f4ce8df0ffbea43f31abfa18ac72f0218effb", size = 275009, upload-time = "2025-09-25T19:49:50.581Z" },
+ { url = "https://files.pythonhosted.org/packages/3b/71/427945e6ead72ccffe77894b2655b695ccf14ae1866cd977e185d606dd2f/bcrypt-5.0.0-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:560ddb6ec730386e7b3b26b8b4c88197aaed924430e7b74666a586ac997249ef", size = 278029, upload-time = "2025-09-25T19:49:52.533Z" },
+ { url = "https://files.pythonhosted.org/packages/17/72/c344825e3b83c5389a369c8a8e58ffe1480b8a699f46c127c34580c4666b/bcrypt-5.0.0-cp38-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:d79e5c65dcc9af213594d6f7f1fa2c98ad3fc10431e7aa53c176b441943efbdd", size = 275907, upload-time = "2025-09-25T19:49:54.709Z" },
+ { url = "https://files.pythonhosted.org/packages/0b/7e/d4e47d2df1641a36d1212e5c0514f5291e1a956a7749f1e595c07a972038/bcrypt-5.0.0-cp38-abi3-manylinux_2_28_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:2b732e7d388fa22d48920baa267ba5d97cca38070b69c0e2d37087b381c681fd", size = 296500, upload-time = "2025-09-25T19:49:56.013Z" },
+ { url = "https://files.pythonhosted.org/packages/0f/c3/0ae57a68be2039287ec28bc463b82e4b8dc23f9d12c0be331f4782e19108/bcrypt-5.0.0-cp38-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:0c8e093ea2532601a6f686edbc2c6b2ec24131ff5c52f7610dd64fa4553b5464", size = 278412, upload-time = "2025-09-25T19:49:57.356Z" },
+ { url = "https://files.pythonhosted.org/packages/45/2b/77424511adb11e6a99e3a00dcc7745034bee89036ad7d7e255a7e47be7d8/bcrypt-5.0.0-cp38-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:5b1589f4839a0899c146e8892efe320c0fa096568abd9b95593efac50a87cb75", size = 275486, upload-time = "2025-09-25T19:49:59.116Z" },
+ { url = "https://files.pythonhosted.org/packages/43/0a/405c753f6158e0f3f14b00b462d8bca31296f7ecfc8fc8bc7919c0c7d73a/bcrypt-5.0.0-cp38-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:89042e61b5e808b67daf24a434d89bab164d4de1746b37a8d173b6b14f3db9ff", size = 277940, upload-time = "2025-09-25T19:50:00.869Z" },
+ { url = "https://files.pythonhosted.org/packages/62/83/b3efc285d4aadc1fa83db385ec64dcfa1707e890eb42f03b127d66ac1b7b/bcrypt-5.0.0-cp38-abi3-musllinux_1_1_aarch64.whl", hash = "sha256:e3cf5b2560c7b5a142286f69bde914494b6d8f901aaa71e453078388a50881c4", size = 310776, upload-time = "2025-09-25T19:50:02.393Z" },
+ { url = "https://files.pythonhosted.org/packages/95/7d/47ee337dacecde6d234890fe929936cb03ebc4c3a7460854bbd9c97780b8/bcrypt-5.0.0-cp38-abi3-musllinux_1_1_x86_64.whl", hash = "sha256:f632fd56fc4e61564f78b46a2269153122db34988e78b6be8b32d28507b7eaeb", size = 312922, upload-time = "2025-09-25T19:50:04.232Z" },
+ { url = "https://files.pythonhosted.org/packages/d6/3a/43d494dfb728f55f4e1cf8fd435d50c16a2d75493225b54c8d06122523c6/bcrypt-5.0.0-cp38-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:801cad5ccb6b87d1b430f183269b94c24f248dddbbc5c1f78b6ed231743e001c", size = 341367, upload-time = "2025-09-25T19:50:05.559Z" },
+ { url = "https://files.pythonhosted.org/packages/55/ab/a0727a4547e383e2e22a630e0f908113db37904f58719dc48d4622139b5c/bcrypt-5.0.0-cp38-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:3cf67a804fc66fc217e6914a5635000259fbbbb12e78a99488e4d5ba445a71eb", size = 359187, upload-time = "2025-09-25T19:50:06.916Z" },
+ { url = "https://files.pythonhosted.org/packages/1b/bb/461f352fdca663524b4643d8b09e8435b4990f17fbf4fea6bc2a90aa0cc7/bcrypt-5.0.0-cp38-abi3-win32.whl", hash = "sha256:3abeb543874b2c0524ff40c57a4e14e5d3a66ff33fb423529c88f180fd756538", size = 153752, upload-time = "2025-09-25T19:50:08.515Z" },
+ { url = "https://files.pythonhosted.org/packages/41/aa/4190e60921927b7056820291f56fc57d00d04757c8b316b2d3c0d1d6da2c/bcrypt-5.0.0-cp38-abi3-win_amd64.whl", hash = "sha256:35a77ec55b541e5e583eb3436ffbbf53b0ffa1fa16ca6782279daf95d146dcd9", size = 150881, upload-time = "2025-09-25T19:50:09.742Z" },
+ { url = "https://files.pythonhosted.org/packages/54/12/cd77221719d0b39ac0b55dbd39358db1cd1246e0282e104366ebbfb8266a/bcrypt-5.0.0-cp38-abi3-win_arm64.whl", hash = "sha256:cde08734f12c6a4e28dc6755cd11d3bdfea608d93d958fffbe95a7026ebe4980", size = 144931, upload-time = "2025-09-25T19:50:11.016Z" },
+ { url = "https://files.pythonhosted.org/packages/5d/ba/2af136406e1c3839aea9ecadc2f6be2bcd1eff255bd451dd39bcf302c47a/bcrypt-5.0.0-cp39-abi3-macosx_10_12_universal2.whl", hash = "sha256:0c418ca99fd47e9c59a301744d63328f17798b5947b0f791e9af3c1c499c2d0a", size = 495313, upload-time = "2025-09-25T19:50:12.309Z" },
+ { url = "https://files.pythonhosted.org/packages/ac/ee/2f4985dbad090ace5ad1f7dd8ff94477fe089b5fab2040bd784a3d5f187b/bcrypt-5.0.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:ddb4e1500f6efdd402218ffe34d040a1196c072e07929b9820f363a1fd1f4191", size = 275290, upload-time = "2025-09-25T19:50:13.673Z" },
+ { url = "https://files.pythonhosted.org/packages/e4/6e/b77ade812672d15cf50842e167eead80ac3514f3beacac8902915417f8b7/bcrypt-5.0.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:7aeef54b60ceddb6f30ee3db090351ecf0d40ec6e2abf41430997407a46d2254", size = 278253, upload-time = "2025-09-25T19:50:15.089Z" },
+ { url = "https://files.pythonhosted.org/packages/36/c4/ed00ed32f1040f7990dac7115f82273e3c03da1e1a1587a778d8cea496d8/bcrypt-5.0.0-cp39-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:f0ce778135f60799d89c9693b9b398819d15f1921ba15fe719acb3178215a7db", size = 276084, upload-time = "2025-09-25T19:50:16.699Z" },
+ { url = "https://files.pythonhosted.org/packages/e7/c4/fa6e16145e145e87f1fa351bbd54b429354fd72145cd3d4e0c5157cf4c70/bcrypt-5.0.0-cp39-abi3-manylinux_2_28_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:a71f70ee269671460b37a449f5ff26982a6f2ba493b3eabdd687b4bf35f875ac", size = 297185, upload-time = "2025-09-25T19:50:18.525Z" },
+ { url = "https://files.pythonhosted.org/packages/24/b4/11f8a31d8b67cca3371e046db49baa7c0594d71eb40ac8121e2fc0888db0/bcrypt-5.0.0-cp39-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:f8429e1c410b4073944f03bd778a9e066e7fad723564a52ff91841d278dfc822", size = 278656, upload-time = "2025-09-25T19:50:19.809Z" },
+ { url = "https://files.pythonhosted.org/packages/ac/31/79f11865f8078e192847d2cb526e3fa27c200933c982c5b2869720fa5fce/bcrypt-5.0.0-cp39-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:edfcdcedd0d0f05850c52ba3127b1fce70b9f89e0fe5ff16517df7e81fa3cbb8", size = 275662, upload-time = "2025-09-25T19:50:21.567Z" },
+ { url = "https://files.pythonhosted.org/packages/d4/8d/5e43d9584b3b3591a6f9b68f755a4da879a59712981ef5ad2a0ac1379f7a/bcrypt-5.0.0-cp39-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:611f0a17aa4a25a69362dcc299fda5c8a3d4f160e2abb3831041feb77393a14a", size = 278240, upload-time = "2025-09-25T19:50:23.305Z" },
+ { url = "https://files.pythonhosted.org/packages/89/48/44590e3fc158620f680a978aafe8f87a4c4320da81ed11552f0323aa9a57/bcrypt-5.0.0-cp39-abi3-musllinux_1_1_aarch64.whl", hash = "sha256:db99dca3b1fdc3db87d7c57eac0c82281242d1eabf19dcb8a6b10eb29a2e72d1", size = 311152, upload-time = "2025-09-25T19:50:24.597Z" },
+ { url = "https://files.pythonhosted.org/packages/5f/85/e4fbfc46f14f47b0d20493669a625da5827d07e8a88ee460af6cd9768b44/bcrypt-5.0.0-cp39-abi3-musllinux_1_1_x86_64.whl", hash = "sha256:5feebf85a9cefda32966d8171f5db7e3ba964b77fdfe31919622256f80f9cf42", size = 313284, upload-time = "2025-09-25T19:50:26.268Z" },
+ { url = "https://files.pythonhosted.org/packages/25/ae/479f81d3f4594456a01ea2f05b132a519eff9ab5768a70430fa1132384b1/bcrypt-5.0.0-cp39-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:3ca8a166b1140436e058298a34d88032ab62f15aae1c598580333dc21d27ef10", size = 341643, upload-time = "2025-09-25T19:50:28.02Z" },
+ { url = "https://files.pythonhosted.org/packages/df/d2/36a086dee1473b14276cd6ea7f61aef3b2648710b5d7f1c9e032c29b859f/bcrypt-5.0.0-cp39-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:61afc381250c3182d9078551e3ac3a41da14154fbff647ddf52a769f588c4172", size = 359698, upload-time = "2025-09-25T19:50:31.347Z" },
+ { url = "https://files.pythonhosted.org/packages/c0/f6/688d2cd64bfd0b14d805ddb8a565e11ca1fb0fd6817175d58b10052b6d88/bcrypt-5.0.0-cp39-abi3-win32.whl", hash = "sha256:64d7ce196203e468c457c37ec22390f1a61c85c6f0b8160fd752940ccfb3a683", size = 153725, upload-time = "2025-09-25T19:50:34.384Z" },
+ { url = "https://files.pythonhosted.org/packages/9f/b9/9d9a641194a730bda138b3dfe53f584d61c58cd5230e37566e83ec2ffa0d/bcrypt-5.0.0-cp39-abi3-win_amd64.whl", hash = "sha256:64ee8434b0da054d830fa8e89e1c8bf30061d539044a39524ff7dec90481e5c2", size = 150912, upload-time = "2025-09-25T19:50:35.69Z" },
+ { url = "https://files.pythonhosted.org/packages/27/44/d2ef5e87509158ad2187f4dd0852df80695bb1ee0cfe0a684727b01a69e0/bcrypt-5.0.0-cp39-abi3-win_arm64.whl", hash = "sha256:f2347d3534e76bf50bca5500989d6c1d05ed64b440408057a37673282c654927", size = 144953, upload-time = "2025-09-25T19:50:37.32Z" },
+ { url = "https://files.pythonhosted.org/packages/8a/75/4aa9f5a4d40d762892066ba1046000b329c7cd58e888a6db878019b282dc/bcrypt-5.0.0-pp311-pypy311_pp73-manylinux_2_28_aarch64.whl", hash = "sha256:7edda91d5ab52b15636d9c30da87d2cc84f426c72b9dba7a9b4fe142ba11f534", size = 271180, upload-time = "2025-09-25T19:50:38.575Z" },
+ { url = "https://files.pythonhosted.org/packages/54/79/875f9558179573d40a9cc743038ac2bf67dfb79cecb1e8b5d70e88c94c3d/bcrypt-5.0.0-pp311-pypy311_pp73-manylinux_2_28_x86_64.whl", hash = "sha256:046ad6db88edb3c5ece4369af997938fb1c19d6a699b9c1b27b0db432faae4c4", size = 273791, upload-time = "2025-09-25T19:50:39.913Z" },
+ { url = "https://files.pythonhosted.org/packages/bc/fe/975adb8c216174bf70fc17535f75e85ac06ed5252ea077be10d9cff5ce24/bcrypt-5.0.0-pp311-pypy311_pp73-manylinux_2_34_aarch64.whl", hash = "sha256:dcd58e2b3a908b5ecc9b9df2f0085592506ac2d5110786018ee5e160f28e0911", size = 270746, upload-time = "2025-09-25T19:50:43.306Z" },
+ { url = "https://files.pythonhosted.org/packages/e4/f8/972c96f5a2b6c4b3deca57009d93e946bbdbe2241dca9806d502f29dd3ee/bcrypt-5.0.0-pp311-pypy311_pp73-manylinux_2_34_x86_64.whl", hash = "sha256:6b8f520b61e8781efee73cba14e3e8c9556ccfb375623f4f97429544734545b4", size = 273375, upload-time = "2025-09-25T19:50:45.43Z" },
+]
+
+[[package]]
+name = "certifi"
+version = "2026.2.25"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/af/2d/7bf41579a8986e348fa033a31cdd0e4121114f6bce2457e8876010b092dd/certifi-2026.2.25.tar.gz", hash = "sha256:e887ab5cee78ea814d3472169153c2d12cd43b14bd03329a39a9c6e2e80bfba7", size = 155029, upload-time = "2026-02-25T02:54:17.342Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/9a/3c/c17fb3ca2d9c3acff52e30b309f538586f9f5b9c9cf454f3845fc9af4881/certifi-2026.2.25-py3-none-any.whl", hash = "sha256:027692e4402ad994f1c42e52a4997a9763c646b73e4096e4d5d6db8af1d6f0fa", size = 153684, upload-time = "2026-02-25T02:54:15.766Z" },
+]
+
+[[package]]
+name = "cffi"
+version = "2.0.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pycparser", marker = "implementation_name != 'PyPy'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/eb/56/b1ba7935a17738ae8453301356628e8147c79dbb825bcbc73dc7401f9846/cffi-2.0.0.tar.gz", hash = "sha256:44d1b5909021139fe36001ae048dbdde8214afa20200eda0f64c068cac5d5529", size = 523588, upload-time = "2025-09-08T23:24:04.541Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/12/4a/3dfd5f7850cbf0d06dc84ba9aa00db766b52ca38d8b86e3a38314d52498c/cffi-2.0.0-cp311-cp311-macosx_10_13_x86_64.whl", hash = "sha256:b4c854ef3adc177950a8dfc81a86f5115d2abd545751a304c5bcf2c2c7283cfe", size = 184344, upload-time = "2025-09-08T23:22:26.456Z" },
+ { url = "https://files.pythonhosted.org/packages/4f/8b/f0e4c441227ba756aafbe78f117485b25bb26b1c059d01f137fa6d14896b/cffi-2.0.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:2de9a304e27f7596cd03d16f1b7c72219bd944e99cc52b84d0145aefb07cbd3c", size = 180560, upload-time = "2025-09-08T23:22:28.197Z" },
+ { url = "https://files.pythonhosted.org/packages/b1/b7/1200d354378ef52ec227395d95c2576330fd22a869f7a70e88e1447eb234/cffi-2.0.0-cp311-cp311-manylinux1_i686.manylinux2014_i686.manylinux_2_17_i686.manylinux_2_5_i686.whl", hash = "sha256:baf5215e0ab74c16e2dd324e8ec067ef59e41125d3eade2b863d294fd5035c92", size = 209613, upload-time = "2025-09-08T23:22:29.475Z" },
+ { url = "https://files.pythonhosted.org/packages/b8/56/6033f5e86e8cc9bb629f0077ba71679508bdf54a9a5e112a3c0b91870332/cffi-2.0.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:730cacb21e1bdff3ce90babf007d0a0917cc3e6492f336c2f0134101e0944f93", size = 216476, upload-time = "2025-09-08T23:22:31.063Z" },
+ { url = "https://files.pythonhosted.org/packages/dc/7f/55fecd70f7ece178db2f26128ec41430d8720f2d12ca97bf8f0a628207d5/cffi-2.0.0-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:6824f87845e3396029f3820c206e459ccc91760e8fa24422f8b0c3d1731cbec5", size = 203374, upload-time = "2025-09-08T23:22:32.507Z" },
+ { url = "https://files.pythonhosted.org/packages/84/ef/a7b77c8bdc0f77adc3b46888f1ad54be8f3b7821697a7b89126e829e676a/cffi-2.0.0-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:9de40a7b0323d889cf8d23d1ef214f565ab154443c42737dfe52ff82cf857664", size = 202597, upload-time = "2025-09-08T23:22:34.132Z" },
+ { url = "https://files.pythonhosted.org/packages/d7/91/500d892b2bf36529a75b77958edfcd5ad8e2ce4064ce2ecfeab2125d72d1/cffi-2.0.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:8941aaadaf67246224cee8c3803777eed332a19d909b47e29c9842ef1e79ac26", size = 215574, upload-time = "2025-09-08T23:22:35.443Z" },
+ { url = "https://files.pythonhosted.org/packages/44/64/58f6255b62b101093d5df22dcb752596066c7e89dd725e0afaed242a61be/cffi-2.0.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:a05d0c237b3349096d3981b727493e22147f934b20f6f125a3eba8f994bec4a9", size = 218971, upload-time = "2025-09-08T23:22:36.805Z" },
+ { url = "https://files.pythonhosted.org/packages/ab/49/fa72cebe2fd8a55fbe14956f9970fe8eb1ac59e5df042f603ef7c8ba0adc/cffi-2.0.0-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:94698a9c5f91f9d138526b48fe26a199609544591f859c870d477351dc7b2414", size = 211972, upload-time = "2025-09-08T23:22:38.436Z" },
+ { url = "https://files.pythonhosted.org/packages/0b/28/dd0967a76aab36731b6ebfe64dec4e981aff7e0608f60c2d46b46982607d/cffi-2.0.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:5fed36fccc0612a53f1d4d9a816b50a36702c28a2aa880cb8a122b3466638743", size = 217078, upload-time = "2025-09-08T23:22:39.776Z" },
+ { url = "https://files.pythonhosted.org/packages/2b/c0/015b25184413d7ab0a410775fdb4a50fca20f5589b5dab1dbbfa3baad8ce/cffi-2.0.0-cp311-cp311-win32.whl", hash = "sha256:c649e3a33450ec82378822b3dad03cc228b8f5963c0c12fc3b1e0ab940f768a5", size = 172076, upload-time = "2025-09-08T23:22:40.95Z" },
+ { url = "https://files.pythonhosted.org/packages/ae/8f/dc5531155e7070361eb1b7e4c1a9d896d0cb21c49f807a6c03fd63fc877e/cffi-2.0.0-cp311-cp311-win_amd64.whl", hash = "sha256:66f011380d0e49ed280c789fbd08ff0d40968ee7b665575489afa95c98196ab5", size = 182820, upload-time = "2025-09-08T23:22:42.463Z" },
+ { url = "https://files.pythonhosted.org/packages/95/5c/1b493356429f9aecfd56bc171285a4c4ac8697f76e9bbbbb105e537853a1/cffi-2.0.0-cp311-cp311-win_arm64.whl", hash = "sha256:c6638687455baf640e37344fe26d37c404db8b80d037c3d29f58fe8d1c3b194d", size = 177635, upload-time = "2025-09-08T23:22:43.623Z" },
+ { url = "https://files.pythonhosted.org/packages/ea/47/4f61023ea636104d4f16ab488e268b93008c3d0bb76893b1b31db1f96802/cffi-2.0.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:6d02d6655b0e54f54c4ef0b94eb6be0607b70853c45ce98bd278dc7de718be5d", size = 185271, upload-time = "2025-09-08T23:22:44.795Z" },
+ { url = "https://files.pythonhosted.org/packages/df/a2/781b623f57358e360d62cdd7a8c681f074a71d445418a776eef0aadb4ab4/cffi-2.0.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:8eca2a813c1cb7ad4fb74d368c2ffbbb4789d377ee5bb8df98373c2cc0dee76c", size = 181048, upload-time = "2025-09-08T23:22:45.938Z" },
+ { url = "https://files.pythonhosted.org/packages/ff/df/a4f0fbd47331ceeba3d37c2e51e9dfc9722498becbeec2bd8bc856c9538a/cffi-2.0.0-cp312-cp312-manylinux1_i686.manylinux2014_i686.manylinux_2_17_i686.manylinux_2_5_i686.whl", hash = "sha256:21d1152871b019407d8ac3985f6775c079416c282e431a4da6afe7aefd2bccbe", size = 212529, upload-time = "2025-09-08T23:22:47.349Z" },
+ { url = "https://files.pythonhosted.org/packages/d5/72/12b5f8d3865bf0f87cf1404d8c374e7487dcf097a1c91c436e72e6badd83/cffi-2.0.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:b21e08af67b8a103c71a250401c78d5e0893beff75e28c53c98f4de42f774062", size = 220097, upload-time = "2025-09-08T23:22:48.677Z" },
+ { url = "https://files.pythonhosted.org/packages/c2/95/7a135d52a50dfa7c882ab0ac17e8dc11cec9d55d2c18dda414c051c5e69e/cffi-2.0.0-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:1e3a615586f05fc4065a8b22b8152f0c1b00cdbc60596d187c2a74f9e3036e4e", size = 207983, upload-time = "2025-09-08T23:22:50.06Z" },
+ { url = "https://files.pythonhosted.org/packages/3a/c8/15cb9ada8895957ea171c62dc78ff3e99159ee7adb13c0123c001a2546c1/cffi-2.0.0-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:81afed14892743bbe14dacb9e36d9e0e504cd204e0b165062c488942b9718037", size = 206519, upload-time = "2025-09-08T23:22:51.364Z" },
+ { url = "https://files.pythonhosted.org/packages/78/2d/7fa73dfa841b5ac06c7b8855cfc18622132e365f5b81d02230333ff26e9e/cffi-2.0.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:3e17ed538242334bf70832644a32a7aae3d83b57567f9fd60a26257e992b79ba", size = 219572, upload-time = "2025-09-08T23:22:52.902Z" },
+ { url = "https://files.pythonhosted.org/packages/07/e0/267e57e387b4ca276b90f0434ff88b2c2241ad72b16d31836adddfd6031b/cffi-2.0.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:3925dd22fa2b7699ed2617149842d2e6adde22b262fcbfada50e3d195e4b3a94", size = 222963, upload-time = "2025-09-08T23:22:54.518Z" },
+ { url = "https://files.pythonhosted.org/packages/b6/75/1f2747525e06f53efbd878f4d03bac5b859cbc11c633d0fb81432d98a795/cffi-2.0.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:2c8f814d84194c9ea681642fd164267891702542f028a15fc97d4674b6206187", size = 221361, upload-time = "2025-09-08T23:22:55.867Z" },
+ { url = "https://files.pythonhosted.org/packages/7b/2b/2b6435f76bfeb6bbf055596976da087377ede68df465419d192acf00c437/cffi-2.0.0-cp312-cp312-win32.whl", hash = "sha256:da902562c3e9c550df360bfa53c035b2f241fed6d9aef119048073680ace4a18", size = 172932, upload-time = "2025-09-08T23:22:57.188Z" },
+ { url = "https://files.pythonhosted.org/packages/f8/ed/13bd4418627013bec4ed6e54283b1959cf6db888048c7cf4b4c3b5b36002/cffi-2.0.0-cp312-cp312-win_amd64.whl", hash = "sha256:da68248800ad6320861f129cd9c1bf96ca849a2771a59e0344e88681905916f5", size = 183557, upload-time = "2025-09-08T23:22:58.351Z" },
+ { url = "https://files.pythonhosted.org/packages/95/31/9f7f93ad2f8eff1dbc1c3656d7ca5bfd8fb52c9d786b4dcf19b2d02217fa/cffi-2.0.0-cp312-cp312-win_arm64.whl", hash = "sha256:4671d9dd5ec934cb9a73e7ee9676f9362aba54f7f34910956b84d727b0d73fb6", size = 177762, upload-time = "2025-09-08T23:22:59.668Z" },
+ { url = "https://files.pythonhosted.org/packages/4b/8d/a0a47a0c9e413a658623d014e91e74a50cdd2c423f7ccfd44086ef767f90/cffi-2.0.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:00bdf7acc5f795150faa6957054fbbca2439db2f775ce831222b66f192f03beb", size = 185230, upload-time = "2025-09-08T23:23:00.879Z" },
+ { url = "https://files.pythonhosted.org/packages/4a/d2/a6c0296814556c68ee32009d9c2ad4f85f2707cdecfd7727951ec228005d/cffi-2.0.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:45d5e886156860dc35862657e1494b9bae8dfa63bf56796f2fb56e1679fc0bca", size = 181043, upload-time = "2025-09-08T23:23:02.231Z" },
+ { url = "https://files.pythonhosted.org/packages/b0/1e/d22cc63332bd59b06481ceaac49d6c507598642e2230f201649058a7e704/cffi-2.0.0-cp313-cp313-manylinux1_i686.manylinux2014_i686.manylinux_2_17_i686.manylinux_2_5_i686.whl", hash = "sha256:07b271772c100085dd28b74fa0cd81c8fb1a3ba18b21e03d7c27f3436a10606b", size = 212446, upload-time = "2025-09-08T23:23:03.472Z" },
+ { url = "https://files.pythonhosted.org/packages/a9/f5/a2c23eb03b61a0b8747f211eb716446c826ad66818ddc7810cc2cc19b3f2/cffi-2.0.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:d48a880098c96020b02d5a1f7d9251308510ce8858940e6fa99ece33f610838b", size = 220101, upload-time = "2025-09-08T23:23:04.792Z" },
+ { url = "https://files.pythonhosted.org/packages/f2/7f/e6647792fc5850d634695bc0e6ab4111ae88e89981d35ac269956605feba/cffi-2.0.0-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:f93fd8e5c8c0a4aa1f424d6173f14a892044054871c771f8566e4008eaa359d2", size = 207948, upload-time = "2025-09-08T23:23:06.127Z" },
+ { url = "https://files.pythonhosted.org/packages/cb/1e/a5a1bd6f1fb30f22573f76533de12a00bf274abcdc55c8edab639078abb6/cffi-2.0.0-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:dd4f05f54a52fb558f1ba9f528228066954fee3ebe629fc1660d874d040ae5a3", size = 206422, upload-time = "2025-09-08T23:23:07.753Z" },
+ { url = "https://files.pythonhosted.org/packages/98/df/0a1755e750013a2081e863e7cd37e0cdd02664372c754e5560099eb7aa44/cffi-2.0.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:c8d3b5532fc71b7a77c09192b4a5a200ea992702734a2e9279a37f2478236f26", size = 219499, upload-time = "2025-09-08T23:23:09.648Z" },
+ { url = "https://files.pythonhosted.org/packages/50/e1/a969e687fcf9ea58e6e2a928ad5e2dd88cc12f6f0ab477e9971f2309b57c/cffi-2.0.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:d9b29c1f0ae438d5ee9acb31cadee00a58c46cc9c0b2f9038c6b0b3470877a8c", size = 222928, upload-time = "2025-09-08T23:23:10.928Z" },
+ { url = "https://files.pythonhosted.org/packages/36/54/0362578dd2c9e557a28ac77698ed67323ed5b9775ca9d3fe73fe191bb5d8/cffi-2.0.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:6d50360be4546678fc1b79ffe7a66265e28667840010348dd69a314145807a1b", size = 221302, upload-time = "2025-09-08T23:23:12.42Z" },
+ { url = "https://files.pythonhosted.org/packages/eb/6d/bf9bda840d5f1dfdbf0feca87fbdb64a918a69bca42cfa0ba7b137c48cb8/cffi-2.0.0-cp313-cp313-win32.whl", hash = "sha256:74a03b9698e198d47562765773b4a8309919089150a0bb17d829ad7b44b60d27", size = 172909, upload-time = "2025-09-08T23:23:14.32Z" },
+ { url = "https://files.pythonhosted.org/packages/37/18/6519e1ee6f5a1e579e04b9ddb6f1676c17368a7aba48299c3759bbc3c8b3/cffi-2.0.0-cp313-cp313-win_amd64.whl", hash = "sha256:19f705ada2530c1167abacb171925dd886168931e0a7b78f5bffcae5c6b5be75", size = 183402, upload-time = "2025-09-08T23:23:15.535Z" },
+ { url = "https://files.pythonhosted.org/packages/cb/0e/02ceeec9a7d6ee63bb596121c2c8e9b3a9e150936f4fbef6ca1943e6137c/cffi-2.0.0-cp313-cp313-win_arm64.whl", hash = "sha256:256f80b80ca3853f90c21b23ee78cd008713787b1b1e93eae9f3d6a7134abd91", size = 177780, upload-time = "2025-09-08T23:23:16.761Z" },
+]
+
+[[package]]
+name = "charset-normalizer"
+version = "3.4.5"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/1d/35/02daf95b9cd686320bb622eb148792655c9412dbb9b67abb5694e5910a24/charset_normalizer-3.4.5.tar.gz", hash = "sha256:95adae7b6c42a6c5b5b559b1a99149f090a57128155daeea91732c8d970d8644", size = 134804, upload-time = "2026-03-06T06:03:19.46Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/8f/9e/bcec3b22c64ecec47d39bf5167c2613efd41898c019dccd4183f6aa5d6a7/charset_normalizer-3.4.5-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:610f72c0ee565dfb8ae1241b666119582fdbfe7c0975c175be719f940e110694", size = 279531, upload-time = "2026-03-06T06:00:52.252Z" },
+ { url = "https://files.pythonhosted.org/packages/58/12/81fd25f7e7078ab5d1eedbb0fac44be4904ae3370a3bf4533c8f2d159acd/charset_normalizer-3.4.5-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:60d68e820af339df4ae8358c7a2e7596badeb61e544438e489035f9fbf3246a5", size = 188006, upload-time = "2026-03-06T06:00:53.8Z" },
+ { url = "https://files.pythonhosted.org/packages/ae/6e/f2d30e8c27c1b0736a6520311982cf5286cfc7f6cac77d7bc1325e3a23f2/charset_normalizer-3.4.5-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:10b473fc8dca1c3ad8559985794815f06ca3fc71942c969129070f2c3cdf7281", size = 205085, upload-time = "2026-03-06T06:00:55.311Z" },
+ { url = "https://files.pythonhosted.org/packages/d0/90/d12cefcb53b5931e2cf792a33718d7126efb116a320eaa0742c7059a95e4/charset_normalizer-3.4.5-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:d4eb8ac7469b2a5d64b5b8c04f84d8bf3ad340f4514b98523805cbf46e3b3923", size = 200545, upload-time = "2026-03-06T06:00:56.532Z" },
+ { url = "https://files.pythonhosted.org/packages/03/f4/44d3b830a20e89ff82a3134912d9a1cf6084d64f3b95dcad40f74449a654/charset_normalizer-3.4.5-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:5bcb3227c3d9aaf73eaaab1db7ccd80a8995c509ee9941e2aae060ca6e4e5d81", size = 193863, upload-time = "2026-03-06T06:00:57.823Z" },
+ { url = "https://files.pythonhosted.org/packages/25/4b/f212119c18a6320a9d4a730d1b4057875cdeabf21b3614f76549042ef8a8/charset_normalizer-3.4.5-cp311-cp311-manylinux_2_31_armv7l.whl", hash = "sha256:75ee9c1cce2911581a70a3c0919d8bccf5b1cbc9b0e5171400ec736b4b569497", size = 181827, upload-time = "2026-03-06T06:00:59.323Z" },
+ { url = "https://files.pythonhosted.org/packages/74/00/b26158e48b425a202a92965f8069e8a63d9af1481dfa206825d7f74d2a3c/charset_normalizer-3.4.5-cp311-cp311-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:1d1401945cb77787dbd3af2446ff2d75912327c4c3a1526ab7955ecf8600687c", size = 191085, upload-time = "2026-03-06T06:01:00.546Z" },
+ { url = "https://files.pythonhosted.org/packages/c4/c2/1c1737bf6fd40335fe53d28fe49afd99ee4143cc57a845e99635ce0b9b6d/charset_normalizer-3.4.5-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:0a45e504f5e1be0bd385935a8e1507c442349ca36f511a47057a71c9d1d6ea9e", size = 190688, upload-time = "2026-03-06T06:01:02.479Z" },
+ { url = "https://files.pythonhosted.org/packages/5a/3d/abb5c22dc2ef493cd56522f811246a63c5427c08f3e3e50ab663de27fcf4/charset_normalizer-3.4.5-cp311-cp311-musllinux_1_2_armv7l.whl", hash = "sha256:e09f671a54ce70b79a1fc1dc6da3072b7ef7251fadb894ed92d9aa8218465a5f", size = 183077, upload-time = "2026-03-06T06:01:04.231Z" },
+ { url = "https://files.pythonhosted.org/packages/44/33/5298ad4d419a58e25b3508e87f2758d1442ff00c2471f8e0403dab8edad5/charset_normalizer-3.4.5-cp311-cp311-musllinux_1_2_ppc64le.whl", hash = "sha256:d01de5e768328646e6a3fa9e562706f8f6641708c115c62588aef2b941a4f88e", size = 206706, upload-time = "2026-03-06T06:01:05.773Z" },
+ { url = "https://files.pythonhosted.org/packages/7b/17/51e7895ac0f87c3b91d276a449ef09f5532a7529818f59646d7a55089432/charset_normalizer-3.4.5-cp311-cp311-musllinux_1_2_riscv64.whl", hash = "sha256:131716d6786ad5e3dc542f5cc6f397ba3339dc0fb87f87ac30e550e8987756af", size = 191665, upload-time = "2026-03-06T06:01:07.473Z" },
+ { url = "https://files.pythonhosted.org/packages/90/8f/cce9adf1883e98906dbae380d769b4852bb0fa0004bc7d7a2243418d3ea8/charset_normalizer-3.4.5-cp311-cp311-musllinux_1_2_s390x.whl", hash = "sha256:1a374cc0b88aa710e8865dc1bd6edb3743c59f27830f0293ab101e4cf3ce9f85", size = 201950, upload-time = "2026-03-06T06:01:08.973Z" },
+ { url = "https://files.pythonhosted.org/packages/08/ca/bce99cd5c397a52919e2769d126723f27a4c037130374c051c00470bcd38/charset_normalizer-3.4.5-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:d31f0d1671e1534e395f9eb84a68e0fb670e1edb1fe819a9d7f564ae3bc4e53f", size = 195830, upload-time = "2026-03-06T06:01:10.155Z" },
+ { url = "https://files.pythonhosted.org/packages/87/4f/2e3d023a06911f1281f97b8f036edc9872167036ca6f55cc874a0be6c12c/charset_normalizer-3.4.5-cp311-cp311-win32.whl", hash = "sha256:cace89841c0599d736d3d74a27bc5821288bb47c5441923277afc6059d7fbcb4", size = 132029, upload-time = "2026-03-06T06:01:11.706Z" },
+ { url = "https://files.pythonhosted.org/packages/fe/1f/a853b73d386521fd44b7f67ded6b17b7b2367067d9106a5c4b44f9a34274/charset_normalizer-3.4.5-cp311-cp311-win_amd64.whl", hash = "sha256:f8102ae93c0bc863b1d41ea0f4499c20a83229f52ed870850892df555187154a", size = 142404, upload-time = "2026-03-06T06:01:12.865Z" },
+ { url = "https://files.pythonhosted.org/packages/b4/10/dba36f76b71c38e9d391abe0fd8a5b818790e053c431adecfc98c35cd2a9/charset_normalizer-3.4.5-cp311-cp311-win_arm64.whl", hash = "sha256:ed98364e1c262cf5f9363c3eca8c2df37024f52a8fa1180a3610014f26eac51c", size = 132796, upload-time = "2026-03-06T06:01:14.106Z" },
+ { url = "https://files.pythonhosted.org/packages/9c/b6/9ee9c1a608916ca5feae81a344dffbaa53b26b90be58cc2159e3332d44ec/charset_normalizer-3.4.5-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:ed97c282ee4f994ef814042423a529df9497e3c666dca19be1d4cd1129dc7ade", size = 280976, upload-time = "2026-03-06T06:01:15.276Z" },
+ { url = "https://files.pythonhosted.org/packages/f8/d8/a54f7c0b96f1df3563e9190f04daf981e365a9b397eedfdfb5dbef7e5c6c/charset_normalizer-3.4.5-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0294916d6ccf2d069727d65973c3a1ca477d68708db25fd758dd28b0827cff54", size = 189356, upload-time = "2026-03-06T06:01:16.511Z" },
+ { url = "https://files.pythonhosted.org/packages/42/69/2bf7f76ce1446759a5787cb87d38f6a61eb47dbbdf035cfebf6347292a65/charset_normalizer-3.4.5-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:dc57a0baa3eeedd99fafaef7511b5a6ef4581494e8168ee086031744e2679467", size = 206369, upload-time = "2026-03-06T06:01:17.853Z" },
+ { url = "https://files.pythonhosted.org/packages/10/9c/949d1a46dab56b959d9a87272482195f1840b515a3380e39986989a893ae/charset_normalizer-3.4.5-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:ed1a9a204f317ef879b32f9af507d47e49cd5e7f8e8d5d96358c98373314fc60", size = 203285, upload-time = "2026-03-06T06:01:19.473Z" },
+ { url = "https://files.pythonhosted.org/packages/67/5c/ae30362a88b4da237d71ea214a8c7eb915db3eec941adda511729ac25fa2/charset_normalizer-3.4.5-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:7ad83b8f9379176c841f8865884f3514d905bcd2a9a3b210eaa446e7d2223e4d", size = 196274, upload-time = "2026-03-06T06:01:20.728Z" },
+ { url = "https://files.pythonhosted.org/packages/b2/07/c9f2cb0e46cb6d64fdcc4f95953747b843bb2181bda678dc4e699b8f0f9a/charset_normalizer-3.4.5-cp312-cp312-manylinux_2_31_armv7l.whl", hash = "sha256:a118e2e0b5ae6b0120d5efa5f866e58f2bb826067a646431da4d6a2bdae7950e", size = 184715, upload-time = "2026-03-06T06:01:22.194Z" },
+ { url = "https://files.pythonhosted.org/packages/36/64/6b0ca95c44fddf692cd06d642b28f63009d0ce325fad6e9b2b4d0ef86a52/charset_normalizer-3.4.5-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:754f96058e61a5e22e91483f823e07df16416ce76afa4ebf306f8e1d1296d43f", size = 193426, upload-time = "2026-03-06T06:01:23.795Z" },
+ { url = "https://files.pythonhosted.org/packages/50/bc/a730690d726403743795ca3f5bb2baf67838c5fea78236098f324b965e40/charset_normalizer-3.4.5-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:0c300cefd9b0970381a46394902cd18eaf2aa00163f999590ace991989dcd0fc", size = 191780, upload-time = "2026-03-06T06:01:25.053Z" },
+ { url = "https://files.pythonhosted.org/packages/97/4f/6c0bc9af68222b22951552d73df4532b5be6447cee32d58e7e8c74ecbb7b/charset_normalizer-3.4.5-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:c108f8619e504140569ee7de3f97d234f0fbae338a7f9f360455071ef9855a95", size = 185805, upload-time = "2026-03-06T06:01:26.294Z" },
+ { url = "https://files.pythonhosted.org/packages/dd/b9/a523fb9b0ee90814b503452b2600e4cbc118cd68714d57041564886e7325/charset_normalizer-3.4.5-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:d1028de43596a315e2720a9849ee79007ab742c06ad8b45a50db8cdb7ed4a82a", size = 208342, upload-time = "2026-03-06T06:01:27.55Z" },
+ { url = "https://files.pythonhosted.org/packages/4d/61/c59e761dee4464050713e50e27b58266cc8e209e518c0b378c1580c959ba/charset_normalizer-3.4.5-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:19092dde50335accf365cce21998a1c6dd8eafd42c7b226eb54b2747cdce2fac", size = 193661, upload-time = "2026-03-06T06:01:29.051Z" },
+ { url = "https://files.pythonhosted.org/packages/1c/43/729fa30aad69783f755c5ad8649da17ee095311ca42024742701e202dc59/charset_normalizer-3.4.5-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:4354e401eb6dab9aed3c7b4030514328a6c748d05e1c3e19175008ca7de84fb1", size = 204819, upload-time = "2026-03-06T06:01:30.298Z" },
+ { url = "https://files.pythonhosted.org/packages/87/33/d9b442ce5a91b96fc0840455a9e49a611bbadae6122778d0a6a79683dd31/charset_normalizer-3.4.5-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:a68766a3c58fde7f9aaa22b3786276f62ab2f594efb02d0a1421b6282e852e98", size = 198080, upload-time = "2026-03-06T06:01:31.478Z" },
+ { url = "https://files.pythonhosted.org/packages/56/5a/b8b5a23134978ee9885cee2d6995f4c27cc41f9baded0a9685eabc5338f0/charset_normalizer-3.4.5-cp312-cp312-win32.whl", hash = "sha256:1827734a5b308b65ac54e86a618de66f935a4f63a8a462ff1e19a6788d6c2262", size = 132630, upload-time = "2026-03-06T06:01:33.056Z" },
+ { url = "https://files.pythonhosted.org/packages/70/53/e44a4c07e8904500aec95865dc3f6464dc3586a039ef0df606eb3ac38e35/charset_normalizer-3.4.5-cp312-cp312-win_amd64.whl", hash = "sha256:728c6a963dfab66ef865f49286e45239384249672cd598576765acc2a640a636", size = 142856, upload-time = "2026-03-06T06:01:34.489Z" },
+ { url = "https://files.pythonhosted.org/packages/ea/aa/c5628f7cad591b1cf45790b7a61483c3e36cf41349c98af7813c483fd6e8/charset_normalizer-3.4.5-cp312-cp312-win_arm64.whl", hash = "sha256:75dfd1afe0b1647449e852f4fb428195a7ed0588947218f7ba929f6538487f02", size = 132982, upload-time = "2026-03-06T06:01:35.641Z" },
+ { url = "https://files.pythonhosted.org/packages/f5/48/9f34ec4bb24aa3fdba1890c1bddb97c8a4be1bd84ef5c42ac2352563ad05/charset_normalizer-3.4.5-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:ac59c15e3f1465f722607800c68713f9fbc2f672b9eb649fe831da4019ae9b23", size = 280788, upload-time = "2026-03-06T06:01:37.126Z" },
+ { url = "https://files.pythonhosted.org/packages/0e/09/6003e7ffeb90cc0560da893e3208396a44c210c5ee42efff539639def59b/charset_normalizer-3.4.5-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:165c7b21d19365464e8f70e5ce5e12524c58b48c78c1f5a57524603c1ab003f8", size = 188890, upload-time = "2026-03-06T06:01:38.73Z" },
+ { url = "https://files.pythonhosted.org/packages/42/1e/02706edf19e390680daa694d17e2b8eab4b5f7ac285e2a51168b4b22ee6b/charset_normalizer-3.4.5-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:28269983f25a4da0425743d0d257a2d6921ea7d9b83599d4039486ec5b9f911d", size = 206136, upload-time = "2026-03-06T06:01:40.016Z" },
+ { url = "https://files.pythonhosted.org/packages/c7/87/942c3def1b37baf3cf786bad01249190f3ca3d5e63a84f831e704977de1f/charset_normalizer-3.4.5-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:d27ce22ec453564770d29d03a9506d449efbb9fa13c00842262b2f6801c48cce", size = 202551, upload-time = "2026-03-06T06:01:41.522Z" },
+ { url = "https://files.pythonhosted.org/packages/94/0a/af49691938dfe175d71b8a929bd7e4ace2809c0c5134e28bc535660d5262/charset_normalizer-3.4.5-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0625665e4ebdddb553ab185de5db7054393af8879fb0c87bd5690d14379d6819", size = 195572, upload-time = "2026-03-06T06:01:43.208Z" },
+ { url = "https://files.pythonhosted.org/packages/20/ea/dfb1792a8050a8e694cfbde1570ff97ff74e48afd874152d38163d1df9ae/charset_normalizer-3.4.5-cp313-cp313-manylinux_2_31_armv7l.whl", hash = "sha256:c23eb3263356d94858655b3e63f85ac5d50970c6e8febcdde7830209139cc37d", size = 184438, upload-time = "2026-03-06T06:01:44.755Z" },
+ { url = "https://files.pythonhosted.org/packages/72/12/c281e2067466e3ddd0595bfaea58a6946765ace5c72dfa3edc2f5f118026/charset_normalizer-3.4.5-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:e6302ca4ae283deb0af68d2fbf467474b8b6aedcd3dab4db187e07f94c109763", size = 193035, upload-time = "2026-03-06T06:01:46.051Z" },
+ { url = "https://files.pythonhosted.org/packages/ba/4f/3792c056e7708e10464bad0438a44708886fb8f92e3c3d29ec5e2d964d42/charset_normalizer-3.4.5-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:e51ae7d81c825761d941962450f50d041db028b7278e7b08930b4541b3e45cb9", size = 191340, upload-time = "2026-03-06T06:01:47.547Z" },
+ { url = "https://files.pythonhosted.org/packages/e7/86/80ddba897127b5c7a9bccc481b0cd36c8fefa485d113262f0fe4332f0bf4/charset_normalizer-3.4.5-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:597d10dec876923e5c59e48dbd366e852eacb2b806029491d307daea6b917d7c", size = 185464, upload-time = "2026-03-06T06:01:48.764Z" },
+ { url = "https://files.pythonhosted.org/packages/4d/00/b5eff85ba198faacab83e0e4b6f0648155f072278e3b392a82478f8b988b/charset_normalizer-3.4.5-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:5cffde4032a197bd3b42fd0b9509ec60fb70918d6970e4cc773f20fc9180ca67", size = 208014, upload-time = "2026-03-06T06:01:50.371Z" },
+ { url = "https://files.pythonhosted.org/packages/c8/11/d36f70be01597fd30850dde8a1269ebc8efadd23ba5785808454f2389bde/charset_normalizer-3.4.5-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:2da4eedcb6338e2321e831a0165759c0c620e37f8cd044a263ff67493be8ffb3", size = 193297, upload-time = "2026-03-06T06:01:51.933Z" },
+ { url = "https://files.pythonhosted.org/packages/1a/1d/259eb0a53d4910536c7c2abb9cb25f4153548efb42800c6a9456764649c0/charset_normalizer-3.4.5-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:65a126fb4b070d05340a84fc709dd9e7c75d9b063b610ece8a60197a291d0adf", size = 204321, upload-time = "2026-03-06T06:01:53.887Z" },
+ { url = "https://files.pythonhosted.org/packages/84/31/faa6c5b9d3688715e1ed1bb9d124c384fe2fc1633a409e503ffe1c6398c1/charset_normalizer-3.4.5-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:c7a80a9242963416bd81f99349d5f3fce1843c303bd404f204918b6d75a75fd6", size = 197509, upload-time = "2026-03-06T06:01:56.439Z" },
+ { url = "https://files.pythonhosted.org/packages/fd/a5/c7d9dd1503ffc08950b3260f5d39ec2366dd08254f0900ecbcf3a6197c7c/charset_normalizer-3.4.5-cp313-cp313-win32.whl", hash = "sha256:f1d725b754e967e648046f00c4facc42d414840f5ccc670c5670f59f83693e4f", size = 132284, upload-time = "2026-03-06T06:01:57.812Z" },
+ { url = "https://files.pythonhosted.org/packages/b9/0f/57072b253af40c8aa6636e6de7d75985624c1eb392815b2f934199340a89/charset_normalizer-3.4.5-cp313-cp313-win_amd64.whl", hash = "sha256:e37bd100d2c5d3ba35db9c7c5ba5a9228cbcffe5c4778dc824b164e5257813d7", size = 142630, upload-time = "2026-03-06T06:01:59.062Z" },
+ { url = "https://files.pythonhosted.org/packages/31/41/1c4b7cc9f13bd9d369ce3bc993e13d374ce25fa38a2663644283ecf422c1/charset_normalizer-3.4.5-cp313-cp313-win_arm64.whl", hash = "sha256:93b3b2cc5cf1b8743660ce77a4f45f3f6d1172068207c1defc779a36eea6bb36", size = 133254, upload-time = "2026-03-06T06:02:00.281Z" },
+ { url = "https://files.pythonhosted.org/packages/c5/60/3a621758945513adfd4db86827a5bafcc615f913dbd0b4c2ed64a65731be/charset_normalizer-3.4.5-py3-none-any.whl", hash = "sha256:9db5e3fcdcee89a78c04dffb3fe33c79f77bd741a624946db2591c81b2fc85b0", size = 55455, upload-time = "2026-03-06T06:03:17.827Z" },
+]
+
+[[package]]
+name = "colorama"
+version = "0.4.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d8/53/6f443c9a4a8358a93a6792e2acffb9d9d5cb0a5cfd8802644b7b1c9a02e4/colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44", size = 27697, upload-time = "2022-10-25T02:36:22.414Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6", size = 25335, upload-time = "2022-10-25T02:36:20.889Z" },
+]
+
+[[package]]
+name = "constantly"
+version = "23.10.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/4d/6f/cb2a94494ff74aa9528a36c5b1422756330a75a8367bf20bd63171fc324d/constantly-23.10.4.tar.gz", hash = "sha256:aa92b70a33e2ac0bb33cd745eb61776594dc48764b06c35e0efd050b7f1c7cbd", size = 13300, upload-time = "2023-10-28T23:18:24.316Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/b8/40/c199d095151addf69efdb4b9ca3a4f20f70e20508d6222bffb9b76f58573/constantly-23.10.4-py3-none-any.whl", hash = "sha256:3fd9b4d1c3dc1ec9757f3c52aef7e53ad9323dbe39f51dfd4c43853b68dfa3f9", size = 13547, upload-time = "2023-10-28T23:18:23.038Z" },
+]
+
+[[package]]
+name = "cryptography"
+version = "46.0.5"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "cffi", marker = "platform_python_implementation != 'PyPy'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/60/04/ee2a9e8542e4fa2773b81771ff8349ff19cdd56b7258a0cc442639052edb/cryptography-46.0.5.tar.gz", hash = "sha256:abace499247268e3757271b2f1e244b36b06f8515cf27c4d49468fc9eb16e93d", size = 750064, upload-time = "2026-02-10T19:18:38.255Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/f7/81/b0bb27f2ba931a65409c6b8a8b358a7f03c0e46eceacddff55f7c84b1f3b/cryptography-46.0.5-cp311-abi3-macosx_10_9_universal2.whl", hash = "sha256:351695ada9ea9618b3500b490ad54c739860883df6c1f555e088eaf25b1bbaad", size = 7176289, upload-time = "2026-02-10T19:17:08.274Z" },
+ { url = "https://files.pythonhosted.org/packages/ff/9e/6b4397a3e3d15123de3b1806ef342522393d50736c13b20ec4c9ea6693a6/cryptography-46.0.5-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:c18ff11e86df2e28854939acde2d003f7984f721eba450b56a200ad90eeb0e6b", size = 4275637, upload-time = "2026-02-10T19:17:10.53Z" },
+ { url = "https://files.pythonhosted.org/packages/63/e7/471ab61099a3920b0c77852ea3f0ea611c9702f651600397ac567848b897/cryptography-46.0.5-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:4d7e3d356b8cd4ea5aff04f129d5f66ebdc7b6f8eae802b93739ed520c47c79b", size = 4424742, upload-time = "2026-02-10T19:17:12.388Z" },
+ { url = "https://files.pythonhosted.org/packages/37/53/a18500f270342d66bf7e4d9f091114e31e5ee9e7375a5aba2e85a91e0044/cryptography-46.0.5-cp311-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:50bfb6925eff619c9c023b967d5b77a54e04256c4281b0e21336a130cd7fc263", size = 4277528, upload-time = "2026-02-10T19:17:13.853Z" },
+ { url = "https://files.pythonhosted.org/packages/22/29/c2e812ebc38c57b40e7c583895e73c8c5adb4d1e4a0cc4c5a4fdab2b1acc/cryptography-46.0.5-cp311-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:803812e111e75d1aa73690d2facc295eaefd4439be1023fefc4995eaea2af90d", size = 4947993, upload-time = "2026-02-10T19:17:15.618Z" },
+ { url = "https://files.pythonhosted.org/packages/6b/e7/237155ae19a9023de7e30ec64e5d99a9431a567407ac21170a046d22a5a3/cryptography-46.0.5-cp311-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:3ee190460e2fbe447175cda91b88b84ae8322a104fc27766ad09428754a618ed", size = 4456855, upload-time = "2026-02-10T19:17:17.221Z" },
+ { url = "https://files.pythonhosted.org/packages/2d/87/fc628a7ad85b81206738abbd213b07702bcbdada1dd43f72236ef3cffbb5/cryptography-46.0.5-cp311-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:f145bba11b878005c496e93e257c1e88f154d278d2638e6450d17e0f31e558d2", size = 3984635, upload-time = "2026-02-10T19:17:18.792Z" },
+ { url = "https://files.pythonhosted.org/packages/84/29/65b55622bde135aedf4565dc509d99b560ee4095e56989e815f8fd2aa910/cryptography-46.0.5-cp311-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:e9251e3be159d1020c4030bd2e5f84d6a43fe54b6c19c12f51cde9542a2817b2", size = 4277038, upload-time = "2026-02-10T19:17:20.256Z" },
+ { url = "https://files.pythonhosted.org/packages/bc/36/45e76c68d7311432741faf1fbf7fac8a196a0a735ca21f504c75d37e2558/cryptography-46.0.5-cp311-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:47fb8a66058b80e509c47118ef8a75d14c455e81ac369050f20ba0d23e77fee0", size = 4912181, upload-time = "2026-02-10T19:17:21.825Z" },
+ { url = "https://files.pythonhosted.org/packages/6d/1a/c1ba8fead184d6e3d5afcf03d569acac5ad063f3ac9fb7258af158f7e378/cryptography-46.0.5-cp311-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:4c3341037c136030cb46e4b1e17b7418ea4cbd9dd207e4a6f3b2b24e0d4ac731", size = 4456482, upload-time = "2026-02-10T19:17:25.133Z" },
+ { url = "https://files.pythonhosted.org/packages/f9/e5/3fb22e37f66827ced3b902cf895e6a6bc1d095b5b26be26bd13c441fdf19/cryptography-46.0.5-cp311-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:890bcb4abd5a2d3f852196437129eb3667d62630333aacc13dfd470fad3aaa82", size = 4405497, upload-time = "2026-02-10T19:17:26.66Z" },
+ { url = "https://files.pythonhosted.org/packages/1a/df/9d58bb32b1121a8a2f27383fabae4d63080c7ca60b9b5c88be742be04ee7/cryptography-46.0.5-cp311-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:80a8d7bfdf38f87ca30a5391c0c9ce4ed2926918e017c29ddf643d0ed2778ea1", size = 4667819, upload-time = "2026-02-10T19:17:28.569Z" },
+ { url = "https://files.pythonhosted.org/packages/ea/ed/325d2a490c5e94038cdb0117da9397ece1f11201f425c4e9c57fe5b9f08b/cryptography-46.0.5-cp311-abi3-win32.whl", hash = "sha256:60ee7e19e95104d4c03871d7d7dfb3d22ef8a9b9c6778c94e1c8fcc8365afd48", size = 3028230, upload-time = "2026-02-10T19:17:30.518Z" },
+ { url = "https://files.pythonhosted.org/packages/e9/5a/ac0f49e48063ab4255d9e3b79f5def51697fce1a95ea1370f03dc9db76f6/cryptography-46.0.5-cp311-abi3-win_amd64.whl", hash = "sha256:38946c54b16c885c72c4f59846be9743d699eee2b69b6988e0a00a01f46a61a4", size = 3480909, upload-time = "2026-02-10T19:17:32.083Z" },
+ { url = "https://files.pythonhosted.org/packages/e2/fa/a66aa722105ad6a458bebd64086ca2b72cdd361fed31763d20390f6f1389/cryptography-46.0.5-cp38-abi3-macosx_10_9_universal2.whl", hash = "sha256:4108d4c09fbbf2789d0c926eb4152ae1760d5a2d97612b92d508d96c861e4d31", size = 7170514, upload-time = "2026-02-10T19:17:56.267Z" },
+ { url = "https://files.pythonhosted.org/packages/0f/04/c85bdeab78c8bc77b701bf0d9bdcf514c044e18a46dcff330df5448631b0/cryptography-46.0.5-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:7d1f30a86d2757199cb2d56e48cce14deddf1f9c95f1ef1b64ee91ea43fe2e18", size = 4275349, upload-time = "2026-02-10T19:17:58.419Z" },
+ { url = "https://files.pythonhosted.org/packages/5c/32/9b87132a2f91ee7f5223b091dc963055503e9b442c98fc0b8a5ca765fab0/cryptography-46.0.5-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:039917b0dc418bb9f6edce8a906572d69e74bd330b0b3fea4f79dab7f8ddd235", size = 4420667, upload-time = "2026-02-10T19:18:00.619Z" },
+ { url = "https://files.pythonhosted.org/packages/a1/a6/a7cb7010bec4b7c5692ca6f024150371b295ee1c108bdc1c400e4c44562b/cryptography-46.0.5-cp38-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:ba2a27ff02f48193fc4daeadf8ad2590516fa3d0adeeb34336b96f7fa64c1e3a", size = 4276980, upload-time = "2026-02-10T19:18:02.379Z" },
+ { url = "https://files.pythonhosted.org/packages/8e/7c/c4f45e0eeff9b91e3f12dbd0e165fcf2a38847288fcfd889deea99fb7b6d/cryptography-46.0.5-cp38-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:61aa400dce22cb001a98014f647dc21cda08f7915ceb95df0c9eaf84b4b6af76", size = 4939143, upload-time = "2026-02-10T19:18:03.964Z" },
+ { url = "https://files.pythonhosted.org/packages/37/19/e1b8f964a834eddb44fa1b9a9976f4e414cbb7aa62809b6760c8803d22d1/cryptography-46.0.5-cp38-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:3ce58ba46e1bc2aac4f7d9290223cead56743fa6ab94a5d53292ffaac6a91614", size = 4453674, upload-time = "2026-02-10T19:18:05.588Z" },
+ { url = "https://files.pythonhosted.org/packages/db/ed/db15d3956f65264ca204625597c410d420e26530c4e2943e05a0d2f24d51/cryptography-46.0.5-cp38-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:420d0e909050490d04359e7fdb5ed7e667ca5c3c402b809ae2563d7e66a92229", size = 3978801, upload-time = "2026-02-10T19:18:07.167Z" },
+ { url = "https://files.pythonhosted.org/packages/41/e2/df40a31d82df0a70a0daf69791f91dbb70e47644c58581d654879b382d11/cryptography-46.0.5-cp38-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:582f5fcd2afa31622f317f80426a027f30dc792e9c80ffee87b993200ea115f1", size = 4276755, upload-time = "2026-02-10T19:18:09.813Z" },
+ { url = "https://files.pythonhosted.org/packages/33/45/726809d1176959f4a896b86907b98ff4391a8aa29c0aaaf9450a8a10630e/cryptography-46.0.5-cp38-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:bfd56bb4b37ed4f330b82402f6f435845a5f5648edf1ad497da51a8452d5d62d", size = 4901539, upload-time = "2026-02-10T19:18:11.263Z" },
+ { url = "https://files.pythonhosted.org/packages/99/0f/a3076874e9c88ecb2ecc31382f6e7c21b428ede6f55aafa1aa272613e3cd/cryptography-46.0.5-cp38-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:a3d507bb6a513ca96ba84443226af944b0f7f47dcc9a399d110cd6146481d24c", size = 4452794, upload-time = "2026-02-10T19:18:12.914Z" },
+ { url = "https://files.pythonhosted.org/packages/02/ef/ffeb542d3683d24194a38f66ca17c0a4b8bf10631feef44a7ef64e631b1a/cryptography-46.0.5-cp38-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:9f16fbdf4da055efb21c22d81b89f155f02ba420558db21288b3d0035bafd5f4", size = 4404160, upload-time = "2026-02-10T19:18:14.375Z" },
+ { url = "https://files.pythonhosted.org/packages/96/93/682d2b43c1d5f1406ed048f377c0fc9fc8f7b0447a478d5c65ab3d3a66eb/cryptography-46.0.5-cp38-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:ced80795227d70549a411a4ab66e8ce307899fad2220ce5ab2f296e687eacde9", size = 4667123, upload-time = "2026-02-10T19:18:15.886Z" },
+ { url = "https://files.pythonhosted.org/packages/45/2d/9c5f2926cb5300a8eefc3f4f0b3f3df39db7f7ce40c8365444c49363cbda/cryptography-46.0.5-cp38-abi3-win32.whl", hash = "sha256:02f547fce831f5096c9a567fd41bc12ca8f11df260959ecc7c3202555cc47a72", size = 3010220, upload-time = "2026-02-10T19:18:17.361Z" },
+ { url = "https://files.pythonhosted.org/packages/48/ef/0c2f4a8e31018a986949d34a01115dd057bf536905dca38897bacd21fac3/cryptography-46.0.5-cp38-abi3-win_amd64.whl", hash = "sha256:556e106ee01aa13484ce9b0239bca667be5004efb0aabbed28d353df86445595", size = 3467050, upload-time = "2026-02-10T19:18:18.899Z" },
+ { url = "https://files.pythonhosted.org/packages/eb/dd/2d9fdb07cebdf3d51179730afb7d5e576153c6744c3ff8fded23030c204e/cryptography-46.0.5-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:3b4995dc971c9fb83c25aa44cf45f02ba86f71ee600d81091c2f0cbae116b06c", size = 3476964, upload-time = "2026-02-10T19:18:20.687Z" },
+ { url = "https://files.pythonhosted.org/packages/e9/6f/6cc6cc9955caa6eaf83660b0da2b077c7fe8ff9950a3c5e45d605038d439/cryptography-46.0.5-pp311-pypy311_pp73-manylinux_2_28_aarch64.whl", hash = "sha256:bc84e875994c3b445871ea7181d424588171efec3e185dced958dad9e001950a", size = 4218321, upload-time = "2026-02-10T19:18:22.349Z" },
+ { url = "https://files.pythonhosted.org/packages/3e/5d/c4da701939eeee699566a6c1367427ab91a8b7088cc2328c09dbee940415/cryptography-46.0.5-pp311-pypy311_pp73-manylinux_2_28_x86_64.whl", hash = "sha256:2ae6971afd6246710480e3f15824ed3029a60fc16991db250034efd0b9fb4356", size = 4381786, upload-time = "2026-02-10T19:18:24.529Z" },
+ { url = "https://files.pythonhosted.org/packages/ac/97/a538654732974a94ff96c1db621fa464f455c02d4bb7d2652f4edc21d600/cryptography-46.0.5-pp311-pypy311_pp73-manylinux_2_34_aarch64.whl", hash = "sha256:d861ee9e76ace6cf36a6a89b959ec08e7bc2493ee39d07ffe5acb23ef46d27da", size = 4217990, upload-time = "2026-02-10T19:18:25.957Z" },
+ { url = "https://files.pythonhosted.org/packages/ae/11/7e500d2dd3ba891197b9efd2da5454b74336d64a7cc419aa7327ab74e5f6/cryptography-46.0.5-pp311-pypy311_pp73-manylinux_2_34_x86_64.whl", hash = "sha256:2b7a67c9cd56372f3249b39699f2ad479f6991e62ea15800973b956f4b73e257", size = 4381252, upload-time = "2026-02-10T19:18:27.496Z" },
+ { url = "https://files.pythonhosted.org/packages/bc/58/6b3d24e6b9bc474a2dcdee65dfd1f008867015408a271562e4b690561a4d/cryptography-46.0.5-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:8456928655f856c6e1533ff59d5be76578a7157224dbd9ce6872f25055ab9ab7", size = 3407605, upload-time = "2026-02-10T19:18:29.233Z" },
+]
+
+[[package]]
+name = "cua-auto"
+version = "0.1.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pillow" },
+ { name = "pynput" },
+ { name = "pyperclip" },
+ { name = "pywinctl" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/69/e8/98e6ecc7a3db4d7b4ba60f990423ad3556af018a750beb08900eef47e607/cua_auto-0.1.2.tar.gz", hash = "sha256:2c5ac6002b12d08b03940e1f8ee547ed206f8b20280380dc8a688b0ab4a56d34", size = 12574, upload-time = "2026-02-26T14:12:09.905Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/d9/c3/f82cf30b457b9ff6fe3104caa9cd45d35edc1f184ff4b85fbcbbbc1f5262/cua_auto-0.1.2-py3-none-any.whl", hash = "sha256:d4e4bb9d5121791b6daf85779dd223f1aca9801836dd5bf2f322a01983c5328c", size = 13164, upload-time = "2026-02-26T14:12:08.802Z" },
+]
+
+[[package]]
+name = "cua-sandbox"
+version = "0.1.0"
+source = { editable = "." }
+dependencies = [
+ { name = "cua-auto" },
+ { name = "grpcio" },
+ { name = "httpx" },
+ { name = "oras" },
+ { name = "paramiko" },
+ { name = "protobuf" },
+ { name = "vncdotool" },
+ { name = "websockets" },
+]
+
+[package.optional-dependencies]
+auth = [
+ { name = "webbrowser-open" },
+]
+dev = [
+ { name = "pytest" },
+ { name = "pytest-asyncio" },
+ { name = "ruff" },
+]
+
+[package.dev-dependencies]
+dev = [
+ { name = "pytest" },
+ { name = "pytest-asyncio" },
+]
+
+[package.metadata]
+requires-dist = [
+ { name = "cua-auto", specifier = ">=0.1.2" },
+ { name = "grpcio", specifier = "==1.78.0" },
+ { name = "httpx", specifier = ">=0.27.0" },
+ { name = "oras", specifier = ">=0.2.40" },
+ { name = "paramiko", specifier = ">=4.0.0" },
+ { name = "protobuf", specifier = "==6.31.1" },
+ { name = "pytest", marker = "extra == 'dev'", specifier = ">=8.0.0" },
+ { name = "pytest-asyncio", marker = "extra == 'dev'", specifier = ">=0.23.0" },
+ { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.1.0" },
+ { name = "vncdotool", specifier = ">=1.2.0" },
+ { name = "webbrowser-open", marker = "extra == 'auth'", specifier = ">=0.0.1" },
+ { name = "websockets", specifier = ">=12.0" },
+]
+provides-extras = ["auth", "dev"]
+
+[package.metadata.requires-dev]
+dev = [
+ { name = "pytest", specifier = ">=9.0.2" },
+ { name = "pytest-asyncio", specifier = ">=1.3.0" },
+]
+
+[[package]]
+name = "evdev"
+version = "1.9.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/a5/f5/397b61091120a9ca5001041dd7bf76c385b3bfd67a0e5bcb74b852bd22a4/evdev-1.9.3.tar.gz", hash = "sha256:2c140e01ac8437758fa23fe5c871397412461f42d421aa20241dc8fe8cfccbc9", size = 32723, upload-time = "2026-02-05T21:54:24.987Z" }
+
+[[package]]
+name = "ewmhlib"
+version = "0.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "python-xlib", marker = "sys_platform == 'linux'" },
+ { name = "typing-extensions" },
+]
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/2f/3a/46ca34abf0725a754bc44ef474ad34aedcc3ea23b052d97b18b76715a6a9/EWMHlib-0.2-py3-none-any.whl", hash = "sha256:f5b07d8cfd4c7734462ee744c32d490f2f3233fa7ab354240069344208d2f6f5", size = 46657, upload-time = "2024-04-17T08:15:56.338Z" },
+]
+
+[[package]]
+name = "grpcio"
+version = "1.78.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/06/8a/3d098f35c143a89520e568e6539cc098fcd294495910e359889ce8741c84/grpcio-1.78.0.tar.gz", hash = "sha256:7382b95189546f375c174f53a5fa873cef91c4b8005faa05cc5b3beea9c4f1c5", size = 12852416, upload-time = "2026-02-06T09:57:18.093Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/86/c7/d0b780a29b0837bf4ca9580904dfb275c1fc321ded7897d620af7047ec57/grpcio-1.78.0-cp311-cp311-linux_armv7l.whl", hash = "sha256:2777b783f6c13b92bd7b716667452c329eefd646bfb3f2e9dabea2e05dbd34f6", size = 5951525, upload-time = "2026-02-06T09:55:01.989Z" },
+ { url = "https://files.pythonhosted.org/packages/c5/b1/96920bf2ee61df85a9503cb6f733fe711c0ff321a5a697d791b075673281/grpcio-1.78.0-cp311-cp311-macosx_11_0_universal2.whl", hash = "sha256:9dca934f24c732750389ce49d638069c3892ad065df86cb465b3fa3012b70c9e", size = 11830418, upload-time = "2026-02-06T09:55:04.462Z" },
+ { url = "https://files.pythonhosted.org/packages/83/0c/7c1528f098aeb75a97de2bae18c530f56959fb7ad6c882db45d9884d6edc/grpcio-1.78.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:459ab414b35f4496138d0ecd735fed26f1318af5e52cb1efbc82a09f0d5aa911", size = 6524477, upload-time = "2026-02-06T09:55:07.111Z" },
+ { url = "https://files.pythonhosted.org/packages/8d/52/e7c1f3688f949058e19a011c4e0dec973da3d0ae5e033909677f967ae1f4/grpcio-1.78.0-cp311-cp311-manylinux2014_i686.manylinux_2_17_i686.whl", hash = "sha256:082653eecbdf290e6e3e2c276ab2c54b9e7c299e07f4221872380312d8cf395e", size = 7198266, upload-time = "2026-02-06T09:55:10.016Z" },
+ { url = "https://files.pythonhosted.org/packages/e5/61/8ac32517c1e856677282c34f2e7812d6c328fa02b8f4067ab80e77fdc9c9/grpcio-1.78.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:85f93781028ec63f383f6bc90db785a016319c561cc11151fbb7b34e0d012303", size = 6730552, upload-time = "2026-02-06T09:55:12.207Z" },
+ { url = "https://files.pythonhosted.org/packages/bd/98/b8ee0158199250220734f620b12e4a345955ac7329cfd908d0bf0fda77f0/grpcio-1.78.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:f12857d24d98441af6a1d5c87442d624411db486f7ba12550b07788f74b67b04", size = 7304296, upload-time = "2026-02-06T09:55:15.044Z" },
+ { url = "https://files.pythonhosted.org/packages/bd/0f/7b72762e0d8840b58032a56fdbd02b78fc645b9fa993d71abf04edbc54f4/grpcio-1.78.0-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:5397fff416b79e4b284959642a4e95ac4b0f1ece82c9993658e0e477d40551ec", size = 8288298, upload-time = "2026-02-06T09:55:17.276Z" },
+ { url = "https://files.pythonhosted.org/packages/24/ae/ae4ce56bc5bb5caa3a486d60f5f6083ac3469228faa734362487176c15c5/grpcio-1.78.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:fbe6e89c7ffb48518384068321621b2a69cab509f58e40e4399fdd378fa6d074", size = 7730953, upload-time = "2026-02-06T09:55:19.545Z" },
+ { url = "https://files.pythonhosted.org/packages/b5/6e/8052e3a28eb6a820c372b2eb4b5e32d195c661e137d3eca94d534a4cfd8a/grpcio-1.78.0-cp311-cp311-win32.whl", hash = "sha256:6092beabe1966a3229f599d7088b38dfc8ffa1608b5b5cdda31e591e6500f856", size = 4076503, upload-time = "2026-02-06T09:55:21.521Z" },
+ { url = "https://files.pythonhosted.org/packages/08/62/f22c98c5265dfad327251fa2f840b591b1df5f5e15d88b19c18c86965b27/grpcio-1.78.0-cp311-cp311-win_amd64.whl", hash = "sha256:1afa62af6e23f88629f2b29ec9e52ec7c65a7176c1e0a83292b93c76ca882558", size = 4799767, upload-time = "2026-02-06T09:55:24.107Z" },
+ { url = "https://files.pythonhosted.org/packages/4e/f4/7384ed0178203d6074446b3c4f46c90a22ddf7ae0b3aee521627f54cfc2a/grpcio-1.78.0-cp312-cp312-linux_armv7l.whl", hash = "sha256:f9ab915a267fc47c7e88c387a3a28325b58c898e23d4995f765728f4e3dedb97", size = 5913985, upload-time = "2026-02-06T09:55:26.832Z" },
+ { url = "https://files.pythonhosted.org/packages/81/ed/be1caa25f06594463f685b3790b320f18aea49b33166f4141bfdc2bfb236/grpcio-1.78.0-cp312-cp312-macosx_11_0_universal2.whl", hash = "sha256:3f8904a8165ab21e07e58bf3e30a73f4dffc7a1e0dbc32d51c61b5360d26f43e", size = 11811853, upload-time = "2026-02-06T09:55:29.224Z" },
+ { url = "https://files.pythonhosted.org/packages/24/a7/f06d151afc4e64b7e3cc3e872d331d011c279aaab02831e40a81c691fb65/grpcio-1.78.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:859b13906ce098c0b493af92142ad051bf64c7870fa58a123911c88606714996", size = 6475766, upload-time = "2026-02-06T09:55:31.825Z" },
+ { url = "https://files.pythonhosted.org/packages/8a/a8/4482922da832ec0082d0f2cc3a10976d84a7424707f25780b82814aafc0a/grpcio-1.78.0-cp312-cp312-manylinux2014_i686.manylinux_2_17_i686.whl", hash = "sha256:b2342d87af32790f934a79c3112641e7b27d63c261b8b4395350dad43eff1dc7", size = 7170027, upload-time = "2026-02-06T09:55:34.7Z" },
+ { url = "https://files.pythonhosted.org/packages/54/bf/f4a3b9693e35d25b24b0b39fa46d7d8a3c439e0a3036c3451764678fec20/grpcio-1.78.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:12a771591ae40bc65ba67048fa52ef4f0e6db8279e595fd349f9dfddeef571f9", size = 6690766, upload-time = "2026-02-06T09:55:36.902Z" },
+ { url = "https://files.pythonhosted.org/packages/c7/b9/521875265cc99fe5ad4c5a17010018085cae2810a928bf15ebe7d8bcd9cc/grpcio-1.78.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:185dea0d5260cbb2d224c507bf2a5444d5abbb1fa3594c1ed7e4c709d5eb8383", size = 7266161, upload-time = "2026-02-06T09:55:39.824Z" },
+ { url = "https://files.pythonhosted.org/packages/05/86/296a82844fd40a4ad4a95f100b55044b4f817dece732bf686aea1a284147/grpcio-1.78.0-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:51b13f9aed9d59ee389ad666b8c2214cc87b5de258fa712f9ab05f922e3896c6", size = 8253303, upload-time = "2026-02-06T09:55:42.353Z" },
+ { url = "https://files.pythonhosted.org/packages/f3/e4/ea3c0caf5468537f27ad5aab92b681ed7cc0ef5f8c9196d3fd42c8c2286b/grpcio-1.78.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:fd5f135b1bd58ab088930b3c613455796dfa0393626a6972663ccdda5b4ac6ce", size = 7698222, upload-time = "2026-02-06T09:55:44.629Z" },
+ { url = "https://files.pythonhosted.org/packages/d7/47/7f05f81e4bb6b831e93271fb12fd52ba7b319b5402cbc101d588f435df00/grpcio-1.78.0-cp312-cp312-win32.whl", hash = "sha256:94309f498bcc07e5a7d16089ab984d42ad96af1d94b5a4eb966a266d9fcabf68", size = 4066123, upload-time = "2026-02-06T09:55:47.644Z" },
+ { url = "https://files.pythonhosted.org/packages/ad/e7/d6914822c88aa2974dbbd10903d801a28a19ce9cd8bad7e694cbbcf61528/grpcio-1.78.0-cp312-cp312-win_amd64.whl", hash = "sha256:9566fe4ababbb2610c39190791e5b829869351d14369603702e890ef3ad2d06e", size = 4797657, upload-time = "2026-02-06T09:55:49.86Z" },
+ { url = "https://files.pythonhosted.org/packages/05/a9/8f75894993895f361ed8636cd9237f4ab39ef87fd30db17467235ed1c045/grpcio-1.78.0-cp313-cp313-linux_armv7l.whl", hash = "sha256:ce3a90455492bf8bfa38e56fbbe1dbd4f872a3d8eeaf7337dc3b1c8aa28c271b", size = 5920143, upload-time = "2026-02-06T09:55:52.035Z" },
+ { url = "https://files.pythonhosted.org/packages/55/06/0b78408e938ac424100100fd081189451b472236e8a3a1f6500390dc4954/grpcio-1.78.0-cp313-cp313-macosx_11_0_universal2.whl", hash = "sha256:2bf5e2e163b356978b23652c4818ce4759d40f4712ee9ec5a83c4be6f8c23a3a", size = 11803926, upload-time = "2026-02-06T09:55:55.494Z" },
+ { url = "https://files.pythonhosted.org/packages/88/93/b59fe7832ff6ae3c78b813ea43dac60e295fa03606d14d89d2e0ec29f4f3/grpcio-1.78.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:8f2ac84905d12918e4e55a16da17939eb63e433dc11b677267c35568aa63fc84", size = 6478628, upload-time = "2026-02-06T09:55:58.533Z" },
+ { url = "https://files.pythonhosted.org/packages/ed/df/e67e3734527f9926b7d9c0dde6cd998d1d26850c3ed8eeec81297967ac67/grpcio-1.78.0-cp313-cp313-manylinux2014_i686.manylinux_2_17_i686.whl", hash = "sha256:b58f37edab4a3881bc6c9bca52670610e0c9ca14e2ea3cf9debf185b870457fb", size = 7173574, upload-time = "2026-02-06T09:56:01.786Z" },
+ { url = "https://files.pythonhosted.org/packages/a6/62/cc03fffb07bfba982a9ec097b164e8835546980aec25ecfa5f9c1a47e022/grpcio-1.78.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:735e38e176a88ce41840c21bb49098ab66177c64c82426e24e0082500cc68af5", size = 6692639, upload-time = "2026-02-06T09:56:04.529Z" },
+ { url = "https://files.pythonhosted.org/packages/bf/9a/289c32e301b85bdb67d7ec68b752155e674ee3ba2173a1858f118e399ef3/grpcio-1.78.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:2045397e63a7a0ee7957c25f7dbb36ddc110e0cfb418403d110c0a7a68a844e9", size = 7268838, upload-time = "2026-02-06T09:56:08.397Z" },
+ { url = "https://files.pythonhosted.org/packages/0e/79/1be93f32add280461fa4773880196572563e9c8510861ac2da0ea0f892b6/grpcio-1.78.0-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:a9f136fbafe7ccf4ac7e8e0c28b31066e810be52d6e344ef954a3a70234e1702", size = 8251878, upload-time = "2026-02-06T09:56:10.914Z" },
+ { url = "https://files.pythonhosted.org/packages/65/65/793f8e95296ab92e4164593674ae6291b204bb5f67f9d4a711489cd30ffa/grpcio-1.78.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:748b6138585379c737adc08aeffd21222abbda1a86a0dca2a39682feb9196c20", size = 7695412, upload-time = "2026-02-06T09:56:13.593Z" },
+ { url = "https://files.pythonhosted.org/packages/1c/9f/1e233fe697ecc82845942c2822ed06bb522e70d6771c28d5528e4c50f6a4/grpcio-1.78.0-cp313-cp313-win32.whl", hash = "sha256:271c73e6e5676afe4fc52907686670c7cea22ab2310b76a59b678403ed40d670", size = 4064899, upload-time = "2026-02-06T09:56:15.601Z" },
+ { url = "https://files.pythonhosted.org/packages/4d/27/d86b89e36de8a951501fb06a0f38df19853210f341d0b28f83f4aa0ffa08/grpcio-1.78.0-cp313-cp313-win_amd64.whl", hash = "sha256:f2d4e43ee362adfc05994ed479334d5a451ab7bc3f3fee1b796b8ca66895acb4", size = 4797393, upload-time = "2026-02-06T09:56:17.882Z" },
+]
+
+[[package]]
+name = "h11"
+version = "0.16.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/01/ee/02a2c011bdab74c6fb3c75474d40b3052059d95df7e73351460c8588d963/h11-0.16.0.tar.gz", hash = "sha256:4e35b956cf45792e4caa5885e69fba00bdbc6ffafbfa020300e549b208ee5ff1", size = 101250, upload-time = "2025-04-24T03:35:25.427Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/04/4b/29cac41a4d98d144bf5f6d33995617b185d14b22401f75ca86f384e87ff1/h11-0.16.0-py3-none-any.whl", hash = "sha256:63cf8bbe7522de3bf65932fda1d9c2772064ffb3dae62d55932da54b31cb6c86", size = 37515, upload-time = "2025-04-24T03:35:24.344Z" },
+]
+
+[[package]]
+name = "httpcore"
+version = "1.0.9"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "certifi" },
+ { name = "h11" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/06/94/82699a10bca87a5556c9c59b5963f2d039dbd239f25bc2a63907a05a14cb/httpcore-1.0.9.tar.gz", hash = "sha256:6e34463af53fd2ab5d807f399a9b45ea31c3dfa2276f15a2c3f00afff6e176e8", size = 85484, upload-time = "2025-04-24T22:06:22.219Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/7e/f5/f66802a942d491edb555dd61e3a9961140fd64c90bce1eafd741609d334d/httpcore-1.0.9-py3-none-any.whl", hash = "sha256:2d400746a40668fc9dec9810239072b40b4484b640a8c38fd654a024c7a1bf55", size = 78784, upload-time = "2025-04-24T22:06:20.566Z" },
+]
+
+[[package]]
+name = "httpx"
+version = "0.28.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "anyio" },
+ { name = "certifi" },
+ { name = "httpcore" },
+ { name = "idna" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b1/df/48c586a5fe32a0f01324ee087459e112ebb7224f646c0b5023f5e79e9956/httpx-0.28.1.tar.gz", hash = "sha256:75e98c5f16b0f35b567856f597f06ff2270a374470a5c2392242528e3e3e42fc", size = 141406, upload-time = "2024-12-06T15:37:23.222Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/2a/39/e50c7c3a983047577ee07d2a9e53faf5a69493943ec3f6a384bdc792deb2/httpx-0.28.1-py3-none-any.whl", hash = "sha256:d909fcccc110f8c7faf814ca82a9a4d816bc5a6dbfea25d6591d6985b8ba59ad", size = 73517, upload-time = "2024-12-06T15:37:21.509Z" },
+]
+
+[[package]]
+name = "hyperlink"
+version = "21.0.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "idna" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/3a/51/1947bd81d75af87e3bb9e34593a4cf118115a8feb451ce7a69044ef1412e/hyperlink-21.0.0.tar.gz", hash = "sha256:427af957daa58bc909471c6c40f74c5450fa123dd093fc53efd2e91d2705a56b", size = 140743, upload-time = "2021-01-08T05:51:20.972Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/6e/aa/8caf6a0a3e62863cbb9dab27135660acba46903b703e224f14f447e57934/hyperlink-21.0.0-py2.py3-none-any.whl", hash = "sha256:e6b14c37ecb73e89c77d78cdb4c2cc8f3fb59a885c5b3f819ff4ed80f25af1b4", size = 74638, upload-time = "2021-01-08T05:51:22.906Z" },
+]
+
+[[package]]
+name = "idna"
+version = "3.11"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/6f/6d/0703ccc57f3a7233505399edb88de3cbd678da106337b9fcde432b65ed60/idna-3.11.tar.gz", hash = "sha256:795dafcc9c04ed0c1fb032c2aa73654d8e8c5023a7df64a53f39190ada629902", size = 194582, upload-time = "2025-10-12T14:55:20.501Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/0e/61/66938bbb5fc52dbdf84594873d5b51fb1f7c7794e9c0f5bd885f30bc507b/idna-3.11-py3-none-any.whl", hash = "sha256:771a87f49d9defaf64091e6e6fe9c18d4833f140bd19464795bc32d966ca37ea", size = 71008, upload-time = "2025-10-12T14:55:18.883Z" },
+]
+
+[[package]]
+name = "incremental"
+version = "24.11.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "packaging" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/ef/3c/82e84109e02c492f382c711c58a3dd91badda6d746def81a1465f74dc9f5/incremental-24.11.0.tar.gz", hash = "sha256:87d3480dbb083c1d736222511a8cf380012a8176c2456d01ef483242abbbcf8c", size = 24000, upload-time = "2025-11-28T02:30:17.861Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/1d/55/0f4df2a44053867ea9cbea73fc588b03c55605cd695cee0a3d86f0029cb2/incremental-24.11.0-py3-none-any.whl", hash = "sha256:a34450716b1c4341fe6676a0598e88a39e04189f4dce5dc96f656e040baa10b3", size = 21109, upload-time = "2025-11-28T02:30:16.442Z" },
+]
+
+[[package]]
+name = "iniconfig"
+version = "2.3.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/72/34/14ca021ce8e5dfedc35312d08ba8bf51fdd999c576889fc2c24cb97f4f10/iniconfig-2.3.0.tar.gz", hash = "sha256:c76315c77db068650d49c5b56314774a7804df16fee4402c1f19d6d15d8c4730", size = 20503, upload-time = "2025-10-18T21:55:43.219Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/cb/b1/3846dd7f199d53cb17f49cba7e651e9ce294d8497c8c150530ed11865bb8/iniconfig-2.3.0-py3-none-any.whl", hash = "sha256:f631c04d2c48c52b84d0d0549c99ff3859c98df65b3101406327ecc7d53fbf12", size = 7484, upload-time = "2025-10-18T21:55:41.639Z" },
+]
+
+[[package]]
+name = "invoke"
+version = "2.2.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/de/bd/b461d3424a24c80490313fd77feeb666ca4f6a28c7e72713e3d9095719b4/invoke-2.2.1.tar.gz", hash = "sha256:515bf49b4a48932b79b024590348da22f39c4942dff991ad1fb8b8baea1be707", size = 304762, upload-time = "2025-10-11T00:36:35.172Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/32/4b/b99e37f88336009971405cbb7630610322ed6fbfa31e1d7ab3fbf3049a2d/invoke-2.2.1-py3-none-any.whl", hash = "sha256:2413bc441b376e5cd3f55bb5d364f973ad8bdd7bf87e53c79de3c11bf3feecc8", size = 160287, upload-time = "2025-10-11T00:36:33.703Z" },
+]
+
+[[package]]
+name = "jsonschema"
+version = "4.26.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "attrs" },
+ { name = "jsonschema-specifications" },
+ { name = "referencing" },
+ { name = "rpds-py" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b3/fc/e067678238fa451312d4c62bf6e6cf5ec56375422aee02f9cb5f909b3047/jsonschema-4.26.0.tar.gz", hash = "sha256:0c26707e2efad8aa1bfc5b7ce170f3fccc2e4918ff85989ba9ffa9facb2be326", size = 366583, upload-time = "2026-01-07T13:41:07.246Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/69/90/f63fb5873511e014207a475e2bb4e8b2e570d655b00ac19a9a0ca0a385ee/jsonschema-4.26.0-py3-none-any.whl", hash = "sha256:d489f15263b8d200f8387e64b4c3a75f06629559fb73deb8fdfb525f2dab50ce", size = 90630, upload-time = "2026-01-07T13:41:05.306Z" },
+]
+
+[[package]]
+name = "jsonschema-specifications"
+version = "2025.9.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "referencing" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/19/74/a633ee74eb36c44aa6d1095e7cc5569bebf04342ee146178e2d36600708b/jsonschema_specifications-2025.9.1.tar.gz", hash = "sha256:b540987f239e745613c7a9176f3edb72b832a4ac465cf02712288397832b5e8d", size = 32855, upload-time = "2025-09-08T01:34:59.186Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/41/45/1a4ed80516f02155c51f51e8cedb3c1902296743db0bbc66608a0db2814f/jsonschema_specifications-2025.9.1-py3-none-any.whl", hash = "sha256:98802fee3a11ee76ecaca44429fda8a41bff98b00a0f2838151b113f210cc6fe", size = 18437, upload-time = "2025-09-08T01:34:57.871Z" },
+]
+
+[[package]]
+name = "oras"
+version = "0.2.42"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "jsonschema" },
+ { name = "requests" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/8a/f9/e9226863b61d3e83d166e7a70a045fdacbb966dd7e7ecef81fed32cf67af/oras-0.2.42.tar.gz", hash = "sha256:51d17088e5dffdeb585dd930bdccb4329762bef4af3f18600392ebae525a9231", size = 58767, upload-time = "2026-03-09T22:31:23.216Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/03/3c/04dce40fe03276a5aaed0e2b49e59e385147f4e750e6960c477284cf5880/oras-0.2.42-py3-none-any.whl", hash = "sha256:d1e2184d42ce99258bd0ad56d932b0f4fce289bccf1b5094436a29579f385728", size = 71832, upload-time = "2026-03-09T22:31:22.145Z" },
+]
+
+[[package]]
+name = "packaging"
+version = "26.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/65/ee/299d360cdc32edc7d2cf530f3accf79c4fca01e96ffc950d8a52213bd8e4/packaging-26.0.tar.gz", hash = "sha256:00243ae351a257117b6a241061796684b084ed1c516a08c48a3f7e147a9d80b4", size = 143416, upload-time = "2026-01-21T20:50:39.064Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/b7/b9/c538f279a4e237a006a2c98387d081e9eb060d203d8ed34467cc0f0b9b53/packaging-26.0-py3-none-any.whl", hash = "sha256:b36f1fef9334a5588b4166f8bcd26a14e521f2b55e6b9de3aaa80d3ff7a37529", size = 74366, upload-time = "2026-01-21T20:50:37.788Z" },
+]
+
+[[package]]
+name = "paramiko"
+version = "4.0.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "bcrypt" },
+ { name = "cryptography" },
+ { name = "invoke" },
+ { name = "pynacl" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/1f/e7/81fdcbc7f190cdb058cffc9431587eb289833bdd633e2002455ca9bb13d4/paramiko-4.0.0.tar.gz", hash = "sha256:6a25f07b380cc9c9a88d2b920ad37167ac4667f8d9886ccebd8f90f654b5d69f", size = 1630743, upload-time = "2025-08-04T01:02:03.711Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/a9/90/a744336f5af32c433bd09af7854599682a383b37cfd78f7de263de6ad6cb/paramiko-4.0.0-py3-none-any.whl", hash = "sha256:0e20e00ac666503bf0b4eda3b6d833465a2b7aff2e2b3d79a8bba5ef144ee3b9", size = 223932, upload-time = "2025-08-04T01:02:02.029Z" },
+]
+
+[[package]]
+name = "pillow"
+version = "12.1.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/1f/42/5c74462b4fd957fcd7b13b04fb3205ff8349236ea74c7c375766d6c82288/pillow-12.1.1.tar.gz", hash = "sha256:9ad8fa5937ab05218e2b6a4cff30295ad35afd2f83ac592e68c0d871bb0fdbc4", size = 46980264, upload-time = "2026-02-11T04:23:07.146Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/2b/46/5da1ec4a5171ee7bf1a0efa064aba70ba3d6e0788ce3f5acd1375d23c8c0/pillow-12.1.1-cp311-cp311-macosx_10_10_x86_64.whl", hash = "sha256:e879bb6cd5c73848ef3b2b48b8af9ff08c5b71ecda8048b7dd22d8a33f60be32", size = 5304084, upload-time = "2026-02-11T04:20:27.501Z" },
+ { url = "https://files.pythonhosted.org/packages/78/93/a29e9bc02d1cf557a834da780ceccd54e02421627200696fcf805ebdc3fb/pillow-12.1.1-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:365b10bb9417dd4498c0e3b128018c4a624dc11c7b97d8cc54effe3b096f4c38", size = 4657866, upload-time = "2026-02-11T04:20:29.827Z" },
+ { url = "https://files.pythonhosted.org/packages/13/84/583a4558d492a179d31e4aae32eadce94b9acf49c0337c4ce0b70e0a01f2/pillow-12.1.1-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:d4ce8e329c93845720cd2014659ca67eac35f6433fd3050393d85f3ecef0dad5", size = 6232148, upload-time = "2026-02-11T04:20:31.329Z" },
+ { url = "https://files.pythonhosted.org/packages/d5/e2/53c43334bbbb2d3b938978532fbda8e62bb6e0b23a26ce8592f36bcc4987/pillow-12.1.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:fc354a04072b765eccf2204f588a7a532c9511e8b9c7f900e1b64e3e33487090", size = 8038007, upload-time = "2026-02-11T04:20:34.225Z" },
+ { url = "https://files.pythonhosted.org/packages/b8/a6/3d0e79c8a9d58150dd98e199d7c1c56861027f3829a3a60b3c2784190180/pillow-12.1.1-cp311-cp311-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:7e7976bf1910a8116b523b9f9f58bf410f3e8aa330cd9a2bb2953f9266ab49af", size = 6345418, upload-time = "2026-02-11T04:20:35.858Z" },
+ { url = "https://files.pythonhosted.org/packages/a2/c8/46dfeac5825e600579157eea177be43e2f7ff4a99da9d0d0a49533509ac5/pillow-12.1.1-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:597bd9c8419bc7c6af5604e55847789b69123bbe25d65cc6ad3012b4f3c98d8b", size = 7034590, upload-time = "2026-02-11T04:20:37.91Z" },
+ { url = "https://files.pythonhosted.org/packages/af/bf/e6f65d3db8a8bbfeaf9e13cc0417813f6319863a73de934f14b2229ada18/pillow-12.1.1-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:2c1fc0f2ca5f96a3c8407e41cca26a16e46b21060fe6d5b099d2cb01412222f5", size = 6458655, upload-time = "2026-02-11T04:20:39.496Z" },
+ { url = "https://files.pythonhosted.org/packages/f9/c2/66091f3f34a25894ca129362e510b956ef26f8fb67a0e6417bc5744e56f1/pillow-12.1.1-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:578510d88c6229d735855e1f278aa305270438d36a05031dfaae5067cc8eb04d", size = 7159286, upload-time = "2026-02-11T04:20:41.139Z" },
+ { url = "https://files.pythonhosted.org/packages/7b/5a/24bc8eb526a22f957d0cec6243146744966d40857e3d8deb68f7902ca6c1/pillow-12.1.1-cp311-cp311-win32.whl", hash = "sha256:7311c0a0dcadb89b36b7025dfd8326ecfa36964e29913074d47382706e516a7c", size = 6328663, upload-time = "2026-02-11T04:20:43.184Z" },
+ { url = "https://files.pythonhosted.org/packages/31/03/bef822e4f2d8f9d7448c133d0a18185d3cce3e70472774fffefe8b0ed562/pillow-12.1.1-cp311-cp311-win_amd64.whl", hash = "sha256:fbfa2a7c10cc2623f412753cddf391c7f971c52ca40a3f65dc5039b2939e8563", size = 7031448, upload-time = "2026-02-11T04:20:44.696Z" },
+ { url = "https://files.pythonhosted.org/packages/49/70/f76296f53610bd17b2e7d31728b8b7825e3ac3b5b3688b51f52eab7c0818/pillow-12.1.1-cp311-cp311-win_arm64.whl", hash = "sha256:b81b5e3511211631b3f672a595e3221252c90af017e399056d0faabb9538aa80", size = 2453651, upload-time = "2026-02-11T04:20:46.243Z" },
+ { url = "https://files.pythonhosted.org/packages/07/d3/8df65da0d4df36b094351dce696f2989bec731d4f10e743b1c5f4da4d3bf/pillow-12.1.1-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:ab323b787d6e18b3d91a72fc99b1a2c28651e4358749842b8f8dfacd28ef2052", size = 5262803, upload-time = "2026-02-11T04:20:47.653Z" },
+ { url = "https://files.pythonhosted.org/packages/d6/71/5026395b290ff404b836e636f51d7297e6c83beceaa87c592718747e670f/pillow-12.1.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:adebb5bee0f0af4909c30db0d890c773d1a92ffe83da908e2e9e720f8edf3984", size = 4657601, upload-time = "2026-02-11T04:20:49.328Z" },
+ { url = "https://files.pythonhosted.org/packages/b1/2e/1001613d941c67442f745aff0f7cc66dd8df9a9c084eb497e6a543ee6f7e/pillow-12.1.1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:bb66b7cc26f50977108790e2456b7921e773f23db5630261102233eb355a3b79", size = 6234995, upload-time = "2026-02-11T04:20:51.032Z" },
+ { url = "https://files.pythonhosted.org/packages/07/26/246ab11455b2549b9233dbd44d358d033a2f780fa9007b61a913c5b2d24e/pillow-12.1.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:aee2810642b2898bb187ced9b349e95d2a7272930796e022efaf12e99dccd293", size = 8045012, upload-time = "2026-02-11T04:20:52.882Z" },
+ { url = "https://files.pythonhosted.org/packages/b2/8b/07587069c27be7535ac1fe33874e32de118fbd34e2a73b7f83436a88368c/pillow-12.1.1-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a0b1cd6232e2b618adcc54d9882e4e662a089d5768cd188f7c245b4c8c44a397", size = 6349638, upload-time = "2026-02-11T04:20:54.444Z" },
+ { url = "https://files.pythonhosted.org/packages/ff/79/6df7b2ee763d619cda2fb4fea498e5f79d984dae304d45a8999b80d6cf5c/pillow-12.1.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:7aac39bcf8d4770d089588a2e1dd111cbaa42df5a94be3114222057d68336bd0", size = 7041540, upload-time = "2026-02-11T04:20:55.97Z" },
+ { url = "https://files.pythonhosted.org/packages/2c/5e/2ba19e7e7236d7529f4d873bdaf317a318896bac289abebd4bb00ef247f0/pillow-12.1.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:ab174cd7d29a62dd139c44bf74b698039328f45cb03b4596c43473a46656b2f3", size = 6462613, upload-time = "2026-02-11T04:20:57.542Z" },
+ { url = "https://files.pythonhosted.org/packages/03/03/31216ec124bb5c3dacd74ce8efff4cc7f52643653bad4825f8f08c697743/pillow-12.1.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:339ffdcb7cbeaa08221cd401d517d4b1fe7a9ed5d400e4a8039719238620ca35", size = 7166745, upload-time = "2026-02-11T04:20:59.196Z" },
+ { url = "https://files.pythonhosted.org/packages/1f/e7/7c4552d80052337eb28653b617eafdef39adfb137c49dd7e831b8dc13bc5/pillow-12.1.1-cp312-cp312-win32.whl", hash = "sha256:5d1f9575a12bed9e9eedd9a4972834b08c97a352bd17955ccdebfeca5913fa0a", size = 6328823, upload-time = "2026-02-11T04:21:01.385Z" },
+ { url = "https://files.pythonhosted.org/packages/3d/17/688626d192d7261bbbf98846fc98995726bddc2c945344b65bec3a29d731/pillow-12.1.1-cp312-cp312-win_amd64.whl", hash = "sha256:21329ec8c96c6e979cd0dfd29406c40c1d52521a90544463057d2aaa937d66a6", size = 7033367, upload-time = "2026-02-11T04:21:03.536Z" },
+ { url = "https://files.pythonhosted.org/packages/ed/fe/a0ef1f73f939b0eca03ee2c108d0043a87468664770612602c63266a43c4/pillow-12.1.1-cp312-cp312-win_arm64.whl", hash = "sha256:af9a332e572978f0218686636610555ae3defd1633597be015ed50289a03c523", size = 2453811, upload-time = "2026-02-11T04:21:05.116Z" },
+ { url = "https://files.pythonhosted.org/packages/d5/11/6db24d4bd7685583caeae54b7009584e38da3c3d4488ed4cd25b439de486/pillow-12.1.1-cp313-cp313-ios_13_0_arm64_iphoneos.whl", hash = "sha256:d242e8ac078781f1de88bf823d70c1a9b3c7950a44cdf4b7c012e22ccbcd8e4e", size = 4062689, upload-time = "2026-02-11T04:21:06.804Z" },
+ { url = "https://files.pythonhosted.org/packages/33/c0/ce6d3b1fe190f0021203e0d9b5b99e57843e345f15f9ef22fcd43842fd21/pillow-12.1.1-cp313-cp313-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:02f84dfad02693676692746df05b89cf25597560db2857363a208e393429f5e9", size = 4138535, upload-time = "2026-02-11T04:21:08.452Z" },
+ { url = "https://files.pythonhosted.org/packages/a0/c6/d5eb6a4fb32a3f9c21a8c7613ec706534ea1cf9f4b3663e99f0d83f6fca8/pillow-12.1.1-cp313-cp313-ios_13_0_x86_64_iphonesimulator.whl", hash = "sha256:e65498daf4b583091ccbb2556c7000abf0f3349fcd57ef7adc9a84a394ed29f6", size = 3601364, upload-time = "2026-02-11T04:21:10.194Z" },
+ { url = "https://files.pythonhosted.org/packages/14/a1/16c4b823838ba4c9c52c0e6bbda903a3fe5a1bdbf1b8eb4fff7156f3e318/pillow-12.1.1-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:6c6db3b84c87d48d0088943bf33440e0c42370b99b1c2a7989216f7b42eede60", size = 5262561, upload-time = "2026-02-11T04:21:11.742Z" },
+ { url = "https://files.pythonhosted.org/packages/bb/ad/ad9dc98ff24f485008aa5cdedaf1a219876f6f6c42a4626c08bc4e80b120/pillow-12.1.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:8b7e5304e34942bf62e15184219a7b5ad4ff7f3bb5cca4d984f37df1a0e1aee2", size = 4657460, upload-time = "2026-02-11T04:21:13.786Z" },
+ { url = "https://files.pythonhosted.org/packages/9e/1b/f1a4ea9a895b5732152789326202a82464d5254759fbacae4deea3069334/pillow-12.1.1-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:18e5bddd742a44b7e6b1e773ab5db102bd7a94c32555ba656e76d319d19c3850", size = 6232698, upload-time = "2026-02-11T04:21:15.949Z" },
+ { url = "https://files.pythonhosted.org/packages/95/f4/86f51b8745070daf21fd2e5b1fe0eb35d4db9ca26e6d58366562fb56a743/pillow-12.1.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:fc44ef1f3de4f45b50ccf9136999d71abb99dca7706bc75d222ed350b9fd2289", size = 8041706, upload-time = "2026-02-11T04:21:17.723Z" },
+ { url = "https://files.pythonhosted.org/packages/29/9b/d6ecd956bb1266dd1045e995cce9b8d77759e740953a1c9aad9502a0461e/pillow-12.1.1-cp313-cp313-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:5a8eb7ed8d4198bccbd07058416eeec51686b498e784eda166395a23eb99138e", size = 6346621, upload-time = "2026-02-11T04:21:19.547Z" },
+ { url = "https://files.pythonhosted.org/packages/71/24/538bff45bde96535d7d998c6fed1a751c75ac7c53c37c90dc2601b243893/pillow-12.1.1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:47b94983da0c642de92ced1702c5b6c292a84bd3a8e1d1702ff923f183594717", size = 7038069, upload-time = "2026-02-11T04:21:21.378Z" },
+ { url = "https://files.pythonhosted.org/packages/94/0e/58cb1a6bc48f746bc4cb3adb8cabff73e2742c92b3bf7a220b7cf69b9177/pillow-12.1.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:518a48c2aab7ce596d3bf79d0e275661b846e86e4d0e7dec34712c30fe07f02a", size = 6460040, upload-time = "2026-02-11T04:21:23.148Z" },
+ { url = "https://files.pythonhosted.org/packages/6c/57/9045cb3ff11eeb6c1adce3b2d60d7d299d7b273a2e6c8381a524abfdc474/pillow-12.1.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:a550ae29b95c6dc13cf69e2c9dc5747f814c54eeb2e32d683e5e93af56caa029", size = 7164523, upload-time = "2026-02-11T04:21:25.01Z" },
+ { url = "https://files.pythonhosted.org/packages/73/f2/9be9cb99f2175f0d4dbadd6616ce1bf068ee54a28277ea1bf1fbf729c250/pillow-12.1.1-cp313-cp313-win32.whl", hash = "sha256:a003d7422449f6d1e3a34e3dd4110c22148336918ddbfc6a32581cd54b2e0b2b", size = 6332552, upload-time = "2026-02-11T04:21:27.238Z" },
+ { url = "https://files.pythonhosted.org/packages/3f/eb/b0834ad8b583d7d9d42b80becff092082a1c3c156bb582590fcc973f1c7c/pillow-12.1.1-cp313-cp313-win_amd64.whl", hash = "sha256:344cf1e3dab3be4b1fa08e449323d98a2a3f819ad20f4b22e77a0ede31f0faa1", size = 7040108, upload-time = "2026-02-11T04:21:29.462Z" },
+ { url = "https://files.pythonhosted.org/packages/d5/7d/fc09634e2aabdd0feabaff4a32f4a7d97789223e7c2042fd805ea4b4d2c2/pillow-12.1.1-cp313-cp313-win_arm64.whl", hash = "sha256:5c0dd1636633e7e6a0afe7bf6a51a14992b7f8e60de5789018ebbdfae55b040a", size = 2453712, upload-time = "2026-02-11T04:21:31.072Z" },
+ { url = "https://files.pythonhosted.org/packages/19/2a/b9d62794fc8a0dd14c1943df68347badbd5511103e0d04c035ffe5cf2255/pillow-12.1.1-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:0330d233c1a0ead844fc097a7d16c0abff4c12e856c0b325f231820fee1f39da", size = 5264880, upload-time = "2026-02-11T04:21:32.865Z" },
+ { url = "https://files.pythonhosted.org/packages/26/9d/e03d857d1347fa5ed9247e123fcd2a97b6220e15e9cb73ca0a8d91702c6e/pillow-12.1.1-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:5dae5f21afb91322f2ff791895ddd8889e5e947ff59f71b46041c8ce6db790bc", size = 4660616, upload-time = "2026-02-11T04:21:34.97Z" },
+ { url = "https://files.pythonhosted.org/packages/f7/ec/8a6d22afd02570d30954e043f09c32772bfe143ba9285e2fdb11284952cd/pillow-12.1.1-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:2e0c664be47252947d870ac0d327fea7e63985a08794758aa8af5b6cb6ec0c9c", size = 6269008, upload-time = "2026-02-11T04:21:36.623Z" },
+ { url = "https://files.pythonhosted.org/packages/3d/1d/6d875422c9f28a4a361f495a5f68d9de4a66941dc2c619103ca335fa6446/pillow-12.1.1-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:691ab2ac363b8217f7d31b3497108fb1f50faab2f75dfb03284ec2f217e87bf8", size = 8073226, upload-time = "2026-02-11T04:21:38.585Z" },
+ { url = "https://files.pythonhosted.org/packages/a1/cd/134b0b6ee5eda6dc09e25e24b40fdafe11a520bc725c1d0bbaa5e00bf95b/pillow-12.1.1-cp313-cp313t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:e9e8064fb1cc019296958595f6db671fba95209e3ceb0c4734c9baf97de04b20", size = 6380136, upload-time = "2026-02-11T04:21:40.562Z" },
+ { url = "https://files.pythonhosted.org/packages/7a/a9/7628f013f18f001c1b98d8fffe3452f306a70dc6aba7d931019e0492f45e/pillow-12.1.1-cp313-cp313t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:472a8d7ded663e6162dafdf20015c486a7009483ca671cece7a9279b512fcb13", size = 7067129, upload-time = "2026-02-11T04:21:42.521Z" },
+ { url = "https://files.pythonhosted.org/packages/1e/f8/66ab30a2193b277785601e82ee2d49f68ea575d9637e5e234faaa98efa4c/pillow-12.1.1-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:89b54027a766529136a06cfebeecb3a04900397a3590fd252160b888479517bf", size = 6491807, upload-time = "2026-02-11T04:21:44.22Z" },
+ { url = "https://files.pythonhosted.org/packages/da/0b/a877a6627dc8318fdb84e357c5e1a758c0941ab1ddffdafd231983788579/pillow-12.1.1-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:86172b0831b82ce4f7877f280055892b31179e1576aa00d0df3bb1bbf8c3e524", size = 7190954, upload-time = "2026-02-11T04:21:46.114Z" },
+ { url = "https://files.pythonhosted.org/packages/83/43/6f732ff85743cf746b1361b91665d9f5155e1483817f693f8d57ea93147f/pillow-12.1.1-cp313-cp313t-win32.whl", hash = "sha256:44ce27545b6efcf0fdbdceb31c9a5bdea9333e664cda58a7e674bb74608b3986", size = 6336441, upload-time = "2026-02-11T04:21:48.22Z" },
+ { url = "https://files.pythonhosted.org/packages/3b/44/e865ef3986611bb75bfabdf94a590016ea327833f434558801122979cd0e/pillow-12.1.1-cp313-cp313t-win_amd64.whl", hash = "sha256:a285e3eb7a5a45a2ff504e31f4a8d1b12ef62e84e5411c6804a42197c1cf586c", size = 7045383, upload-time = "2026-02-11T04:21:50.015Z" },
+ { url = "https://files.pythonhosted.org/packages/a8/c6/f4fb24268d0c6908b9f04143697ea18b0379490cb74ba9e8d41b898bd005/pillow-12.1.1-cp313-cp313t-win_arm64.whl", hash = "sha256:cc7d296b5ea4d29e6570dabeaed58d31c3fea35a633a69679fb03d7664f43fb3", size = 2456104, upload-time = "2026-02-11T04:21:51.633Z" },
+ { url = "https://files.pythonhosted.org/packages/56/11/5d43209aa4cb58e0cc80127956ff1796a68b928e6324bbf06ef4db34367b/pillow-12.1.1-pp311-pypy311_pp73-macosx_10_15_x86_64.whl", hash = "sha256:600fd103672b925fe62ed08e0d874ea34d692474df6f4bf7ebe148b30f89f39f", size = 5228606, upload-time = "2026-02-11T04:22:52.106Z" },
+ { url = "https://files.pythonhosted.org/packages/5f/d5/3b005b4e4fda6698b371fa6c21b097d4707585d7db99e98d9b0b87ac612a/pillow-12.1.1-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:665e1b916b043cef294bc54d47bf02d87e13f769bc4bc5fa225a24b3a6c5aca9", size = 4622321, upload-time = "2026-02-11T04:22:53.827Z" },
+ { url = "https://files.pythonhosted.org/packages/df/36/ed3ea2d594356fd8037e5a01f6156c74bc8d92dbb0fa60746cc96cabb6e8/pillow-12.1.1-pp311-pypy311_pp73-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:495c302af3aad1ca67420ddd5c7bd480c8867ad173528767d906428057a11f0e", size = 5247579, upload-time = "2026-02-11T04:22:56.094Z" },
+ { url = "https://files.pythonhosted.org/packages/54/9a/9cc3e029683cf6d20ae5085da0dafc63148e3252c2f13328e553aaa13cfb/pillow-12.1.1-pp311-pypy311_pp73-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:8fd420ef0c52c88b5a035a0886f367748c72147b2b8f384c9d12656678dfdfa9", size = 6989094, upload-time = "2026-02-11T04:22:58.288Z" },
+ { url = "https://files.pythonhosted.org/packages/00/98/fc53ab36da80b88df0967896b6c4b4cd948a0dc5aa40a754266aa3ae48b3/pillow-12.1.1-pp311-pypy311_pp73-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f975aa7ef9684ce7e2c18a3aa8f8e2106ce1e46b94ab713d156b2898811651d3", size = 5313850, upload-time = "2026-02-11T04:23:00.554Z" },
+ { url = "https://files.pythonhosted.org/packages/30/02/00fa585abfd9fe9d73e5f6e554dc36cc2b842898cbfc46d70353dae227f8/pillow-12.1.1-pp311-pypy311_pp73-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:8089c852a56c2966cf18835db62d9b34fef7ba74c726ad943928d494fa7f4735", size = 5963343, upload-time = "2026-02-11T04:23:02.934Z" },
+ { url = "https://files.pythonhosted.org/packages/f2/26/c56ce33ca856e358d27fda9676c055395abddb82c35ac0f593877ed4562e/pillow-12.1.1-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:cb9bb857b2d057c6dfc72ac5f3b44836924ba15721882ef103cecb40d002d80e", size = 7029880, upload-time = "2026-02-11T04:23:04.783Z" },
+]
+
+[[package]]
+name = "pluggy"
+version = "1.6.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f9/e2/3e91f31a7d2b083fe6ef3fa267035b518369d9511ffab804f839851d2779/pluggy-1.6.0.tar.gz", hash = "sha256:7dcc130b76258d33b90f61b658791dede3486c3e6bfb003ee5c9bfb396dd22f3", size = 69412, upload-time = "2025-05-15T12:30:07.975Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/54/20/4d324d65cc6d9205fabedc306948156824eb9f0ee1633355a8f7ec5c66bf/pluggy-1.6.0-py3-none-any.whl", hash = "sha256:e920276dd6813095e9377c0bc5566d94c932c33b27a3e3945d8389c374dd4746", size = 20538, upload-time = "2025-05-15T12:30:06.134Z" },
+]
+
+[[package]]
+name = "protobuf"
+version = "6.31.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/52/f3/b9655a711b32c19720253f6f06326faf90580834e2e83f840472d752bc8b/protobuf-6.31.1.tar.gz", hash = "sha256:d8cac4c982f0b957a4dc73a80e2ea24fab08e679c0de9deb835f4a12d69aca9a", size = 441797, upload-time = "2025-05-28T19:25:54.947Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/f3/6f/6ab8e4bf962fd5570d3deaa2d5c38f0a363f57b4501047b5ebeb83ab1125/protobuf-6.31.1-cp310-abi3-win32.whl", hash = "sha256:7fa17d5a29c2e04b7d90e5e32388b8bfd0e7107cd8e616feef7ed3fa6bdab5c9", size = 423603, upload-time = "2025-05-28T19:25:41.198Z" },
+ { url = "https://files.pythonhosted.org/packages/44/3a/b15c4347dd4bf3a1b0ee882f384623e2063bb5cf9fa9d57990a4f7df2fb6/protobuf-6.31.1-cp310-abi3-win_amd64.whl", hash = "sha256:426f59d2964864a1a366254fa703b8632dcec0790d8862d30034d8245e1cd447", size = 435283, upload-time = "2025-05-28T19:25:44.275Z" },
+ { url = "https://files.pythonhosted.org/packages/6a/c9/b9689a2a250264a84e66c46d8862ba788ee7a641cdca39bccf64f59284b7/protobuf-6.31.1-cp39-abi3-macosx_10_9_universal2.whl", hash = "sha256:6f1227473dc43d44ed644425268eb7c2e488ae245d51c6866d19fe158e207402", size = 425604, upload-time = "2025-05-28T19:25:45.702Z" },
+ { url = "https://files.pythonhosted.org/packages/76/a1/7a5a94032c83375e4fe7e7f56e3976ea6ac90c5e85fac8576409e25c39c3/protobuf-6.31.1-cp39-abi3-manylinux2014_aarch64.whl", hash = "sha256:a40fc12b84c154884d7d4c4ebd675d5b3b5283e155f324049ae396b95ddebc39", size = 322115, upload-time = "2025-05-28T19:25:47.128Z" },
+ { url = "https://files.pythonhosted.org/packages/fa/b1/b59d405d64d31999244643d88c45c8241c58f17cc887e73bcb90602327f8/protobuf-6.31.1-cp39-abi3-manylinux2014_x86_64.whl", hash = "sha256:4ee898bf66f7a8b0bd21bce523814e6fbd8c6add948045ce958b73af7e8878c6", size = 321070, upload-time = "2025-05-28T19:25:50.036Z" },
+ { url = "https://files.pythonhosted.org/packages/f7/af/ab3c51ab7507a7325e98ffe691d9495ee3d3aa5f589afad65ec920d39821/protobuf-6.31.1-py3-none-any.whl", hash = "sha256:720a6c7e6b77288b85063569baae8536671b39f15cc22037ec7045658d80489e", size = 168724, upload-time = "2025-05-28T19:25:53.926Z" },
+]
+
+[[package]]
+name = "pycparser"
+version = "3.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/1b/7d/92392ff7815c21062bea51aa7b87d45576f649f16458d78b7cf94b9ab2e6/pycparser-3.0.tar.gz", hash = "sha256:600f49d217304a5902ac3c37e1281c9fe94e4d0489de643a9504c5cdfdfc6b29", size = 103492, upload-time = "2026-01-21T14:26:51.89Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/0c/c3/44f3fbbfa403ea2a7c779186dc20772604442dde72947e7d01069cbe98e3/pycparser-3.0-py3-none-any.whl", hash = "sha256:b727414169a36b7d524c1c3e31839a521725078d7b2ff038656844266160a992", size = 48172, upload-time = "2026-01-21T14:26:50.693Z" },
+]
+
+[[package]]
+name = "pycryptodomex"
+version = "3.23.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/c9/85/e24bf90972a30b0fcd16c73009add1d7d7cd9140c2498a68252028899e41/pycryptodomex-3.23.0.tar.gz", hash = "sha256:71909758f010c82bc99b0abf4ea12012c98962fbf0583c2164f8b84533c2e4da", size = 4922157, upload-time = "2025-05-17T17:23:41.434Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/2e/00/10edb04777069a42490a38c137099d4b17ba6e36a4e6e28bdc7470e9e853/pycryptodomex-3.23.0-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:7b37e08e3871efe2187bc1fd9320cc81d87caf19816c648f24443483005ff886", size = 2498764, upload-time = "2025-05-17T17:22:21.453Z" },
+ { url = "https://files.pythonhosted.org/packages/6b/3f/2872a9c2d3a27eac094f9ceaa5a8a483b774ae69018040ea3240d5b11154/pycryptodomex-3.23.0-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:91979028227543010d7b2ba2471cf1d1e398b3f183cb105ac584df0c36dac28d", size = 1643012, upload-time = "2025-05-17T17:22:23.702Z" },
+ { url = "https://files.pythonhosted.org/packages/70/af/774c2e2b4f6570fbf6a4972161adbb183aeeaa1863bde31e8706f123bf92/pycryptodomex-3.23.0-cp313-cp313t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:6b8962204c47464d5c1c4038abeadd4514a133b28748bcd9fa5b6d62e3cec6fa", size = 2187643, upload-time = "2025-05-17T17:22:26.37Z" },
+ { url = "https://files.pythonhosted.org/packages/de/a3/71065b24cb889d537954cedc3ae5466af00a2cabcff8e29b73be047e9a19/pycryptodomex-3.23.0-cp313-cp313t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:a33986a0066860f7fcf7c7bd2bc804fa90e434183645595ae7b33d01f3c91ed8", size = 2273762, upload-time = "2025-05-17T17:22:28.313Z" },
+ { url = "https://files.pythonhosted.org/packages/c9/0b/ff6f43b7fbef4d302c8b981fe58467b8871902cdc3eb28896b52421422cc/pycryptodomex-3.23.0-cp313-cp313t-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:c7947ab8d589e3178da3d7cdeabe14f841b391e17046954f2fbcd941705762b5", size = 2313012, upload-time = "2025-05-17T17:22:30.57Z" },
+ { url = "https://files.pythonhosted.org/packages/02/de/9d4772c0506ab6da10b41159493657105d3f8bb5c53615d19452afc6b315/pycryptodomex-3.23.0-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:c25e30a20e1b426e1f0fa00131c516f16e474204eee1139d1603e132acffc314", size = 2186856, upload-time = "2025-05-17T17:22:32.819Z" },
+ { url = "https://files.pythonhosted.org/packages/28/ad/8b30efcd6341707a234e5eba5493700a17852ca1ac7a75daa7945fcf6427/pycryptodomex-3.23.0-cp313-cp313t-musllinux_1_2_i686.whl", hash = "sha256:da4fa650cef02db88c2b98acc5434461e027dce0ae8c22dd5a69013eaf510006", size = 2347523, upload-time = "2025-05-17T17:22:35.386Z" },
+ { url = "https://files.pythonhosted.org/packages/0f/02/16868e9f655b7670dbb0ac4f2844145cbc42251f916fc35c414ad2359849/pycryptodomex-3.23.0-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:58b851b9effd0d072d4ca2e4542bf2a4abcf13c82a29fd2c93ce27ee2a2e9462", size = 2272825, upload-time = "2025-05-17T17:22:37.632Z" },
+ { url = "https://files.pythonhosted.org/packages/ca/18/4ca89ac737230b52ac8ffaca42f9c6f1fd07c81a6cd821e91af79db60632/pycryptodomex-3.23.0-cp313-cp313t-win32.whl", hash = "sha256:a9d446e844f08299236780f2efa9898c818fe7e02f17263866b8550c7d5fb328", size = 1772078, upload-time = "2025-05-17T17:22:40Z" },
+ { url = "https://files.pythonhosted.org/packages/73/34/13e01c322db027682e00986873eca803f11c56ade9ba5bbf3225841ea2d4/pycryptodomex-3.23.0-cp313-cp313t-win_amd64.whl", hash = "sha256:bc65bdd9fc8de7a35a74cab1c898cab391a4add33a8fe740bda00f5976ca4708", size = 1803656, upload-time = "2025-05-17T17:22:42.139Z" },
+ { url = "https://files.pythonhosted.org/packages/54/68/9504c8796b1805d58f4425002bcca20f12880e6fa4dc2fc9a668705c7a08/pycryptodomex-3.23.0-cp313-cp313t-win_arm64.whl", hash = "sha256:c885da45e70139464f082018ac527fdaad26f1657a99ee13eecdce0f0ca24ab4", size = 1707172, upload-time = "2025-05-17T17:22:44.704Z" },
+ { url = "https://files.pythonhosted.org/packages/dd/9c/1a8f35daa39784ed8adf93a694e7e5dc15c23c741bbda06e1d45f8979e9e/pycryptodomex-3.23.0-cp37-abi3-macosx_10_9_universal2.whl", hash = "sha256:06698f957fe1ab229a99ba2defeeae1c09af185baa909a31a5d1f9d42b1aaed6", size = 2499240, upload-time = "2025-05-17T17:22:46.953Z" },
+ { url = "https://files.pythonhosted.org/packages/7a/62/f5221a191a97157d240cf6643747558759126c76ee92f29a3f4aee3197a5/pycryptodomex-3.23.0-cp37-abi3-macosx_10_9_x86_64.whl", hash = "sha256:b2c2537863eccef2d41061e82a881dcabb04944c5c06c5aa7110b577cc487545", size = 1644042, upload-time = "2025-05-17T17:22:49.098Z" },
+ { url = "https://files.pythonhosted.org/packages/8c/fd/5a054543c8988d4ed7b612721d7e78a4b9bf36bc3c5ad45ef45c22d0060e/pycryptodomex-3.23.0-cp37-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:43c446e2ba8df8889e0e16f02211c25b4934898384c1ec1ec04d7889c0333587", size = 2186227, upload-time = "2025-05-17T17:22:51.139Z" },
+ { url = "https://files.pythonhosted.org/packages/c8/a9/8862616a85cf450d2822dbd4fff1fcaba90877907a6ff5bc2672cafe42f8/pycryptodomex-3.23.0-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:f489c4765093fb60e2edafdf223397bc716491b2b69fe74367b70d6999257a5c", size = 2272578, upload-time = "2025-05-17T17:22:53.676Z" },
+ { url = "https://files.pythonhosted.org/packages/46/9f/bda9c49a7c1842820de674ab36c79f4fbeeee03f8ff0e4f3546c3889076b/pycryptodomex-3.23.0-cp37-abi3-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:bdc69d0d3d989a1029df0eed67cc5e8e5d968f3724f4519bd03e0ec68df7543c", size = 2312166, upload-time = "2025-05-17T17:22:56.585Z" },
+ { url = "https://files.pythonhosted.org/packages/03/cc/870b9bf8ca92866ca0186534801cf8d20554ad2a76ca959538041b7a7cf4/pycryptodomex-3.23.0-cp37-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:6bbcb1dd0f646484939e142462d9e532482bc74475cecf9c4903d4e1cd21f003", size = 2185467, upload-time = "2025-05-17T17:22:59.237Z" },
+ { url = "https://files.pythonhosted.org/packages/96/e3/ce9348236d8e669fea5dd82a90e86be48b9c341210f44e25443162aba187/pycryptodomex-3.23.0-cp37-abi3-musllinux_1_2_i686.whl", hash = "sha256:8a4fcd42ccb04c31268d1efeecfccfd1249612b4de6374205376b8f280321744", size = 2346104, upload-time = "2025-05-17T17:23:02.112Z" },
+ { url = "https://files.pythonhosted.org/packages/a5/e9/e869bcee87beb89040263c416a8a50204f7f7a83ac11897646c9e71e0daf/pycryptodomex-3.23.0-cp37-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:55ccbe27f049743a4caf4f4221b166560d3438d0b1e5ab929e07ae1702a4d6fd", size = 2271038, upload-time = "2025-05-17T17:23:04.872Z" },
+ { url = "https://files.pythonhosted.org/packages/8d/67/09ee8500dd22614af5fbaa51a4aee6e342b5fa8aecf0a6cb9cbf52fa6d45/pycryptodomex-3.23.0-cp37-abi3-win32.whl", hash = "sha256:189afbc87f0b9f158386bf051f720e20fa6145975f1e76369303d0f31d1a8d7c", size = 1771969, upload-time = "2025-05-17T17:23:07.115Z" },
+ { url = "https://files.pythonhosted.org/packages/69/96/11f36f71a865dd6df03716d33bd07a67e9d20f6b8d39820470b766af323c/pycryptodomex-3.23.0-cp37-abi3-win_amd64.whl", hash = "sha256:52e5ca58c3a0b0bd5e100a9fbc8015059b05cffc6c66ce9d98b4b45e023443b9", size = 1803124, upload-time = "2025-05-17T17:23:09.267Z" },
+ { url = "https://files.pythonhosted.org/packages/f9/93/45c1cdcbeb182ccd2e144c693eaa097763b08b38cded279f0053ed53c553/pycryptodomex-3.23.0-cp37-abi3-win_arm64.whl", hash = "sha256:02d87b80778c171445d67e23d1caef279bf4b25c3597050ccd2e13970b57fd51", size = 1707161, upload-time = "2025-05-17T17:23:11.414Z" },
+]
+
+[[package]]
+name = "pygments"
+version = "2.19.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/b0/77/a5b8c569bf593b0140bde72ea885a803b82086995367bf2037de0159d924/pygments-2.19.2.tar.gz", hash = "sha256:636cb2477cec7f8952536970bc533bc43743542f70392ae026374600add5b887", size = 4968631, upload-time = "2025-06-21T13:39:12.283Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/c7/21/705964c7812476f378728bdf590ca4b771ec72385c533964653c68e86bdc/pygments-2.19.2-py3-none-any.whl", hash = "sha256:86540386c03d588bb81d44bc3928634ff26449851e99741617ecb9037ee5ec0b", size = 1225217, upload-time = "2025-06-21T13:39:07.939Z" },
+]
+
+[[package]]
+name = "pymonctl"
+version = "0.92"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "ewmhlib", marker = "sys_platform == 'linux'" },
+ { name = "pyobjc", marker = "sys_platform == 'darwin'" },
+ { name = "python-xlib", marker = "sys_platform == 'linux'" },
+ { name = "pywin32", marker = "sys_platform == 'win32'" },
+ { name = "typing-extensions" },
+]
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/2d/13/076a20da28b82be281f7e43e16d9da0f545090f5d14b2125699232b9feba/PyMonCtl-0.92-py3-none-any.whl", hash = "sha256:2495d8dab78f9a7dbce37e74543e60b8bd404a35c3108935697dda7768611b5a", size = 45945, upload-time = "2024-04-22T10:07:09.566Z" },
+]
+
+[[package]]
+name = "pynacl"
+version = "1.6.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "cffi", marker = "platform_python_implementation != 'PyPy'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/d9/9a/4019b524b03a13438637b11538c82781a5eda427394380381af8f04f467a/pynacl-1.6.2.tar.gz", hash = "sha256:018494d6d696ae03c7e656e5e74cdfd8ea1326962cc401bcf018f1ed8436811c", size = 3511692, upload-time = "2026-01-01T17:48:10.851Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/be/7b/4845bbf88e94586ec47a432da4e9107e3fc3ce37eb412b1398630a37f7dd/pynacl-1.6.2-cp38-abi3-macosx_10_10_universal2.whl", hash = "sha256:c949ea47e4206af7c8f604b8278093b674f7c79ed0d4719cc836902bf4517465", size = 388458, upload-time = "2026-01-01T17:32:16.829Z" },
+ { url = "https://files.pythonhosted.org/packages/1e/b4/e927e0653ba63b02a4ca5b4d852a8d1d678afbf69b3dbf9c4d0785ac905c/pynacl-1.6.2-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:8845c0631c0be43abdd865511c41eab235e0be69c81dc66a50911594198679b0", size = 800020, upload-time = "2026-01-01T17:32:18.34Z" },
+ { url = "https://files.pythonhosted.org/packages/7f/81/d60984052df5c97b1d24365bc1e30024379b42c4edcd79d2436b1b9806f2/pynacl-1.6.2-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:22de65bb9010a725b0dac248f353bb072969c94fa8d6b1f34b87d7953cf7bbe4", size = 1399174, upload-time = "2026-01-01T17:32:20.239Z" },
+ { url = "https://files.pythonhosted.org/packages/68/f7/322f2f9915c4ef27d140101dd0ed26b479f7e6f5f183590fd32dfc48c4d3/pynacl-1.6.2-cp38-abi3-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:46065496ab748469cdd999246d17e301b2c24ae2fdf739132e580a0e94c94a87", size = 835085, upload-time = "2026-01-01T17:32:22.24Z" },
+ { url = "https://files.pythonhosted.org/packages/3e/d0/f301f83ac8dbe53442c5a43f6a39016f94f754d7a9815a875b65e218a307/pynacl-1.6.2-cp38-abi3-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:8a66d6fb6ae7661c58995f9c6435bda2b1e68b54b598a6a10247bfcdadac996c", size = 1437614, upload-time = "2026-01-01T17:32:23.766Z" },
+ { url = "https://files.pythonhosted.org/packages/c4/58/fc6e649762b029315325ace1a8c6be66125e42f67416d3dbd47b69563d61/pynacl-1.6.2-cp38-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:26bfcd00dcf2cf160f122186af731ae30ab120c18e8375684ec2670dccd28130", size = 818251, upload-time = "2026-01-01T17:32:25.69Z" },
+ { url = "https://files.pythonhosted.org/packages/c9/a8/b917096b1accc9acd878819a49d3d84875731a41eb665f6ebc826b1af99e/pynacl-1.6.2-cp38-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:c8a231e36ec2cab018c4ad4358c386e36eede0319a0c41fed24f840b1dac59f6", size = 1402859, upload-time = "2026-01-01T17:32:27.215Z" },
+ { url = "https://files.pythonhosted.org/packages/85/42/fe60b5f4473e12c72f977548e4028156f4d340b884c635ec6b063fe7e9a5/pynacl-1.6.2-cp38-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:68be3a09455743ff9505491220b64440ced8973fe930f270c8e07ccfa25b1f9e", size = 791926, upload-time = "2026-01-01T17:32:29.314Z" },
+ { url = "https://files.pythonhosted.org/packages/fa/f9/e40e318c604259301cc091a2a63f237d9e7b424c4851cafaea4ea7c4834e/pynacl-1.6.2-cp38-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:8b097553b380236d51ed11356c953bf8ce36a29a3e596e934ecabe76c985a577", size = 1363101, upload-time = "2026-01-01T17:32:31.263Z" },
+ { url = "https://files.pythonhosted.org/packages/48/47/e761c254f410c023a469284a9bc210933e18588ca87706ae93002c05114c/pynacl-1.6.2-cp38-abi3-win32.whl", hash = "sha256:5811c72b473b2f38f7e2a3dc4f8642e3a3e9b5e7317266e4ced1fba85cae41aa", size = 227421, upload-time = "2026-01-01T17:32:33.076Z" },
+ { url = "https://files.pythonhosted.org/packages/41/ad/334600e8cacc7d86587fe5f565480fde569dfb487389c8e1be56ac21d8ac/pynacl-1.6.2-cp38-abi3-win_amd64.whl", hash = "sha256:62985f233210dee6548c223301b6c25440852e13d59a8b81490203c3227c5ba0", size = 239754, upload-time = "2026-01-01T17:32:34.557Z" },
+ { url = "https://files.pythonhosted.org/packages/29/7d/5945b5af29534641820d3bd7b00962abbbdfee84ec7e19f0d5b3175f9a31/pynacl-1.6.2-cp38-abi3-win_arm64.whl", hash = "sha256:834a43af110f743a754448463e8fd61259cd4ab5bbedcf70f9dabad1d28a394c", size = 184801, upload-time = "2026-01-01T17:32:36.309Z" },
+]
+
+[[package]]
+name = "pynput"
+version = "1.8.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "evdev", marker = "'linux' in sys_platform" },
+ { name = "pyobjc-framework-applicationservices", marker = "sys_platform == 'darwin'" },
+ { name = "pyobjc-framework-quartz", marker = "sys_platform == 'darwin'" },
+ { name = "python-xlib", marker = "'linux' in sys_platform" },
+ { name = "six" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/f0/c3/dccf44c68225046df5324db0cc7d563a560635355b3e5f1d249468268a6f/pynput-1.8.1.tar.gz", hash = "sha256:70d7c8373ee98911004a7c938742242840a5628c004573d84ba849d4601df81e", size = 82289, upload-time = "2025-03-17T17:12:01.481Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/59/4f/ac3fa906ae8a375a536b12794128c5efacade9eaa917a35dfd27ce0c7400/pynput-1.8.1-py2.py3-none-any.whl", hash = "sha256:42dfcf27404459ca16ca889c8fb8ffe42a9fe54f722fd1a3e130728e59e768d2", size = 91693, upload-time = "2025-03-17T17:12:00.094Z" },
+]
+
+[[package]]
+name = "pyobjc"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-accessibility", marker = "platform_release >= '20.0'" },
+ { name = "pyobjc-framework-accounts", marker = "platform_release >= '12.0'" },
+ { name = "pyobjc-framework-addressbook" },
+ { name = "pyobjc-framework-adservices", marker = "platform_release >= '20.0'" },
+ { name = "pyobjc-framework-adsupport", marker = "platform_release >= '18.0'" },
+ { name = "pyobjc-framework-applescriptkit" },
+ { name = "pyobjc-framework-applescriptobjc", marker = "platform_release >= '10.0'" },
+ { name = "pyobjc-framework-applicationservices" },
+ { name = "pyobjc-framework-apptrackingtransparency", marker = "platform_release >= '20.0'" },
+ { name = "pyobjc-framework-arkit", marker = "platform_release >= '25.0'" },
+ { name = "pyobjc-framework-audiovideobridging", marker = "platform_release >= '12.0'" },
+ { name = "pyobjc-framework-authenticationservices", marker = "platform_release >= '19.0'" },
+ { name = "pyobjc-framework-automaticassessmentconfiguration", marker = "platform_release >= '19.0'" },
+ { name = "pyobjc-framework-automator" },
+ { name = "pyobjc-framework-avfoundation", marker = "platform_release >= '11.0'" },
+ { name = "pyobjc-framework-avkit", marker = "platform_release >= '13.0'" },
+ { name = "pyobjc-framework-avrouting", marker = "platform_release >= '22.0'" },
+ { name = "pyobjc-framework-backgroundassets", marker = "platform_release >= '22.0'" },
+ { name = "pyobjc-framework-browserenginekit", marker = "platform_release >= '23.4'" },
+ { name = "pyobjc-framework-businesschat", marker = "platform_release >= '18.0'" },
+ { name = "pyobjc-framework-calendarstore", marker = "platform_release >= '9.0'" },
+ { name = "pyobjc-framework-callkit", marker = "platform_release >= '20.0'" },
+ { name = "pyobjc-framework-carbon" },
+ { name = "pyobjc-framework-cfnetwork" },
+ { name = "pyobjc-framework-cinematic", marker = "platform_release >= '23.0'" },
+ { name = "pyobjc-framework-classkit", marker = "platform_release >= '20.0'" },
+ { name = "pyobjc-framework-cloudkit", marker = "platform_release >= '14.0'" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-collaboration", marker = "platform_release >= '9.0'" },
+ { name = "pyobjc-framework-colorsync", marker = "platform_release >= '17.0'" },
+ { name = "pyobjc-framework-compositorservices", marker = "platform_release >= '25.0'" },
+ { name = "pyobjc-framework-contacts", marker = "platform_release >= '15.0'" },
+ { name = "pyobjc-framework-contactsui", marker = "platform_release >= '15.0'" },
+ { name = "pyobjc-framework-coreaudio" },
+ { name = "pyobjc-framework-coreaudiokit" },
+ { name = "pyobjc-framework-corebluetooth", marker = "platform_release >= '14.0'" },
+ { name = "pyobjc-framework-coredata" },
+ { name = "pyobjc-framework-corehaptics", marker = "platform_release >= '19.0'" },
+ { name = "pyobjc-framework-corelocation", marker = "platform_release >= '10.0'" },
+ { name = "pyobjc-framework-coremedia", marker = "platform_release >= '11.0'" },
+ { name = "pyobjc-framework-coremediaio", marker = "platform_release >= '11.0'" },
+ { name = "pyobjc-framework-coremidi" },
+ { name = "pyobjc-framework-coreml", marker = "platform_release >= '17.0'" },
+ { name = "pyobjc-framework-coremotion", marker = "platform_release >= '19.0'" },
+ { name = "pyobjc-framework-coreservices" },
+ { name = "pyobjc-framework-corespotlight", marker = "platform_release >= '17.0'" },
+ { name = "pyobjc-framework-coretext" },
+ { name = "pyobjc-framework-corewlan", marker = "platform_release >= '10.0'" },
+ { name = "pyobjc-framework-cryptotokenkit", marker = "platform_release >= '14.0'" },
+ { name = "pyobjc-framework-datadetection", marker = "platform_release >= '21.0'" },
+ { name = "pyobjc-framework-devicecheck", marker = "platform_release >= '19.0'" },
+ { name = "pyobjc-framework-devicediscoveryextension", marker = "platform_release >= '24.0'" },
+ { name = "pyobjc-framework-dictionaryservices", marker = "platform_release >= '9.0'" },
+ { name = "pyobjc-framework-discrecording" },
+ { name = "pyobjc-framework-discrecordingui" },
+ { name = "pyobjc-framework-diskarbitration" },
+ { name = "pyobjc-framework-dvdplayback" },
+ { name = "pyobjc-framework-eventkit", marker = "platform_release >= '12.0'" },
+ { name = "pyobjc-framework-exceptionhandling" },
+ { name = "pyobjc-framework-executionpolicy", marker = "platform_release >= '19.0'" },
+ { name = "pyobjc-framework-extensionkit", marker = "platform_release >= '22.0'" },
+ { name = "pyobjc-framework-externalaccessory", marker = "platform_release >= '17.0'" },
+ { name = "pyobjc-framework-fileprovider", marker = "platform_release >= '19.0'" },
+ { name = "pyobjc-framework-fileproviderui", marker = "platform_release >= '19.0'" },
+ { name = "pyobjc-framework-findersync", marker = "platform_release >= '14.0'" },
+ { name = "pyobjc-framework-fsevents", marker = "platform_release >= '9.0'" },
+ { name = "pyobjc-framework-fskit", marker = "platform_release >= '24.4'" },
+ { name = "pyobjc-framework-gamecenter", marker = "platform_release >= '12.0'" },
+ { name = "pyobjc-framework-gamecontroller", marker = "platform_release >= '13.0'" },
+ { name = "pyobjc-framework-gamekit", marker = "platform_release >= '12.0'" },
+ { name = "pyobjc-framework-gameplaykit", marker = "platform_release >= '15.0'" },
+ { name = "pyobjc-framework-gamesave", marker = "platform_release >= '25.0'" },
+ { name = "pyobjc-framework-healthkit", marker = "platform_release >= '22.0'" },
+ { name = "pyobjc-framework-imagecapturecore", marker = "platform_release >= '10.0'" },
+ { name = "pyobjc-framework-inputmethodkit", marker = "platform_release >= '9.0'" },
+ { name = "pyobjc-framework-installerplugins" },
+ { name = "pyobjc-framework-instantmessage", marker = "platform_release >= '9.0'" },
+ { name = "pyobjc-framework-intents", marker = "platform_release >= '16.0'" },
+ { name = "pyobjc-framework-intentsui", marker = "platform_release >= '21.0'" },
+ { name = "pyobjc-framework-iobluetooth" },
+ { name = "pyobjc-framework-iobluetoothui" },
+ { name = "pyobjc-framework-iosurface", marker = "platform_release >= '10.0'" },
+ { name = "pyobjc-framework-ituneslibrary", marker = "platform_release >= '10.0'" },
+ { name = "pyobjc-framework-kernelmanagement", marker = "platform_release >= '20.0'" },
+ { name = "pyobjc-framework-latentsemanticmapping" },
+ { name = "pyobjc-framework-launchservices" },
+ { name = "pyobjc-framework-libdispatch", marker = "platform_release >= '12.0'" },
+ { name = "pyobjc-framework-libxpc", marker = "platform_release >= '12.0'" },
+ { name = "pyobjc-framework-linkpresentation", marker = "platform_release >= '19.0'" },
+ { name = "pyobjc-framework-localauthentication", marker = "platform_release >= '14.0'" },
+ { name = "pyobjc-framework-localauthenticationembeddedui", marker = "platform_release >= '21.0'" },
+ { name = "pyobjc-framework-mailkit", marker = "platform_release >= '21.0'" },
+ { name = "pyobjc-framework-mapkit", marker = "platform_release >= '13.0'" },
+ { name = "pyobjc-framework-mediaaccessibility", marker = "platform_release >= '13.0'" },
+ { name = "pyobjc-framework-mediaextension", marker = "platform_release >= '24.0'" },
+ { name = "pyobjc-framework-medialibrary", marker = "platform_release >= '13.0'" },
+ { name = "pyobjc-framework-mediaplayer", marker = "platform_release >= '16.0'" },
+ { name = "pyobjc-framework-mediatoolbox", marker = "platform_release >= '13.0'" },
+ { name = "pyobjc-framework-metal", marker = "platform_release >= '15.0'" },
+ { name = "pyobjc-framework-metalfx", marker = "platform_release >= '22.0'" },
+ { name = "pyobjc-framework-metalkit", marker = "platform_release >= '15.0'" },
+ { name = "pyobjc-framework-metalperformanceshaders", marker = "platform_release >= '17.0'" },
+ { name = "pyobjc-framework-metalperformanceshadersgraph", marker = "platform_release >= '20.0'" },
+ { name = "pyobjc-framework-metrickit", marker = "platform_release >= '21.0'" },
+ { name = "pyobjc-framework-mlcompute", marker = "platform_release >= '20.0'" },
+ { name = "pyobjc-framework-modelio", marker = "platform_release >= '15.0'" },
+ { name = "pyobjc-framework-multipeerconnectivity", marker = "platform_release >= '14.0'" },
+ { name = "pyobjc-framework-naturallanguage", marker = "platform_release >= '18.0'" },
+ { name = "pyobjc-framework-netfs", marker = "platform_release >= '10.0'" },
+ { name = "pyobjc-framework-network", marker = "platform_release >= '18.0'" },
+ { name = "pyobjc-framework-networkextension", marker = "platform_release >= '15.0'" },
+ { name = "pyobjc-framework-notificationcenter", marker = "platform_release >= '14.0'" },
+ { name = "pyobjc-framework-opendirectory", marker = "platform_release >= '10.0'" },
+ { name = "pyobjc-framework-osakit" },
+ { name = "pyobjc-framework-oslog", marker = "platform_release >= '19.0'" },
+ { name = "pyobjc-framework-passkit", marker = "platform_release >= '20.0'" },
+ { name = "pyobjc-framework-pencilkit", marker = "platform_release >= '19.0'" },
+ { name = "pyobjc-framework-phase", marker = "platform_release >= '21.0'" },
+ { name = "pyobjc-framework-photos", marker = "platform_release >= '15.0'" },
+ { name = "pyobjc-framework-photosui", marker = "platform_release >= '15.0'" },
+ { name = "pyobjc-framework-preferencepanes" },
+ { name = "pyobjc-framework-pushkit", marker = "platform_release >= '19.0'" },
+ { name = "pyobjc-framework-quartz" },
+ { name = "pyobjc-framework-quicklookthumbnailing", marker = "platform_release >= '19.0'" },
+ { name = "pyobjc-framework-replaykit", marker = "platform_release >= '20.0'" },
+ { name = "pyobjc-framework-safariservices", marker = "platform_release >= '16.0'" },
+ { name = "pyobjc-framework-safetykit", marker = "platform_release >= '22.0'" },
+ { name = "pyobjc-framework-scenekit", marker = "platform_release >= '11.0'" },
+ { name = "pyobjc-framework-screencapturekit", marker = "platform_release >= '21.4'" },
+ { name = "pyobjc-framework-screensaver" },
+ { name = "pyobjc-framework-screentime", marker = "platform_release >= '20.0'" },
+ { name = "pyobjc-framework-scriptingbridge", marker = "platform_release >= '9.0'" },
+ { name = "pyobjc-framework-searchkit" },
+ { name = "pyobjc-framework-security" },
+ { name = "pyobjc-framework-securityfoundation" },
+ { name = "pyobjc-framework-securityinterface" },
+ { name = "pyobjc-framework-securityui", marker = "platform_release >= '24.4'" },
+ { name = "pyobjc-framework-sensitivecontentanalysis", marker = "platform_release >= '23.0'" },
+ { name = "pyobjc-framework-servicemanagement", marker = "platform_release >= '10.0'" },
+ { name = "pyobjc-framework-sharedwithyou", marker = "platform_release >= '22.0'" },
+ { name = "pyobjc-framework-sharedwithyoucore", marker = "platform_release >= '22.0'" },
+ { name = "pyobjc-framework-shazamkit", marker = "platform_release >= '21.0'" },
+ { name = "pyobjc-framework-social", marker = "platform_release >= '12.0'" },
+ { name = "pyobjc-framework-soundanalysis", marker = "platform_release >= '19.0'" },
+ { name = "pyobjc-framework-speech", marker = "platform_release >= '19.0'" },
+ { name = "pyobjc-framework-spritekit", marker = "platform_release >= '13.0'" },
+ { name = "pyobjc-framework-storekit", marker = "platform_release >= '11.0'" },
+ { name = "pyobjc-framework-symbols", marker = "platform_release >= '23.0'" },
+ { name = "pyobjc-framework-syncservices" },
+ { name = "pyobjc-framework-systemconfiguration" },
+ { name = "pyobjc-framework-systemextensions", marker = "platform_release >= '19.0'" },
+ { name = "pyobjc-framework-threadnetwork", marker = "platform_release >= '22.0'" },
+ { name = "pyobjc-framework-uniformtypeidentifiers", marker = "platform_release >= '20.0'" },
+ { name = "pyobjc-framework-usernotifications", marker = "platform_release >= '18.0'" },
+ { name = "pyobjc-framework-usernotificationsui", marker = "platform_release >= '20.0'" },
+ { name = "pyobjc-framework-videosubscriberaccount", marker = "platform_release >= '18.0'" },
+ { name = "pyobjc-framework-videotoolbox", marker = "platform_release >= '12.0'" },
+ { name = "pyobjc-framework-virtualization", marker = "platform_release >= '20.0'" },
+ { name = "pyobjc-framework-vision", marker = "platform_release >= '17.0'" },
+ { name = "pyobjc-framework-webkit" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/17/06/d77639ba166cc09aed2d32ae204811b47bc5d40e035cdc9bff7fff72ec5f/pyobjc-12.1.tar.gz", hash = "sha256:686d6db3eb3182fac9846b8ce3eedf4c7d2680b21b8b8d6e6df054a17e92a12d", size = 11345, upload-time = "2025-11-14T10:07:28.155Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/ef/00/1085de7b73abf37ec27ad59f7a1d7a406e6e6da45720bced2e198fdf1ddf/pyobjc-12.1-py3-none-any.whl", hash = "sha256:6f8c36cf87b1159d2ca1aa387ffc3efcd51cc3da13ef47c65f45e6d9fbccc729", size = 4226, upload-time = "2025-11-14T09:30:25.185Z" },
+]
+
+[[package]]
+name = "pyobjc-core"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/b8/b6/d5612eb40be4fd5ef88c259339e6313f46ba67577a95d86c3470b951fce0/pyobjc_core-12.1.tar.gz", hash = "sha256:2bb3903f5387f72422145e1466b3ac3f7f0ef2e9960afa9bcd8961c5cbf8bd21", size = 1000532, upload-time = "2025-11-14T10:08:28.292Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/95/df/d2b290708e9da86d6e7a9a2a2022b91915cf2e712a5a82e306cb6ee99792/pyobjc_core-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:c918ebca280925e7fcb14c5c43ce12dcb9574a33cccb889be7c8c17f3bcce8b6", size = 671263, upload-time = "2025-11-14T09:31:35.231Z" },
+ { url = "https://files.pythonhosted.org/packages/64/5a/6b15e499de73050f4a2c88fff664ae154307d25dc04da8fb38998a428358/pyobjc_core-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:818bcc6723561f207e5b5453efe9703f34bc8781d11ce9b8be286bb415eb4962", size = 678335, upload-time = "2025-11-14T09:32:20.107Z" },
+ { url = "https://files.pythonhosted.org/packages/f4/d2/29e5e536adc07bc3d33dd09f3f7cf844bf7b4981820dc2a91dd810f3c782/pyobjc_core-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:01c0cf500596f03e21c23aef9b5f326b9fb1f8f118cf0d8b66749b6cf4cbb37a", size = 677370, upload-time = "2025-11-14T09:33:05.273Z" },
+ { url = "https://files.pythonhosted.org/packages/1b/f0/4b4ed8924cd04e425f2a07269943018d43949afad1c348c3ed4d9d032787/pyobjc_core-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:177aaca84bb369a483e4961186704f64b2697708046745f8167e818d968c88fc", size = 719586, upload-time = "2025-11-14T09:33:53.302Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-accessibility"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-quartz" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/2d/87/8ca40428d05a668fecc638f2f47dba86054dbdc35351d247f039749de955/pyobjc_framework_accessibility-12.1.tar.gz", hash = "sha256:5ff362c3425edc242d49deec11f5f3e26e565cefb6a2872eda59ab7362149772", size = 29800, upload-time = "2025-11-14T10:08:31.949Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/76/00/182c57584ad8e5946a82dacdc83c9791567e10bffdea1fe92272b3fdec14/pyobjc_framework_accessibility-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:5e29dac0ce8327cd5a8b9a5a8bd8aa83e4070018b93699e97ac0c3af09b42a9a", size = 11301, upload-time = "2025-11-14T09:35:28.678Z" },
+ { url = "https://files.pythonhosted.org/packages/cc/95/9ea0d1c16316b4b5babf4b0515e9a133ac64269d3ec031f15ee9c7c2a8c1/pyobjc_framework_accessibility-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:537691a0b28fedb8385cd093df069a6e5d7e027629671fc47b50210404eca20b", size = 11335, upload-time = "2025-11-14T09:35:30.81Z" },
+ { url = "https://files.pythonhosted.org/packages/40/71/aa9625b1b064f7d3e1bbc0b6b40cf92d1d46c7f798e0b345594d626f5510/pyobjc_framework_accessibility-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:44d872d8a1f9d1569da0590c5a9185d2c02dc2e08e410c84a03aa54ca6e05c2c", size = 11352, upload-time = "2025-11-14T09:35:32.967Z" },
+ { url = "https://files.pythonhosted.org/packages/e9/d8/ff4c720d6140f7a20eaed15d5430af1fc8be372998674b82931993177261/pyobjc_framework_accessibility-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:4b9e2079ad0da736ba32a10e63698ff1db9667b5f6342a81220aa86cfa0de8c8", size = 11521, upload-time = "2025-11-14T09:35:35.112Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-accounts"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/65/10/f6fe336c7624d6753c1f6edac102310ce4434d49b548c479e8e6420d4024/pyobjc_framework_accounts-12.1.tar.gz", hash = "sha256:76d62c5e7b831eb8f4c9ca6abaf79d9ed961dfffe24d89a041fb1de97fe56a3e", size = 15202, upload-time = "2025-11-14T10:08:33.995Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/ac/70/5f9214250f92fbe2e07f35778875d2771d612f313af2a0e4bacba80af28e/pyobjc_framework_accounts-12.1-py2.py3-none-any.whl", hash = "sha256:e1544ad11a2f889a7aaed649188d0e76d58595a27eec07ca663847a7adb21ae5", size = 5104, upload-time = "2025-11-14T09:35:40.246Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-addressbook"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/18/28/0404af2a1c6fa8fd266df26fb6196a8f3fb500d6fe3dab94701949247bea/pyobjc_framework_addressbook-12.1.tar.gz", hash = "sha256:c48b740cf981103cef1743d0804a226d86481fcb839bd84b80e9a586187e8000", size = 44359, upload-time = "2025-11-14T10:08:37.687Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/9f/5a/2ecaa94e5f56c6631f0820ec4209f8075c1b7561fe37495e2d024de1c8df/pyobjc_framework_addressbook-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:681755ada6c95bd4a096bc2b9f9c24661ffe6bff19a96963ee3fad34f3d61d2b", size = 12879, upload-time = "2025-11-14T09:35:45.21Z" },
+ { url = "https://files.pythonhosted.org/packages/b6/33/da709c69cbb60df9522cd614d5c23c15b649b72e5d62fed1048e75c70e7b/pyobjc_framework_addressbook-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:7893dd784322f4674299fb3ca40cb03385e5eddb78defd38f08c0b730813b56c", size = 12894, upload-time = "2025-11-14T09:35:47.498Z" },
+ { url = "https://files.pythonhosted.org/packages/62/eb/de0d539bbf31685050dd9fe8894bd2dbc1632bf5311fc74c2c3c46ce61d0/pyobjc_framework_addressbook-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:f03312faeb3c381e040f965b288379468d567b1449c1cfe66d150885b48510a3", size = 12910, upload-time = "2025-11-14T09:35:49.694Z" },
+ { url = "https://files.pythonhosted.org/packages/e7/59/720da201349f67bca9e6b577fea1a8a3344e88a6527c48933be898c9559d/pyobjc_framework_addressbook-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:3b6931f78e01a215df3d9a27d1a10aab04659e636b0836ac448f8dd7fc56a581", size = 13064, upload-time = "2025-11-14T09:35:51.664Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-adservices"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/19/04/1c3d3e0a1ac981664f30b33407dcdf8956046ecde6abc88832cf2aa535f4/pyobjc_framework_adservices-12.1.tar.gz", hash = "sha256:7a31fc8d5c6fd58f012db87c89ba581361fc905114bfb912e0a3a87475c02183", size = 11793, upload-time = "2025-11-14T10:08:39.56Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/ad/13/f7796469b25f50750299c4b0e95dc2f75c7c7fc4c93ef2c644f947f10529/pyobjc_framework_adservices-12.1-py2.py3-none-any.whl", hash = "sha256:9ca3c55e35b2abb3149a0bce5de9a1f7e8ee4f8642036910ca8586ab2e161538", size = 3492, upload-time = "2025-11-14T09:35:57.344Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-adsupport"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/43/77/f26a2e9994d4df32e9b3680c8014e350b0f1c78d7673b3eba9de2e04816f/pyobjc_framework_adsupport-12.1.tar.gz", hash = "sha256:9a68480e76de567c339dca29a8c739d6d7b5cad30e1cd585ff6e49ec2fc283dd", size = 11645, upload-time = "2025-11-14T10:08:41.439Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/cd/1a/3e90d5a09953bde7b60946cd09cca1411aed05dea855cb88cb9e944c7006/pyobjc_framework_adsupport-12.1-py2.py3-none-any.whl", hash = "sha256:97dcd8799dd61f047bb2eb788bbde81f86e95241b5e5173a3a61cfc05b5598b1", size = 3401, upload-time = "2025-11-14T09:35:59.039Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-applescriptkit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/cd/f1/e0c07b2a9eb98f1a2050f153d287a52a92f873eeddb41b74c52c144d8767/pyobjc_framework_applescriptkit-12.1.tar.gz", hash = "sha256:cb09f88cf0ad9753dedc02720065818f854b50e33eb4194f0ea34de6d7a3eb33", size = 11451, upload-time = "2025-11-14T10:08:43.328Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/3b/70/6c399c6ebc37a4e48acf63967e0a916878aedfe420531f6d739215184c0c/pyobjc_framework_applescriptkit-12.1-py2.py3-none-any.whl", hash = "sha256:b955fc017b524027f635d92a8a45a5fd9fbae898f3e03de16ecd94aa4c4db987", size = 4352, upload-time = "2025-11-14T09:36:00.705Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-applescriptobjc"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c0/4b/e4d1592207cbe17355e01828bdd11dd58f31356108f6a49f5e0484a5df50/pyobjc_framework_applescriptobjc-12.1.tar.gz", hash = "sha256:dce080ed07409b0dda2fee75d559bd312ea1ef0243a4338606440f282a6a0f5f", size = 11588, upload-time = "2025-11-14T10:08:45.037Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/3e/5f/9ce6706399706930eb29c5308037109c30cfb36f943a6df66fdf38cc842a/pyobjc_framework_applescriptobjc-12.1-py2.py3-none-any.whl", hash = "sha256:79068f982cc22471712ce808c0a8fd5deea11258fc8d8c61968a84b1962a3d10", size = 4454, upload-time = "2025-11-14T09:36:02.276Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-applicationservices"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-coretext" },
+ { name = "pyobjc-framework-quartz" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/be/6a/d4e613c8e926a5744fc47a9e9fea08384a510dc4f27d844f7ad7a2d793bd/pyobjc_framework_applicationservices-12.1.tar.gz", hash = "sha256:c06abb74f119bc27aeb41bf1aef8102c0ae1288aec1ac8665ea186a067a8945b", size = 103247, upload-time = "2025-11-14T10:08:52.18Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/17/86/d07eff705ff909a0ffa96d14fc14026e9fc9dd716233648c53dfd5056b8e/pyobjc_framework_applicationservices-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:bdddd492eeac6d14ff2f5bd342aba29e30dffa72a2d358c08444da22129890e2", size = 32784, upload-time = "2025-11-14T09:36:08.755Z" },
+ { url = "https://files.pythonhosted.org/packages/37/a7/55fa88def5c02732c4b747606ff1cbce6e1f890734bbd00f5596b21eaa02/pyobjc_framework_applicationservices-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:c8f6e2fb3b3e9214ab4864ef04eee18f592b46a986c86ea0113448b310520532", size = 32835, upload-time = "2025-11-14T09:36:11.855Z" },
+ { url = "https://files.pythonhosted.org/packages/fc/21/79e42ee836f1010f5fe9e97d2817a006736bd287c15a3674c399190a2e77/pyobjc_framework_applicationservices-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:bd1f4dbb38234a24ae6819f5e22485cf7dd3dd4074ff3bf9a9fdb4c01a3b4a38", size = 32859, upload-time = "2025-11-14T09:36:15.208Z" },
+ { url = "https://files.pythonhosted.org/packages/66/3a/0f1d4dcf2345e875e5ea9761d5a70969e241d24089133d21f008dde596f5/pyobjc_framework_applicationservices-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:8a5d2845249b6a85ba9e320a9848468c3f8cd6f59605a9a43f406a7810eaa830", size = 33115, upload-time = "2025-11-14T09:36:18.384Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-apptrackingtransparency"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/0d/de/f24348982ecab0cb13067c348fc5fbc882c60d704ca290bada9a2b3e594b/pyobjc_framework_apptrackingtransparency-12.1.tar.gz", hash = "sha256:e25bf4e4dfa2d929993ee8e852b28fdf332fa6cde0a33328fdc3b2f502fa50ec", size = 12407, upload-time = "2025-11-14T10:08:54.118Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/19/b2/90120b93ecfb099b6af21696c26356ad0f2182bdef72b6cba28aa6472ca6/pyobjc_framework_apptrackingtransparency-12.1-py2.py3-none-any.whl", hash = "sha256:23a98ade55495f2f992ecf62c3cbd8f648cbd68ba5539c3f795bf66de82e37ca", size = 3879, upload-time = "2025-11-14T09:36:26.425Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-arkit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c9/8b/843fe08e696bca8e7fc129344965ab6280f8336f64f01ba0a8862d219c3f/pyobjc_framework_arkit-12.1.tar.gz", hash = "sha256:0c5c6b702926179700b68ba29b8247464c3b609fd002a07a3308e72cfa953adf", size = 35814, upload-time = "2025-11-14T10:08:57.55Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/21/1e/64c55b409243b3eb9abc7a99e7b27ad4e16b9e74bc4b507fb7e7b81fd41a/pyobjc_framework_arkit-12.1-py2.py3-none-any.whl", hash = "sha256:f6d39e28d858ee03f052d6780a552247e682204382dbc090f1d3192fa1b21493", size = 8302, upload-time = "2025-11-14T09:36:28.127Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-audiovideobridging"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/9f/51/f81581e7a3c5cb6c9254c6f1e1ee1d614930493761dec491b5b0d49544b9/pyobjc_framework_audiovideobridging-12.1.tar.gz", hash = "sha256:6230ace6bec1f38e8a727c35d054a7be54e039b3053f98e6dd8d08d6baee2625", size = 38457, upload-time = "2025-11-14T10:09:01.122Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/0a/f8/c614630fa382720bbd42a0ff567378630c36d10f114476d6c70b73f73b49/pyobjc_framework_audiovideobridging-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:6bc24a7063b08c7d9f1749a4641430d363b6dba642c04d09b58abcee7a5260cb", size = 11037, upload-time = "2025-11-14T09:36:32.583Z" },
+ { url = "https://files.pythonhosted.org/packages/f3/8e/a28badfcc6c731696e3d3a8a83927bd844d992f9152f903c2fee355702ca/pyobjc_framework_audiovideobridging-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:010021502649e2cca4e999a7c09358d48c6b0ed83530bbc0b85bba6834340e4b", size = 11052, upload-time = "2025-11-14T09:36:34.475Z" },
+ { url = "https://files.pythonhosted.org/packages/9a/e7/d6436115ebb623dbc14283f5e76577245fa6460995e9f7981e79e97003d3/pyobjc_framework_audiovideobridging-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:a9901a88b6c8dbc982d8605c6b1ff0330ff80647a0a96a8187b6784249eb42dc", size = 11065, upload-time = "2025-11-14T09:36:36.69Z" },
+ { url = "https://files.pythonhosted.org/packages/97/ca/d6740b0f666dca9fc28d4e08358a7a2fffaf879cf9c49d2c99c470b83ef8/pyobjc_framework_audiovideobridging-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:0c57fdf1762f616d10549c0eddf84e59c193800f4a7932aaa7d5f13c123609c0", size = 11239, upload-time = "2025-11-14T09:36:38.992Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-authenticationservices"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/6c/18/86218de3bf67fc1d810065f353d9df70c740de567ebee8550d476cb23862/pyobjc_framework_authenticationservices-12.1.tar.gz", hash = "sha256:cef71faeae2559f5c0ff9a81c9ceea1c81108e2f4ec7de52a98c269feff7a4b6", size = 58683, upload-time = "2025-11-14T10:09:06.003Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/c2/16/2f19d8a95f0cf8e940f7b7fb506ced805d5522b4118336c8e640c34517ae/pyobjc_framework_authenticationservices-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:c15bb81282356f3f062ac79ff4166c93097448edc44b17dcf686e1dac78cc832", size = 20636, upload-time = "2025-11-14T09:36:48.35Z" },
+ { url = "https://files.pythonhosted.org/packages/f1/1d/e9f296fe1ee9a074ff6c45ce9eb109fc3b45696de000f373265c8e42fd47/pyobjc_framework_authenticationservices-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:6fd5ce10fe5359cbbfe03eb12cab3e01992b32ab65653c579b00ac93cf674985", size = 20738, upload-time = "2025-11-14T09:36:51.094Z" },
+ { url = "https://files.pythonhosted.org/packages/23/2f/7016b3ca344b079932abe56d7d6216c88cac715d81ca687753aed4b749f7/pyobjc_framework_authenticationservices-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:4491a2352cd53a38c7d057d674b1aa40d05eddb8dd7a1a2f415d9f2858b52d40", size = 20746, upload-time = "2025-11-14T09:36:53.762Z" },
+ { url = "https://files.pythonhosted.org/packages/5b/63/f2d1137e542b2badb5803e01628a61e9df8853b773513a6a066524c77903/pyobjc_framework_authenticationservices-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:a3957039eae3a82ada418ee475a347619e42ba10c45a57cd6ca83b1a0e61c2ad", size = 20994, upload-time = "2025-11-14T09:36:56.153Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-automaticassessmentconfiguration"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e4/24/080afe8189c47c4bb3daa191ccfd962400ca31a67c14b0f7c2d002c2e249/pyobjc_framework_automaticassessmentconfiguration-12.1.tar.gz", hash = "sha256:2b732c02d9097682ca16e48f5d3b10056b740bc091e217ee4d5715194c8970b1", size = 21895, upload-time = "2025-11-14T10:09:08.779Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/fc/c9/4d2785565cc470daa222f93f3d332af97de600aef6bd23507ec07501999d/pyobjc_framework_automaticassessmentconfiguration-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:d94a4a3beb77b3b2ab7b610c4b41e28593d15571724a9e6ab196b82acc98dc13", size = 9316, upload-time = "2025-11-14T09:37:05.052Z" },
+ { url = "https://files.pythonhosted.org/packages/f2/b2/fbec3d649bf275d7a9604e5f56015be02ef8dcf002f4ae4d760436b8e222/pyobjc_framework_automaticassessmentconfiguration-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:c2e22ea67d7e6d6a84d968169f83d92b59857a49ab12132de07345adbfea8a62", size = 9332, upload-time = "2025-11-14T09:37:07.083Z" },
+ { url = "https://files.pythonhosted.org/packages/52/85/42cf8718bbfef47e67228a39d4f25b86b6fa9676f5ca5904af21ae42ad43/pyobjc_framework_automaticassessmentconfiguration-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:467739e70ddbc259bf453056cc9ce4ed96de8e6aad8122fa4035d2e6ecf9fc9c", size = 9344, upload-time = "2025-11-14T09:37:09.02Z" },
+ { url = "https://files.pythonhosted.org/packages/09/ec/a889dd812adfa446238853cf3cf6a7a2691e3096247a7ef75970d135e5bb/pyobjc_framework_automaticassessmentconfiguration-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:b4ea4b00f70bf242a5d8ce9c420987239dbc74285588c141ac1e0d6bd71fcd4c", size = 9501, upload-time = "2025-11-14T09:37:10.684Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-automator"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/7e/08/362bf6ac2bba393c46cf56078d4578b692b56857c385e47690637a72f0dd/pyobjc_framework_automator-12.1.tar.gz", hash = "sha256:7491a99347bb30da3a3f744052a03434ee29bee3e2ae520576f7e796740e4ba7", size = 186068, upload-time = "2025-11-14T10:09:20.82Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/e7/99/480e07eef053a2ad2a5cf1e15f71982f21d7f4119daafac338fa0352309c/pyobjc_framework_automator-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:4f3d96da10d28c5c197193a9d805a13157b1cb694b6c535983f8572f5f8746ea", size = 10016, upload-time = "2025-11-14T09:37:18.621Z" },
+ { url = "https://files.pythonhosted.org/packages/e3/36/2e8c36ddf20d501f9d344ed694e39021190faffc44b596f3a430bf437174/pyobjc_framework_automator-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:4df9aec77f0fbca66cd3534d1b8398fe6f3e3c2748c0fc12fec2546c7f2e3ffd", size = 10034, upload-time = "2025-11-14T09:37:20.293Z" },
+ { url = "https://files.pythonhosted.org/packages/1f/cd/666e44c8deb41e5c9dc5930abf8379edd80bff14eb4d0a56380cdbbbbf9a/pyobjc_framework_automator-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:cdda7b8c48c0f8e15cbb97600ac848fd76cf9837ca3353286a7c02281e9c17a3", size = 10045, upload-time = "2025-11-14T09:37:22.179Z" },
+ { url = "https://files.pythonhosted.org/packages/08/92/75fa03ad8673336689bd663ba153b378e070f159122d8478deb0940039c0/pyobjc_framework_automator-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:e9962ea45875fda6a648449015ccc26cc1229fdbd0166556a7271c60ba6d9011", size = 10192, upload-time = "2025-11-14T09:37:24.836Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-avfoundation"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-coreaudio" },
+ { name = "pyobjc-framework-coremedia" },
+ { name = "pyobjc-framework-quartz" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/cd/42/c026ab308edc2ed5582d8b4b93da6b15d1b6557c0086914a4aabedd1f032/pyobjc_framework_avfoundation-12.1.tar.gz", hash = "sha256:eda0bb60be380f9ba2344600c4231dd58a3efafa99fdc65d3673ecfbb83f6fcb", size = 310047, upload-time = "2025-11-14T10:09:40.069Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/9a/5a/4ef36b309138840ff8cd85364f66c29e27023f291004c335a99f6e87e599/pyobjc_framework_avfoundation-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:82cc2c2d9ab6cc04feeb4700ff251d00f1fcafff573c63d4e87168ff80adb926", size = 83328, upload-time = "2025-11-14T09:37:40.808Z" },
+ { url = "https://files.pythonhosted.org/packages/a6/00/ca471e5dd33f040f69320832e45415d00440260bf7f8221a9df4c4662659/pyobjc_framework_avfoundation-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:bf634f89265b4d93126153200d885b6de4859ed6b3bc65e69ff75540bc398406", size = 83375, upload-time = "2025-11-14T09:37:47.262Z" },
+ { url = "https://files.pythonhosted.org/packages/b3/d4/ade88067deff45858b457648dd82c9363977eb1915efd257232cd06bdac1/pyobjc_framework_avfoundation-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:f8ac7f7e0884ac8f12009cdb9d4fefc2f269294ab2ccfd84520a560859b69cec", size = 83413, upload-time = "2025-11-14T09:37:53.759Z" },
+ { url = "https://files.pythonhosted.org/packages/a7/3a/fa699d748d6351fa0aeca656ea2f9eacc36e31203dfa56bc13c8a3d26d7d/pyobjc_framework_avfoundation-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:51aba2c6816badfb1fb5a2de1b68b33a23f065bf9e3b99d46ede0c8c774ac7a4", size = 83860, upload-time = "2025-11-14T09:38:00.051Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-avkit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-quartz" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/34/a9/e44db1a1f26e2882c140f1d502d508b1f240af9048909dcf1e1a687375b4/pyobjc_framework_avkit-12.1.tar.gz", hash = "sha256:a5c0ddb0cb700f9b09c8afeca2c58952d554139e9bb078236d2355b1fddfb588", size = 28473, upload-time = "2025-11-14T10:09:43.105Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/8c/68/409ee30f3418b76573c70aa05fa4c38e9b8b1d4864093edcc781d66019c2/pyobjc_framework_avkit-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:78bd31a8aed48644e5407b444dec8b1e15ff77af765607b52edf88b8f1213ac7", size = 11583, upload-time = "2025-11-14T09:38:17.569Z" },
+ { url = "https://files.pythonhosted.org/packages/75/34/e77b18f7ed0bd707afd388702e910bdf2d0acee39d1139e8619c916d3eb4/pyobjc_framework_avkit-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:eef2c0a51465de025a4509db05ef18ca2b678bb00ee0a8fbad7fd470edfd58f9", size = 11613, upload-time = "2025-11-14T09:38:19.78Z" },
+ { url = "https://files.pythonhosted.org/packages/11/f2/4a55fdc8baca23dd315dab39479203396db54468a4c5a3e2480748ac68af/pyobjc_framework_avkit-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:c0241548fc7ca3fcd335da05c3dd15d7314fe58debd792317a725d8ae9cf90fa", size = 11620, upload-time = "2025-11-14T09:38:21.904Z" },
+ { url = "https://files.pythonhosted.org/packages/d7/37/76d67c86db80f13f0746b493ae025482cb407b875f3138fc6a6e1fd3d5e3/pyobjc_framework_avkit-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:869fd54ccdac097abe36d7d4ef8945c80b9c886d881173f590b382f6c743ff12", size = 11824, upload-time = "2025-11-14T09:38:23.777Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-avrouting"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/6e/83/15bf6c28ec100dae7f92d37c9e117b3b4ee6b4873db062833e16f1cfd6c4/pyobjc_framework_avrouting-12.1.tar.gz", hash = "sha256:6a6c5e583d14f6501df530a9d0559a32269a821fc8140e3646015f097155cd1c", size = 20031, upload-time = "2025-11-14T10:09:45.701Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/69/a7/5c5725db9c91b492ffbd4ae3e40025deeb9e60fcc7c8fbd5279b52280b95/pyobjc_framework_avrouting-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:9a79f05fb66e337cabc19a9d949c8b29a5145c879f42e29ba02b601b7700d1bb", size = 8431, upload-time = "2025-11-14T09:38:33.018Z" },
+ { url = "https://files.pythonhosted.org/packages/68/54/fa24f666525c1332a11b2de959c9877b0fe08f00f29ecf96964b24246c13/pyobjc_framework_avrouting-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:4c0fb0d3d260527320377a70c87688ca5e4a208b09fddcae2b4257d7fe9b1e18", size = 8450, upload-time = "2025-11-14T09:38:34.941Z" },
+ { url = "https://files.pythonhosted.org/packages/3b/a4/cdbbe5745a49c9c5f5503dbbdd1b90084d4be83bd8503c998db160bb378e/pyobjc_framework_avrouting-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:18c62af1ce9ac99b04c36f66959ca64530d51b62aa0e6f00400dea600112e370", size = 8465, upload-time = "2025-11-14T09:38:37.638Z" },
+ { url = "https://files.pythonhosted.org/packages/29/d7/c709d277e872495f452fe797c619d9b202cd388b655ccf7196724dbbb600/pyobjc_framework_avrouting-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:e5a1d2e4e431aae815e38b75dbe644aa1fd495f8ec1e2194fc175132d7cfc1d3", size = 8630, upload-time = "2025-11-14T09:38:39.284Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-backgroundassets"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/34/d1/e917fba82790495152fd3508c5053827658881cf7e9887ba60def5e3f221/pyobjc_framework_backgroundassets-12.1.tar.gz", hash = "sha256:8da34df9ae4519c360c429415477fdaf3fbba5addbc647b3340b8783454eb419", size = 26210, upload-time = "2025-11-14T10:09:48.792Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/c1/49/33c1c3eaf26a7d89dd414e14939d4f02063d66252d0f51c02082350223e0/pyobjc_framework_backgroundassets-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:17de7990b5ea8047d447339f9e9e6f54b954ffc06647c830932a1688c4743fea", size = 10763, upload-time = "2025-11-14T09:38:46.671Z" },
+ { url = "https://files.pythonhosted.org/packages/de/34/bbba61f0e8ecb0fe0da7aa2c9ea15f7cb0dca2fb2914fcdcd77b782b5c11/pyobjc_framework_backgroundassets-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:2c11cb98650c1a4bc68eeb4b040541ba96613434c5957e98e9bb363413b23c91", size = 10786, upload-time = "2025-11-14T09:38:48.341Z" },
+ { url = "https://files.pythonhosted.org/packages/04/9b/872f9ff0593ffb9dbc029dc775390b0e45fe3278068b28aade8060503003/pyobjc_framework_backgroundassets-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:a089a71b2db471f5af703e35f7a61060164d61eb60a3f482076826dfa5697c7c", size = 10803, upload-time = "2025-11-14T09:38:49.996Z" },
+ { url = "https://files.pythonhosted.org/packages/cc/44/4afc2e8bcf16919b1ab82eaf88067469ea255b0a3390d353fec1002dbd0a/pyobjc_framework_backgroundassets-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:e8c560f1aaa7a4bf6e336806749ce0a20f2a792ab924d9424714e299a59b3edf", size = 11058, upload-time = "2025-11-14T09:38:51.743Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-browserenginekit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-coreaudio" },
+ { name = "pyobjc-framework-coremedia" },
+ { name = "pyobjc-framework-quartz" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/5d/b9/39f9de1730e6f8e73be0e4f0c6087cd9439cbe11645b8052d22e1fb8e69b/pyobjc_framework_browserenginekit-12.1.tar.gz", hash = "sha256:6a1a34a155778ab55ab5f463e885f2a3b4680231264e1fe078e62ddeccce49ed", size = 29120, upload-time = "2025-11-14T10:09:51.582Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/f2/a4/2d576d71b2e4b3e1a9aa9fd62eb73167d90cdc2e07b425bbaba8edd32ff5/pyobjc_framework_browserenginekit-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:41229c766fb3e5bba2de5e580776388297303b4d63d3065fef3f67b77ec46c3f", size = 11526, upload-time = "2025-11-14T09:38:58.861Z" },
+ { url = "https://files.pythonhosted.org/packages/46/e0/8d2cebbfcfd6aacb805ae0ae7ba931f6a39140540b2e1e96719e7be28359/pyobjc_framework_browserenginekit-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:d15766bb841b081447015c9626e2a766febfe651f487893d29c5d72bef976b94", size = 11545, upload-time = "2025-11-14T09:39:00.988Z" },
+ { url = "https://files.pythonhosted.org/packages/5b/2c/d39ab696b0316e1faf112a3aee24ef3bcb5fb42eb5db18ba2d74264a41a8/pyobjc_framework_browserenginekit-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:1aa2da131bbdf81748894c18d253cd2711dc535f1711263c6c604e20cdc094a6", size = 11567, upload-time = "2025-11-14T09:39:02.811Z" },
+ { url = "https://files.pythonhosted.org/packages/0e/dd/624d273beea036ec20e16f8bdaaca6b062da647b785dedf90fa2a92a8cc0/pyobjc_framework_browserenginekit-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:657d78bb5c1a51097560cb3219692321640d0d5c8e57e9160765e1ecfb3fe7ef", size = 11738, upload-time = "2025-11-14T09:39:04.651Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-businesschat"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/4d/da/bc09b6ed19e9ea38ecca9387c291ca11fa680a8132d82b27030f82551c23/pyobjc_framework_businesschat-12.1.tar.gz", hash = "sha256:f6fa3a8369a1a51363e1757530128741d9d09ed90692a1d6777a4c0fbad25868", size = 12055, upload-time = "2025-11-14T10:09:53.436Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/53/88/4c727424b05efa33ed7f6c45e40333e5a8a8dc5bb238e34695addd68463b/pyobjc_framework_businesschat-12.1-py2.py3-none-any.whl", hash = "sha256:f66ce741507b324de3c301d72ba0cfa6aaf7093d7235972332807645c118cc29", size = 3474, upload-time = "2025-11-14T09:39:10.771Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-calendarstore"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/88/41/ae955d1c44dcc18b5b9df45c679e9a08311a0f853b9d981bca760cf1eef2/pyobjc_framework_calendarstore-12.1.tar.gz", hash = "sha256:f9a798d560a3c99ad4c0d2af68767bc5695d8b1aabef04d8377861cd1d6d1670", size = 52272, upload-time = "2025-11-14T10:09:58.48Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/fa/70/f68aebdb7d3fa2dec2e9da9e9cdaa76d370de326a495917dbcde7bb7711e/pyobjc_framework_calendarstore-12.1-py2.py3-none-any.whl", hash = "sha256:18533e0fcbcdd29ee5884dfbd30606710f65df9b688bf47daee1438ee22e50cc", size = 5285, upload-time = "2025-11-14T09:39:12.473Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-callkit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/1a/c0/1859d4532d39254df085309aff55b85323576f00a883626325af40da4653/pyobjc_framework_callkit-12.1.tar.gz", hash = "sha256:fd6dc9688b785aab360139d683be56f0844bf68bf5e45d0eb770cb68221083cc", size = 29171, upload-time = "2025-11-14T10:10:01.336Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/2b/f6/aafd14b31e00d59d830f9a8e8e46c4f41a249f0370499d5b017599362cf1/pyobjc_framework_callkit-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:e73beae08e6a32bcced8d5bdb45b52d6a0866dd1485eaaddba6063f17d41fcb0", size = 11273, upload-time = "2025-11-14T09:39:16.837Z" },
+ { url = "https://files.pythonhosted.org/packages/2e/b7/b3a498b14751b4be6af5272c9be9ded718aa850ebf769b052c7d610a142a/pyobjc_framework_callkit-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:12adc0ace464a057f8908187698e1d417c6c53619797a69d096f4329bffb1089", size = 11334, upload-time = "2025-11-14T09:39:18.622Z" },
+ { url = "https://files.pythonhosted.org/packages/37/30/f434921c17a59d8db06783189ca98ccf291d5366be364f96439e987c1b13/pyobjc_framework_callkit-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:b8909402f8690ea2fe8fa7c0256b5c491435f20881832808b86433f526ff28f8", size = 11347, upload-time = "2025-11-14T09:39:20.412Z" },
+ { url = "https://files.pythonhosted.org/packages/f0/b8/c6a52c3c2e1e0bd23a84fef0d2cb089c456d62add59f87d8510ffe871068/pyobjc_framework_callkit-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:9ec6635b6a6fecde6e5252ceff76c71d699ed8e0f3ebc6fd220a351dc653040b", size = 11558, upload-time = "2025-11-14T09:39:22.266Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-carbon"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/0c/0f/9ab8e518a4e5ac4a1e2fdde38a054c32aef82787ff7f30927345c18b7765/pyobjc_framework_carbon-12.1.tar.gz", hash = "sha256:57a72807db252d5746caccc46da4bd20ff8ea9e82109af9f72735579645ff4f0", size = 37293, upload-time = "2025-11-14T10:10:04.464Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/a4/9e/91853c8f98b9d5bccf464113908620c94cc12c2a3e4625f3ce172e3ea4bc/pyobjc_framework_carbon-12.1-py2.py3-none-any.whl", hash = "sha256:f8b719b3c7c5cf1d61ac7c45a8a70b5e5e5a83fa02f5194c2a48a7e81a3d1b7f", size = 4625, upload-time = "2025-11-14T09:39:27.937Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-cfnetwork"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/d2/6a/f5f0f191956e187db85312cbffcc41bf863670d121b9190b4a35f0d36403/pyobjc_framework_cfnetwork-12.1.tar.gz", hash = "sha256:2d16e820f2d43522c793f55833fda89888139d7a84ca5758548ba1f3a325a88d", size = 44383, upload-time = "2025-11-14T10:10:08.428Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/f0/7e/82aca783499b690163dd19d5ccbba580398970874a3431bfd7c14ceddbb3/pyobjc_framework_cfnetwork-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:3bf93c0f3d262f629e72f8dd43384d0930ed8e610b3fc5ff555c0c1a1e05334a", size = 18949, upload-time = "2025-11-14T09:39:32.924Z" },
+ { url = "https://files.pythonhosted.org/packages/f9/0b/28034e63f3a25b30ede814469c3f57d44268cbced19664c84a8664200f9d/pyobjc_framework_cfnetwork-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:92760da248c757085fc39bce4388a0f6f0b67540e51edf60a92ad60ca907d071", size = 19135, upload-time = "2025-11-14T09:39:36.382Z" },
+ { url = "https://files.pythonhosted.org/packages/f4/36/d6b95a5b156de5e2c071ecb7f7056f0badb3a0d09e0dbcf0d8d35743f822/pyobjc_framework_cfnetwork-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:86cc3f650d3169cd8ce4a1438219aa750accac0efc29539920ab0a7e75e25ab4", size = 19135, upload-time = "2025-11-14T09:39:39.95Z" },
+ { url = "https://files.pythonhosted.org/packages/4b/23/ff66133af4592e123320337f443aa6e36993cc48d6c10f6e7436e01678b1/pyobjc_framework_cfnetwork-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:5ff3e246e5186b9bad23b2e4e856ca87eaa9329f5904643c5484510059a07e24", size = 19412, upload-time = "2025-11-14T09:39:42.412Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-cinematic"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-avfoundation" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-coremedia" },
+ { name = "pyobjc-framework-metal" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/67/4e/f4cc7f9f7f66df0290c90fe445f1ff5aa514c6634f5203fe049161053716/pyobjc_framework_cinematic-12.1.tar.gz", hash = "sha256:795068c30447548c0e8614e9c432d4b288b13d5614622ef2f9e3246132329b06", size = 21215, upload-time = "2025-11-14T10:10:10.795Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/c9/a0/cd85c827ce5535c08d936e5723c16ee49f7ff633f2e9881f4f58bf83e4ce/pyobjc_framework_cinematic-12.1-py2.py3-none-any.whl", hash = "sha256:c003543bb6908379680a93dfd77a44228686b86c118cf3bc930f60241d0cd141", size = 5031, upload-time = "2025-11-14T09:39:49.003Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-classkit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/ac/ef/67815278023b344a79c7e95f748f647245d6f5305136fc80615254ad447c/pyobjc_framework_classkit-12.1.tar.gz", hash = "sha256:8d1e9dd75c3d14938ff533d88b72bca2d34918e4461f418ea323bfb2498473b4", size = 26298, upload-time = "2025-11-14T10:10:13.406Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/14/e2/67bd062fbc9761c34b9911ed099ee50ccddc3032779ce420ca40083ee15c/pyobjc_framework_classkit-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:bd90aacc68eff3412204a9040fa81eb18348cbd88ed56d33558349f3e51bff52", size = 8857, upload-time = "2025-11-14T09:39:53.283Z" },
+ { url = "https://files.pythonhosted.org/packages/87/5e/cf43c647af872499fc8e80cc6ac6e9ad77d9c77861dc2e62bdd9b01473ce/pyobjc_framework_classkit-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:c027a3cd9be5fee3f605589118b8b278297c384a271f224c1a98b224e0c087e6", size = 8877, upload-time = "2025-11-14T09:39:54.979Z" },
+ { url = "https://files.pythonhosted.org/packages/a5/47/f89917b4683a8f61c64d5d30d64ed0a5c1cfd9f0dd9dfb099b3465c73bcf/pyobjc_framework_classkit-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:0ac959a4e91a40865f12f041c083fa8862672f13e596c983f2b99afc8c67bc4e", size = 8890, upload-time = "2025-11-14T09:39:56.65Z" },
+ { url = "https://files.pythonhosted.org/packages/b4/9b/8a0dc753e73001026663fe8556895b23fbf6c238a705bfc86d8ce191eee3/pyobjc_framework_classkit-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:61fdac9e3bad384b47725587b77f932dbed71d0ae63b749eddfa390791eed4a2", size = 9043, upload-time = "2025-11-14T09:39:58.684Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-cloudkit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-accounts" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-coredata" },
+ { name = "pyobjc-framework-corelocation" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/2d/09/762ee4f3ae8568b8e0e5392c705bc4aa1929aa454646c124ca470f1bf9fc/pyobjc_framework_cloudkit-12.1.tar.gz", hash = "sha256:1dddd38e60863f88adb3d1d37d3b4ccb9cbff48c4ef02ab50e36fa40c2379d2f", size = 53730, upload-time = "2025-11-14T10:10:17.831Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/35/71/cbef7179bf1a594558ea27f1e5ad18f5c17ef71a8a24192aae16127bc849/pyobjc_framework_cloudkit-12.1-py2.py3-none-any.whl", hash = "sha256:875e37bf1a2ce3d05c2492692650104f2d908b56b71a0aedf6620bc517c6c9ca", size = 11090, upload-time = "2025-11-14T09:40:04.207Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-cocoa"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/02/a3/16ca9a15e77c061a9250afbae2eae26f2e1579eb8ca9462ae2d2c71e1169/pyobjc_framework_cocoa-12.1.tar.gz", hash = "sha256:5556c87db95711b985d5efdaaf01c917ddd41d148b1e52a0c66b1a2e2c5c1640", size = 2772191, upload-time = "2025-11-14T10:13:02.069Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/3f/07/5760735c0fffc65107e648eaf7e0991f46da442ac4493501be5380e6d9d4/pyobjc_framework_cocoa-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:f52228bcf38da64b77328787967d464e28b981492b33a7675585141e1b0a01e6", size = 383812, upload-time = "2025-11-14T09:40:53.169Z" },
+ { url = "https://files.pythonhosted.org/packages/95/bf/ee4f27ec3920d5c6fc63c63e797c5b2cc4e20fe439217085d01ea5b63856/pyobjc_framework_cocoa-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:547c182837214b7ec4796dac5aee3aa25abc665757b75d7f44f83c994bcb0858", size = 384590, upload-time = "2025-11-14T09:41:17.336Z" },
+ { url = "https://files.pythonhosted.org/packages/ad/31/0c2e734165abb46215797bd830c4bdcb780b699854b15f2b6240515edcc6/pyobjc_framework_cocoa-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:5a3dcd491cacc2f5a197142b3c556d8aafa3963011110102a093349017705118", size = 384689, upload-time = "2025-11-14T09:41:41.478Z" },
+ { url = "https://files.pythonhosted.org/packages/23/3b/b9f61be7b9f9b4e0a6db18b3c35c4c4d589f2d04e963e2174d38c6555a92/pyobjc_framework_cocoa-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:914b74328c22d8ca261d78c23ef2befc29776e0b85555973927b338c5734ca44", size = 388843, upload-time = "2025-11-14T09:42:05.719Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-collaboration"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/64/21/77fe64b39eae98412de1a0d33e9c735aa9949d53fff6b2d81403572b410b/pyobjc_framework_collaboration-12.1.tar.gz", hash = "sha256:2afa264d3233fc0a03a56789c6fefe655ffd81a2da4ba1dc79ea0c45931ad47b", size = 14299, upload-time = "2025-11-14T10:13:04.631Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/2a/66/1507de01f1e2b309f8e11553a52769e4e2e9939ed770b5b560ef5bc27bc1/pyobjc_framework_collaboration-12.1-py2.py3-none-any.whl", hash = "sha256:182d6e6080833b97f9bef61738ae7bacb509714538f0d7281e5f0814c804b315", size = 4907, upload-time = "2025-11-14T09:42:55.781Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-colorsync"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c0/b4/706e4cc9db25b400201fc90f3edfaa1ab2d51b400b19437b043a68532078/pyobjc_framework_colorsync-12.1.tar.gz", hash = "sha256:d69dab7df01245a8c1bd536b9231c97993a5d1a2765d77692ce40ebbe6c1b8e9", size = 25269, upload-time = "2025-11-14T10:13:07.522Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/e8/e1/82e45c712f43905ee1e6d585180764e8fa6b6f1377feb872f9f03c8c1fb8/pyobjc_framework_colorsync-12.1-py2.py3-none-any.whl", hash = "sha256:41e08d5b9a7af4b380c9adab24c7ff59dfd607b3073ae466693a3e791d8ffdc9", size = 6020, upload-time = "2025-11-14T09:42:57.504Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-compositorservices"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-metal" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/54/c5/0ba31d7af7e464b7f7ece8c2bd09112bdb0b7260848402e79ba6aacc622c/pyobjc_framework_compositorservices-12.1.tar.gz", hash = "sha256:028e357bbee7fbd3723339a321bbe14e6da5a772708a661a13eea5f17c89e4ab", size = 23292, upload-time = "2025-11-14T10:13:10.392Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/f9/34/5a2de8d531dbb88023898e0b5d2ce8edee14751af6c70e6103f6aa31a669/pyobjc_framework_compositorservices-12.1-py2.py3-none-any.whl", hash = "sha256:9ef22d4eacd492e13099b9b8936db892cdbbef1e3d23c3484e0ed749f83c4984", size = 5910, upload-time = "2025-11-14T09:42:59.154Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-contacts"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/4b/a0/ce0542d211d4ea02f5cbcf72ee0a16b66b0d477a4ba5c32e00117703f2f0/pyobjc_framework_contacts-12.1.tar.gz", hash = "sha256:89bca3c5cf31404b714abaa1673577e1aaad6f2ef49d4141c6dbcc0643a789ad", size = 42378, upload-time = "2025-11-14T10:13:14.203Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/94/f5/5d2c03cf5219f2e35f3f908afa11868e9096aff33b29b41d63f2de3595f2/pyobjc_framework_contacts-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:8ab86070895a005239256d207e18209b1a79d35335b6604db160e8375a7165e6", size = 12086, upload-time = "2025-11-14T09:43:03.225Z" },
+ { url = "https://files.pythonhosted.org/packages/32/c8/2c4638c0d06447886a34070eebb9ba57407d4dd5f0fcb7ab642568272b88/pyobjc_framework_contacts-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:2e5ce33b686eb9c0a39351938a756442ea8dea88f6ae2f16bff5494a8569c687", size = 12165, upload-time = "2025-11-14T09:43:05.119Z" },
+ { url = "https://files.pythonhosted.org/packages/25/43/e322dd14c77eada5a4f327f5bc094061c90efabc774b30396d1155a69c44/pyobjc_framework_contacts-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:62d985098aa86a86d23bff408aac47389680da4edc61f6acf10b2197efcbd0e0", size = 12177, upload-time = "2025-11-14T09:43:06.957Z" },
+ { url = "https://files.pythonhosted.org/packages/0a/37/53eba15f2e31950056c63b78732b73379ddbf946c5e6681f3b2773dcf282/pyobjc_framework_contacts-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:ab1d78f363dfede16bd5d951327332564bae86f68834d1e657dd18fe4dc12082", size = 12346, upload-time = "2025-11-14T09:43:08.865Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-contactsui"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-contacts" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/cd/0c/7bb7f898456a81d88d06a1084a42e374519d2e40a668a872b69b11f8c1f9/pyobjc_framework_contactsui-12.1.tar.gz", hash = "sha256:aaeca7c9e0c9c4e224d73636f9a558f9368c2c7422155a41fd4d7a13613a77c1", size = 18769, upload-time = "2025-11-14T10:13:16.301Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/04/e3/8d330640bf0337289834334c54c599fec2dad38a8a3b736d40bcb5d8db6e/pyobjc_framework_contactsui-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:10e7ce3b105795919605be89ebeecffd656e82dbf1bafa5db6d51d6def2265ee", size = 7871, upload-time = "2025-11-14T09:43:16.973Z" },
+ { url = "https://files.pythonhosted.org/packages/f3/ab/319aa52dfe6f836f4dc542282c2c13996222d4f5c9ea7ff8f391b12dac83/pyobjc_framework_contactsui-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:057f40d2f6eb1b169a300675ec75cc7a747cddcbcee8ece133e652a7086c5ab5", size = 7888, upload-time = "2025-11-14T09:43:18.502Z" },
+ { url = "https://files.pythonhosted.org/packages/fd/9c/c9a71681e2ad8695222dbdbbe740af22cc354e9130df6108f9bfe90a4100/pyobjc_framework_contactsui-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:2ee2eccb633bc772ecb49dba7199546154efc2db5727992229cdf84b3f6ac84f", size = 7907, upload-time = "2025-11-14T09:43:20.409Z" },
+ { url = "https://files.pythonhosted.org/packages/a0/54/abdb4c5f53323edc1e02bd0916133c4e6b82ad268eded668ef7b40a1e6c9/pyobjc_framework_contactsui-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:c9d64bbc4cfae0f082627b57f7e29e71b924af970f344b106b17fb68e13f7da0", size = 8056, upload-time = "2025-11-14T09:43:22Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-coreaudio"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/84/d1/0b884c5564ab952ff5daa949128c64815300556019c1bba0cf2ca752a1a0/pyobjc_framework_coreaudio-12.1.tar.gz", hash = "sha256:a9e72925fcc1795430496ce0bffd4ddaa92c22460a10308a7283ade830089fe1", size = 75077, upload-time = "2025-11-14T10:13:22.345Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/9e/25/491ff549fd9a40be4416793d335bff1911d3d1d1e1635e3b0defbd2cf585/pyobjc_framework_coreaudio-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:a452de6b509fa4a20160c0410b72330ac871696cd80237883955a5b3a4de8f2a", size = 35327, upload-time = "2025-11-14T09:43:32.523Z" },
+ { url = "https://files.pythonhosted.org/packages/a9/48/05b5192122e23140cf583eac99ccc5bf615591d6ff76483ba986c38ee750/pyobjc_framework_coreaudio-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:a5ad6309779663f846ab36fe6c49647e470b7e08473c3e48b4f004017bdb68a4", size = 36908, upload-time = "2025-11-14T09:43:36.108Z" },
+ { url = "https://files.pythonhosted.org/packages/3d/ce/45808618fefc760e2948c363e0a3402ff77690c8934609cd07b19bc5b15f/pyobjc_framework_coreaudio-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:3d8ef424850c8ae2146f963afaec6c4f5bf0c2e412871e68fb6ecfb209b8376f", size = 36935, upload-time = "2025-11-14T09:43:39.414Z" },
+ { url = "https://files.pythonhosted.org/packages/bf/f6/0d74d9464bfb4f39451abf745174ec0c4d5c5ebf1c2fcb7556263ae3f75a/pyobjc_framework_coreaudio-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:6552624df39dbc68ff9328f244ba56f59234ecbde8455db1e617a71bc4f3dd3a", size = 38390, upload-time = "2025-11-14T09:43:43.194Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-coreaudiokit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-coreaudio" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/41/1c/5c7e39b9361d4eec99b9115b593edd9825388acd594cb3b4519f8f1ac12c/pyobjc_framework_coreaudiokit-12.1.tar.gz", hash = "sha256:b83624f8de3068ab2ca279f786be0804da5cf904ff9979d96007b69ef4869e1e", size = 20137, upload-time = "2025-11-14T10:13:24.611Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/c2/53/e4233fbe5b94b124f5612e1edc130a9280c4674a1d1bf42079ea14b816e1/pyobjc_framework_coreaudiokit-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:e1144c272f8d6429a34a6757700048f4631eb067c4b08d4768ddc28c371a7014", size = 7250, upload-time = "2025-11-14T09:43:53.208Z" },
+ { url = "https://files.pythonhosted.org/packages/19/d7/f171c04c6496afeaad2ab658b0c810682c8407127edc94d4b3f3b90c2bb1/pyobjc_framework_coreaudiokit-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:97d5dd857e73d5b597cfc980972b021314b760e2f5bdde7bbba0334fbf404722", size = 7273, upload-time = "2025-11-14T09:43:55.411Z" },
+ { url = "https://files.pythonhosted.org/packages/81/9a/6cb91461b07c38b2db7918ee756f05fd704120b75ddc1a759e04af50351b/pyobjc_framework_coreaudiokit-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:dc1589cda7a4ae0560bf73e1a0623bb710de09ef030d585035f8a428a3e8d6a1", size = 7284, upload-time = "2025-11-14T09:43:57.109Z" },
+ { url = "https://files.pythonhosted.org/packages/21/d8/1418fb222c6502ce2a99c415982895b510f6c48bdf60ca0dbed9897d96df/pyobjc_framework_coreaudiokit-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:6ec70b69d21925e02602cc22c5e0132daedc15ce65b7e3cc863fdb5f13cc23e3", size = 7446, upload-time = "2025-11-14T09:43:58.714Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-corebluetooth"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/4b/25/d21d6cb3fd249c2c2aa96ee54279f40876a0c93e7161b3304bf21cbd0bfe/pyobjc_framework_corebluetooth-12.1.tar.gz", hash = "sha256:8060c1466d90bbb9100741a1091bb79975d9ba43911c9841599879fc45c2bbe0", size = 33157, upload-time = "2025-11-14T10:13:28.064Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/57/7a/26ae106beb97e9c4745065edb3ce3c2bdd91d81f5b52b8224f82ce9d5fb9/pyobjc_framework_corebluetooth-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:37e6456c8a076bd5a2bdd781d0324edd5e7397ef9ac9234a97433b522efb13cf", size = 13189, upload-time = "2025-11-14T09:44:06.229Z" },
+ { url = "https://files.pythonhosted.org/packages/2a/56/01fef62a479cdd6ff9ee40b6e062a205408ff386ce5ba56d7e14a71fcf73/pyobjc_framework_corebluetooth-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:fe72c9732ee6c5c793b9543f08c1f5bdd98cd95dfc9d96efd5708ec9d6eeb213", size = 13209, upload-time = "2025-11-14T09:44:08.203Z" },
+ { url = "https://files.pythonhosted.org/packages/e0/6c/831139ebf6a811aed36abfdfad846bc380dcdf4e6fb751a310ce719ddcfd/pyobjc_framework_corebluetooth-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:5a894f695e6c672f0260327103a31ad8b98f8d4fb9516a0383db79a82a7e58dc", size = 13229, upload-time = "2025-11-14T09:44:10.463Z" },
+ { url = "https://files.pythonhosted.org/packages/09/3c/3a6fe259a9e0745aa4612dee86b61b4fd7041c44b62642814e146b654463/pyobjc_framework_corebluetooth-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:1daf07a0047c3ed89fab84ad5f6769537306733b6a6e92e631581a0f419e3f32", size = 13409, upload-time = "2025-11-14T09:44:12.438Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-coredata"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/3e/c5/8cd46cd4f1b7cf88bdeed3848f830ea9cdcc4e55cd0287a968a2838033fb/pyobjc_framework_coredata-12.1.tar.gz", hash = "sha256:1e47d3c5e51fdc87a90da62b97cae1bc49931a2bb064db1305827028e1fc0ffa", size = 124348, upload-time = "2025-11-14T10:13:36.435Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/6b/a8/4c694c85365071baef36013a7460850dcf6ebfea0ba239e52d7293cdcb93/pyobjc_framework_coredata-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:c861dc42b786243cbd96d9ea07d74023787d03637ef69a2f75a1191a2f16d9d6", size = 16395, upload-time = "2025-11-14T09:44:21.105Z" },
+ { url = "https://files.pythonhosted.org/packages/a3/29/fe24dc81e0f154805534923a56fe572c3b296092f086cf5a239fccc2d46a/pyobjc_framework_coredata-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:a3ee3581ca23ead0b152257e98622fe0bf7e7948f30a62a25a17cafe28fe015e", size = 16409, upload-time = "2025-11-14T09:44:23.582Z" },
+ { url = "https://files.pythonhosted.org/packages/f8/12/a22773c3a590d4923c74990d6714c4463bd1e183daaa67d6b00c9f325b33/pyobjc_framework_coredata-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:79f68577a7e96c57559ec844a129a5edce6827cdfafe49bf31524a488d715a37", size = 16420, upload-time = "2025-11-14T09:44:26.179Z" },
+ { url = "https://files.pythonhosted.org/packages/a6/32/9595f0c8727d6ac312d18d23fc4a327c34c6ab873d2b760bbc40cf063726/pyobjc_framework_coredata-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:279b39bdb2a9c5e4d0377c1e81263b7d137bf2be37e15d6b5b2403598596f0e3", size = 16576, upload-time = "2025-11-14T09:44:28.266Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-corehaptics"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/3a/2f/74a3da79d9188b05dd4be4428a819ea6992d4dfaedf7d629027cf1f57bfc/pyobjc_framework_corehaptics-12.1.tar.gz", hash = "sha256:521dd2986c8a4266d583dd9ed9ae42053b11ae7d3aa89bf53fbee88307d8db10", size = 22164, upload-time = "2025-11-14T10:13:38.941Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/25/f4/f469d6a9cac7c195f3d08fa65f94c32dd1dcf97a54b481be648fb3a7a5f3/pyobjc_framework_corehaptics-12.1-py2.py3-none-any.whl", hash = "sha256:a3b07d36ddf5c86a9cdaa411ab53d09553d26ea04fc7d4f82d21a84f0fc05fc0", size = 5382, upload-time = "2025-11-14T09:44:34.725Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-corelocation"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/cc/79/b75885e0d75397dc2fe1ed9ca80be2b64c18b817f5fb924277cb1bf7b163/pyobjc_framework_corelocation-12.1.tar.gz", hash = "sha256:3674e9353f949d91dde6230ad68f6d5748a7f0424751e08a2c09d06050d66231", size = 53511, upload-time = "2025-11-14T10:13:43.384Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/34/ac/44b6cb414ce647da8328d0ed39f0a8b6eb54e72189ce9049678ce2cb04c3/pyobjc_framework_corelocation-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:ffc96b9ba504b35fe3e0fcfb0153e68fdfca6fe71663d240829ceab2d7122588", size = 12700, upload-time = "2025-11-14T09:44:38.717Z" },
+ { url = "https://files.pythonhosted.org/packages/71/57/1b670890fbf650f1a00afe5ee897ea3856a4a1417c2304c633ee2e978ed0/pyobjc_framework_corelocation-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:8c35ad29a062fea7d417fd8997a9309660ba7963f2847c004e670efbe6bb5b00", size = 12721, upload-time = "2025-11-14T09:44:41.185Z" },
+ { url = "https://files.pythonhosted.org/packages/9f/09/3da1947a5908d70461596eda5a0dc486ae807dc1c5a1ce2bf98567b474be/pyobjc_framework_corelocation-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:616eec0ccfcdcff7696bccf88c1aa39935387e595b22dd4c14842567aa0986a6", size = 12736, upload-time = "2025-11-14T09:44:42.977Z" },
+ { url = "https://files.pythonhosted.org/packages/5d/9a/e5e11ec90500ce2c809a46113d3ebd70dd4b4ce450072db9a85f86e9a30f/pyobjc_framework_corelocation-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:0a80ba8e8d9120eb80486235c483a0c734cb451265e5aa81bcf315f0e644eb00", size = 12867, upload-time = "2025-11-14T09:44:44.89Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-coremedia"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/da/7d/5ad600ff7aedfef8ba8f51b11d9aaacdf247b870bd14045d6e6f232e3df9/pyobjc_framework_coremedia-12.1.tar.gz", hash = "sha256:166c66a9c01e7a70103f3ca44c571431d124b9070612ef63a1511a4e6d9d84a7", size = 89566, upload-time = "2025-11-14T10:13:49.788Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/c8/bc/e66de468b3777d8fece69279cf6d2af51d2263e9a1ccad21b90c35c74b1b/pyobjc_framework_coremedia-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:ee7b822c9bb674b5b0a70bfb133410acae354e9241b6983f075395f3562f3c46", size = 29503, upload-time = "2025-11-14T09:44:54.716Z" },
+ { url = "https://files.pythonhosted.org/packages/c8/ae/f773cdc33c34a3f9ce6db829dbf72661b65c28ea9efaec8940364185b977/pyobjc_framework_coremedia-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:161a627f5c8cd30a5ebb935189f740e21e6cd94871a9afd463efdb5d51e255fa", size = 29396, upload-time = "2025-11-14T09:44:57.563Z" },
+ { url = "https://files.pythonhosted.org/packages/a5/ea/aee26a475b4af8ed4152d3c50b1b8955241b8e95ae789aa9ee296953bc6a/pyobjc_framework_coremedia-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:98e885b7a092083fceaef0a7fc406a01ba7bcd3318fb927e59e055931c99cac8", size = 29414, upload-time = "2025-11-14T09:45:01.336Z" },
+ { url = "https://files.pythonhosted.org/packages/db/9d/5ff10ee0ff539e125c96b8cff005457558766f942919814c968c3367cc32/pyobjc_framework_coremedia-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:d2b84149c1b3e65ec9050a3e5b617e6c0b4cdad2ab622c2d8c5747a20f013e16", size = 29477, upload-time = "2025-11-14T09:45:04.218Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-coremediaio"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/08/8e/23baee53ccd6c011c965cff62eb55638b4088c3df27d2bf05004105d6190/pyobjc_framework_coremediaio-12.1.tar.gz", hash = "sha256:880b313b28f00b27775d630174d09e0b53d1cdbadb74216618c9dd5b3eb6806a", size = 51100, upload-time = "2025-11-14T10:13:54.277Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/46/6c/88514f8938719f74aa13abb9fd5492499f1834391133809b4e125c3e7150/pyobjc_framework_coremediaio-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:3da79c5b9785c5ccc1f5982de61d4d0f1ba29717909eb6720734076ccdc0633c", size = 17218, upload-time = "2025-11-14T09:45:15.294Z" },
+ { url = "https://files.pythonhosted.org/packages/d4/0c/9425c53c9a8c26e468e065ba12ef076bab20197ff7c82052a6dddd46d42b/pyobjc_framework_coremediaio-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:1108f8a278928fbca465f95123ea4a56456bd6571c1dc8b91793e6c61d624517", size = 17277, upload-time = "2025-11-14T09:45:17.457Z" },
+ { url = "https://files.pythonhosted.org/packages/6d/d1/0267ec27841ee96458e6b669ce5b0c67d040ef3d5de90fa4e945ff989c48/pyobjc_framework_coremediaio-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:85ae768294ec307d5b502c075aeae1c53a731afc2f7f0307c9bef785775e26a6", size = 17249, upload-time = "2025-11-14T09:45:20.42Z" },
+ { url = "https://files.pythonhosted.org/packages/ca/4e/bd0114aa052aaffc250b0c00567b42df8c7cb35517488c3238bcc964d016/pyobjc_framework_coremediaio-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:6136a600a1435b9e798427984088a7bd5e68778e1bcf48a23a0eb9bc946a06f0", size = 17573, upload-time = "2025-11-14T09:45:22.572Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-coremidi"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/75/96/2d583060a71a73c8a7e6d92f2a02675621b63c1f489f2639e020fae34792/pyobjc_framework_coremidi-12.1.tar.gz", hash = "sha256:3c6f1fd03997c3b0f20ab8545126b1ce5f0cddcc1587dffacad876c161da8c54", size = 55587, upload-time = "2025-11-14T10:13:58.903Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/76/d5/49b8720ec86f64e3dc3c804bd7e16fabb2a234a9a8b1b6753332ed343b4e/pyobjc_framework_coremidi-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:af3cdf195e8d5e30d1203889cc4107bebc6eb901aaa81bf3faf15e9ffaca0735", size = 24282, upload-time = "2025-11-14T09:45:32.288Z" },
+ { url = "https://files.pythonhosted.org/packages/e3/2d/99520f6f1685e4cad816e55cbf6d85f8ce6ea908107950e2d37dc17219d8/pyobjc_framework_coremidi-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:e84ffc1de59691c04201b0872e184fe55b5589f3a14876bd14460f3b5f3cd109", size = 24317, upload-time = "2025-11-14T09:45:34.92Z" },
+ { url = "https://files.pythonhosted.org/packages/a9/2a/093ec8366d5f9e6c45e750310121ea572b8696518c51c4bbcf1623c01cf1/pyobjc_framework_coremidi-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:69720f38cfeea4299f31cb3e15d07e5d43e55127605f95e001794c7850c1c637", size = 24333, upload-time = "2025-11-14T09:45:37.577Z" },
+ { url = "https://files.pythonhosted.org/packages/0e/cf/f03a0b44d1cfcfa9837cdfd6385c1e7d1e42301076d376329a44b6cbec03/pyobjc_framework_coremidi-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:06e5bce0a28bac21f09bcfedda46d93b2152c138764380314d99f2370a8c00f2", size = 24493, upload-time = "2025-11-14T09:45:40.591Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-coreml"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/30/2d/baa9ea02cbb1c200683cb7273b69b4bee5070e86f2060b77e6a27c2a9d7e/pyobjc_framework_coreml-12.1.tar.gz", hash = "sha256:0d1a4216891a18775c9e0170d908714c18e4f53f9dc79fb0f5263b2aa81609ba", size = 40465, upload-time = "2025-11-14T10:14:02.265Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/34/0f/f55369da4a33cfe1db38a3512aac4487602783d3a1d572d2c8c4ccce6abc/pyobjc_framework_coreml-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:16dafcfb123f022e62f47a590a7eccf7d0cb5957a77fd5f062b5ee751cb5a423", size = 11331, upload-time = "2025-11-14T09:45:50.445Z" },
+ { url = "https://files.pythonhosted.org/packages/bb/39/4defef0deb25c5d7e3b7826d301e71ac5b54ef901b7dac4db1adc00f172d/pyobjc_framework_coreml-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:10dc8e8db53d7631ebc712cad146e3a9a9a443f4e1a037e844149a24c3c42669", size = 11356, upload-time = "2025-11-14T09:45:52.271Z" },
+ { url = "https://files.pythonhosted.org/packages/ae/3f/3749964aa3583f8c30d9996f0d15541120b78d307bb3070f5e47154ef38d/pyobjc_framework_coreml-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:48fa3bb4a03fa23e0e36c93936dca2969598e4102f4b441e1663f535fc99cd31", size = 11371, upload-time = "2025-11-14T09:45:54.105Z" },
+ { url = "https://files.pythonhosted.org/packages/9c/c8/cf20ea91ae33f05f3b92dec648c6f44a65f86d1a64c1d6375c95b85ccb7c/pyobjc_framework_coreml-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:71de5b37e6a017e3ed16645c5d6533138f24708da5b56c35c818ae49d0253ee1", size = 11600, upload-time = "2025-11-14T09:45:55.976Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-coremotion"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/2c/eb/abef7d405670cf9c844befc2330a46ee59f6ff7bac6f199bf249561a2ca6/pyobjc_framework_coremotion-12.1.tar.gz", hash = "sha256:8e1b094d34084cc8cf07bedc0630b4ee7f32b0215011f79c9e3cd09d205a27c7", size = 33851, upload-time = "2025-11-14T10:14:05.619Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/77/fd/0d24796779e4d8187abbce5d06cfd7614496d57a68081c5ff1e978b398f9/pyobjc_framework_coremotion-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:ed8cb67927985d97b1dd23ab6a4a1b716fc7c409c35349816108781efdcbb5b6", size = 10382, upload-time = "2025-11-14T09:46:03.438Z" },
+ { url = "https://files.pythonhosted.org/packages/bc/75/89fa4aab818aeca21ac0a60b7ceb89a9e685df0ddd3828d36a6f84a0cff0/pyobjc_framework_coremotion-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:a77908ab83c422030f913a2a761d196359ab47f6d1e7c76f21de2c6c05ea2f5f", size = 10406, upload-time = "2025-11-14T09:46:05.076Z" },
+ { url = "https://files.pythonhosted.org/packages/4d/dd/9a4cc56c55f7ffece2e100664503cb27b4f4265d57656d050a3af1c71d94/pyobjc_framework_coremotion-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:b7b0d47b5889ca0b6e3a687bd1f83a13d3bb59c07a1c4c37dcca380ede5d6e81", size = 10423, upload-time = "2025-11-14T09:46:07.051Z" },
+ { url = "https://files.pythonhosted.org/packages/0d/4d/660b47e9e0bc10ae87f85bede39e3f922b8382e0f6ac273058183d0bdc2f/pyobjc_framework_coremotion-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:531ea82945266d78e23d1f35de0cae2391e18677ed54120b90a4b9dd19f32596", size = 10570, upload-time = "2025-11-14T09:46:09.047Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-coreservices"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-fsevents" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/4c/b3/52338a3ff41713f7d7bccaf63bef4ba4a8f2ce0c7eaff39a3629d022a79a/pyobjc_framework_coreservices-12.1.tar.gz", hash = "sha256:fc6a9f18fc6da64c166fe95f2defeb7ac8a9836b3b03bb6a891d36035260dbaa", size = 366150, upload-time = "2025-11-14T10:14:28.133Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/55/56/c905deb5ab6f7f758faac3f2cbc6f62fde89f8364837b626801bba0975c3/pyobjc_framework_coreservices-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:b6ef07bcf99e941395491f1efcf46e99e5fb83eb6bfa12ae5371135d83f731e1", size = 30196, upload-time = "2025-11-14T09:46:19.356Z" },
+ { url = "https://files.pythonhosted.org/packages/61/6c/33984caaf497fc5a6f86350d7ca4fac8abeb2bc33203edc96955a21e8c05/pyobjc_framework_coreservices-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:8751dc2edcb7cfa248bf8a274c4d6493e8d53ef28a843827a4fc9a0a8b04b8be", size = 30206, upload-time = "2025-11-14T09:46:22.732Z" },
+ { url = "https://files.pythonhosted.org/packages/a7/6f/4a6eb2f2bbdbf66a1b35f272d8504ce6f098947f9343df474f0d15a2b507/pyobjc_framework_coreservices-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:96574fb24d2b8b507901ef7be7fcb70b7f49e110bd050a411b90874cc18c7c7b", size = 30226, upload-time = "2025-11-14T09:46:25.565Z" },
+ { url = "https://files.pythonhosted.org/packages/60/6e/78a831834dc7f84a2d61efb47d212239f3ae3d16aa5512f1265a8f6c0162/pyobjc_framework_coreservices-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:227fb4144a87c6c97a5f737fb0c666293b33e54f0ffb500f2c420da6c110ba2d", size = 30229, upload-time = "2025-11-14T09:46:28.51Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-corespotlight"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/99/d0/88ca73b0cf23847af463334989dd8f98e44f801b811e7e1d8a5627ec20b4/pyobjc_framework_corespotlight-12.1.tar.gz", hash = "sha256:57add47380cd0bbb9793f50a4a4b435a90d4ebd2a33698e058cb353ddfb0d068", size = 38002, upload-time = "2025-11-14T10:14:31.948Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/d4/37/1e7bacb9307a8df52234923e054b7303783e7a48a4637d44ce390b015921/pyobjc_framework_corespotlight-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:404a1e362fe19f0dff477edc1665d8ad90aada928246802da777399f7c06b22e", size = 9976, upload-time = "2025-11-14T09:46:45.221Z" },
+ { url = "https://files.pythonhosted.org/packages/f6/3b/d3031eddff8029859de6d92b1f741625b1c233748889141a6a5a89b96f0e/pyobjc_framework_corespotlight-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:bfcea64ab3250e2886d202b8731be3817b5ac0c8c9f43e77d0d5a0b6602e71a7", size = 9996, upload-time = "2025-11-14T09:46:47.157Z" },
+ { url = "https://files.pythonhosted.org/packages/7b/ed/419ae27bdd17701404301ede1969daadeef6ef6dd8b4a8110a90a1d77df1/pyobjc_framework_corespotlight-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:37003bfea415ff21859d44403c3a13ac55f90b6dca92c69b81b61d96cee0c7be", size = 10012, upload-time = "2025-11-14T09:46:48.826Z" },
+ { url = "https://files.pythonhosted.org/packages/a8/84/ebe1acb365958604465f83710772c1a08854f472896e607f7eedb5944e1b/pyobjc_framework_corespotlight-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:ede26027cfa577e6748b7dd0615e8a1bb379e48ad2324489b2c8d242cdf6fce8", size = 10152, upload-time = "2025-11-14T09:46:51.025Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-coretext"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-quartz" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/29/da/682c9c92a39f713bd3c56e7375fa8f1b10ad558ecb075258ab6f1cdd4a6d/pyobjc_framework_coretext-12.1.tar.gz", hash = "sha256:e0adb717738fae395dc645c9e8a10bb5f6a4277e73cba8fa2a57f3b518e71da5", size = 90124, upload-time = "2025-11-14T10:14:38.596Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/f0/81/7b8efc41e743adfa2d74b92dec263c91bcebfb188d2a8f5eea1886a195ff/pyobjc_framework_coretext-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:4f6742ba5b0bb7629c345e99eff928fbfd9e9d3d667421ac1a2a43bdb7ba9833", size = 29990, upload-time = "2025-11-14T09:47:01.206Z" },
+ { url = "https://files.pythonhosted.org/packages/cd/0f/ddf45bf0e3ba4fbdc7772de4728fd97ffc34a0b5a15e1ab1115b202fe4ae/pyobjc_framework_coretext-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:d246fa654bdbf43bae3969887d58f0b336c29b795ad55a54eb76397d0e62b93c", size = 30108, upload-time = "2025-11-14T09:47:04.228Z" },
+ { url = "https://files.pythonhosted.org/packages/20/a2/a3974e3e807c68e23a9d7db66fc38ac54f7ecd2b7a9237042006699a76e1/pyobjc_framework_coretext-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:7cbb2c28580e6704ce10b9a991ccd9563a22b3a75f67c36cf612544bd8b21b5f", size = 30110, upload-time = "2025-11-14T09:47:07.518Z" },
+ { url = "https://files.pythonhosted.org/packages/0f/5d/85e059349e9cfbd57269a1f11f56747b3ff5799a3bcbd95485f363c623d8/pyobjc_framework_coretext-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:14100d1e39efb30f57869671fb6fce8d668f80c82e25e7930fb364866e5c0dab", size = 30697, upload-time = "2025-11-14T09:47:10.932Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-corewlan"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/88/71/739a5d023566b506b3fd3d2412983faa95a8c16226c0dcd0f67a9294a342/pyobjc_framework_corewlan-12.1.tar.gz", hash = "sha256:a9d82ec71ef61f37e1d611caf51a4203f3dbd8caf827e98128a1afaa0fd2feb5", size = 32417, upload-time = "2025-11-14T10:14:41.921Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/f5/74/4d8a52b930a276f6f9b4f3b1e07cd518cb6d923cb512e39c935e3adb0b86/pyobjc_framework_corewlan-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:3e3f2614eb37dfd6860d6a0683877c2f3b909758ef78b68e5f6b7ea9c858cc51", size = 9931, upload-time = "2025-11-14T09:47:20.849Z" },
+ { url = "https://files.pythonhosted.org/packages/4e/31/3e9cf2c0ac3c979062958eae7a275b602515c9c76fd30680e1ee0fea82ae/pyobjc_framework_corewlan-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:5cba04c0550fc777767cd3a5471e4ed837406ab182d7d5c273bc5ce6ea237bfe", size = 9958, upload-time = "2025-11-14T09:47:22.474Z" },
+ { url = "https://files.pythonhosted.org/packages/c0/a4/b691e4d1730c16f8ea2f883712054961a3e45f40e1471c0edfc30f061c07/pyobjc_framework_corewlan-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:aac949646953effdd36d2d21bc0ab645e58bb25deafe86c6e600b3cdcfc2228b", size = 9968, upload-time = "2025-11-14T09:47:24.454Z" },
+ { url = "https://files.pythonhosted.org/packages/88/2e/dbba1674e1629839f479c9d14b90c37ed3b5f76d3b6b3ad56af48951c45b/pyobjc_framework_corewlan-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:dae63c36affcc933c9161980e4fe7333e0c59c968174a00a75cb5f6e4ede10c6", size = 10115, upload-time = "2025-11-14T09:47:26.152Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-cryptotokenkit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/6b/7c/d03ff4f74054578577296f33bc669fce16c7827eb1a553bb372b5aab30ca/pyobjc_framework_cryptotokenkit-12.1.tar.gz", hash = "sha256:c95116b4b7a41bf5b54aff823a4ef6f4d9da4d0441996d6d2c115026a42d82f5", size = 32716, upload-time = "2025-11-14T10:14:45.024Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/2c/90/1623b60d6189db08f642777374fd32287b06932c51dfeb1e9ed5bbf67f35/pyobjc_framework_cryptotokenkit-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:d84b75569054fa0886e3e341c00d7179d5fe287e6d1509630dd698ee60ec5af1", size = 12598, upload-time = "2025-11-14T09:47:33.798Z" },
+ { url = "https://files.pythonhosted.org/packages/0f/c7/aecba253cf21303b2c9f3ce03fc0e987523609d7839ea8e0a688ae816c96/pyobjc_framework_cryptotokenkit-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:ef51a86c1d0125fabdfad0b3efa51098fb03660d8dad2787d82e8b71c9f189de", size = 12633, upload-time = "2025-11-14T09:47:35.707Z" },
+ { url = "https://files.pythonhosted.org/packages/15/8d/3e24abc92a8ee8ee11386d4d9dfb2d6961d10814474053a8ebccfaff0d97/pyobjc_framework_cryptotokenkit-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:e65a8e4558e6cf1e46a9b4a52fcbf7b2ddd17958d675e9047d8a9f131d0a4d33", size = 12650, upload-time = "2025-11-14T09:47:37.633Z" },
+ { url = "https://files.pythonhosted.org/packages/e9/eb/418afc27429922e73a05bd22198c71e1f6b3badebd73cad208eb9e922f64/pyobjc_framework_cryptotokenkit-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:cc9aa75e418376e92b1540d1edfa0c8097a027a1a241717983d0223cdad8e9ca", size = 12834, upload-time = "2025-11-14T09:47:40.27Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-datadetection"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/db/97/9b03832695ec4d3008e6150ddfdc581b0fda559d9709a98b62815581259a/pyobjc_framework_datadetection-12.1.tar.gz", hash = "sha256:95539e46d3bc970ce890aa4a97515db10b2690597c5dd362996794572e5d5de0", size = 12323, upload-time = "2025-11-14T10:14:46.769Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/70/1c/5d2f941501e84da8fef8ef3fd378b5c083f063f083f97dd3e8a07f0404b3/pyobjc_framework_datadetection-12.1-py2.py3-none-any.whl", hash = "sha256:4dc8e1d386d655b44b2681a4a2341fb2fc9addbf3dda14cb1553cd22be6a5387", size = 3497, upload-time = "2025-11-14T09:47:45.826Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-devicecheck"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/cd/af/c676107c40d51f55d0a42043865d7246db821d01241b518ea1d3b3ef1394/pyobjc_framework_devicecheck-12.1.tar.gz", hash = "sha256:567e85fc1f567b3fe64ac1cdc323d989509331f64ee54fbcbde2001aec5adbdb", size = 12885, upload-time = "2025-11-14T10:14:48.804Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/c5/d8/1f1b13fa4775b6474c9ad0f4b823953eaeb6c11bd6f03fa8479429b36577/pyobjc_framework_devicecheck-12.1-py2.py3-none-any.whl", hash = "sha256:ffd58148bdef4a1ee8548b243861b7d97a686e73808ca0efac5bef3c430e4a15", size = 3684, upload-time = "2025-11-14T09:47:47.25Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-devicediscoveryextension"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/91/b0/e6e2ed6a7f4b689746818000a003ff7ab9c10945df66398ae8d323ae9579/pyobjc_framework_devicediscoveryextension-12.1.tar.gz", hash = "sha256:60e12445fad97ff1f83472255c943685a8f3a9d95b3126d887cfe769b7261044", size = 14718, upload-time = "2025-11-14T10:14:50.723Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/7e/0c/005fe8db1e19135f493a3de8c8d38031e1ad2d626de4ef89f282acf4aff7/pyobjc_framework_devicediscoveryextension-12.1-py2.py3-none-any.whl", hash = "sha256:d6d6b606d27d4d88efc0bed4727c375e749149b360290c3ad2afc52337739a1b", size = 4321, upload-time = "2025-11-14T09:47:48.78Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-dictionaryservices"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-coreservices" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/7a/c0/daf03cdaf6d4e04e0cf164db358378c07facd21e4e3f8622505d72573e2c/pyobjc_framework_dictionaryservices-12.1.tar.gz", hash = "sha256:354158f3c55d66681fa903c7b3cb05a435b717fa78d0cef44d258d61156454a7", size = 10573, upload-time = "2025-11-14T10:14:53.961Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/e7/13/ab308e934146cfd54691ddad87e572cd1edb6659d795903c4c75904e2d7d/pyobjc_framework_dictionaryservices-12.1-py2.py3-none-any.whl", hash = "sha256:578854eec17fa473ac17ab30050a7bbb2ab69f17c5c49b673695254c3e88ad4b", size = 3930, upload-time = "2025-11-14T09:47:50.782Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-discrecording"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c4/87/8bd4544793bfcdf507174abddd02b1f077b48fab0004b3db9a63142ce7e9/pyobjc_framework_discrecording-12.1.tar.gz", hash = "sha256:6defc8ea97fb33b4d43870c673710c04c3dc48be30cdf78ba28191a922094990", size = 55607, upload-time = "2025-11-14T10:14:58.276Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/0e/ce/89df4d53a0a5e3a590d6e735eca4f0ba4d1ccc0e0acfbc14164026a3c502/pyobjc_framework_discrecording-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:f7d815f28f781e20de0bf278aaa10b0de7e5ea1189aa17676c0bf5b99e9e0d52", size = 14540, upload-time = "2025-11-14T09:47:55.442Z" },
+ { url = "https://files.pythonhosted.org/packages/c8/70/14a5aa348a5eba16e8773bb56698575cf114aa55aa303037b7000fc53959/pyobjc_framework_discrecording-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:865f1551e58459da6073360afc8f2cc452472c676ba83dcaa9b0c44e7775e4b5", size = 14566, upload-time = "2025-11-14T09:47:57.503Z" },
+ { url = "https://files.pythonhosted.org/packages/aa/29/0064a48b24694597890cb065f5d33f719eed2cfff2878f43f310f27485cc/pyobjc_framework_discrecording-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:8c682c458622db9b4ea8363335ee38f5dd98db6691680041a3fda73e26714346", size = 14567, upload-time = "2025-11-14T09:47:59.78Z" },
+ { url = "https://files.pythonhosted.org/packages/de/78/b8b3f063ecda49d600548eeee0c29b47a0b7635623a68609038326bfa7e7/pyobjc_framework_discrecording-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:36e1ba4d37fe310bad2fbfeadd43c8ef001cfae9a2a0484d7318504c5dbefa3f", size = 14745, upload-time = "2025-11-14T09:48:02.271Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-discrecordingui"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-discrecording" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/30/63/8667f5bb1ecb556add04e86b278cb358dc1f2f03862705cae6f09097464c/pyobjc_framework_discrecordingui-12.1.tar.gz", hash = "sha256:6793d4a1a7f3219d063f39d87f1d4ebbbb3347e35d09194a193cfe16cba718a8", size = 16450, upload-time = "2025-11-14T10:15:00.254Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/f2/4e/76016130c27b98943c5758a05beab3ba1bc9349ee881e1dfc509ea954233/pyobjc_framework_discrecordingui-12.1-py2.py3-none-any.whl", hash = "sha256:6544ef99cad3dee95716c83cb207088768b6ecd3de178f7e1b17df5997689dfd", size = 4702, upload-time = "2025-11-14T09:48:08.01Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-diskarbitration"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/3a/42/f75fcabec1a0033e4c5235cc8225773f610321d565b63bf982c10c6bbee4/pyobjc_framework_diskarbitration-12.1.tar.gz", hash = "sha256:6703bc5a09b38a720c9ffca356b58f7e99fa76fc988c9ec4d87112344e63dfc2", size = 17121, upload-time = "2025-11-14T10:15:02.223Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/48/65/c1f54c47af17cb6b923eab85e95f22396c52f90ee8f5b387acffad9a99ea/pyobjc_framework_diskarbitration-12.1-py2.py3-none-any.whl", hash = "sha256:54caf3079fe4ae5ac14466a9b68923ee260a1a88a8290686b4a2015ba14c2db6", size = 4877, upload-time = "2025-11-14T09:48:09.945Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-dvdplayback"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/cf/dd/7859a58e8dd336c77f83feb76d502e9623c394ea09322e29a03f5bc04d32/pyobjc_framework_dvdplayback-12.1.tar.gz", hash = "sha256:279345d4b5fb2c47dd8e5c2fd289e644b6648b74f5c25079805eeb61bfc4a9cd", size = 32332, upload-time = "2025-11-14T10:15:05.257Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/29/7d/22c07c28fab1f15f0d364806e39a6ca63c737c645fe7e98e157878b5998c/pyobjc_framework_dvdplayback-12.1-py2.py3-none-any.whl", hash = "sha256:af911cc222272a55b46a1a02a46a355279aecfd8132231d8d1b279e252b8ad4c", size = 8243, upload-time = "2025-11-14T09:48:11.824Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-eventkit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b6/42/4ec97e641fdcf30896fe76476181622954cb017117b1429f634d24816711/pyobjc_framework_eventkit-12.1.tar.gz", hash = "sha256:7c1882be2f444b1d0f71e9a0cd1e9c04ad98e0261292ab741fc9de0b8bbbbae9", size = 28538, upload-time = "2025-11-14T10:15:07.878Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/f4/35/142f43227627d6324993869d354b9e57eb1e88c4e229e2271592254daf25/pyobjc_framework_eventkit-12.1-py2.py3-none-any.whl", hash = "sha256:3d2d36d5bd9e0a13887a6ac7cdd36675985ebe2a9cb3cdf8cec0725670c92c60", size = 6820, upload-time = "2025-11-14T09:48:14.035Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-exceptionhandling"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/f1/17/5c9d4164f7ccf6b9100be0ad597a7857395dd58ea492cba4f0e9c0b77049/pyobjc_framework_exceptionhandling-12.1.tar.gz", hash = "sha256:7f0719eeea6695197fce0e7042342daa462683dc466eb6a442aad897032ab00d", size = 16694, upload-time = "2025-11-14T10:15:10.173Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/0b/ad/8e05acf3635f20ea7d878be30d58a484c8b901a8552c501feb7893472f86/pyobjc_framework_exceptionhandling-12.1-py2.py3-none-any.whl", hash = "sha256:2f1eae14cf0162e53a0888d9ffe63f047501fe583a23cdc9c966e89f48cf4713", size = 7113, upload-time = "2025-11-14T09:48:15.685Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-executionpolicy"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/95/11/db765e76e7b00e1521d7bb3a61ae49b59e7573ac108da174720e5d96b61b/pyobjc_framework_executionpolicy-12.1.tar.gz", hash = "sha256:682866589365cd01d3a724d8a2781794b5cba1e152411a58825ea52d7b972941", size = 12594, upload-time = "2025-11-14T10:15:12.077Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/51/2c/f10352398f10f244401ab8f53cabd127dc3f5dbbfc8de83464661d716671/pyobjc_framework_executionpolicy-12.1-py2.py3-none-any.whl", hash = "sha256:c3a9eca3bd143cf202787dd5e3f40d954c198f18a5e0b8b3e2fcdd317bf33a52", size = 3739, upload-time = "2025-11-14T09:48:17.35Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-extensionkit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/9a/d4/e9b1f74d29ad9dea3d60468d59b80e14ed3a19f9f7a25afcbc10d29c8a1e/pyobjc_framework_extensionkit-12.1.tar.gz", hash = "sha256:773987353e8aba04223dbba3149253db944abfb090c35318b3a770195b75da6d", size = 18694, upload-time = "2025-11-14T10:15:14.104Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/4f/02/3d1df48f838dc9d64f03bedd29f0fdac6c31945251c9818c3e34083eb731/pyobjc_framework_extensionkit-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:9139c064e1c7f21455411848eb39f092af6085a26cad322aa26309260e7929d9", size = 7919, upload-time = "2025-11-14T09:48:22.14Z" },
+ { url = "https://files.pythonhosted.org/packages/9c/d9/8064dad6114a489e5439cc20d9fb0dd64cfc406d875b4a3c87015b3f6266/pyobjc_framework_extensionkit-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:7e01d705c7ac6d080ae34a81db6d9b81875eabefa63fd6eafbfa30f676dd780b", size = 7932, upload-time = "2025-11-14T09:48:23.653Z" },
+ { url = "https://files.pythonhosted.org/packages/f5/75/63c304543fc3c5c0755521ab0535e3f81f6ab8de656a02598e23f687cb6c/pyobjc_framework_extensionkit-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:8f2a87bd4fbb8d14900bbe9c979b23b7532b23685c0f5022671b26db4fa3e515", size = 7946, upload-time = "2025-11-14T09:48:25.803Z" },
+ { url = "https://files.pythonhosted.org/packages/bd/40/2dab02d8726abf586f253fbddc2d0d9b2abd5dbb4b24272eb48c886741fc/pyobjc_framework_extensionkit-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:570e8a89116380a27dd8df7ce28cd5f7296eb785aea4cb7dc6447954005360c2", size = 8086, upload-time = "2025-11-14T09:48:27.715Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-externalaccessory"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/8e/35/86c097ae2fdf912c61c1276e80f3e090a3fc898c75effdf51d86afec456b/pyobjc_framework_externalaccessory-12.1.tar.gz", hash = "sha256:079f770a115d517a6ab87db1b8a62ca6cdf6c35ae65f45eecc21b491e78776c0", size = 20958, upload-time = "2025-11-14T10:15:16.419Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/18/01/2a83b63e82ce58722277a00521c3aeec58ac5abb3086704554e47f8becf3/pyobjc_framework_externalaccessory-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:32208e05c9448c8f41b3efdd35dbea4a8b119af190f7a2db0d580be8a5cf962e", size = 8911, upload-time = "2025-11-14T09:48:35.349Z" },
+ { url = "https://files.pythonhosted.org/packages/ec/52/984034396089766b6e5ff3be0f93470e721c420fa9d1076398557532234f/pyobjc_framework_externalaccessory-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:dedbf7a09375ac19668156c1417bd7829565b164a246b714e225b9cbb6a351ad", size = 8932, upload-time = "2025-11-14T09:48:37.393Z" },
+ { url = "https://files.pythonhosted.org/packages/2d/bf/9e368e16edb94d9507c1034542379b943e0d9c3bcc0ce8062ac330216317/pyobjc_framework_externalaccessory-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:34858f06cd75fe4e358555961a6898eb8778fd2931058fd660fcd5d6cf31b162", size = 8944, upload-time = "2025-11-14T09:48:39.07Z" },
+ { url = "https://files.pythonhosted.org/packages/71/5b/643a00fe334485b4100d7a68330b6c6c349fe27434e0dc0fdf2065984555/pyobjc_framework_externalaccessory-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:5551915fa82ff1eea8e5810f74c1298e5327aefe4ac90abeb9a7abd69ff33a22", size = 9100, upload-time = "2025-11-14T09:48:41.57Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-fileprovider"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/cc/9a/724b1fae5709f8860f06a6a2a46de568f9bb8bdb2e2aae45b4e010368f51/pyobjc_framework_fileprovider-12.1.tar.gz", hash = "sha256:45034e0d00ae153c991aa01cb1fd41874650a30093e77ba73401dcce5534c8ad", size = 43071, upload-time = "2025-11-14T10:15:19.989Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/1d/37/2f56167e9f43d3b25a5ed073305ca0cfbfc66bedec7aae9e1f2c9c337265/pyobjc_framework_fileprovider-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:9d527c417f06d27c4908e51d4e6ccce0adcd80c054f19e709626e55c511dc963", size = 20970, upload-time = "2025-11-14T09:48:50.557Z" },
+ { url = "https://files.pythonhosted.org/packages/2c/f5/56f0751a2988b2caca89d6800c8f29246828d1a7498bb676ef1ab28000b7/pyobjc_framework_fileprovider-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:89b140ea8369512ddf4164b007cbe35b4d97d1dcb8affa12a7264c0ab8d56e45", size = 21003, upload-time = "2025-11-14T09:48:53.128Z" },
+ { url = "https://files.pythonhosted.org/packages/31/92/23deb9d12690a69599dd7a66f3f5a5a3c09824147d148759a33c5c2933fc/pyobjc_framework_fileprovider-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:a1a7a6ac3af1e93d23f5644b4c7140dc7edf5ff79419cc0bd25ce7001afc1cf6", size = 21018, upload-time = "2025-11-14T09:48:55.504Z" },
+ { url = "https://files.pythonhosted.org/packages/a4/99/cec0a13ca8da9283d1a1bbaeeabdff7903be5c85cfb27a2bb7cc121cb529/pyobjc_framework_fileprovider-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:6d6744c8c4f915b6193a982365d947b63286cea605f990a2aaa3bb37069471f2", size = 21300, upload-time = "2025-11-14T09:48:57.948Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-fileproviderui"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-fileprovider" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/50/00/234f9b93f75255845df81d9d5ea20cb83ecb5c0a4e59147168b622dd0b9d/pyobjc_framework_fileproviderui-12.1.tar.gz", hash = "sha256:15296429d9db0955abc3242b2920b7a810509a85118dbc185f3ac8234e5a6165", size = 12437, upload-time = "2025-11-14T10:15:22.044Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/e8/65/cc4397511bd0af91993d6302a2aed205296a9ad626146eefdfc8a9624219/pyobjc_framework_fileproviderui-12.1-py2.py3-none-any.whl", hash = "sha256:521a914055089e28631018bd78df4c4f7416e98b4150f861d4a5bc97d5b1ffe4", size = 3715, upload-time = "2025-11-14T09:49:04.213Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-findersync"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e4/63/c8da472e0910238a905bc48620e005a1b8ae7921701408ca13e5fb0bfb4b/pyobjc_framework_findersync-12.1.tar.gz", hash = "sha256:c513104cef0013c233bf8655b527df665ce6f840c8bc0b3781e996933d4dcfa6", size = 13507, upload-time = "2025-11-14T10:15:24.161Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/6a/9f/ec7f393e3e2fd11cbdf930d884a0ba81078bdb61920b3cba4f264de8b446/pyobjc_framework_findersync-12.1-py2.py3-none-any.whl", hash = "sha256:e07abeca52c486cf14927f617afc27afa7a3828b99fab3ad02355105fb29203e", size = 4889, upload-time = "2025-11-14T09:49:05.763Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-fsevents"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/43/17/21f45d2bca2efc72b975f2dfeae7a163dbeabb1236c1f188578403fd4f09/pyobjc_framework_fsevents-12.1.tar.gz", hash = "sha256:a22350e2aa789dec59b62da869c1b494a429f8c618854b1383d6473f4c065a02", size = 26487, upload-time = "2025-11-14T10:15:26.796Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/a4/3f/a7fe5656b205ee3a9fd828e342157b91e643ee3e5c0d50b12bd4c737f683/pyobjc_framework_fsevents-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:459cc0aac9850c489d238ba778379d09f073bbc3626248855e78c4bc4d97fe46", size = 13059, upload-time = "2025-11-14T09:49:09.814Z" },
+ { url = "https://files.pythonhosted.org/packages/2d/e3/2c5eeea390c0b053e2d73b223af3ec87a3e99a8106e8d3ee79942edb0822/pyobjc_framework_fsevents-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:a2949358513fd7bc622fb362b5c4af4fc24fc6307320070ca410885e5e13d975", size = 13141, upload-time = "2025-11-14T09:49:11.947Z" },
+ { url = "https://files.pythonhosted.org/packages/19/41/f06d14020eb9ec10c0e36f5e3f836f8541b989dcde9f53ea172852a7c864/pyobjc_framework_fsevents-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:2b30c72239a9ced4e4604fcf265a1efee788cb47850982dd80fcbaafa7ee64f9", size = 13143, upload-time = "2025-11-14T09:49:14.019Z" },
+ { url = "https://files.pythonhosted.org/packages/2b/3a/10c1576da38f7e39d6adb592f54fa1b058c859c7d38d03b0cdaf25e12f8d/pyobjc_framework_fsevents-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:05220368b0685783e0ae00c885e167169d47ff5cf66de7172ca8074682dfc330", size = 13511, upload-time = "2025-11-14T09:49:16.423Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-fskit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/a1/55/d00246d6e6d9756e129e1d94bc131c99eece2daa84b2696f6442b8a22177/pyobjc_framework_fskit-12.1.tar.gz", hash = "sha256:ec54e941cdb0b7d800616c06ca76a93685bd7119b8aa6eb4e7a3ee27658fc7ba", size = 42372, upload-time = "2025-11-14T10:15:30.411Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/e7/1a/5a0b6b8dc18b9dbcb7d1ef7bebdd93f12560097dafa6d7c4b3c15649afba/pyobjc_framework_fskit-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:95b9135eea81eeed319dcca32c9db04b38688301586180b86c4585fef6b0e9cd", size = 20228, upload-time = "2025-11-14T09:49:25.324Z" },
+ { url = "https://files.pythonhosted.org/packages/6d/a9/0c47469fe80fa14bc698bb0a5b772b44283cc3aca0f67e7f70ab45e09b24/pyobjc_framework_fskit-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:50972897adea86508cfee33ec4c23aa91dede97e9da1640ea2fe74702b065be1", size = 20250, upload-time = "2025-11-14T09:49:28.065Z" },
+ { url = "https://files.pythonhosted.org/packages/ce/99/eb30b8b99a4d62ff90b8aa66c6074bf6e2732705a3a8f086ba623fcc642f/pyobjc_framework_fskit-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:528b988ea6af1274c81ff698f802bb55a12e32633862919dd4b303ec3b941fae", size = 20258, upload-time = "2025-11-14T09:49:30.893Z" },
+ { url = "https://files.pythonhosted.org/packages/50/b6/0579127ff0ad03f6b8f26a7e856e5c9998c9b0efb7ac944b27e23136acf7/pyobjc_framework_fskit-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:55e3e00e51bc33d43ed57efb9ceb252abfceba0bd563dae07c7b462da7add849", size = 20491, upload-time = "2025-11-14T09:49:33.249Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-gamecenter"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/d2/f8/b5fd86f6b722d4259228922e125b50e0a6975120a1c4d957e990fb84e42c/pyobjc_framework_gamecenter-12.1.tar.gz", hash = "sha256:de4118f14c9cf93eb0316d49da410faded3609ce9cd63425e9ef878cebb7ea72", size = 31473, upload-time = "2025-11-14T10:15:33.38Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/ca/17/6491f9e96664e05ec00af7942a6c2f69217771522c9d1180524273cac7cb/pyobjc_framework_gamecenter-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:30943512f2aa8cb129f8e1abf951bf06922ca20b868e918b26c19202f4ee5cc4", size = 18824, upload-time = "2025-11-14T09:49:42.543Z" },
+ { url = "https://files.pythonhosted.org/packages/16/ee/b496cc4248c5b901e159d6d9a437da9b86a3105fc3999a66744ba2b2c884/pyobjc_framework_gamecenter-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:e8d6d10b868be7c00c2d5a0944cc79315945735dcf17eaa3fec1a7986d26be9b", size = 18868, upload-time = "2025-11-14T09:49:44.767Z" },
+ { url = "https://files.pythonhosted.org/packages/cd/b4/d89eaeae9057e5fc6264ad47247739160650dfd02b1e85a84d45036f25f9/pyobjc_framework_gamecenter-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:16c885eae6ad29abb8d3ad17a9068c920f778622bff5401df31842fdbcebdd84", size = 18873, upload-time = "2025-11-14T09:49:47.072Z" },
+ { url = "https://files.pythonhosted.org/packages/20/17/e5fe5a8f80288e61d70b6f9ccf05cffe6f1809736c11f172570af24216f6/pyobjc_framework_gamecenter-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:9112d7aa8807d4b18a3f7190f310d60380640faaf405a1d0a9fd066c6420ae5b", size = 19154, upload-time = "2025-11-14T09:49:49.26Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-gamecontroller"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/21/14/353bb1fe448cd833839fd199ab26426c0248088753e63c22fe19dc07530f/pyobjc_framework_gamecontroller-12.1.tar.gz", hash = "sha256:64ed3cc4844b67f1faeb540c7cc8d512c84f70b3a4bafdb33d4663a2b2a2b1d8", size = 54554, upload-time = "2025-11-14T10:15:37.591Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/e4/dc/1d8bd4845a46cb5a5c1f860d85394e64729b2447bbe149bb33301bc99056/pyobjc_framework_gamecontroller-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:2633c2703fb30ce068b2f5ce145edbd10fd574d2670b5cdee77a9a126f154fec", size = 20913, upload-time = "2025-11-14T09:49:58.863Z" },
+ { url = "https://files.pythonhosted.org/packages/06/28/9f03d0ef7c78340441f78b19fb2d2c952af04a240da5ed30c7cf2d0d0f4e/pyobjc_framework_gamecontroller-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:878aa6590c1510e91bfc8710d6c880e7a8f3656a7b7b6f4f3af487a6f677ccd5", size = 20949, upload-time = "2025-11-14T09:50:01.608Z" },
+ { url = "https://files.pythonhosted.org/packages/9d/7c/4553f7c37eedef4cd2e6f0d9b6c63da556ed2fbe7dd2a79735654e082932/pyobjc_framework_gamecontroller-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:2105b4309222e538b9bccf906d24f083c3cbf1cd1c18b3ae6876e842e84d2163", size = 20956, upload-time = "2025-11-14T09:50:04.123Z" },
+ { url = "https://files.pythonhosted.org/packages/ad/ed/19e27404ce87256642431a60914ef2cb0578142727981714d494970e21c3/pyobjc_framework_gamecontroller-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:a772cc9fbe09bcc601abcc36855a70cbad4640bd3349c1d611c09fcc7e45b73b", size = 21226, upload-time = "2025-11-14T09:50:06.462Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-gamekit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-quartz" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/52/7b/d625c0937557f7e2e64200fdbeb867d2f6f86b2f148b8d6bfe085e32d872/pyobjc_framework_gamekit-12.1.tar.gz", hash = "sha256:014d032c3484093f1409f8f631ba8a0fd2ff7a3ae23fd9d14235340889854c16", size = 63833, upload-time = "2025-11-14T10:15:42.842Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/06/47/d3b78cf57bc2d62dc1408aaad226b776d167832063bbaa0c7cc7a9a6fa12/pyobjc_framework_gamekit-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:eb263e90a6af3d7294bc1b1ea5907f8e33bb77d62fb806696f8df7e14806ccad", size = 22463, upload-time = "2025-11-14T09:50:16.444Z" },
+ { url = "https://files.pythonhosted.org/packages/c4/05/1c49e1030dc9f2812fa8049442158be76c32f271075f4571f94e4389ea86/pyobjc_framework_gamekit-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:2eee796d5781157f2c5684f7ef4c2a7ace9d9b408a26a9e7e92e8adf5a3f63d7", size = 22493, upload-time = "2025-11-14T09:50:19.129Z" },
+ { url = "https://files.pythonhosted.org/packages/8a/7d/65b16b18dc15283d6f56df5ebf30ae765eaf1f8e67e6eb30539581fe9749/pyobjc_framework_gamekit-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:ad14393ac496a4cb8008b6172d536f5c07fc11bb7b00fb541b044681cf9e4a34", size = 22505, upload-time = "2025-11-14T09:50:21.989Z" },
+ { url = "https://files.pythonhosted.org/packages/98/19/433595ff873684e0df73067b32aba6fc4b360d3ed552444115285a5d969a/pyobjc_framework_gamekit-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:97e41b4800be30cb3e6a88007b6f741cb18935467d1631537ac23b918659900e", size = 22798, upload-time = "2025-11-14T09:50:24.583Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-gameplaykit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-spritekit" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e2/11/c310bbc2526f95cce662cc1f1359bb11e2458eab0689737b4850d0f6acb7/pyobjc_framework_gameplaykit-12.1.tar.gz", hash = "sha256:935ebd806d802888969357946245d35a304c530c86f1ffe584e2cf21f0a608a8", size = 41511, upload-time = "2025-11-14T10:15:46.529Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/3b/84/7a4a2c358770f5ffdb6bdabb74dcefdfa248b17c250a7c0f9d16d3b8d987/pyobjc_framework_gameplaykit-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:b2fb27f9f48c3279937e938a0456a5231b5c89e53e3199b9d54009a0bbd1228a", size = 13125, upload-time = "2025-11-14T09:50:34.384Z" },
+ { url = "https://files.pythonhosted.org/packages/35/1f/e5fe404f92ec0f9c8c37b00d6cb3ba96ee396c7f91b0a41a39b64bfc2743/pyobjc_framework_gameplaykit-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:309b0d7479f702830c9be92dbe5855ac2557a9d23f05f063caf9d9fdb85ff5f0", size = 13150, upload-time = "2025-11-14T09:50:36.884Z" },
+ { url = "https://files.pythonhosted.org/packages/08/c9/d90505bed51b487d7a8eff54a51dda0d9b8e2d76740a99924b5067b58062/pyobjc_framework_gameplaykit-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:947911902e0caf1d82dedae8842025891d57e91504714a7732dc7c4f80d486a1", size = 13164, upload-time = "2025-11-14T09:50:39.251Z" },
+ { url = "https://files.pythonhosted.org/packages/ad/42/9d5ac9a4398f1d1566ce83f16f68aeaa174137de78bec4515ed927c24530/pyobjc_framework_gameplaykit-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:3218de7a56ac63a47ab7c50ce30592d626759196c937d20426a0ea74091e0614", size = 13383, upload-time = "2025-11-14T09:50:41.227Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-gamesave"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/1b/1f/8d05585c844535e75dbc242dd6bdfecfc613d074dcb700362d1c908fb403/pyobjc_framework_gamesave-12.1.tar.gz", hash = "sha256:eb731c97aa644e78a87838ed56d0e5bdbaae125bdc8854a7772394877312cc2e", size = 12654, upload-time = "2025-11-14T10:15:48.344Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/59/ec/93d48cb048a1b35cea559cc9261b07f0d410078b3af029121302faa410d0/pyobjc_framework_gamesave-12.1-py2.py3-none-any.whl", hash = "sha256:432e69f8404be9290d42c89caba241a3156ed52013947978ac54f0f032a14ffd", size = 3689, upload-time = "2025-11-14T09:50:47.263Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-healthkit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/af/67/436630d00ba1028ea33cc9df2fc28e081481433e5075600f2ea1ff00f45e/pyobjc_framework_healthkit-12.1.tar.gz", hash = "sha256:29c5e5de54b41080b7a4b0207698ac6f600dcb9149becc9c6b3a69957e200e5c", size = 91802, upload-time = "2025-11-14T10:15:54.661Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/1e/37/b23d3c04ee37cbb94ff92caedc3669cd259be0344fcf6bdf1ff75ff0a078/pyobjc_framework_healthkit-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:e67bce41f8f63c11000394c6ce1dc694655d9ff0458771340d2c782f9eafcc6e", size = 20785, upload-time = "2025-11-14T09:50:52.152Z" },
+ { url = "https://files.pythonhosted.org/packages/65/87/bb1c438de51c4fa733a99ce4d3301e585f14d7efd94031a97707c0be2b46/pyobjc_framework_healthkit-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:15b6fc958ff5de42888b18dffdec839cb36d2dd8b82076ed2f21a51db5271109", size = 20799, upload-time = "2025-11-14T09:50:54.531Z" },
+ { url = "https://files.pythonhosted.org/packages/40/f8/4bbaf71a11a99649a4aa9f4ac28d94a2bf357cd4c88fba91439000301cf0/pyobjc_framework_healthkit-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:c57ba8e3cce620665236d9f6b77482c9cfb16fe3372c8b6bbabc50222fb1b790", size = 20812, upload-time = "2025-11-14T09:50:57.238Z" },
+ { url = "https://files.pythonhosted.org/packages/e9/ef/4461f34f42e8f78b941161df7045d27e48d73d203847a21921b5a36ffe68/pyobjc_framework_healthkit-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:b2a0890d920015b40afe8ecda6c541840d20b4ae6c7f2daaa9efbaafae8cc1bc", size = 20980, upload-time = "2025-11-14T09:50:59.644Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-imagecapturecore"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/6d/a1/39347381fc7d3cd5ab942d86af347b25c73f0ddf6f5227d8b4d8f5328016/pyobjc_framework_imagecapturecore-12.1.tar.gz", hash = "sha256:c4776c59f4db57727389d17e1ffd9c567b854b8db52198b3ccc11281711074e5", size = 46397, upload-time = "2025-11-14T10:15:58.541Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/b4/6b/b34d5c9041e90b8a82d87025a1854b60a8ec2d88d9ef9e715f3a40109ed5/pyobjc_framework_imagecapturecore-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:64d1eb677fe5b658a6b6ed734b7120998ea738ca038ec18c4f9c776e90bd9402", size = 15983, upload-time = "2025-11-14T09:51:09.978Z" },
+ { url = "https://files.pythonhosted.org/packages/50/13/632957b284dec3743d73fb30dbdf03793b3cf1b4c62e61e6484d870f3879/pyobjc_framework_imagecapturecore-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:a2777e17ff71fb5a327a897e48c5c7b5a561723a80f990d26e6ed5a1b8748816", size = 16012, upload-time = "2025-11-14T09:51:12.058Z" },
+ { url = "https://files.pythonhosted.org/packages/f9/32/2d936320147f299d83c14af4eb8e28821d226f2920d2df3f7a3b3daf61dc/pyobjc_framework_imagecapturecore-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:2ae57b54e7b92e2efb40b7346e12d7767f42ed2bcf8f050cd9a88a9926a1e387", size = 16025, upload-time = "2025-11-14T09:51:14.387Z" },
+ { url = "https://files.pythonhosted.org/packages/09/5a/7bfa64b0561c7eb858dac9b2e0e3a50000e9dc50416451e8ae40b316eb8f/pyobjc_framework_imagecapturecore-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:08f8ed5434ee5cc7605e71227c284c0c3fa0a32a6d83e1862e7870543a65a630", size = 16213, upload-time = "2025-11-14T09:51:16.531Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-inputmethodkit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/5d/b8/d33dd8b7306029bbbd80525bf833fc547e6a223c494bf69a534487283a28/pyobjc_framework_inputmethodkit-12.1.tar.gz", hash = "sha256:f63b6fe2fa7f1412eae63baea1e120e7865e3b68ccfb7d8b0a4aadb309f2b278", size = 23054, upload-time = "2025-11-14T10:16:01.464Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/a7/04/1315f84dba5704a4976ea0185f877f0f33f28781473a817010cee209a8f0/pyobjc_framework_inputmethodkit-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:c4e02f49816799a31d558866492048d69e8086178770b76f4c511295610e02ab", size = 9502, upload-time = "2025-11-14T09:51:24.708Z" },
+ { url = "https://files.pythonhosted.org/packages/01/c2/59bea66405784b25f5d4e821467ba534a0b92dfc98e07257c971e2a8ed73/pyobjc_framework_inputmethodkit-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:0b7d813d46a060572fc0c14ef832e4fe538ebf64e5cab80ee955191792ce0110", size = 9506, upload-time = "2025-11-14T09:51:26.924Z" },
+ { url = "https://files.pythonhosted.org/packages/9e/ec/502019d314729e7e82a7fa187dd52b6f99a6097ac0ab6dc675ccd60b5677/pyobjc_framework_inputmethodkit-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:b5c7458082e3f7e8bb115ed10074ad862cc6566da7357540205d3cd1e24e2b9f", size = 9523, upload-time = "2025-11-14T09:51:30.751Z" },
+ { url = "https://files.pythonhosted.org/packages/47/68/76a75461de5b9c195a6b5081179578fef7136f19ffc4990f6591cabae591/pyobjc_framework_inputmethodkit-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:a4e782edd8e59b1ea81ea688d27edbf98cc5c8262e081cb772cf8c36c74733df", size = 9694, upload-time = "2025-11-14T09:51:32.616Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-installerplugins"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e7/60/ca4ab04eafa388a97a521db7d60a812e2f81a3c21c2372587872e6b074f9/pyobjc_framework_installerplugins-12.1.tar.gz", hash = "sha256:1329a193bd2e92a2320a981a9a421a9b99749bade3e5914358923e94fe995795", size = 25277, upload-time = "2025-11-14T10:16:04.379Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/99/1f/31dca45db3342882a628aa1b27707a283d4dc7ef558fddd2533175a0661a/pyobjc_framework_installerplugins-12.1-py2.py3-none-any.whl", hash = "sha256:d2201c81b05bdbe0abf0af25db58dc230802573463bea322f8b2863e37b511d5", size = 4813, upload-time = "2025-11-14T09:51:37.836Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-instantmessage"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-quartz" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/d4/67/66754e0d26320ba24a33608ca94d3f38e60ee6b2d2e094cb6269b346fdd4/pyobjc_framework_instantmessage-12.1.tar.gz", hash = "sha256:f453118d5693dc3c94554791bd2aaafe32a8b03b0e3d8ec3934b44b7fdd1f7e7", size = 31217, upload-time = "2025-11-14T10:16:07.693Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/c1/38/6ae95b5c87d887c075bd5f4f7cca3d21dafd0a77cfdde870e87ca17579eb/pyobjc_framework_instantmessage-12.1-py2.py3-none-any.whl", hash = "sha256:cd91d38e8f356afd726b6ea8c235699316ea90edfd3472965c251efbf4150bc9", size = 5436, upload-time = "2025-11-14T09:51:39.557Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-intents"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/f1/a1/3bab6139e94b97eca098e1562f5d6840e3ff10ea1f7fd704a17111a97d5b/pyobjc_framework_intents-12.1.tar.gz", hash = "sha256:bd688c3ab34a18412f56e459e9dae29e1f4152d3c2048fcacdef5fc49dfb9765", size = 132262, upload-time = "2025-11-14T10:16:16.428Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/d0/25/648db47b9c3879fa50c65ab7cc5fbe0dd400cc97141ac2658ef2e196c0b6/pyobjc_framework_intents-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:dc68dc49f1f8d9f8d2ffbc0f57ad25caac35312ddc444899707461e596024fec", size = 32134, upload-time = "2025-11-14T09:51:46.369Z" },
+ { url = "https://files.pythonhosted.org/packages/7a/90/e9489492ae90b4c1ffd02c1221c0432b8768d475787e7887f79032c2487a/pyobjc_framework_intents-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:0ea9f3e79bf4baf6c7b0fd2d2797184ed51a372bf7f32974b4424f9bd067ef50", size = 32156, upload-time = "2025-11-14T09:51:49.438Z" },
+ { url = "https://files.pythonhosted.org/packages/74/83/6b03ac6d5663be41d76ab69412a21f94eff69c67ffa13516a91e4b946890/pyobjc_framework_intents-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:1da8d1501c8c85198dfbc4623ea18db96077f9947f6e1fe5ffa2ed06935e8a3b", size = 32168, upload-time = "2025-11-14T09:51:52.888Z" },
+ { url = "https://files.pythonhosted.org/packages/d9/f8/1fd0a75de415d335a1aa43e9c86e468960b3a4d969a87aa4a70084452277/pyobjc_framework_intents-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:50ab244f2a9ad4c94bbc1dd81421f8553f59121d4e0ad0c894a927a878319843", size = 32413, upload-time = "2025-11-14T09:51:56.057Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-intentsui"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-intents" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/19/cf/f0e385b9cfbf153d68efe8d19e5ae672b59acbbfc1f9b58faaefc5ec8c9e/pyobjc_framework_intentsui-12.1.tar.gz", hash = "sha256:16bdf4b7b91c0d1ec9d5513a1182861f1b5b7af95d4f4218ff7cf03032d57f99", size = 19784, upload-time = "2025-11-14T10:16:18.716Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/84/cc/7678f901cbf5bca8ccace568ae85ee7baddcd93d78754ac43a3bb5e5a7ac/pyobjc_framework_intentsui-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:a877555e313d74ac3b10f7b4e738647eea9f744c00a227d1238935ac3f9d7968", size = 8961, upload-time = "2025-11-14T09:52:05.595Z" },
+ { url = "https://files.pythonhosted.org/packages/f1/17/06812542a9028f5b2dcce56f52f25633c08b638faacd43bad862aad1b41d/pyobjc_framework_intentsui-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:cb894fcc4c9ea613a424dcf6fb48142d51174559b82cfdafac8cb47555c842cf", size = 8983, upload-time = "2025-11-14T09:52:07.667Z" },
+ { url = "https://files.pythonhosted.org/packages/57/af/4dc8b6f714ba1bd9cf0218da98c49ece5dcee4e0593b59196ec5aa85e07c/pyobjc_framework_intentsui-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:369a88db1ff3647e4d8cf38d315f1e9b381fc7732d765b08994036f9d330f57d", size = 9004, upload-time = "2025-11-14T09:52:09.625Z" },
+ { url = "https://files.pythonhosted.org/packages/18/ab/794ed92dcf955dc2d0a0dcfbc384e087864f2dacd330d59d1185f8403353/pyobjc_framework_intentsui-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:8742e9237ef2df8dbb1566cdc77e4d747b2693202f438d49435e0c3c91eaa709", size = 9177, upload-time = "2025-11-14T09:52:11.26Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-iobluetooth"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e4/aa/ca3944bbdfead4201b4ae6b51510942c5a7d8e5e2dc3139a071c74061fdf/pyobjc_framework_iobluetooth-12.1.tar.gz", hash = "sha256:8a434118812f4c01dfc64339d41fe8229516864a59d2803e9094ee4cbe2b7edd", size = 155241, upload-time = "2025-11-14T10:16:28.896Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/f6/ab/ad6b36f574c3d52b5e935b1d57ab0f14f4e4cd328cc922d2b6ba6428c12d/pyobjc_framework_iobluetooth-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:77959f2ecf379aa41eb0848fdb25da7c322f9f4a82429965c87c4bc147137953", size = 40415, upload-time = "2025-11-14T09:52:22.069Z" },
+ { url = "https://files.pythonhosted.org/packages/0b/b6/933b56afb5e84c3c35c074c9e30d7b701c6038989d4867867bdaa7ab618b/pyobjc_framework_iobluetooth-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:111a6e54be9e9dcf77fa2bf84fdac09fae339aa33087d8647ea7ffbd34765d4c", size = 40439, upload-time = "2025-11-14T09:52:26.071Z" },
+ { url = "https://files.pythonhosted.org/packages/15/6f/5e165daaf3b637d37fee50f42beda62ab3d5e6e99b1d84c4af4700d39d01/pyobjc_framework_iobluetooth-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:2ee0d4fdddf871fb89c49033495ae49973cc8b0e8de50c2e60c92355ce3bea86", size = 40452, upload-time = "2025-11-14T09:52:29.68Z" },
+ { url = "https://files.pythonhosted.org/packages/37/bd/7cc5f01fbf573112059766c94535ae3f9c044d6e0cf49c599e490224db58/pyobjc_framework_iobluetooth-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:0cd2ea9384e93913703bf40641196a930af83c2f6f62f59f8606b7162fe1caa3", size = 40659, upload-time = "2025-11-14T09:52:33.299Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-iobluetoothui"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-iobluetooth" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/8f/39/31d9a4e8565a4b1ec0a9ad81480dc0879f3df28799eae3bc22d1dd53705d/pyobjc_framework_iobluetoothui-12.1.tar.gz", hash = "sha256:81f8158bdfb2966a574b6988eb346114d6a4c277300c8c0a978c272018184e6f", size = 16495, upload-time = "2025-11-14T10:16:31.212Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/e3/c9/69aeda0cdb5d25d30dc4596a1c5b464fc81b5c0c4e28efc54b7e11bde51c/pyobjc_framework_iobluetoothui-12.1-py2.py3-none-any.whl", hash = "sha256:a6d8ab98efa3029130577a57ee96b183c35c39b0f1c53a7534f8838260fab993", size = 4045, upload-time = "2025-11-14T09:52:42.201Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-iosurface"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/07/61/0f12ad67a72d434e1c84b229ec760b5be71f53671ee9018593961c8bfeb7/pyobjc_framework_iosurface-12.1.tar.gz", hash = "sha256:4b9d0c66431aa296f3ca7c4f84c00dc5fc961194830ad7682fdbbc358fa0db55", size = 17690, upload-time = "2025-11-14T10:16:33.282Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/88/ad/793d98a7ed9b775dc8cce54144cdab0df1808a1960ee017e46189291a8f3/pyobjc_framework_iosurface-12.1-py2.py3-none-any.whl", hash = "sha256:e784e248397cfebef4655d2c0025766d3eaa4a70474e363d084fc5ce2a4f2a3f", size = 4902, upload-time = "2025-11-14T09:52:43.899Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-ituneslibrary"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/f5/46/d9bcec88675bf4ee887b9707bd245e2a793e7cb916cf310f286741d54b1f/pyobjc_framework_ituneslibrary-12.1.tar.gz", hash = "sha256:7f3aa76c4d05f6fa6015056b88986cacbda107c3f29520dd35ef0936c7367a6e", size = 23730, upload-time = "2025-11-14T10:16:36.127Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/de/92/b598694a1713ee46f45c4bfb1a0425082253cbd2b1caf9f8fd50f292b017/pyobjc_framework_ituneslibrary-12.1-py2.py3-none-any.whl", hash = "sha256:fb678d7c3ff14c81672e09c015e25880dac278aa819971f4d5f75d46465932ef", size = 5205, upload-time = "2025-11-14T09:52:45.733Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-kernelmanagement"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/0a/7e/ecbac119866e8ac2cce700d7a48a4297946412ac7cbc243a7084a6582fb1/pyobjc_framework_kernelmanagement-12.1.tar.gz", hash = "sha256:488062893ac2074e0c8178667bf864a21f7909c11111de2f6a10d9bc579df59d", size = 11773, upload-time = "2025-11-14T10:16:38.216Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/94/32/04325a20f39d88d6d712437e536961a9e6a4ec19f204f241de6ed54d1d84/pyobjc_framework_kernelmanagement-12.1-py2.py3-none-any.whl", hash = "sha256:926381bfbfbc985c3e6dfcb7004af21bb16ff66ecbc08912b925989a705944ff", size = 3704, upload-time = "2025-11-14T09:52:47.268Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-latentsemanticmapping"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/88/3c/b621dac54ae8e77ac25ee75dd93e310e2d6e0faaf15b8da13513258d6657/pyobjc_framework_latentsemanticmapping-12.1.tar.gz", hash = "sha256:f0b1fa823313eefecbf1539b4ed4b32461534b7a35826c2cd9f6024411dc9284", size = 15526, upload-time = "2025-11-14T10:16:40.149Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/29/8e/74a7eb29b545f294485cd3cf70557b4a35616555fe63021edbb3e0ea4c20/pyobjc_framework_latentsemanticmapping-12.1-py2.py3-none-any.whl", hash = "sha256:7d760213b42bc8b1bc1472e1873c0f78ee80f987225978837b1fecdceddbdbf4", size = 5471, upload-time = "2025-11-14T09:52:48.939Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-launchservices"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-coreservices" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/37/d0/24673625922b0ad21546be5cf49e5ec1afaa4553ae92f222adacdc915907/pyobjc_framework_launchservices-12.1.tar.gz", hash = "sha256:4d2d34c9bd6fb7f77566155b539a2c70283d1f0326e1695da234a93ef48352dc", size = 20470, upload-time = "2025-11-14T10:16:42.499Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/08/af/9a0aebaab4c15632dc8fcb3669c68fa541a3278d99541d9c5f966fbc0909/pyobjc_framework_launchservices-12.1-py2.py3-none-any.whl", hash = "sha256:e63e78fceeed4d4dc807f9dabd5cf90407e4f552fab6a0d75a8d0af63094ad3c", size = 3905, upload-time = "2025-11-14T09:52:50.71Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-libdispatch"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/26/e8/75b6b9b3c88b37723c237e5a7600384ea2d84874548671139db02e76652b/pyobjc_framework_libdispatch-12.1.tar.gz", hash = "sha256:4035535b4fae1b5e976f3e0e38b6e3442ffea1b8aa178d0ca89faa9b8ecdea41", size = 38277, upload-time = "2025-11-14T10:16:46.235Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/1f/75/c4aeab6ce7268373d4ceabbc5c406c4bbf557038649784384910932985f8/pyobjc_framework_libdispatch-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:954cc2d817b71383bd267cc5cd27d83536c5f879539122353ca59f1c945ac706", size = 20463, upload-time = "2025-11-14T09:52:55.703Z" },
+ { url = "https://files.pythonhosted.org/packages/83/6f/96e15c7b2f7b51fc53252216cd0bed0c3541bc0f0aeb32756fefd31bed7d/pyobjc_framework_libdispatch-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:0e9570d7a9a3136f54b0b834683bf3f206acd5df0e421c30f8fd4f8b9b556789", size = 15650, upload-time = "2025-11-14T09:52:59.284Z" },
+ { url = "https://files.pythonhosted.org/packages/38/3a/d85a74606c89b6b293782adfb18711026ff79159db20fc543740f2ac0bc7/pyobjc_framework_libdispatch-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:58ffce5e6bcd7456b4311009480b195b9f22107b7682fb0835d4908af5a68ad0", size = 15668, upload-time = "2025-11-14T09:53:01.354Z" },
+ { url = "https://files.pythonhosted.org/packages/cc/40/49b1c1702114ee972678597393320d7b33f477e9d24f2a62f93d77f23dfb/pyobjc_framework_libdispatch-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:e9f49517e253716e40a0009412151f527005eec0b9a2311ac63ecac1bdf02332", size = 15938, upload-time = "2025-11-14T09:53:03.461Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-libxpc"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/16/e4/364db7dc26f235e3d7eaab2f92057f460b39800bffdec3128f113388ac9f/pyobjc_framework_libxpc-12.1.tar.gz", hash = "sha256:e46363a735f3ecc9a2f91637750623f90ee74f9938a4e7c833e01233174af44d", size = 35186, upload-time = "2025-11-14T10:16:49.503Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/7c/c9/701630d025407497b7af50a795ddb6202c184da7f12b46aa683dae3d3552/pyobjc_framework_libxpc-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:8d7201db995e5dcd38775fd103641d8fb69b8577d8e6a405c5562e6c0bb72fd1", size = 19620, upload-time = "2025-11-14T09:53:12.529Z" },
+ { url = "https://files.pythonhosted.org/packages/82/7f/fdec72430f90921b154517a6f9bbeefa7bacfb16b91320742eb16a5955c5/pyobjc_framework_libxpc-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:ba93e91e9ca79603dd265382e9f80e9bd32309cd09c8ac3e6489fc5b233676c8", size = 19730, upload-time = "2025-11-14T09:53:17.113Z" },
+ { url = "https://files.pythonhosted.org/packages/0a/64/c4e2f9a4f92f4d2b84c0e213b4a9410968b5f181f15a764eeb43f92c4eb2/pyobjc_framework_libxpc-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:635520187a6456ad259e40dd04829caeef08561d0a1a0cfd09787ebd281d47b3", size = 19729, upload-time = "2025-11-14T09:53:19.038Z" },
+ { url = "https://files.pythonhosted.org/packages/51/c2/654dd2a22b6f505ff706a66117c522029df9449a9a19ca4827af0d16b5b3/pyobjc_framework_libxpc-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:1c36e3e109a95275f90b319161265a7f6a5e0e674938ce49babdf3a64d9fc892", size = 20309, upload-time = "2025-11-14T09:53:22.657Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-linkpresentation"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-quartz" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e3/58/c0c5919d883485ccdb6dccd8ecfe50271d2f6e6ab7c9b624789235ccec5a/pyobjc_framework_linkpresentation-12.1.tar.gz", hash = "sha256:84df6779591bb93217aa8bd82c10e16643441678547d2d73ba895475a02ade94", size = 13330, upload-time = "2025-11-14T10:16:52.169Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/ad/51/226eb45f196f3bf93374713571aae6c8a4760389e1d9435c4a4cc3f38ea4/pyobjc_framework_linkpresentation-12.1-py2.py3-none-any.whl", hash = "sha256:853a84c7b525b77b114a7a8d798aef83f528ed3a6803bda12184fe5af4e79a47", size = 3865, upload-time = "2025-11-14T09:53:28.386Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-localauthentication"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-security" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/8d/0e/7e5d9a58bb3d5b79a75d925557ef68084171526191b1c0929a887a553d4f/pyobjc_framework_localauthentication-12.1.tar.gz", hash = "sha256:2284f587d8e1206166e4495b33f420c1de486c36c28c4921d09eec858a699d05", size = 29947, upload-time = "2025-11-14T10:16:54.923Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/6e/cb/cf9d13943e13dc868a68844448a7714c16f4ee6ecac384d21aaa5ac43796/pyobjc_framework_localauthentication-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:2d7e1b3f987dc387361517525c2c38550dc44dfb3ba42dec3a9fbf35015831a6", size = 10762, upload-time = "2025-11-14T09:53:32.035Z" },
+ { url = "https://files.pythonhosted.org/packages/05/93/91761ad4e5fa1c3ec25819865d1ccfbee033987147087bff4fcce67a4dc4/pyobjc_framework_localauthentication-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:3af1acd287d830cc7f912f46cde0dab054952bde0adaf66c8e8524311a68d279", size = 10773, upload-time = "2025-11-14T09:53:34.074Z" },
+ { url = "https://files.pythonhosted.org/packages/e4/f5/a12c76525e4839c7fc902c6b0f0c441414a4dd9bc9a2d89ae697f6cd8850/pyobjc_framework_localauthentication-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:e26e746717f4774cce0568debec711f1d8effc430559ad634ff6b06fefd0a0bf", size = 10792, upload-time = "2025-11-14T09:53:35.876Z" },
+ { url = "https://files.pythonhosted.org/packages/5c/ed/2714934b027afc6a99d0d817e42bf482d08c711422795fe777e3cd9ad8be/pyobjc_framework_localauthentication-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:02357cddc979aa169782bf09f380aab1c3af475c9eb6ffb07c77084ed10f6a6a", size = 10931, upload-time = "2025-11-14T09:53:37.672Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-localauthenticationembeddedui"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-localauthentication" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/31/20/83ab4180e29b9a4a44d735c7f88909296c6adbe6250e8e00a156aff753e1/pyobjc_framework_localauthenticationembeddedui-12.1.tar.gz", hash = "sha256:a15ec44bf2769c872e86c6b550b6dd4f58d4eda40ad9ff00272a67d279d1d4e9", size = 13611, upload-time = "2025-11-14T10:16:57.145Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/30/7d/0d46639c7a26b6af928ab4c822cd28b733791e02ac28cc84c3014bcf7dc7/pyobjc_framework_localauthenticationembeddedui-12.1-py2.py3-none-any.whl", hash = "sha256:a7ce7b56346597b9f4768be61938cbc8fc5b1292137225b6c7f631b9cde97cd7", size = 3991, upload-time = "2025-11-14T09:53:42.958Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-mailkit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/2a/98/3d9028620c1cd32ff4fb031155aba3b5511e980cdd114dd51383be9cb51b/pyobjc_framework_mailkit-12.1.tar.gz", hash = "sha256:d5574b7259baec17096410efcaacf5d45c7bb5f893d4c25cbb7072369799b652", size = 20996, upload-time = "2025-11-14T10:16:59.449Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/70/8d/3c968b736a3a8bd9d8e870b39b1c772a013eea1b81b89fc4efad9021a6cb/pyobjc_framework_mailkit-12.1-py2.py3-none-any.whl", hash = "sha256:536ac0c4ea3560364cd159a6512c3c18a744a12e4e0883c07df0f8a2ff21e3fe", size = 4871, upload-time = "2025-11-14T09:53:44.697Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-mapkit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-corelocation" },
+ { name = "pyobjc-framework-quartz" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/36/bb/2a668203c20e509a648c35e803d79d0c7f7816dacba74eb5ad8acb186790/pyobjc_framework_mapkit-12.1.tar.gz", hash = "sha256:dbc32dc48e821aaa9b4294402c240adbc1c6834e658a07677b7c19b7990533c5", size = 63520, upload-time = "2025-11-14T10:17:04.221Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/d0/8f/411067e5c5cd23b9fe4c5edfb02ed94417b94eefe56562d36e244edc70ff/pyobjc_framework_mapkit-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:e8aa82d4aae81765c05dcd53fd362af615aa04159fc7a1df1d0eac9c252cb7d5", size = 22493, upload-time = "2025-11-14T09:53:50.112Z" },
+ { url = "https://files.pythonhosted.org/packages/11/00/a3de41cdf3e6cd7a144e38999fe1ea9777ad19e19d863f2da862e7affe7b/pyobjc_framework_mapkit-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:84ad7766271c114bdc423e4e2ff5433e5fc6771a3338b5f8e4b54d0340775800", size = 22518, upload-time = "2025-11-14T09:53:52.727Z" },
+ { url = "https://files.pythonhosted.org/packages/5e/f1/db2aa9fa44669b9c060a3ae02d5661052a05868ccba1674543565818fdaf/pyobjc_framework_mapkit-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:ea210ba88bef2468adb5c8303071d86118d630bf37a29d28cf236c13c3bb85ad", size = 22539, upload-time = "2025-11-14T09:53:55.543Z" },
+ { url = "https://files.pythonhosted.org/packages/c1/e4/7dd9f7333eea7f4666274f568cac03e4687b442c9b20622f244497700177/pyobjc_framework_mapkit-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:dfee615b73bb687101f08e7fd839eea2aa8b241563ad4cabbcb075d12f598266", size = 22712, upload-time = "2025-11-14T09:53:58.159Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-mediaaccessibility"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e0/10/dc1007e56944ed2e981e69e7b2fed2b2202c79b0d5b742b29b1081d1cbdd/pyobjc_framework_mediaaccessibility-12.1.tar.gz", hash = "sha256:cc4e3b1d45e84133d240318d53424eff55968f5c6873c2c53267598853445a3f", size = 16325, upload-time = "2025-11-14T10:17:07.454Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/a2/0c/7fb5462561f59d739192c6d02ba0fd36ad7841efac5a8398a85a030ef7fc/pyobjc_framework_mediaaccessibility-12.1-py2.py3-none-any.whl", hash = "sha256:2ff8845c97dd52b0e5cf53990291e6d77c8a73a7aac0e9235d62d9a4256916d1", size = 4800, upload-time = "2025-11-14T09:54:05.04Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-mediaextension"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-avfoundation" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-coremedia" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/d6/aa/1e8015711df1cdb5e4a0aa0ed4721409d39971ae6e1e71915e3ab72423a3/pyobjc_framework_mediaextension-12.1.tar.gz", hash = "sha256:44409d63cc7d74e5724a68e3f9252cb62fd0fd3ccf0ca94c6a33e5c990149953", size = 39425, upload-time = "2025-11-14T10:17:11.486Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/8e/6f/60b63edf5d27acf450e4937b7193c1a2bd6195fee18e15df6a5734dedb71/pyobjc_framework_mediaextension-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:9555f937f2508bd2b6264cba088e2c2e516b2f94a6c804aee40e33fd89c2fb78", size = 38957, upload-time = "2025-11-14T09:54:13.22Z" },
+ { url = "https://files.pythonhosted.org/packages/2b/ed/99038bcf72ec68e452709af10a087c1377c2d595ba4e66d7a2b0775145d2/pyobjc_framework_mediaextension-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:442bc3a759efb5c154cb75d643a5e182297093533fcdd1c24be6f64f68b93371", size = 38973, upload-time = "2025-11-14T09:54:16.701Z" },
+ { url = "https://files.pythonhosted.org/packages/01/df/7ecdbac430d2d2844fb2145e26f3e87a8a7692fa669d0629d90f32575991/pyobjc_framework_mediaextension-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:0f3bdca0eb11923efc1e3b95beb1e6e01c675fd7809ed7ef0b475334e3562931", size = 38991, upload-time = "2025-11-14T09:54:20.316Z" },
+ { url = "https://files.pythonhosted.org/packages/fc/98/88ac2edeb69bde3708ef3f7b6434f810ba89321d8375914ad642c9a575b0/pyobjc_framework_mediaextension-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:0101b8495051bac9791a0488530386eefe9c722477a5239c5bd208967d0eaa67", size = 39198, upload-time = "2025-11-14T09:54:23.806Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-medialibrary"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-quartz" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/34/e9/848ebd02456f8fdb41b42298ec585bfed5899dbd30306ea5b0a7e4c4b341/pyobjc_framework_medialibrary-12.1.tar.gz", hash = "sha256:690dcca09b62511df18f58e8566cb33d9652aae09fe63a83f594bd018b5edfcd", size = 15995, upload-time = "2025-11-14T10:17:15.45Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/c2/cd/eeaf8585a343fda5b8cf3b8f144c872d1057c845202098b9441a39b76cb0/pyobjc_framework_medialibrary-12.1-py2.py3-none-any.whl", hash = "sha256:1f03ad6802a5c6e19ee3208b065689d3ec79defe1052cb80e00f54e1eff5f2a0", size = 4361, upload-time = "2025-11-14T09:54:32.259Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-mediaplayer"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-avfoundation" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e9/f0/851f6f47e11acbd62d5f5dcb8274afc969135e30018591f75bf3cbf6417f/pyobjc_framework_mediaplayer-12.1.tar.gz", hash = "sha256:5ef3f669bdf837d87cdb5a486ec34831542360d14bcba099c7c2e0383380794c", size = 35402, upload-time = "2025-11-14T10:17:18.97Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/58/c0/038ee3efd286c0fbc89c1e0cb688f4670ed0e5803aa36e739e79ffc91331/pyobjc_framework_mediaplayer-12.1-py2.py3-none-any.whl", hash = "sha256:85d9baec131807bfdf0f4c24d4b943e83cce806ab31c95c7e19c78e3fb7eefc8", size = 7120, upload-time = "2025-11-14T09:54:33.901Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-mediatoolbox"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/a3/71/be5879380a161f98212a336b432256f307d1dcbaaaeb8ec988aea2ada2cd/pyobjc_framework_mediatoolbox-12.1.tar.gz", hash = "sha256:385b48746a5f08756ee87afc14037e552954c427ed5745d7ece31a21a7bad5ab", size = 22305, upload-time = "2025-11-14T10:17:22.501Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/8f/7a/f20ebd3c590b2cc85cde3e608e49309bfccf9312e4aca7b7ea60908d36d7/pyobjc_framework_mediatoolbox-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:74de0cb2d5aaa77e81f8b97eab0f39cd2fab5bf6fa7c6fb5546740cbfb1f8c1f", size = 12656, upload-time = "2025-11-14T09:54:39.215Z" },
+ { url = "https://files.pythonhosted.org/packages/9c/94/d5ee221f2afbc64b2a7074efe25387cd8700e8116518904b28091ea6ad74/pyobjc_framework_mediatoolbox-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:d7bcfeeff3fbf7e9e556ecafd8eaed2411df15c52baf134efa7480494e6faf6d", size = 12818, upload-time = "2025-11-14T09:54:41.251Z" },
+ { url = "https://files.pythonhosted.org/packages/ca/30/79aa0010b30f3c54c68673d00f06f45ef28f5093ff1e927d68b5376ea097/pyobjc_framework_mediatoolbox-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:1529a754cdb5b32797d297c0bf6279c7c14a3f7088f2dfbded09edcbfda19838", size = 12830, upload-time = "2025-11-14T09:54:43.191Z" },
+ { url = "https://files.pythonhosted.org/packages/da/26/ae890f8ecce3fdda3e3a518426665467d36945c7c2729da1b073b1c44ff6/pyobjc_framework_mediatoolbox-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:13afec7d9f094ca5642e32b98680d1ee59aaa11a3d694cb1a6e454f72003f51c", size = 13420, upload-time = "2025-11-14T09:54:45.133Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-metal"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e7/06/a84f7eb8561d5631954b9458cfca04b690b80b5b85ce70642bc89335f52a/pyobjc_framework_metal-12.1.tar.gz", hash = "sha256:bb554877d5ee2bf3f340ad88e8fe1b85baab7b5ec4bd6ae0f4f7604147e3eae7", size = 181847, upload-time = "2025-11-14T10:17:34.157Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/1d/cf/edbb8b6dd084df3d235b74dbeb1fc5daf4d063ee79d13fa3bc1cb1779177/pyobjc_framework_metal-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:59e10f9b36d2e409f80f42b6175457a07b18a21ca57ff268f4bc519cd30db202", size = 75920, upload-time = "2025-11-14T09:55:01.048Z" },
+ { url = "https://files.pythonhosted.org/packages/d0/48/9286d06e1b14c11b65d3fea1555edc0061d9ebe11898dff8a14089e3a4c9/pyobjc_framework_metal-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:38ab566b5a2979a43e13593d3eb12000a45e574576fe76996a5e1eb75ad7ac78", size = 75841, upload-time = "2025-11-14T09:55:06.801Z" },
+ { url = "https://files.pythonhosted.org/packages/1c/aa/caa900c1fdb9a3b7e48946c5206171a7adcf3b5189bcdb535cf899220909/pyobjc_framework_metal-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:2f04a1a687cc346d23f3baf1ec56e3f42206709b590058d9778b52d45ca1c8ab", size = 75871, upload-time = "2025-11-14T09:55:13.008Z" },
+ { url = "https://files.pythonhosted.org/packages/9c/a9/a42a173ea2d94071bc0f3112006a5d6ba7eaf0df9c48424f99b3e867e02d/pyobjc_framework_metal-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:3f3aa0848f4da46773952408b4814a440b210dc3f67f5ec5cfc0156ca2c8c0b6", size = 76420, upload-time = "2025-11-14T09:55:18.985Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-metalfx"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-metal" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/f1/09/ce5c74565677fde66de3b9d35389066b19e5d1bfef9d9a4ad80f0c858c0c/pyobjc_framework_metalfx-12.1.tar.gz", hash = "sha256:1551b686fb80083a97879ce0331bdb1d4c9b94557570b7ecc35ebf40ff65c90b", size = 29470, upload-time = "2025-11-14T10:17:37.16Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/8b/e5/5494639c927085bbba1a310e73662e0bda44b90cdff67fa03a4e1c24d4c4/pyobjc_framework_metalfx-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:1ec3f7ab036eae45e067fbf209676f98075892aa307d73bb9394304960746cd2", size = 15026, upload-time = "2025-11-14T09:55:35.239Z" },
+ { url = "https://files.pythonhosted.org/packages/2a/0b/508e3af499694f4eec74cc3ab0530e38db76e43a27db9ecb98c50c68f5f9/pyobjc_framework_metalfx-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:a4418ae5c2eb77ec00695fa720a547638dc252dfd77ecb6feb88f713f5a948fd", size = 15062, upload-time = "2025-11-14T09:55:37.352Z" },
+ { url = "https://files.pythonhosted.org/packages/02/b6/baa6071a36962e11c8834d8d13833509ce7ecb63e5c79fe2718d153a8312/pyobjc_framework_metalfx-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:d443b0ee06de1b21a3ec5adab315840e71d52a74f8585090200228ab2fa1e59d", size = 15073, upload-time = "2025-11-14T09:55:39.436Z" },
+ { url = "https://files.pythonhosted.org/packages/42/d1/b4ea7e6c0c66710db81f315c48dca0252ed81bbde4a41de21b8d54ff2241/pyobjc_framework_metalfx-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:dcd334b42c5c50ec88e049f1b0bf43544b52e3ac09fd57b712fec8f63507190e", size = 15286, upload-time = "2025-11-14T09:55:41.642Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-metalkit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-metal" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/14/15/5091147aae12d4011a788b93971c3376aaaf9bf32aa935a2c9a06a71e18b/pyobjc_framework_metalkit-12.1.tar.gz", hash = "sha256:14cc5c256f0e3471b412a5b3582cb2a0d36d3d57401a8aa09e433252d1c34824", size = 25473, upload-time = "2025-11-14T10:17:39.721Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/10/c5/f72cbc3a5e83211cbfa33b60611abcebbe893854d0f2b28ff6f444f97549/pyobjc_framework_metalkit-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:28636454f222d9b20cb61f6e8dc1ebd48237903feb4d0dbdf9d7904c542475e5", size = 8735, upload-time = "2025-11-14T09:55:50.053Z" },
+ { url = "https://files.pythonhosted.org/packages/bf/c0/c8b5b060895cd51493afe3f09909b7e34893b1161cf4d93bc8e3cd306129/pyobjc_framework_metalkit-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:1c4869076571d94788fe539fabfdd568a5c8e340936c7726d2551196640bd152", size = 8755, upload-time = "2025-11-14T09:55:51.683Z" },
+ { url = "https://files.pythonhosted.org/packages/2b/cd/f04e991f4db4512e64ea7611796141c316506e733d75c468512df0e8fda4/pyobjc_framework_metalkit-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:4dec94431ee888682115fe88ae72fca8bffc5df0957e3c006777c1d8267f65c3", size = 8769, upload-time = "2025-11-14T09:55:53.318Z" },
+ { url = "https://files.pythonhosted.org/packages/b7/b8/6f2fc56b6f8aee222d584edbdef4cf300e90782813e315418eba6d395533/pyobjc_framework_metalkit-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:d16958c0d4e2a75e1ea973de8951c775da1e39e378a7a7762fbce1837bf3179c", size = 8922, upload-time = "2025-11-14T09:55:55.016Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-metalperformanceshaders"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-metal" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c5/68/58da38e54aa0d8c19f0d3084d8c84e92d54cc8c9254041f07119d86aa073/pyobjc_framework_metalperformanceshaders-12.1.tar.gz", hash = "sha256:b198e755b95a1de1525e63c3b14327ae93ef1d88359e6be1ce554a3493755b50", size = 137301, upload-time = "2025-11-14T10:17:49.554Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/00/0f/6dc06a08599a3bc211852a5e6dcb4ed65dfbf1066958feb367ba7702798a/pyobjc_framework_metalperformanceshaders-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:e0159a6f731dc0fd126481a26490683586864e9d47c678900049a8ffe0135f56", size = 32988, upload-time = "2025-11-14T09:56:05.323Z" },
+ { url = "https://files.pythonhosted.org/packages/62/84/d505496fca9341e0cb11258ace7640cd986fe3e831f8b4749035e9f82109/pyobjc_framework_metalperformanceshaders-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:c00e786c352b3ff5d86cf0cf3a830dc9f6fc32a03ae1a7539d20d11324adb2e8", size = 33242, upload-time = "2025-11-14T09:56:09.354Z" },
+ { url = "https://files.pythonhosted.org/packages/e9/6c/8f3d81905ce6b0613fe364a6dd77bf4ed85a6350f867b40a5e99b69e8d07/pyobjc_framework_metalperformanceshaders-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:240321f2fad1555b5ede3aed938c9f37da40a57fc3e7e9c96a45658dc12c3771", size = 33269, upload-time = "2025-11-14T09:56:12.527Z" },
+ { url = "https://files.pythonhosted.org/packages/58/44/4813f8606a91a88f67a0b0c02ed9e2449cbfd5b701f7ca61cf9ce3fe0769/pyobjc_framework_metalperformanceshaders-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:0aa287ee357fe5bd5660b3d0688f947a768cda8565dbbca3b876307b9876639e", size = 33457, upload-time = "2025-11-14T09:56:15.72Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-metalperformanceshadersgraph"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-metalperformanceshaders" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/a7/56/7ad0cd085532f7bdea9a8d4e9a2dfde376d26dd21e5eabdf1a366040eff8/pyobjc_framework_metalperformanceshadersgraph-12.1.tar.gz", hash = "sha256:b8fd017b47698037d7b172d41bed7a4835f4c4f2a288235819d200005f89ee35", size = 42992, upload-time = "2025-11-14T10:17:53.502Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/e2/c9/5e7fd0d4bc9bdf7b442f36e020677c721ba9b4c1dc1fa3180085f22a4ef9/pyobjc_framework_metalperformanceshadersgraph-12.1-py2.py3-none-any.whl", hash = "sha256:85a1c7a6114ada05c7924b3235a1a98c45359410d148097488f15aee5ebb6ab9", size = 6481, upload-time = "2025-11-14T09:56:23.66Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-metrickit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/ba/13/5576ddfbc0b174810a49171e2dbe610bdafd3b701011c6ecd9b3a461de8a/pyobjc_framework_metrickit-12.1.tar.gz", hash = "sha256:77841daf6b36ba0c19df88545fd910c0516acf279e6b7b4fa0a712a046eaa9f1", size = 27627, upload-time = "2025-11-14T10:17:56.353Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/5e/b0/e57c60af3e9214e05309dca201abb82e10e8cf91952d90d572b641d62027/pyobjc_framework_metrickit-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:da6650afd9523cf7a9cae177f4bbd1ad45cc122d97784785fa1482847485142c", size = 8102, upload-time = "2025-11-14T09:56:27.194Z" },
+ { url = "https://files.pythonhosted.org/packages/b7/04/8da5126e47306438c99750f1dfed430d7cc388f6b7f420ae748f3060ab96/pyobjc_framework_metrickit-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:3ec96e9ec7dc37fbce57dae277f0d89c66ffe1c3fa2feaca1b7125f8b2b29d87", size = 8120, upload-time = "2025-11-14T09:56:28.73Z" },
+ { url = "https://files.pythonhosted.org/packages/f1/e0/8b379325acb39e0966f818106b3c3c8e3966bf87a7ab5c2d0e89753b0d1f/pyobjc_framework_metrickit-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:884afb6ec863883318975fda38db9d741b8da5f64a2b8c34bf8edc5ff56019d4", size = 8131, upload-time = "2025-11-14T09:56:30.524Z" },
+ { url = "https://files.pythonhosted.org/packages/86/67/dcd2b18a787d3fec89e372aadb83c01879dda24fe1ed2a333a5e1d388591/pyobjc_framework_metrickit-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:37674b0e049035d8b32d0221d0afbfedd3f643e4a2ee74b9a0e4e6d1b94fcd69", size = 8273, upload-time = "2025-11-14T09:56:32.128Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-mlcompute"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/00/69/15f8ce96c14383aa783c8e4bc1e6d936a489343bb197b8e71abb3ddc1cb8/pyobjc_framework_mlcompute-12.1.tar.gz", hash = "sha256:3281db120273dcc56e97becffd5cedf9c62042788289f7be6ea067a863164f1e", size = 40698, upload-time = "2025-11-14T10:17:59.792Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/ac/f7/4614b9ccd0151795e328b9ed881fbcbb13e577a8ec4ae3507edb1a462731/pyobjc_framework_mlcompute-12.1-py2.py3-none-any.whl", hash = "sha256:4f0fc19551d710a03dfc4c7129299897544ff8ea76db6c7539ecc2f9b2571bde", size = 6744, upload-time = "2025-11-14T09:56:36.973Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-modelio"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-quartz" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b4/11/32c358111b623b4a0af9e90470b198fffc068b45acac74e1ba711aee7199/pyobjc_framework_modelio-12.1.tar.gz", hash = "sha256:d041d7bca7c2a4526344d3e593347225b7a2e51a499b3aa548895ba516d1bdbb", size = 66482, upload-time = "2025-11-14T10:18:04.92Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/35/c0/c67b806f3f2bb6264a4f7778a2aa82c7b0f50dfac40f6a60366ffc5afaf5/pyobjc_framework_modelio-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:1c2c99d47a7e4956a75ce19bddbe2d8ada7d7ce9e2f56ff53fc2898367187749", size = 20180, upload-time = "2025-11-14T09:56:41.924Z" },
+ { url = "https://files.pythonhosted.org/packages/f6/0e/b8331100f0d658ecb3e87e75c108e2ae8ac7c78b521fd5ad0205b60a2584/pyobjc_framework_modelio-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:68d971917c289fdddf69094c74915d2ccb746b42b150e0bdc16d8161e6164022", size = 20193, upload-time = "2025-11-14T09:56:44.296Z" },
+ { url = "https://files.pythonhosted.org/packages/db/fa/f111717fd64015fc3906b7c36dcfca4dda1d31916251c9640a8c70ff611a/pyobjc_framework_modelio-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:dad6e914b6efe8ea3d2cd10029c4eb838f1ad6a12344787e8db70c4149df8cfc", size = 20208, upload-time = "2025-11-14T09:56:46.627Z" },
+ { url = "https://files.pythonhosted.org/packages/58/d3/6f3131a16694684f3dfa6b2845054941dfb69a63f18980eea02a25c06f6d/pyobjc_framework_modelio-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:f00b739f9333d611e7124acf95491bdf025dd32ba7c48b7521f6845b92e2dcce", size = 20448, upload-time = "2025-11-14T09:56:49.184Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-multipeerconnectivity"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/87/35/0d0bb6881004cb238cfd7bf74f4b2e42601a1accdf27b2189ec61cf3a2dc/pyobjc_framework_multipeerconnectivity-12.1.tar.gz", hash = "sha256:7123f734b7174cacbe92a51a62b4645cc9033f6b462ff945b504b62e1b9e6c1c", size = 22816, upload-time = "2025-11-14T10:18:07.363Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/12/eb/e3e4ba158167696498f6491f91a8ac7e24f1ebbab5042cd34318e5d2035c/pyobjc_framework_multipeerconnectivity-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:7372e505ed050286aeb83d7e158fda65ad379eae12e1526f32da0a260a8b7d06", size = 11981, upload-time = "2025-11-14T09:56:58.858Z" },
+ { url = "https://files.pythonhosted.org/packages/33/8d/0646ff7db36942829f0e84be18ba44bc5cd96d6a81651f8e7dc0974821c1/pyobjc_framework_multipeerconnectivity-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:1c3bd254a16debed321debf4858f9c9b7d41572ddf1058a4bacf6a5bcfedeeff", size = 12001, upload-time = "2025-11-14T09:57:01.027Z" },
+ { url = "https://files.pythonhosted.org/packages/93/65/589cf3abaec888878d9b86162e5e622d4d467fd88a5f55320f555484dd54/pyobjc_framework_multipeerconnectivity-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:25169a2fded90d13431db03787ac238b4ed551c44f7656996f8dfb6b6986b997", size = 12019, upload-time = "2025-11-14T09:57:02.86Z" },
+ { url = "https://files.pythonhosted.org/packages/0e/77/c184a36ba61d803d482029021410568b0a2155b5bf0dd2def4256ab58a1e/pyobjc_framework_multipeerconnectivity-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:3a6c2d233ecda3127bd6b6ded289ef0d1fa6ddc3acbab7f8af996c96090f7bfc", size = 12194, upload-time = "2025-11-14T09:57:04.63Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-naturallanguage"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/8a/d1/c81c0cdbb198d498edc9bc5fbb17e79b796450c17bb7541adbf502f9ad65/pyobjc_framework_naturallanguage-12.1.tar.gz", hash = "sha256:cb27a1e1e5b2913d308c49fcd2fd04ab5ea87cb60cac4a576a91ebf6a50e52f6", size = 23524, upload-time = "2025-11-14T10:18:09.883Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/ec/d8/715a11111f76c80769cb267a19ecf2a4ac76152a6410debb5a4790422256/pyobjc_framework_naturallanguage-12.1-py2.py3-none-any.whl", hash = "sha256:a02ef383ec88948ca28f03ab8995523726b3bc75c49f593b5c89c218bcbce7ce", size = 5320, upload-time = "2025-11-14T09:57:10.294Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-netfs"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/46/68/4bf0e5b8cc0780cf7acf0aec54def58c8bcf8d733db0bd38f5a264d1af06/pyobjc_framework_netfs-12.1.tar.gz", hash = "sha256:e8d0c25f41d7d9ced1aa2483238d0a80536df21f4b588640a72e1bdb87e75c1e", size = 14799, upload-time = "2025-11-14T10:18:11.85Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/7e/6b/8c2f223879edd3e3f030d0a9c9ba812775519c6d0c257e3e7255785ca6e7/pyobjc_framework_netfs-12.1-py2.py3-none-any.whl", hash = "sha256:0021f8b141e693d3821524c170e9c645090eb320e80c2935ddb978a6e8b8da81", size = 4163, upload-time = "2025-11-14T09:57:11.845Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-network"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/38/13/a71270a1b0a9ec979e68b8ec84b0f960e908b17b51cb3cac246a74d52b6b/pyobjc_framework_network-12.1.tar.gz", hash = "sha256:dbf736ff84d1caa41224e86ff84d34b4e9eb6918ae4e373a44d3cb597648a16a", size = 56990, upload-time = "2025-11-14T10:18:16.714Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/e3/7c/4f9fc6b94be3e949b7579128cbb9171943e27d1d7841db12d66b76aeadc3/pyobjc_framework_network-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:d1ad948b9b977f432bf05363381d7d85a7021246ebf9d50771b35bf8d4548d2b", size = 19593, upload-time = "2025-11-14T09:57:17.027Z" },
+ { url = "https://files.pythonhosted.org/packages/9d/ef/a53f04f43e93932817f2ea71689dcc8afe3b908d631c21d11ec30c7b2e87/pyobjc_framework_network-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:5e53aad64eae2933fe12d49185d66aca62fb817abf8a46f86b01e436ce1b79e4", size = 19613, upload-time = "2025-11-14T09:57:19.571Z" },
+ { url = "https://files.pythonhosted.org/packages/d1/f5/612539c2c0c7ce1160bd348325747f3a94ea367901965b217af877a556a1/pyobjc_framework_network-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:e341beb32c7f95ed3e38f00cfed0a9fe7f89b8d80679bf2bd97c1a8d2280180a", size = 19632, upload-time = "2025-11-14T09:57:21.762Z" },
+ { url = "https://files.pythonhosted.org/packages/c6/ff/6a1909206f6d840ebcf40c9ea5de9a9ee07e7bb1ffa4fe573da7f90fac12/pyobjc_framework_network-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:8344e3b57afccc762983e4629ec5eff72a3d7292afa8169a3e2aada3348848a8", size = 19696, upload-time = "2025-11-14T09:57:23.948Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-networkextension"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/bf/3e/ac51dbb2efa16903e6af01f3c1f5a854c558661a7a5375c3e8767ac668e8/pyobjc_framework_networkextension-12.1.tar.gz", hash = "sha256:36abc339a7f214ab6a05cb2384a9df912f247163710741e118662bd049acfa2e", size = 62796, upload-time = "2025-11-14T10:18:21.769Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/6e/4e/aa34fc983f001cdb1afbbb4d08b42fd019fc9816caca0bf0b166db1688c1/pyobjc_framework_networkextension-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:c3082c29f94ca3a05cd1f3219999ca3af9b6dece1302ccf789f347e612bb9303", size = 14368, upload-time = "2025-11-14T09:57:33.748Z" },
+ { url = "https://files.pythonhosted.org/packages/f6/14/4934b10ade5ad0518001bfc25260d926816b9c7d08d85ef45e8a61fdef1b/pyobjc_framework_networkextension-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:adc9baacfc532944d67018e381c7645f66a9fa0064939a5a841476d81422cdcc", size = 14376, upload-time = "2025-11-14T09:57:36.132Z" },
+ { url = "https://files.pythonhosted.org/packages/cb/a8/5d847dd3ffea913597342982614eb17bad4c29c07fac3447b56c9c5136ab/pyobjc_framework_networkextension-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:63453b38e5a795f9ff950397e5a564071c2b4fd3360d79169ab017755bbb932a", size = 14399, upload-time = "2025-11-14T09:57:38.178Z" },
+ { url = "https://files.pythonhosted.org/packages/b4/a8/8d56c6ca7826633f856924256761338094eeab1ae40783c29c14b9746bc9/pyobjc_framework_networkextension-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:e21d8ec762ded95afaff41b68425219df55ca8c3f777b810238441a4f7c221e3", size = 14539, upload-time = "2025-11-14T09:57:40.222Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-notificationcenter"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c6/12/ae0fe82fb1e02365c9fe9531c9de46322f7af09e3659882212c6bf24d75e/pyobjc_framework_notificationcenter-12.1.tar.gz", hash = "sha256:2d09f5ab9dc39770bae4fa0c7cfe961e6c440c8fc465191d403633dccc941094", size = 21282, upload-time = "2025-11-14T10:18:24.51Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/47/aa/03526fc0cc285c0f8cf31c74ce3a7a464011cc8fa82a35a1637d9878c788/pyobjc_framework_notificationcenter-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:84e254f2a56ff5372793dea938a2b2683dd0bc40c5107fede76f9c2c1f6641a2", size = 9871, upload-time = "2025-11-14T09:57:49.208Z" },
+ { url = "https://files.pythonhosted.org/packages/d8/05/3168637dd425257df5693c2ceafecf92d2e6833c0aaa6594d894a528d797/pyobjc_framework_notificationcenter-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:82a735bd63f315f0a56abd206373917b7d09a0ae35fd99f1639a0fac4c525c0a", size = 9895, upload-time = "2025-11-14T09:57:51.151Z" },
+ { url = "https://files.pythonhosted.org/packages/44/9a/f2b627dd4631a0756ee3e99b57de1e78447081d11f10313ed198e7521a31/pyobjc_framework_notificationcenter-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:06470683f568803f55f1646accfbf5eaa3fda56d15f27fca31bdbff4eaa8796c", size = 9917, upload-time = "2025-11-14T09:57:53.001Z" },
+ { url = "https://files.pythonhosted.org/packages/f4/f5/5fff664571dc48eea9246d31530fc564c654af827bfca1ddab47b72dc344/pyobjc_framework_notificationcenter-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:bdf87e5f027bec727b24bb1764a9933af9728862f6a0e9a7f4a1835061f283dd", size = 10110, upload-time = "2025-11-14T09:57:55.015Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-opendirectory"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/5b/11/bc2f71d3077b3bd078dccad5c0c5c57ec807fefe3d90c97b97dd0ed3d04b/pyobjc_framework_opendirectory-12.1.tar.gz", hash = "sha256:2c63ce5dd179828ef2d8f9e3961da3bfa971a57db07a6c34eedc296548a928bb", size = 61049, upload-time = "2025-11-14T10:18:29.336Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/d6/e7/3c2dece9c5b28af28a44d72a27b35ea5ffac31fed7cbd8d696ea75dc4a81/pyobjc_framework_opendirectory-12.1-py2.py3-none-any.whl", hash = "sha256:b5b5a5cf3cc2fb25147b16b79f046b90e3982bf3ded1b210a993d8cfdba737c4", size = 11845, upload-time = "2025-11-14T09:58:00.175Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-osakit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/cb/b9/bf52c555c75a83aa45782122432fa06066bb76469047f13d06fb31e585c4/pyobjc_framework_osakit-12.1.tar.gz", hash = "sha256:36ea6acf03483dc1e4344a0cce7250a9656f44277d12bc265fa86d4cbde01f23", size = 17102, upload-time = "2025-11-14T10:18:31.354Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/99/10/30a15d7b23e6fcfa63d41ca4c7356c39ff81300249de89c3ff28216a9790/pyobjc_framework_osakit-12.1-py2.py3-none-any.whl", hash = "sha256:c49165336856fd75113d2e264a98c6deb235f1bd033eae48f661d4d832d85e6b", size = 4162, upload-time = "2025-11-14T09:58:01.953Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-oslog"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-coremedia" },
+ { name = "pyobjc-framework-quartz" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/12/42/805c9b4ac6ad25deb4215989d8fc41533d01e07ffd23f31b65620bade546/pyobjc_framework_oslog-12.1.tar.gz", hash = "sha256:d0ec6f4e3d1689d5e4341bc1130c6f24cb4ad619939f6c14d11a7e80c0ac4553", size = 21193, upload-time = "2025-11-14T10:18:33.645Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/d9/d5/8d37c2e733bd8a9a16546ceca07809d14401a059f8433cdc13579cd6a41a/pyobjc_framework_oslog-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:8dd03386331fbb6b39df8941d99071da0bfeda7d10f6434d1daa1c69f0e7bb14", size = 7802, upload-time = "2025-11-14T09:58:05.619Z" },
+ { url = "https://files.pythonhosted.org/packages/ee/60/0b742347d484068e9d6867cd95dedd1810c790b6aca45f6ef1d0f089f1f5/pyobjc_framework_oslog-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:072a41d36fcf780a070f13ac2569f8bafbb5ae4792fab4136b1a4d602dd9f5b4", size = 7813, upload-time = "2025-11-14T09:58:07.768Z" },
+ { url = "https://files.pythonhosted.org/packages/89/ad/719d65e7202623da7a3f22225e7f2b736f38cd6d3e0d87253b7f74f5b9c0/pyobjc_framework_oslog-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:d26ce39be2394695cf4c4c699e47f9b85479cf1ccb0472614bb88027803a8986", size = 7834, upload-time = "2025-11-14T09:58:09.586Z" },
+ { url = "https://files.pythonhosted.org/packages/86/f0/a042b06f47d11bdad58d5c0cec9fe3dc4dc12ed9e476031cd4c0f08c6f18/pyobjc_framework_oslog-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:a6925e6764c6f293b69fbd4f5fd32a9810fca07d63e782c41cb4ebf05dc42977", size = 8016, upload-time = "2025-11-14T09:58:11.431Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-passkit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/6c/d4/2afb59fb0f99eb2f03888850887e536f1ef64b303fd756283679471a5189/pyobjc_framework_passkit-12.1.tar.gz", hash = "sha256:d8c27c352e86a3549bf696504e6b25af5f2134b173d9dd60d66c6d3da53bb078", size = 53835, upload-time = "2025-11-14T10:18:37.906Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/25/e6/dabd6b99bdadc50aa0306495d8d0afe4b9b3475c2bafdad182721401a724/pyobjc_framework_passkit-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:cb5c8f0fdc46db6b91c51ee1f41a2b81e9a482c96a0c91c096dcb78a012b740a", size = 14087, upload-time = "2025-11-14T09:58:18.991Z" },
+ { url = "https://files.pythonhosted.org/packages/d8/dc/9cb27e8b7b00649af5e802815ffa8928bd8a619f2984a1bea7dabd28f741/pyobjc_framework_passkit-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:7e95a484ec529dbf1d44f5f7f1406502a77bda733511e117856e3dca9fa29c5c", size = 14102, upload-time = "2025-11-14T09:58:20.903Z" },
+ { url = "https://files.pythonhosted.org/packages/7c/e2/6135402be2151042b234ea241e89f4b8984f6494fd11d9f56b4a56a9d7d4/pyobjc_framework_passkit-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:64287e6dc54ab4c0aa8ba80a7a51762e36591602c77c6a803aee690e7464b6b2", size = 14110, upload-time = "2025-11-14T09:58:23.107Z" },
+ { url = "https://files.pythonhosted.org/packages/23/f3/ff6f81206eca1e1fb49c5a516d5eb15f143b38c5adee5b0c24076be02be9/pyobjc_framework_passkit-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:4a360e98b29eee8642f3e7d973c636284c24fb2ec2c3ee56022eeae6270943be", size = 14277, upload-time = "2025-11-14T09:58:25.338Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-pencilkit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/7e/43/859068016bcbe7d80597d5c579de0b84b0da62c5c55cdf9cc940e9f9c0f8/pyobjc_framework_pencilkit-12.1.tar.gz", hash = "sha256:d404982d1f7a474369f3e7fea3fbd6290326143fa4138d64b6753005a6263dc4", size = 17664, upload-time = "2025-11-14T10:18:40.045Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/e8/26/daf47dcfced8f7326218dced5c68ed2f3b522ec113329218ce1305809535/pyobjc_framework_pencilkit-12.1-py2.py3-none-any.whl", hash = "sha256:33b88e5ed15724a12fd8bf27a68614b654ff739d227e81161298bc0d03acca4f", size = 4206, upload-time = "2025-11-14T09:58:30.814Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-phase"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-avfoundation" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/96/51/3b25eaf7ca85f38ceef892fdf066b7faa0fec716f35ea928c6ffec6ae311/pyobjc_framework_phase-12.1.tar.gz", hash = "sha256:3a69005c572f6fd777276a835115eb8359a33673d4a87e754209f99583534475", size = 32730, upload-time = "2025-11-14T10:18:43.102Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/ae/9f/1ae45db731e8d6dd3e0b408c3accd0cf3236849e671f95c7c8cf95687240/pyobjc_framework_phase-12.1-py2.py3-none-any.whl", hash = "sha256:99a1c1efc6644f5312cce3693117d4e4482538f65ad08fe59e41e2579b67ab17", size = 6902, upload-time = "2025-11-14T09:58:32.436Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-photos"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b8/53/f8a3dc7f711034d2283e289cd966fb7486028ea132a24260290ff32d3525/pyobjc_framework_photos-12.1.tar.gz", hash = "sha256:adb68aaa29e186832d3c36a0b60b0592a834e24c5263e9d78c956b2b77dce563", size = 47034, upload-time = "2025-11-14T10:18:47.27Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/e4/e0/8824f7cb167934a8aa1c088b7e6f1b5a9342b14694e76eda95fc736282b2/pyobjc_framework_photos-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:f28db92602daac9d760067449fc9bf940594536e65ad542aec47d52b56f51959", size = 12319, upload-time = "2025-11-14T09:58:36.324Z" },
+ { url = "https://files.pythonhosted.org/packages/13/38/e6f25aec46a1a9d0a310795606cc43f9823d41c3e152114b814b597835a8/pyobjc_framework_photos-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:eda8a584a851506a1ebbb2ee8de2cb1ed9e3431e6a642ef6a9543e32117d17b9", size = 12358, upload-time = "2025-11-14T09:58:38.131Z" },
+ { url = "https://files.pythonhosted.org/packages/71/5a/3c4e2af8d17e62ecf26e066fbb9209aacccfaf691f5faa42e3fd64b2b9f2/pyobjc_framework_photos-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:bd7906d8662af29f91c71892ae0b0cab4682a3a7ef5be1a2277d881d7b8d37d3", size = 12367, upload-time = "2025-11-14T09:58:42.328Z" },
+ { url = "https://files.pythonhosted.org/packages/fb/24/566de3200d4aa05ca75b0150e5d031d2384a388f9126a4fef62a8f53818f/pyobjc_framework_photos-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:c822d81c778dd2a789f15d0f329cee633391c5ad766482ffbaf40d3dc57584a3", size = 12552, upload-time = "2025-11-14T09:58:44.134Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-photosui"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/40/a5/14c538828ed1a420e047388aedc4a2d7d9292030d81bf6b1ced2ec27b6e9/pyobjc_framework_photosui-12.1.tar.gz", hash = "sha256:9141234bb9d17687f1e8b66303158eccdd45132341fbe5e892174910035f029a", size = 29886, upload-time = "2025-11-14T10:18:50.238Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/64/6c/d678767bbeafa932b91c88bc8bb3a586a1b404b5564b0dc791702eb376c3/pyobjc_framework_photosui-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:02ca941187b2a2dcbbd4964d7b2a05de869653ed8484dc059a51cc70f520cd07", size = 11688, upload-time = "2025-11-14T09:58:51.84Z" },
+ { url = "https://files.pythonhosted.org/packages/16/a2/b5afca8039b1a659a2a979bb1bdbdddfdf9b1d2724a2cc4633dca2573d5f/pyobjc_framework_photosui-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:713e3bb25feb5ea891e67260c2c0769cab44a7f11b252023bfcf9f8c29dd1206", size = 11714, upload-time = "2025-11-14T09:58:53.674Z" },
+ { url = "https://files.pythonhosted.org/packages/d6/cd/204298e136ff22d3502f0b66cda1d36df89346fa2b20f4a3a681c2c96fee/pyobjc_framework_photosui-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:5fa3ca2bc4c8609dee46e3c8fb5f3fbfb615f39fa3d710a213febec38e227758", size = 11725, upload-time = "2025-11-14T09:58:56.694Z" },
+ { url = "https://files.pythonhosted.org/packages/f6/5e/492007c629844666e8334e535471c5492e93715965fdffe4f75227f47fac/pyobjc_framework_photosui-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:713ec72b13d8399229d285ccd1e94e5ea2627cf88858977a2a91cc94d1affcd6", size = 11921, upload-time = "2025-11-14T09:58:58.477Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-preferencepanes"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/90/bc/e87df041d4f7f6b7721bf7996fa02aa0255939fb0fac0ecb294229765f92/pyobjc_framework_preferencepanes-12.1.tar.gz", hash = "sha256:b2a02f9049f136bdeca7642b3307637b190850e5853b74b5c372bc7d88ef9744", size = 24543, upload-time = "2025-11-14T10:18:53.259Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/36/7b/8ceec1ab0446224d685e243e2770c5a5c92285bcab0b9324dbe7a893ae5a/pyobjc_framework_preferencepanes-12.1-py2.py3-none-any.whl", hash = "sha256:1b3af9db9e0cfed8db28c260b2cf9a22c15fda5f0ff4c26157b17f99a0e29bbf", size = 4797, upload-time = "2025-11-14T09:59:03.998Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-pushkit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/a9/45/de756b62709add6d0615f86e48291ee2bee40223e7dde7bbe68a952593f0/pyobjc_framework_pushkit-12.1.tar.gz", hash = "sha256:829a2fc8f4780e75fc2a41217290ee0ff92d4ade43c42def4d7e5af436d8ae82", size = 19465, upload-time = "2025-11-14T10:18:57.727Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/a1/b2/d92045e0d4399feda83ee56a9fd685b5c5c175f7ac8423e2cd9b3d52a9da/pyobjc_framework_pushkit-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:03f41be8b27d06302ea487a6b250aaf811917a0e7d648cd4043fac759d027210", size = 8158, upload-time = "2025-11-14T09:59:09.593Z" },
+ { url = "https://files.pythonhosted.org/packages/b9/01/74cf1dd0764c590de05dc1e87d168031e424f834721940b7bb02c67fe821/pyobjc_framework_pushkit-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:7bdf472a55ac65154e03f54ae0bcad64c4cf45e9b1acba62f15107f2bc994d69", size = 8177, upload-time = "2025-11-14T09:59:11.155Z" },
+ { url = "https://files.pythonhosted.org/packages/1b/79/00368a140fe4a14e92393da25ef5a3037a09bb0024d984d7813e7e3fa11c/pyobjc_framework_pushkit-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:f3751276cb595a9f886ed6094e06004fd11932443e345760eade09119f8e0181", size = 8193, upload-time = "2025-11-14T09:59:13.23Z" },
+ { url = "https://files.pythonhosted.org/packages/57/29/dccede214ef1835662066c74138978629d92b6a9f723e28670cfb04f3ce7/pyobjc_framework_pushkit-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:64955af6441635449c2af6c6f468c9ba5e413e1494b87617bc1e9fbd8be7e5bf", size = 8339, upload-time = "2025-11-14T09:59:14.754Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-quartz"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/94/18/cc59f3d4355c9456fc945eae7fe8797003c4da99212dd531ad1b0de8a0c6/pyobjc_framework_quartz-12.1.tar.gz", hash = "sha256:27f782f3513ac88ec9b6c82d9767eef95a5cf4175ce88a1e5a65875fee799608", size = 3159099, upload-time = "2025-11-14T10:21:24.31Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/b7/ef/dcd22b743e38b3c430fce4788176c2c5afa8bfb01085b8143b02d1e75201/pyobjc_framework_quartz-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:19f99ac49a0b15dd892e155644fe80242d741411a9ed9c119b18b7466048625a", size = 217795, upload-time = "2025-11-14T09:59:46.922Z" },
+ { url = "https://files.pythonhosted.org/packages/e9/9b/780f057e5962f690f23fdff1083a4cfda5a96d5b4d3bb49505cac4f624f2/pyobjc_framework_quartz-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:7730cdce46c7e985535b5a42c31381af4aa6556e5642dc55b5e6597595e57a16", size = 218798, upload-time = "2025-11-14T10:00:01.236Z" },
+ { url = "https://files.pythonhosted.org/packages/ba/2d/e8f495328101898c16c32ac10e7b14b08ff2c443a756a76fd1271915f097/pyobjc_framework_quartz-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:629b7971b1b43a11617f1460cd218bd308dfea247cd4ee3842eb40ca6f588860", size = 219206, upload-time = "2025-11-14T10:00:15.623Z" },
+ { url = "https://files.pythonhosted.org/packages/67/43/b1f0ad3b842ab150a7e6b7d97f6257eab6af241b4c7d14cb8e7fde9214b8/pyobjc_framework_quartz-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:53b84e880c358ba1ddcd7e8d5ea0407d760eca58b96f0d344829162cda5f37b3", size = 224317, upload-time = "2025-11-14T10:00:30.703Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-quicklookthumbnailing"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-quartz" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/97/1a/b90539500e9a27c2049c388d85a824fc0704009b11e33b05009f52a6dc67/pyobjc_framework_quicklookthumbnailing-12.1.tar.gz", hash = "sha256:4f7e09e873e9bda236dce6e2f238cab571baeb75eca2e0bc0961d5fcd85f3c8f", size = 14790, upload-time = "2025-11-14T10:21:26.442Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/1e/22/7bd07b5b44bf8540514a9f24bc46da68812c1fd6c63bb2d3496e5ea44bf0/pyobjc_framework_quicklookthumbnailing-12.1-py2.py3-none-any.whl", hash = "sha256:5efe50b0318188b3a4147681788b47fce64709f6fe0e1b5d020e408ef40ab08e", size = 4234, upload-time = "2025-11-14T10:01:02.209Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-replaykit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/35/f8/b92af879734d91c1726227e7a03b9e68ab8d9d2bb1716d1a5c29254087f2/pyobjc_framework_replaykit-12.1.tar.gz", hash = "sha256:95801fd35c329d7302b2541f2754e6574bf36547ab869fbbf41e408dfa07268a", size = 23312, upload-time = "2025-11-14T10:21:29.18Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/10/b1/fab264c6a82a78cd050a773c61dec397c5df7e7969eba3c57e17c8964ea3/pyobjc_framework_replaykit-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:3a2f9da6939d7695fa40de9c560c20948d31b0cc2f892fdd611fc566a6b83606", size = 10090, upload-time = "2025-11-14T10:01:06.321Z" },
+ { url = "https://files.pythonhosted.org/packages/6b/fc/c68d2111b2655148d88574959d3d8b21d3a003573013301d4d2a7254c1af/pyobjc_framework_replaykit-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:b0528c2a6188440fdc2017f0924c0a0f15d0a2f6aa295f1d1c2d6b3894c22f1d", size = 10120, upload-time = "2025-11-14T10:01:08.397Z" },
+ { url = "https://files.pythonhosted.org/packages/22/f1/95d3cf08a5b747e15dfb45f4ad23aeae566e75e6c54f3c58caf59b99f4d9/pyobjc_framework_replaykit-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:18af5ab59574102978790ce9ccc89fe24be9fa57579f24ed8cfc2b44ea28d839", size = 10141, upload-time = "2025-11-14T10:01:10.366Z" },
+ { url = "https://files.pythonhosted.org/packages/4e/78/fac397700f62fdb73161e04affd608678883e9476553fd99e9d65db51f79/pyobjc_framework_replaykit-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:31c826a71b76cd7d12c3f30956c202116b0c985a19eb420e91fc1f51bedd2f72", size = 10319, upload-time = "2025-11-14T10:01:12.058Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-safariservices"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/3e/4b/8f896bafbdbfa180a5ba1e21a6f5dc63150c09cba69d85f68708e02866ae/pyobjc_framework_safariservices-12.1.tar.gz", hash = "sha256:6a56f71c1e692bca1f48fe7c40e4c5a41e148b4e3c6cfb185fd80a4d4a951897", size = 25165, upload-time = "2025-11-14T10:21:32.041Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/f1/bb/da1059bfad021c417e090058c0a155419b735b4891a7eedc03177b376012/pyobjc_framework_safariservices-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:ae709cf7a72ac7b95d2f131349f852d5d7a1729a8d760ea3308883f8269a4c37", size = 7281, upload-time = "2025-11-14T10:01:19.294Z" },
+ { url = "https://files.pythonhosted.org/packages/67/3a/8c525562fd782c88bc44e8c07fc2c073919f98dead08fffd50f280ef1afa/pyobjc_framework_safariservices-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:b475abc82504fc1c0801096a639562d6a6d37370193e8e4a406de9199a7cea13", size = 7281, upload-time = "2025-11-14T10:01:21.238Z" },
+ { url = "https://files.pythonhosted.org/packages/b6/e7/fc984cf2471597e71378b4f82be4a1923855a4c4a56486cc8d97fdaf1694/pyobjc_framework_safariservices-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:592cf5080a9e7f104d6a8d338ebf2523a961f38068f238f11783e86dc105f9c7", size = 7304, upload-time = "2025-11-14T10:01:22.786Z" },
+ { url = "https://files.pythonhosted.org/packages/6e/99/3d3062808a64422f39586519d38a52e73304ed60f45500b2c75b97fdd667/pyobjc_framework_safariservices-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:097a2166f79c60633e963913722a087a13b1c5849f3173655b24a8be47039ac4", size = 7308, upload-time = "2025-11-14T10:01:24.299Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-safetykit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-quartz" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/f4/bf/ad6bf60ceb61614c9c9f5758190971e9b90c45b1c7a244e45db64138b6c2/pyobjc_framework_safetykit-12.1.tar.gz", hash = "sha256:0cd4850659fb9b5632fd8ad21f2de6863e8303ff0d51c5cc9c0034aac5db08d8", size = 20086, upload-time = "2025-11-14T10:21:34.212Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/94/68/77f17fba082de7c65176e0d74aacbce5c9c9066d6d6edcde5a537c8c140a/pyobjc_framework_safetykit-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:6c63bcd5d571bba149e28c49c8db06073e54e073b08589e94b850b39a43e52b0", size = 8539, upload-time = "2025-11-14T10:01:31.201Z" },
+ { url = "https://files.pythonhosted.org/packages/b7/0c/08a20fb7516405186c0fe7299530edd4aa22c24f73290198312447f26c8c/pyobjc_framework_safetykit-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:e4977f7069a23252053d1a42b1a053aefc19b85c960a5214b05daf3c037a6f16", size = 8550, upload-time = "2025-11-14T10:01:32.885Z" },
+ { url = "https://files.pythonhosted.org/packages/02/c5/0e8961e48a2e5942f3f4fad46be5a7b47e17792d89f4c2405b065c1241b5/pyobjc_framework_safetykit-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:20170b4869c4ee5485f750ad02bbfcb25c53bbfe86892e5328096dc3c6478b83", size = 8564, upload-time = "2025-11-14T10:01:34.934Z" },
+ { url = "https://files.pythonhosted.org/packages/48/3f/fdadc2b992cb3e08269fc75dec3128f8153dd833715b9fbfb975c193c4d2/pyobjc_framework_safetykit-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:4a935c55ae8e731a44c3cb74324da7517634bfc0eca678b6d4b2f9fe04ff53d8", size = 8720, upload-time = "2025-11-14T10:01:36.564Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-scenekit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-quartz" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/94/8c/1f4005cf0cb68f84dd98b93bbc0974ee7851bb33d976791c85e042dc2278/pyobjc_framework_scenekit-12.1.tar.gz", hash = "sha256:1bd5b866f31fd829f26feac52e807ed942254fd248115c7c742cfad41d949426", size = 101212, upload-time = "2025-11-14T10:21:41.265Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/a0/7f/eda261013dc41cc70f3157d1a750712dc29b64fc05be84232006b5cd57e5/pyobjc_framework_scenekit-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:01bf1336a7a8bdc96fabde8f3506aa7a7d1905e20a5c46030a57daf0ce2cbd16", size = 33542, upload-time = "2025-11-14T10:01:47.613Z" },
+ { url = "https://files.pythonhosted.org/packages/d2/f1/4986bd96e0ba0f60bff482a6b135b9d6db65d56578d535751f18f88190f0/pyobjc_framework_scenekit-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:40aea10098893f0b06191f1e79d7b25e12e36a9265549d324238bdb25c7e6df0", size = 33597, upload-time = "2025-11-14T10:01:51.297Z" },
+ { url = "https://files.pythonhosted.org/packages/4a/82/c728a025fd09cd259870d43b68ce8e7cffb639112033693ffa02d3d1eac0/pyobjc_framework_scenekit-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:a032377a7374320131768b6c8bf84589e45819d9e0fe187bd3f8d985207016b9", size = 33623, upload-time = "2025-11-14T10:01:54.878Z" },
+ { url = "https://files.pythonhosted.org/packages/5e/ef/9cea4cc4ac7f43fa6fb60d0690d25b2da1d8e1cf42266316014d1bb43a11/pyobjc_framework_scenekit-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:633909adff9b505b49c34307f507f4bd926b88a1482d8143655d5703481cbbf5", size = 33934, upload-time = "2025-11-14T10:01:57.994Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-screencapturekit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-coremedia" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/2d/7f/73458db1361d2cb408f43821a1e3819318a0f81885f833d78d93bdc698e0/pyobjc_framework_screencapturekit-12.1.tar.gz", hash = "sha256:50992c6128b35ab45d9e336f0993ddd112f58b8c8c8f0892a9cb42d61bd1f4c9", size = 32573, upload-time = "2025-11-14T10:21:44.497Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/79/92/fe66408f4bd74f6b6da75977d534a7091efe988301d13da4f009bf54ab71/pyobjc_framework_screencapturekit-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:ae412d397eedf189e763defe3497fcb8dffa5e0b54f62390cb33bf9b1cfb864a", size = 11473, upload-time = "2025-11-14T10:02:09.177Z" },
+ { url = "https://files.pythonhosted.org/packages/05/a8/533acdbf26e0a908ff640d3a445481f3c948682ca887be6711b5fcf82682/pyobjc_framework_screencapturekit-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:27df138ce2dfa9d4aae5106d4877e9ed694b5a174643c058f1c48678ffc7001a", size = 11504, upload-time = "2025-11-14T10:02:11.36Z" },
+ { url = "https://files.pythonhosted.org/packages/45/f9/ff713b8c4659f9ef1c4dbb8ca4b59c4b22d9df48471230979d620709e3b4/pyobjc_framework_screencapturekit-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:168125388fb35c6909bec93b259508156e89b9e30fec5748d4a04fd0157f0e0d", size = 11523, upload-time = "2025-11-14T10:02:13.494Z" },
+ { url = "https://files.pythonhosted.org/packages/f0/26/8bf1bacdb2892cf26d043c7f6e8788a613bbb2ccb313a5ea0634612cfc24/pyobjc_framework_screencapturekit-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:4fc2fe72c1da5ac1b8898a7b2082ed69803e6d9c11f414bb5a5ec94422a5f74f", size = 11701, upload-time = "2025-11-14T10:02:15.634Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-screensaver"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/7d/99/7cfbce880cea61253a44eed594dce66c2b2fbf29e37eaedcd40cffa949e9/pyobjc_framework_screensaver-12.1.tar.gz", hash = "sha256:c4ca111317c5a3883b7eace0a9e7dd72bc6ffaa2ca954bdec918c3ab7c65c96f", size = 22229, upload-time = "2025-11-14T10:21:47.299Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/2d/8d/87ca0fa0a9eda3097a0f4f2eef1544bf1d984697939fbef7cda7495fddb9/pyobjc_framework_screensaver-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:5bd10809005fbe0d68fe651f32a393ce059e90da38e74b6b3cd055ed5b23eaa9", size = 8480, upload-time = "2025-11-14T10:02:22.798Z" },
+ { url = "https://files.pythonhosted.org/packages/5a/a4/2481711f2e9557b90bac74fa8bf821162cf7b65835732ae560fd52e9037e/pyobjc_framework_screensaver-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:a3c90c2299eac6d01add81427ae2f90d7724f15d676261e838d7a7750f812322", size = 8422, upload-time = "2025-11-14T10:02:24.49Z" },
+ { url = "https://files.pythonhosted.org/packages/7e/8a/2e0cb958e872896b67ae6d5877070867f4a845ea1010984ff887ad418396/pyobjc_framework_screensaver-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:2a865b6dbb39fb92cdb67b13f68d594ab84d08a984cc3e9a39fab3386f431649", size = 8442, upload-time = "2025-11-14T10:02:26.135Z" },
+ { url = "https://files.pythonhosted.org/packages/35/45/3eb9984119be3dcd90f4628ecc3964c1a394b702a71034af6d932f98de3a/pyobjc_framework_screensaver-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:c249dffcb95d55fc6be626bf17f70b477e320c33d94e234597bc0074e302cfcd", size = 8450, upload-time = "2025-11-14T10:02:27.782Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-screentime"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/10/11/ba18f905321895715dac3cae2071c2789745ae13605b283b8114b41e0459/pyobjc_framework_screentime-12.1.tar.gz", hash = "sha256:583de46b365543bbbcf27cd70eedd375d397441d64a2cf43c65286fd9c91af55", size = 13413, upload-time = "2025-11-14T10:21:49.17Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/27/06/904174de6170e11b53673cc5844e5f13394eeeed486e0bcdf5288c1b0853/pyobjc_framework_screentime-12.1-py2.py3-none-any.whl", hash = "sha256:d34a068ec8ba2704987fcd05c37c9a9392de61d92933e6e71c8e4eaa4dfce029", size = 3963, upload-time = "2025-11-14T10:02:32.577Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-scriptingbridge"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/0c/cb/adc0a09e8c4755c2281bd12803a87f36e0832a8fc853a2d663433dbb72ce/pyobjc_framework_scriptingbridge-12.1.tar.gz", hash = "sha256:0e90f866a7e6a8aeaf723d04c826657dd528c8c1b91e7a605f8bb947c74ad082", size = 20339, upload-time = "2025-11-14T10:21:51.769Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/42/de/0943ee8d7f1a7d8467df6e2ea017a6d5041caff2fb0283f37fea4c4ce370/pyobjc_framework_scriptingbridge-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:e6e37e69760d6ac9d813decf135d107760d33e1cdf7335016522235607f6f31b", size = 8335, upload-time = "2025-11-14T10:02:36.654Z" },
+ { url = "https://files.pythonhosted.org/packages/51/46/e0b07d2b3ff9effb8b1179a6cc681a953d3dfbf0eb8b1d6a0e54cef2e922/pyobjc_framework_scriptingbridge-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:8083cd68c559c55a3787b2e74fc983c8665e5078571475aaeabf4f34add36b62", size = 8356, upload-time = "2025-11-14T10:02:38.559Z" },
+ { url = "https://files.pythonhosted.org/packages/1a/da/b11568f21924a994aa59272e2752e742f8380ab2cf88d111326ba7baede0/pyobjc_framework_scriptingbridge-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:bddbd3a13bfaeaa38ab66e44f10446d5bc7d1110dbc02e59b80bcd9c3a60548a", size = 8371, upload-time = "2025-11-14T10:02:40.603Z" },
+ { url = "https://files.pythonhosted.org/packages/77/eb/9bc3e6e9611d757fc80b4423cc28128750a72eae8241be8ae43e1d76c4cd/pyobjc_framework_scriptingbridge-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:148191010b4e10c3938cdb2dcecad43fa0884cefb5a78499a21bdaf5a78318b3", size = 8526, upload-time = "2025-11-14T10:02:42.298Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-searchkit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-coreservices" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/6e/60/a38523198430e14fdef21ebe62a93c43aedd08f1f3a07ea3d96d9997db5d/pyobjc_framework_searchkit-12.1.tar.gz", hash = "sha256:ddd94131dabbbc2d7c3f17db3da87c1a712c431310eef16f07187771e7e85226", size = 30942, upload-time = "2025-11-14T10:21:55.483Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/72/46/4f9cd3011f47b43b21b2924ab3770303c3f0a4d16f05550d38c5fcb42e78/pyobjc_framework_searchkit-12.1-py2.py3-none-any.whl", hash = "sha256:844ce62b7296b19da8db7dedd539d07f7b3fb3bb8b029c261f7bcf0e01a97758", size = 3733, upload-time = "2025-11-14T10:02:47.026Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-security"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/80/aa/796e09a3e3d5cee32ebeebb7dcf421b48ea86e28c387924608a05e3f668b/pyobjc_framework_security-12.1.tar.gz", hash = "sha256:7fecb982bd2f7c4354513faf90ba4c53c190b7e88167984c2d0da99741de6da9", size = 168044, upload-time = "2025-11-14T10:22:06.334Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/5e/3d/8d3a39cd292d7c76ab76233498189bc7170fc80f573b415308464f68c7ee/pyobjc_framework_security-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:1b2d8819f0fb7b619ec7627a0d8c1cac1a57c5143579ce8ac21548165680684b", size = 41287, upload-time = "2025-11-14T10:02:54.491Z" },
+ { url = "https://files.pythonhosted.org/packages/76/66/5160c0f938fc0515fe8d9af146aac1b093f7ef285ce797fedae161b6c0e8/pyobjc_framework_security-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:ab42e55f5b782332be5442750fcd9637ee33247d57c7b1d5801bc0e24ee13278", size = 41280, upload-time = "2025-11-14T10:02:58.097Z" },
+ { url = "https://files.pythonhosted.org/packages/32/48/b294ed75247c5cfa00d51925a10237337d24f54961d49a179b20a4307642/pyobjc_framework_security-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:afc36661cc6eb98cd794bed1d6668791e96557d6f72d9ac70aa49022d26af1d4", size = 41284, upload-time = "2025-11-14T10:03:01.722Z" },
+ { url = "https://files.pythonhosted.org/packages/ef/57/0d3ef78779cf5c3bba878b2f824137e50978ad4a21dabe65d8b5ae0fc0d1/pyobjc_framework_security-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:9510c98ab56921d1d416437372605cc1c1f6c1ad8d3061ee56b17bf423dd5427", size = 42162, upload-time = "2025-11-14T10:03:05.337Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-securityfoundation"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-security" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/57/d5/c2b77e83c1585ba43e5f00c917273ba4bf7ed548c1b691f6766eb0418d52/pyobjc_framework_securityfoundation-12.1.tar.gz", hash = "sha256:1f39f4b3db6e3bd3a420aaf4923228b88e48c90692cf3612b0f6f1573302a75d", size = 12669, upload-time = "2025-11-14T10:22:09.256Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/93/1e/349fb71a413b37b1b41e712c7ca180df82144478f8a9a59497d66d0f2ea2/pyobjc_framework_securityfoundation-12.1-py2.py3-none-any.whl", hash = "sha256:579cf23e63434226f78ffe0afb8426e971009588e4ad812c478d47dfd558201c", size = 3792, upload-time = "2025-11-14T10:03:14.459Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-securityinterface"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-security" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/f9/64/bf5b5d82655112a2314422ee649f1e1e73d4381afa87e1651ce7e8444694/pyobjc_framework_securityinterface-12.1.tar.gz", hash = "sha256:deef11ad03be8d9ff77db6e7ac40f6b641ee2d72eaafcf91040537942472e88b", size = 25552, upload-time = "2025-11-14T10:22:12.098Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/37/1c/a01fd56765792d1614eb5e8dc0a7d5467564be6a2056b417c9ec7efc648f/pyobjc_framework_securityinterface-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:ed599be750122376392e95c2407d57bd94644e8320ddef1d67660e16e96b0d06", size = 10719, upload-time = "2025-11-14T10:03:18.353Z" },
+ { url = "https://files.pythonhosted.org/packages/59/3e/17889a6de03dc813606bb97887dc2c4c2d4e7c8f266bc439548bae756e90/pyobjc_framework_securityinterface-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:5cb5e79a73ea17663ebd29e350401162d93e42343da7d96c77efb38ae64ff01f", size = 10783, upload-time = "2025-11-14T10:03:20.202Z" },
+ { url = "https://files.pythonhosted.org/packages/78/c0/b286689fca6dd23f1ad5185eb429a12fba60d157d7d53f6188c19475b331/pyobjc_framework_securityinterface-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:af5db06d53c92f05446600d241afab5aec6fec7ab10941b4eeb27a452c543b64", size = 10799, upload-time = "2025-11-14T10:03:22.296Z" },
+ { url = "https://files.pythonhosted.org/packages/72/52/d378f25bb15f0d34e610f6cba50cedb0b99fdbae9bae9c0f0e715340f338/pyobjc_framework_securityinterface-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:08516c01954233fecb9bd203778b1bf559d427ccea26444ae1fa93691e751ddd", size = 11139, upload-time = "2025-11-14T10:03:24.17Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-securityui"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-security" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/83/3f/d870305f5dec58cd02966ca06ac29b69fb045d8b46dfb64e2da31f295345/pyobjc_framework_securityui-12.1.tar.gz", hash = "sha256:f1435fed85edc57533c334a4efc8032170424b759da184cb7a7a950ceea0e0b6", size = 12184, upload-time = "2025-11-14T10:22:14.323Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/36/7f/eff9ffdd34511cc95a60e5bd62f1cfbcbcec1a5012ef1168161506628c87/pyobjc_framework_securityui-12.1-py2.py3-none-any.whl", hash = "sha256:3e988b83c9a2bb0393207eaa030fc023a8708a975ac5b8ea0508cdafc2b60705", size = 3594, upload-time = "2025-11-14T10:03:29.628Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-sensitivecontentanalysis"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-quartz" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e7/ce/17bf31753e14cb4d64fffaaba2377453c4977c2c5d3cf2ff0a3db30026c7/pyobjc_framework_sensitivecontentanalysis-12.1.tar.gz", hash = "sha256:2c615ac10e93eb547b32b214cd45092056bee0e79696426fd09978dc3e670f25", size = 13745, upload-time = "2025-11-14T10:22:16.447Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/95/23/c99568a0d4e38bd8337d52e4ae25a0b0bd540577f2e06f3430c951d73209/pyobjc_framework_sensitivecontentanalysis-12.1-py2.py3-none-any.whl", hash = "sha256:faf19d32d4599ac2b18fb1ccdc3e33b2b242bdf34c02e69978bd62d3643ad068", size = 4230, upload-time = "2025-11-14T10:03:31.26Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-servicemanagement"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/31/d0/b26c83ae96ab55013df5fedf89337d4d62311b56ce3f520fc7597d223d82/pyobjc_framework_servicemanagement-12.1.tar.gz", hash = "sha256:08120981749a698033a1d7a6ab99dbbe412c5c0d40f2b4154014b52113511c1d", size = 14585, upload-time = "2025-11-14T10:22:18.735Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/ee/5d/1009c32189f9cb26da0124b4a60640ed26dd8ad453810594f0cbfab0ff70/pyobjc_framework_servicemanagement-12.1-py2.py3-none-any.whl", hash = "sha256:9a2941f16eeb71e55e1cd94f50197f91520778c7f48ad896761f5e78725cc08f", size = 5357, upload-time = "2025-11-14T10:03:32.928Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-sharedwithyou"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-sharedwithyoucore" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/0f/8b/8ab209a143c11575a857e2111acc5427fb4986b84708b21324cbcbf5591b/pyobjc_framework_sharedwithyou-12.1.tar.gz", hash = "sha256:167d84794a48f408ee51f885210c616fda1ec4bff3dd8617a4b5547f61b05caf", size = 24791, upload-time = "2025-11-14T10:22:21.248Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/19/69/3ad9b344808c5619adc253b665f8677829dfb978888227e07233d120cfab/pyobjc_framework_sharedwithyou-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:359c03096a6988371ea89921806bb81483ea509c9aa7114f9cd20efd511b3576", size = 8739, upload-time = "2025-11-14T10:03:36.48Z" },
+ { url = "https://files.pythonhosted.org/packages/ec/ee/e5113ce985a480d13a0fa3d41a242c8068dc09b3c13210557cf5cc6a544a/pyobjc_framework_sharedwithyou-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:a99a6ebc6b6de7bc8663b1f07332fab9560b984a57ce344dc5703f25258f258d", size = 8763, upload-time = "2025-11-14T10:03:38.467Z" },
+ { url = "https://files.pythonhosted.org/packages/2e/51/e833c41cb6578f51623da361f6ded50b5b91331f9339b125ea50b4e62f8b/pyobjc_framework_sharedwithyou-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:491b35cdb3a0bc11e730c96d4109944c77ab153573a28220ff12d41d34dd9c0f", size = 8781, upload-time = "2025-11-14T10:03:40.14Z" },
+ { url = "https://files.pythonhosted.org/packages/59/c4/b843dc3b7bd1385634df7f0bb8b557d8d09df3a384c7b2df0bc85af5bd4e/pyobjc_framework_sharedwithyou-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:50f0b32e2bf6f7ceb3af4422b015f674dc20a8cb1afa72d78f7e4186eb3710b9", size = 8917, upload-time = "2025-11-14T10:03:41.824Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-sharedwithyoucore"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/55/ef/84059c5774fd5435551ab7ab40b51271cfb9997b0d21f491c6b429fe57a8/pyobjc_framework_sharedwithyoucore-12.1.tar.gz", hash = "sha256:0813149eeb755d718b146ec9365eb4ca3262b6af9ff9ba7db2f7b6f4fd104518", size = 22350, upload-time = "2025-11-14T10:22:23.611Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/ce/a1/83e58eca8827a1a9975a9c5de7f8c0bdc73b5f53ee79768d1fdbec6747de/pyobjc_framework_sharedwithyoucore-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:f4f9f7fed0768ebbbc2d24248365da2cf5f014b8822b2a1fbbce5fa920f410f1", size = 8512, upload-time = "2025-11-14T10:03:49.176Z" },
+ { url = "https://files.pythonhosted.org/packages/dd/0e/0c2b0591ebc72d437dccca7a1e7164c5f11dde2189d4f4c707a132bab740/pyobjc_framework_sharedwithyoucore-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:ed928266ae9d577ff73de72a03bebc66a751918eb59ca660a9eca157392f17be", size = 8530, upload-time = "2025-11-14T10:03:50.839Z" },
+ { url = "https://files.pythonhosted.org/packages/5e/23/2446cb158efe0f55d983ae7b4729b3b24c52a1370b5d22bc134f046cdb34/pyobjc_framework_sharedwithyoucore-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:13eebca21722556449e47b0eda3339165b5afbb455ae00b34aabe03988affd7a", size = 8547, upload-time = "2025-11-14T10:03:52.459Z" },
+ { url = "https://files.pythonhosted.org/packages/8e/42/6c5de4e508a0c0f4715e3466c0035e23b5875d2a43525a6ed81e4770ad3c/pyobjc_framework_sharedwithyoucore-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:d9aa525cdff75005a8f0ca2f7afdd1535b9e34ccafb6a92a932f3ded4b6d64d4", size = 8677, upload-time = "2025-11-14T10:03:54.15Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-shazamkit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/ed/2c/8d82c5066cc376de68ad8c1454b7c722c7a62215e5c2f9dac5b33a6c3d42/pyobjc_framework_shazamkit-12.1.tar.gz", hash = "sha256:71db2addd016874639a224ed32b2000b858802b0370c595a283cce27f76883fe", size = 22518, upload-time = "2025-11-14T10:22:25.996Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/92/12/09d83a8ac51dc11a574449dea48ffa99b3a7c9baf74afeedb487394d110d/pyobjc_framework_shazamkit-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:0c10ba22de524fbedf06270a71bb0a3dbd4a3853b7002ddf54394589c3be6939", size = 8555, upload-time = "2025-11-14T10:04:02.552Z" },
+ { url = "https://files.pythonhosted.org/packages/04/5e/7d60d8e7b036b20d0e94cd7c4563e7414653344482e85fbc7facffabc95f/pyobjc_framework_shazamkit-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:e184dd0f61a604b1cfcf44418eb95b943e7b8f536058a29e4b81acadd27a9420", size = 8577, upload-time = "2025-11-14T10:04:04.182Z" },
+ { url = "https://files.pythonhosted.org/packages/a9/fa/476cf0eb6f70e434056276b1a52bb47419e4b91d80e0c8e1190ce84f888f/pyobjc_framework_shazamkit-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:957c5e31b2b275c822ea43d7c4435fa1455c6dc5469ad4b86b29455571794027", size = 8587, upload-time = "2025-11-14T10:04:06.351Z" },
+ { url = "https://files.pythonhosted.org/packages/9a/69/105fccda6c5ca32d35edc5e055d4cffc9aefe6a40fdd00bb21ec5d21e0ce/pyobjc_framework_shazamkit-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:eb2875ddf18d3cd2dc2b1327f58e142b9bd86fafd32078387ed867ec5a6c5571", size = 8734, upload-time = "2025-11-14T10:04:08.33Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-social"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/31/21/afc6f37dfdd2cafcba0227e15240b5b0f1f4ad57621aeefda2985ac9560e/pyobjc_framework_social-12.1.tar.gz", hash = "sha256:1963db6939e92ae40dd9d68852e8f88111cbfd37a83a9fdbc9a0c08993ca7e60", size = 13184, upload-time = "2025-11-14T10:22:28.048Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/f6/fb/090867e332d49a1e492e4b8972ac6034d1c7d17cf39f546077f35be58c46/pyobjc_framework_social-12.1-py2.py3-none-any.whl", hash = "sha256:2f3b36ba5769503b1bc945f85fd7b255d42d7f6e417d78567507816502ff2b44", size = 4462, upload-time = "2025-11-14T10:04:14.578Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-soundanalysis"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/6b/d6/5039b61edc310083425f87ce2363304d3a87617e941c1d07968c63b5638d/pyobjc_framework_soundanalysis-12.1.tar.gz", hash = "sha256:e2deead8b9a1c4513dbdcf703b21650dcb234b60a32d08afcec4895582b040b1", size = 14804, upload-time = "2025-11-14T10:22:29.998Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/53/d3/8df5183d52d20d459225d3f5d24f55e01b8cd9fe587ed972e3f20dd18709/pyobjc_framework_soundanalysis-12.1-py2.py3-none-any.whl", hash = "sha256:8b2029ab48c1a9772f247f0aea995e8c3ff4706909002a9c1551722769343a52", size = 4188, upload-time = "2025-11-14T10:04:16.12Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-speech"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/8d/3d/194cf19fe7a56c2be5dfc28f42b3b597a62ebb1e1f52a7dd9c55b917ac6c/pyobjc_framework_speech-12.1.tar.gz", hash = "sha256:2a2a546ba6c52d5dd35ddcfee3fd9226a428043d1719597e8701851a6566afdd", size = 25218, upload-time = "2025-11-14T10:22:32.505Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/03/54/77e12e4c23a98fc49d874f9703c9f8fd0257d64bb0c6ae329b91fc7a99e3/pyobjc_framework_speech-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:0301bfae5d0d09b6e69bd4dbabc5631209e291cc40bda223c69ed0c618f8f2dc", size = 9248, upload-time = "2025-11-14T10:04:19.73Z" },
+ { url = "https://files.pythonhosted.org/packages/f9/1b/224cb98c9c32a6d5e68072f89d26444095be54c6f461efe4fefe9d1330a5/pyobjc_framework_speech-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:cae4b88ef9563157a6c9e66b37778fc4022ee44dd1a2a53081c2adbb69698945", size = 9254, upload-time = "2025-11-14T10:04:21.361Z" },
+ { url = "https://files.pythonhosted.org/packages/21/98/9ae05ebe183f35ac4bb769070f90533405d886fb9216e868e30a0e58d1ad/pyobjc_framework_speech-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:49df0ac39ae6fb44a83b2f4d7f500e0fa074ff58fbc53106d8f626d325079c23", size = 9274, upload-time = "2025-11-14T10:04:23.399Z" },
+ { url = "https://files.pythonhosted.org/packages/ec/9d/41581c58ea8f8962189bcf6a15944f9a0bf36b46c5fce611a9632b3344a2/pyobjc_framework_speech-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:ed5455f6d9e473c08ebf904ae280ad5fd0d00a073448bf4f0a01fee5887c5537", size = 9430, upload-time = "2025-11-14T10:04:25.026Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-spritekit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-quartz" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b6/78/d683ebe0afb49f46d2d21d38c870646e7cb3c2e83251f264e79d357b1b74/pyobjc_framework_spritekit-12.1.tar.gz", hash = "sha256:a851f4ef5aa65cc9e08008644a528e83cb31021a1c0f17ebfce4de343764d403", size = 64470, upload-time = "2025-11-14T10:22:37.569Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/60/6a/e8e44fc690d898394093f3a1c5fe90110d1fbcc6e3f486764437c022b0f8/pyobjc_framework_spritekit-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:26fd12944684713ae1e3cdd229348609c1142e60802624161ca0c3540eec3ffa", size = 17736, upload-time = "2025-11-14T10:04:33.202Z" },
+ { url = "https://files.pythonhosted.org/packages/3b/38/97c3b6c3437e3e9267fb4e1cd86e0da4eff07e0abe7cd6923644d2dfc878/pyobjc_framework_spritekit-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:1649e57c25145795d04bb6a1ec44c20ef7cf0af7c60a9f6f5bc7998dd269db1e", size = 17802, upload-time = "2025-11-14T10:04:35.346Z" },
+ { url = "https://files.pythonhosted.org/packages/1f/c6/0e62700fbc90ab57170931fb5056d964202d49efd4d07a610fdaa28ffcfa/pyobjc_framework_spritekit-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:dd6847cb7a287c42492ffd7c30bc08165f4fbb51b2602290e001c0d27e0aa0f0", size = 17818, upload-time = "2025-11-14T10:04:37.804Z" },
+ { url = "https://files.pythonhosted.org/packages/a6/22/26b19fc487913d9324cbba824841c9ac921aa9bdd6e340ed46b9968547bc/pyobjc_framework_spritekit-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:dd6e309aa284fa9b434aa7bf8ab9ab23fe52e7a372e2db3869586a74471f3419", size = 18088, upload-time = "2025-11-14T10:04:39.973Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-storekit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/00/87/8a66a145feb026819775d44975c71c1c64df4e5e9ea20338f01456a61208/pyobjc_framework_storekit-12.1.tar.gz", hash = "sha256:818452e67e937a10b5c8451758274faa44ad5d4329df0fa85735115fb0608da9", size = 34574, upload-time = "2025-11-14T10:22:40.73Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/d9/41/af2afc4d27bde026cfd3b725ee1b082b2838dcaa9880ab719226957bc7cd/pyobjc_framework_storekit-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:a29f45bcba9dee4cf73dae05ab0f94d06a32fb052e31414d0c23791c1ec7931c", size = 12810, upload-time = "2025-11-14T10:04:48.693Z" },
+ { url = "https://files.pythonhosted.org/packages/8a/9f/938985e506de0cc3a543e44e1f9990e9e2fb8980b8f3bcfc8f7921d09061/pyobjc_framework_storekit-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:9fe2d65a2b644bb6b4fdd3002292cba153560917de3dd6cf969431fa32d21dd0", size = 12819, upload-time = "2025-11-14T10:04:50.945Z" },
+ { url = "https://files.pythonhosted.org/packages/5a/84/d354fd6f50952148614597dd4ebd52ed1d6a3e38cbd5d88e930bd549983d/pyobjc_framework_storekit-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:556c3dc187646ab8bda714a7e5630201b931956b81b0162ba420c64f55e5faaf", size = 12835, upload-time = "2025-11-14T10:04:52.866Z" },
+ { url = "https://files.pythonhosted.org/packages/4f/24/f8a8d2f1c1107a0a0f85bd830b9e0ff7016d4530924b17787cb8c7bf4f4c/pyobjc_framework_storekit-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:15d4643bc4de4aa62f72efcb7a4930bd7e15280867be225bd2c582b3367d75ae", size = 13028, upload-time = "2025-11-14T10:04:55.605Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-symbols"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/9a/ce/a48819eb8524fa2dc11fb3dd40bb9c4dcad0596fe538f5004923396c2c6c/pyobjc_framework_symbols-12.1.tar.gz", hash = "sha256:7d8e999b8a59c97d38d1d343b6253b1b7d04bf50b665700957d89c8ac43b9110", size = 12782, upload-time = "2025-11-14T10:22:42.609Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/f0/ea/6e9af9c750d68109ac54fbffb5463e33a7b54ffe8b9901a5b6b603b7884b/pyobjc_framework_symbols-12.1-py2.py3-none-any.whl", hash = "sha256:c72eecbc25f6bfcd39c733067276270057c5aca684be20fdc56def645f2b6446", size = 3331, upload-time = "2025-11-14T10:05:01.333Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-syncservices"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-coredata" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/21/91/6d03a988831ddb0fb001b13573560e9a5bcccde575b99350f98fe56a2dd4/pyobjc_framework_syncservices-12.1.tar.gz", hash = "sha256:6a213e93d9ce15128810987e4c5de8c73cfab1564ac8d273e6b437a49965e976", size = 31032, upload-time = "2025-11-14T10:22:45.902Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/4a/9b/25c117f8ffe15aa6cc447da7f5c179627ebafb2b5ec30dfb5e70fede2549/pyobjc_framework_syncservices-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:e81a38c2eb7617cb0ecfc4406c1ae2a97c60e95af42e863b2b0f1f6facd9b0da", size = 13380, upload-time = "2025-11-14T10:05:05.814Z" },
+ { url = "https://files.pythonhosted.org/packages/54/ac/a83cdd120e279ee905e9085afda90992159ed30c6a728b2c56fa2d36b6ea/pyobjc_framework_syncservices-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:0cd629bea95692aad2d26196657cde2fbadedae252c7846964228661a600b900", size = 13411, upload-time = "2025-11-14T10:05:07.741Z" },
+ { url = "https://files.pythonhosted.org/packages/5b/e3/9a6bd76529feffe08a3f6b2962c9a96d75febc02453881ec81389ff9ac13/pyobjc_framework_syncservices-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:606afac9255b5bf828f1dcf7b0d7bdc7726021b686ad4f5743978eb4086902d9", size = 13425, upload-time = "2025-11-14T10:05:09.692Z" },
+ { url = "https://files.pythonhosted.org/packages/3b/5d/338850a31968b94417ba95a7b94db9fcd40b16011eaf82f757de7c1eba6c/pyobjc_framework_syncservices-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:9d1ebe60e92efd08455be209a265879cf297feda831aadf36431f38229b1dd52", size = 13599, upload-time = "2025-11-14T10:05:11.732Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-systemconfiguration"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/90/7d/50848df8e1c6b5e13967dee9fb91d3391fe1f2399d2d0797d2fc5edb32ba/pyobjc_framework_systemconfiguration-12.1.tar.gz", hash = "sha256:90fe04aa059876a21626931c71eaff742a27c79798a46347fd053d7008ec496e", size = 59158, upload-time = "2025-11-14T10:22:53.056Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/1d/7b/9126a7af1b798998837027390a20b981e0298e51c4c55eed6435967145cb/pyobjc_framework_systemconfiguration-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:796390a80500cc7fde86adc71b11cdc41d09507dd69103d3443fbb60e94fb438", size = 21663, upload-time = "2025-11-14T10:05:21.259Z" },
+ { url = "https://files.pythonhosted.org/packages/d3/d3/bb935c3d4bae9e6ce4a52638e30eea7039c480dd96bc4f0777c9fabda21b/pyobjc_framework_systemconfiguration-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:0e5bb9103d39483964431db7125195c59001b7bff2961869cfe157b4c861e52d", size = 21578, upload-time = "2025-11-14T10:05:25.572Z" },
+ { url = "https://files.pythonhosted.org/packages/64/26/22f031c99fd7012dffa41455951004a758aaf9a25216b3a4ee83496bc44f/pyobjc_framework_systemconfiguration-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:359b35c00f52f57834169c1057522279201ac5a64ac5b4d90dbafa40ad6c54b4", size = 21575, upload-time = "2025-11-14T10:05:28.396Z" },
+ { url = "https://files.pythonhosted.org/packages/f2/58/648803bdf3d2ebd3221ef43deb008c77aefe0bec231af2aa67e5b29a78e2/pyobjc_framework_systemconfiguration-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:f4ff57defb4dcd933db392eb8ea9e5a46005cb7a6f2b46c27ab2dd5e13a459ab", size = 21990, upload-time = "2025-11-14T10:05:30.875Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-systemextensions"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/12/01/8a706cd3f7dfcb9a5017831f2e6f9e5538298e90052db3bb8163230cbc4f/pyobjc_framework_systemextensions-12.1.tar.gz", hash = "sha256:243e043e2daee4b5c46cd90af5fff46b34596aac25011bab8ba8a37099685eeb", size = 20701, upload-time = "2025-11-14T10:22:58.257Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/ac/a1/f8df6d59e06bc4b5989a76724e8551935e5b99aff6a21d3592e5ced91f1c/pyobjc_framework_systemextensions-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:2a4e82160e43c0b1aa17e6d4435e840a655737fbe534e00e37fc1961fbf3bebd", size = 9156, upload-time = "2025-11-14T10:05:39.744Z" },
+ { url = "https://files.pythonhosted.org/packages/0a/cc/a42883d6ad0ae257a7fa62660b4dd13be15f8fa657922f9a5b6697f26e28/pyobjc_framework_systemextensions-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:01fac4f8d88c0956d9fc714d24811cd070e67200ba811904317d91e849e38233", size = 9166, upload-time = "2025-11-14T10:05:41.479Z" },
+ { url = "https://files.pythonhosted.org/packages/dd/ef/fd34784added1dff088bd18cc2694049b0893b01e835587eab1735fd68f3/pyobjc_framework_systemextensions-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:038032801d46cc7b1ea69400f43d5c17b25d7a16efa7a7d9727b25789387a8cf", size = 9185, upload-time = "2025-11-14T10:05:43.136Z" },
+ { url = "https://files.pythonhosted.org/packages/72/76/fd6f06e54299998677548bacd21105450bc6435df215a6620422a31b0099/pyobjc_framework_systemextensions-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:2aea4e823d915abca463b1c091ff969cef09108c88b71b68569485dec6f3651d", size = 9345, upload-time = "2025-11-14T10:05:44.814Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-threadnetwork"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/62/7e/f1816c3461e4121186f2f7750c58af083d1826bbd73f72728da3edcf4915/pyobjc_framework_threadnetwork-12.1.tar.gz", hash = "sha256:e071eedb41bfc1b205111deb54783ec5a035ccd6929e6e0076336107fdd046ee", size = 12788, upload-time = "2025-11-14T10:23:00.329Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/4f/b8/94b37dd353302c051a76f1a698cf55b5ad50ca061db7f0f332aa9e195766/pyobjc_framework_threadnetwork-12.1-py2.py3-none-any.whl", hash = "sha256:07d937748fc54199f5ec04d5a408e8691a870481c11b641785c2adc279dd8e4b", size = 3771, upload-time = "2025-11-14T10:05:49.899Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-uniformtypeidentifiers"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/65/b8/dd9d2a94509a6c16d965a7b0155e78edf520056313a80f0cd352413f0d0b/pyobjc_framework_uniformtypeidentifiers-12.1.tar.gz", hash = "sha256:64510a6df78336579e9c39b873cfcd03371c4b4be2cec8af75a8a3d07dff607d", size = 17030, upload-time = "2025-11-14T10:23:02.222Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/4e/5f/1f10f5275b06d213c9897850f1fca9c881c741c1f9190cea6db982b71824/pyobjc_framework_uniformtypeidentifiers-12.1-py2.py3-none-any.whl", hash = "sha256:ec5411e39152304d2a7e0e426c3058fa37a00860af64e164794e0bcffee813f2", size = 4901, upload-time = "2025-11-14T10:05:51.532Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-usernotifications"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/90/cd/e0253072f221fa89a42fe53f1a2650cc9bf415eb94ae455235bd010ee12e/pyobjc_framework_usernotifications-12.1.tar.gz", hash = "sha256:019ccdf2d400f9a428769df7dba4ea97c02453372bc5f8b75ce7ae54dfe130f9", size = 29749, upload-time = "2025-11-14T10:23:05.364Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/d1/96/aa25bb0727e661a352d1c52e7288e25c12fe77047f988bb45557c17cf2d7/pyobjc_framework_usernotifications-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:c62e8d7153d72c4379071e34258aa8b7263fa59212cfffd2f137013667e50381", size = 9632, upload-time = "2025-11-14T10:05:55.166Z" },
+ { url = "https://files.pythonhosted.org/packages/61/ad/c95053a475246464cba686e16269b0973821601910d1947d088b855a8dac/pyobjc_framework_usernotifications-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:412afb2bf5fe0049f9c4e732e81a8a35d5ebf97c30a5a6abd276259d020c82ac", size = 9644, upload-time = "2025-11-14T10:05:56.801Z" },
+ { url = "https://files.pythonhosted.org/packages/b1/cc/4c6efe6a65b1742ea238734f81509ceba5346b45f605baa809ca63f30692/pyobjc_framework_usernotifications-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:40a5457f4157ca007f80f0644413f44f0dc141f7864b28e1728623baf56a8539", size = 9659, upload-time = "2025-11-14T10:05:58.763Z" },
+ { url = "https://files.pythonhosted.org/packages/06/4e/02ff6975567974f360cf0e1e358236026e35f7ba7795511bc4dcbaa13f62/pyobjc_framework_usernotifications-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:58c09bd1bd7a8cd29613d0d0e6096eda6c8465dc5a7a733675e1b8d0406f7adc", size = 9811, upload-time = "2025-11-14T10:06:00.775Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-usernotificationsui"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-usernotifications" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/0e/03/73e29fd5e5973cb3800c9d56107c1062547ef7524cbcc757c3cbbd5465c6/pyobjc_framework_usernotificationsui-12.1.tar.gz", hash = "sha256:51381c97c7344099377870e49ed0871fea85ba50efe50ab05ccffc06b43ec02e", size = 13125, upload-time = "2025-11-14T10:23:07.259Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/23/c8/52ac8a879079c1fbf25de8335ff506f7db87ff61e64838b20426f817f5d5/pyobjc_framework_usernotificationsui-12.1-py2.py3-none-any.whl", hash = "sha256:11af59dc5abfcb72c08769ab4d7ca32a628527a8ba341786431a0d2dacf31605", size = 3933, upload-time = "2025-11-14T10:06:05.478Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-videosubscriberaccount"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/10/f8/27927a9c125c622656ee5aada4596ccb8e5679da0260742360f193df6dcf/pyobjc_framework_videosubscriberaccount-12.1.tar.gz", hash = "sha256:750459fa88220ab83416f769f2d5d210a1f77b8938fa4d119aad0002fc32846b", size = 18793, upload-time = "2025-11-14T10:23:09.33Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/41/ca/e2f982916267508c1594f1e50d27bf223a24f55a5e175ab7d7822a00997c/pyobjc_framework_videosubscriberaccount-12.1-py2.py3-none-any.whl", hash = "sha256:381a5e8a3016676e52b88e38b706559fa09391d33474d8a8a52f20a883104a7b", size = 4825, upload-time = "2025-11-14T10:06:07.027Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-videotoolbox"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-coremedia" },
+ { name = "pyobjc-framework-quartz" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b3/5f/6995ee40dc0d1a3460ee183f696e5254c0ad14a25b5bc5fd9bd7266c077b/pyobjc_framework_videotoolbox-12.1.tar.gz", hash = "sha256:7adc8670f3b94b086aed6e86c3199b388892edab4f02933c2e2d9b1657561bef", size = 57825, upload-time = "2025-11-14T10:23:13.825Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/1e/42/53d57b09fd4879988084ec0d9b74c645c9fdd322be594c9601f6cf265dd0/pyobjc_framework_videotoolbox-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:a1eb1eb41c0ffdd8dcc6a9b68ab2b5bc50824a85820c8a7802a94a22dfbb4f91", size = 18781, upload-time = "2025-11-14T10:06:11.89Z" },
+ { url = "https://files.pythonhosted.org/packages/94/a5/91c6c95416f41c412c2079950527cb746c0712ec319c51a6c728c8d6b231/pyobjc_framework_videotoolbox-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:eb6ce6837344ee319122066c16ada4beb913e7bfd62188a8d14b1ecbb5a89234", size = 18908, upload-time = "2025-11-14T10:06:14.087Z" },
+ { url = "https://files.pythonhosted.org/packages/f0/59/7fc3d67df437f3e263b477dd181eef3ac3430cb7eb1acc951f5f1e84cc4d/pyobjc_framework_videotoolbox-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:ca28b39e22016eb5f81f540102a575ee6e6114074d09e17e22eb3b5647976d93", size = 18929, upload-time = "2025-11-14T10:06:16.418Z" },
+ { url = "https://files.pythonhosted.org/packages/f4/41/08b526d2f228271994f8216651d2e5c8e76415224daa012e67c53c90fc7a/pyobjc_framework_videotoolbox-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:dba7e078df01432331ee75a90c2c147264bfdb9e31998b4e4fc28913b93b832e", size = 19139, upload-time = "2025-11-14T10:06:18.602Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-virtualization"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/3b/6a/9d110b5521d9b898fad10928818c9f55d66a4af9ac097426c65a9878b095/pyobjc_framework_virtualization-12.1.tar.gz", hash = "sha256:e96afd8e801e92c6863da0921e40a3b68f724804f888bce43791330658abdb0f", size = 40682, upload-time = "2025-11-14T10:23:17.456Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/8b/ee/e18d0d9014c42758d7169144acb2d37eb5ff19bf959db74b20eac706bd8c/pyobjc_framework_virtualization-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:a88a307dc96885afc227ceda4067f1af787f024063f4ccf453d59e7afd47cda8", size = 13099, upload-time = "2025-11-14T10:06:27.403Z" },
+ { url = "https://files.pythonhosted.org/packages/c6/f2/0da47e91f3f8eeda9a8b4bb0d3a0c54a18925009e99b66a8226b9e06ce1e/pyobjc_framework_virtualization-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:7d5724b38e64b39ab5ec3b45993afa29fc88b307d99ee2c7a1c0fd770e9b4b21", size = 13131, upload-time = "2025-11-14T10:06:29.337Z" },
+ { url = "https://files.pythonhosted.org/packages/76/ca/228fffccbeafecbe7599fc2cdaa64bf2a8e42fd8fe619c5b670c92b263c3/pyobjc_framework_virtualization-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:232956de8a0c3086a58c96621e0a2148497d1750ebb1bb6bea9f7f34ec3c83c6", size = 13147, upload-time = "2025-11-14T10:06:31.294Z" },
+ { url = "https://files.pythonhosted.org/packages/b3/2f/4e56147bc9963bb7f96886fda376004a66c5abe579dc029180952fd872fa/pyobjc_framework_virtualization-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:a9552e49b967fb520e5be1cfce510e0b68c2ba314a28ac90aad36fe33218d430", size = 13351, upload-time = "2025-11-14T10:06:33.189Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-vision"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+ { name = "pyobjc-framework-coreml" },
+ { name = "pyobjc-framework-quartz" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c2/5a/08bb3e278f870443d226c141af14205ff41c0274da1e053b72b11dfc9fb2/pyobjc_framework_vision-12.1.tar.gz", hash = "sha256:a30959100e85dcede3a786c544e621ad6eb65ff6abf85721f805822b8c5fe9b0", size = 59538, upload-time = "2025-11-14T10:23:21.979Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/bd/37/e30cf4eef2b4c7e20ccadc1249117c77305fbc38b2e5904eb42e3753f63c/pyobjc_framework_vision-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:1edbf2fc18ce3b31108f845901a88f2236783ae6bf0bc68438d7ece572dc2a29", size = 21432, upload-time = "2025-11-14T10:06:42.373Z" },
+ { url = "https://files.pythonhosted.org/packages/3a/5a/23502935b3fc877d7573e743fc3e6c28748f33a45c43851d503bde52cde7/pyobjc_framework_vision-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:6b3211d84f3a12aad0cde752cfd43a80d0218960ac9e6b46b141c730e7d655bd", size = 16625, upload-time = "2025-11-14T10:06:44.422Z" },
+ { url = "https://files.pythonhosted.org/packages/f5/e4/e87361a31b82b22f8c0a59652d6e17625870dd002e8da75cb2343a84f2f9/pyobjc_framework_vision-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:7273e2508db4c2e88523b4b7ff38ac54808756e7ba01d78e6c08ea68f32577d2", size = 16640, upload-time = "2025-11-14T10:06:46.653Z" },
+ { url = "https://files.pythonhosted.org/packages/b1/dd/def55d8a80b0817f486f2712fc6243482c3264d373dc5ff75037b3aeb7ea/pyobjc_framework_vision-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:04296f0848cc8cdead66c76df6063720885cbdf24fdfd1900749a6e2297313db", size = 16782, upload-time = "2025-11-14T10:06:48.816Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-webkit"
+version = "12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/14/10/110a50e8e6670765d25190ca7f7bfeecc47ec4a8c018cb928f4f82c56e04/pyobjc_framework_webkit-12.1.tar.gz", hash = "sha256:97a54dd05ab5266bd4f614e41add517ae62cdd5a30328eabb06792474b37d82a", size = 284531, upload-time = "2025-11-14T10:23:40.287Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/e5/37/5082a0bbe12e48d4ffa53b0c0f09c77a4a6ffcfa119e26fa8dd77c08dc1c/pyobjc_framework_webkit-12.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:3db734877025614eaef4504fadc0fbbe1279f68686a6f106f2e614e89e0d1a9d", size = 49970, upload-time = "2025-11-14T10:07:01.413Z" },
+ { url = "https://files.pythonhosted.org/packages/db/67/64920c8d201a7fc27962f467c636c4e763b43845baba2e091a50a97a5d52/pyobjc_framework_webkit-12.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:af2c7197447638b92aafbe4847c063b6dd5e1ed83b44d3ce7e71e4c9b042ab5a", size = 50084, upload-time = "2025-11-14T10:07:05.868Z" },
+ { url = "https://files.pythonhosted.org/packages/7a/3d/80d36280164c69220ce99372f7736a028617c207e42cb587716009eecb88/pyobjc_framework_webkit-12.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:1da0c428c9d9891c93e0de51c9f272bfeb96d34356cdf3136cb4ad56ce32ec2d", size = 50096, upload-time = "2025-11-14T10:07:10.027Z" },
+ { url = "https://files.pythonhosted.org/packages/8a/7a/03c29c46866e266b0c705811c55c22625c349b0a80f5cf4776454b13dc4c/pyobjc_framework_webkit-12.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:1a29e334d5a7dd4a4f0b5647481b6ccf8a107b92e67b2b3c6b368c899f571965", size = 50572, upload-time = "2025-11-14T10:07:14.232Z" },
+]
+
+[[package]]
+name = "pyperclip"
+version = "1.11.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e8/52/d87eba7cb129b81563019d1679026e7a112ef76855d6159d24754dbd2a51/pyperclip-1.11.0.tar.gz", hash = "sha256:244035963e4428530d9e3a6101a1ef97209c6825edab1567beac148ccc1db1b6", size = 12185, upload-time = "2025-09-26T14:40:37.245Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/df/80/fc9d01d5ed37ba4c42ca2b55b4339ae6e200b456be3a1aaddf4a9fa99b8c/pyperclip-1.11.0-py3-none-any.whl", hash = "sha256:299403e9ff44581cb9ba2ffeed69c7aa96a008622ad0c46cb575ca75b5b84273", size = 11063, upload-time = "2025-09-26T14:40:36.069Z" },
+]
+
+[[package]]
+name = "pytest"
+version = "9.0.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "colorama", marker = "sys_platform == 'win32'" },
+ { name = "iniconfig" },
+ { name = "packaging" },
+ { name = "pluggy" },
+ { name = "pygments" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/d1/db/7ef3487e0fb0049ddb5ce41d3a49c235bf9ad299b6a25d5780a89f19230f/pytest-9.0.2.tar.gz", hash = "sha256:75186651a92bd89611d1d9fc20f0b4345fd827c41ccd5c299a868a05d70edf11", size = 1568901, upload-time = "2025-12-06T21:30:51.014Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/3b/ab/b3226f0bd7cdcf710fbede2b3548584366da3b19b5021e74f5bde2a8fa3f/pytest-9.0.2-py3-none-any.whl", hash = "sha256:711ffd45bf766d5264d487b917733b453d917afd2b0ad65223959f59089f875b", size = 374801, upload-time = "2025-12-06T21:30:49.154Z" },
+]
+
+[[package]]
+name = "pytest-asyncio"
+version = "1.3.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pytest" },
+ { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/90/2c/8af215c0f776415f3590cac4f9086ccefd6fd463befeae41cd4d3f193e5a/pytest_asyncio-1.3.0.tar.gz", hash = "sha256:d7f52f36d231b80ee124cd216ffb19369aa168fc10095013c6b014a34d3ee9e5", size = 50087, upload-time = "2025-11-10T16:07:47.256Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/e5/35/f8b19922b6a25bc0880171a2f1a003eaeb93657475193ab516fd87cac9da/pytest_asyncio-1.3.0-py3-none-any.whl", hash = "sha256:611e26147c7f77640e6d0a92a38ed17c3e9848063698d5c93d5aa7aa11cebff5", size = 15075, upload-time = "2025-11-10T16:07:45.537Z" },
+]
+
+[[package]]
+name = "python-xlib"
+version = "0.33"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "six" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/86/f5/8c0653e5bb54e0cbdfe27bf32d41f27bc4e12faa8742778c17f2a71be2c0/python-xlib-0.33.tar.gz", hash = "sha256:55af7906a2c75ce6cb280a584776080602444f75815a7aff4d287bb2d7018b32", size = 269068, upload-time = "2022-12-25T18:53:00.824Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/fc/b8/ff33610932e0ee81ae7f1269c890f697d56ff74b9f5b2ee5d9b7fa2c5355/python_xlib-0.33-py2.py3-none-any.whl", hash = "sha256:c3534038d42e0df2f1392a1b30a15a4ff5fdc2b86cfa94f072bf11b10a164398", size = 182185, upload-time = "2022-12-25T18:52:58.662Z" },
+]
+
+[[package]]
+name = "pywin32"
+version = "311"
+source = { registry = "https://pypi.org/simple" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/7c/af/449a6a91e5d6db51420875c54f6aff7c97a86a3b13a0b4f1a5c13b988de3/pywin32-311-cp311-cp311-win32.whl", hash = "sha256:184eb5e436dea364dcd3d2316d577d625c0351bf237c4e9a5fabbcfa5a58b151", size = 8697031, upload-time = "2025-07-14T20:13:13.266Z" },
+ { url = "https://files.pythonhosted.org/packages/51/8f/9bb81dd5bb77d22243d33c8397f09377056d5c687aa6d4042bea7fbf8364/pywin32-311-cp311-cp311-win_amd64.whl", hash = "sha256:3ce80b34b22b17ccbd937a6e78e7225d80c52f5ab9940fe0506a1a16f3dab503", size = 9508308, upload-time = "2025-07-14T20:13:15.147Z" },
+ { url = "https://files.pythonhosted.org/packages/44/7b/9c2ab54f74a138c491aba1b1cd0795ba61f144c711daea84a88b63dc0f6c/pywin32-311-cp311-cp311-win_arm64.whl", hash = "sha256:a733f1388e1a842abb67ffa8e7aad0e70ac519e09b0f6a784e65a136ec7cefd2", size = 8703930, upload-time = "2025-07-14T20:13:16.945Z" },
+ { url = "https://files.pythonhosted.org/packages/e7/ab/01ea1943d4eba0f850c3c61e78e8dd59757ff815ff3ccd0a84de5f541f42/pywin32-311-cp312-cp312-win32.whl", hash = "sha256:750ec6e621af2b948540032557b10a2d43b0cee2ae9758c54154d711cc852d31", size = 8706543, upload-time = "2025-07-14T20:13:20.765Z" },
+ { url = "https://files.pythonhosted.org/packages/d1/a8/a0e8d07d4d051ec7502cd58b291ec98dcc0c3fff027caad0470b72cfcc2f/pywin32-311-cp312-cp312-win_amd64.whl", hash = "sha256:b8c095edad5c211ff31c05223658e71bf7116daa0ecf3ad85f3201ea3190d067", size = 9495040, upload-time = "2025-07-14T20:13:22.543Z" },
+ { url = "https://files.pythonhosted.org/packages/ba/3a/2ae996277b4b50f17d61f0603efd8253cb2d79cc7ae159468007b586396d/pywin32-311-cp312-cp312-win_arm64.whl", hash = "sha256:e286f46a9a39c4a18b319c28f59b61de793654af2f395c102b4f819e584b5852", size = 8710102, upload-time = "2025-07-14T20:13:24.682Z" },
+ { url = "https://files.pythonhosted.org/packages/a5/be/3fd5de0979fcb3994bfee0d65ed8ca9506a8a1260651b86174f6a86f52b3/pywin32-311-cp313-cp313-win32.whl", hash = "sha256:f95ba5a847cba10dd8c4d8fefa9f2a6cf283b8b88ed6178fa8a6c1ab16054d0d", size = 8705700, upload-time = "2025-07-14T20:13:26.471Z" },
+ { url = "https://files.pythonhosted.org/packages/e3/28/e0a1909523c6890208295a29e05c2adb2126364e289826c0a8bc7297bd5c/pywin32-311-cp313-cp313-win_amd64.whl", hash = "sha256:718a38f7e5b058e76aee1c56ddd06908116d35147e133427e59a3983f703a20d", size = 9494700, upload-time = "2025-07-14T20:13:28.243Z" },
+ { url = "https://files.pythonhosted.org/packages/04/bf/90339ac0f55726dce7d794e6d79a18a91265bdf3aa70b6b9ca52f35e022a/pywin32-311-cp313-cp313-win_arm64.whl", hash = "sha256:7b4075d959648406202d92a2310cb990fea19b535c7f4a78d3f5e10b926eeb8a", size = 8709318, upload-time = "2025-07-14T20:13:30.348Z" },
+]
+
+[[package]]
+name = "pywinbox"
+version = "0.7"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "ewmhlib", marker = "sys_platform == 'linux'" },
+ { name = "pyobjc", marker = "sys_platform == 'darwin'" },
+ { name = "python-xlib", marker = "sys_platform == 'linux'" },
+ { name = "pywin32", marker = "sys_platform == 'win32'" },
+ { name = "typing-extensions" },
+]
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/b1/37/d59397221e15d2a7f38afaa4e8e6b8c244d818044f7daa0bdc5988df0a69/PyWinBox-0.7-py3-none-any.whl", hash = "sha256:8b2506a8dd7afa0a910b368762adfac885274132ef9151b0c81b0d2c6ffd6f83", size = 12274, upload-time = "2024-04-17T10:10:31.899Z" },
+]
+
+[[package]]
+name = "pywinctl"
+version = "0.4.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "ewmhlib", marker = "sys_platform == 'linux'" },
+ { name = "pymonctl" },
+ { name = "pyobjc", marker = "sys_platform == 'darwin'" },
+ { name = "python-xlib", marker = "sys_platform == 'linux'" },
+ { name = "pywin32", marker = "sys_platform == 'win32'" },
+ { name = "pywinbox" },
+ { name = "typing-extensions" },
+]
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/be/33/8e4f632210b28fc9e998a9ab990e7ed97ecd2800cc50038e3800e1d85dbe/PyWinCtl-0.4.1-py3-none-any.whl", hash = "sha256:4d875e22969e1c6239d8c73156193630aaab876366167b8d97716f956384b089", size = 63158, upload-time = "2024-09-23T08:33:39.881Z" },
+]
+
+[[package]]
+name = "referencing"
+version = "0.37.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "attrs" },
+ { name = "rpds-py" },
+ { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/22/f5/df4e9027acead3ecc63e50fe1e36aca1523e1719559c499951bb4b53188f/referencing-0.37.0.tar.gz", hash = "sha256:44aefc3142c5b842538163acb373e24cce6632bd54bdb01b21ad5863489f50d8", size = 78036, upload-time = "2025-10-13T15:30:48.871Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/2c/58/ca301544e1fa93ed4f80d724bf5b194f6e4b945841c5bfd555878eea9fcb/referencing-0.37.0-py3-none-any.whl", hash = "sha256:381329a9f99628c9069361716891d34ad94af76e461dcb0335825aecc7692231", size = 26766, upload-time = "2025-10-13T15:30:47.625Z" },
+]
+
+[[package]]
+name = "requests"
+version = "2.32.5"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "certifi" },
+ { name = "charset-normalizer" },
+ { name = "idna" },
+ { name = "urllib3" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c9/74/b3ff8e6c8446842c3f5c837e9c3dfcfe2018ea6ecef224c710c85ef728f4/requests-2.32.5.tar.gz", hash = "sha256:dbba0bac56e100853db0ea71b82b4dfd5fe2bf6d3754a8893c3af500cec7d7cf", size = 134517, upload-time = "2025-08-18T20:46:02.573Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/1e/db/4254e3eabe8020b458f1a747140d32277ec7a271daf1d235b70dc0b4e6e3/requests-2.32.5-py3-none-any.whl", hash = "sha256:2462f94637a34fd532264295e186976db0f5d453d1cdd31473c85a6a161affb6", size = 64738, upload-time = "2025-08-18T20:46:00.542Z" },
+]
+
+[[package]]
+name = "rpds-py"
+version = "0.30.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/20/af/3f2f423103f1113b36230496629986e0ef7e199d2aa8392452b484b38ced/rpds_py-0.30.0.tar.gz", hash = "sha256:dd8ff7cf90014af0c0f787eea34794ebf6415242ee1d6fa91eaba725cc441e84", size = 69469, upload-time = "2025-11-30T20:24:38.837Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/4d/6e/f964e88b3d2abee2a82c1ac8366da848fce1c6d834dc2132c3fda3970290/rpds_py-0.30.0-cp311-cp311-macosx_10_12_x86_64.whl", hash = "sha256:a2bffea6a4ca9f01b3f8e548302470306689684e61602aa3d141e34da06cf425", size = 370157, upload-time = "2025-11-30T20:21:53.789Z" },
+ { url = "https://files.pythonhosted.org/packages/94/ba/24e5ebb7c1c82e74c4e4f33b2112a5573ddc703915b13a073737b59b86e0/rpds_py-0.30.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:dc4f992dfe1e2bc3ebc7444f6c7051b4bc13cd8e33e43511e8ffd13bf407010d", size = 359676, upload-time = "2025-11-30T20:21:55.475Z" },
+ { url = "https://files.pythonhosted.org/packages/84/86/04dbba1b087227747d64d80c3b74df946b986c57af0a9f0c98726d4d7a3b/rpds_py-0.30.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:422c3cb9856d80b09d30d2eb255d0754b23e090034e1deb4083f8004bd0761e4", size = 389938, upload-time = "2025-11-30T20:21:57.079Z" },
+ { url = "https://files.pythonhosted.org/packages/42/bb/1463f0b1722b7f45431bdd468301991d1328b16cffe0b1c2918eba2c4eee/rpds_py-0.30.0-cp311-cp311-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:07ae8a593e1c3c6b82ca3292efbe73c30b61332fd612e05abee07c79359f292f", size = 402932, upload-time = "2025-11-30T20:21:58.47Z" },
+ { url = "https://files.pythonhosted.org/packages/99/ee/2520700a5c1f2d76631f948b0736cdf9b0acb25abd0ca8e889b5c62ac2e3/rpds_py-0.30.0-cp311-cp311-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:12f90dd7557b6bd57f40abe7747e81e0c0b119bef015ea7726e69fe550e394a4", size = 525830, upload-time = "2025-11-30T20:21:59.699Z" },
+ { url = "https://files.pythonhosted.org/packages/e0/ad/bd0331f740f5705cc555a5e17fdf334671262160270962e69a2bdef3bf76/rpds_py-0.30.0-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:99b47d6ad9a6da00bec6aabe5a6279ecd3c06a329d4aa4771034a21e335c3a97", size = 412033, upload-time = "2025-11-30T20:22:00.991Z" },
+ { url = "https://files.pythonhosted.org/packages/f8/1e/372195d326549bb51f0ba0f2ecb9874579906b97e08880e7a65c3bef1a99/rpds_py-0.30.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:33f559f3104504506a44bb666b93a33f5d33133765b0c216a5bf2f1e1503af89", size = 390828, upload-time = "2025-11-30T20:22:02.723Z" },
+ { url = "https://files.pythonhosted.org/packages/ab/2b/d88bb33294e3e0c76bc8f351a3721212713629ffca1700fa94979cb3eae8/rpds_py-0.30.0-cp311-cp311-manylinux_2_31_riscv64.whl", hash = "sha256:946fe926af6e44f3697abbc305ea168c2c31d3e3ef1058cf68f379bf0335a78d", size = 404683, upload-time = "2025-11-30T20:22:04.367Z" },
+ { url = "https://files.pythonhosted.org/packages/50/32/c759a8d42bcb5289c1fac697cd92f6fe01a018dd937e62ae77e0e7f15702/rpds_py-0.30.0-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:495aeca4b93d465efde585977365187149e75383ad2684f81519f504f5c13038", size = 421583, upload-time = "2025-11-30T20:22:05.814Z" },
+ { url = "https://files.pythonhosted.org/packages/2b/81/e729761dbd55ddf5d84ec4ff1f47857f4374b0f19bdabfcf929164da3e24/rpds_py-0.30.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:d9a0ca5da0386dee0655b4ccdf46119df60e0f10da268d04fe7cc87886872ba7", size = 572496, upload-time = "2025-11-30T20:22:07.713Z" },
+ { url = "https://files.pythonhosted.org/packages/14/f6/69066a924c3557c9c30baa6ec3a0aa07526305684c6f86c696b08860726c/rpds_py-0.30.0-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:8d6d1cc13664ec13c1b84241204ff3b12f9bb82464b8ad6e7a5d3486975c2eed", size = 598669, upload-time = "2025-11-30T20:22:09.312Z" },
+ { url = "https://files.pythonhosted.org/packages/5f/48/905896b1eb8a05630d20333d1d8ffd162394127b74ce0b0784ae04498d32/rpds_py-0.30.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:3896fa1be39912cf0757753826bc8bdc8ca331a28a7c4ae46b7a21280b06bb85", size = 561011, upload-time = "2025-11-30T20:22:11.309Z" },
+ { url = "https://files.pythonhosted.org/packages/22/16/cd3027c7e279d22e5eb431dd3c0fbc677bed58797fe7581e148f3f68818b/rpds_py-0.30.0-cp311-cp311-win32.whl", hash = "sha256:55f66022632205940f1827effeff17c4fa7ae1953d2b74a8581baaefb7d16f8c", size = 221406, upload-time = "2025-11-30T20:22:13.101Z" },
+ { url = "https://files.pythonhosted.org/packages/fa/5b/e7b7aa136f28462b344e652ee010d4de26ee9fd16f1bfd5811f5153ccf89/rpds_py-0.30.0-cp311-cp311-win_amd64.whl", hash = "sha256:a51033ff701fca756439d641c0ad09a41d9242fa69121c7d8769604a0a629825", size = 236024, upload-time = "2025-11-30T20:22:14.853Z" },
+ { url = "https://files.pythonhosted.org/packages/14/a6/364bba985e4c13658edb156640608f2c9e1d3ea3c81b27aa9d889fff0e31/rpds_py-0.30.0-cp311-cp311-win_arm64.whl", hash = "sha256:47b0ef6231c58f506ef0b74d44e330405caa8428e770fec25329ed2cb971a229", size = 229069, upload-time = "2025-11-30T20:22:16.577Z" },
+ { url = "https://files.pythonhosted.org/packages/03/e7/98a2f4ac921d82f33e03f3835f5bf3a4a40aa1bfdc57975e74a97b2b4bdd/rpds_py-0.30.0-cp312-cp312-macosx_10_12_x86_64.whl", hash = "sha256:a161f20d9a43006833cd7068375a94d035714d73a172b681d8881820600abfad", size = 375086, upload-time = "2025-11-30T20:22:17.93Z" },
+ { url = "https://files.pythonhosted.org/packages/4d/a1/bca7fd3d452b272e13335db8d6b0b3ecde0f90ad6f16f3328c6fb150c889/rpds_py-0.30.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:6abc8880d9d036ecaafe709079969f56e876fcf107f7a8e9920ba6d5a3878d05", size = 359053, upload-time = "2025-11-30T20:22:19.297Z" },
+ { url = "https://files.pythonhosted.org/packages/65/1c/ae157e83a6357eceff62ba7e52113e3ec4834a84cfe07fa4b0757a7d105f/rpds_py-0.30.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ca28829ae5f5d569bb62a79512c842a03a12576375d5ece7d2cadf8abe96ec28", size = 390763, upload-time = "2025-11-30T20:22:21.661Z" },
+ { url = "https://files.pythonhosted.org/packages/d4/36/eb2eb8515e2ad24c0bd43c3ee9cd74c33f7ca6430755ccdb240fd3144c44/rpds_py-0.30.0-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:a1010ed9524c73b94d15919ca4d41d8780980e1765babf85f9a2f90d247153dd", size = 408951, upload-time = "2025-11-30T20:22:23.408Z" },
+ { url = "https://files.pythonhosted.org/packages/d6/65/ad8dc1784a331fabbd740ef6f71ce2198c7ed0890dab595adb9ea2d775a1/rpds_py-0.30.0-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:f8d1736cfb49381ba528cd5baa46f82fdc65c06e843dab24dd70b63d09121b3f", size = 514622, upload-time = "2025-11-30T20:22:25.16Z" },
+ { url = "https://files.pythonhosted.org/packages/63/8e/0cfa7ae158e15e143fe03993b5bcd743a59f541f5952e1546b1ac1b5fd45/rpds_py-0.30.0-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:d948b135c4693daff7bc2dcfc4ec57237a29bd37e60c2fabf5aff2bbacf3e2f1", size = 414492, upload-time = "2025-11-30T20:22:26.505Z" },
+ { url = "https://files.pythonhosted.org/packages/60/1b/6f8f29f3f995c7ffdde46a626ddccd7c63aefc0efae881dc13b6e5d5bb16/rpds_py-0.30.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:47f236970bccb2233267d89173d3ad2703cd36a0e2a6e92d0560d333871a3d23", size = 394080, upload-time = "2025-11-30T20:22:27.934Z" },
+ { url = "https://files.pythonhosted.org/packages/6d/d5/a266341051a7a3ca2f4b750a3aa4abc986378431fc2da508c5034d081b70/rpds_py-0.30.0-cp312-cp312-manylinux_2_31_riscv64.whl", hash = "sha256:2e6ecb5a5bcacf59c3f912155044479af1d0b6681280048b338b28e364aca1f6", size = 408680, upload-time = "2025-11-30T20:22:29.341Z" },
+ { url = "https://files.pythonhosted.org/packages/10/3b/71b725851df9ab7a7a4e33cf36d241933da66040d195a84781f49c50490c/rpds_py-0.30.0-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:a8fa71a2e078c527c3e9dc9fc5a98c9db40bcc8a92b4e8858e36d329f8684b51", size = 423589, upload-time = "2025-11-30T20:22:31.469Z" },
+ { url = "https://files.pythonhosted.org/packages/00/2b/e59e58c544dc9bd8bd8384ecdb8ea91f6727f0e37a7131baeff8d6f51661/rpds_py-0.30.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:73c67f2db7bc334e518d097c6d1e6fed021bbc9b7d678d6cc433478365d1d5f5", size = 573289, upload-time = "2025-11-30T20:22:32.997Z" },
+ { url = "https://files.pythonhosted.org/packages/da/3e/a18e6f5b460893172a7d6a680e86d3b6bc87a54c1f0b03446a3c8c7b588f/rpds_py-0.30.0-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:5ba103fb455be00f3b1c2076c9d4264bfcb037c976167a6047ed82f23153f02e", size = 599737, upload-time = "2025-11-30T20:22:34.419Z" },
+ { url = "https://files.pythonhosted.org/packages/5c/e2/714694e4b87b85a18e2c243614974413c60aa107fd815b8cbc42b873d1d7/rpds_py-0.30.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:7cee9c752c0364588353e627da8a7e808a66873672bcb5f52890c33fd965b394", size = 563120, upload-time = "2025-11-30T20:22:35.903Z" },
+ { url = "https://files.pythonhosted.org/packages/6f/ab/d5d5e3bcedb0a77f4f613706b750e50a5a3ba1c15ccd3665ecc636c968fd/rpds_py-0.30.0-cp312-cp312-win32.whl", hash = "sha256:1ab5b83dbcf55acc8b08fc62b796ef672c457b17dbd7820a11d6c52c06839bdf", size = 223782, upload-time = "2025-11-30T20:22:37.271Z" },
+ { url = "https://files.pythonhosted.org/packages/39/3b/f786af9957306fdc38a74cef405b7b93180f481fb48453a114bb6465744a/rpds_py-0.30.0-cp312-cp312-win_amd64.whl", hash = "sha256:a090322ca841abd453d43456ac34db46e8b05fd9b3b4ac0c78bcde8b089f959b", size = 240463, upload-time = "2025-11-30T20:22:39.021Z" },
+ { url = "https://files.pythonhosted.org/packages/f3/d2/b91dc748126c1559042cfe41990deb92c4ee3e2b415f6b5234969ffaf0cc/rpds_py-0.30.0-cp312-cp312-win_arm64.whl", hash = "sha256:669b1805bd639dd2989b281be2cfd951c6121b65e729d9b843e9639ef1fd555e", size = 230868, upload-time = "2025-11-30T20:22:40.493Z" },
+ { url = "https://files.pythonhosted.org/packages/ed/dc/d61221eb88ff410de3c49143407f6f3147acf2538c86f2ab7ce65ae7d5f9/rpds_py-0.30.0-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:f83424d738204d9770830d35290ff3273fbb02b41f919870479fab14b9d303b2", size = 374887, upload-time = "2025-11-30T20:22:41.812Z" },
+ { url = "https://files.pythonhosted.org/packages/fd/32/55fb50ae104061dbc564ef15cc43c013dc4a9f4527a1f4d99baddf56fe5f/rpds_py-0.30.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:e7536cd91353c5273434b4e003cbda89034d67e7710eab8761fd918ec6c69cf8", size = 358904, upload-time = "2025-11-30T20:22:43.479Z" },
+ { url = "https://files.pythonhosted.org/packages/58/70/faed8186300e3b9bdd138d0273109784eea2396c68458ed580f885dfe7ad/rpds_py-0.30.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:2771c6c15973347f50fece41fc447c054b7ac2ae0502388ce3b6738cd366e3d4", size = 389945, upload-time = "2025-11-30T20:22:44.819Z" },
+ { url = "https://files.pythonhosted.org/packages/bd/a8/073cac3ed2c6387df38f71296d002ab43496a96b92c823e76f46b8af0543/rpds_py-0.30.0-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:0a59119fc6e3f460315fe9d08149f8102aa322299deaa5cab5b40092345c2136", size = 407783, upload-time = "2025-11-30T20:22:46.103Z" },
+ { url = "https://files.pythonhosted.org/packages/77/57/5999eb8c58671f1c11eba084115e77a8899d6e694d2a18f69f0ba471ec8b/rpds_py-0.30.0-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:76fec018282b4ead0364022e3c54b60bf368b9d926877957a8624b58419169b7", size = 515021, upload-time = "2025-11-30T20:22:47.458Z" },
+ { url = "https://files.pythonhosted.org/packages/e0/af/5ab4833eadc36c0a8ed2bc5c0de0493c04f6c06de223170bd0798ff98ced/rpds_py-0.30.0-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:692bef75a5525db97318e8cd061542b5a79812d711ea03dbc1f6f8dbb0c5f0d2", size = 414589, upload-time = "2025-11-30T20:22:48.872Z" },
+ { url = "https://files.pythonhosted.org/packages/b7/de/f7192e12b21b9e9a68a6d0f249b4af3fdcdff8418be0767a627564afa1f1/rpds_py-0.30.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:9027da1ce107104c50c81383cae773ef5c24d296dd11c99e2629dbd7967a20c6", size = 394025, upload-time = "2025-11-30T20:22:50.196Z" },
+ { url = "https://files.pythonhosted.org/packages/91/c4/fc70cd0249496493500e7cc2de87504f5aa6509de1e88623431fec76d4b6/rpds_py-0.30.0-cp313-cp313-manylinux_2_31_riscv64.whl", hash = "sha256:9cf69cdda1f5968a30a359aba2f7f9aa648a9ce4b580d6826437f2b291cfc86e", size = 408895, upload-time = "2025-11-30T20:22:51.87Z" },
+ { url = "https://files.pythonhosted.org/packages/58/95/d9275b05ab96556fefff73a385813eb66032e4c99f411d0795372d9abcea/rpds_py-0.30.0-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:a4796a717bf12b9da9d3ad002519a86063dcac8988b030e405704ef7d74d2d9d", size = 422799, upload-time = "2025-11-30T20:22:53.341Z" },
+ { url = "https://files.pythonhosted.org/packages/06/c1/3088fc04b6624eb12a57eb814f0d4997a44b0d208d6cace713033ff1a6ba/rpds_py-0.30.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:5d4c2aa7c50ad4728a094ebd5eb46c452e9cb7edbfdb18f9e1221f597a73e1e7", size = 572731, upload-time = "2025-11-30T20:22:54.778Z" },
+ { url = "https://files.pythonhosted.org/packages/d8/42/c612a833183b39774e8ac8fecae81263a68b9583ee343db33ab571a7ce55/rpds_py-0.30.0-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:ba81a9203d07805435eb06f536d95a266c21e5b2dfbf6517748ca40c98d19e31", size = 599027, upload-time = "2025-11-30T20:22:56.212Z" },
+ { url = "https://files.pythonhosted.org/packages/5f/60/525a50f45b01d70005403ae0e25f43c0384369ad24ffe46e8d9068b50086/rpds_py-0.30.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:945dccface01af02675628334f7cf49c2af4c1c904748efc5cf7bbdf0b579f95", size = 563020, upload-time = "2025-11-30T20:22:58.2Z" },
+ { url = "https://files.pythonhosted.org/packages/0b/5d/47c4655e9bcd5ca907148535c10e7d489044243cc9941c16ed7cd53be91d/rpds_py-0.30.0-cp313-cp313-win32.whl", hash = "sha256:b40fb160a2db369a194cb27943582b38f79fc4887291417685f3ad693c5a1d5d", size = 223139, upload-time = "2025-11-30T20:23:00.209Z" },
+ { url = "https://files.pythonhosted.org/packages/f2/e1/485132437d20aa4d3e1d8b3fb5a5e65aa8139f1e097080c2a8443201742c/rpds_py-0.30.0-cp313-cp313-win_amd64.whl", hash = "sha256:806f36b1b605e2d6a72716f321f20036b9489d29c51c91f4dd29a3e3afb73b15", size = 240224, upload-time = "2025-11-30T20:23:02.008Z" },
+ { url = "https://files.pythonhosted.org/packages/24/95/ffd128ed1146a153d928617b0ef673960130be0009c77d8fbf0abe306713/rpds_py-0.30.0-cp313-cp313-win_arm64.whl", hash = "sha256:d96c2086587c7c30d44f31f42eae4eac89b60dabbac18c7669be3700f13c3ce1", size = 230645, upload-time = "2025-11-30T20:23:03.43Z" },
+ { url = "https://files.pythonhosted.org/packages/ff/1b/b10de890a0def2a319a2626334a7f0ae388215eb60914dbac8a3bae54435/rpds_py-0.30.0-cp313-cp313t-macosx_10_12_x86_64.whl", hash = "sha256:eb0b93f2e5c2189ee831ee43f156ed34e2a89a78a66b98cadad955972548be5a", size = 364443, upload-time = "2025-11-30T20:23:04.878Z" },
+ { url = "https://files.pythonhosted.org/packages/0d/bf/27e39f5971dc4f305a4fb9c672ca06f290f7c4e261c568f3dea16a410d47/rpds_py-0.30.0-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:922e10f31f303c7c920da8981051ff6d8c1a56207dbdf330d9047f6d30b70e5e", size = 353375, upload-time = "2025-11-30T20:23:06.342Z" },
+ { url = "https://files.pythonhosted.org/packages/40/58/442ada3bba6e8e6615fc00483135c14a7538d2ffac30e2d933ccf6852232/rpds_py-0.30.0-cp313-cp313t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:cdc62c8286ba9bf7f47befdcea13ea0e26bf294bda99758fd90535cbaf408000", size = 383850, upload-time = "2025-11-30T20:23:07.825Z" },
+ { url = "https://files.pythonhosted.org/packages/14/14/f59b0127409a33c6ef6f5c1ebd5ad8e32d7861c9c7adfa9a624fc3889f6c/rpds_py-0.30.0-cp313-cp313t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:47f9a91efc418b54fb8190a6b4aa7813a23fb79c51f4bb84e418f5476c38b8db", size = 392812, upload-time = "2025-11-30T20:23:09.228Z" },
+ { url = "https://files.pythonhosted.org/packages/b3/66/e0be3e162ac299b3a22527e8913767d869e6cc75c46bd844aa43fb81ab62/rpds_py-0.30.0-cp313-cp313t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:1f3587eb9b17f3789ad50824084fa6f81921bbf9a795826570bda82cb3ed91f2", size = 517841, upload-time = "2025-11-30T20:23:11.186Z" },
+ { url = "https://files.pythonhosted.org/packages/3d/55/fa3b9cf31d0c963ecf1ba777f7cf4b2a2c976795ac430d24a1f43d25a6ba/rpds_py-0.30.0-cp313-cp313t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:39c02563fc592411c2c61d26b6c5fe1e51eaa44a75aa2c8735ca88b0d9599daa", size = 408149, upload-time = "2025-11-30T20:23:12.864Z" },
+ { url = "https://files.pythonhosted.org/packages/60/ca/780cf3b1a32b18c0f05c441958d3758f02544f1d613abf9488cd78876378/rpds_py-0.30.0-cp313-cp313t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:51a1234d8febafdfd33a42d97da7a43f5dcb120c1060e352a3fbc0c6d36e2083", size = 383843, upload-time = "2025-11-30T20:23:14.638Z" },
+ { url = "https://files.pythonhosted.org/packages/82/86/d5f2e04f2aa6247c613da0c1dd87fcd08fa17107e858193566048a1e2f0a/rpds_py-0.30.0-cp313-cp313t-manylinux_2_31_riscv64.whl", hash = "sha256:eb2c4071ab598733724c08221091e8d80e89064cd472819285a9ab0f24bcedb9", size = 396507, upload-time = "2025-11-30T20:23:16.105Z" },
+ { url = "https://files.pythonhosted.org/packages/4b/9a/453255d2f769fe44e07ea9785c8347edaf867f7026872e76c1ad9f7bed92/rpds_py-0.30.0-cp313-cp313t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:6bdfdb946967d816e6adf9a3d8201bfad269c67efe6cefd7093ef959683c8de0", size = 414949, upload-time = "2025-11-30T20:23:17.539Z" },
+ { url = "https://files.pythonhosted.org/packages/a3/31/622a86cdc0c45d6df0e9ccb6becdba5074735e7033c20e401a6d9d0e2ca0/rpds_py-0.30.0-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:c77afbd5f5250bf27bf516c7c4a016813eb2d3e116139aed0096940c5982da94", size = 565790, upload-time = "2025-11-30T20:23:19.029Z" },
+ { url = "https://files.pythonhosted.org/packages/1c/5d/15bbf0fb4a3f58a3b1c67855ec1efcc4ceaef4e86644665fff03e1b66d8d/rpds_py-0.30.0-cp313-cp313t-musllinux_1_2_i686.whl", hash = "sha256:61046904275472a76c8c90c9ccee9013d70a6d0f73eecefd38c1ae7c39045a08", size = 590217, upload-time = "2025-11-30T20:23:20.885Z" },
+ { url = "https://files.pythonhosted.org/packages/6d/61/21b8c41f68e60c8cc3b2e25644f0e3681926020f11d06ab0b78e3c6bbff1/rpds_py-0.30.0-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:4c5f36a861bc4b7da6516dbdf302c55313afa09b81931e8280361a4f6c9a2d27", size = 555806, upload-time = "2025-11-30T20:23:22.488Z" },
+ { url = "https://files.pythonhosted.org/packages/f9/39/7e067bb06c31de48de3eb200f9fc7c58982a4d3db44b07e73963e10d3be9/rpds_py-0.30.0-cp313-cp313t-win32.whl", hash = "sha256:3d4a69de7a3e50ffc214ae16d79d8fbb0922972da0356dcf4d0fdca2878559c6", size = 211341, upload-time = "2025-11-30T20:23:24.449Z" },
+ { url = "https://files.pythonhosted.org/packages/0a/4d/222ef0b46443cf4cf46764d9c630f3fe4abaa7245be9417e56e9f52b8f65/rpds_py-0.30.0-cp313-cp313t-win_amd64.whl", hash = "sha256:f14fc5df50a716f7ece6a80b6c78bb35ea2ca47c499e422aa4463455dd96d56d", size = 225768, upload-time = "2025-11-30T20:23:25.908Z" },
+ { url = "https://files.pythonhosted.org/packages/69/71/3f34339ee70521864411f8b6992e7ab13ac30d8e4e3309e07c7361767d91/rpds_py-0.30.0-pp311-pypy311_pp73-macosx_10_12_x86_64.whl", hash = "sha256:c2262bdba0ad4fc6fb5545660673925c2d2a5d9e2e0fb603aad545427be0fc58", size = 372292, upload-time = "2025-11-30T20:24:16.537Z" },
+ { url = "https://files.pythonhosted.org/packages/57/09/f183df9b8f2d66720d2ef71075c59f7e1b336bec7ee4c48f0a2b06857653/rpds_py-0.30.0-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:ee6af14263f25eedc3bb918a3c04245106a42dfd4f5c2285ea6f997b1fc3f89a", size = 362128, upload-time = "2025-11-30T20:24:18.086Z" },
+ { url = "https://files.pythonhosted.org/packages/7a/68/5c2594e937253457342e078f0cc1ded3dd7b2ad59afdbf2d354869110a02/rpds_py-0.30.0-pp311-pypy311_pp73-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:3adbb8179ce342d235c31ab8ec511e66c73faa27a47e076ccc92421add53e2bb", size = 391542, upload-time = "2025-11-30T20:24:20.092Z" },
+ { url = "https://files.pythonhosted.org/packages/49/5c/31ef1afd70b4b4fbdb2800249f34c57c64beb687495b10aec0365f53dfc4/rpds_py-0.30.0-pp311-pypy311_pp73-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:250fa00e9543ac9b97ac258bd37367ff5256666122c2d0f2bc97577c60a1818c", size = 404004, upload-time = "2025-11-30T20:24:22.231Z" },
+ { url = "https://files.pythonhosted.org/packages/e3/63/0cfbea38d05756f3440ce6534d51a491d26176ac045e2707adc99bb6e60a/rpds_py-0.30.0-pp311-pypy311_pp73-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:9854cf4f488b3d57b9aaeb105f06d78e5529d3145b1e4a41750167e8c213c6d3", size = 527063, upload-time = "2025-11-30T20:24:24.302Z" },
+ { url = "https://files.pythonhosted.org/packages/42/e6/01e1f72a2456678b0f618fc9a1a13f882061690893c192fcad9f2926553a/rpds_py-0.30.0-pp311-pypy311_pp73-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:993914b8e560023bc0a8bf742c5f303551992dcb85e247b1e5c7f4a7d145bda5", size = 413099, upload-time = "2025-11-30T20:24:25.916Z" },
+ { url = "https://files.pythonhosted.org/packages/b8/25/8df56677f209003dcbb180765520c544525e3ef21ea72279c98b9aa7c7fb/rpds_py-0.30.0-pp311-pypy311_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:58edca431fb9b29950807e301826586e5bbf24163677732429770a697ffe6738", size = 392177, upload-time = "2025-11-30T20:24:27.834Z" },
+ { url = "https://files.pythonhosted.org/packages/4a/b4/0a771378c5f16f8115f796d1f437950158679bcd2a7c68cf251cfb00ed5b/rpds_py-0.30.0-pp311-pypy311_pp73-manylinux_2_31_riscv64.whl", hash = "sha256:dea5b552272a944763b34394d04577cf0f9bd013207bc32323b5a89a53cf9c2f", size = 406015, upload-time = "2025-11-30T20:24:29.457Z" },
+ { url = "https://files.pythonhosted.org/packages/36/d8/456dbba0af75049dc6f63ff295a2f92766b9d521fa00de67a2bd6427d57a/rpds_py-0.30.0-pp311-pypy311_pp73-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:ba3af48635eb83d03f6c9735dfb21785303e73d22ad03d489e88adae6eab8877", size = 423736, upload-time = "2025-11-30T20:24:31.22Z" },
+ { url = "https://files.pythonhosted.org/packages/13/64/b4d76f227d5c45a7e0b796c674fd81b0a6c4fbd48dc29271857d8219571c/rpds_py-0.30.0-pp311-pypy311_pp73-musllinux_1_2_aarch64.whl", hash = "sha256:dff13836529b921e22f15cb099751209a60009731a68519630a24d61f0b1b30a", size = 573981, upload-time = "2025-11-30T20:24:32.934Z" },
+ { url = "https://files.pythonhosted.org/packages/20/91/092bacadeda3edf92bf743cc96a7be133e13a39cdbfd7b5082e7ab638406/rpds_py-0.30.0-pp311-pypy311_pp73-musllinux_1_2_i686.whl", hash = "sha256:1b151685b23929ab7beec71080a8889d4d6d9fa9a983d213f07121205d48e2c4", size = 599782, upload-time = "2025-11-30T20:24:35.169Z" },
+ { url = "https://files.pythonhosted.org/packages/d1/b7/b95708304cd49b7b6f82fdd039f1748b66ec2b21d6a45180910802f1abf1/rpds_py-0.30.0-pp311-pypy311_pp73-musllinux_1_2_x86_64.whl", hash = "sha256:ac37f9f516c51e5753f27dfdef11a88330f04de2d564be3991384b2f3535d02e", size = 562191, upload-time = "2025-11-30T20:24:36.853Z" },
+]
+
+[[package]]
+name = "ruff"
+version = "0.15.5"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/77/9b/840e0039e65fcf12758adf684d2289024d6140cde9268cc59887dc55189c/ruff-0.15.5.tar.gz", hash = "sha256:7c3601d3b6d76dce18c5c824fc8d06f4eef33d6df0c21ec7799510cde0f159a2", size = 4574214, upload-time = "2026-03-05T20:06:34.946Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/47/20/5369c3ce21588c708bcbe517a8fbe1a8dfdb5dfd5137e14790b1da71612c/ruff-0.15.5-py3-none-linux_armv6l.whl", hash = "sha256:4ae44c42281f42e3b06b988e442d344a5b9b72450ff3c892e30d11b29a96a57c", size = 10478185, upload-time = "2026-03-05T20:06:29.093Z" },
+ { url = "https://files.pythonhosted.org/packages/44/ed/e81dd668547da281e5dce710cf0bc60193f8d3d43833e8241d006720e42b/ruff-0.15.5-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:6edd3792d408ebcf61adabc01822da687579a1a023f297618ac27a5b51ef0080", size = 10859201, upload-time = "2026-03-05T20:06:32.632Z" },
+ { url = "https://files.pythonhosted.org/packages/c4/8f/533075f00aaf19b07c5cd6aa6e5d89424b06b3b3f4583bfa9c640a079059/ruff-0.15.5-py3-none-macosx_11_0_arm64.whl", hash = "sha256:89f463f7c8205a9f8dea9d658d59eff49db05f88f89cc3047fb1a02d9f344010", size = 10184752, upload-time = "2026-03-05T20:06:40.312Z" },
+ { url = "https://files.pythonhosted.org/packages/66/0e/ba49e2c3fa0395b3152bad634c7432f7edfc509c133b8f4529053ff024fb/ruff-0.15.5-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ba786a8295c6574c1116704cf0b9e6563de3432ac888d8f83685654fe528fd65", size = 10534857, upload-time = "2026-03-05T20:06:19.581Z" },
+ { url = "https://files.pythonhosted.org/packages/59/71/39234440f27a226475a0659561adb0d784b4d247dfe7f43ffc12dd02e288/ruff-0.15.5-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:fd4b801e57955fe9f02b31d20375ab3a5c4415f2e5105b79fb94cf2642c91440", size = 10309120, upload-time = "2026-03-05T20:06:00.435Z" },
+ { url = "https://files.pythonhosted.org/packages/f5/87/4140aa86a93df032156982b726f4952aaec4a883bb98cb6ef73c347da253/ruff-0.15.5-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:391f7c73388f3d8c11b794dbbc2959a5b5afe66642c142a6effa90b45f6f5204", size = 11047428, upload-time = "2026-03-05T20:05:51.867Z" },
+ { url = "https://files.pythonhosted.org/packages/5a/f7/4953e7e3287676f78fbe85e3a0ca414c5ca81237b7575bdadc00229ac240/ruff-0.15.5-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:8dc18f30302e379fe1e998548b0f5e9f4dff907f52f73ad6da419ea9c19d66c8", size = 11914251, upload-time = "2026-03-05T20:06:22.887Z" },
+ { url = "https://files.pythonhosted.org/packages/77/46/0f7c865c10cf896ccf5a939c3e84e1cfaeed608ff5249584799a74d33835/ruff-0.15.5-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:1cc6e7f90087e2d27f98dc34ed1b3ab7c8f0d273cc5431415454e22c0bd2a681", size = 11333801, upload-time = "2026-03-05T20:05:57.168Z" },
+ { url = "https://files.pythonhosted.org/packages/d3/01/a10fe54b653061585e655f5286c2662ebddb68831ed3eaebfb0eb08c0a16/ruff-0.15.5-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:c1cb7169f53c1ddb06e71a9aebd7e98fc0fea936b39afb36d8e86d36ecc2636a", size = 11206821, upload-time = "2026-03-05T20:06:03.441Z" },
+ { url = "https://files.pythonhosted.org/packages/7a/0d/2132ceaf20c5e8699aa83da2706ecb5c5dcdf78b453f77edca7fb70f8a93/ruff-0.15.5-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:9b037924500a31ee17389b5c8c4d88874cc6ea8e42f12e9c61a3d754ff72f1ca", size = 11133326, upload-time = "2026-03-05T20:06:25.655Z" },
+ { url = "https://files.pythonhosted.org/packages/72/cb/2e5259a7eb2a0f87c08c0fe5bf5825a1e4b90883a52685524596bfc93072/ruff-0.15.5-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:65bb414e5b4eadd95a8c1e4804f6772bbe8995889f203a01f77ddf2d790929dd", size = 10510820, upload-time = "2026-03-05T20:06:37.79Z" },
+ { url = "https://files.pythonhosted.org/packages/ff/20/b67ce78f9e6c59ffbdb5b4503d0090e749b5f2d31b599b554698a80d861c/ruff-0.15.5-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:d20aa469ae3b57033519c559e9bc9cd9e782842e39be05b50e852c7c981fa01d", size = 10302395, upload-time = "2026-03-05T20:05:54.504Z" },
+ { url = "https://files.pythonhosted.org/packages/5f/e5/719f1acccd31b720d477751558ed74e9c88134adcc377e5e886af89d3072/ruff-0.15.5-py3-none-musllinux_1_2_i686.whl", hash = "sha256:15388dd28c9161cdb8eda68993533acc870aa4e646a0a277aa166de9ad5a8752", size = 10754069, upload-time = "2026-03-05T20:06:06.422Z" },
+ { url = "https://files.pythonhosted.org/packages/c3/9c/d1db14469e32d98f3ca27079dbd30b7b44dbb5317d06ab36718dee3baf03/ruff-0.15.5-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:b30da330cbd03bed0c21420b6b953158f60c74c54c5f4c1dabbdf3a57bf355d2", size = 11304315, upload-time = "2026-03-05T20:06:10.867Z" },
+ { url = "https://files.pythonhosted.org/packages/28/3a/950367aee7c69027f4f422059227b290ed780366b6aecee5de5039d50fa8/ruff-0.15.5-py3-none-win32.whl", hash = "sha256:732e5ee1f98ba5b3679029989a06ca39a950cced52143a0ea82a2102cb592b74", size = 10551676, upload-time = "2026-03-05T20:06:13.705Z" },
+ { url = "https://files.pythonhosted.org/packages/b8/00/bf077a505b4e649bdd3c47ff8ec967735ce2544c8e4a43aba42ee9bf935d/ruff-0.15.5-py3-none-win_amd64.whl", hash = "sha256:821d41c5fa9e19117616c35eaa3f4b75046ec76c65e7ae20a333e9a8696bc7fe", size = 11678972, upload-time = "2026-03-05T20:06:45.379Z" },
+ { url = "https://files.pythonhosted.org/packages/fe/4e/cd76eca6db6115604b7626668e891c9dd03330384082e33662fb0f113614/ruff-0.15.5-py3-none-win_arm64.whl", hash = "sha256:b498d1c60d2fe5c10c45ec3f698901065772730b411f164ae270bb6bfcc4740b", size = 10965572, upload-time = "2026-03-05T20:06:16.984Z" },
+]
+
+[[package]]
+name = "six"
+version = "1.17.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/94/e7/b2c673351809dca68a0e064b6af791aa332cf192da575fd474ed7d6f16a2/six-1.17.0.tar.gz", hash = "sha256:ff70335d468e7eb6ec65b95b99d3a2836546063f63acc5171de367e834932a81", size = 34031, upload-time = "2024-12-04T17:35:28.174Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/b7/ce/149a00dd41f10bc29e5921b496af8b574d8413afcd5e30dfa0ed46c2cc5e/six-1.17.0-py2.py3-none-any.whl", hash = "sha256:4721f391ed90541fddacab5acf947aa0d3dc7d27b2e1e8eda2be8970586c3274", size = 11050, upload-time = "2024-12-04T17:35:26.475Z" },
+]
+
+[[package]]
+name = "twisted"
+version = "25.5.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "attrs" },
+ { name = "automat" },
+ { name = "constantly" },
+ { name = "hyperlink" },
+ { name = "incremental" },
+ { name = "typing-extensions" },
+ { name = "zope-interface" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/13/0f/82716ed849bf7ea4984c21385597c949944f0f9b428b5710f79d0afc084d/twisted-25.5.0.tar.gz", hash = "sha256:1deb272358cb6be1e3e8fc6f9c8b36f78eb0fa7c2233d2dbe11ec6fee04ea316", size = 3545725, upload-time = "2025-06-07T09:52:24.858Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/eb/66/ab7efd8941f0bc7b2bd555b0f0471bff77df4c88e0cc31120c82737fec77/twisted-25.5.0-py3-none-any.whl", hash = "sha256:8559f654d01a54a8c3efe66d533d43f383531ebf8d81d9f9ab4769d91ca15df7", size = 3204767, upload-time = "2025-06-07T09:52:21.428Z" },
+]
+
+[[package]]
+name = "typing-extensions"
+version = "4.15.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/72/94/1a15dd82efb362ac84269196e94cf00f187f7ed21c242792a923cdb1c61f/typing_extensions-4.15.0.tar.gz", hash = "sha256:0cea48d173cc12fa28ecabc3b837ea3cf6f38c6d1136f85cbaaf598984861466", size = 109391, upload-time = "2025-08-25T13:49:26.313Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/18/67/36e9267722cc04a6b9f15c7f3441c2363321a3ea07da7ae0c0707beb2a9c/typing_extensions-4.15.0-py3-none-any.whl", hash = "sha256:f0fa19c6845758ab08074a0cfa8b7aecb71c999ca73d62883bc25cc018c4e548", size = 44614, upload-time = "2025-08-25T13:49:24.86Z" },
+]
+
+[[package]]
+name = "urllib3"
+version = "2.6.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/c7/24/5f1b3bdffd70275f6661c76461e25f024d5a38a46f04aaca912426a2b1d3/urllib3-2.6.3.tar.gz", hash = "sha256:1b62b6884944a57dbe321509ab94fd4d3b307075e0c2eae991ac71ee15ad38ed", size = 435556, upload-time = "2026-01-07T16:24:43.925Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/39/08/aaaad47bc4e9dc8c725e68f9d04865dbcb2052843ff09c97b08904852d84/urllib3-2.6.3-py3-none-any.whl", hash = "sha256:bf272323e553dfb2e87d9bfd225ca7b0f467b919d7bbd355436d3fd37cb0acd4", size = 131584, upload-time = "2026-01-07T16:24:42.685Z" },
+]
+
+[[package]]
+name = "vncdotool"
+version = "1.2.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pillow" },
+ { name = "pycryptodomex" },
+ { name = "twisted" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/64/68/d43c145f110fbc7da6cbd4082d940fdbc8aaa7d9e8b52f3f574485d49208/vncdotool-1.2.0.tar.gz", hash = "sha256:53408d18ca7f9f21c525fc88189b01ca6594153ec1a9be09f6198306d166ea0d", size = 54809, upload-time = "2023-07-06T18:00:43.146Z" }
+
+[[package]]
+name = "webbrowser-open"
+version = "0.3.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/48/40/2e6eb1c513b60fe489da49bbdfca3e0d8c4ae5657352c90dad1dde2cc3c4/webbrowser_open-0.3.0.tar.gz", hash = "sha256:d751dd76e888d105d786b86ac890b9c0dd7b273d6f39e67c57a1cc7ddefe03a2", size = 14657, upload-time = "2025-02-27T12:09:16.143Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/2d/0e/16fa8d77cfefd4f09c7c21e518e8f7cc5d0c1b80c57048a38deabc13b96b/webbrowser_open-0.3.0-py3-none-any.whl", hash = "sha256:bd44ce80df1db634df3156f6b56ec2b445812e7bcff82d9f22b2217acaede23f", size = 9315, upload-time = "2025-02-27T12:09:14.089Z" },
+]
+
+[[package]]
+name = "websockets"
+version = "16.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/04/24/4b2031d72e840ce4c1ccb255f693b15c334757fc50023e4db9537080b8c4/websockets-16.0.tar.gz", hash = "sha256:5f6261a5e56e8d5c42a4497b364ea24d94d9563e8fbd44e78ac40879c60179b5", size = 179346, upload-time = "2026-01-10T09:23:47.181Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/f2/db/de907251b4ff46ae804ad0409809504153b3f30984daf82a1d84a9875830/websockets-16.0-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:31a52addea25187bde0797a97d6fc3d2f92b6f72a9370792d65a6e84615ac8a8", size = 177340, upload-time = "2026-01-10T09:22:34.539Z" },
+ { url = "https://files.pythonhosted.org/packages/f3/fa/abe89019d8d8815c8781e90d697dec52523fb8ebe308bf11664e8de1877e/websockets-16.0-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:417b28978cdccab24f46400586d128366313e8a96312e4b9362a4af504f3bbad", size = 175022, upload-time = "2026-01-10T09:22:36.332Z" },
+ { url = "https://files.pythonhosted.org/packages/58/5d/88ea17ed1ded2079358b40d31d48abe90a73c9e5819dbcde1606e991e2ad/websockets-16.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:af80d74d4edfa3cb9ed973a0a5ba2b2a549371f8a741e0800cb07becdd20f23d", size = 175319, upload-time = "2026-01-10T09:22:37.602Z" },
+ { url = "https://files.pythonhosted.org/packages/d2/ae/0ee92b33087a33632f37a635e11e1d99d429d3d323329675a6022312aac2/websockets-16.0-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:08d7af67b64d29823fed316505a89b86705f2b7981c07848fb5e3ea3020c1abe", size = 184631, upload-time = "2026-01-10T09:22:38.789Z" },
+ { url = "https://files.pythonhosted.org/packages/c8/c5/27178df583b6c5b31b29f526ba2da5e2f864ecc79c99dae630a85d68c304/websockets-16.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:7be95cfb0a4dae143eaed2bcba8ac23f4892d8971311f1b06f3c6b78952ee70b", size = 185870, upload-time = "2026-01-10T09:22:39.893Z" },
+ { url = "https://files.pythonhosted.org/packages/87/05/536652aa84ddc1c018dbb7e2c4cbcd0db884580bf8e95aece7593fde526f/websockets-16.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:d6297ce39ce5c2e6feb13c1a996a2ded3b6832155fcfc920265c76f24c7cceb5", size = 185361, upload-time = "2026-01-10T09:22:41.016Z" },
+ { url = "https://files.pythonhosted.org/packages/6d/e2/d5332c90da12b1e01f06fb1b85c50cfc489783076547415bf9f0a659ec19/websockets-16.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:1c1b30e4f497b0b354057f3467f56244c603a79c0d1dafce1d16c283c25f6e64", size = 184615, upload-time = "2026-01-10T09:22:42.442Z" },
+ { url = "https://files.pythonhosted.org/packages/77/fb/d3f9576691cae9253b51555f841bc6600bf0a983a461c79500ace5a5b364/websockets-16.0-cp311-cp311-win32.whl", hash = "sha256:5f451484aeb5cafee1ccf789b1b66f535409d038c56966d6101740c1614b86c6", size = 178246, upload-time = "2026-01-10T09:22:43.654Z" },
+ { url = "https://files.pythonhosted.org/packages/54/67/eaff76b3dbaf18dcddabc3b8c1dba50b483761cccff67793897945b37408/websockets-16.0-cp311-cp311-win_amd64.whl", hash = "sha256:8d7f0659570eefb578dacde98e24fb60af35350193e4f56e11190787bee77dac", size = 178684, upload-time = "2026-01-10T09:22:44.941Z" },
+ { url = "https://files.pythonhosted.org/packages/84/7b/bac442e6b96c9d25092695578dda82403c77936104b5682307bd4deb1ad4/websockets-16.0-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:71c989cbf3254fbd5e84d3bff31e4da39c43f884e64f2551d14bb3c186230f00", size = 177365, upload-time = "2026-01-10T09:22:46.787Z" },
+ { url = "https://files.pythonhosted.org/packages/b0/fe/136ccece61bd690d9c1f715baaeefd953bb2360134de73519d5df19d29ca/websockets-16.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:8b6e209ffee39ff1b6d0fa7bfef6de950c60dfb91b8fcead17da4ee539121a79", size = 175038, upload-time = "2026-01-10T09:22:47.999Z" },
+ { url = "https://files.pythonhosted.org/packages/40/1e/9771421ac2286eaab95b8575b0cb701ae3663abf8b5e1f64f1fd90d0a673/websockets-16.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:86890e837d61574c92a97496d590968b23c2ef0aeb8a9bc9421d174cd378ae39", size = 175328, upload-time = "2026-01-10T09:22:49.809Z" },
+ { url = "https://files.pythonhosted.org/packages/18/29/71729b4671f21e1eaa5d6573031ab810ad2936c8175f03f97f3ff164c802/websockets-16.0-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:9b5aca38b67492ef518a8ab76851862488a478602229112c4b0d58d63a7a4d5c", size = 184915, upload-time = "2026-01-10T09:22:51.071Z" },
+ { url = "https://files.pythonhosted.org/packages/97/bb/21c36b7dbbafc85d2d480cd65df02a1dc93bf76d97147605a8e27ff9409d/websockets-16.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:e0334872c0a37b606418ac52f6ab9cfd17317ac26365f7f65e203e2d0d0d359f", size = 186152, upload-time = "2026-01-10T09:22:52.224Z" },
+ { url = "https://files.pythonhosted.org/packages/4a/34/9bf8df0c0cf88fa7bfe36678dc7b02970c9a7d5e065a3099292db87b1be2/websockets-16.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:a0b31e0b424cc6b5a04b8838bbaec1688834b2383256688cf47eb97412531da1", size = 185583, upload-time = "2026-01-10T09:22:53.443Z" },
+ { url = "https://files.pythonhosted.org/packages/47/88/4dd516068e1a3d6ab3c7c183288404cd424a9a02d585efbac226cb61ff2d/websockets-16.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:485c49116d0af10ac698623c513c1cc01c9446c058a4e61e3bf6c19dff7335a2", size = 184880, upload-time = "2026-01-10T09:22:55.033Z" },
+ { url = "https://files.pythonhosted.org/packages/91/d6/7d4553ad4bf1c0421e1ebd4b18de5d9098383b5caa1d937b63df8d04b565/websockets-16.0-cp312-cp312-win32.whl", hash = "sha256:eaded469f5e5b7294e2bdca0ab06becb6756ea86894a47806456089298813c89", size = 178261, upload-time = "2026-01-10T09:22:56.251Z" },
+ { url = "https://files.pythonhosted.org/packages/c3/f0/f3a17365441ed1c27f850a80b2bc680a0fa9505d733fe152fdf5e98c1c0b/websockets-16.0-cp312-cp312-win_amd64.whl", hash = "sha256:5569417dc80977fc8c2d43a86f78e0a5a22fee17565d78621b6bb264a115d4ea", size = 178693, upload-time = "2026-01-10T09:22:57.478Z" },
+ { url = "https://files.pythonhosted.org/packages/cc/9c/baa8456050d1c1b08dd0ec7346026668cbc6f145ab4e314d707bb845bf0d/websockets-16.0-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:878b336ac47938b474c8f982ac2f7266a540adc3fa4ad74ae96fea9823a02cc9", size = 177364, upload-time = "2026-01-10T09:22:59.333Z" },
+ { url = "https://files.pythonhosted.org/packages/7e/0c/8811fc53e9bcff68fe7de2bcbe75116a8d959ac699a3200f4847a8925210/websockets-16.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:52a0fec0e6c8d9a784c2c78276a48a2bdf099e4ccc2a4cad53b27718dbfd0230", size = 175039, upload-time = "2026-01-10T09:23:01.171Z" },
+ { url = "https://files.pythonhosted.org/packages/aa/82/39a5f910cb99ec0b59e482971238c845af9220d3ab9fa76dd9162cda9d62/websockets-16.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:e6578ed5b6981005df1860a56e3617f14a6c307e6a71b4fff8c48fdc50f3ed2c", size = 175323, upload-time = "2026-01-10T09:23:02.341Z" },
+ { url = "https://files.pythonhosted.org/packages/bd/28/0a25ee5342eb5d5f297d992a77e56892ecb65e7854c7898fb7d35e9b33bd/websockets-16.0-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:95724e638f0f9c350bb1c2b0a7ad0e83d9cc0c9259f3ea94e40d7b02a2179ae5", size = 184975, upload-time = "2026-01-10T09:23:03.756Z" },
+ { url = "https://files.pythonhosted.org/packages/f9/66/27ea52741752f5107c2e41fda05e8395a682a1e11c4e592a809a90c6a506/websockets-16.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c0204dc62a89dc9d50d682412c10b3542d748260d743500a85c13cd1ee4bde82", size = 186203, upload-time = "2026-01-10T09:23:05.01Z" },
+ { url = "https://files.pythonhosted.org/packages/37/e5/8e32857371406a757816a2b471939d51c463509be73fa538216ea52b792a/websockets-16.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:52ac480f44d32970d66763115edea932f1c5b1312de36df06d6b219f6741eed8", size = 185653, upload-time = "2026-01-10T09:23:06.301Z" },
+ { url = "https://files.pythonhosted.org/packages/9b/67/f926bac29882894669368dc73f4da900fcdf47955d0a0185d60103df5737/websockets-16.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:6e5a82b677f8f6f59e8dfc34ec06ca6b5b48bc4fcda346acd093694cc2c24d8f", size = 184920, upload-time = "2026-01-10T09:23:07.492Z" },
+ { url = "https://files.pythonhosted.org/packages/3c/a1/3d6ccdcd125b0a42a311bcd15a7f705d688f73b2a22d8cf1c0875d35d34a/websockets-16.0-cp313-cp313-win32.whl", hash = "sha256:abf050a199613f64c886ea10f38b47770a65154dc37181bfaff70c160f45315a", size = 178255, upload-time = "2026-01-10T09:23:09.245Z" },
+ { url = "https://files.pythonhosted.org/packages/6b/ae/90366304d7c2ce80f9b826096a9e9048b4bb760e44d3b873bb272cba696b/websockets-16.0-cp313-cp313-win_amd64.whl", hash = "sha256:3425ac5cf448801335d6fdc7ae1eb22072055417a96cc6b31b3861f455fbc156", size = 178689, upload-time = "2026-01-10T09:23:10.483Z" },
+ { url = "https://files.pythonhosted.org/packages/72/07/c98a68571dcf256e74f1f816b8cc5eae6eb2d3d5cfa44d37f801619d9166/websockets-16.0-pp311-pypy311_pp73-macosx_10_15_x86_64.whl", hash = "sha256:349f83cd6c9a415428ee1005cadb5c2c56f4389bc06a9af16103c3bc3dcc8b7d", size = 174947, upload-time = "2026-01-10T09:23:36.166Z" },
+ { url = "https://files.pythonhosted.org/packages/7e/52/93e166a81e0305b33fe416338be92ae863563fe7bce446b0f687b9df5aea/websockets-16.0-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:4a1aba3340a8dca8db6eb5a7986157f52eb9e436b74813764241981ca4888f03", size = 175260, upload-time = "2026-01-10T09:23:37.409Z" },
+ { url = "https://files.pythonhosted.org/packages/56/0c/2dbf513bafd24889d33de2ff0368190a0e69f37bcfa19009ef819fe4d507/websockets-16.0-pp311-pypy311_pp73-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:f4a32d1bd841d4bcbffdcb3d2ce50c09c3909fbead375ab28d0181af89fd04da", size = 176071, upload-time = "2026-01-10T09:23:39.158Z" },
+ { url = "https://files.pythonhosted.org/packages/a5/8f/aea9c71cc92bf9b6cc0f7f70df8f0b420636b6c96ef4feee1e16f80f75dd/websockets-16.0-pp311-pypy311_pp73-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0298d07ee155e2e9fda5be8a9042200dd2e3bb0b8a38482156576f863a9d457c", size = 176968, upload-time = "2026-01-10T09:23:41.031Z" },
+ { url = "https://files.pythonhosted.org/packages/9a/3f/f70e03f40ffc9a30d817eef7da1be72ee4956ba8d7255c399a01b135902a/websockets-16.0-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:a653aea902e0324b52f1613332ddf50b00c06fdaf7e92624fbf8c77c78fa5767", size = 178735, upload-time = "2026-01-10T09:23:42.259Z" },
+ { url = "https://files.pythonhosted.org/packages/6f/28/258ebab549c2bf3e64d2b0217b973467394a9cea8c42f70418ca2c5d0d2e/websockets-16.0-py3-none-any.whl", hash = "sha256:1637db62fad1dc833276dded54215f2c7fa46912301a24bd94d45d46a011ceec", size = 171598, upload-time = "2026-01-10T09:23:45.395Z" },
+]
+
+[[package]]
+name = "zope-interface"
+version = "8.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/86/a4/77daa5ba398996d16bb43fc721599d27d03eae68fe3c799de1963c72e228/zope_interface-8.2.tar.gz", hash = "sha256:afb20c371a601d261b4f6edb53c3c418c249db1a9717b0baafc9a9bb39ba1224", size = 254019, upload-time = "2026-01-09T07:51:07.253Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/98/97/9c2aa8caae79915ed64eb114e18816f178984c917aa9adf2a18345e4f2e5/zope_interface-8.2-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:c65ade7ea85516e428651048489f5e689e695c79188761de8c622594d1e13322", size = 208081, upload-time = "2026-01-09T08:05:06.623Z" },
+ { url = "https://files.pythonhosted.org/packages/34/86/4e2fcb01a8f6780ac84923748e450af0805531f47c0956b83065c99ab543/zope_interface-8.2-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:a1ef4b43659e1348f35f38e7d1a6bbc1682efde239761f335ffc7e31e798b65b", size = 208522, upload-time = "2026-01-09T08:05:07.986Z" },
+ { url = "https://files.pythonhosted.org/packages/f6/eb/08e277da32ddcd4014922854096cf6dcb7081fad415892c2da1bedefbf02/zope_interface-8.2-cp311-cp311-manylinux1_i686.manylinux2014_i686.manylinux_2_17_i686.manylinux_2_5_i686.whl", hash = "sha256:dfc4f44e8de2ff4eba20af4f0a3ca42d3c43ab24a08e49ccd8558b7a4185b466", size = 255198, upload-time = "2026-01-09T08:05:09.532Z" },
+ { url = "https://files.pythonhosted.org/packages/ea/a1/b32484f3281a5dc83bc713ad61eca52c543735cdf204543172087a074a74/zope_interface-8.2-cp311-cp311-manylinux1_x86_64.manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:8f094bfb49179ec5dc9981cb769af1275702bd64720ef94874d9e34da1390d4c", size = 259970, upload-time = "2026-01-09T08:05:11.477Z" },
+ { url = "https://files.pythonhosted.org/packages/f6/81/bca0e8ae1e487d4093a8a7cfed2118aa2d4758c8cfd66e59d2af09d71f1c/zope_interface-8.2-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:d2bb8e7364e18f083bf6744ccf30433b2a5f236c39c95df8514e3c13007098ce", size = 261153, upload-time = "2026-01-09T08:05:13.402Z" },
+ { url = "https://files.pythonhosted.org/packages/40/1e/e3ff2a708011e56b10b271b038d4cb650a8ad5b7d24352fe2edf6d6b187a/zope_interface-8.2-cp311-cp311-win_amd64.whl", hash = "sha256:6f4b4dfcfdfaa9177a600bb31cebf711fdb8c8e9ed84f14c61c420c6aa398489", size = 212330, upload-time = "2026-01-09T08:05:15.267Z" },
+ { url = "https://files.pythonhosted.org/packages/e0/a0/1e1fabbd2e9c53ef92b69df6d14f4adc94ec25583b1380336905dc37e9a0/zope_interface-8.2-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:624b6787fc7c3e45fa401984f6add2c736b70a7506518c3b537ffaacc4b29d4c", size = 208785, upload-time = "2026-01-09T08:05:17.348Z" },
+ { url = "https://files.pythonhosted.org/packages/c3/2a/88d098a06975c722a192ef1fb7d623d1b57c6a6997cf01a7aabb45ab1970/zope_interface-8.2-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:bc9ded9e97a0ed17731d479596ed1071e53b18e6fdb2fc33af1e43f5fd2d3aaa", size = 208976, upload-time = "2026-01-09T08:05:18.792Z" },
+ { url = "https://files.pythonhosted.org/packages/e9/e8/757398549fdfd2f8c89f32c82ae4d2f0537ae2a5d2f21f4a2f711f5a059f/zope_interface-8.2-cp312-cp312-manylinux1_i686.manylinux2014_i686.manylinux_2_17_i686.manylinux_2_5_i686.whl", hash = "sha256:532367553e4420c80c0fc0cabcc2c74080d495573706f66723edee6eae53361d", size = 259411, upload-time = "2026-01-09T08:05:20.567Z" },
+ { url = "https://files.pythonhosted.org/packages/91/af/502601f0395ce84dff622f63cab47488657a04d0065547df42bee3a680ff/zope_interface-8.2-cp312-cp312-manylinux1_x86_64.manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:2bf9cf275468bafa3c72688aad8cfcbe3d28ee792baf0b228a1b2d93bd1d541a", size = 264859, upload-time = "2026-01-09T08:05:22.234Z" },
+ { url = "https://files.pythonhosted.org/packages/89/0c/d2f765b9b4814a368a7c1b0ac23b68823c6789a732112668072fe596945d/zope_interface-8.2-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:0009d2d3c02ea783045d7804da4fd016245e5c5de31a86cebba66dd6914d59a2", size = 264398, upload-time = "2026-01-09T08:05:23.853Z" },
+ { url = "https://files.pythonhosted.org/packages/4a/81/2f171fbc4222066957e6b9220c4fb9146792540102c37e6d94e5d14aad97/zope_interface-8.2-cp312-cp312-win_amd64.whl", hash = "sha256:845d14e580220ae4544bd4d7eb800f0b6034fe5585fc2536806e0a26c2ee6640", size = 212444, upload-time = "2026-01-09T08:05:25.148Z" },
+ { url = "https://files.pythonhosted.org/packages/66/47/45188fb101fa060b20e6090e500682398ab415e516a0c228fbb22bc7def2/zope_interface-8.2-cp313-cp313-macosx_10_9_x86_64.whl", hash = "sha256:6068322004a0158c80dfd4708dfb103a899635408c67c3b10e9acec4dbacefec", size = 209170, upload-time = "2026-01-09T08:05:26.616Z" },
+ { url = "https://files.pythonhosted.org/packages/09/03/f6b9336c03c2b48403c4eb73a1ec961d94dc2fb5354c583dfb5fa05fd41f/zope_interface-8.2-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:2499de92e8275d0dd68f84425b3e19e9268cd1fa8507997900fa4175f157733c", size = 209229, upload-time = "2026-01-09T08:05:28.521Z" },
+ { url = "https://files.pythonhosted.org/packages/07/b1/65fe1dca708569f302ade02e6cdca309eab6752bc9f80105514f5b708651/zope_interface-8.2-cp313-cp313-manylinux1_i686.manylinux2014_i686.manylinux_2_17_i686.manylinux_2_5_i686.whl", hash = "sha256:f777e68c76208503609c83ca021a6864902b646530a1a39abb9ed310d1100664", size = 259393, upload-time = "2026-01-09T08:05:29.897Z" },
+ { url = "https://files.pythonhosted.org/packages/eb/a5/97b49cfceb6ed53d3dcfb3f3ebf24d83b5553194f0337fbbb3a9fec6cf78/zope_interface-8.2-cp313-cp313-manylinux1_x86_64.manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:9b05a919fdb0ed6ea942e5a7800e09a8b6cdae6f98fee1bef1c9d1a3fc43aaa0", size = 264863, upload-time = "2026-01-09T08:05:31.501Z" },
+ { url = "https://files.pythonhosted.org/packages/cb/02/0b7a77292810efe3a0586a505b077ebafd5114e10c6e6e659f0c8e387e1f/zope_interface-8.2-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:ccc62b5712dd7bd64cfba3ee63089fb11e840f5914b990033beeae3b2180b6cb", size = 264369, upload-time = "2026-01-09T08:05:32.941Z" },
+ { url = "https://files.pythonhosted.org/packages/fb/1d/0d1ff3846302ed1b5bbf659316d8084b30106770a5f346b7ff4e9f540f80/zope_interface-8.2-cp313-cp313-win_amd64.whl", hash = "sha256:34f877d1d3bb7565c494ed93828fa6417641ca26faf6e8f044e0d0d500807028", size = 212447, upload-time = "2026-01-09T08:05:35.064Z" },
+]
diff --git a/libs/python/cua-sandbox/vnc_screen.png b/libs/python/cua-sandbox/vnc_screen.png
new file mode 100644
index 0000000000..9f3b4f5f48
Binary files /dev/null and b/libs/python/cua-sandbox/vnc_screen.png differ
diff --git a/scripts/docs-generators/python-sdk.ts b/scripts/docs-generators/python-sdk.ts
index 776bce5459..da24c31b13 100644
--- a/scripts/docs-generators/python-sdk.ts
+++ b/scripts/docs-generators/python-sdk.ts
@@ -143,6 +143,16 @@ const SDK_CONFIGS: Record<string, SDKConfig> = {
outputDir: 'cli',
tagPrefix: 'cli-v',
},
+ sandbox: {
+ packageDir: 'libs/python/cua-sandbox/cua_sandbox',
+ packageName: 'cua_sandbox',
+ outputPath: 'docs/content/docs/cua/reference/sandbox-sdk/index.mdx',
+ displayName: 'Sandbox SDK',
+ description: 'Python API reference for cua-sandbox — creating and controlling sandboxes',
+ outputDir: 'sandbox-sdk',
+ tagPrefix: 'sandbox-v',
+ includeSubmodules: ['sandbox', 'image', 'localhost', 'interfaces', 'builder'],
+ },
bench: {
packageDir: 'libs/cua-bench/cua_bench',
packageName: 'cua_bench',
diff --git a/tests/android_rps_benchmark.py b/tests/android_rps_benchmark.py
new file mode 100644
index 0000000000..bac049d6e3
--- /dev/null
+++ b/tests/android_rps_benchmark.py
@@ -0,0 +1,527 @@
+"""Android VM fleet benchmark — measure max achievable RPS for a given sandbox count.
+
+Provisions N Android sandboxes in parallel, then drives them as fast as possible
+(no rate limiting). Reports achieved throughput and latency percentiles.
+
+Usage:
+ python tests/android_rps_benchmark.py --sandboxes 2 --duration 30
+ python tests/android_rps_benchmark.py --sandboxes 8 --duration 60 --action step
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import builtins
+import functools
+import math
+import os
+import statistics
+import time
+from dataclasses import dataclass, field
+
+from cua_sandbox import Image, Sandbox
+from cua_sandbox.transport.cloud import CloudTransport
+
+print = functools.partial(builtins.print, flush=True)
+
+# ── Data types ────────────────────────────────────────────────────────────────
+
+
+@dataclass
+class SandboxStats:
+ name: str
+ provision_time: float
+ requests: int = 0
+ errors: int = 0
+ latencies: list[float] = field(default_factory=list)
+
+
+@dataclass
+class BenchmarkResult:
+ achieved_rps: float
+ sandboxes: int
+ duration: float
+ total_requests: int
+ total_errors: int
+ provision_times: list[float]
+ all_latencies: list[float]
+
+ @property
+ def error_rate(self) -> float:
+ return self.total_errors / max(self.total_requests, 1)
+
+ @property
+ def mean_provision(self) -> float:
+ return statistics.mean(self.provision_times) if self.provision_times else 0.0
+
+ @property
+ def p50(self) -> float:
+ return _percentile(self.all_latencies, 50)
+
+ @property
+ def p95(self) -> float:
+ return _percentile(self.all_latencies, 95)
+
+ @property
+ def p99(self) -> float:
+ return _percentile(self.all_latencies, 99)
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+
+def _percentile(data: list[float], p: float) -> float:
+ if not data:
+ return 0.0
+ s = sorted(data)
+ idx = (p / 100) * (len(s) - 1)
+ lo = int(idx)
+ hi = min(lo + 1, len(s) - 1)
+ return s[lo] + (idx - lo) * (s[hi] - s[lo])
+
+
+# ── Sandbox lifecycle ─────────────────────────────────────────────────────────
+
+
+async def _provision(image: Image, idx: int) -> tuple[Sandbox, SandboxStats]:
+ t0 = time.monotonic()
+ sb = await Sandbox.create(image)
+ elapsed = time.monotonic() - t0
+ name = getattr(sb, "name", None) or f"sb-{idx}"
+ print(f" [{idx + 1:>3}] {name} provisioned in {elapsed:.1f}s")
+ return sb, SandboxStats(name=name, provision_time=elapsed)
+
+
+async def _provision_fleet(
+ image: Image, n: int, parallel: int = 2
+) -> tuple[list[Sandbox], list[SandboxStats], list[float]]:
+ sandboxes, stats, provision_times = [], [], []
+
+ for batch_start in range(0, n, parallel):
+ batch = range(batch_start, min(batch_start + parallel, n))
+ tasks = [_provision(image, i) for i in batch]
+ raw = await asyncio.gather(*tasks, return_exceptions=True)
+ for i, res in zip(batch, raw):
+ if isinstance(res, Exception):
+ print(f" [!] sandbox {i + 1} failed to provision: {res}")
+ else:
+ sb, st = res
+ sandboxes.append(sb)
+ stats.append(st)
+ provision_times.append(st.provision_time)
+
+ return sandboxes, stats, provision_times
+
+
+async def _destroy_fleet(sandboxes: list[Sandbox]) -> None:
+ results = await asyncio.gather(*[sb.destroy() for sb in sandboxes], return_exceptions=True)
+ for i, r in enumerate(results):
+ if isinstance(r, Exception):
+ print(f" [!] sandbox {i} destroy failed: {r}")
+
+
+# ── Per-sandbox actions ───────────────────────────────────────────────────────
+
+_t_bench_start: float = 0.0 # set when load test begins
+
+
+def _ts() -> str:
+ """Relative timestamp from load test start."""
+ return f"{time.monotonic() - _t_bench_start:>7.3f}s"
+
+
+async def _do_screenshot(sb: Sandbox, name: str) -> None:
+ t0 = time.monotonic()
+ data = await sb.screenshot(format="jpeg")
+ elapsed = time.monotonic() - t0
+ print(f" {_ts()} {name} screenshot {elapsed*1000:.0f}ms {len(data)}B")
+ if len(data) < 500:
+ raise ValueError(f"screenshot too small ({len(data)} bytes)")
+
+
+async def _do_step(sb: Sandbox, name: str) -> None:
+ """Simulate one RL step: tap center of screen + screenshot."""
+ t_size0 = time.monotonic()
+ w, h = await sb.screen.size()
+ t_size = time.monotonic() - t_size0
+ print(f" {_ts()} {name} screen_size {t_size*1000:.0f}ms ({w}x{h})")
+
+ t_tap0 = time.monotonic()
+ await sb.mouse.click(w // 2, h // 2)
+ t_tap = time.monotonic() - t_tap0
+ print(f" {_ts()} {name} tap {t_tap*1000:.0f}ms")
+
+ t_ss0 = time.monotonic()
+ data = await sb.screenshot(format="jpeg")
+ t_ss = time.monotonic() - t_ss0
+ print(f" {_ts()} {name} screenshot {t_ss*1000:.0f}ms {len(data)}B")
+
+ if len(data) < 500:
+ raise ValueError(f"screenshot too small ({len(data)} bytes)")
+
+
+_ACTION_FNS = {
+ "screenshot": _do_screenshot,
+ "step": _do_step,
+}
+# action fn signature: (sb, name) -> None
+
+
+# ── Worker loop ───────────────────────────────────────────────────────────────
+
+
+async def _worker(
+ sb: Sandbox,
+ stats: SandboxStats,
+ stop_event: asyncio.Event,
+ action: str,
+) -> None:
+ """Drive one sandbox as fast as possible until stop_event is set."""
+ fn = _ACTION_FNS[action]
+ while not stop_event.is_set():
+ t0 = time.monotonic()
+ try:
+ await fn(sb, stats.name)
+ elapsed = time.monotonic() - t0
+ stats.latencies.append(elapsed)
+ stats.requests += 1
+ except asyncio.CancelledError:
+ raise
+ except Exception as e:
+ stats.errors += 1
+ stats.requests += 1
+ if not stop_event.is_set():
+ print(f" [!] {stats.name}: {e}")
+
+
+# ── Progress reporter ─────────────────────────────────────────────────────────
+
+
+async def _progress_reporter(
+ all_stats: list[SandboxStats],
+ t_start: float,
+ duration: float,
+ stop_event: asyncio.Event,
+) -> None:
+ interval = max(5.0, duration / 6)
+ while not stop_event.is_set():
+ await asyncio.sleep(interval)
+ if stop_event.is_set():
+ break
+ elapsed = time.monotonic() - t_start
+ total_reqs = sum(s.requests for s in all_stats)
+ total_errs = sum(s.errors for s in all_stats)
+ rps = total_reqs / elapsed if elapsed > 0 else 0.0
+ remain = max(0, duration - elapsed)
+ print(
+ f" t={elapsed:>5.1f}s {rps:>6.1f} RPS "
+ f"reqs={total_reqs} errs={total_errs} remain={remain:.0f}s"
+ )
+
+
+# ── Benchmark orchestrator ────────────────────────────────────────────────────
+
+
+async def run_benchmark(
+ n_sandboxes: int,
+ duration: float,
+ action: str,
+ image: Image,
+ parallel: int = 2,
+) -> BenchmarkResult:
+
+ # ── Provision ──────────────────────────────────────────────────────────
+ print(f"\n── Provisioning {n_sandboxes} sandbox(es) ──")
+ sandboxes, all_stats, provision_times = await _provision_fleet(
+ image, n_sandboxes, parallel=parallel
+ )
+
+ if not sandboxes:
+ raise RuntimeError("All sandboxes failed to provision — aborting benchmark.")
+
+ actual = len(sandboxes)
+ print(
+ f" {actual}/{n_sandboxes} provisioned | "
+ f"mean={statistics.mean(provision_times):.1f}s "
+ f"max={max(provision_times):.1f}s"
+ )
+
+ # ── Load test ─────────────────────────────────────────────────────────
+ stop_event = asyncio.Event()
+ t_start = time.monotonic()
+
+ global _t_bench_start
+ _t_bench_start = t_start
+
+ print(f"\n── Load test: max RPS × {duration}s ──\n action={action} sandboxes={actual}")
+
+ workers = [
+ asyncio.create_task(_worker(sb, st, stop_event, action))
+ for sb, st in zip(sandboxes, all_stats)
+ ]
+ reporter = asyncio.create_task(_progress_reporter(all_stats, t_start, duration, stop_event))
+
+ await asyncio.sleep(duration)
+ stop_event.set()
+
+ for w in workers:
+ w.cancel()
+ reporter.cancel()
+ await asyncio.gather(*workers, reporter, return_exceptions=True)
+
+ elapsed = time.monotonic() - t_start
+
+ # ── Cleanup ───────────────────────────────────────────────────────────
+ print(f"\n── Destroying {actual} sandbox(es) ──")
+ await _destroy_fleet(sandboxes)
+
+ # ── Aggregate ─────────────────────────────────────────────────────────
+ total_reqs = sum(s.requests for s in all_stats)
+ total_errs = sum(s.errors for s in all_stats)
+ all_latencies = [lat for s in all_stats for lat in s.latencies]
+ achieved_rps = total_reqs / elapsed if elapsed > 0 else 0.0
+
+ return BenchmarkResult(
+ achieved_rps=achieved_rps,
+ sandboxes=actual,
+ duration=elapsed,
+ total_requests=total_reqs,
+ total_errors=total_errs,
+ provision_times=provision_times,
+ all_latencies=all_latencies,
+ )
+
+
+# ── Report ────────────────────────────────────────────────────────────────────
+
+
+def print_report(result: BenchmarkResult) -> None:
+ bar = "─" * 58
+ print(f"\n{'═'*58}")
+ print(" Android VM Fleet Benchmark")
+ print(f"{'═'*58}")
+ print(f" {bar}")
+ print(" Throughput")
+ print(f" {'Achieved RPS':<24} {result.achieved_rps:.2f}")
+ print(f" {'RPS / sandbox':<24} {result.achieved_rps / max(result.sandboxes, 1):.2f}")
+ print(f" {'Sandboxes':<24} {result.sandboxes}")
+ print(f" {'Duration':<24} {result.duration:.1f}s")
+ print(f" {'Total requests':<24} {result.total_requests}")
+ print(f" {'Error rate':<24} {result.error_rate * 100:.1f}%")
+ print(f" {bar}")
+ print(" Provisioning")
+ print(f" {'Mean cold start':<24} {result.mean_provision:.1f}s")
+ if result.provision_times:
+ print(f" {'Max cold start':<24} {max(result.provision_times):.1f}s")
+ print(f" {bar}")
+ print(" Latency (successful requests)")
+ if result.all_latencies:
+ print(f" {'p50':<24} {result.p50 * 1000:.0f}ms")
+ print(f" {'p95':<24} {result.p95 * 1000:.0f}ms")
+ print(f" {'p99':<24} {result.p99 * 1000:.0f}ms")
+ else:
+ print(" (no successful requests)")
+ print(f"{'═'*58}\n")
+
+
+# ── CLI ───────────────────────────────────────────────────────────────────────
+
+
+_STATE_FILE = "/tmp/android_bench_sandboxes.txt"
+
+
+def _parse_args() -> argparse.Namespace:
+ p = argparse.ArgumentParser(
+ description="Measure max RPS for a fleet of Android sandboxes.",
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ epilog="""
+Examples:
+ # Full run (provision + load test + delete):
+ python tests/android_rps_benchmark.py --sandboxes 4 --duration 30
+
+ # Step-by-step:
+ python tests/android_rps_benchmark.py --sandboxes 4 --provision
+ python tests/android_rps_benchmark.py --continue
+ python tests/android_rps_benchmark.py --delete
+ """,
+ )
+ p.add_argument(
+ "--sandboxes", type=int, default=2, help="Number of Android sandboxes (default: 2)."
+ )
+ p.add_argument(
+ "--duration", type=float, default=30.0, help="Load-test duration in seconds (default: 30)."
+ )
+ p.add_argument(
+ "--action",
+ choices=list(_ACTION_FNS),
+ default="screenshot",
+ help="'screenshot' = observation only; 'step' = tap + screenshot. Default: screenshot.",
+ )
+ p.add_argument("--android-version", default="14", help="Android version (default: 14).")
+ p.add_argument(
+ "--parallel",
+ type=int,
+ default=4,
+ metavar="N",
+ help="Number of sandboxes to provision concurrently (default: 4). Use 1 for fully sequential.",
+ )
+ mode = p.add_mutually_exclusive_group()
+ mode.add_argument(
+ "--provision",
+ action="store_true",
+ help=f"Provision sandboxes and save names to {_STATE_FILE}. No load test or delete.",
+ )
+ mode.add_argument(
+ "--continue",
+ dest="cont",
+ action="store_true",
+ help=f"Load sandbox names from {_STATE_FILE}, run load test, then delete.",
+ )
+ mode.add_argument(
+ "--delete",
+ action="store_true",
+ help=f"Delete sandboxes listed in {_STATE_FILE}.",
+ )
+ return p.parse_args()
+
+
+async def _main() -> None:
+ args = _parse_args()
+ image = Image.android(args.android_version)
+
+ # ── --delete ──────────────────────────────────────────────────────────
+ if args.delete:
+ try:
+ names = open(_STATE_FILE).read().split()
+ except FileNotFoundError:
+ print(f"No state file at {_STATE_FILE}")
+ return
+ print(f"── Deleting {len(names)} sandbox(es) from {_STATE_FILE} ──")
+ sandboxes = [Sandbox(CloudTransport(name=n), name=n, _ephemeral=False) for n in names]
+ await _destroy_fleet(sandboxes)
+ os.unlink(_STATE_FILE)
+ print("Done.")
+ return
+
+ # ── --continue ────────────────────────────────────────────────────────
+ if args.cont:
+ try:
+ names = open(_STATE_FILE).read().split()
+ except FileNotFoundError:
+ print(f"No state file at {_STATE_FILE} — run --provision first.")
+ return
+ print(f"── Reconnecting to {len(names)} sandbox(es) from {_STATE_FILE} ──")
+ sandboxes = []
+ all_stats = []
+ provision_times = []
+
+ async def _reconnect(name: str):
+ try:
+ sb = await Sandbox.connect(name=name)
+ print(f" [ok] {name}", flush=True)
+ return sb
+ except Exception as e:
+ print(f" [!] {name}: {e}", flush=True)
+ return None
+
+ results = await asyncio.gather(*[_reconnect(n) for n in names])
+ for name, sb in zip(names, results):
+ if sb is None:
+ continue
+ sandboxes.append(sb)
+ all_stats.append(SandboxStats(name=name, provision_time=0.0))
+ provision_times.append(0.0)
+
+ stop_event = asyncio.Event()
+ t_start = time.monotonic()
+ global _t_bench_start
+ _t_bench_start = t_start
+
+ print(
+ f"\n── Load test: max RPS × {args.duration}s ──\n action={args.action} sandboxes={len(sandboxes)}"
+ )
+ workers = [
+ asyncio.create_task(_worker(sb, st, stop_event, args.action))
+ for sb, st in zip(sandboxes, all_stats)
+ ]
+ reporter = asyncio.create_task(
+ _progress_reporter(all_stats, t_start, args.duration, stop_event)
+ )
+ await asyncio.sleep(args.duration)
+ stop_event.set()
+ for w in workers:
+ w.cancel()
+ reporter.cancel()
+ await asyncio.gather(*workers, reporter, return_exceptions=True)
+ elapsed = time.monotonic() - t_start
+
+ total_reqs = sum(s.requests for s in all_stats)
+ total_errs = sum(s.errors for s in all_stats)
+ all_latencies = [lat for s in all_stats for lat in s.latencies]
+ result = BenchmarkResult(
+ achieved_rps=total_reqs / elapsed if elapsed > 0 else 0.0,
+ sandboxes=len(sandboxes),
+ duration=elapsed,
+ total_requests=total_reqs,
+ total_errors=total_errs,
+ provision_times=provision_times,
+ all_latencies=all_latencies,
+ )
+ print_report(result)
+ return
+
+ # ── --provision ───────────────────────────────────────────────────────
+ if args.provision:
+ # Resume: load existing names so we only provision what's missing
+ existing_names: list[str] = []
+ try:
+ existing_names = open(_STATE_FILE).read().split()
+ print(
+ f"Resuming: {len(existing_names)} already provisioned, "
+ f"targeting {args.sandboxes} total."
+ )
+ except FileNotFoundError:
+ pass
+
+ remaining = args.sandboxes - len(existing_names)
+ print("Android RL Fleet Benchmark")
+ print(
+ f" sandboxes={args.sandboxes} android={args.android_version} "
+ f"mode=provision-only remaining={remaining}"
+ )
+
+ if remaining <= 0:
+ print(f"Already have {len(existing_names)} sandboxes — nothing to provision.")
+ return
+
+ print(f"\n── Provisioning {remaining} more sandbox(es) (parallel={args.parallel}) ──")
+ new_sandboxes, _, _ = await _provision_fleet(image, remaining, parallel=args.parallel)
+ new_names = [
+ getattr(sb, "name", None) or f"sb-{len(existing_names) + i}"
+ for i, sb in enumerate(new_sandboxes)
+ ]
+ all_names = existing_names + new_names
+ with open(_STATE_FILE, "w") as f:
+ f.write("\n".join(all_names) + "\n")
+ print(f"\nSaved {len(all_names)} sandbox name(s) to {_STATE_FILE}")
+ print("Run with --continue to start the load test.")
+ return
+
+ # ── normal (all-in-one) ───────────────────────────────────────────────
+ print("Android RL Fleet Benchmark")
+ print(
+ f" sandboxes={args.sandboxes} duration={args.duration}s action={args.action} android={args.android_version}"
+ )
+ result = await run_benchmark(
+ n_sandboxes=args.sandboxes,
+ duration=args.duration,
+ action=args.action,
+ image=image,
+ parallel=args.parallel,
+ )
+ print_report(result)
+
+
+if __name__ == "__main__":
+ asyncio.run(_main())
diff --git a/tests/android_rps_benchmark_local.py b/tests/android_rps_benchmark_local.py
new file mode 100644
index 0000000000..5c080b8e33
--- /dev/null
+++ b/tests/android_rps_benchmark_local.py
@@ -0,0 +1,366 @@
+"""Android baremetal benchmark — measure max achievable RPS using local AndroidEmulatorRuntime.
+
+Provisions N Android sandboxes locally (local=True), then drives them as fast as possible.
+Reports achieved throughput and latency percentiles.
+
+Usage:
+ python tests/android_rps_benchmark_local.py --sandboxes 1 --duration 30
+ python tests/android_rps_benchmark_local.py --sandboxes 2 --duration 60 --action step
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import builtins
+import functools
+import statistics
+import time
+from dataclasses import dataclass, field
+
+from cua_sandbox import Image, Sandbox
+from cua_sandbox.runtime.android_emulator import AndroidEmulatorRuntime
+
+print = functools.partial(builtins.print, flush=True)
+
+# ── Data types ────────────────────────────────────────────────────────────────
+
+
+@dataclass
+class SandboxStats:
+ name: str
+ provision_time: float
+ requests: int = 0
+ errors: int = 0
+ latencies: list[float] = field(default_factory=list)
+
+
+@dataclass
+class BenchmarkResult:
+ achieved_rps: float
+ sandboxes: int
+ duration: float
+ total_requests: int
+ total_errors: int
+ provision_times: list[float]
+ all_latencies: list[float]
+
+ @property
+ def error_rate(self) -> float:
+ return self.total_errors / max(self.total_requests, 1)
+
+ @property
+ def mean_provision(self) -> float:
+ return statistics.mean(self.provision_times) if self.provision_times else 0.0
+
+ @property
+ def p50(self) -> float:
+ return _percentile(self.all_latencies, 50)
+
+ @property
+ def p95(self) -> float:
+ return _percentile(self.all_latencies, 95)
+
+ @property
+ def p99(self) -> float:
+ return _percentile(self.all_latencies, 99)
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+
+def _percentile(data: list[float], p: float) -> float:
+ if not data:
+ return 0.0
+ s = sorted(data)
+ idx = (p / 100) * (len(s) - 1)
+ lo = int(idx)
+ hi = min(lo + 1, len(s) - 1)
+ return s[lo] + (idx - lo) * (s[hi] - s[lo])
+
+
+# ── Sandbox lifecycle ─────────────────────────────────────────────────────────
+
+
+async def _provision(image: Image, idx: int) -> tuple[Sandbox, SandboxStats]:
+ t0 = time.monotonic()
+ sb = await Sandbox.create(image, local=True, runtime=AndroidEmulatorRuntime())
+ elapsed = time.monotonic() - t0
+ name = getattr(sb, "name", None) or f"sb-{idx}"
+ print(f" [{idx + 1:>3}] {name} provisioned in {elapsed:.1f}s")
+ return sb, SandboxStats(name=name, provision_time=elapsed)
+
+
+async def _provision_fleet(
+ image: Image, n: int
+) -> tuple[list[Sandbox], list[SandboxStats], list[float]]:
+ tasks = [_provision(image, i) for i in range(n)]
+ raw = await asyncio.gather(*tasks, return_exceptions=True)
+
+ sandboxes, stats, provision_times = [], [], []
+ for i, res in enumerate(raw):
+ if isinstance(res, Exception):
+ print(f" [!] sandbox {i + 1} failed to provision: {res}")
+ else:
+ sb, st = res
+ sandboxes.append(sb)
+ stats.append(st)
+ provision_times.append(st.provision_time)
+
+ return sandboxes, stats, provision_times
+
+
+async def _destroy_fleet(sandboxes: list[Sandbox]) -> None:
+ results = await asyncio.gather(*[sb.destroy() for sb in sandboxes], return_exceptions=True)
+ for i, r in enumerate(results):
+ if isinstance(r, Exception):
+ print(f" [!] sandbox {i} destroy failed: {r}")
+
+
+# ── Per-sandbox actions ───────────────────────────────────────────────────────
+
+_t_bench_start: float = 0.0 # set when load test begins
+
+
+def _ts() -> str:
+ return f"{time.monotonic() - _t_bench_start:>7.3f}s"
+
+
+async def _do_screenshot(sb: Sandbox, name: str) -> None:
+ t0 = time.monotonic()
+ data = await sb.screenshot(format="jpeg")
+ elapsed = time.monotonic() - t0
+ print(f" {_ts()} {name} screenshot {elapsed*1000:.0f}ms {len(data)}B")
+ if len(data) < 500:
+ raise ValueError(f"screenshot too small ({len(data)} bytes)")
+
+
+async def _do_step(sb: Sandbox, name: str) -> None:
+ """Simulate one RL step: tap center of screen + screenshot."""
+ t_size0 = time.monotonic()
+ w, h = await sb.screen.size()
+ t_size = time.monotonic() - t_size0
+ print(f" {_ts()} {name} screen_size {t_size*1000:.0f}ms ({w}x{h})")
+
+ t_tap0 = time.monotonic()
+ await sb.mouse.click(w // 2, h // 2)
+ t_tap = time.monotonic() - t_tap0
+ print(f" {_ts()} {name} tap {t_tap*1000:.0f}ms")
+
+ t_ss0 = time.monotonic()
+ data = await sb.screenshot(format="jpeg")
+ t_ss = time.monotonic() - t_ss0
+ print(f" {_ts()} {name} screenshot {t_ss*1000:.0f}ms {len(data)}B")
+
+ if len(data) < 500:
+ raise ValueError(f"screenshot too small ({len(data)} bytes)")
+
+
+_ACTION_FNS = {
+ "screenshot": _do_screenshot,
+ "step": _do_step,
+}
+
+
+# ── Worker loop ───────────────────────────────────────────────────────────────
+
+
+async def _worker(
+ sb: Sandbox,
+ stats: SandboxStats,
+ stop_event: asyncio.Event,
+ action: str,
+) -> None:
+ fn = _ACTION_FNS[action]
+ while not stop_event.is_set():
+ t0 = time.monotonic()
+ try:
+ await fn(sb, stats.name)
+ elapsed = time.monotonic() - t0
+ stats.latencies.append(elapsed)
+ stats.requests += 1
+ except asyncio.CancelledError:
+ raise
+ except Exception as e:
+ stats.errors += 1
+ stats.requests += 1
+ if not stop_event.is_set():
+ print(f" [!] {stats.name}: {e}")
+
+
+# ── Progress reporter ─────────────────────────────────────────────────────────
+
+
+async def _progress_reporter(
+ all_stats: list[SandboxStats],
+ t_start: float,
+ duration: float,
+ stop_event: asyncio.Event,
+) -> None:
+ interval = max(5.0, duration / 6)
+ while not stop_event.is_set():
+ await asyncio.sleep(interval)
+ if stop_event.is_set():
+ break
+ elapsed = time.monotonic() - t_start
+ total_reqs = sum(s.requests for s in all_stats)
+ total_errs = sum(s.errors for s in all_stats)
+ rps = total_reqs / elapsed if elapsed > 0 else 0.0
+ remain = max(0, duration - elapsed)
+ print(
+ f" t={elapsed:>5.1f}s {rps:>6.1f} RPS "
+ f"reqs={total_reqs} errs={total_errs} remain={remain:.0f}s"
+ )
+
+
+# ── Benchmark orchestrator ────────────────────────────────────────────────────
+
+
+async def run_benchmark(
+ n_sandboxes: int,
+ duration: float,
+ action: str,
+ image: Image,
+) -> BenchmarkResult:
+
+ # ── Provision ──────────────────────────────────────────────────────────
+ print(f"\n── Provisioning {n_sandboxes} sandbox(es) locally ──")
+ sandboxes, all_stats, provision_times = await _provision_fleet(image, n_sandboxes)
+
+ if not sandboxes:
+ raise RuntimeError("All sandboxes failed to provision — aborting benchmark.")
+
+ actual = len(sandboxes)
+ print(
+ f" {actual}/{n_sandboxes} provisioned | "
+ f"mean={statistics.mean(provision_times):.1f}s "
+ f"max={max(provision_times):.1f}s"
+ )
+
+ # ── Load test ─────────────────────────────────────────────────────────
+ stop_event = asyncio.Event()
+ t_start = time.monotonic()
+
+ global _t_bench_start
+ _t_bench_start = t_start
+
+ print(f"\n── Load test: max RPS × {duration}s ──\n action={action} sandboxes={actual}")
+
+ workers = [
+ asyncio.create_task(_worker(sb, st, stop_event, action))
+ for sb, st in zip(sandboxes, all_stats)
+ ]
+ reporter = asyncio.create_task(_progress_reporter(all_stats, t_start, duration, stop_event))
+
+ await asyncio.sleep(duration)
+ stop_event.set()
+
+ for w in workers:
+ w.cancel()
+ reporter.cancel()
+ await asyncio.gather(*workers, reporter, return_exceptions=True)
+
+ elapsed = time.monotonic() - t_start
+
+ # ── Cleanup ───────────────────────────────────────────────────────────
+ print(f"\n── Destroying {actual} sandbox(es) ──")
+ await _destroy_fleet(sandboxes)
+
+ # ── Aggregate ─────────────────────────────────────────────────────────
+ total_reqs = sum(s.requests for s in all_stats)
+ total_errs = sum(s.errors for s in all_stats)
+ all_latencies = [lat for s in all_stats for lat in s.latencies]
+ achieved_rps = total_reqs / elapsed if elapsed > 0 else 0.0
+
+ return BenchmarkResult(
+ achieved_rps=achieved_rps,
+ sandboxes=actual,
+ duration=elapsed,
+ total_requests=total_reqs,
+ total_errors=total_errs,
+ provision_times=provision_times,
+ all_latencies=all_latencies,
+ )
+
+
+# ── Report ────────────────────────────────────────────────────────────────────
+
+
+def print_report(result: BenchmarkResult) -> None:
+ bar = "─" * 58
+ print(f"\n{'═'*58}")
+ print(" Android Baremetal Benchmark (local)")
+ print(f"{'═'*58}")
+ print(f" {bar}")
+ print(" Throughput")
+ print(f" {'Achieved RPS':<24} {result.achieved_rps:.2f}")
+ print(f" {'RPS / sandbox':<24} {result.achieved_rps / max(result.sandboxes, 1):.2f}")
+ print(f" {'Sandboxes':<24} {result.sandboxes}")
+ print(f" {'Duration':<24} {result.duration:.1f}s")
+ print(f" {'Total requests':<24} {result.total_requests}")
+ print(f" {'Error rate':<24} {result.error_rate * 100:.1f}%")
+ print(f" {bar}")
+ print(" Provisioning")
+ print(f" {'Mean cold start':<24} {result.mean_provision:.1f}s")
+ if result.provision_times:
+ print(f" {'Max cold start':<24} {max(result.provision_times):.1f}s")
+ print(f" {bar}")
+ print(" Latency (successful requests)")
+ if result.all_latencies:
+ print(f" {'p50':<24} {result.p50 * 1000:.0f}ms")
+ print(f" {'p95':<24} {result.p95 * 1000:.0f}ms")
+ print(f" {'p99':<24} {result.p99 * 1000:.0f}ms")
+ else:
+ print(" (no successful requests)")
+ print(f"{'═'*58}\n")
+
+
+# ── CLI ───────────────────────────────────────────────────────────────────────
+
+
+def _parse_args() -> argparse.Namespace:
+ p = argparse.ArgumentParser(
+ description="Measure max RPS for local Android sandboxes (AndroidEmulatorRuntime).",
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ epilog="""
+Examples:
+ python tests/android_rps_benchmark_local.py --sandboxes 1 --duration 30
+ python tests/android_rps_benchmark_local.py --sandboxes 2 --duration 60 --action step
+ """,
+ )
+ p.add_argument(
+ "--sandboxes", type=int, default=1, help="Number of Android sandboxes (default: 1)."
+ )
+ p.add_argument(
+ "--duration", type=float, default=30.0, help="Load-test duration in seconds (default: 30)."
+ )
+ p.add_argument(
+ "--action",
+ choices=list(_ACTION_FNS),
+ default="screenshot",
+ help="'screenshot' = observation only; 'step' = tap + screenshot. Default: screenshot.",
+ )
+ p.add_argument("--android-version", default="14", help="Android version (default: 14).")
+ return p.parse_args()
+
+
+async def _main() -> None:
+ args = _parse_args()
+ image = Image.android(args.android_version)
+
+ print("Android Baremetal Benchmark (local)")
+ print(
+ f" sandboxes={args.sandboxes} duration={args.duration}s action={args.action} android={args.android_version}"
+ )
+
+ result = await run_benchmark(
+ n_sandboxes=args.sandboxes,
+ duration=args.duration,
+ action=args.action,
+ image=image,
+ )
+ print_report(result)
+
+
+if __name__ == "__main__":
+ asyncio.run(_main())
diff --git a/tests/cold_start_benchmark.py b/tests/cold_start_benchmark.py
new file mode 100644
index 0000000000..0d7fd0484a
--- /dev/null
+++ b/tests/cold_start_benchmark.py
@@ -0,0 +1,115 @@
+"""Cold start benchmark for cloud sandboxes.
+
+Measures provisioning time for each OS type across 2 attempts and
+exports results as GitHub Actions env vars for Slack notification.
+"""
+
+import asyncio
+import json
+import os
+import time
+import urllib.request
+
+from cua_sandbox import Image, Sandbox
+
+OS_CONFIGS = [
+ ("linux", Image.linux()),
+ ("android", Image.android("14")),
+]
+
+ATTEMPTS = 2
+
+
+async def measure_cold_start(image, timeout: float = 120) -> tuple[float | None, str | None]:
+ """Create an ephemeral sandbox and return (seconds, error)."""
+ t0 = time.time()
+ try:
+ async with Sandbox.ephemeral(image) as sb:
+ elapsed = time.time() - t0
+ # Quick health check
+ screenshot = await sb.screenshot()
+ if len(screenshot) < 500:
+ return elapsed, "screenshot too small"
+ return elapsed, None
+ except Exception as e:
+ return time.time() - t0, str(e)[:80]
+
+
+def color_for_time(seconds: float | None) -> str:
+ if seconds is None:
+ return "🔴"
+ if seconds < 15:
+ return "🟢"
+ if seconds < 60:
+ return "🟡"
+ return "🔴"
+
+
+def fmt(seconds: float | None, error: str | None) -> str:
+ if error:
+ return f"❌ {error}"
+ return f"{seconds:.1f}s"
+
+
+async def main():
+ results: dict[str, list[tuple[float | None, str | None]]] = {}
+
+ for os_name, image in OS_CONFIGS:
+ results[os_name] = []
+ for attempt in range(ATTEMPTS):
+ print(f"[{os_name}] attempt {attempt + 1}/{ATTEMPTS}...")
+ elapsed, error = await measure_cold_start(image)
+ results[os_name].append((elapsed, error))
+ if error:
+ print(f" ❌ {elapsed:.1f}s - {error}")
+ else:
+ print(f" ✅ {elapsed:.1f}s")
+
+ # Build Slack message as a table
+ lines = ["*☁️ Cloud Sandbox Cold Start Benchmark*\n"]
+ lines.append("```")
+ lines.append(f"{'OS':<12} {'Attempt 1':<20} {'Attempt 2':<20}")
+ lines.append(f"{'─'*12} {'─'*20} {'─'*20}")
+
+ worst_color = "#36a64f" # green
+ for os_name in [c[0] for c in OS_CONFIGS]:
+ cols = []
+ for elapsed, error in results[os_name]:
+ icon = color_for_time(elapsed if not error else None)
+ cols.append(f"{icon} {fmt(elapsed, error)}")
+ # Track worst color
+ if error:
+ worst_color = "#dc3545"
+ elif elapsed and elapsed >= 60 and worst_color != "#dc3545":
+ worst_color = "#ffa500"
+ elif elapsed and elapsed >= 15 and worst_color == "#36a64f":
+ worst_color = "#ffa500"
+ lines.append(f"{os_name:<12} {cols[0]:<20} {cols[1]:<20}")
+
+ lines.append("```")
+
+ msg = "\n".join(lines)
+ print(f"\n{msg}")
+
+ # Export to GitHub Actions
+ gh_env = os.environ.get("GITHUB_ENV")
+ if gh_env:
+ with open(gh_env, "a") as f:
+ f.write(f"SLACK_MESSAGE<<EOF\n{msg}\nEOF\n")
+ f.write(f"SLACK_COLOR={worst_color}\n")
+
+ # Send directly via webhook (local runs or CI with SLACK_WEBHOOK set)
+ webhook_url = os.environ.get("SLACK_WEBHOOK")
+ if webhook_url and not gh_env:
+ payload = json.dumps(
+ {"text": msg, "attachments": [{"color": worst_color, "text": ""}]}
+ ).encode()
+ req = urllib.request.Request(
+ webhook_url, data=payload, headers={"Content-Type": "application/json"}
+ )
+ with urllib.request.urlopen(req) as resp:
+ print(f"\nSlack webhook sent: {resp.status}")
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/uv.lock b/uv.lock
index 8064b7ce49..889b8cbb8e 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1,5 +1,5 @@
version = 1
-revision = 3
+revision = 2
requires-python = ">=3.12, <3.14"
resolution-markers = [
"python_full_version >= '3.13' and sys_platform == 'darwin'",
@@ -422,6 +422,15 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/54/51/321e821856452f7386c4e9df866f196720b1ad0c5ea1623ea7399969ae3b/authlib-1.6.6-py2.py3-none-any.whl", hash = "sha256:7d9e9bc535c13974313a87f53e8430eb6ea3d1cf6ae4f6efcd793f2e949143fd", size = 244005, upload-time = "2025-12-12T08:01:40.209Z" },
]
+[[package]]
+name = "automat"
+version = "25.4.16"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e3/0f/d40bbe294bbf004d436a8bcbcfaadca8b5140d39ad0ad3d73d1a8ba15f14/automat-25.4.16.tar.gz", hash = "sha256:0017591a5477066e90d26b0e696ddc143baafd87b588cfac8100bc6be9634de0", size = 129977, upload-time = "2025-04-16T20:12:16.002Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/02/ff/1175b0b7371e46244032d43a56862d0af455823b5280a50c63d99cc50f18/automat-25.4.16-py3-none-any.whl", hash = "sha256:04e9bce696a8d5671ee698005af6e5a9fa15354140a87f4870744604dcdd3ba1", size = 42842, upload-time = "2025-04-16T20:12:14.447Z" },
+]
+
[[package]]
name = "av"
version = "16.0.1"
@@ -851,6 +860,15 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/60/97/891a0971e1e4a8c5d2b20bbe0e524dc04548d2307fee33cdeba148fd4fc7/comm-0.2.3-py3-none-any.whl", hash = "sha256:c615d91d75f7f04f095b30d1c1711babd43bdc6419c1be9886a85f2f4e489417", size = 7294, upload-time = "2025-07-25T14:02:02.896Z" },
]
+[[package]]
+name = "constantly"
+version = "23.10.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/4d/6f/cb2a94494ff74aa9528a36c5b1422756330a75a8367bf20bd63171fc324d/constantly-23.10.4.tar.gz", hash = "sha256:aa92b70a33e2ac0bb33cd745eb61776594dc48764b06c35e0efd050b7f1c7cbd", size = 13300, upload-time = "2023-10-28T23:18:24.316Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/b8/40/c199d095151addf69efdb4b9ca3a4f20f70e20508d6222bffb9b76f58573/constantly-23.10.4-py3-none-any.whl", hash = "sha256:3fd9b4d1c3dc1ec9757f3c52aef7e53ad9323dbe39f51dfd4c43853b68dfa3f9", size = 13547, upload-time = "2023-10-28T23:18:23.038Z" },
+]
+
[[package]]
name = "contourpy"
version = "1.3.3"
@@ -1039,7 +1057,7 @@ wheels = [
[[package]]
name = "cua-agent"
-version = "0.7.29"
+version = "0.7.37"
source = { editable = "libs/python/agent" }
dependencies = [
{ name = "aiohttp" },
@@ -1077,6 +1095,13 @@ all = [
cli = [
{ name = "yaspin" },
]
+cloud = [
+ { name = "google-genai" },
+ { name = "pillow" },
+ { name = "qwen-agent" },
+ { name = "qwen-vl-utils" },
+ { name = "yaspin" },
+]
gemini = [
{ name = "google-genai" },
]
@@ -1148,23 +1173,27 @@ requires-dist = [
{ name = "einops", marker = "extra == 'all'" },
{ name = "einops", marker = "extra == 'internvl-hf'" },
{ name = "google-genai", marker = "extra == 'all'", specifier = ">=1.41.0" },
+ { name = "google-genai", marker = "extra == 'cloud'", specifier = ">=1.41.0" },
{ name = "google-genai", marker = "extra == 'gemini'", specifier = ">=1.41.0" },
{ name = "gradio", marker = "extra == 'all'", specifier = ">=6.0.0" },
{ name = "gradio", marker = "extra == 'ui'", specifier = ">=6.0.0" },
{ name = "httpx", specifier = ">=0.27.0" },
{ name = "hud-python", marker = "extra == 'hud'", specifier = "==0.4.52" },
- { name = "litellm", specifier = ">=1.74.12" },
+ { 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", 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" },
{ name = "pydantic", specifier = ">=2.6.4" },
{ name = "python-dotenv", specifier = ">=1.0.1" },
{ name = "python-dotenv", marker = "extra == 'all'", specifier = ">=1.0.1" },
{ name = "python-dotenv", marker = "extra == 'ui'", specifier = ">=1.0.1" },
{ name = "qwen-agent", marker = "extra == 'all'" },
+ { name = "qwen-agent", marker = "extra == 'cloud'" },
{ name = "qwen-agent", marker = "extra == 'qwen'" },
{ name = "qwen-vl-utils", marker = "extra == 'all'" },
+ { name = "qwen-vl-utils", marker = "extra == 'cloud'" },
{ name = "qwen-vl-utils", marker = "extra == 'qwen'" },
{ name = "rich", specifier = ">=13.7.1" },
{ name = "tiktoken", marker = "extra == 'all'", specifier = ">=0.11.0" },
@@ -1186,12 +1215,13 @@ requires-dist = [
{ name = "typing-extensions", specifier = ">=4.12.2" },
{ name = "yaspin", marker = "extra == 'all'", specifier = ">=3.1.0" },
{ name = "yaspin", marker = "extra == 'cli'", specifier = ">=3.1.0" },
+ { name = "yaspin", marker = "extra == 'cloud'", specifier = ">=3.1.0" },
]
-provides-extras = ["openai", "anthropic", "qwen", "omni", "uitars", "uitars-mlx", "uitars-hf", "glm45v-hf", "opencua-hf", "internvl-hf", "moondream3", "ui", "cli", "hud", "gemini", "all"]
+provides-extras = ["openai", "anthropic", "qwen", "omni", "uitars", "uitars-mlx", "uitars-hf", "glm45v-hf", "opencua-hf", "internvl-hf", "moondream3", "ui", "cli", "hud", "gemini", "cloud", "all"]
[[package]]
name = "cua-auto"
-version = "0.1.1"
+version = "0.1.2"
source = { editable = "libs/python/cua-auto" }
dependencies = [
{ name = "pillow" },
@@ -1235,7 +1265,7 @@ requires-dist = [
[[package]]
name = "cua-computer"
-version = "0.5.16"
+version = "0.5.17"
source = { editable = "libs/python/computer" }
dependencies = [
{ name = "aiohttp" },
@@ -1279,7 +1309,7 @@ provides-extras = ["lume", "lumier", "ui", "all"]
[[package]]
name = "cua-computer-server"
-version = "0.3.19"
+version = "0.3.27"
source = { editable = "libs/python/computer-server" }
dependencies = [
{ name = "aiohttp" },
@@ -1312,6 +1342,9 @@ macos = [
{ name = "pyobjc-framework-cocoa" },
{ name = "pyobjc-framework-quartz" },
]
+vnc = [
+ { name = "vncdotool" },
+]
windows = [
{ name = "pywin32" },
]
@@ -1341,9 +1374,10 @@ requires-dist = [
{ name = "pywin32", marker = "extra == 'windows'", specifier = ">=310" },
{ name = "pywinctl", specifier = ">=0.4.1" },
{ name = "uvicorn", extras = ["standard"], specifier = ">=0.27.0" },
+ { name = "vncdotool", marker = "extra == 'vnc'", specifier = ">=1.2.0" },
{ name = "websockets", specifier = ">=12.0" },
]
-provides-extras = ["macos", "linux", "windows"]
+provides-extras = ["macos", "linux", "windows", "vnc"]
[[package]]
name = "cua-core"
@@ -2266,6 +2300,7 @@ dependencies = [
{ name = "griffecli" },
{ name = "griffelib" },
]
+sdist = { url = "https://files.pythonhosted.org/packages/04/56/28a0accac339c164b52a92c6cfc45a903acc0c174caa5c1713803467b533/griffe-2.0.0.tar.gz", hash = "sha256:c68979cd8395422083a51ea7cf02f9c119d889646d99b7b656ee43725de1b80f", size = 293906, upload-time = "2026-03-23T21:06:53.402Z" }
wheels = [
{ url = "https://files.pythonhosted.org/packages/8b/94/ee21d41e7eb4f823b94603b9d40f86d3c7fde80eacc2c3c71845476dddaa/griffe-2.0.0-py3-none-any.whl", hash = "sha256:5418081135a391c3e6e757a7f3f156f1a1a746cc7b4023868ff7d5e2f9a980aa", size = 5214, upload-time = "2026-02-09T19:09:44.105Z" },
]
@@ -2278,6 +2313,7 @@ dependencies = [
{ name = "colorama" },
{ name = "griffelib" },
]
+sdist = { url = "https://files.pythonhosted.org/packages/a4/f8/2e129fd4a86e52e58eefe664de05e7d502decf766e7316cc9e70fdec3e18/griffecli-2.0.0.tar.gz", hash = "sha256:312fa5ebb4ce6afc786356e2d0ce85b06c1c20d45abc42d74f0cda65e159f6ef", size = 56213, upload-time = "2026-03-23T21:06:54.8Z" }
wheels = [
{ url = "https://files.pythonhosted.org/packages/e6/ed/d93f7a447bbf7a935d8868e9617cbe1cadf9ee9ee6bd275d3040fbf93d60/griffecli-2.0.0-py3-none-any.whl", hash = "sha256:9f7cd9ee9b21d55e91689358978d2385ae65c22f307a63fb3269acf3f21e643d", size = 9345, upload-time = "2026-02-09T19:09:42.554Z" },
]
@@ -2286,6 +2322,7 @@ wheels = [
name = "griffelib"
version = "2.0.0"
source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/ad/06/eccbd311c9e2b3ca45dbc063b93134c57a1ccc7607c5e545264ad092c4a9/griffelib-2.0.0.tar.gz", hash = "sha256:e504d637a089f5cab9b5daf18f7645970509bf4f53eda8d79ed71cce8bd97934", size = 166312, upload-time = "2026-03-23T21:06:55.954Z" }
wheels = [
{ url = "https://files.pythonhosted.org/packages/4d/51/c936033e16d12b627ea334aaaaf42229c37620d0f15593456ab69ab48161/griffelib-2.0.0-py3-none-any.whl", hash = "sha256:01284878c966508b6d6f1dbff9b6fa607bc062d8261c5c7253cb285b06422a7f", size = 142004, upload-time = "2026-02-09T19:09:40.561Z" },
]
@@ -2301,33 +2338,33 @@ wheels = [
[[package]]
name = "grpcio"
-version = "1.76.0"
+version = "1.78.0"
source = { registry = "https://pypi.org/simple" }
dependencies = [
{ name = "typing-extensions" },
]
-sdist = { url = "https://files.pythonhosted.org/packages/b6/e0/318c1ce3ae5a17894d5791e87aea147587c9e702f24122cc7a5c8bbaeeb1/grpcio-1.76.0.tar.gz", hash = "sha256:7be78388d6da1a25c0d5ec506523db58b18be22d9c37d8d3a32c08be4987bd73", size = 12785182, upload-time = "2025-10-21T16:23:12.106Z" }
-wheels = [
- { url = "https://files.pythonhosted.org/packages/bf/05/8e29121994b8d959ffa0afd28996d452f291b48cfc0875619de0bde2c50c/grpcio-1.76.0-cp312-cp312-linux_armv7l.whl", hash = "sha256:81fd9652b37b36f16138611c7e884eb82e0cec137c40d3ef7c3f9b3ed00f6ed8", size = 5799718, upload-time = "2025-10-21T16:21:17.939Z" },
- { url = "https://files.pythonhosted.org/packages/d9/75/11d0e66b3cdf998c996489581bdad8900db79ebd83513e45c19548f1cba4/grpcio-1.76.0-cp312-cp312-macosx_11_0_universal2.whl", hash = "sha256:04bbe1bfe3a68bbfd4e52402ab7d4eb59d72d02647ae2042204326cf4bbad280", size = 11825627, upload-time = "2025-10-21T16:21:20.466Z" },
- { url = "https://files.pythonhosted.org/packages/28/50/2f0aa0498bc188048f5d9504dcc5c2c24f2eb1a9337cd0fa09a61a2e75f0/grpcio-1.76.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:d388087771c837cdb6515539f43b9d4bf0b0f23593a24054ac16f7a960be16f4", size = 6359167, upload-time = "2025-10-21T16:21:23.122Z" },
- { url = "https://files.pythonhosted.org/packages/66/e5/bbf0bb97d29ede1d59d6588af40018cfc345b17ce979b7b45424628dc8bb/grpcio-1.76.0-cp312-cp312-manylinux2014_i686.manylinux_2_17_i686.whl", hash = "sha256:9f8f757bebaaea112c00dba718fc0d3260052ce714e25804a03f93f5d1c6cc11", size = 7044267, upload-time = "2025-10-21T16:21:25.995Z" },
- { url = "https://files.pythonhosted.org/packages/f5/86/f6ec2164f743d9609691115ae8ece098c76b894ebe4f7c94a655c6b03e98/grpcio-1.76.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:980a846182ce88c4f2f7e2c22c56aefd515daeb36149d1c897f83cf57999e0b6", size = 6573963, upload-time = "2025-10-21T16:21:28.631Z" },
- { url = "https://files.pythonhosted.org/packages/60/bc/8d9d0d8505feccfdf38a766d262c71e73639c165b311c9457208b56d92ae/grpcio-1.76.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:f92f88e6c033db65a5ae3d97905c8fea9c725b63e28d5a75cb73b49bda5024d8", size = 7164484, upload-time = "2025-10-21T16:21:30.837Z" },
- { url = "https://files.pythonhosted.org/packages/67/e6/5d6c2fc10b95edf6df9b8f19cf10a34263b7fd48493936fffd5085521292/grpcio-1.76.0-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:4baf3cbe2f0be3289eb68ac8ae771156971848bb8aaff60bad42005539431980", size = 8127777, upload-time = "2025-10-21T16:21:33.577Z" },
- { url = "https://files.pythonhosted.org/packages/3f/c8/dce8ff21c86abe025efe304d9e31fdb0deaaa3b502b6a78141080f206da0/grpcio-1.76.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:615ba64c208aaceb5ec83bfdce7728b80bfeb8be97562944836a7a0a9647d882", size = 7594014, upload-time = "2025-10-21T16:21:41.882Z" },
- { url = "https://files.pythonhosted.org/packages/e0/42/ad28191ebf983a5d0ecef90bab66baa5a6b18f2bfdef9d0a63b1973d9f75/grpcio-1.76.0-cp312-cp312-win32.whl", hash = "sha256:45d59a649a82df5718fd9527ce775fd66d1af35e6d31abdcdc906a49c6822958", size = 3984750, upload-time = "2025-10-21T16:21:44.006Z" },
- { url = "https://files.pythonhosted.org/packages/9e/00/7bd478cbb851c04a48baccaa49b75abaa8e4122f7d86da797500cccdd771/grpcio-1.76.0-cp312-cp312-win_amd64.whl", hash = "sha256:c088e7a90b6017307f423efbb9d1ba97a22aa2170876223f9709e9d1de0b5347", size = 4704003, upload-time = "2025-10-21T16:21:46.244Z" },
- { url = "https://files.pythonhosted.org/packages/fc/ed/71467ab770effc9e8cef5f2e7388beb2be26ed642d567697bb103a790c72/grpcio-1.76.0-cp313-cp313-linux_armv7l.whl", hash = "sha256:26ef06c73eb53267c2b319f43e6634c7556ea37672029241a056629af27c10e2", size = 5807716, upload-time = "2025-10-21T16:21:48.475Z" },
- { url = "https://files.pythonhosted.org/packages/2c/85/c6ed56f9817fab03fa8a111ca91469941fb514e3e3ce6d793cb8f1e1347b/grpcio-1.76.0-cp313-cp313-macosx_11_0_universal2.whl", hash = "sha256:45e0111e73f43f735d70786557dc38141185072d7ff8dc1829d6a77ac1471468", size = 11821522, upload-time = "2025-10-21T16:21:51.142Z" },
- { url = "https://files.pythonhosted.org/packages/ac/31/2b8a235ab40c39cbc141ef647f8a6eb7b0028f023015a4842933bc0d6831/grpcio-1.76.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:83d57312a58dcfe2a3a0f9d1389b299438909a02db60e2f2ea2ae2d8034909d3", size = 6362558, upload-time = "2025-10-21T16:21:54.213Z" },
- { url = "https://files.pythonhosted.org/packages/bd/64/9784eab483358e08847498ee56faf8ff6ea8e0a4592568d9f68edc97e9e9/grpcio-1.76.0-cp313-cp313-manylinux2014_i686.manylinux_2_17_i686.whl", hash = "sha256:3e2a27c89eb9ac3d81ec8835e12414d73536c6e620355d65102503064a4ed6eb", size = 7049990, upload-time = "2025-10-21T16:21:56.476Z" },
- { url = "https://files.pythonhosted.org/packages/2b/94/8c12319a6369434e7a184b987e8e9f3b49a114c489b8315f029e24de4837/grpcio-1.76.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:61f69297cba3950a524f61c7c8ee12e55c486cb5f7db47ff9dcee33da6f0d3ae", size = 6575387, upload-time = "2025-10-21T16:21:59.051Z" },
- { url = "https://files.pythonhosted.org/packages/15/0f/f12c32b03f731f4a6242f771f63039df182c8b8e2cf8075b245b409259d4/grpcio-1.76.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:6a15c17af8839b6801d554263c546c69c4d7718ad4321e3166175b37eaacca77", size = 7166668, upload-time = "2025-10-21T16:22:02.049Z" },
- { url = "https://files.pythonhosted.org/packages/ff/2d/3ec9ce0c2b1d92dd59d1c3264aaec9f0f7c817d6e8ac683b97198a36ed5a/grpcio-1.76.0-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:25a18e9810fbc7e7f03ec2516addc116a957f8cbb8cbc95ccc80faa072743d03", size = 8124928, upload-time = "2025-10-21T16:22:04.984Z" },
- { url = "https://files.pythonhosted.org/packages/1a/74/fd3317be5672f4856bcdd1a9e7b5e17554692d3db9a3b273879dc02d657d/grpcio-1.76.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:931091142fd8cc14edccc0845a79248bc155425eee9a98b2db2ea4f00a235a42", size = 7589983, upload-time = "2025-10-21T16:22:07.881Z" },
- { url = "https://files.pythonhosted.org/packages/45/bb/ca038cf420f405971f19821c8c15bcbc875505f6ffadafe9ffd77871dc4c/grpcio-1.76.0-cp313-cp313-win32.whl", hash = "sha256:5e8571632780e08526f118f74170ad8d50fb0a48c23a746bef2a6ebade3abd6f", size = 3984727, upload-time = "2025-10-21T16:22:10.032Z" },
- { url = "https://files.pythonhosted.org/packages/41/80/84087dc56437ced7cdd4b13d7875e7439a52a261e3ab4e06488ba6173b0a/grpcio-1.76.0-cp313-cp313-win_amd64.whl", hash = "sha256:f9f7bd5faab55f47231ad8dba7787866b69f5e93bc306e3915606779bbfb4ba8", size = 4702799, upload-time = "2025-10-21T16:22:12.709Z" },
+sdist = { url = "https://files.pythonhosted.org/packages/06/8a/3d098f35c143a89520e568e6539cc098fcd294495910e359889ce8741c84/grpcio-1.78.0.tar.gz", hash = "sha256:7382b95189546f375c174f53a5fa873cef91c4b8005faa05cc5b3beea9c4f1c5", size = 12852416, upload-time = "2026-02-06T09:57:18.093Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/4e/f4/7384ed0178203d6074446b3c4f46c90a22ddf7ae0b3aee521627f54cfc2a/grpcio-1.78.0-cp312-cp312-linux_armv7l.whl", hash = "sha256:f9ab915a267fc47c7e88c387a3a28325b58c898e23d4995f765728f4e3dedb97", size = 5913985, upload-time = "2026-02-06T09:55:26.832Z" },
+ { url = "https://files.pythonhosted.org/packages/81/ed/be1caa25f06594463f685b3790b320f18aea49b33166f4141bfdc2bfb236/grpcio-1.78.0-cp312-cp312-macosx_11_0_universal2.whl", hash = "sha256:3f8904a8165ab21e07e58bf3e30a73f4dffc7a1e0dbc32d51c61b5360d26f43e", size = 11811853, upload-time = "2026-02-06T09:55:29.224Z" },
+ { url = "https://files.pythonhosted.org/packages/24/a7/f06d151afc4e64b7e3cc3e872d331d011c279aaab02831e40a81c691fb65/grpcio-1.78.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:859b13906ce098c0b493af92142ad051bf64c7870fa58a123911c88606714996", size = 6475766, upload-time = "2026-02-06T09:55:31.825Z" },
+ { url = "https://files.pythonhosted.org/packages/8a/a8/4482922da832ec0082d0f2cc3a10976d84a7424707f25780b82814aafc0a/grpcio-1.78.0-cp312-cp312-manylinux2014_i686.manylinux_2_17_i686.whl", hash = "sha256:b2342d87af32790f934a79c3112641e7b27d63c261b8b4395350dad43eff1dc7", size = 7170027, upload-time = "2026-02-06T09:55:34.7Z" },
+ { url = "https://files.pythonhosted.org/packages/54/bf/f4a3b9693e35d25b24b0b39fa46d7d8a3c439e0a3036c3451764678fec20/grpcio-1.78.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:12a771591ae40bc65ba67048fa52ef4f0e6db8279e595fd349f9dfddeef571f9", size = 6690766, upload-time = "2026-02-06T09:55:36.902Z" },
+ { url = "https://files.pythonhosted.org/packages/c7/b9/521875265cc99fe5ad4c5a17010018085cae2810a928bf15ebe7d8bcd9cc/grpcio-1.78.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:185dea0d5260cbb2d224c507bf2a5444d5abbb1fa3594c1ed7e4c709d5eb8383", size = 7266161, upload-time = "2026-02-06T09:55:39.824Z" },
+ { url = "https://files.pythonhosted.org/packages/05/86/296a82844fd40a4ad4a95f100b55044b4f817dece732bf686aea1a284147/grpcio-1.78.0-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:51b13f9aed9d59ee389ad666b8c2214cc87b5de258fa712f9ab05f922e3896c6", size = 8253303, upload-time = "2026-02-06T09:55:42.353Z" },
+ { url = "https://files.pythonhosted.org/packages/f3/e4/ea3c0caf5468537f27ad5aab92b681ed7cc0ef5f8c9196d3fd42c8c2286b/grpcio-1.78.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:fd5f135b1bd58ab088930b3c613455796dfa0393626a6972663ccdda5b4ac6ce", size = 7698222, upload-time = "2026-02-06T09:55:44.629Z" },
+ { url = "https://files.pythonhosted.org/packages/d7/47/7f05f81e4bb6b831e93271fb12fd52ba7b319b5402cbc101d588f435df00/grpcio-1.78.0-cp312-cp312-win32.whl", hash = "sha256:94309f498bcc07e5a7d16089ab984d42ad96af1d94b5a4eb966a266d9fcabf68", size = 4066123, upload-time = "2026-02-06T09:55:47.644Z" },
+ { url = "https://files.pythonhosted.org/packages/ad/e7/d6914822c88aa2974dbbd10903d801a28a19ce9cd8bad7e694cbbcf61528/grpcio-1.78.0-cp312-cp312-win_amd64.whl", hash = "sha256:9566fe4ababbb2610c39190791e5b829869351d14369603702e890ef3ad2d06e", size = 4797657, upload-time = "2026-02-06T09:55:49.86Z" },
+ { url = "https://files.pythonhosted.org/packages/05/a9/8f75894993895f361ed8636cd9237f4ab39ef87fd30db17467235ed1c045/grpcio-1.78.0-cp313-cp313-linux_armv7l.whl", hash = "sha256:ce3a90455492bf8bfa38e56fbbe1dbd4f872a3d8eeaf7337dc3b1c8aa28c271b", size = 5920143, upload-time = "2026-02-06T09:55:52.035Z" },
+ { url = "https://files.pythonhosted.org/packages/55/06/0b78408e938ac424100100fd081189451b472236e8a3a1f6500390dc4954/grpcio-1.78.0-cp313-cp313-macosx_11_0_universal2.whl", hash = "sha256:2bf5e2e163b356978b23652c4818ce4759d40f4712ee9ec5a83c4be6f8c23a3a", size = 11803926, upload-time = "2026-02-06T09:55:55.494Z" },
+ { url = "https://files.pythonhosted.org/packages/88/93/b59fe7832ff6ae3c78b813ea43dac60e295fa03606d14d89d2e0ec29f4f3/grpcio-1.78.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:8f2ac84905d12918e4e55a16da17939eb63e433dc11b677267c35568aa63fc84", size = 6478628, upload-time = "2026-02-06T09:55:58.533Z" },
+ { url = "https://files.pythonhosted.org/packages/ed/df/e67e3734527f9926b7d9c0dde6cd998d1d26850c3ed8eeec81297967ac67/grpcio-1.78.0-cp313-cp313-manylinux2014_i686.manylinux_2_17_i686.whl", hash = "sha256:b58f37edab4a3881bc6c9bca52670610e0c9ca14e2ea3cf9debf185b870457fb", size = 7173574, upload-time = "2026-02-06T09:56:01.786Z" },
+ { url = "https://files.pythonhosted.org/packages/a6/62/cc03fffb07bfba982a9ec097b164e8835546980aec25ecfa5f9c1a47e022/grpcio-1.78.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:735e38e176a88ce41840c21bb49098ab66177c64c82426e24e0082500cc68af5", size = 6692639, upload-time = "2026-02-06T09:56:04.529Z" },
+ { url = "https://files.pythonhosted.org/packages/bf/9a/289c32e301b85bdb67d7ec68b752155e674ee3ba2173a1858f118e399ef3/grpcio-1.78.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:2045397e63a7a0ee7957c25f7dbb36ddc110e0cfb418403d110c0a7a68a844e9", size = 7268838, upload-time = "2026-02-06T09:56:08.397Z" },
+ { url = "https://files.pythonhosted.org/packages/0e/79/1be93f32add280461fa4773880196572563e9c8510861ac2da0ea0f892b6/grpcio-1.78.0-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:a9f136fbafe7ccf4ac7e8e0c28b31066e810be52d6e344ef954a3a70234e1702", size = 8251878, upload-time = "2026-02-06T09:56:10.914Z" },
+ { url = "https://files.pythonhosted.org/packages/65/65/793f8e95296ab92e4164593674ae6291b204bb5f67f9d4a711489cd30ffa/grpcio-1.78.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:748b6138585379c737adc08aeffd21222abbda1a86a0dca2a39682feb9196c20", size = 7695412, upload-time = "2026-02-06T09:56:13.593Z" },
+ { url = "https://files.pythonhosted.org/packages/1c/9f/1e233fe697ecc82845942c2822ed06bb522e70d6771c28d5528e4c50f6a4/grpcio-1.78.0-cp313-cp313-win32.whl", hash = "sha256:271c73e6e5676afe4fc52907686670c7cea22ab2310b76a59b678403ed40d670", size = 4064899, upload-time = "2026-02-06T09:56:15.601Z" },
+ { url = "https://files.pythonhosted.org/packages/4d/27/d86b89e36de8a951501fb06a0f38df19853210f341d0b28f83f4aa0ffa08/grpcio-1.78.0-cp313-cp313-win_amd64.whl", hash = "sha256:f2d4e43ee362adfc05994ed479334d5a451ab7bc3f3fee1b796b8ca66895acb4", size = 4797393, upload-time = "2026-02-06T09:56:17.882Z" },
]
[[package]]
@@ -2637,6 +2674,18 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/48/30/47d0bf6072f7252e6521f3447ccfa40b421b6824517f82854703d0f5a98b/hyperframe-6.1.0-py3-none-any.whl", hash = "sha256:b03380493a519fce58ea5af42e4a42317bf9bd425596f7a0835ffce80f1a42e5", size = 13007, upload-time = "2025-01-22T21:41:47.295Z" },
]
+[[package]]
+name = "hyperlink"
+version = "21.0.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "idna" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/3a/51/1947bd81d75af87e3bb9e34593a4cf118115a8feb451ce7a69044ef1412e/hyperlink-21.0.0.tar.gz", hash = "sha256:427af957daa58bc909471c6c40f74c5450fa123dd093fc53efd2e91d2705a56b", size = 140743, upload-time = "2021-01-08T05:51:20.972Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/6e/aa/8caf6a0a3e62863cbb9dab27135660acba46903b703e224f14f447e57934/hyperlink-21.0.0-py2.py3-none-any.whl", hash = "sha256:e6b14c37ecb73e89c77d78cdb4c2cc8f3fb59a885c5b3f819ff4ed80f25af1b4", size = 74638, upload-time = "2021-01-08T05:51:22.906Z" },
+]
+
[[package]]
name = "identify"
version = "2.6.15"
@@ -2721,6 +2770,18 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/fa/5e/f8e9a1d23b9c20a551a8a02ea3637b4642e22c2626e3a13a9a29cdea99eb/importlib_metadata-8.7.1-py3-none-any.whl", hash = "sha256:5a1f80bf1daa489495071efbb095d75a634cf28a8bc299581244063b53176151", size = 27865, upload-time = "2025-12-21T10:00:18.329Z" },
]
+[[package]]
+name = "incremental"
+version = "24.11.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "packaging" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/ef/3c/82e84109e02c492f382c711c58a3dd91badda6d746def81a1465f74dc9f5/incremental-24.11.0.tar.gz", hash = "sha256:87d3480dbb083c1d736222511a8cf380012a8176c2456d01ef483242abbbcf8c", size = 24000, upload-time = "2025-11-28T02:30:17.861Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/1d/55/0f4df2a44053867ea9cbea73fc588b03c55605cd695cee0a3d86f0029cb2/incremental-24.11.0-py3-none-any.whl", hash = "sha256:a34450716b1c4341fe6676a0598e88a39e04189f4dce5dc96f656e040baa10b3", size = 21109, upload-time = "2025-11-28T02:30:16.442Z" },
+]
+
[[package]]
name = "iniconfig"
version = "2.3.0"
@@ -9984,6 +10045,24 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/37/92/e97fcc6b2c27cdb87ce5ee063d77f8f26f19f06916aa680464c8104ef0f6/triton-3.5.1-cp313-cp313t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0b4d2c70127fca6a23e247f9348b8adde979d2e7a20391bfbabaac6aebc7e6a8", size = 170579924, upload-time = "2025-11-11T17:41:12.455Z" },
]
+[[package]]
+name = "twisted"
+version = "25.5.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "attrs" },
+ { name = "automat" },
+ { name = "constantly" },
+ { name = "hyperlink" },
+ { name = "incremental" },
+ { name = "typing-extensions" },
+ { name = "zope-interface" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/13/0f/82716ed849bf7ea4984c21385597c949944f0f9b428b5710f79d0afc084d/twisted-25.5.0.tar.gz", hash = "sha256:1deb272358cb6be1e3e8fc6f9c8b36f78eb0fa7c2233d2dbe11ec6fee04ea316", size = 3545725, upload-time = "2025-06-07T09:52:24.858Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/eb/66/ab7efd8941f0bc7b2bd555b0f0471bff77df4c88e0cc31120c82737fec77/twisted-25.5.0-py3-none-any.whl", hash = "sha256:8559f654d01a54a8c3efe66d533d43f383531ebf8d81d9f9ab4769d91ca15df7", size = 3204767, upload-time = "2025-06-07T09:52:21.428Z" },
+]
+
[[package]]
name = "typer"
version = "0.21.0"
@@ -10215,6 +10294,17 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/79/0c/c05523fa3181fdf0c9c52a6ba91a23fbf3246cc095f26f6516f9c60e6771/virtualenv-20.35.4-py3-none-any.whl", hash = "sha256:c21c9cede36c9753eeade68ba7d523529f228a403463376cf821eaae2b650f1b", size = 6005095, upload-time = "2025-10-29T06:57:37.598Z" },
]
+[[package]]
+name = "vncdotool"
+version = "1.2.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pillow" },
+ { name = "pycryptodomex" },
+ { name = "twisted" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/64/68/d43c145f110fbc7da6cbd4082d940fdbc8aaa7d9e8b52f3f574485d49208/vncdotool-1.2.0.tar.gz", hash = "sha256:53408d18ca7f9f21c525fc88189b01ca6594153ec1a9be09f6198306d166ea0d", size = 54809, upload-time = "2023-07-06T18:00:43.146Z" }
+
[[package]]
name = "watchdog"
version = "6.0.0"
@@ -10539,6 +10629,26 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/2e/54/647ade08bf0db230bfea292f893923872fd20be6ac6f53b2b936ba839d75/zipp-3.23.0-py3-none-any.whl", hash = "sha256:071652d6115ed432f5ce1d34c336c0adfd6a884660d1e9712a256d3d3bd4b14e", size = 10276, upload-time = "2025-06-08T17:06:38.034Z" },
]
+[[package]]
+name = "zope-interface"
+version = "8.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/86/a4/77daa5ba398996d16bb43fc721599d27d03eae68fe3c799de1963c72e228/zope_interface-8.2.tar.gz", hash = "sha256:afb20c371a601d261b4f6edb53c3c418c249db1a9717b0baafc9a9bb39ba1224", size = 254019, upload-time = "2026-01-09T07:51:07.253Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/e0/a0/1e1fabbd2e9c53ef92b69df6d14f4adc94ec25583b1380336905dc37e9a0/zope_interface-8.2-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:624b6787fc7c3e45fa401984f6add2c736b70a7506518c3b537ffaacc4b29d4c", size = 208785, upload-time = "2026-01-09T08:05:17.348Z" },
+ { url = "https://files.pythonhosted.org/packages/c3/2a/88d098a06975c722a192ef1fb7d623d1b57c6a6997cf01a7aabb45ab1970/zope_interface-8.2-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:bc9ded9e97a0ed17731d479596ed1071e53b18e6fdb2fc33af1e43f5fd2d3aaa", size = 208976, upload-time = "2026-01-09T08:05:18.792Z" },
+ { url = "https://files.pythonhosted.org/packages/e9/e8/757398549fdfd2f8c89f32c82ae4d2f0537ae2a5d2f21f4a2f711f5a059f/zope_interface-8.2-cp312-cp312-manylinux1_i686.manylinux2014_i686.manylinux_2_17_i686.manylinux_2_5_i686.whl", hash = "sha256:532367553e4420c80c0fc0cabcc2c74080d495573706f66723edee6eae53361d", size = 259411, upload-time = "2026-01-09T08:05:20.567Z" },
+ { url = "https://files.pythonhosted.org/packages/91/af/502601f0395ce84dff622f63cab47488657a04d0065547df42bee3a680ff/zope_interface-8.2-cp312-cp312-manylinux1_x86_64.manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:2bf9cf275468bafa3c72688aad8cfcbe3d28ee792baf0b228a1b2d93bd1d541a", size = 264859, upload-time = "2026-01-09T08:05:22.234Z" },
+ { url = "https://files.pythonhosted.org/packages/89/0c/d2f765b9b4814a368a7c1b0ac23b68823c6789a732112668072fe596945d/zope_interface-8.2-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:0009d2d3c02ea783045d7804da4fd016245e5c5de31a86cebba66dd6914d59a2", size = 264398, upload-time = "2026-01-09T08:05:23.853Z" },
+ { url = "https://files.pythonhosted.org/packages/4a/81/2f171fbc4222066957e6b9220c4fb9146792540102c37e6d94e5d14aad97/zope_interface-8.2-cp312-cp312-win_amd64.whl", hash = "sha256:845d14e580220ae4544bd4d7eb800f0b6034fe5585fc2536806e0a26c2ee6640", size = 212444, upload-time = "2026-01-09T08:05:25.148Z" },
+ { url = "https://files.pythonhosted.org/packages/66/47/45188fb101fa060b20e6090e500682398ab415e516a0c228fbb22bc7def2/zope_interface-8.2-cp313-cp313-macosx_10_9_x86_64.whl", hash = "sha256:6068322004a0158c80dfd4708dfb103a899635408c67c3b10e9acec4dbacefec", size = 209170, upload-time = "2026-01-09T08:05:26.616Z" },
+ { url = "https://files.pythonhosted.org/packages/09/03/f6b9336c03c2b48403c4eb73a1ec961d94dc2fb5354c583dfb5fa05fd41f/zope_interface-8.2-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:2499de92e8275d0dd68f84425b3e19e9268cd1fa8507997900fa4175f157733c", size = 209229, upload-time = "2026-01-09T08:05:28.521Z" },
+ { url = "https://files.pythonhosted.org/packages/07/b1/65fe1dca708569f302ade02e6cdca309eab6752bc9f80105514f5b708651/zope_interface-8.2-cp313-cp313-manylinux1_i686.manylinux2014_i686.manylinux_2_17_i686.manylinux_2_5_i686.whl", hash = "sha256:f777e68c76208503609c83ca021a6864902b646530a1a39abb9ed310d1100664", size = 259393, upload-time = "2026-01-09T08:05:29.897Z" },
+ { url = "https://files.pythonhosted.org/packages/eb/a5/97b49cfceb6ed53d3dcfb3f3ebf24d83b5553194f0337fbbb3a9fec6cf78/zope_interface-8.2-cp313-cp313-manylinux1_x86_64.manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:9b05a919fdb0ed6ea942e5a7800e09a8b6cdae6f98fee1bef1c9d1a3fc43aaa0", size = 264863, upload-time = "2026-01-09T08:05:31.501Z" },
+ { url = "https://files.pythonhosted.org/packages/cb/02/0b7a77292810efe3a0586a505b077ebafd5114e10c6e6e659f0c8e387e1f/zope_interface-8.2-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:ccc62b5712dd7bd64cfba3ee63089fb11e840f5914b990033beeae3b2180b6cb", size = 264369, upload-time = "2026-01-09T08:05:32.941Z" },
+ { url = "https://files.pythonhosted.org/packages/fb/1d/0d1ff3846302ed1b5bbf659316d8084b30106770a5f346b7ff4e9f540f80/zope_interface-8.2-cp313-cp313-win_amd64.whl", hash = "sha256:34f877d1d3bb7565c494ed93828fa6417641ca26faf6e8f044e0d0d500807028", size = 212447, upload-time = "2026-01-09T08:05:35.064Z" },
+]
+
[[package]]
name = "zstandard"
version = "0.25.0"