opencomputer-sdk 0.4.6__tar.gz → 0.4.7__tar.gz

{opencomputer_sdk-0.4.6 → opencomputer_sdk-0.4.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opencomputer-sdk
-Version: 0.4.6
+Version: 0.4.7
 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.4.7/examples/test_declarative_images.py

@@ -0,0 +1,337 @@
+#!/usr/bin/env python3
+"""
+Declarative Image Builder & Snapshots Test (Python SDK)
+
+Tests both patterns for defining sandbox environments:
+
+  Pattern 1 — On-demand images (cached by content hash):
+    image = Image.base().apt_install(["curl"])
+    sandbox = await Sandbox.create(image=image)
+
+  Pattern 2 — Pre-built named snapshots:
+    await snapshots.create(name="my-env", image=image)
+    sandbox = await Sandbox.create(snapshot="my-env")
+
+Usage:
+  python examples/test_declarative_images.py
+"""
+
+import asyncio
+import sys
+import time
+
+from opencomputer import Sandbox, Image, Snapshots
+
+passed = 0
+failed = 0
+
+
+def green(msg: str) -> None:
+    print(f"\033[32m\u2713 {msg}\033[0m")
+
+
+def red(msg: str) -> None:
+    print(f"\033[31m\u2717 {msg}\033[0m")
+
+
+def bold(msg: str) -> None:
+    print(f"\033[1m{msg}\033[0m")
+
+
+def dim(msg: str) -> None:
+    print(f"\033[2m  {msg}\033[0m")
+
+
+def check(desc: str, condition: bool, detail: str = "") -> None:
+    global passed, failed
+    if condition:
+        green(desc)
+        passed += 1
+    else:
+        red(f"{desc} ({detail})" if detail else desc)
+        failed += 1
+
+
+async def main() -> None:
+    global passed, failed
+
+    bold("\n╔══════════════════════════════════════════════════════╗")
+    bold("║  Declarative Image Builder & Snapshots Test (Python) ║")
+    bold("╚══════════════════════════════════════════════════════════╝\n")
+
+    sandboxes: list[Sandbox] = []
+    snapshots = Snapshots()
+
+    try:
+        # ── Test: Image builder basics ──────────────────────────────
+        bold("━━━ Test: Image builder basics ━━━\n")
+
+        base = Image.base()
+        with_curl = base.apt_install(["curl"])
+        with_python = with_curl.pip_install(["requests"])
+
+        check("Image.base() uses default base", base.to_dict()["base"] == "base")
+        check("Image is immutable — apt_install returns new instance", len(base.to_dict()["steps"]) == 0)
+        check("Chained image has 1 step", len(with_curl.to_dict()["steps"]) == 1)
+        check("Further chained image has 2 steps", len(with_python.to_dict()["steps"]) == 2)
+
+        check("Different images have different cache keys", base.cache_key() != with_curl.cache_key())
+        check("Same image produces same cache key", base.cache_key() == Image.base().cache_key())
+
+        # File operations
+        with_file = base.add_file("/workspace/config.json", '{"key": "value"}')
+        check("add_file creates a step", len(with_file.to_dict()["steps"]) == 1)
+        check("add_file step type is correct", with_file.to_dict()["steps"][0]["type"] == "add_file")
+        print()
+
+        # ── Pattern 1: On-demand image creation ────────────────────
+        bold("━━━ Pattern 1: On-demand image (first build — cold) ━━━\n")
+
+        image = (
+            Image.base()
+            .apt_install(["curl", "jq"])
+            .run_commands("mkdir -p /workspace/project")
+            .env({"MY_VAR": "hello-from-image", "PROJECT_ROOT": "/workspace/project"})
+            .workdir("/workspace/project")
+        )
+
+        dim(f"Cache key: {image.cache_key()}")
+        dim("Creating sandbox from image (this will build on first run)...")
+
+        t1_start = time.time()
+        sandbox1 = await Sandbox.create(image=image, timeout=300)
+        t1_elapsed = int((time.time() - t1_start) * 1000)
+        sandboxes.append(sandbox1)
+
+        green(f"Sandbox created: {sandbox1.sandbox_id} ({t1_elapsed}ms)")
+        check("Sandbox created successfully", sandbox1.status in ("running", "creating"))
+        print()
+
+        # ── Verify installed packages ──────────────────────────────
+        bold("━━━ Verify: Packages installed ━━━\n")
+
+        curl_check = await sandbox1.commands.run("which curl")
+        check("curl is installed", curl_check.exit_code == 0, f"exit={curl_check.exit_code}")
+
+        jq_check = await sandbox1.commands.run("which jq")
+        check("jq is installed", jq_check.exit_code == 0, f"exit={jq_check.exit_code}")
+        print()
+
+        # ── Verify env vars ────────────────────────────────────────
+        bold("━━━ Verify: Environment variables ━━━\n")
+
+        env_check = await sandbox1.commands.run("bash -lc 'echo $MY_VAR'")
+        check("MY_VAR is set", env_check.stdout.strip() == "hello-from-image", f'got: "{env_check.stdout.strip()}"')
+
+        root_check = await sandbox1.commands.run("bash -lc 'echo $PROJECT_ROOT'")
+        check("PROJECT_ROOT is set", root_check.stdout.strip() == "/workspace/project", f'got: "{root_check.stdout.strip()}"')
+        print()
+
+        # ── Cache hit: second sandbox from same image ──────────────
+        bold("━━━ Pattern 1: Cache hit (second sandbox, same image) ━━━\n")
+
+        dim("Creating second sandbox from same image (should be cached)...")
+        t2_start = time.time()
+        sandbox2 = await Sandbox.create(image=image, timeout=300)
+        t2_elapsed = int((time.time() - t2_start) * 1000)
+        sandboxes.append(sandbox2)
+
+        green(f"Second sandbox created: {sandbox2.sandbox_id} ({t2_elapsed}ms)")
+
+        if t1_elapsed > 5000:
+            check(
+                f"Cache hit is faster ({t2_elapsed}ms vs {t1_elapsed}ms cold build)",
+                t2_elapsed < t1_elapsed,
+                f"cold={t1_elapsed}ms, cached={t2_elapsed}ms",
+            )
+        else:
+            dim(f"Cold build was fast ({t1_elapsed}ms) — skipping speedup check")
+
+        curl_check2 = await sandbox2.commands.run("which curl")
+        check("Cached sandbox also has curl", curl_check2.exit_code == 0)
+        print()
+
+        # Kill sandboxes before creating more
+        for sb in sandboxes:
+            try:
+                await sb.kill()
+            except Exception:
+                pass
+        sandboxes.clear()
+
+        # ── Pattern 2: Pre-built named snapshot ────────────────────
+        bold("━━━ Pattern 2: Create named snapshot ━━━\n")
+
+        snapshot_image = (
+            Image.base()
+            .run_commands(
+                "echo 'snapshot-marker' > /workspace/snapshot-test.txt",
+                "mkdir -p /workspace/data",
+            )
+            .env({"SNAPSHOT_ENV": "from-snapshot"})
+        )
+
+        dim("Creating snapshot 'test-env-py'...")
+        snapshot_info = await snapshots.create(name="test-env-py", image=snapshot_image)
+        green(f"Snapshot created: {snapshot_info['name']} (status={snapshot_info['status']})")
+        check("Snapshot status is ready", snapshot_info["status"] == "ready")
+        print()
+
+        # ── List snapshots ─────────────────────────────────────────
+        bold("━━━ Verify: List snapshots ━━━\n")
+
+        snapshot_list = await snapshots.list()
+        found = next((s for s in snapshot_list if s["name"] == "test-env-py"), None)
+        check("Snapshot appears in list", found is not None)
+        print()
+
+        # ── Get snapshot by name ───────────────────────────────────
+        bold("━━━ Verify: Get snapshot by name ━━━\n")
+
+        fetched = await snapshots.get("test-env-py")
+        check("Fetched snapshot matches", fetched["name"] == "test-env-py")
+        check("Fetched snapshot is ready", fetched["status"] == "ready")
+        print()
+
+        # ── Create sandbox from named snapshot ─────────────────────
+        bold("━━━ Pattern 2: Create sandbox from named snapshot ━━━\n")
+
+        dim("Creating sandbox from snapshot 'test-env-py'...")
+        sandbox3 = await Sandbox.create(snapshot="test-env-py", timeout=300)
+        sandboxes.append(sandbox3)
+
+        check("Sandbox created successfully", sandbox3.status in ("running", "creating"))
+
+        marker_check = await sandbox3.commands.run("cat /workspace/snapshot-test.txt")
+        check("Snapshot marker file exists", marker_check.stdout.strip() == "snapshot-marker", f'got: "{marker_check.stdout.strip()}"')
+
+        snapshot_env_check = await sandbox3.commands.run("bash -lc 'echo $SNAPSHOT_ENV'")
+        check("Snapshot env var is set", snapshot_env_check.stdout.strip() == "from-snapshot", f'got: "{snapshot_env_check.stdout.strip()}"')
+        print()
+
+        # ── Delete snapshot ────────────────────────────────────────
+        bold("━━━ Cleanup: Delete snapshot ━━━\n")
+
+        await snapshots.delete("test-env-py")
+        green("Snapshot 'test-env-py' deleted")
+
+        list_after = await snapshots.list()
+        deleted_found = next((s for s in list_after if s["name"] == "test-env-py"), None)
+        check("Snapshot no longer in list", deleted_found is None)
+        print()
+
+        # Kill sandbox before next test
+        for sb in sandboxes:
+            try:
+                await sb.kill()
+            except Exception:
+                pass
+        sandboxes.clear()
+
+        # ── Test: addFile step ─────────────────────────────────────
+        bold("━━━ Test: add_file — bake files into the image ━━━\n")
+
+        file_image = (
+            Image.base()
+            .add_file("/workspace/config.json", '{"env": "production", "debug": false}')
+            .add_file("/workspace/setup.sh", "#!/bin/bash\necho 'Hello from setup!'")
+            .run_commands("chmod +x /workspace/setup.sh")
+        )
+
+        dim("Creating sandbox with embedded files...")
+        sandbox4 = await Sandbox.create(image=file_image, timeout=300)
+        sandboxes.append(sandbox4)
+
+        config_check = await sandbox4.commands.run("cat /workspace/config.json")
+        check("add_file wrote config.json", '"env": "production"' in config_check.stdout, f'got: "{config_check.stdout.strip()}"')
+
+        setup_check = await sandbox4.commands.run("/workspace/setup.sh")
+        check("add_file wrote executable script", setup_check.stdout.strip() == "Hello from setup!", f'got: "{setup_check.stdout.strip()}"')
+        print()
+
+        # Kill sandbox before next test
+        for sb in sandboxes:
+            try:
+                await sb.kill()
+            except Exception:
+                pass
+        sandboxes.clear()
+
+        # ── Test: Build log streaming ──────────────────────────────
+        bold("━━━ Test: Build log streaming (on_build_log callback) ━━━\n")
+
+        log_image = Image.base().run_commands("echo 'build step 1'", "echo 'build step 2'")
+
+        build_logs: list[str] = []
+        dim("Creating sandbox with build log streaming...")
+        sandbox5 = await Sandbox.create(
+            image=log_image,
+            timeout=300,
+            on_build_log=lambda log: (build_logs.append(log), dim(f"  build: {log}")),
+        )
+        sandboxes.append(sandbox5)
+
+        check("Build log callback was called", len(build_logs) > 0, f"got {len(build_logs)} logs")
+        check("Sandbox created via SSE stream", sandbox5.status in ("running", "creating"))
+        print()
+
+        # Kill sandbox before next test
+        for sb in sandboxes:
+            try:
+                await sb.kill()
+            except Exception:
+                pass
+        sandboxes.clear()
+
+        # ── Test: Snapshot build log streaming ──────────────────────
+        bold("━━━ Test: Snapshot build log streaming (on_build_logs) ━━━\n")
+
+        snapshot_log_image = Image.base().run_commands("echo 'snapshot build'")
+
+        snapshot_logs: list[str] = []
+        dim("Creating snapshot with build log streaming...")
+        streamed_snapshot = await snapshots.create(
+            name="test-streamed-py",
+            image=snapshot_log_image,
+            on_build_logs=lambda log: (snapshot_logs.append(log), dim(f"  snapshot build: {log}")),
+        )
+
+        check("Snapshot build log callback was called", len(snapshot_logs) > 0, f"got {len(snapshot_logs)} logs")
+        check("Streamed snapshot has name", streamed_snapshot["name"] == "test-streamed-py")
+        check("Streamed snapshot is ready", streamed_snapshot["status"] == "ready")
+
+        await snapshots.delete("test-streamed-py")
+        green("Cleaned up test-streamed-py snapshot")
+        print()
+
+    except Exception as err:
+        red(f"Fatal error: {err}")
+        import traceback
+        traceback.print_exc()
+        failed += 1
+    finally:
+        bold("━━━ Cleanup ━━━\n")
+        for sb in sandboxes:
+            try:
+                await sb.kill()
+                dim(f"Killed {sb.sandbox_id}")
+            except Exception:
+                pass
+        try:
+            await snapshots.delete("test-env-py")
+        except Exception:
+            pass
+        try:
+            await snapshots.delete("test-streamed-py")
+        except Exception:
+            pass
+
+    bold("========================================")
+    bold(f" Results: {passed} passed, {failed} failed")
+    bold("========================================\n")
+    if failed > 0:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

{opencomputer_sdk-0.4.6 → opencomputer_sdk-0.4.7}/opencomputer/__init__.py

@@ -4,8 +4,9 @@ from opencomputer.sandbox import Sandbox
 from opencomputer.agent import Agent, AgentEvent, AgentSession, AgentSessionInfo
 from opencomputer.filesystem import Filesystem
 from opencomputer.exec import Exec, ProcessResult, ExecSessionInfo
+from opencomputer.image import Image
 from opencomputer.pty import Pty, PtySession
-from opencomputer.template import Template
+from opencomputer.snapshot import Snapshots
 
 __all__ = [
     "Sandbox",
@@ -17,9 +18,10 @@ __all__ = [
     "Exec",
     "ProcessResult",
     "ExecSessionInfo",
+    "Image",
     "Pty",
     "PtySession",
-    "Template",
+    "Snapshots",
 ]
 
 __version__ = "0.5.0"

{opencomputer_sdk-0.4.6 → opencomputer_sdk-0.4.7}/opencomputer/agent.py

@@ -48,11 +48,13 @@ class Agent:
         sandbox_id: str,
         connect_url: str,
         token: str,
+        api_key: str = "",
     ):
         self._client = client
         self._sandbox_id = sandbox_id
         self._connect_url = connect_url
         self._token = token
+        self._api_key = api_key
 
     async def start(
         self,
@@ -138,8 +140,12 @@ class Agent:
             "https://", "wss://"
         )
         ws_endpoint = f"{ws_url}/sandboxes/{self._sandbox_id}/exec/{session_id}"
+        # WebSocket API cannot set custom headers, so pass credentials as query params.
+        # Prefer JWT token (direct worker access); fall back to API key (control plane).
         if self._token:
             ws_endpoint += f"?token={self._token}"
+        elif self._api_key:
+            ws_endpoint += f"?api_key={self._api_key}"
 
         ws = await websockets.connect(ws_endpoint)
 

opencomputer_sdk-0.4.7/opencomputer/image.py

@@ -0,0 +1,168 @@
+"""Declarative image builder for OpenSandbox."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ImageStep:
+    type: str
+    args: dict[str, Any]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"type": self.type, "args": self.args}
+
+
+@dataclass(frozen=True)
+class Image:
+    """Declarative image builder.
+
+    Defines a reproducible sandbox environment via a fluent API.
+    Under the hood, the manifest is sent to the server which boots a base sandbox,
+    executes each step, checkpoints the result, and caches it by content hash.
+
+    Example::
+
+        image = (
+            Image.base()
+            .apt_install(["curl", "git"])
+            .pip_install(["requests", "pandas"])
+            .add_file("/workspace/config.json", '{"key": "value"}')
+            .env({"PROJECT_ROOT": "/workspace"})
+            .workdir("/workspace")
+        )
+
+        # On-demand: cached by content hash
+        sandbox = await Sandbox.create(image=image)
+
+        # Pre-built snapshot
+        await Snapshot.create(name="data-science", image=image)
+    """
+
+    _base: str = "base"
+    _steps: tuple[ImageStep, ...] = field(default_factory=tuple)
+
+    @classmethod
+    def base(cls) -> Image:
+        """Create a new image starting from the default OpenSandbox environment.
+
+        The base includes Ubuntu 22.04 with Python, Node.js, build tools, and
+        common utilities. Customize by chaining steps like .apt_install(),
+        .pip_install(), .run_commands(), etc.
+        """
+        return cls()
+
+    def apt_install(self, packages: list[str]) -> Image:
+        """Install system packages via apt-get."""
+        return Image(
+            _base=self._base,
+            _steps=(*self._steps, ImageStep("apt_install", {"packages": packages})),
+        )
+
+    def pip_install(self, packages: list[str]) -> Image:
+        """Install Python packages via pip."""
+        return Image(
+            _base=self._base,
+            _steps=(*self._steps, ImageStep("pip_install", {"packages": packages})),
+        )
+
+    def run_commands(self, *commands: str) -> Image:
+        """Run one or more shell commands."""
+        return Image(
+            _base=self._base,
+            _steps=(*self._steps, ImageStep("run", {"commands": list(commands)})),
+        )
+
+    def env(self, vars: dict[str, str]) -> Image:
+        """Set environment variables (written to /etc/environment)."""
+        return Image(
+            _base=self._base,
+            _steps=(*self._steps, ImageStep("env", {"vars": vars})),
+        )
+
+    def workdir(self, path: str) -> Image:
+        """Set the default working directory."""
+        return Image(
+            _base=self._base,
+            _steps=(*self._steps, ImageStep("workdir", {"path": path})),
+        )
+
+    def add_file(self, remote_path: str, content: str) -> Image:
+        """Add a file with inline content to the image.
+
+        Args:
+            remote_path: Absolute path inside the sandbox where the file will be written.
+            content: String content of the file.
+        """
+        encoded = base64.b64encode(content.encode()).decode()
+        return Image(
+            _base=self._base,
+            _steps=(*self._steps, ImageStep("add_file", {
+                "path": remote_path,
+                "content": encoded,
+                "encoding": "base64",
+            })),
+        )
+
+    def add_local_file(self, local_path: str, remote_path: str) -> Image:
+        """Add a local file into the image.
+
+        Reads the file from disk and embeds its content in the manifest.
+
+        Args:
+            local_path: Path to the file on the local machine.
+            remote_path: Absolute path inside the sandbox where the file will be written.
+        """
+        with open(local_path, "rb") as f:
+            encoded = base64.b64encode(f.read()).decode()
+        return Image(
+            _base=self._base,
+            _steps=(*self._steps, ImageStep("add_file", {
+                "path": remote_path,
+                "content": encoded,
+                "encoding": "base64",
+            })),
+        )
+
+    def add_local_dir(self, local_path: str, remote_path: str) -> Image:
+        """Add a local directory into the image.
+
+        Recursively reads all files and embeds them in the manifest.
+
+        Args:
+            local_path: Path to the directory on the local machine.
+            remote_path: Absolute path inside the sandbox where the directory will be created.
+        """
+        files: list[dict[str, str]] = []
+        for root, _dirs, filenames in os.walk(local_path):
+            for fname in filenames:
+                full = os.path.join(root, fname)
+                rel = os.path.relpath(full, local_path)
+                with open(full, "rb") as f:
+                    encoded = base64.b64encode(f.read()).decode()
+                files.append({"relativePath": rel, "content": encoded})
+        return Image(
+            _base=self._base,
+            _steps=(*self._steps, ImageStep("add_dir", {
+                "path": remote_path,
+                "files": files,
+            })),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Returns the manifest as a plain dict (for JSON serialization)."""
+        return {
+            "base": self._base,
+            "steps": [s.to_dict() for s in self._steps],
+        }
+
+    def cache_key(self) -> str:
+        """Compute a deterministic content hash for caching."""
+        canonical = json.dumps(self.to_dict(), sort_keys=True, separators=(",", ":"))
+        return hashlib.sha256(canonical.encode()).hexdigest()

{opencomputer_sdk-0.4.6 → opencomputer_sdk-0.4.7}/opencomputer/pty.py

@@ -70,9 +70,13 @@ class Pty:
         ws_url = self._api_url.replace("http://", "ws://").replace("https://", "wss://")
         ws_url = f"{ws_url}/sandboxes/{self._sandbox_id}/pty/{session_id}"
 
+        # Pass credentials as both header and query param for compatibility.
+        # Python websockets supports custom headers, but query params work
+        # consistently across all WebSocket implementations.
         headers = {}
         if self._api_key:
             headers["X-API-Key"] = self._api_key
+            ws_url += f"?api_key={self._api_key}"
 
         ws = await websockets.connect(ws_url, additional_headers=headers)
 

{opencomputer_sdk-0.4.6 → opencomputer_sdk-0.4.7}/opencomputer/sandbox.py

@@ -4,14 +4,16 @@ from __future__ import annotations
 
 import os
 from dataclasses import dataclass, field
-from typing import Any
+from typing import Any, Callable
 
 import httpx
 
 from opencomputer.agent import Agent
 from opencomputer.exec import Exec
 from opencomputer.filesystem import Filesystem
+from opencomputer.image import Image
 from opencomputer.pty import Pty
+from opencomputer.sse import parse_sse_stream
 
 
 @dataclass
@@ -37,8 +39,23 @@ class Sandbox:
         api_url: str | None = None,
         envs: dict[str, str] | None = None,
         metadata: dict[str, str] | None = None,
+        image: Image | None = None,
+        snapshot: str | None = None,
+        on_build_log: Callable[[str], None] | None = None,
     ) -> Sandbox:
