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
"""Where a new sandbox runs, what kind it is and which engine runs it.
Three independent axes, the same on every cua surface:
* ``on``: ``"local"`` (``local=True`` is the same switch). Cua Cloud has
ended: ``"cloud"`` and ``local=False`` raise
:class:`~cua_sandbox._ended.CloudEnded`. Other locations (``direct:<addr>``,
registered providers) are existing machines or plugins, not something
cua-sandbox creates.
* ``kind``: ``"auto"``, ``"container"`` or ``"vm"``.
* ``runtime``: ``"auto"`` or an engine the location offers for the kind:
``gvisor``/``runc`` (containers) and ``qemu``/``lume`` (VMs). A legacy
:class:`~cua_sandbox.runtime.Runtime` object still picks a local adapter.
Unset values come from the user's defaults, in this order: environment
(``CUA_DEFAULT_ON``, ``CUA_DEFAULT_KIND``, ``CUA_DEFAULT_RUNTIME``), then
``$CUA_HOME/config.toml`` (``cua config set default.on local``), then the
built-in ``local``/``auto``/``auto``. The native cua SDK owns both the
settings and the validation; this module only asks it.
"""
from __future__ import annotations
import logging
import os
from dataclasses import dataclass
from typing import Any, Optional
from cua_sandbox._ended import CloudEnded
from cua_sandbox._sdk import InvalidArgument, InvalidPlacement, Unsupported
logger = logging.getLogger(__name__)
#: Locations cua-sandbox creates sandboxes on.
LOCATIONS = ("local", "cloud")
KINDS = ("auto", "container", "vm")
#: Every engine; which ones a location offers is the native SDK's rule.
ENGINES = ("auto", "gvisor", "runc", "qemu", "lume")
#: The kind an engine runs.
ENGINE_KIND = {
"gvisor": "container",
"runc": "container",
"qemu": "vm",
"lume": "vm",
}
_ENV = {"default.on": "CUA_DEFAULT_ON", "default.kind": "CUA_DEFAULT_KIND"}
_ENV["default.runtime"] = "CUA_DEFAULT_RUNTIME"
_BUILTIN = {"default.on": "local", "default.kind": "auto", "default.runtime": "auto"}
_default_notice_shown = False
@dataclass(frozen=True)
class Setting:
"""One user default: its value and where it came from (``env``,
``config`` or ``default``; ``origin`` names the variable or file)."""
value: str
source: str
origin: str = ""
def setting(key: str) -> Setting:
"""The effective value of ``key`` (``default.on``, ``default.kind``,
``default.runtime``) from ``cua.config_get``."""
try:
from cua_sandbox._sdk import native
entry = native().config_get(key)
origin = getattr(entry, "_from", None) or getattr(entry, "from_", "") or ""
return Setting(str(entry.value), str(entry.source), str(origin))
except ImportError:
# No native SDK (a packaging error elsewhere): env, else built-in.
env = _ENV.get(key)
value = os.environ.get(env, "").strip() if env else ""
if value:
return Setting(value, "env", env or "")
return Setting(_BUILTIN.get(key, ""), "default")
def translate(error: BaseException) -> BaseException:
"""The cua-sandbox exception for a native placement error (the message,
with the valid values, is kept); anything else unchanged."""
try:
from cua_sandbox._sdk import native
cua_error = native().CuaError
except Exception: # noqa: BLE001 - no SDK: nothing to translate
return error
if isinstance(error, cua_error.InvalidPlacement):
return InvalidPlacement(str(error))
if isinstance(error, cua_error.InvalidArgument):
return InvalidArgument(str(error))
return error
def check(on: str, kind: Optional[str], runtime: Optional[str]) -> None:
"""Validates the combination with the native rule
(``cua.check_placement``); raises :class:`InvalidPlacement` listing the
valid values."""
from cua_sandbox._sdk import native
try:
native().check_placement(on, kind or "", runtime or "")
except Exception as error: # noqa: BLE001 - translated below
translated = translate(error)
if translated is error:
raise
raise translated from None
def _text(value: Any, what: str) -> Optional[str]:
"""``None``/``""``/``"auto"`` as ``None``; otherwise the lowercased word."""
if value is None:
return None
if not isinstance(value, str):
raise InvalidArgument(f"{what}= takes a string, got {type(value).__name__}")
word = value.strip().lower()
return None if word in ("", "auto") else word
def _on_word(on: Any) -> str:
if not isinstance(on, str) or not on.strip():
raise InvalidArgument(f"on= takes 'local', got {on!r}")
text = on.strip()
head, sep, rest = text.partition(":")
return head.lower() + sep + rest if sep else text.lower()
@dataclass(frozen=True)
class Placement:
"""The resolved location, kind and engine of a new sandbox."""
on: str
#: ``explicit`` (on=/local=), ``implied`` (a legacy Runtime object), or
#: the default's source (``env``, ``config``, ``default``).
on_source: str
on_origin: str = ""
#: ``container``/``vm``, or ``None`` for auto.
kind: Optional[str] = None
#: An engine string, or ``None`` for auto.
runtime: Optional[str] = None
#: A legacy Runtime object (local adapters), when one was passed.
legacy_runtime: Any = None
@property
def local(self) -> bool:
return self.on == "local"
def _notice() -> None:
global _default_notice_shown
if _default_notice_shown:
return
_default_notice_shown = True
quiet = os.environ.get("CUA_QUIET_DEFAULT", "").strip().lower()
if quiet not in ("1", "true", "yes", "on"):
# Logged from cua_sandbox.sandbox, where users filter it.
logging.getLogger("cua_sandbox.sandbox").warning(
"defaulting to a local sandbox (CUA_QUIET_DEFAULT=1 hides this notice)"
)
def resolve(
*,
on: Optional[str] = None,
local: Optional[bool] = None,
kind: Optional[str] = None,
runtime: Any = None,
image_kind: Optional[str] = None,
) -> Placement:
"""Where, what kind and which engine (see the module docstring).
Location: ``on=`` or ``local=`` (contradicting each other is
:class:`InvalidArgument`); else a legacy ``Runtime`` object means local;
else ``default.on``. The cloud is gone: asking for it raises
:class:`CloudEnded`. The one-time "defaulting to a local sandbox" notice
appears only when ``default.on`` is the built-in default.
Kind: ``kind=`` > the image's ``kind`` > the engine's kind >
``default.kind`` (skipped when it does not fit) > auto.
Engine: ``runtime=`` > ``default.runtime`` (skipped when it does not
fit) > auto.
"""
legacy = runtime if runtime is not None and not isinstance(runtime, str) else None
engine = _text(runtime, "runtime") if legacy is None else None
explicit_kind = _text(kind, "kind")
if on is not None:
where, source, origin = _on_word(on), "explicit", ""
if local is not None and (where == "local") != bool(local):
raise InvalidArgument(
f"on={on!r} and local={local!r} contradict each other; pass one of them"
)
elif local is not None:
where, source, origin = ("local" if local else "cloud"), "explicit", ""
elif legacy is not None:
# A Runtime object is a local adapter (Docker, QEMU, Lume, Tart, ...).
where, source, origin = "local", "implied", ""
else:
default = setting("default.on")
where, source, origin = _on_word(default.value), default.source, default.origin
if source == "default" and where == "local":
_notice()
if legacy is not None:
if where != "local":
if on is not None:
raise InvalidArgument(
f"runtime={type(legacy).__name__}(...) runs the sandbox on this computer; "
f"drop on={on!r}, or pass an engine name (runtime='gvisor'/'qemu')"
)
# Shipped behaviour (0.8.0): a Runtime object ran locally, even
# with local=False.
where, source, origin = "local", "implied", ""
if explicit_kind is not None:
check("local", explicit_kind, None)
return Placement(where, source, origin, explicit_kind or image_kind, None, legacy)
if where.partition(":")[0] == "cloud":
raise CloudEnded()
# Validate what was asked for before defaults fill the rest.
check(where, explicit_kind, engine)
if where not in LOCATIONS:
raise Unsupported(
f"on={where!r}: cua-sandbox creates local sandboxes. Connect to an "
"existing computer with Sandbox.connect(url=...), or use the cua SDK for other "
"providers"
)
# The image's kind (Image.linux(kind="vm")) is as explicit as kind=.
resolved_kind = explicit_kind or image_kind or (ENGINE_KIND.get(engine) if engine else None)
if resolved_kind is None:
default_kind = _text(setting("default.kind").value, "default.kind")
if default_kind is not None and _fits(where, default_kind, engine):
resolved_kind = default_kind
# The image's own kind against the engine (Image.linux(kind="vm") with
# runtime="gvisor").
check(where, resolved_kind, engine)
if engine is None:
default_engine = _text(setting("default.runtime").value, "default.runtime")
if default_engine is not None and _fits(where, resolved_kind, default_engine):
engine = default_engine
resolved_kind = resolved_kind or ENGINE_KIND.get(engine)
return Placement(where, source, origin, resolved_kind, engine, None)
def _fits(on: str, kind: Optional[str], runtime: Optional[str]) -> bool:
try:
check(on, kind, runtime)
except InvalidArgument:
return False
return True