opencomputer-sdk 0.3.0__tar.gz

opencomputer_sdk-0.3.0/.gitignore

@@ -0,0 +1,49 @@
+# OS files
+.DS_Store
+Thumbs.db
+
+# Editor/IDE files
+.cursor/
+*.swp
+*.swo
+*~
+.idea/
+.vscode/
+
+# Environment files
+.env
+.env.*
+!.env.example
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+.pytest_cache/
+
+# Node
+node_modules/
+
+# Build artifacts
+dist/
+
+# Compiled binaries
+bin/opensandbox-server
+bin/opensandbox-worker
+opensandbox-worker
+
+# Worker env (secrets)
+worker.env
+caddy.env
+
+# Loom demo (private)
+sdks/typescript/examples/loom/
+
+# Media files
+*.mp4
+*.gif
+
+# Temp files
+*.tmp
+*.log

opencomputer_sdk-0.3.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: opencomputer-sdk
+Version: 0.3.0
+Summary: Python SDK for OpenComputer - cloud sandbox platform
+Project-URL: Homepage, https://github.com/diggerhq/opensandbox
+Project-URL: Repository, https://github.com/diggerhq/opensandbox
+Project-URL: Documentation, https://github.com/diggerhq/opensandbox/tree/main/sdks/python
+Project-URL: Issues, https://github.com/diggerhq/opensandbox/issues
+Author: OpenComputer
+License-Expression: MIT
+Keywords: cloud,code-execution,containers,opencomputer,sandbox
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# opencomputer
+
+Python SDK for [OpenComputer](https://github.com/diggerhq/opensandbox) — cloud sandbox platform.
+
+## Install
+
+```bash
+pip install opencomputer
+```
+
+## Quick Start
+
+```python
+import asyncio
+from opencomputer import Sandbox
+
+async def main():
+    sandbox = await Sandbox.create(template="base")
+
+    # Execute commands
+    result = await sandbox.commands.run("echo hello")
+    print(result.stdout)  # "hello\n"
+
+    # Read and write files
+    await sandbox.files.write("/tmp/test.txt", "Hello, world!")
+    content = await sandbox.files.read("/tmp/test.txt")
+
+    # Clean up
+    await sandbox.kill()
+    await sandbox.close()
+
+asyncio.run(main())
+```
+
+## Configuration
+
+| Parameter  | Env Variable            | Default                 |
+|------------|------------------------|-------------------------|
+| `api_url`  | `OPENSANDBOX_API_URL`  | `https://app.opencomputer.dev` |
+| `api_key`  | `OPENSANDBOX_API_KEY`  | (none)                  |
+
+## License
+
+MIT

opencomputer_sdk-0.3.0/README.md

@@ -0,0 +1,44 @@
+# opencomputer
+
+Python SDK for [OpenComputer](https://github.com/diggerhq/opensandbox) — cloud sandbox platform.
+
+## Install
+
+```bash
+pip install opencomputer
+```
+
+## Quick Start
+
+```python
+import asyncio
+from opencomputer import Sandbox
+
+async def main():
+    sandbox = await Sandbox.create(template="base")
+
+    # Execute commands
+    result = await sandbox.commands.run("echo hello")
+    print(result.stdout)  # "hello\n"
+
+    # Read and write files
+    await sandbox.files.write("/tmp/test.txt", "Hello, world!")
+    content = await sandbox.files.read("/tmp/test.txt")
+
+    # Clean up
+    await sandbox.kill()
+    await sandbox.close()
+
+asyncio.run(main())
+```
+
+## Configuration
+
+| Parameter  | Env Variable            | Default                 |
+|------------|------------------------|-------------------------|
+| `api_url`  | `OPENSANDBOX_API_URL`  | `https://app.opencomputer.dev` |
+| `api_key`  | `OPENSANDBOX_API_KEY`  | (none)                  |
+
+## License
+
+MIT

opencomputer_sdk-0.3.0/opencomputer/__init__.py

@@ -0,0 +1,19 @@
+"""OpenComputer Python SDK - cloud sandbox platform."""
+
+from opencomputer.sandbox import Sandbox
+from opencomputer.filesystem import Filesystem
+from opencomputer.commands import Commands, ProcessResult
+from opencomputer.pty import Pty, PtySession
+from opencomputer.template import Template
+
+__all__ = [
+    "Sandbox",
+    "Filesystem",
+    "Commands",
+    "ProcessResult",
+    "Pty",
+    "PtySession",
+    "Template",
+]
+
+__version__ = "0.3.0"

opencomputer_sdk-0.3.0/opencomputer/commands.py

@@ -0,0 +1,56 @@
+"""Command execution inside a sandbox."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+
+@dataclass
+class ProcessResult:
+    """Result of a command execution."""
+
+    exit_code: int
+    stdout: str
+    stderr: str
+
+
+@dataclass
+class Commands:
+    """Command execution for a sandbox."""
+
+    _client: httpx.AsyncClient
+    _sandbox_id: str
+
+    async def run(
+        self,
+        command: str,
+        timeout: int = 60,
+        env: dict[str, str] | None = None,
+        cwd: str | None = None,
+    ) -> ProcessResult:
+        """Run a command and wait for completion."""
+        body: dict[str, Any] = {
+            "cmd": command,
+            "timeout": timeout,
+        }
+        if env:
+            body["envs"] = env
+        if cwd:
+            body["cwd"] = cwd
+
+        resp = await self._client.post(
+            f"/sandboxes/{self._sandbox_id}/commands",
+            json=body,
+            timeout=timeout + 5,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+
+        return ProcessResult(
+            exit_code=data.get("exitCode", -1),
+            stdout=data.get("stdout", ""),
+            stderr=data.get("stderr", ""),
+        )

opencomputer_sdk-0.3.0/opencomputer/filesystem.py

@@ -0,0 +1,100 @@
+"""Filesystem operations inside a sandbox."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import httpx
+
+
+@dataclass
+class EntryInfo:
+    """File or directory entry."""
+
+    name: str
+    is_dir: bool
+    path: str
+    size: int = 0
+
+
+@dataclass
+class Filesystem:
+    """Filesystem operations for a sandbox."""
+
+    _client: httpx.AsyncClient
+    _sandbox_id: str
+
+    async def read(self, path: str) -> str:
+        """Read a file as text."""
+        resp = await self._client.get(
+            f"/sandboxes/{self._sandbox_id}/files",
+            params={"path": path},
+        )
+        resp.raise_for_status()
+        return resp.text
+
+    async def read_bytes(self, path: str) -> bytes:
+        """Read a file as bytes."""
+        resp = await self._client.get(
+            f"/sandboxes/{self._sandbox_id}/files",
+            params={"path": path},
+        )
+        resp.raise_for_status()
+        return resp.content
+
+    async def write(self, path: str, content: str | bytes) -> None:
+        """Write content to a file."""
+        data = content if isinstance(content, bytes) else content.encode()
+        resp = await self._client.put(
+            f"/sandboxes/{self._sandbox_id}/files",
+            params={"path": path},
+            content=data,
+        )
+        resp.raise_for_status()
+
+    async def list(self, path: str = "/") -> list[EntryInfo]:
+        """List directory contents."""
+        resp = await self._client.get(
+            f"/sandboxes/{self._sandbox_id}/files/list",
+            params={"path": path},
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        if data is None:
+            return []
+        return [
+            EntryInfo(
+                name=entry["name"],
+                is_dir=entry.get("isDir", False),
+                path=entry.get("path", ""),
+                size=entry.get("size", 0),
+            )
+            for entry in data
+        ]
+
+    async def make_dir(self, path: str) -> None:
+        """Create a directory (and parents)."""
+        resp = await self._client.post(
+            f"/sandboxes/{self._sandbox_id}/files/mkdir",
+            params={"path": path},
+        )
+        resp.raise_for_status()
+
+    async def remove(self, path: str) -> None:
+        """Remove a file or directory."""
+        resp = await self._client.delete(
+            f"/sandboxes/{self._sandbox_id}/files",
+            params={"path": path},
+        )
+        resp.raise_for_status()
+
+    async def exists(self, path: str) -> bool:
+        """Check if a path exists."""
+        try:
+            resp = await self._client.get(
+                f"/sandboxes/{self._sandbox_id}/files",
+                params={"path": path},
+            )
+            return resp.status_code == 200
+        except httpx.HTTPError:
+            return False

opencomputer_sdk-0.3.0/opencomputer/pty.py

@@ -0,0 +1,96 @@
+"""PTY terminal sessions inside a sandbox."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import Callable
+
+import httpx
+import websockets
+
+
+@dataclass
+class PtySession:
+    """An active PTY terminal session."""
+
+    session_id: str
+    sandbox_id: str
+    _ws: websockets.WebSocketClientProtocol | None = None
+    _read_task: asyncio.Task | None = None
+
+    async def send(self, data: str | bytes) -> None:
+        """Send input to the terminal."""
+        if self._ws is None:
+            raise RuntimeError("PTY session not connected")
+        payload = data if isinstance(data, bytes) else data.encode()
+        await self._ws.send(payload)
+
+    async def recv(self) -> bytes:
+        """Receive output from the terminal."""
+        if self._ws is None:
+            raise RuntimeError("PTY session not connected")
+        data = await self._ws.recv()
+        return data if isinstance(data, bytes) else data.encode()
+
+    async def close(self) -> None:
+        """Close the PTY session."""
+        if self._read_task and not self._read_task.done():
+            self._read_task.cancel()
+        if self._ws:
+            await self._ws.close()
+
+
+@dataclass
+class Pty:
+    """PTY terminal session manager for a sandbox."""
+
+    _client: httpx.AsyncClient
+    _sandbox_id: str
+    _api_url: str
+    _api_key: str
+
+    async def create(
+        self,
+        cols: int = 80,
+        rows: int = 24,
+        on_output: Callable[[bytes], None] | None = None,
+    ) -> PtySession:
+        """Create a new PTY session and connect via WebSocket."""
+        # Create session via REST
+        resp = await self._client.post(
+            f"/sandboxes/{self._sandbox_id}/pty",
+            json={"cols": cols, "rows": rows},
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        session_id = data["sessionID"]
+
+        # Connect via WebSocket
+        ws_url = self._api_url.replace("http://", "ws://").replace("https://", "wss://")
+        ws_url = f"{ws_url}/sandboxes/{self._sandbox_id}/pty/{session_id}"
+
+        headers = {}
+        if self._api_key:
+            headers["X-API-Key"] = self._api_key
+
+        ws = await websockets.connect(ws_url, additional_headers=headers)
+
+        session = PtySession(
+            session_id=session_id,
+            sandbox_id=self._sandbox_id,
+            _ws=ws,
+        )
+
+        if on_output:
+            async def _reader() -> None:
+                try:
+                    async for msg in ws:
+                        output = msg if isinstance(msg, bytes) else msg.encode()
+                        on_output(output)
+                except websockets.ConnectionClosed:
+                    pass
+
+            session._read_task = asyncio.create_task(_reader())
+
+        return session

opencomputer_sdk-0.3.0/opencomputer/sandbox.py

@@ -0,0 +1,201 @@
+"""Sandbox class - main entry point for the OpenSandbox SDK."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+
+from opencomputer.commands import Commands
+from opencomputer.filesystem import Filesystem
+from opencomputer.pty import Pty
+
+
+@dataclass
+class Sandbox:
+    """E2B-compatible sandbox interface."""
+
+    sandbox_id: str
+    status: str = "running"
+    template: str = ""
+    domain: str = ""
+    _api_url: str = ""
+    _api_key: str = ""
+    _connect_url: str = ""
+    _token: str = ""
+    _client: httpx.AsyncClient = field(default=None, repr=False)
+    _data_client: httpx.AsyncClient = field(default=None, repr=False)
+
+    @classmethod
+    async def create(
+        cls,
+        template: str = "base",
+        timeout: int = 300,
+        api_key: str | None = None,
+        api_url: str | None = None,
+        envs: dict[str, str] | None = None,
+        metadata: dict[str, str] | None = None,
+    ) -> Sandbox:
+        """Create a new sandbox instance."""
+        url = api_url or os.environ.get("OPENSANDBOX_API_URL", "https://app.opencomputer.dev")
+        url = url.rstrip("/")
+        key = api_key or os.environ.get("OPENSANDBOX_API_KEY", "")
+
+        # Control plane client always uses /api prefix
+        api_base = url if url.endswith("/api") else f"{url}/api"
+
+        headers = {}
+        if key:
+            headers["X-API-Key"] = key
+
+        client = httpx.AsyncClient(base_url=api_base, headers=headers, timeout=30.0)
+
+        body: dict[str, Any] = {
+            "templateID": template,
+            "timeout": timeout,
+        }
+        if envs:
+            body["envs"] = envs
+        if metadata:
+            body["metadata"] = metadata
+
+        resp = await client.post("/sandboxes", json=body)
+        resp.raise_for_status()
+        data = resp.json()
+
+        connect_url = data.get("connectURL", "")
+        token = data.get("token", "")
+
+        # If worker returned a direct connectURL, create a separate client for data ops
+        data_client = None
+        if connect_url and token:
+            data_client = httpx.AsyncClient(
+                base_url=connect_url,
+                headers={"Authorization": f"Bearer {token}"},
+                timeout=30.0,
+            )
+
+        return cls(
+            sandbox_id=data["sandboxID"],
+            status=data.get("status", "running"),
+            template=template,
+            domain=data.get("domain", ""),
+            _api_url=url,
+            _api_key=key,
+            _connect_url=connect_url,
+            _token=token,
+            _client=client,
+            _data_client=data_client,
+        )
+
+    @classmethod
+    async def connect(
+        cls,
+        sandbox_id: str,
+        api_key: str | None = None,
+        api_url: str | None = None,
+    ) -> Sandbox:
+        """Connect to an existing sandbox."""
+        url = api_url or os.environ.get("OPENSANDBOX_API_URL", "https://app.opencomputer.dev")
+        url = url.rstrip("/")
+        key = api_key or os.environ.get("OPENSANDBOX_API_KEY", "")
+
+        api_base = url if url.endswith("/api") else f"{url}/api"
+
+        headers = {}
+        if key:
+            headers["X-API-Key"] = key
+
+        client = httpx.AsyncClient(base_url=api_base, headers=headers, timeout=30.0)
+
+        resp = await client.get(f"/sandboxes/{sandbox_id}")
+        resp.raise_for_status()
+        data = resp.json()
+
+        connect_url = data.get("connectURL", "")
+        token = data.get("token", "")
+
+        data_client = None
+        if connect_url and token:
+            data_client = httpx.AsyncClient(
+                base_url=connect_url,
+                headers={"Authorization": f"Bearer {token}"},
+                timeout=30.0,
+            )
+
+        return cls(
+            sandbox_id=sandbox_id,
+            status=data.get("status", "running"),
+            template=data.get("templateID", ""),
+            domain=data.get("domain", ""),
+            _api_url=url,
+            _api_key=key,
+            _connect_url=connect_url,
+            _token=token,
+            _client=client,
+            _data_client=data_client,
+        )
+
+    @property
+    def _ops_client(self) -> httpx.AsyncClient:
+        """Return the client for data operations (direct worker if available, else CP)."""
+        if self._data_client is not None:
+            return self._data_client
+        return self._client
+
+    async def kill(self) -> None:
+        """Kill and remove the sandbox."""
+        resp = await self._client.delete(f"/sandboxes/{self.sandbox_id}")
+        resp.raise_for_status()
+        self.status = "stopped"
+
+    async def is_running(self) -> bool:
+        """Check if the sandbox is still running."""
+        try:
+            resp = await self._client.get(f"/sandboxes/{self.sandbox_id}")
+            resp.raise_for_status()
+            data = resp.json()
+            self.status = data.get("status", "stopped")
+            return self.status == "running"
+        except httpx.HTTPStatusError:
+            return False
+
+    async def set_timeout(self, timeout: int) -> None:
+        """Update the sandbox timeout in seconds."""
+        resp = await self._client.post(
+            f"/sandboxes/{self.sandbox_id}/timeout",
+            json={"timeout": timeout},
+        )
+        resp.raise_for_status()
+
+    @property
+    def files(self) -> Filesystem:
+        """Access filesystem operations."""
+        return Filesystem(self._ops_client, self.sandbox_id)
+
+    @property
+    def commands(self) -> Commands:
+        """Access command execution."""
+        return Commands(self._ops_client, self.sandbox_id)
+
+    @property
+    def pty(self) -> Pty:
+        """Access PTY terminal sessions."""
+        pty_url = self._connect_url or self._api_url
+        pty_key = self._token or self._api_key
+        return Pty(self._ops_client, self.sandbox_id, pty_url, pty_key)
+
+    async def close(self) -> None:
+        """Close the HTTP client (does not kill the sandbox)."""
+        await self._client.aclose()
+        if self._data_client is not None:
+            await self._data_client.aclose()
+
+    async def __aenter__(self) -> Sandbox:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.kill()
+        await self.close()

opencomputer_sdk-0.3.0/opencomputer/template.py

@@ -0,0 +1,75 @@
+"""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()

opencomputer_sdk-0.3.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "opencomputer-sdk"
+version = "0.3.0"
+description = "Python SDK for OpenComputer - cloud sandbox platform"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "OpenComputer" },
+]
+keywords = ["sandbox", "opencomputer", "cloud", "containers", "code-execution"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27.0",
+    "websockets>=12.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+]
+
+[project.urls]
+Homepage = "https://github.com/diggerhq/opensandbox"
+Repository = "https://github.com/diggerhq/opensandbox"
+Documentation = "https://github.com/diggerhq/opensandbox/tree/main/sdks/python"
+Issues = "https://github.com/diggerhq/opensandbox/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["opencomputer"]
+exclude = ["__pycache__"]