-        """Create a new sandbox instance."""
+        """Create a new sandbox instance.
+
+        Args:
+            template: Base template name (default "base").
+            timeout: Sandbox timeout in seconds (default 300).
+            api_key: API key (or OPENCOMPUTER_API_KEY env var).
+            api_url: API URL (or OPENCOMPUTER_API_URL env var).
+            envs: Environment variables to inject.
+            metadata: Arbitrary metadata tags.
+            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.
+        """
         url = api_url or os.environ.get("OPENCOMPUTER_API_URL", "https://app.opencomputer.dev")
         url = url.rstrip("/")
         key = api_key or os.environ.get("OPENCOMPUTER_API_KEY", "")
@@ -46,11 +63,17 @@ class Sandbox:
         # Control plane client always uses /api prefix
         api_base = url if url.endswith("/api") else f"{url}/api"
 
-        headers = {}
+        headers: dict[str, str] = {}
         if key:
             headers["X-API-Key"] = key
 
-        client = httpx.AsyncClient(base_url=api_base, headers=headers, timeout=30.0)
+        use_sse = on_build_log is not None and (image is not None or snapshot is not None)
+        if use_sse:
+            headers["Accept"] = "text/event-stream"
+
+        # Image builds may take longer
+        client_timeout = 300.0 if image else 30.0
+        client = httpx.AsyncClient(base_url=api_base, headers=headers, timeout=client_timeout)
 
         body: dict[str, Any] = {
             "templateID": template,
@@ -60,10 +83,17 @@ class Sandbox:
             body["envs"] = envs
         if metadata:
             body["metadata"] = metadata
-
-        resp = await client.post("/sandboxes", json=body)
-        resp.raise_for_status()
-        data = resp.json()
+        if image is not None:
+            body["image"] = image.to_dict()
+        if snapshot is not None:
+            body["snapshot"] = snapshot
+
+        if use_sse:
+            data = await cls._create_with_sse(client, body, on_build_log)
+        else:
+            resp = await client.post("/sandboxes", json=body)
+            resp.raise_for_status()
+            data = resp.json()
 
         connect_url = data.get("connectURL", "")
         token = data.get("token", "")
@@ -89,6 +119,18 @@ class Sandbox:
             _data_client=data_client,
         )
 
