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.

83.2 KB
Raw Blame
"""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()