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

{opencomputer_sdk-0.5.4 → opencomputer_sdk-0.6.1}/.gitignore

@@ -19,6 +19,9 @@ Thumbs.db
 .env.*
 !.env.example
 
+# Per-developer dev-box lifecycle state (written by deploy/*/deploy-qemu-dev.sh)
+deploy/**/.qemu-dev-state-*
+
 # Python
 __pycache__/
 *.pyc
@@ -29,8 +32,14 @@ __pycache__/
 # Node
 node_modules/
 
+# api-edge Workers Assets — copied from web/dist at deploy time. Source of truth lives in web/.
+cloudflare-workers/api-edge/assets/
+
 # Build artifacts
 dist/
+# Built dashboard SPA bundle served by the api-edge Worker — produced by
+# `vite build` in web/, copied here by the deploy script. Never check in.
+cloudflare-workers/api-edge/assets/
 
 # Compiled binaries
 bin/
@@ -65,4 +74,7 @@ delme
 deploy/azure/.dev-env-state-*
 deploy/azure/.dev-env-secrets*
 !deploy/azure/.dev-env-secrets.example
+deploy/azure/.dev-vector-token-*
 /server
+/seed-dev-secrets
+/backfill

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opencomputer-sdk
-Version: 0.5.4
+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.5.4 → 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
@@ -20,6 +21,8 @@ from opencomputer.usage import (
     UsageBySandboxResponse,
     UsageByTagResponse,
     SandboxUsageResponse,
+    SandboxUsagePoint,
+    SandboxUsageTotals,
     TagKeyInfo,
 )
 
@@ -27,6 +30,7 @@ __all__ = [
     "Sandbox",
     "ScalingLockedError",
     "PlanLimitError",
+    "SandboxFamilyLimitError",
     "Agent",
     "AgentEvent",
     "AgentSession",
@@ -37,6 +41,8 @@ __all__ = [
     "ExecSession",
     "ExecSessionInfo",
     "Image",
+    "Mounts",
+    "MountInfo",
     "Pty",
     "PtySession",
     "Shell",
@@ -54,7 +60,9 @@ __all__ = [
     "UsageBySandboxResponse",
     "UsageByTagResponse",
     "SandboxUsageResponse",
+    "SandboxUsagePoint",
+    "SandboxUsageTotals",
     "TagKeyInfo",
 ]
 
-__version__ = "0.5.4"
+__version__ = "0.6.0"

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.5.4 → 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.5.4 → opencomputer_sdk-0.6.1}/opencomputer/usage.py

@@ -66,19 +66,50 @@ class UsageByTagResponse:
     next_cursor: str | None
 
 
+@dataclass
+class SandboxUsagePoint:
+    """One 1-minute bucket of memory usage. Integrals (``*_gb_seconds``,
+    ``uptime_seconds``) compose by summation; snapshot scalars
+    (``allocated_memory_mb``, ``used_memory_mb_*``) are for charts.
+
+    v1 is memory only. CPU fields will appear once the server-side
+    collector starts populating cgroup cpu.stat.
+    """
+
+    ts: str
+    memory_allocated_gb_seconds: float
+    memory_used_gb_seconds: float
+    uptime_seconds: int
+    allocated_memory_mb: int
+    used_memory_mb_avg: int
+    used_memory_mb_peak: int
+
+
+@dataclass
+class SandboxUsageTotals:
+    """Envelope totals over ``[from_, to)``. Invariant: summing the
+    matching field across ``points`` reproduces the value here."""
+
+    memory_allocated_gb_seconds: float
+    memory_used_gb_seconds: float
+    uptime_seconds: int
+    memory_allocated_peak_mb: int
+    memory_used_peak_mb: int
+
+
 @dataclass
 class SandboxUsageResponse:
+    """Response for ``GET /sandboxes/:id/usage``. Default window is
+    last 1 hour; max 30 days (server returns 400 beyond that).
+    ``from_`` and ``to`` accept ISO dates (``YYYY-MM-DD``) or RFC3339
+    timestamps."""
+
     sandbox_id: str
     from_: str
     to: str
-    memory_gb_seconds: float
-    disk_overage_gb_seconds: float
-    tags: dict[str, str]
-    tags_last_updated_at: str | None
-    first_started_at: str | None
-    last_ended_at: str | None
+    totals: SandboxUsageTotals
+    points: list[SandboxUsagePoint]
     alias: str | None = None
-    status: str | None = None
 
 
 @dataclass
@@ -235,18 +266,31 @@ class Usage:
         resp = await self._client.get(f"/sandboxes/{sandbox_id}/usage", params=params)
         resp.raise_for_status()
         b = resp.json()
+        t = b.get("totals") or {}
         return SandboxUsageResponse(
             sandbox_id=b["sandboxId"],
             from_=b["from"],
             to=b["to"],
-            memory_gb_seconds=b["memoryGbSeconds"],
-            disk_overage_gb_seconds=b["diskOverageGbSeconds"],
-            tags=b.get("tags") or {},
-            tags_last_updated_at=b.get("tagsLastUpdatedAt"),
-            first_started_at=b.get("firstStartedAt"),
-            last_ended_at=b.get("lastEndedAt"),
+            totals=SandboxUsageTotals(
+                memory_allocated_gb_seconds=t.get("memoryAllocatedGbSeconds", 0.0),
+                memory_used_gb_seconds=t.get("memoryUsedGbSeconds", 0.0),
+                uptime_seconds=t.get("uptimeSeconds", 0),
+                memory_allocated_peak_mb=t.get("memoryAllocatedPeakMb", 0),
+                memory_used_peak_mb=t.get("memoryUsedPeakMb", 0),
+            ),
+            points=[
+                SandboxUsagePoint(
+                    ts=p["ts"],
+                    memory_allocated_gb_seconds=p["memoryAllocatedGbSeconds"],
+                    memory_used_gb_seconds=p["memoryUsedGbSeconds"],
+                    uptime_seconds=p["uptimeSeconds"],
+                    allocated_memory_mb=p["allocatedMemoryMb"],
+                    used_memory_mb_avg=p["usedMemoryMbAvg"],
+                    used_memory_mb_peak=p["usedMemoryMbPeak"],
+                )
+                for p in b.get("points") or []
+            ],
             alias=b.get("alias"),
-            status=b.get("status"),
         )
 
 

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

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