Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
"""Sandbox class — the primary entry point for sandboxed environments.
Exposes .mouse, .keyboard, .screen, .clipboard, .shell, .window, .terminal
as interface objects backed by a Transport.
cua-sandbox is a thin wrapper over the ``cua`` SDK: the Docker/QEMU/Lume
runtimes and cua-spacesd (the interfaces) go through it. Sandboxes are
daemon-agnostic: creating, connecting and deleting one never
assumes a guest agent; the interfaces use cua-spacesd when the image has it
and an agentless path (QMP, VNC, SSH, ADB) otherwise.
Usage::
from cua_sandbox import Image, Sandbox, http
sb = await Sandbox.create(
Image.from_registry("python:3.12-slim"),
command=["python", "-m", "my_mcp", "--port", "8765"],
services={"mcp": 8765},
wait_for=http("mcp", "/health"),
on="local",
kind="container", # "auto" | "container" | "vm"
runtime="gvisor", # the engine: "auto", gvisor, runc, qemu, lume
)
r = await sb.service("mcp").request("POST", "/mcp", json={...}, headers={...})
url = await sb.public_url("mcp", ttl=3600)
await sb.destroy()
# Connect to an existing sandbox by name (plain await or async with)
sb = await Sandbox.connect("my-sandbox")
# ...or to any reachable cua-spacesd by URL
sb = await Sandbox.connect(url="http://10.0.0.5:3211", token="...")
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.linux()) as sb:
await sb.shell.run("whoami")
"""
from __future__ import annotations
import asyncio
import logging
import os
import random
import time
import warnings
from contextlib import asynccontextmanager
from dataclasses import dataclass, field
from datetime import datetime, timezone
from typing import (
TYPE_CHECKING,
Any,
AsyncIterator,
Callable,
Coroutine,
Optional,
TypeVar,
)
try:
from cua_core.telemetry import is_telemetry_enabled, record_event
_TELEMETRY_AVAILABLE = True
except ImportError:
_TELEMETRY_AVAILABLE = False
def is_telemetry_enabled() -> bool:
return False
def record_event(event_name: str, properties: dict | None = None) -> None:
pass
from cua_sandbox import _placement, _refs
from cua_sandbox._ended import CloudEnded
from cua_sandbox._refs import AmbiguousSandbox # noqa: F401 - re-exported
from cua_sandbox._sdk import ( # noqa: F401 - InvalidPlacement is re-exported
ENV_SERVICE,
InvalidArgument,
InvalidPlacement,
SpacesdNotAvailable,
Unsupported,
)
from cua_sandbox.image import Image, ImageInfo
from cua_sandbox.interfaces import (
Apps,
Clipboard,
Files,
Keyboard,
Mobile,
Mouse,
Screen,
Services,
Shell,
Terminal,
Tunnel,
Window,
)
from cua_sandbox.interfaces import mcp as _mcp
from cua_sandbox.interfaces.driver import Driver
from cua_sandbox.options import (
Probe,
PublicUrl,
WaitFor,
check_network,
check_services,
parse_memory,
probes,
)
from cua_sandbox.transport.base import Transport
from cua_sandbox.transport.env import EnvTransport, env_url
if TYPE_CHECKING:
from cua_sandbox.interfaces.services import ServiceHandle
from cua_sandbox.runtime.base import Runtime, RuntimeInfo
from cua_sandbox.sandbox_pool import SandboxPool
logger = logging.getLogger(__name__)
_T = TypeVar("_T")
def _overlay_specs(overlay: Any) -> list:
"""``{name: path}`` / ``{name: (path, guest_path)}`` / a list of
``cua.Overlay`` into native overlays."""
if not overlay:
return []
if isinstance(overlay, dict):
from cua_sandbox._sdk import sdk
native = sdk()._native
out = []
for name, spec in overlay.items():
path, target = (spec, None) if isinstance(spec, (str, os.PathLike)) else spec
out.append(
native.Overlay(name=str(name), path=os.fspath(path), target=target, source=None)
)
return out
return list(overlay)
async def _with_overlays(sandbox: "Sandbox", overlay: Any) -> "Sandbox":
"""Applies ``overlay`` to a new sandbox; deletes it if that fails (a
sandbox that cannot run the build under test is not returned)."""
if not overlay:
return sandbox
try:
await sandbox.overlay(overlay)
except BaseException:
try:
await sandbox.destroy()
except Exception: # noqa: BLE001 - the overlay error is the one to raise
logger.warning("could not delete sandbox %r after a failed overlay", sandbox.name)
raise
return sandbox
def validate_server_port(server_port: Any) -> None:
"""``None`` (daemon-agnostic default) or a TCP port."""
if server_port is None:
return
if (
isinstance(server_port, bool)
or not isinstance(server_port, int)
or server_port < 1
or server_port > 65535
):
raise ValueError("server_port must be an integer between 1 and 65535")
async def _sandbox_pool(pool: Any, *, on: Optional[str], local: Optional[bool]) -> "Any":
"""The pool of this machine ``pool`` names (a :class:`SandboxPool`, or
the name of one) when the create runs here, else ``None`` (a name
nothing here has, or a create elsewhere; :func:`_reject_pool` then
refuses it)."""
from cua_sandbox.sandbox_pool import SandboxPool, get_pool
if isinstance(pool, SandboxPool):
if local is False or (on is not None and str(on).strip().lower() not in ("", "local")):
raise InvalidArgument(
f"pool {pool.name!r} runs on this machine; drop on=/local= or use on='local'"
)
return pool
if not isinstance(pool, str) or local is False:
return None
if on is not None and str(on).strip().lower() not in ("", "local"):
return None
try:
return await get_pool(pool)
except Exception: # noqa: BLE001 - no daemon: no pools here
return None
def _pool_args(sp: Any, image: Any, cpu: Any, memory_mb: Any, kind: Any, runtime: Any) -> Any:
"""A create's image, size, kind and runtime from pool ``sp`` (the daemon
refuses an image or size other than the pool's)."""
if image is None:
image = Image.from_registry(sp.image)
return (
image,
cpu if cpu is not None else sp.cpus,
memory_mb if memory_mb is not None else sp.memory_mb,
kind or (sp.kind or None),
runtime if runtime is not None else (sp.runtime or None),
)
def _reject_pool(pool: Optional[str]) -> None:
"""``pool=`` named no pool of this machine: only a Cua Cloud pool could
be meant, and Cua Cloud has ended."""
if pool is not None:
raise CloudEnded()
def _is_local_sandbox(name: str) -> bool:
"""Whether ``name`` is a local sandbox (a state file that is not a stale
record of a Cua Cloud claim, which an older release left behind)."""
from cua_sandbox import sandbox_state
state = sandbox_state.load(name)
return bool(state) and state.get("runtime_type") != "fleet"
async def _lookup(name: str, local: Optional[bool]) -> tuple[str, bool]:
"""``(plain name, local)`` for a sandbox ref or bare name (see
:func:`cua_sandbox._refs.resolve`). A ``direct:`` machine is not managed
here: connect to it with ``Sandbox.connect(url=...)``."""
plain, _, direct = await _refs.resolve(name, local)
if direct is not None:
raise Unsupported(
f"{name}: a direct computer is not managed by cua-sandbox; connect to it with "
f"Sandbox.connect({name!r})"
)
# A bare name is a local sandbox (an unknown one fails as "not found" in the
# local path); a cloud ref or ``local=False`` already raised CloudEnded.
return plain, True
@dataclass
class SandboxInfo:
"""Metadata for a local sandbox.
``status`` from :meth:`Sandbox.info` is portable: ``provisioning``,
``starting``, ``ready`` or ``stopped``. Listings keep the provider's word
(``running``, ``suspended``, ...). Provider internals (the local backend)
are in ``provider_details``.
"""
name: str
status: str
source: str # "lume" | "docker" | "qemu-baremetal" | ...
os_type: Optional[str] = None
host: Optional[str] = None
vnc_url: Optional[str] = None
api_url: Optional[str] = None
created_at: Optional[str] = None
#: The qualified ref: ``local:<name>`` or ``direct:<host:port>`` (what
#: ``Sandbox.connect`` / ``delete`` take).
id: Optional[str] = None
location: Optional[str] = None # "local" | "direct"
services: dict = field(default_factory=dict)
expires_at: Optional[str] = None
provider_details: dict = field(default_factory=dict)
#: What kind of machine: ``container`` or ``vm`` (``None`` when unknown).
kind: Optional[str] = None
#: Which engine runs it: ``gvisor``, ``runc``, ``qemu``, ``lume``;
#: ``None`` when unknown.
runtime: Optional[str] = None
def __post_init__(self) -> None:
# The qualified ref (`local:<name>`) when not given.
if self.id is None and self.location and self.name:
self.id = f"{self.location}:{self.name}"
_PHASE_WORDS = {
"PROVISIONING": "provisioning",
"STARTING": "starting",
"READY": "ready",
"STOPPED": "stopped",
}
def _apply_on(
on: Optional[str],
local: Optional[bool],
runtime: Any,
*,
cpu: Optional[int] = None,
memory_mb: Optional[int] = None,
time_to_start: Optional[float] = None,
) -> "tuple[Optional[str], Optional[bool], Any]":
"""Route ``on=`` to a provider when it names one: a contrib platform
(``"e2b"``, ``"daytona"``, ``"modal"``; opt-in SDK builds) or your own
cloud (``"aws"``, ``"gcp"``, ``"hetzner"``, ``"modal"``; connect it with ``cua cloud
connect``). ``"local"``, ``"direct:<addr>"`` and ``"relay:<id>"`` fall
through to the placement model (:mod:`cua_sandbox._placement`); so does
``"cloud"``, which raises :class:`CloudEnded`. Returns
``(on, local, runtime)``; a contrib provider becomes ``(None, True,
ContribRuntime(...))``, a local sandbox served through the provider's SDK
handle."""
if on is None or not str(on).strip():
return on, local, runtime
word = str(on).strip().lower()
if word in ("local", "cloud") or word.startswith("direct:") or word.startswith("relay:"):
return on, local, runtime
from cua_sandbox.runtime.contrib import ContribRuntime, contrib_locations
if word not in contrib_locations():
# Not a known provider: let the placement model raise the proper error.
return on, local, runtime
if local is not None or runtime is not None:
raise InvalidArgument(f"on={word!r} picks the provider; drop local= and runtime=")
kwargs: dict[str, Any] = {"ephemeral": True, "cpus": cpu, "memory_mb": memory_mb}
if time_to_start is not None:
kwargs["ready_timeout"] = float(time_to_start)
return None, True, ContribRuntime(word, **kwargs)
def _place_new(
image: Optional[Image],
*,
on: Optional[str],
local: Optional[bool],
kind: Optional[str],
runtime: Any,
) -> "tuple[_placement.Placement, Optional[Image]]":
"""Where, what kind and which engine for a new sandbox (see
:mod:`cua_sandbox._placement`), and the image with the resolved kind."""
place = _placement.resolve(
on=on,
local=local,
kind=kind,
runtime=runtime,
image_kind=image.kind if image is not None else None,
)
if image is not None and place.kind and place.kind != image.kind:
image = image._with(kind=place.kind)
return place, image
def _sdk_backed(runtime: Any) -> bool:
"""Whether a local adapter starts its sandboxes through the cua SDK (and
so takes ``kind``/``runtime`` start options)."""
from cua_sandbox.runtime.native import NativeRuntime
from cua_sandbox.runtime.qemu import QEMUBaremetalRuntime
return isinstance(runtime, (NativeRuntime, QEMUBaremetalRuntime))
def _require_network_none_support(runtime: Any) -> None:
"""Local runtimes that can cut guest egress: the SDK's native runtimes
(the Rust backend refuses containers and Lume itself) and the legacy
QEMU launchers. Anything else would silently ignore it."""
from cua_sandbox.runtime.native import NativeRuntime
from cua_sandbox.runtime.qemu import QEMUBaremetalRuntime, QEMUWSL2Runtime
if not isinstance(runtime, (NativeRuntime, QEMUBaremetalRuntime, QEMUWSL2Runtime)):
raise Unsupported(
f"{type(runtime).__name__} does not support network='none'; only local QEMU "
"VMs run without outbound network"
)
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 _remove_orphan_container(name: str) -> bool:
"""Remove a container left behind by a launch that never wrote state.
A local launch that times out during the readiness probe leaves a running
container and no state file, which put it beyond the reach of
``Sandbox.delete``. Returns whether a container was actually removed.
"""
import subprocess
try:
exists = subprocess.run(
["docker", "inspect", "--type", "container", name],
capture_output=True,
)
if exists.returncode != 0:
return False
removed = subprocess.run(["docker", "rm", "-f", name], capture_output=True)
return removed.returncode == 0
except (OSError, subprocess.SubprocessError):
# Docker missing or unusable — no orphan we can claim to have removed.
return False
def _auto_runtime(
image: Image,
*,
cpu: Optional[int] = None,
memory_mb: Optional[int] = None,
server_port: Optional[int] = None,
engine: Optional[str] = None,
) -> "Runtime":
"""Pick a runtime automatically based on image.os_type and image.kind.
``cpu`` / ``memory_mb`` size the sandbox; unset keeps each runtime's default.
``server_port`` is the image's own server: published, probed for
readiness and reachable as the ``server`` service. ``engine``
(``runtime="qemu"``/``"lume"``/``"gvisor"``/``"runc"``) picks the adapter
for it.
"""
rt = _pick_runtime(image, cpu=cpu, memory_mb=memory_mb, engine=engine)
if server_port is not None:
# NativeRuntime (and the QEMU wrappers that delegate to it) read it.
rt.server_port = server_port
return rt
def _pick_runtime(
image: Image,
*,
cpu: Optional[int] = None,
memory_mb: Optional[int] = None,
engine: Optional[str] = None,
) -> "Runtime":
import platform as _plat
# Docker and Lume name the CPU count ``cpus``; the VM runtimes ``cpu_count``.
shape = {"cpus": cpu} if cpu is not None else {}
vm_shape = {"cpu_count": cpu} if cpu is not None else {}
if memory_mb is not None:
shape["memory_mb"] = memory_mb
vm_shape["memory_mb"] = memory_mb
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."
)
# An engine names its adapter (the SDK checks it against the image).
if engine == "lume":
from cua_sandbox.runtime.lume import LumeRuntime
return LumeRuntime(**shape)
if engine == "qemu":
from cua_sandbox.runtime.qemu import QEMURuntime
return QEMURuntime(mode="bare-metal", **vm_shape)
if image.kind == "container":
from cua_sandbox.runtime.docker import DockerRuntime
return DockerRuntime(ephemeral=True, **shape)
# kind == "vm"
if image.os_type == "macos":
from cua_sandbox.runtime.lume import LumeRuntime
return LumeRuntime(**shape)
if image.os_type == "android":
from cua_sandbox.runtime.android_emulator import AndroidEmulatorRuntime
return AndroidEmulatorRuntime(**vm_shape)
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(**vm_shape)
# 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", **vm_shape)
# Linux VM or Windows VM → prefer Docker-wrapped QEMU; fall back to bare-metal
from cua_sandbox.runtime.qemu import QEMURuntime
if image.os_type == "linux":
# A Linux VM boots the pinned containerDisk under bare-metal QEMU.
# Docker-wrapped QEMU cannot reach that path at all: resolve_image()
# hands it the XFCE *container* image, so asking for a VM used to
# quietly get you a container.
from cua_sandbox.runtime.compat import _has_qemu
if not _has_qemu():
raise RuntimeError(
"Image.linux() is a VM and needs QEMU, which was not found on "
"this host. Install it:\n"
" Debian/Ubuntu: sudo apt install qemu-system-x86\n"
" Fedora/RHEL: sudo dnf install qemu-system-x86\n"
" macOS: brew install qemu\n"
"Or pass an explicit runtime= if you want a different one."
)
return QEMURuntime(mode="bare-metal", **vm_shape)
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", **vm_shape)
except Exception:
pass
return QEMURuntime(mode="docker", **vm_shape)
# Coarse telemetry labels for built-in runtime classes. Anything else (user
# subclasses, contributed runtimes) is reported as "other" so a user-chosen
# class name never leaves the machine.
_TELEMETRY_RUNTIME_LABELS = {
"DockerRuntime": "docker",
"LumeRuntime": "lume",
"NativeQEMURuntime": "qemu",
"QEMUDockerRuntime": "qemu-docker",
"QEMUBaremetalRuntime": "qemu-baremetal",
"QEMUWSL2Runtime": "qemu-wsl2",
"HyperVRuntime": "hyperv",
"TartRuntime": "tart",
"AndroidEmulatorRuntime": "android-emulator",
"NativeRuntime": "native",
"ContribRuntime": "contrib",
}
_TELEMETRY_OS_TYPES = {"linux", "macos", "windows", "android"}
_TELEMETRY_IMAGE_KINDS = {"container", "vm"}
def _telemetry_runtime_label(runtime: Any) -> str:
cls = type(runtime)
label = _TELEMETRY_RUNTIME_LABELS.get(cls.__name__)
if label and (cls.__module__ or "").startswith("cua_sandbox."):
return label
return "other"
def _record_sandbox_create(
sb: Any,
*,
image: Optional[Any],
local: bool,
ephemeral: bool,
t_start: float,
) -> None:
"""Fire a sandbox_create PostHog event if telemetry is enabled."""
if not sb.telemetry_enabled or not _TELEMETRY_AVAILABLE or not is_telemetry_enabled():
return
# Never send the sandbox name: it is user-chosen.
props: dict = {
"local": local,
"ephemeral": ephemeral,
"duration_seconds": round(time.monotonic() - t_start, 3),
}
if image is not None:
os_type = getattr(image, "os_type", None)
kind = getattr(image, "kind", None)
props["os_type"] = os_type if os_type in _TELEMETRY_OS_TYPES else "other"
if kind is not None:
props["image_kind"] = kind if kind in _TELEMETRY_IMAGE_KINDS else "other"
if sb._runtime is not None:
props["runtime_type"] = _telemetry_runtime_label(sb._runtime)
record_event("sandbox_create", props)
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. To control the local machine, use cua-driver.
There are three ways to obtain a Sandbox:
1. **Persistent** — provision and keep alive after the script exits::
sb = await Sandbox.create(Image.linux())
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.linux()) 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,
_telemetry_enabled: bool = True,
):
self._transport = transport
self.name = name
"""The sandbox name."""
self._runtime = _runtime
self._runtime_info = _runtime_info
self._ephemeral = _ephemeral
# Image info the Python side resolved (runtimes with no SDK handle).
self._image_info_fallback: Optional[ImageInfo] = None
# Set for a machine reached by URL (``direct:<host:port>``).
self._direct_url: Optional[str] = None
self.telemetry_enabled = _telemetry_enabled
"""Whether this sandbox records anonymous usage events."""
self.screen = Screen(transport)
"""Screenshots and screen size (cua-spacesd)."""
self.mouse = Mouse(transport)
"""Pointer input in screen pixels (cua-spacesd)."""
self.keyboard = Keyboard(transport)
"""Typing and key presses (cua-spacesd)."""
self.clipboard = Clipboard(transport)
"""Clipboard text (cua-spacesd)."""
self.shell = Shell(transport)
"""Run shell commands (cua-spacesd)."""
self.files = Files(transport)
"""Read, write and transfer files (cua-spacesd)."""
self.window = Window(transport)
"""The active window (cua-spacesd)."""
self.terminal = Terminal(transport)
"""PTY terminal sessions (cua-spacesd)."""
self.mobile = Mobile(transport)
"""Android touch and hardware keys (Android sandboxes)."""
self.tunnel = Tunnel(transport)
"""Forward sandbox ports to loopback ports on this machine."""
self.services = Services(transport)
"""Older named-service helpers; prefer `service(name)`."""
self.driver = Driver(transport)
"""Typed Cua Driver access (`cua-sandbox[driver]`)."""
_os = _runtime_info.environment if _runtime_info and _runtime_info.environment else "linux"
self.apps = Apps(transport, os_type=_os)
"""Install and launch catalog applications (cua-spacesd)."""
async def _connect(self) -> None:
await self._transport.connect()
async def disconnect(self) -> None:
"""Drop the transport connection. The sandbox keeps running."""
await self.driver.close()
await self._transport.disconnect()
@property
def exposed_ports(self) -> dict:
"""Map each Image.expose() port to the host port forwarding it.
Local sandboxes forward exposed ports to free host ports chosen at boot,
so the mapping is only knowable at runtime. Reading it from the saved
state as well means a reconnecting caller can still find the port rather
than it living only on the object create() returned. Empty when the
runtime forwards nothing (use tunnel.forward()).
"""
info = getattr(self, "_runtime_info", None)
ports = getattr(info, "exposed_ports", None) if info else None
if ports:
return dict(ports)
name = getattr(self, "name", None)
if name:
try:
from cua_sandbox import sandbox_state
saved = sandbox_state.load(name) or {}
except Exception: # noqa: BLE001 - a missing state file is not an error here
saved = {}
stored = saved.get("exposed_ports") or {}
# JSON object keys are strings; callers index by guest port int.
return {int(guest): host for guest, host in stored.items()}
return {}
@property
def image_info(self) -> Optional[ImageInfo]:
"""The image this sandbox runs, as resolved and pinned at create time
(digest, variant, arch), or ``None`` when unknown: direct (URL)
connections, images not resolved from a registry.
The SDK handle's ``image_info()`` is the source of truth; runtimes
without one report what was resolved at create or claim time. Never
makes a network call and never raises.
"""
try:
for handle in self._native_candidates():
getter = getattr(handle, "image_info", None)
if callable(getter):
return ImageInfo._from_native(getter())
return getattr(self, "_image_info_fallback", None)
except Exception: # noqa: BLE001 - informational; never fail the caller
return None
def _native_candidates(self) -> list:
"""SDK sandbox handles this sandbox holds, without any I/O."""
info = getattr(self, "_runtime_info", None)
transport = getattr(self, "_transport", None)
found = [
getattr(info, "native", None) if info is not None else None,
getattr(transport, "_native_sandbox", None),
]
return [h for h in found if h is not None]
@property
def location(self) -> str:
"""Where it runs: ``local`` or ``direct``."""
if self._direct_url is not None:
return "direct"
return "local"
@property
def id(self) -> str | None:
"""The qualified ref: ``local:<name>`` or ``direct:<host:port>``. It
is what ``Sandbox.connect(id)`` and ``Sandbox.delete(id)`` take, and
what listings print."""
if self._direct_url is not None:
try:
return _refs.parse(self._direct_url).id
except Exception: # noqa: BLE001 - an unparsable URL keeps its name
return self.name
return _refs.qualified(self.location, self.name) if self.name else None
async def _native_handle(self) -> Any:
"""The ``cua.Sandbox`` handle (services, forwards, public URLs)."""
handle = getattr(self._transport, "native_handle", None)
if callable(handle):
return await handle()
native = getattr(self._runtime_info, "native", None) if self._runtime_info else None
if native is not None:
return native
raise NotImplementedError(
f"{type(self._transport).__name__} sandboxes have no named services"
)
async def overlay(
self, overlay: "dict[str, Any] | list", timeout: Optional[float] = None
) -> list:
"""Injects binaries into this sandbox (see ``create(overlay=...)``):
``{"cua-driver": "./target/release/cua-driver"}``. Returns one
``cua.OverlayResult`` per binary (``name``, ``target``, ``sha256``,
``previous_sha256``, ``restarted``); pass ``NAME=sha256:<hex>`` to
``cua doctor --expect``. ``timeout`` (seconds) bounds a cua-spacesd
restart."""
handle = await self._native_handle()
ms = None if timeout is None else int(timeout * 1000)
return list(await handle.overlay(_overlay_specs(overlay), ms))
async def info(self) -> SandboxInfo:
"""Portable info: ``status`` (provisioning, starting, ready, stopped),
``location`` (local or direct), ``services`` (name -> guest port),
``expires_at`` and ``provider_details``."""
handle = await self._native_handle()
record = await handle.refresh()
expires = (
datetime.fromtimestamp(record.expires_at_unix, timezone.utc).isoformat()
if record.expires_at_unix
else None
)
phase = _PHASE_WORDS.get(getattr(record.phase, "name", str(record.phase)), "starting")
return SandboxInfo(
name=self.name or record.name,
status=phase,
source=record.runtime_type,
os_type=getattr(self._runtime_info, "environment", None),
id=record.id or self.id,
location=record.location,
services={k: v for k, v in dict(record.services).items() if v or k != "env"},
expires_at=expires,
provider_details=dict(record.provider_details),
kind=getattr(record, "kind", None) or None,
runtime=getattr(record, "runtime", None) or None,
)
def service(self, name: str) -> "ServiceHandle":
"""A named service (``services={"mcp": 8765}`` at create):
``request``, ``url`` and ``public_url``."""
from cua_sandbox.interfaces.services import ServiceHandle
return ServiceHandle(self, name)
async def public_url(
self, service: str, *, ttl: float = 3600, label: Optional[str] = None
) -> PublicUrl:
"""A shareable URL for ``service`` that stops working after ``ttl``
seconds (60 s to 24 h): a loopback URL with its own token, served by
the cua daemon (started if needed)."""
from cua_sandbox.interfaces.services import public_url_from_native
handle = await self._native_handle()
return public_url_from_native(await handle.public_url(service, int(ttl), label))
async def revoke_public_url(self, url: "PublicUrl | str") -> None:
"""Revokes a URL from :meth:`public_url` (or its id)."""
handle = await self._native_handle()
await handle.revoke_public_url(url if isinstance(url, str) else url.id)
async def destroy(self) -> None:
"""Disconnect and permanently delete the sandbox (VM/container)."""
if self.telemetry_enabled and _TELEMETRY_AVAILABLE and is_telemetry_enabled():
record_event("sandbox_destroy", {"ephemeral": self._ephemeral})
# Run each cleanup step independently so a failure in one
# (e.g. disconnect timeout) doesn't prevent the VM from being deleted.
try:
await self.disconnect()
except Exception:
logger.warning("Failed to disconnect transport for sandbox %r", self.name)
if self._runtime and self._runtime_info:
vm_name = self._runtime_info.name or self.name or "cua-sandbox"
try:
if self._ephemeral and hasattr(self._runtime, "delete"):
await self._runtime.delete(vm_name)
else:
await self._runtime.stop(vm_name)
except Exception:
logger.warning("Failed to stop/delete runtime for sandbox %r", self.name)
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.
With cua-spacesd this is a link to its HTML5 viewer, carrying a
scoped viewer ticket that expires. Images without cua-spacesd return
the page of a declared web display service, or a VNC address.
Args:
share: If True, return a link meant for sharing (an expiring
public link for a legacy web display service; viewer links
always expire). If False, return a direct connection URL.
"""
return await self._transport.get_display_url(share=share)
async def viewer_url(self) -> str:
"""A browser link to this sandbox's desktop in the cua-spacesd HTML5
viewer (video, audio, input, clipboard, files). The link carries a
scoped viewer ticket that expires after an hour. Same as
``get_display_url()`` for sandboxes with cua-spacesd.
"""
return await self._transport.get_display_url(share=False)
async def get_dimensions(self) -> tuple[int, int]:
return await self.screen.size()
def mcp(self, service: str, *, path: str = "/mcp") -> Any:
"""An official MCP SDK client for the MCP server behind ``service``.
An async context manager (``pip install "cua-sandbox[mcp]"``)::
async with sb.mcp("mcp") as client:
tools = await client.list_tools()
result = await client.call_tool("add", {"a": 2, "b": 3})
Requests go through the sandbox's service route (loopback), streamed
both ways, so every protocol feature and content block works
unchanged. No cua-spacesd needed.
"""
return _mcp.open_mcp(lambda: self._transport.native_service(service), path)
async def mcp_config(self, service: str, *, path: str = "/mcp") -> dict:
"""``{"url": ..., "headers": {...}}`` of ``service``'s MCP endpoint, for
any MCP client (Claude Code, Cursor, other SDKs). The headers can carry
a short-lived bearer: fetch a fresh config per connection."""
return await _mcp.mcp_config(lambda: self._transport.native_service(service), path)
async def spacesd(self) -> Any:
"""The raw ``cua.SpacesdClient`` for this sandbox's cua-spacesd.
The typed escape hatch to every ``cua.env.v1`` RPC (``call_json``),
process streaming, chunked transfers and media sessions. Raises
:class:`~cua_sandbox._sdk.SpacesdNotAvailable` when the sandbox has no
spacesd (for example a plain VNC-only image).
"""
if isinstance(self._transport, EnvTransport):
return await self._transport.spacesd()
raise SpacesdNotAvailable(
f"{type(self._transport).__name__} sandboxes are driven without cua-spacesd"
)
# ── 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 | None = None,
*,
pool: "SandboxPool | str | None" = None,
name: Optional[str] = None,
on: Optional[str] = None,
local: Optional[bool] = None,
kind: Optional[str] = None,
runtime: "Runtime | str | None" = None,
cpu: Optional[int] = None,
memory_mb: Optional[int] = None,
disk_gb: Optional[int] = None,
time_to_start: Optional[float] = None,
request_timeout: Optional[float] = None,
server_port: Optional[int] = None,
telemetry_enabled: bool = True,
command: Optional[list[str]] = None,
sidecars: Optional[list] = None,
env: Optional[dict[str, str]] = None,
services: Optional[dict[str, int]] = None,
wait_for: WaitFor = None,
memory: "str | int | None" = None,
network: Optional[str] = None,
overlay: "dict[str, Any] | list | None" = None,
) -> "Sandbox":
"""Provision a persistent local sandbox and return it connected.
Where, what kind and which engine are three separate choices:
* ``on``: ``"local"``. ``local=True`` is the same switch; ``on`` and a
contradicting ``local`` is an :class:`InvalidArgument`. Unset, the
user default applies (``CUA_DEFAULT_ON``, else ``cua config set
default.on`` in ``$CUA_HOME/config.toml``, else local, with a
one-time notice that ``CUA_QUIET_DEFAULT=1`` hides). Cua Cloud has
ended: ``on="cloud"``, ``local=False`` and ``pool=`` naming no pool
of this machine raise :class:`CloudEnded`.
* ``kind``: ``"auto"``, ``"container"`` or ``"vm"``. Unset: the
image's ``kind`` when it has one, else ``default.kind``, else auto
(macOS and Windows images are VMs, a container rootfs is a
container, a disk-only image is a VM).
* ``runtime``: the engine, ``"auto"`` or one the location offers for
the kind: ``"gvisor"``/``"runc"`` (containers) and
``"qemu"``/``"lume"`` (VMs). Unset: ``default.runtime``, else auto.
A sandbox with ``sidecars`` needs ``"runc"`` where gVisor would run
(separate gVisor containers cannot share a network namespace).
A :class:`Runtime` object (``DockerRuntime()``, ``TartRuntime()``,
...) still picks a local adapter, as before.
A combination that does not exist (``kind="container",
runtime="qemu"``) raises :class:`InvalidPlacement`, listing the valid
values.
Options:
* ``command``: argv replacing the image's entrypoint.
* ``env``: environment variables.
* ``services``: named guest ports, ``{"mcp": 8765}``; reach them with
``sb.service("mcp")``, ``sb.public_url("mcp")`` or
``sb.tunnel.forward(8765)``.
* ``wait_for``: ``tcp("mcp")`` / ``http("mcp", "/health")`` (or a
list); readiness otherwise is "the sandbox is running".
* ``memory``: ``"4GB"`` / ``"512MB"`` (or ``memory_mb``).
* ``network``: ``"default"`` (outbound network, like a Docker
container) or ``"none"`` (no egress; the SDK still reaches the
guest's published ports). ``"none"`` needs a local QEMU VM;
containers and Lume raise :class:`Unsupported`.
* ``overlay``: binaries to inject once it is up, so tests run the
build under test and not the copy the image bundles:
``{"cua-driver": "./target/release/cua-driver"}`` (``cua-driver`` and
``cua-spacesd`` resolve their guest path; other names take
``(path, "/guest/path")``). Each replaces the guest file atomically,
is recorded with its sha256 (``cua doctor --expect``) and what runs
it is restarted. If it fails, the sandbox is deleted and the error
raised. See :meth:`overlay`.
``pool``: a pool of this machine (a :class:`SandboxPool` from
:func:`create_pool`, or its name) gives the sandbox the pool's image
and size and takes one of its ready sandboxes (about 0.1 s).
``server_port`` names a port your image serves itself: it becomes the
readiness probe. Leave it unset for the default, daemon-agnostic
readiness (the provider reports the sandbox running; cua-spacesd on
3211 is used by the interfaces when the image has it).
"""
validate_server_port(server_port)
# A pool of this machine: the sandbox gets its image and size and
# takes one of its ready sandboxes.
local_pool = await _sandbox_pool(pool, on=on, local=local)
if local_pool is not None:
image, cpu, memory_mb, kind, runtime = _pool_args(
local_pool, image, cpu, memory_mb, kind, runtime
)
pool, local = None, True
_reject_pool(pool)
on, local, runtime = _apply_on(
on,
local,
runtime,
cpu=cpu,
memory_mb=memory_mb,
time_to_start=time_to_start,
)
place, image = _place_new(image, on=on, local=local, kind=kind, runtime=runtime)
# The engine (a string) and a legacy local Runtime object.
engine, runtime = place.runtime, place.legacy_runtime
network = check_network(network)
if memory is not None:
if memory_mb is not None:
raise ValueError("pass memory= or memory_mb=, not both")
memory_mb = parse_memory(memory)
wait = probes(wait_for)
services = check_services(services, wait)
if image is None:
raise ValueError("image is required")
created = await cls._create(
image=image,
name=name,
local_pool=local_pool.name if local_pool is not None else None,
ephemeral=False,
local=True,
runtime=runtime,
cpu=cpu,
memory_mb=memory_mb,
disk_gb=disk_gb,
time_to_start=time_to_start,
request_timeout=request_timeout,
server_port=server_port,
telemetry_enabled=telemetry_enabled,
command=command,
sidecars=sidecars,
engine=engine,
network=network,
env=env,
services=services,
wait_for=wait,
)
return await _with_overlays(created, overlay)
@classmethod
def connect(
cls,
name: Optional[str] = None,
*,
url: Optional[str] = None,
token: Optional[str] = None,
api_key: Optional[str] = None,
local: Optional[bool] = None,
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,
telemetry_enabled: bool = True,
) -> "_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: A sandbox ref (``local:<name>``, ``direct:<host:port>``, a
legacy id) or a name. A ``cloud:<name>`` ref raises
:class:`CloudEnded`: Cua Cloud has ended.
local: ``None`` (default): the local sandbox ``name``.
``False`` raises :class:`CloudEnded`.
url: A cua-spacesd URL to connect to directly
(``http://host:3211`` or a relay URL).
token: The spacesd token for ``url``.
api_key: Used as the spacesd token for ``url`` when ``token`` is
not given.
ws_url: Removed (the computer-server WebSocket protocol is gone).
http_url: Base URL of a cua-spacesd (same as ``url``).
container_name: Unused; kept for compatibility.
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()
"""
if name is None and url is None and http_url is None:
raise ValueError("Sandbox.connect needs a sandbox name or url=")
async def _factory() -> "Sandbox":
# A ref decides the location; a bare name is the local sandbox.
target, direct = name, None
if name and not (url or http_url):
target, _, direct = await _refs.resolve(name, local)
return await cls._create(
name=target if direct is None else None,
url=url or direct,
token=token,
ephemeral=False,
local=True,
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,
telemetry_enabled=telemetry_enabled,
)
return _ConnectResult(_factory)
@classmethod
@asynccontextmanager
async def ephemeral(
cls,
image: Image | None = None,
*,
pool: "SandboxPool | str | None" = None,
name: Optional[str] = None,
on: Optional[str] = None,
local: Optional[bool] = None,
kind: Optional[str] = None,
runtime: "Runtime | str | None" = None,
cpu: Optional[int] = None,
memory_mb: Optional[int] = None,
disk_gb: Optional[int] = None,
time_to_start: Optional[float] = None,
request_timeout: Optional[float] = None,
server_port: Optional[int] = None,
telemetry_enabled: bool = True,
command: Optional[list[str]] = None,
sidecars: Optional[list] = None,
env: Optional[dict[str, str]] = None,
services: Optional[dict[str, int]] = None,
wait_for: WaitFor = None,
memory: "str | int | None" = None,
network: Optional[str] = None,
) -> AsyncIterator["Sandbox"]:
"""A local sandbox that is deleted when the ``async with`` block exits.
Takes the same ``pool``, ``on``/``local``, ``kind``, ``runtime``, ``command``,
``env``, ``services``, ``wait_for``, ``memory`` and ``network``
options as :meth:`create`.
"""
# A pool of this machine: the sandbox gets its image and size and
# takes one of its ready sandboxes.
local_pool = await _sandbox_pool(pool, on=on, local=local)
if local_pool is not None:
image, cpu, memory_mb, kind, runtime = _pool_args(
local_pool, image, cpu, memory_mb, kind, runtime
)
pool, local = None, True
_reject_pool(pool)
on, local, runtime = _apply_on(
on,
local,
runtime,
cpu=cpu,
memory_mb=memory_mb,
time_to_start=time_to_start,
)
place, image = _place_new(image, on=on, local=local, kind=kind, runtime=runtime)
# The engine (a string) and a legacy local Runtime object.
engine, runtime = place.runtime, place.legacy_runtime
network = check_network(network)
if memory is not None:
if memory_mb is not None:
raise ValueError("pass memory= or memory_mb=, not both")
memory_mb = parse_memory(memory)
wait = probes(wait_for)
services = check_services(services, wait)
if image is None:
raise ValueError("image is required")
sandbox = await cls._create(
image=image,
name=name,
ephemeral=True,
local_pool=local_pool.name if local_pool is not None else None,
local=True,
runtime=runtime,
cpu=cpu,
memory_mb=memory_mb,
disk_gb=disk_gb,
time_to_start=time_to_start,
request_timeout=request_timeout,
server_port=server_port,
telemetry_enabled=telemetry_enabled,
command=command,
sidecars=sidecars,
engine=engine,
network=network,
env=env,
services=services,
wait_for=wait,
)
try:
yield sandbox
finally:
await sandbox.destroy()
# ── Lifecycle management ─────────────────────────────────────────────
@classmethod
async def list(
cls,
*,
location: Optional[str] = None,
local: Optional[bool] = None,
all: Optional[bool] = None, # noqa: A002 - deprecated
api_key: Optional[str] = None,
) -> "list[SandboxInfo]":
"""List the local sandboxes (containers, QEMU, Lume, Android), each
with its ``location``, ``kind`` and ``runtime``.
Args:
location: ``None`` (default) or ``"local"``: the local sandboxes.
``"cloud"`` raises :class:`CloudEnded`: Cua Cloud has ended.
local: The same switch as a bool (``True`` is ``"local"``,
``False`` is ``"cloud"``).
all: Deprecated; everything is the default.
api_key: Unused; kept for compatibility.
"""
if all is not None:
warnings.warn(
"Sandbox.list(all=...) is deprecated: everything is the default",
DeprecationWarning,
stacklevel=2,
)
if all and (local is not None or location is not None):
raise InvalidArgument("pass all=True or local=/location=, not both")
if location is not None:
where = str(location).strip().lower()
if where not in _placement.LOCATIONS:
raise InvalidArgument(f"location={location!r}: cua-sandbox lists 'local' sandboxes")
if local is not None and (where == "local") != bool(local):
raise InvalidArgument(
f"location={location!r} and local={local!r} contradict each other"
)
local = where == "local"
if local is False:
raise CloudEnded()
return await cls._list_local()
@classmethod
async def _list_local(cls) -> "list[SandboxInfo]":
import asyncio
from cua_sandbox.runtime.android_emulator import AndroidEmulatorRuntime
async def _list_sdk():
# Every sandbox the SDK knows: state files (including those older
# cua-sandbox releases wrote) plus instances its backends manage.
try:
from cua_sandbox._sdk import local_runtime
return list(await local_runtime().sandboxes().list("local"))
except Exception as error: # noqa: BLE001 - listing is best effort
logger.debug("SDK local listing failed: %s", error)
return []
async def _list_android():
try:
return await AndroidEmulatorRuntime().list()
except Exception:
return []
sdk_records, android_vms = await asyncio.gather(_list_sdk(), _list_android())
from cua_sandbox import sandbox_state
from cua_sandbox.runtime.native import _status_word
results: list[SandboxInfo] = []
seen: set[str] = set()
for record in sdk_records:
state = sandbox_state.load(record.name) or {}
host = state.get("host")
api_port = state.get("api_port")
results.append(
SandboxInfo(
name=record.name,
status=(
_status_word(record.status)
if record.status_detail is None
else state.get("status", record.status_detail)
),
source=record.runtime_type,
os_type=state.get("os_type"),
host=host,
api_url=f"http://{host}:{api_port}" if host and api_port else None,
created_at=state.get("created_at"),
id=record.id or _refs.qualified("local", record.name),
location="local",
services=dict(state.get("services") or {}),
provider_details={"backend": record.runtime_type},
kind=getattr(record, "kind", None) or None,
runtime=getattr(record, "runtime", None) or None,
)
)
seen.add(record.name)
for vm in android_vms:
if vm["name"] in seen:
continue
results.append(
SandboxInfo(
location="local",
id=_refs.qualified("local", vm["name"]),
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 get_info(
cls,
name: str,
*,
local: Optional[bool] = None,
api_key: Optional[str] = None,
) -> "SandboxInfo":
"""Get metadata for a specific sandbox.
Args:
name: Sandbox ref (``local:<name>``) or a name. A ``cloud:<name>``
ref raises :class:`CloudEnded`: Cua Cloud has ended.
local: ``None`` (default) or ``True``: the local sandbox ``name``.
``False`` raises :class:`CloudEnded`.
api_key: Unused; kept for compatibility.
"""
name, _ = await _lookup(name, 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(
location="local",
id=_refs.qualified("local", name),
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.")
@classmethod
async def suspend(
cls,
name: str,
*,
local: Optional[bool] = None,
api_key: Optional[str] = None,
) -> None:
"""Suspend the local sandbox ``name``, keeping its state;
:meth:`resume` continues it. Only that sandbox is affected.
The SDK suspends it on its backend (a container is paused or
checkpointed, a QEMU VM snapshotted, a Lume VM stopped with its
disk).
Args:
name: Sandbox name.
local: ``None`` (default) or ``True``: the local sandbox ``name``.
``False`` raises :class:`CloudEnded`: Cua Cloud has ended.
api_key: Unused; kept for compatibility.
"""
name, _ = await _lookup(name, local)
await cls._suspend_local(name)
@classmethod
async def _suspend_local(cls, name: str) -> None:
from cua_sandbox import sandbox_state
from cua_sandbox.runtime.native import is_native_state
state = sandbox_state.load(name)
runtime_type = state.get("runtime_type") if state else None
if is_native_state(state) or runtime_type in ("docker", "qemu-docker", "lume"):
# The SDK finds the owning backend (container, QEMU, Lume) itself.
from cua_sandbox._sdk import local_runtime
handle = await local_runtime().sandboxes().connect(name)
await handle.suspend()
if state is not None and not is_native_state(state):
sandbox_state.update(name, status="suspended")
elif runtime_type == "qemu-baremetal":
from cua_sandbox.runtime.qemu import QEMUBaremetalRuntime
rt = QEMUBaremetalRuntime(use_sdk=False)
if state:
rt.qmp_port = state.get("qmp_port", rt.qmp_port)
await rt.suspend(name)
else:
raise ValueError(f"Cannot suspend sandbox '{name}': unknown runtime '{runtime_type}'")
@classmethod
async def resume(
cls,
name: str,
*,
local: Optional[bool] = None,
api_key: Optional[str] = None,
) -> "Sandbox":
"""Resume the suspended local sandbox ``name`` and return it
connected. The backend resumes it.
Args:
name: Sandbox name.
local: ``None`` (default) or ``True``: the local sandbox ``name``.
``False`` raises :class:`CloudEnded`: Cua Cloud has ended.
api_key: Unused; kept for compatibility.
Returns:
A connected Sandbox ready to use.
"""
name, _ = await _lookup(name, local)
return await cls._resume_local(name)
@classmethod
async def _resume_local(cls, name: str) -> "Sandbox":
from cua_sandbox import sandbox_state
from cua_sandbox.runtime.native import is_native_state
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 is_native_state(state) or runtime_type in ("docker", "qemu-docker", "lume"):
from cua_sandbox._sdk import local_runtime
handle = await local_runtime().sandboxes().connect(name)
await handle.resume()
if not is_native_state(state):
sandbox_state.update(name, status="running")
sb = cls(
await _local_state_transport(name, sandbox_state.load(name) or state),
name=name,
_ephemeral=False,
)
await sb._connect()
return sb
if runtime_type == "qemu-baremetal":
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),
use_sdk=False,
)
rt_info = await rt.resume(image, name)
transport = _env_transport(rt_info, environment=state.get("os_type"))
sb = cls(transport, name=name, _ephemeral=False)
await sb._connect()
return sb
raise ValueError(f"Cannot resume sandbox '{name}': unknown runtime_type '{runtime_type}'")
@classmethod
async def restart(
cls,
name: str,
*,
local: Optional[bool] = None,
api_key: Optional[str] = None,
) -> "Sandbox":
"""Restart the local sandbox ``name`` (suspend then resume) and return
it connected (see :meth:`suspend`).
Args:
name: Sandbox name.
local: ``None`` (default) or ``True``: the local sandbox ``name``.
``False`` raises :class:`CloudEnded`: Cua Cloud has ended.
api_key: Unused; kept for compatibility.
Returns:
A connected Sandbox ready to use.
"""
name, _ = await _lookup(name, local)
await cls._suspend_local(name)
return await cls._resume_local(name)
@classmethod
async def delete(
cls,
name: str,
*,
local: Optional[bool] = None,
api_key: Optional[str] = None,
) -> None:
"""Permanently delete a local sandbox: stops the VM or container and
removes the state file.
Args:
name: Sandbox name.
local: ``None`` (default) or ``True``: the local sandbox ``name``.
``False`` raises :class:`CloudEnded`: Cua Cloud has ended.
api_key: Unused; kept for compatibility.
"""
name, _ = await _lookup(name, local)
await cls._delete_local(name)
@classmethod
async def _delete_local(cls, name: str) -> None:
from cua_sandbox import sandbox_state
from cua_sandbox.runtime.native import is_native_state
state = sandbox_state.load(name)
runtime_type = state.get("runtime_type") if state else None
if is_native_state(state) or runtime_type in ("docker", "qemu-docker", "lume"):
from cua_sandbox._sdk import local_runtime
# Deletes the instance (container, VM, Lume clone) and its state.
await local_runtime().sandboxes().delete(name)
elif runtime_type == "qemu-baremetal":
from cua_sandbox.runtime.qemu import QEMUBaremetalRuntime
await QEMUBaremetalRuntime(use_sdk=False).stop(name) # stop() deletes the state file
return
elif runtime_type == "androidemulator":
from cua_sandbox.runtime.android_emulator import AndroidEmulatorRuntime
await AndroidEmulatorRuntime().stop(name)
elif runtime_type is not None:
raise ValueError(f"Cannot delete sandbox '{name}': unknown runtime '{runtime_type}'")
elif not _remove_orphan_container(name):
# No state file and no container by that name — deleting nothing at
# all used to report success, so a typo looked like a deletion.
raise ValueError(f"No local sandbox named {name!r}")
sandbox_state.delete(name)
# ── Internal factory ─────────────────────────────────────────────────
@classmethod
async def _create(
cls,
*,
local: bool = False,
ws_url: Optional[str] = None,
http_url: Optional[str] = None,
url: Optional[str] = None,
token: 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,
time_to_start: Optional[float] = None,
request_timeout: Optional[float] = None,
server_port: Optional[int] = None,
telemetry_enabled: bool = True,
command: Optional[list[str]] = None,
sidecars: Optional[list] = None,
engine: Optional[str] = None,
network: Optional[str] = None,
env: Optional[dict[str, str]] = None,
services: Optional[dict[str, int]] = None,
wait_for: Optional[list[Probe]] = None,
local_pool: Optional[str] = None,
) -> "Sandbox":
"""Internal factory that validates server_port before selecting a transport.
``runtime`` is a legacy local :class:`Runtime` object; ``engine`` the
engine name the placement resolved (``gvisor``, ``qemu``, ...), with
``image.kind`` already set to the resolved kind.
"""
validate_server_port(server_port)
auto_adapter = runtime is None
_t_start = time.monotonic()
if ephemeral is None:
ephemeral = bool(image)
rt_info = None
if image and image.kind is None and local:
# The one resolver (native cua_image): short refs are docker.io,
# containerDisks run on QEMU, rootfs images as containers.
from cua_sandbox.image import resolve_image_kind
image = await asyncio.to_thread(resolve_image_kind, image)
# Direct connection to a cua-spacesd by URL — no provider involved.
direct_url = url or http_url
if direct_url and not image:
transport = EnvTransport(url=direct_url, token=token or api_key)
sb = cls(
transport,
name=name or direct_url,
_ephemeral=False,
_telemetry_enabled=telemetry_enabled,
)
sb._direct_url = direct_url
await sb._connect()
_record_sandbox_create(sb, image=None, local=False, ephemeral=False, t_start=_t_start)
return sb
# Local connect by name — read state file
if name and not image and local and not ws_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:
transport = await _local_state_transport(name, state)
sb = cls(transport, name=name, _ephemeral=False, _telemetry_enabled=telemetry_enabled)
await sb._connect()
_record_sandbox_create(sb, image=None, local=local, ephemeral=False, t_start=_t_start)
return sb
if not local:
# Cua Cloud has ended (CUA-1854): a cloud create and a connect by
# cloud name stop here.
raise CloudEnded()
if image and not runtime:
# local=True with no runtime → auto-select based on image type
runtime = _auto_runtime(
image, cpu=cpu, memory_mb=memory_mb, server_port=server_port, engine=engine
)
if image and runtime:
sb_name = name or _random_name()
# Forward the sizing knobs the caller gave Sandbox.create/ephemeral so a
# local VM honours cpu= and memory_mb=.
start_opts: dict = {}
if cpu is not None:
start_opts["cpu_count"] = cpu
if memory_mb is not None:
start_opts["memory_mb"] = memory_mb
if disk_gb is not None:
start_opts["disk_size_gb"] = disk_gb
if command or env or services or wait_for or sidecars:
from cua_sandbox.runtime.native import NativeRuntime
if not isinstance(runtime, NativeRuntime):
raise NotImplementedError(
f"{type(runtime).__name__} does not take command, env, services, "
"sidecars or wait_for; use the default local runtime (containers, "
"QEMU, Lume)"
)
start_opts.update(
command=list(command) if command else None,
env=dict(env or {}),
services=dict(services or {}),
wait_for=list(wait_for or []),
sidecars=list(sidecars or []),
)
if auto_adapter and _sdk_backed(runtime):
# The adapter was picked from the placement: the SDK gets the
# kind and engine too (and checks them against the image).
if image.kind:
start_opts["kind"] = image.kind
if engine:
start_opts["runtime"] = engine
if network == "none":
_require_network_none_support(runtime)
start_opts["network"] = "none"
if local_pool is not None:
# A pool of this machine (`create_pool`) to take a ready
# sandbox from.
if not _sdk_backed(runtime):
raise Unsupported(
f"{type(runtime).__name__} does not take sandboxes from a pool; "
"omit runtime= to use the pool"
)
start_opts["pool"] = local_pool
rt_info = await runtime.start(image, sb_name, ephemeral=bool(ephemeral), **start_opts)
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.native is None and not rt_info.api_port and rt_info.vnc_port:
# VNC-only: a VM with no guest agent port at all.
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.native is None and rt_info.qmp_port and rt_info.environment:
# QMP-driven VM (use_qmp_transport / Android-x86): agentless.
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:
# cua-spacesd when the image has it; QMP/VNC otherwise.
transport = _env_transport(
rt_info, environment=rt_info.environment or image.os_type, token=token
)
else:
if ws_url:
raise ValueError(
"ws_url= spoke the computer-server WebSocket protocol, which was removed. "
"Connect to the sandbox's cua-spacesd instead: "
"Sandbox.connect(url='http://host:3211', token=...)"
)
raise ValueError("a sandbox needs an image, a name or a url")
# Write persistent state for local (non-ephemeral) sandboxes. Runtimes
# on the cua SDK persisted it themselves, in the same format.
if not ephemeral and rt_info and rt_info.native is None:
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,
_telemetry_enabled=telemetry_enabled,
)
sb._image_info_fallback = getattr(image, "_resolved", None) if image else None
await sb._connect()
_record_sandbox_create(
sb, image=image, local=local, ephemeral=bool(ephemeral), t_start=_t_start
)
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",
"frosty",
"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 _fallback_transport(
host: str,
*,
qmp_port: Optional[int] = None,
vnc_port: Optional[int] = None,
environment: Optional[str] = None,
) -> Optional[Transport]:
"""An agentless transport (QMP, else VNC) for sandboxes without spacesd."""
if qmp_port:
from cua_sandbox.transport.qmp import QMPTransport
return QMPTransport(qmp_host=host, qmp_port=qmp_port, environment=environment or "linux")
if vnc_port:
from cua_sandbox.transport.vnc import VNCTransport
return VNCTransport(host=host, port=vnc_port, environment=environment or "linux")
return None
def _env_transport(
rt_info: "RuntimeInfo",
*,
environment: Optional[str] = None,
token: Optional[str] = None,
) -> EnvTransport:
"""EnvTransport for a started local runtime (SDK-backed or legacy)."""
fallback = _fallback_transport(
rt_info.host,
qmp_port=rt_info.qmp_port,
vnc_port=rt_info.vnc_port,
environment=environment,
)
ready_timeout = rt_info.env_ready_timeout or (120.0 if fallback is not None else 60.0)
vnc_url = f"vnc://{rt_info.host}:{rt_info.vnc_port}" if rt_info.vnc_port else None
handle = rt_info.native
if handle is not None:
from cua_sandbox.transport.agentless import (
AgentlessTransport,
supports_agentless,
)
if supports_agentless(handle):
# A local Lume sandbox: once cua-spacesd proves absent (the macOS
# images), shell via SSH and screen via VNC, the path `cua sb exec`
# and `cua sb screenshot` use. Lume's VNC needs a password the
# plain VNCTransport does not have.
fallback = AgentlessTransport(handle, environment=environment)
direct = env_url(rt_info.host, rt_info.api_port) if rt_info.api_port else None
env_token = token or rt_info.env_token
# The SDK reports no `env` service for an image without cua-spacesd:
# say so at once instead of probing a port nothing listens on.
no_env = rt_info.guest_server_port is None
async def open_env() -> Any:
from cua_sandbox._sdk import connect_url, millis
if no_env:
raise SpacesdNotAvailable(
"this sandbox's image does not run cua-spacesd; use its named "
"services (sb.services.request) or sb.tunnel.forward(port)"
)
if direct and env_token:
# A handle re-attached from state carries no token; dial the
# published env port with the recorded one.
return await (await connect_url(direct, env_token)).spacesd(millis(15))
return await handle.spacesd(millis(15))
return EnvTransport(
env_factory=open_env,
environment=environment,
fallback=fallback,
ready_timeout=ready_timeout,
native_sandbox=handle,
vnc_url=vnc_url,
)
return EnvTransport(
url=env_url(rt_info.host, rt_info.api_port),
token=token or rt_info.env_token,
environment=environment,
fallback=fallback,
ready_timeout=ready_timeout,
vnc_url=vnc_url,
)
async def _local_state_transport(name: str, state: dict) -> EnvTransport:
"""EnvTransport for a local sandbox recorded in ``~/.cua/sandboxes``."""
from cua_sandbox.runtime.base import RuntimeInfo
from cua_sandbox.runtime.native import is_native_state, runtime_info_from_state
if is_native_state(state):
from cua_sandbox._sdk import local_runtime
handle = await local_runtime().sandboxes().connect(name)
rt_info = runtime_info_from_state(name, state, handle=handle)
else:
rt_info = RuntimeInfo(
host=state.get("host") or "localhost",
api_port=int(state.get("api_port") or 0),
vnc_port=state.get("vnc_port"),
qmp_port=state.get("qmp_port"),
name=name,
environment=state.get("os_type"),
)
return _env_transport(rt_info, environment=state.get("os_type"))
@asynccontextmanager
async def sandbox(
*,
on: Optional[str] = None,
local: Optional[bool] = None,
kind: Optional[str] = None,
ws_url: Optional[str] = None,
http_url: Optional[str] = None,
url: Optional[str] = None,
token: Optional[str] = None,
api_key: Optional[str] = None,
container_name: Optional[str] = None,
image: Optional[Image] = None,
runtime: "Runtime | str | None" = None,
name: Optional[str] = None,
ephemeral: Optional[bool] = None,
cpu: Optional[int] = None,
memory_mb: Optional[int] = None,
disk_gb: Optional[int] = None,
) -> AsyncIterator[Sandbox]:
"""Async context manager for a sandboxed environment.
``on``/``local``, ``kind`` and ``runtime`` mean what they mean for
:meth:`Sandbox.create`.
.. deprecated::
Prefer ``Sandbox.create()``, ``Sandbox.connect()``, or
``Sandbox.ephemeral()`` instead.
"""
engine = None
if image is not None and not (url or http_url or ws_url):
# A new sandbox: the same placement rules as Sandbox.create.
on, local, runtime = _apply_on(on, local, runtime, cpu=cpu, memory_mb=memory_mb)
place, image = _place_new(image, on=on, local=local, kind=kind, runtime=runtime)
local, engine, runtime = place.local, place.runtime, place.legacy_runtime
elif on is not None:
local = _placement.resolve(on=on, local=local).local
sb = await Sandbox._create(
local=bool(local),
ws_url=ws_url,
http_url=http_url,
url=url,
token=token,
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,
engine=engine,
)
try:
yield sb
finally:
if sb._ephemeral:
await sb.destroy()
else:
await sb.disconnect()