+    @classmethod
+    async def _create_with_sse(
+        cls,
+        client: httpx.AsyncClient,
+        body: dict[str, Any],
+        on_build_log: Callable[[str], None] | None,
+    ) -> dict[str, Any]:
+        """Create sandbox with SSE build log streaming."""
+        async with client.stream("POST", "/sandboxes", json=body) as resp:
+            resp.raise_for_status()
+            return await parse_sse_stream(resp, on_build_log or (lambda _: None))
+
     @classmethod
     async def connect(
         cls,
@@ -173,7 +215,7 @@ class Sandbox:
     @property
     def agent(self) -> Agent:
         """Access Claude Agent SDK sessions."""
-        return Agent(self._ops_client, self.sandbox_id, self._connect_url, self._token)
+        return Agent(self._ops_client, self.sandbox_id, self._connect_url, self._token, self._api_key)
 
     @property
     def files(self) -> Filesystem:

opencomputer_sdk-0.4.7/opencomputer/snapshot.py

@@ -0,0 +1,105 @@
+"""Snapshot management for OpenSandbox - pre-built named image checkpoints."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Callable
+
+import httpx
+
+from opencomputer.image import Image
+from opencomputer.sse import parse_sse_stream
+
+
+class Snapshots:
+    """Manage pre-built snapshots (named, persistent image checkpoints).
+
+    Example::
+
+        snapshots = Snapshots()
+
+        image = (
+            Image.base()
+            .apt_install(["python3", "python3-pip"])
+            .pip_install(["pandas", "numpy"])
+        )
+
+        await snapshots.create(name="data-science", image=image)
+        info = await snapshots.get("data-science")
+        all_snapshots = await snapshots.list()
+        await snapshots.delete("data-science")
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        api_url: str | None = None,
+    ) -> None:
+        url = api_url or os.environ.get("OPENCOMPUTER_API_URL", "https://app.opencomputer.dev")
+        url = url.rstrip("/")
+        key = api_key or os.environ.get("OPENCOMPUTER_API_KEY", "")
+
+        api_base = url if url.endswith("/api") else f"{url}/api"
+
+        self._headers: dict[str, str] = {}
+        if key:
+            self._headers["X-API-Key"] = key
+
+        self._api_base = api_base
+        self._client = httpx.AsyncClient(base_url=api_base, headers=self._headers, timeout=300.0)
+
+    async def create(
+        self,
+        name: str,
+        image: Image,
+        on_build_logs: Callable[[str], None] | None = None,
+    ) -> dict[str, Any]:
+        """Create a pre-built snapshot from a declarative image.
+
+        Args:
+            name: Unique name for this snapshot.
+            image: Declarative Image definition.
+            on_build_logs: Optional callback for build log streaming.
+
+        Returns:
+            Snapshot info dict with id, name, status, etc.
+        """
+        body = {"name": name, "image": image.to_dict()}
+
+        if on_build_logs is not None:
+            headers = {**self._headers, "Accept": "text/event-stream"}
+            client = httpx.AsyncClient(
+                base_url=self._api_base, headers=headers, timeout=300.0,
+            )
+            try:
+                async with client.stream("POST", "/snapshots", json=body) as resp:
+                    resp.raise_for_status()
+                    return await parse_sse_stream(resp, on_build_logs)
+            finally:
+                await client.aclose()
+
+        resp = await self._client.post("/snapshots", json=body)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def list(self) -> list[dict[str, Any]]:
+        """List all named snapshots for the current org."""
+        resp = await self._client.get("/snapshots")
+        resp.raise_for_status()
+        return resp.json()
+
+    async def get(self, name: str) -> dict[str, Any]:
+        """Get a snapshot by name."""
+        resp = await self._client.get(f"/snapshots/{name}")
+        resp.raise_for_status()
+        return resp.json()
+
+    async def delete(self, name: str) -> None:
+        """Delete a named snapshot."""
+        resp = await self._client.delete(f"/snapshots/{name}")
+        if resp.status_code != 404:
+            resp.raise_for_status()
+
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        await self._client.aclose()

