opencomputer-sdk 0.6.0__tar.gz → 0.6.1__tar.gz

{opencomputer_sdk-0.6.0 → opencomputer_sdk-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opencomputer-sdk
-Version: 0.6.0
+Version: 0.6.1
 Summary: Python SDK for OpenComputer - cloud sandbox platform
 Project-URL: Homepage, https://github.com/diggerhq/opensandbox
 Project-URL: Repository, https://github.com/diggerhq/opensandbox

{opencomputer_sdk-0.6.0 → opencomputer_sdk-0.6.1}/opencomputer/__init__.py

@@ -1,10 +1,11 @@
 """OpenComputer Python SDK - cloud sandbox platform."""
 
-from opencomputer.sandbox import Sandbox, ScalingLockedError, PlanLimitError
+from opencomputer.sandbox import Sandbox, ScalingLockedError, PlanLimitError, SandboxFamilyLimitError
 from opencomputer.agent import Agent, AgentEvent, AgentSession, AgentSessionInfo
 from opencomputer.filesystem import Filesystem
 from opencomputer.exec import Exec, ProcessResult, ExecSession, ExecSessionInfo
 from opencomputer.image import Image
+from opencomputer.mounts import Mounts, MountInfo
 from opencomputer.pty import Pty, PtySession
 from opencomputer.shell import Shell, ShellBusyError, ShellClosedError
 from opencomputer.template import Template
@@ -29,6 +30,7 @@ __all__ = [
     "Sandbox",
     "ScalingLockedError",
     "PlanLimitError",
+    "SandboxFamilyLimitError",
     "Agent",
     "AgentEvent",
     "AgentSession",
@@ -39,6 +41,8 @@ __all__ = [
     "ExecSession",
     "ExecSessionInfo",
     "Image",
+    "Mounts",
+    "MountInfo",
     "Pty",
     "PtySession",
     "Shell",

opencomputer_sdk-0.6.1/opencomputer/mounts.py

@@ -0,0 +1,124 @@
+"""FUSE-backed remote filesystem mounts inside a sandbox.
+
+Mounts use ``rclone mount`` under the hood — one driver covering ~40 backends
+(S3, GCS, Azure Blob, SFTP, WebDAV, Dropbox, etc.). Credentials are passed
+inline, written to a tmpfs file inside the VM (mode 0600), and never persisted
+on the worker. v1 does NOT auto-restore mounts on hibernate/wake — callers
+re-issue ``add(...)`` after a wake if they need the mount back.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+import httpx
+
+MountBackend = Literal["s3", "gcs", "azureblob", "sftp", "webdav", "dropbox"]
+
+
+@dataclass
+class MountInfo:
+    """An active mount as tracked by the worker.
+
+    ``rclone_version`` is the rclone version inside the sandbox captured at
+    mount-add time (e.g. ``"v1.65.2"``). rclone is baked into the rootfs, so
+    different sandboxes may carry different versions; this lets ops triage
+    backend-specific bug reports quickly.
+    """
+
+    path: str
+    remote: str
+    read_only: bool
+    backend: str = ""
+    rclone_version: str = ""
+
+
+@dataclass
+class Mounts:
+    """Mount remote filesystems via rclone+FUSE inside the sandbox."""
+
+    _client: httpx.AsyncClient
+    _sandbox_id: str
+
+    async def add(
+        self,
+        path: str,
+        remote: str,
+        backend: MountBackend | None = None,
+        creds: dict[str, str] | None = None,
+        rclone_config: str | None = None,
+        read_only: bool = True,
+        mount_options: list[str] | None = None,
+    ) -> MountInfo:
+        """Mount a remote filesystem at ``path`` inside the sandbox.
+
+        Args:
+            path: Absolute path inside the VM where the remote will be mounted.
+            remote: rclone remote spec — ``"<name>:<path>"`` (e.g. ``"s3:my-bucket/prefix"``).
+            backend: One of ``s3``, ``gcs``, ``azureblob``, ``sftp``, ``webdav``,
+                ``dropbox``. Determines how ``creds`` are templated into the
+                rclone config. Omit when passing ``rclone_config`` directly.
+            creds: Backend-specific config keys (rclone field names — e.g. for
+                S3: ``access_key_id``, ``secret_access_key``, ``region``).
+            rclone_config: Raw rclone config string. Overrides ``backend`` and
+                ``creds`` — useful for backends not in the typed list or for
+                advanced tuning.
+            read_only: Default ``True``. Object-store FUSE mounts have
+                well-known write footguns; opt in to RW explicitly.
+            mount_options: Extra args appended to ``rclone mount`` (e.g.
+                ``["--dir-cache-time", "1m"]``).
+        """
+        body: dict[str, object] = {
+            "path": path,
+            "remote": remote,
+            "readOnly": read_only,
+        }
+        if backend is not None:
+            body["backend"] = backend
+        if creds is not None:
+            body["creds"] = creds
+        if rclone_config is not None:
+            body["rcloneConfig"] = rclone_config
+        if mount_options is not None:
+            body["mountOptions"] = mount_options
+
+        resp = await self._client.post(
+            f"/sandboxes/{self._sandbox_id}/mounts", json=body
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        return _mount_from_dict(data)
+
+    async def list(self) -> list[MountInfo]:
+        """List the mounts this worker is tracking for the sandbox.
+
+        Returns empty after hibernate/wake — re-issue ``add()`` for any mounts
+        you need back.
+        """
+        resp = await self._client.get(f"/sandboxes/{self._sandbox_id}/mounts")
+        resp.raise_for_status()
+        data = resp.json() or []
+        return [_mount_from_dict(entry) for entry in data]
+
+    async def remove(self, path: str) -> None:
+        """Unmount a path previously passed to ``add()``. No-op if not mounted."""
+        try:
+            resp = await self._client.delete(
+                f"/sandboxes/{self._sandbox_id}/mounts", params={"path": path}
+            )
+            if resp.status_code == 404:
+                return
+            resp.raise_for_status()
+        except httpx.HTTPError:
+            raise
+
+
+def _mount_from_dict(data: dict) -> MountInfo:
+    return MountInfo(
+        path=data["path"],
+        remote=data["remote"],
+        backend=data.get("backend", ""),
+        read_only=data.get("readOnly", True),
+        rclone_version=data.get("rcloneVersion", ""),
+    )

{opencomputer_sdk-0.6.0 → opencomputer_sdk-0.6.1}/opencomputer/sandbox.py

@@ -12,6 +12,7 @@ from opencomputer.agent import Agent
 from opencomputer.exec import Exec
 from opencomputer.filesystem import Filesystem
 from opencomputer.image import Image
+from opencomputer.mounts import Mounts
 from opencomputer.pty import Pty
 from opencomputer.sse import parse_sse_stream
 
@@ -33,6 +34,14 @@ class PlanLimitError(Exception):
     """
 
 
+class SandboxFamilyLimitError(Exception):
+    """Raised when a resource-changing call is blocked by a sandbox family.
+    Kept for compatibility with older API responses.
+    """
+
+    code = "sandbox_family_scale_disabled"
+
+
 def _raise_scaling_error(resp: httpx.Response, action: str) -> None:
     """Inspect a non-OK scaling response and raise the most specific error.
     Falls back to ``raise_for_status`` so callers still see HTTP details for
@@ -43,6 +52,8 @@ def _raise_scaling_error(resp: httpx.Response, action: str) -> None:
         body = {}
     if resp.status_code == 403 and isinstance(body, dict) and body.get("code") == "scaling_locked":
         raise ScalingLockedError(body.get("error", "scaling is locked on this sandbox"))
+    if resp.status_code == 403 and isinstance(body, dict) and body.get("code") == "sandbox_family_scale_disabled":
+        raise SandboxFamilyLimitError(body.get("error", "sandbox family does not allow scaling"))
     if resp.status_code == 402:
         msg = body.get("error", "plan limit exceeded") if isinstance(body, dict) else "plan limit exceeded"
         raise PlanLimitError(msg)
@@ -75,7 +86,10 @@ class Sandbox:
         api_url: str | None = None,
         envs: dict[str, str] | None = None,
         metadata: dict[str, str] | None = None,
+        burst: bool | None = None,
+        sandbox_family: str | None = None,
         disk_mb: int | None = None,
+        memory_mb: int | None = None,
         secret_store: str | None = None,
         image: Image | None = None,
         snapshot: str | None = None,
@@ -90,11 +104,18 @@ class Sandbox:
             api_url: API URL (or OPENCOMPUTER_API_URL env var).
             envs: Environment variables to inject. Overrides store secrets.
             metadata: Custom metadata key-value pairs.
+            burst: Create a Burst Sandbox. Disk is preserved across
+                infrastructure restarts; processes may restart.
+            sandbox_family: Internal/legacy placement family. Prefer
+                ``burst=True`` for public API usage.
             disk_mb: Workspace disk size in MB (default 20480 = 20GB). Any
                 additional GB above 20GB is metered at a per-second rate
                 comparable to EBS gp3. Closed beta: requests above 20GB
                 require the org's ``max_disk_mb`` to be raised. Contact us:
                 https://cal.com/team/digger/opencomputer-founder-chat
+            memory_mb: Memory in MB. On a snapshot/checkpoint fork the server
+                clamps this to [snapshot memory, 16 GB]; the new sandbox's
+                ``memory_mb`` reflects the effective value.
             secret_store: Secret store name — resolves encrypted secrets
                 and egress allowlist.
             image: Declarative Image definition. The server builds and caches it as a checkpoint.
@@ -130,8 +151,14 @@ class Sandbox:
             body["envs"] = envs
         if metadata:
             body["metadata"] = metadata
+        if burst is not None:
+            body["burst"] = burst
+        if sandbox_family:
+            body["sandboxFamily"] = sandbox_family
         if disk_mb is not None:
             body["diskMB"] = disk_mb
+        if memory_mb is not None:
+            body["memoryMB"] = memory_mb
         if secret_store:
             body["secretStore"] = secret_store
         if image is not None:
@@ -270,6 +297,32 @@ class Sandbox:
         resp = await self._client.post(f"/sandboxes/{self.sandbox_id}/power-cycle")
         resp.raise_for_status()
 
+    async def hibernate(self) -> None:
+        """Hibernate the sandbox.
+
+        Snapshots the running VM (RAM + disk) to storage and frees its worker
+        slot. The sandbox keeps its ID, disks, env, and secrets; in-memory
+        process state is preserved and restored on :meth:`wake`. Compute
+        billing stops while hibernated (only storage is metered).
+        """
+        resp = await self._client.post(f"/sandboxes/{self.sandbox_id}/hibernate")
+        resp.raise_for_status()
+        self.status = "hibernated"
+
+    async def wake(self, timeout: int | None = None) -> None:
+        """Wake a hibernated sandbox.
+
+        Restores the VM from its hibernation snapshot on a worker — running
+        processes resume where they left off. Optionally set a new idle
+        ``timeout`` (seconds; ``0`` = persistent, never auto-hibernate).
+        """
+        body: dict[str, Any] = {}
+        if timeout is not None:
+            body["timeout"] = timeout
+        resp = await self._client.post(f"/sandboxes/{self.sandbox_id}/wake", json=body)
+        resp.raise_for_status()
+        self.status = "running"
+
     async def is_running(self) -> bool:
         """Check if the sandbox is still running."""
         try:
@@ -482,6 +535,11 @@ class Sandbox:
         """Access filesystem operations."""
         return Filesystem(self._ops_client, self.sandbox_id)
 
+    @property
+    def mounts(self) -> Mounts:
+        """Mount remote filesystems (S3, GCS, SFTP, …) via rclone+FUSE."""
+        return Mounts(self._ops_client, self.sandbox_id)
+
     @property
     def exec(self) -> Exec:
         """Access session-based command execution."""

{opencomputer_sdk-0.6.0 → opencomputer_sdk-0.6.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "opencomputer-sdk"
-version = "0.6.0"
+version = "0.6.1"
 description = "Python SDK for OpenComputer - cloud sandbox platform"
 readme = "README.md"
 requires-python = ">=3.10"