use-computer 0.0.24__tar.gz → 0.0.26__tar.gz

{use_computer-0.0.24 → use_computer-0.0.26}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: use-computer
-Version: 0.0.24
-Summary: Python SDK for the use.computer macOS and iOS Computer Use API
+Version: 0.0.26
+Summary: Python SDK for use.computer sandboxes across macOS, iOS simulators, Windows, and Ubuntu
 Project-URL: Homepage, https://use.computer
 Project-URL: Documentation, https://api.use.computer/docs
 Project-URL: Repository, https://github.com/josancamon19/use-computer-python
 Author: use.computer
-Keywords: automation,computer-use,ios,macos,sandbox
+Keywords: automation,computer-use,ios,macos,sandbox,ubuntu,vnc,windows
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
@@ -22,7 +22,7 @@ Description-Content-Type: text/markdown
 
 # use-computer Python SDK
 
-Python client for [use.computer](https://use.computer) — rent dedicated Mac minis with macOS and Apple simulator sandboxes built for computer-use agents.
+Python client for [use.computer](https://use.computer) — rent dedicated VMs across macOS, iOS/visionOS/tvOS simulators, Windows, and Ubuntu built for computer-use agents.
 
 ```bash
 pip install use-computer
@@ -73,7 +73,7 @@ Ubuntu sandboxes are **Beta** (admin-only). They use the same KVM/noVNC backend
 as Windows; pass `version="ubuntu-24.04"` to select a specific image. Exec
 defaults to bash and the macOS accessibility tree is not available yet.
 
-Full DSL reference (macOS + simulator): [docs.use.computer/docs/sdk](https://docs.use.computer/docs/sdk)
+Full DSL reference: [docs.use.computer/docs/sdk](https://docs.use.computer/docs/sdk)
 
 Simulator sandboxes use `type=SandboxType.IOS` for the SDK route, but
 `device_type` and `runtime` can target any installed compatible CoreSimulator
@@ -105,6 +105,8 @@ visionOS yet. Use it for read-only flows for now.
 | [`examples/_4_file_transfer.py`](examples/_4_file_transfer.py) | upload bytes, download a file back             |
 | [`examples/_5_keepalive.py`](examples/_5_keepalive.py)         | heartbeat for sessions idle > 2 min            |
 | [`examples/_6_hello_tvos.py`](examples/_6_hello_tvos.py)       | tvOS: pick TV family + drive the Apple Remote  |
+| [`examples/_7_hello_windows.py`](examples/_7_hello_windows.py) | create Windows → run PowerShell → screenshot   |
+| [`examples/_8_hello_ubuntu.py`](examples/_8_hello_ubuntu.py)   | create Ubuntu → run bash → screenshot          |
 
 For agent loops and evals: [use-computer-cookbook](https://github.com/josancamon19/use-computer-cookbook).
 

{use_computer-0.0.24 → use_computer-0.0.26}/README.md

@@ -1,6 +1,6 @@
 # use-computer Python SDK
 
-Python client for [use.computer](https://use.computer) — rent dedicated Mac minis with macOS and Apple simulator sandboxes built for computer-use agents.
+Python client for [use.computer](https://use.computer) — rent dedicated VMs across macOS, iOS/visionOS/tvOS simulators, Windows, and Ubuntu built for computer-use agents.
 
 ```bash
 pip install use-computer
@@ -51,7 +51,7 @@ Ubuntu sandboxes are **Beta** (admin-only). They use the same KVM/noVNC backend
 as Windows; pass `version="ubuntu-24.04"` to select a specific image. Exec
 defaults to bash and the macOS accessibility tree is not available yet.
 
-Full DSL reference (macOS + simulator): [docs.use.computer/docs/sdk](https://docs.use.computer/docs/sdk)
+Full DSL reference: [docs.use.computer/docs/sdk](https://docs.use.computer/docs/sdk)
 
 Simulator sandboxes use `type=SandboxType.IOS` for the SDK route, but
 `device_type` and `runtime` can target any installed compatible CoreSimulator
@@ -83,6 +83,8 @@ visionOS yet. Use it for read-only flows for now.
 | [`examples/_4_file_transfer.py`](examples/_4_file_transfer.py) | upload bytes, download a file back             |
 | [`examples/_5_keepalive.py`](examples/_5_keepalive.py)         | heartbeat for sessions idle > 2 min            |
 | [`examples/_6_hello_tvos.py`](examples/_6_hello_tvos.py)       | tvOS: pick TV family + drive the Apple Remote  |
+| [`examples/_7_hello_windows.py`](examples/_7_hello_windows.py) | create Windows → run PowerShell → screenshot   |
+| [`examples/_8_hello_ubuntu.py`](examples/_8_hello_ubuntu.py)   | create Ubuntu → run bash → screenshot          |
 
 For agent loops and evals: [use-computer-cookbook](https://github.com/josancamon19/use-computer-cookbook).
 

{use_computer-0.0.24 → use_computer-0.0.26}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "hatchling.build"
 
 [project]
 name = "use-computer"
-version = "0.0.24"
-description = "Python SDK for the use.computer macOS and iOS Computer Use API"
+version = "0.0.26"
+description = "Python SDK for use.computer sandboxes across macOS, iOS simulators, Windows, and Ubuntu"
 readme = "README.md"
 requires-python = ">=3.10"
 authors = [{ name = "use.computer" }]
 dependencies = ["httpx>=0.27"]
-keywords = ["computer-use", "macos", "ios", "automation", "sandbox"]
+keywords = ["computer-use", "macos", "ios", "windows", "ubuntu", "automation", "sandbox", "vnc"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",

{use_computer-0.0.24 → use_computer-0.0.26}/use_computer/__init__.py

@@ -17,10 +17,12 @@ from use_computer.sandbox import (
     AsyncSandbox,
     AsyncUbuntuSandbox,
     AsyncWindowsSandbox,
+    HostRedirect,
     IOSSandbox,
     MacOSSandbox,
     Sandbox,
     SandboxType,
+    Snapshot,
     UbuntuSandbox,
     WindowsSandbox,
 )
@@ -51,6 +53,7 @@ __all__ = [
     "CursorPosition",
     "DisplayInfo",
     "ExecResult",
+    "HostRedirect",
     "IOSSandbox",
     "Key",
     "MacOSSandbox",
@@ -60,6 +63,7 @@ __all__ = [
     "RunStatus",
     "Sandbox",
     "SandboxType",
+    "Snapshot",
     "SimulatorChoice",
     "SimulatorFamily",
     "Task",

{use_computer-0.0.24 → use_computer-0.0.26}/use_computer/client.py

@@ -91,7 +91,7 @@ class RunStatus:
 
 
 class Computer:
-    """use.computer client. Creates and manages macOS and iOS sandboxes."""
+    """use.computer client. Creates and manages macOS, iOS, Windows, and Ubuntu sandboxes."""
 
     def __init__(self, api_key: str | None = None, base_url: str | None = None):
         self._base_url = _resolve_base_url(base_url)
@@ -114,6 +114,13 @@ class Computer:
         resp.raise_for_status()
         return resp.json()
 
+    def snapshots(self, platform: str = "") -> list[dict[str, Any]]:
+        """List Windur desktop snapshots visible to this API key."""
+        params = {"platform": platform} if platform else None
+        resp = self._http.get("/v1/snapshots", params=params)
+        resp.raise_for_status()
+        return resp.json().get("snapshots", [])
+
     @overload
     def create(
         self,
@@ -138,6 +145,7 @@ class Computer:
         *,
         type: Literal["windows", SandboxType.WINDOWS],
         version: str = ...,
+        snapshot: str = ...,
         host: str = ...,
     ) -> WindowsSandbox: ...
 
@@ -147,6 +155,7 @@ class Computer:
         *,
         type: Literal["ubuntu", SandboxType.UBUNTU],
         version: str = ...,
+        snapshot: str = ...,
         host: str = ...,
     ) -> UbuntuSandbox: ...
 
@@ -159,24 +168,31 @@ class Computer:
         device_type: str = "",
         runtime: str = "",
         version: str = "",
+        snapshot: str = "",
     ) -> MacOSSandbox | IOSSandbox | WindowsSandbox | UbuntuSandbox:
         """Create a new sandbox.
 
         Args:
-            type: SandboxType.MACOS (default), SandboxType.IOS, or the raw API string.
+            type: SandboxType.MACOS (default), IOS, WINDOWS, UBUNTU, or the raw API string.
             host: Pin sandbox to a specific host machine (e.g. "mm001").
             family: Simulator family enum/alias, for example SimulatorFamily.TV.
             device_type: Simulator device type identifier, for exact pinning.
             runtime: Simulator runtime identifier, for exact pinning.
             version: KVM desktop image version, for example "windows-11",
                 "windows-10", or "ubuntu-24.04".
+            snapshot: Windur snapshot version returned by sandbox.snapshot().
         """
         sandbox_type = _normalize_sandbox_type(type)
         body: dict = {"type": sandbox_type.value}
         if host:
             body["host"] = host
-        if sandbox_type in (SandboxType.WINDOWS, SandboxType.UBUNTU) and version:
-            body["version"] = version
+        if sandbox_type in (SandboxType.WINDOWS, SandboxType.UBUNTU):
+            if version and snapshot:
+                raise ValueError("version and snapshot are mutually exclusive")
+            if snapshot:
+                body["snapshot"] = snapshot
+            elif version:
+                body["version"] = version
         if sandbox_type == SandboxType.IOS:
             if family and (not device_type or not runtime):
                 choice = select_simulator(self.platforms(), family)
@@ -333,6 +349,13 @@ class AsyncComputer:
         resp.raise_for_status()
         return resp.json()
 
+    async def snapshots(self, platform: str = "") -> list[dict[str, Any]]:
+        """List Windur desktop snapshots visible to this API key."""
+        params = {"platform": platform} if platform else None
+        resp = await self._http.get("/v1/snapshots", params=params)
+        resp.raise_for_status()
+        return resp.json().get("snapshots", [])
+
     @overload
     async def create(
         self,
@@ -357,6 +380,7 @@ class AsyncComputer:
         *,
         type: Literal["windows", SandboxType.WINDOWS],
         version: str = ...,
+        snapshot: str = ...,
         host: str = ...,
     ) -> AsyncWindowsSandbox: ...
 
@@ -366,6 +390,7 @@ class AsyncComputer:
         *,
         type: Literal["ubuntu", SandboxType.UBUNTU],
         version: str = ...,
+        snapshot: str = ...,
         host: str = ...,
     ) -> AsyncUbuntuSandbox: ...
 
@@ -378,24 +403,31 @@ class AsyncComputer:
         device_type: str = "",
         runtime: str = "",
         version: str = "",
+        snapshot: str = "",
     ) -> AsyncMacOSSandbox | AsyncIOSSandbox | AsyncWindowsSandbox | AsyncUbuntuSandbox:
         """Create a new sandbox.
 
         Args:
-            type: SandboxType.MACOS (default), SandboxType.IOS, or the raw API string.
+            type: SandboxType.MACOS (default), IOS, WINDOWS, UBUNTU, or the raw API string.
             host: Pin sandbox to a specific host machine (e.g. "mm001").
             family: Simulator family enum/alias, for example SimulatorFamily.TV.
             device_type: Simulator device type identifier, for exact pinning.
             runtime: Simulator runtime identifier, for exact pinning.
             version: KVM desktop image version, for example "windows-11",
                 "windows-10", or "ubuntu-24.04".
+            snapshot: Windur snapshot version returned by sandbox.snapshot().
         """
         sandbox_type = _normalize_sandbox_type(type)
         body: dict = {"type": sandbox_type.value}
         if host:
             body["host"] = host
-        if sandbox_type in (SandboxType.WINDOWS, SandboxType.UBUNTU) and version:
-            body["version"] = version
+        if sandbox_type in (SandboxType.WINDOWS, SandboxType.UBUNTU):
+            if version and snapshot:
+                raise ValueError("version and snapshot are mutually exclusive")
+            if snapshot:
+                body["snapshot"] = snapshot
+            elif version:
+                body["version"] = version
         if sandbox_type == SandboxType.IOS:
             if family and (not device_type or not runtime):
                 choice = select_simulator(await self.platforms(), family)

{use_computer-0.0.24 → use_computer-0.0.26}/use_computer/models.py

@@ -88,12 +88,18 @@ class RecordingInfo:
 class ExecResult:
     return_code: int
     stdout: str
+    stderr: str = ""
+
+    @property
+    def exit_code(self) -> int:
+        return self.return_code
 
     @classmethod
     def from_dict(cls, d: dict) -> ExecResult:
         return cls(
-            return_code=d.get("return_code", 0),
+            return_code=d.get("return_code", d.get("exit_code", d.get("returncode", 0))),
             stdout=d.get("stdout", ""),
+            stderr=d.get("stderr", ""),
         )
 
 

{use_computer-0.0.24 → use_computer-0.0.26}/use_computer/sandbox.py

@@ -1,9 +1,11 @@
 from __future__ import annotations
 
+import base64
 import io
 import tarfile
 import threading
 import urllib.request
+from dataclasses import dataclass
 from enum import Enum
 from pathlib import Path
 
@@ -30,6 +32,15 @@ class SandboxType(str, Enum):
     UBUNTU = "ubuntu"
 
 
+@dataclass
+class Snapshot:
+    """Windur-backed desktop snapshot."""
+
+    name: str
+    version: str
+    platform: str
+
+
 # ---------------------------------------------------------------------------
 # Keepalive helper — shared by sync and async sandboxes
 # ---------------------------------------------------------------------------
@@ -134,6 +145,26 @@ class Sandbox:
         resp.raise_for_status()
         local_path.write_bytes(resp.content)
 
+    def snapshot(self, name: str, *, version: str = "", timeout: int = 900) -> Snapshot:
+        """Capture a Windur desktop snapshot and return its image version."""
+        if self.type not in (SandboxType.WINDOWS, SandboxType.UBUNTU):
+            raise PlatformNotSupportedError(
+                action="snapshot",
+                sandbox_type=self.type.value,
+                hint="snapshots are supported for Windows and Ubuntu sandboxes",
+            )
+        body = {"name": name}
+        if version:
+            body["version"] = version
+        resp = self._http.post(f"{self._prefix}/snapshots", json=body, timeout=timeout)
+        resp.raise_for_status()
+        data = resp.json()
+        return Snapshot(
+            name=data.get("name", name),
+            version=data.get("version", version),
+            platform=data.get("platform", self.type.value),
+        )
+
     def start_keepalive(self, interval: float = 30.0) -> None:
         """Start a background thread that pings the gateway every `interval` seconds."""
         self._keepalive_stop, self._keepalive_thread = _start_keepalive_thread(
@@ -256,6 +287,90 @@ class IOSSandbox(Sandbox):
         self.environment = Environment(http, self._prefix)
 
 
+@dataclass
+class HostRedirect:
+    """Point a domain at the loopback host (the /etc/hosts redirect) so a browser
+    hitting it lands on a locally-running app. If ``port`` is set, :80 and :443
+    are also forwarded to 127.0.0.1:port, so e.g. ``https://mail.google.com``
+    reaches a local server on that port."""
+
+    host: str
+    ip: str = "127.0.0.1"
+    port: int | None = None
+
+
+def _build_setup_spec(
+    hosts: list[HostRedirect] | None,
+    files: dict[str, bytes | str] | None,
+    script: str | None,
+    open_urls: list[str] | None,
+    open_apps: list[str] | None,
+) -> dict:
+    spec: dict = {}
+    if hosts:
+        spec["hosts"] = [
+            {"host": h.host, "ip": h.ip, **({"port": h.port} if h.port else {})} for h in hosts
+        ]
+    if files:
+        spec["files"] = [
+            {
+                "path": path,
+                "content_b64": base64.b64encode(
+                    data if isinstance(data, bytes) else data.encode()
+                ).decode(),
+            }
+            for path, data in files.items()
+        ]
+    if script:
+        spec["script"] = script
+    if open_urls:
+        spec["open_urls"] = list(open_urls)
+    if open_apps:
+        spec["open_apps"] = list(open_apps)
+    return spec
+
+
+class _Seeding:
+    """Typed seeding for KVM desktops (windows/ubuntu), applied in order:
+    host redirects → files → script → open_urls → open_apps."""
+
+    _http: httpx.Client
+    _prefix: str
+
+    def setup(
+        self,
+        *,
+        hosts: list[HostRedirect] | None = None,
+        files: dict[str, bytes | str] | None = None,
+        script: str | None = None,
+        open_urls: list[str] | None = None,
+        open_apps: list[str] | None = None,
+    ) -> None:
+        spec = _build_setup_spec(hosts, files, script, open_urls, open_apps)
+        resp = self._http.post(f"{self._prefix}/setup", json=spec, timeout=1200)
+        resp.raise_for_status()
+
+
+class _AsyncSeeding:
+    """Async counterpart of _Seeding."""
+
+    _http: httpx.AsyncClient
+    _prefix: str
+
+    async def setup(
+        self,
+        *,
+        hosts: list[HostRedirect] | None = None,
+        files: dict[str, bytes | str] | None = None,
+        script: str | None = None,
+        open_urls: list[str] | None = None,
+        open_apps: list[str] | None = None,
+    ) -> None:
+        spec = _build_setup_spec(hosts, files, script, open_urls, open_apps)
+        resp = await self._http.post(f"{self._prefix}/setup", json=spec, timeout=1200)
+        resp.raise_for_status()
+
+
 class _NoAxeAccessibility:
     """Mixin for desktop guests without the macOS axe-schema tree."""
 
@@ -275,7 +390,7 @@ class _NoAxeAccessibility:
         pass  # discard the base's axe helper — Windows exposes .ui_tree() instead
 
 
-class WindowsSandbox(_NoAxeAccessibility, Sandbox):
+class WindowsSandbox(_Seeding, _NoAxeAccessibility, Sandbox):
     """Windows VM sandbox (Beta) — mouse, keyboard, PowerShell/cmd exec, VNC.
 
     Beta. Differs from macOS: no SSH (exec runs through the in-guest agent via
@@ -333,7 +448,7 @@ class WindowsSandbox(_NoAxeAccessibility, Sandbox):
         return resp.json()
 
 
-class UbuntuSandbox(_NoAxeAccessibility, Sandbox):
+class UbuntuSandbox(_Seeding, _NoAxeAccessibility, Sandbox):
     """Ubuntu desktop VM sandbox — mouse, keyboard, bash exec, VNC."""
 
     _accessibility_sandbox_type = "ubuntu"
@@ -431,6 +546,26 @@ class AsyncSandbox:
         resp.raise_for_status()
         local_path.write_bytes(resp.content)
 
+    async def snapshot(self, name: str, *, version: str = "", timeout: int = 900) -> Snapshot:
+        """Capture a Windur desktop snapshot and return its image version."""
+        if self.type not in (SandboxType.WINDOWS, SandboxType.UBUNTU):
+            raise PlatformNotSupportedError(
+                action="snapshot",
+                sandbox_type=self.type.value,
+                hint="snapshots are supported for Windows and Ubuntu sandboxes",
+            )
+        body = {"name": name}
+        if version:
+            body["version"] = version
+        resp = await self._http.post(f"{self._prefix}/snapshots", json=body, timeout=timeout)
+        resp.raise_for_status()
+        data = resp.json()
+        return Snapshot(
+            name=data.get("name", name),
+            version=data.get("version", version),
+            platform=data.get("platform", self.type.value),
+        )
+
     async def start_keepalive(self, interval: float = 30.0) -> None:
         """Start a background OS thread that pings the gateway every `interval` seconds.
 
@@ -549,7 +684,7 @@ class AsyncIOSSandbox(AsyncSandbox):
         self.environment = AsyncEnvironment(http, self._prefix)
 
 
-class AsyncWindowsSandbox(_NoAxeAccessibility, AsyncSandbox):
+class AsyncWindowsSandbox(_AsyncSeeding, _NoAxeAccessibility, AsyncSandbox):
     """Async Windows VM sandbox — see WindowsSandbox."""
 
     _accessibility_sandbox_type = "windows"
@@ -605,7 +740,7 @@ class AsyncWindowsSandbox(_NoAxeAccessibility, AsyncSandbox):
         return resp.json()
 
 
-class AsyncUbuntuSandbox(_NoAxeAccessibility, AsyncSandbox):
+class AsyncUbuntuSandbox(_AsyncSeeding, _NoAxeAccessibility, AsyncSandbox):
     """Async Ubuntu desktop VM sandbox — see UbuntuSandbox."""
 
     _accessibility_sandbox_type = "ubuntu"

{use_computer-0.0.24 → use_computer-0.0.26}/use_computer/windows/shell.py

@@ -10,7 +10,7 @@ ShellKind = Literal["bash", "sh", "powershell", "cmd"]
 
 
 class Shell:
-    """Run commands inside a Windows sandbox via the in-guest agent (no SSH)."""
+    """Run commands inside a KVM desktop sandbox via the in-guest agent."""
 
     def __init__(self, http: httpx.Client, prefix: str, default_shell: ShellKind = "powershell"):
         self._http = http