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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opencomputer-sdk
-Version: 0.6.0
+Version: 0.6.2
 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.2}/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.2/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.2}/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)
@@ -59,6 +70,12 @@ class Sandbox:
     sandbox_id: str
     status: str = "running"
     template: str = ""
+    #: Plaintext preview-URL bearer token, available immediately after a
+    #: ``Sandbox.create(preview_auth=...)`` call. Read it once and store
+    #: it somewhere durable — the server will not return it again. After
+    #: a successful ``rotate_preview_auth_token()`` this value is replaced
+    #: with the new token. Empty string when not enabled or when reconnecting.
+    preview_auth_token: str = ""
     _api_url: str = ""
     _api_key: str = ""
     _connect_url: str = ""
@@ -75,11 +92,15 @@ 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,
         on_build_log: Callable[[str], None] | None = None,
+        preview_auth: dict[str, str] | None = None,
     ) -> Sandbox:
         """Create a new sandbox instance.
 
@@ -90,16 +111,32 @@ 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.
             snapshot: Name of a pre-built snapshot to create the sandbox from.
             on_build_log: Callback for build log streaming when using image/snapshot.
+            preview_auth: Require a bearer token on the sandbox's preview URLs.
+                When set, every request to ``https://sb-{id}-p{port}.<domain>``
+                must include the token in an ``Authorization: Bearer <token>``
+                or ``X-OC-Preview-Token`` header. The check happens at the edge
+                before traffic reaches the VM. Pass ``{"token": "auto"}`` (or
+                omit the key) to have the server generate a 256-bit random
+                token; pass an explicit string (>=16 chars) to bring your own.
+                The plaintext is returned exactly once and assigned to
+                ``sandbox.preview_auth_token``.
         """
         url = api_url or os.environ.get("OPENCOMPUTER_API_URL", "https://app.opencomputer.dev")
         url = url.rstrip("/")
@@ -130,14 +167,25 @@ 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:
             body["image"] = image.to_dict()
         if snapshot is not None:
             body["snapshot"] = snapshot
+        if preview_auth is not None:
+            body["previewAuth"] = {
+                "scheme": preview_auth.get("scheme", "bearer"),
+                "token": preview_auth.get("token", "auto"),
+            }
 
         if use_sse:
             data = await cls._create_with_sse(client, body, on_build_log)
@@ -162,6 +210,7 @@ class Sandbox:
             sandbox_id=data["sandboxID"],
             status=data.get("status", "running"),
             template=template,
+            preview_auth_token=data.get("previewAuthToken", ""),
             _api_url=url,
             _api_key=key,
             _connect_url=connect_url,
@@ -270,6 +319,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 +557,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."""
@@ -751,6 +831,25 @@ class Sandbox:
         if resp.status_code != 404:
             resp.raise_for_status()
 
+    async def rotate_preview_auth_token(self) -> str:
+        """Issue a new preview-URL bearer token; invalidate the previous one.
+
+        The old token stops working immediately — there is no zero-downtime
+        dual-token mode in v1, so coordinate the rollover with whoever is
+        calling your preview URL. If the sandbox was created without
+        ``preview_auth``, calling this enables the auth gate from now on.
+
+        Returns the new plaintext token (also written to
+        ``self.preview_auth_token``).
+        """
+        resp = await self._client.post(
+            f"/sandboxes/{self.sandbox_id}/preview/rotate",
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        self.preview_auth_token = data["previewAuthToken"]
+        return self.preview_auth_token
+
     async def create_preview_url(self, port: int, domain: str | None = None, auth_config: dict | None = None) -> dict:
         """Create a preview URL targeting a specific container port.
 

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

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