Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
"""Sandbox options: command, env, services, readiness probes and sizing.
::
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"],
env={"FOO": "bar"},
services={"mcp": 8765},
wait_for=http("mcp", "/health"),
on="local",
kind="container", # "auto" | "container" | "vm"
runtime="gvisor", # the engine; "auto" picks one
)
"""
from __future__ import annotations
from dataclasses import dataclass, field
from typing import Any, Iterable, Mapping, Optional, Sequence, Union
@dataclass(frozen=True)
class Probe:
"""A readiness probe on a declared service: TCP, or ``GET path`` returning
2xx when ``path`` is set. Build it with :func:`tcp` or :func:`http`."""
service: str
path: Optional[str] = None
def native(self) -> Any:
"""The ``cua.ReadinessProbe`` for this probe."""
from cua_sandbox._sdk import native
n = native()
return n.ReadinessProbe(port=0, http_path=self.path, http_status=None, service=self.service)
def tcp(service: str) -> Probe:
"""Ready once a TCP connect to the declared ``service`` succeeds."""
return Probe(service=service)
def http(service: str, path: str = "/") -> Probe:
"""Ready once ``GET path`` on the declared ``service`` returns 2xx."""
return Probe(service=service, path=path if path.startswith("/") else f"/{path}")
WaitFor = Union[Probe, Sequence[Probe], None]
def probes(wait_for: WaitFor) -> list[Probe]:
"""``wait_for`` as a list (a single probe, a sequence, or ``None``)."""
if wait_for is None:
return []
if isinstance(wait_for, Probe):
return [wait_for]
out = list(wait_for)
for p in out:
if not isinstance(p, Probe):
raise TypeError("wait_for takes tcp(service) / http(service, path) probes")
return out
def check_services(services: Optional[Mapping[str, int]], wait_for: Iterable[Probe]) -> dict:
"""Validates ``services`` (name -> guest port) and that every probe names
one of them."""
out: dict[str, int] = {}
for name, port in (services or {}).items():
if not isinstance(name, str) or not name:
raise ValueError("service names must be non-empty strings")
if isinstance(port, bool) or not isinstance(port, int) or not 0 < port < 65536:
raise ValueError(f"service {name!r}: port must be 1-65535, got {port!r}")
out[name] = port
for p in wait_for:
if p.service not in out and p.service != "env":
raise ValueError(
f"wait_for names service {p.service!r}, which is not declared in services= "
f"(declared: {sorted(out)})"
)
return out
#: ``network=`` values: ``"default"`` gives the guest outbound network (like a
#: Docker container); ``"none"`` cuts it while published ports still work.
NETWORK_MODES = ("default", "none")
def check_network(network: Optional[str]) -> Optional[str]:
"""Normalizes ``network=`` (``None`` / ``"default"`` / ``"none"``).
Only local QEMU VMs can run with ``"none"``; containers and Lume reject it
(``Unsupported``) rather than ignore it.
"""
if network is None:
return None
if not isinstance(network, str):
raise ValueError(f"network must be one of {NETWORK_MODES}, got {network!r}")
value = network.strip().lower() or "default"
if value not in NETWORK_MODES:
raise ValueError(f"network {network!r}: expected 'default' or 'none'")
return value
def parse_memory(memory: Union[str, int, None]) -> Optional[int]:
"""``"4GB"`` / ``"512MB"`` / ``4096`` (MiB) -> MiB."""
if memory is None:
return None
if isinstance(memory, bool):
raise ValueError("memory must be like '4GB', '512MB' or MiB as an int")
if isinstance(memory, int):
return memory
text = str(memory).strip().upper().replace(" ", "")
for suffix, factor in (
("GIB", 1024),
("GB", 1024),
("G", 1024),
("MIB", 1),
("MB", 1),
("M", 1),
):
if text.endswith(suffix):
number = text[: -len(suffix)]
break
else:
number, factor = text, 1024
try:
value = float(number)
except ValueError as error:
raise ValueError(f"bad memory {memory!r} (use '4GB' or '512MB')") from error
if value <= 0:
raise ValueError(f"bad memory {memory!r}")
return int(value * factor)
@dataclass(frozen=True)
class PublicUrl:
"""A shareable URL of a sandbox service that stops working at
``expires_at``: a loopback URL with its own token, served by the cua
daemon."""
url: str
expires_at: str
id: str
service: str
provider_details: dict = field(default_factory=dict)