opencomputer_sdk-0.4.7/opencomputer/sse.py

@@ -0,0 +1,73 @@
+"""Shared SSE stream parser for build log streaming."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Callable
+
+import httpx
+
+
+async def parse_sse_stream(
+    resp: httpx.Response,
+    on_log: Callable[[str], None],
+) -> dict[str, Any]:
+    """Parse an SSE stream from the server.
+
+    The server emits three event types:
+      - build_log: streamed during image build, contains { step, type, message }
+      - error: build failed, contains { error: string }
+      - result: final result JSON
+
+    Args:
+        resp: httpx streaming response with content-type text/event-stream
+        on_log: Callback for build log messages
+
+    Returns:
+        The parsed result dict from the "result" event
+
+    Raises:
+        RuntimeError: If the build fails or no result is received
+    """
+    result: dict[str, Any] | None = None
+    buffer = ""
+
+    async for chunk in resp.aiter_text():
+        buffer += chunk
+        events = buffer.split("\n\n")
+        buffer = events[-1]
+
+        for event in events[:-1]:
+            if not event.strip():
+                continue
+
+            event_type = ""
+            data = ""
+            for line in event.split("\n"):
+                if line.startswith("event: "):
+                    event_type = line[7:]
+                elif line.startswith("data: "):
+                    data = line[6:]
+
+            if not data:
+                continue
+
+            if event_type == "build_log":
+                try:
+                    parsed = json.loads(data)
+                    on_log(parsed.get("message", data))
+                except (json.JSONDecodeError, TypeError):
+                    on_log(data)
+            elif event_type == "error":
+                msg = data
+                try:
+                    msg = json.loads(data).get("error", data)
+                except (json.JSONDecodeError, TypeError):
+                    pass
+                raise RuntimeError(f"Build failed: {msg}")
+            elif event_type == "result":
+                result = json.loads(data)
+
+    if not result:
+        raise RuntimeError("No result received from build stream")
+    return result

{opencomputer_sdk-0.4.6 → opencomputer_sdk-0.4.7}/pyproject.toml

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

opencomputer_sdk-0.4.6/opencomputer/template.py

@@ -1,75 +0,0 @@
-"""Template management for custom sandbox environments."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-import httpx
-
-
-@dataclass
-class TemplateInfo:
-    """Template metadata."""
-
-    template_id: str
-    name: str
-    tag: str
-    status: str
-
-
-@dataclass
-class Template:
-    """Template management operations."""
-
-    _client: httpx.AsyncClient
-
-    @classmethod
-    def _from_client(cls, client: httpx.AsyncClient) -> Template:
-        return cls(_client=client)
-
-    async def build(self, name: str, dockerfile: str) -> TemplateInfo:
-        """Build a new template from a Dockerfile."""
-        resp = await self._client.post(
-            "/templates",
-            json={"name": name, "dockerfile": dockerfile},
-            timeout=300.0,
-        )
-        resp.raise_for_status()
-        data = resp.json()
-        return TemplateInfo(
-            template_id=data["templateID"],
-            name=data["name"],
-            tag=data.get("tag", "latest"),
-            status=data.get("status", "ready"),
-        )
-
-    async def list(self) -> list[TemplateInfo]:
-        """List all available templates."""
-        resp = await self._client.get("/templates")
-        resp.raise_for_status()
-        return [
-            TemplateInfo(
-                template_id=t["templateID"],
-                name=t["name"],
-                tag=t.get("tag", "latest"),
-                status=t.get("status", "ready"),
-            )
-            for t in resp.json()
-        ]
-
-    async def get(self, name: str) -> TemplateInfo:
-        """Get template details by name."""
-        resp = await self._client.get(f"/templates/{name}")
-        resp.raise_for_status()
-        data = resp.json()
-        return TemplateInfo(
-            template_id=data["templateID"],
-            name=data["name"],
-            tag=data.get("tag", "latest"),
-            status=data.get("status", "ready"),
-        )
-
-    async def delete(self, name: str) -> None:
-        """Delete a template."""
-        resp = await self._client.delete(f"/templates/{name}")
-        resp.raise_for_status()