runcloud-sdk 0.7.0__tar.gz

runcloud_sdk-0.7.0/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+Copyright 2026 Newly
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

runcloud_sdk-0.7.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: runcloud-sdk
+Version: 0.7.0
+Summary: Python SDK for run.cloud, including sandbox-provider compatibility adapters
+Author: Newly
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://run.cloud
+Project-URL: Documentation, https://docs.run.cloud
+Project-URL: Repository, https://github.com/newly-app/newly/tree/main/run-cloud/python-sdk
+Keywords: runcloud,run-cloud,sandbox,microvm,firecracker,sdk
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# runcloud
+
+Python SDK for [run.cloud](https://run.cloud).
+
+```bash
+pip install runcloud-sdk
+export RUN_CLOUD_API_KEY="rc_live_..."
+```
+
+```python
+from runcloud import Client
+
+cloud = Client()
+box = cloud.create(image="runcloud/agent-base", cpu=2, memory=4096)
+try:
+    result = box.exec("python -V")
+    print(result.stdout)
+finally:
+    box.destroy()
+```
+
+## Compatibility adapters
+
+The same distribution includes migration adapters:
+
+| Provider | Import |
+| --- | --- |
+| Modal | `from runcloud.compat import modal` |
+| E2B | `from runcloud.compat.e2b import Sandbox` |
+| Daytona | `from runcloud.compat.daytona import Daytona` |
+| Vercel Sandbox | `from runcloud.compat.vercel import Sandbox` |
+| Blaxel async | `from runcloud.compat.blaxel import SandboxInstance` |
+| Blaxel sync | `from runcloud.compat.blaxel import SyncSandboxInstance` |
+| Fly Sprites | `from runcloud.compat.sprites import SpritesClient` |
+
+Adapters cover creation, command execution, lookup/listing, and destruction
+where the upstream SDK exposes them. Blaxel's current `SandboxInstance` API is
+async; `SyncSandboxInstance` preserves its synchronous API. Unsupported
+provider-specific features raise `UnsupportedCompatibilityFeatureError` with a
+migration hint. They do not silently pretend that run.cloud implements a
+provider-specific feature.

runcloud_sdk-0.7.0/README.md

@@ -0,0 +1,41 @@
+# runcloud
+
+Python SDK for [run.cloud](https://run.cloud).
+
+```bash
+pip install runcloud-sdk
+export RUN_CLOUD_API_KEY="rc_live_..."
+```
+
+```python
+from runcloud import Client
+
+cloud = Client()
+box = cloud.create(image="runcloud/agent-base", cpu=2, memory=4096)
+try:
+    result = box.exec("python -V")
+    print(result.stdout)
+finally:
+    box.destroy()
+```
+
+## Compatibility adapters
+
+The same distribution includes migration adapters:
+
+| Provider | Import |
+| --- | --- |
+| Modal | `from runcloud.compat import modal` |
+| E2B | `from runcloud.compat.e2b import Sandbox` |
+| Daytona | `from runcloud.compat.daytona import Daytona` |
+| Vercel Sandbox | `from runcloud.compat.vercel import Sandbox` |
+| Blaxel async | `from runcloud.compat.blaxel import SandboxInstance` |
+| Blaxel sync | `from runcloud.compat.blaxel import SyncSandboxInstance` |
+| Fly Sprites | `from runcloud.compat.sprites import SpritesClient` |
+
+Adapters cover creation, command execution, lookup/listing, and destruction
+where the upstream SDK exposes them. Blaxel's current `SandboxInstance` API is
+async; `SyncSandboxInstance` preserves its synchronous API. Unsupported
+provider-specific features raise `UnsupportedCompatibilityFeatureError` with a
+migration hint. They do not silently pretend that run.cloud implements a
+provider-specific feature.

runcloud_sdk-0.7.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "runcloud-sdk"
+version = "0.7.0"
+description = "Python SDK for run.cloud, including sandbox-provider compatibility adapters"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [{ name = "Newly" }]
+keywords = ["runcloud", "run-cloud", "sandbox", "microvm", "firecracker", "sdk"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://run.cloud"
+Documentation = "https://docs.run.cloud"
+Repository = "https://github.com/newly-app/newly/tree/main/run-cloud/python-sdk"
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["runcloud*"]

runcloud_sdk-0.7.0/runcloud/__init__.py

@@ -0,0 +1,17 @@
+"""Public Python SDK for run.cloud."""
+
+from .client import (
+    Client,
+    ExecResult,
+    RunCloudError,
+    Sandbox,
+    UnsupportedCompatibilityFeatureError,
+)
+
+__all__ = [
+    "Client",
+    "ExecResult",
+    "RunCloudError",
+    "Sandbox",
+    "UnsupportedCompatibilityFeatureError",
+]

runcloud_sdk-0.7.0/runcloud/client.py

@@ -0,0 +1,209 @@
+"""Dependency-free Python client for the public run.cloud API."""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Callable, Optional, Union
+
+Transport = Callable[[str, str, Any], Any]
+
+
+class RunCloudError(Exception):
+    def __init__(self, status: int, detail: str):
+        super().__init__(f"run.cloud API {status}: {detail}")
+        self.status = status
+        self.detail = detail
+
+
+class UnsupportedCompatibilityFeatureError(Exception):
+    def __init__(self, provider: str, feature: str, alternative: str = ""):
+        message = f"{provider} compatibility does not support {feature} on run.cloud yet"
+        if alternative:
+            message += f"; {alternative}"
+        super().__init__(message)
+        self.provider = provider
+        self.feature = feature
+
+
+@dataclass(frozen=True)
+class ExecResult:
+    exit_code: int
+    stdout: str
+    stderr: str
+
+
+class Client:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        api_url: Optional[str] = None,
+        timeout: float = 60.0,
+        transport: Optional[Transport] = None,
+    ):
+        self.api_key = (
+            api_key
+            or os.environ.get("RUN_CLOUD_API_KEY")
+            or os.environ.get("RUN_CLOUD_API_TOKEN")
+        )
+        if not self.api_key:
+            raise ValueError(
+                "Run Cloud API key required. Set RUN_CLOUD_API_KEY or pass Client(api_key=...)."
+            )
+        self.api_url = (
+            api_url or os.environ.get("RUN_CLOUD_API_URL") or "https://api.run.cloud"
+        ).rstrip("/")
+        self.timeout = timeout
+        self._transport = transport
+
+    def request(self, method: str, path: str, body: Any = None) -> Any:
+        if self._transport is not None:
+            return self._transport(method, path, body)
+        data = json.dumps(body).encode() if body is not None else None
+        request = urllib.request.Request(
+            self.api_url + path,
+            data=data,
+            method=method,
+            headers={
+                "Authorization": "Bearer " + self.api_key,
+                "Content-Type": "application/json",
+            },
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                raw = response.read()
+                return json.loads(raw) if raw else None
+        except urllib.error.HTTPError as error:
+            text = error.read().decode(errors="replace")
+            try:
+                parsed = json.loads(text)
+                text = parsed.get("detail") or parsed.get("error") or parsed.get("message") or text
+            except Exception:
+                pass
+            raise RunCloudError(error.code, str(text)) from None
+
+    def create(
+        self,
+        image: str = "runcloud/agent-base",
+        cpu: Optional[float] = None,
+        memory: Optional[int] = None,
+        disk: Optional[int] = None,
+        idle_pause_seconds: Optional[int] = None,
+        timeout_seconds: Optional[int] = None,
+        region: Optional[str] = None,
+        name: Optional[str] = None,
+    ) -> "Sandbox":
+        values = {
+            "image": image,
+            "cpu": cpu,
+            "memory": memory,
+            "disk": disk,
+            "idlePauseSeconds": idle_pause_seconds,
+            "timeoutSeconds": timeout_seconds,
+            "region": region,
+            "name": name,
+        }
+        body = {key: value for key, value in values.items() if value is not None}
+        return Sandbox(self, self.request("POST", "/run-cloud/sandboxes", body))
+
+    def get(self, sandbox_id: str) -> "Sandbox":
+        sid = urllib.parse.quote(sandbox_id, safe="")
+        return Sandbox(self, self.request("GET", f"/run-cloud/sandboxes/{sid}"))
+
+    def list(self, state: Optional[str] = None) -> list["Sandbox"]:
+        query = f"?state={urllib.parse.quote(state, safe='')}" if state else ""
+        payload = self.request("GET", "/run-cloud/sandboxes" + query) or {}
+        return [Sandbox(self, item) for item in payload.get("items", [])]
+
+
+class Sandbox:
+    def __init__(self, client: Client, data: dict[str, Any]):
+        self._client = client
+        self._data = data
+        self.id = str(data["id"])
+
+    @property
+    def state(self) -> str:
+        return str(self._data.get("state", ""))
+
+    @property
+    def name(self) -> str:
+        return str(self._data.get("name") or "")
+
+    def refresh(self) -> "Sandbox":
+        self._data = self._client.request(
+            "GET", f"/run-cloud/sandboxes/{urllib.parse.quote(self.id, safe='')}"
+        )
+        return self
+
+    def exec(
+        self,
+        command: Union[str, list[str]],
+        cwd: Optional[str] = None,
+        env: Optional[dict[str, str]] = None,
+        timeout: Optional[int] = None,
+    ) -> ExecResult:
+        argv = ["/bin/sh", "-c", command] if isinstance(command, str) else command
+        if not argv:
+            raise ValueError("command must not be empty")
+        body: dict[str, Any] = {"cmd": argv}
+        if cwd:
+            body["cwd"] = cwd
+        if env:
+            body["env"] = env
+        if timeout is not None:
+            body["timeout_seconds"] = timeout
+        payload = self._client.request(
+            "POST",
+            f"/run-cloud/sandboxes/{urllib.parse.quote(self.id, safe='')}/exec",
+            body,
+        )
+        return ExecResult(
+            int(payload.get("exit_code", 0)),
+            str(payload.get("stdout", "")),
+            str(payload.get("stderr", "")),
+        )
+
+    def read_file(self, path: str) -> bytes:
+        payload = self._client.request(
+            "POST",
+            f"/run-cloud/sandboxes/{urllib.parse.quote(self.id, safe='')}/fs",
+            {"op": "read", "path": path},
+        )
+        if payload.get("error"):
+            raise RunCloudError(0, str(payload["error"]))
+        return base64.b64decode(payload.get("content") or "")
+
+    def pause(self) -> "Sandbox":
+        self._data = self._client.request(
+            "POST",
+            f"/run-cloud/sandboxes/{urllib.parse.quote(self.id, safe='')}/pause",
+            {},
+        )
+        return self
+
+    def resume(self) -> "Sandbox":
+        self._data = self._client.request(
+            "POST",
+            f"/run-cloud/sandboxes/{urllib.parse.quote(self.id, safe='')}/resume",
+            {},
+        )
+        return self
+
+    def set_timeout(self, seconds: int) -> "Sandbox":
+        self._data = self._client.request(
+            "POST",
+            f"/run-cloud/sandboxes/{urllib.parse.quote(self.id, safe='')}/timeout",
+            {"timeoutSeconds": seconds},
+        )
+        return self
+
+    def destroy(self) -> None:
+        self._client.request(
+            "DELETE", f"/run-cloud/sandboxes/{urllib.parse.quote(self.id, safe='')}"
+        )

runcloud_sdk-0.7.0/runcloud/compat/__init__.py

@@ -0,0 +1,5 @@
+"""Provider-shaped migration adapters included with the runcloud package."""
+
+from . import modal
+
+__all__ = ["modal"]

runcloud_sdk-0.7.0/runcloud/compat/blaxel.py

@@ -0,0 +1,147 @@
+"""Blaxel-shaped compatibility adapter."""
+
+from runcloud.client import Client, UnsupportedCompatibilityFeatureError
+
+
+class _SyncProcess:
+    def __init__(self, native):
+        self._native = native
+
+    def exec(self, config):
+        if config.get("wait_for_completion") is False:
+            raise UnsupportedCompatibilityFeatureError("Blaxel", "background processes")
+        result = self._native.exec(
+            config["command"],
+            cwd=config.get("working_dir"),
+            env=config.get("env"),
+        )
+        return {
+            "pid": 0,
+            "name": config.get("name", ""),
+            "status": "completed" if result.exit_code == 0 else "failed",
+            "exitCode": result.exit_code,
+            "logs": result.stdout + result.stderr,
+        }
+
+
+class _SyncDeleteDescriptor:
+    def __get__(self, instance, owner):
+        if instance is not None:
+
+            def delete():
+                instance.native.destroy()
+
+            return delete
+
+        def delete(sandbox_name, client=None, **client_options):
+            owner.get(sandbox_name, client=client, **client_options).delete()
+
+        return delete
+
+
+class SyncSandboxInstance:
+    delete = _SyncDeleteDescriptor()
+
+    def __init__(self, native):
+        self.native = native
+        self.process = _SyncProcess(native)
+
+    @classmethod
+    def create(
+        cls,
+        sandbox=None,
+        safe=False,
+        create_if_not_exist=False,
+        client=None,
+        **options,
+    ):
+        config = dict(sandbox or {})
+        config.update(options)
+        actual = client or Client(
+            api_key=config.get("api_key"), api_url=config.get("api_url")
+        )
+        return cls(
+            actual.create(
+                image=config.get("image", "runcloud/agent-base"),
+                name=config.get("name"),
+                cpu=config.get("cpu"),
+                memory=config.get("memory"),
+                region=config.get("region"),
+            )
+        )
+
+    @classmethod
+    def get(cls, sandbox_name, client=None, **client_options):
+        actual = client or Client(**client_options)
+        match = next(
+            (item for item in actual.list() if item.name == sandbox_name), None
+        )
+        if match is None:
+            raise LookupError(f"no sandbox named {sandbox_name}")
+        return cls(match)
+
+
+class _AsyncProcess:
+    def __init__(self, native):
+        self._sync = _SyncProcess(native)
+
+    async def exec(self, config):
+        return self._sync.exec(config)
+
+
+class _AsyncDeleteDescriptor:
+    def __get__(self, instance, owner):
+        if instance is not None:
+
+            async def delete():
+                instance.native.destroy()
+
+            return delete
+
+        async def delete(sandbox_name, client=None, **client_options):
+            sandbox = await owner.get(
+                sandbox_name,
+                client=client,
+                **client_options,
+            )
+            await sandbox.delete()
+
+        return delete
+
+
+class SandboxInstance:
+    delete = _AsyncDeleteDescriptor()
+
+    def __init__(self, native):
+        self.native = native
+        self.process = _AsyncProcess(native)
+
+    @classmethod
+    async def create(
+        cls, sandbox=None, safe=False, create_if_not_exist=False, **options
+    ):
+        config = dict(sandbox or {})
+        config.update(options)
+        actual = config.pop("client", None) or Client(
+            api_key=config.pop("api_key", None),
+            api_url=config.pop("api_url", None),
+        )
+        return cls(
+            actual.create(
+                image=config.get("image", "runcloud/agent-base"),
+                name=config.get("name"),
+                cpu=config.get("cpu"),
+                memory=config.get("memory"),
+                region=config.get("region"),
+            )
+        )
+
+    @classmethod
+    async def get(cls, sandbox_name, client=None, **client_options):
+        actual = client or Client(**client_options)
+        match = next(
+            (item for item in actual.list() if item.name == sandbox_name), None
+        )
+        if match is None:
+            raise LookupError(f"no sandbox named {sandbox_name}")
+        return cls(match)

runcloud_sdk-0.7.0/runcloud/compat/daytona.py

@@ -0,0 +1,67 @@
+"""Daytona-shaped compatibility adapter."""
+
+from runcloud.client import Client, UnsupportedCompatibilityFeatureError
+
+
+class _Process:
+    def __init__(self, native):
+        self._native = native
+
+    def exec(self, command, cwd=None, env=None, timeout=None):
+        result = self._native.exec(command, cwd=cwd, env=env, timeout=timeout)
+        return type(
+            "ExecuteResponse",
+            (),
+            {
+                "exit_code": result.exit_code,
+                "exitCode": result.exit_code,
+                "result": result.stdout,
+                "stdout": result.stdout,
+                "stderr": result.stderr,
+            },
+        )()
+
+
+class DaytonaSandbox:
+    def __init__(self, native):
+        self.native = native
+        self.id = native.id
+        self.process = _Process(native)
+
+    def get_preview_link(self, _port):
+        raise UnsupportedCompatibilityFeatureError(
+            "Daytona",
+            "preview links",
+            "run.cloud public port capabilities are not available in the SDK yet",
+        )
+
+    def delete(self):
+        self.native.destroy()
+
+
+class Daytona:
+    def __init__(self, config=None, client=None, **options):
+        config = config or {}
+        self.client = client or Client(
+            api_key=options.get("api_key") or config.get("api_key"),
+            api_url=options.get("server_url") or config.get("server_url"),
+        )
+
+    def create(self, params=None):
+        params = params or {}
+        return DaytonaSandbox(
+            self.client.create(
+                image=params.get("image", "runcloud/agent-base"),
+                name=params.get("name"),
+                region=params.get("region"),
+            )
+        )
+
+    def get(self, sandbox_id_or_name):
+        return DaytonaSandbox(self.client.get(sandbox_id_or_name))
+
+    def remove(self, sandbox):
+        sandbox.delete()
+
+    def delete(self, sandbox, timeout=None, wait=True):
+        sandbox.delete()

runcloud_sdk-0.7.0/runcloud/compat/e2b.py

@@ -0,0 +1,80 @@
+"""E2B Sandbox-shaped compatibility adapter."""
+
+from __future__ import annotations
+
+from runcloud.client import Client, UnsupportedCompatibilityFeatureError
+
+
+class _Commands:
+    def __init__(self, sandbox):
+        self._sandbox = sandbox
+
+    def run(self, command, cwd=None, envs=None, timeout=None, background=False):
+        if background:
+            raise UnsupportedCompatibilityFeatureError("E2B", "background commands")
+        return self._sandbox.native.exec(command, cwd=cwd, env=envs, timeout=timeout)
+
+
+class _Files:
+    def __init__(self, sandbox):
+        self._sandbox = sandbox
+
+    def read(self, path):
+        return self._sandbox.native.read_file(path).decode()
+
+    def read_bytes(self, path):
+        return self._sandbox.native.read_file(path)
+
+    def write(self, *_args, **_kwargs):
+        raise UnsupportedCompatibilityFeatureError(
+            "E2B", "file writes", "use an image or command"
+        )
+
+
+class Sandbox:
+    def __init__(self, native, metadata=None):
+        self.native = native
+        self.metadata = metadata or {}
+        self.commands = _Commands(self)
+        self.files = _Files(self)
+
+    @classmethod
+    def create(
+        cls,
+        template="base",
+        timeout=None,
+        metadata=None,
+        envs=None,
+        client=None,
+        api_key=None,
+        domain=None,
+        **_ignored,
+    ):
+        actual = client or Client(api_key=api_key, api_url=domain)
+        image = "runcloud/agent-base" if template == "base" else template
+        sandbox = cls(actual.create(image=image, timeout_seconds=timeout), metadata)
+        sandbox.envs = envs or {}
+        return sandbox
+
+    @classmethod
+    def connect(cls, sandbox_id, client=None, **client_options):
+        actual = client or Client(**client_options)
+        return cls(actual.get(sandbox_id))
+
+    @property
+    def sandbox_id(self):
+        return self.native.id
+
+    def set_timeout(self, timeout):
+        self.native.set_timeout(timeout)
+
+    def get_host(self, _port):
+        raise UnsupportedCompatibilityFeatureError(
+            "E2B",
+            "get_host",
+            "run.cloud public port capabilities are not available in the SDK yet",
+        )
+
+    def kill(self):
+        self.native.destroy()
+        return True

runcloud_sdk-0.7.0/runcloud/compat/modal.py

@@ -0,0 +1,165 @@
+"""Modal Sandbox-shaped compatibility adapter."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from runcloud.client import (
+    Client,
+    UnsupportedCompatibilityFeatureError,
+)
+from runcloud.client import (
+    Sandbox as NativeSandbox,
+)
+
+
+class Image:
+    def __init__(self, ref: str):
+        self.ref = ref
+
+    @classmethod
+    def from_registry(cls, ref: str) -> "Image":
+        return cls(ref)
+
+    @classmethod
+    def debian_slim(cls, python_version: Optional[str] = None) -> "Image":
+        return cls("debian:12-slim")
+
+    def _unsupported(self, feature: str):
+        raise UnsupportedCompatibilityFeatureError(
+            "Modal", feature, "register a prebuilt OCI image with run.cloud"
+        )
+
+    def apt_install(self, *packages: str):
+        return self._unsupported("Image.apt_install")
+
+    def pip_install(self, *packages: str):
+        return self._unsupported("Image.pip_install")
+
+    def run_commands(self, *commands: str):
+        return self._unsupported("Image.run_commands")
+
+
+class Process:
+    def __init__(self, result):
+        self._result = result
+        self.stdout = _Reader(result.stdout)
+        self.stderr = _Reader(result.stderr)
+        self.returncode = result.exit_code
+
+    def wait(self):
+        return self.returncode
+
+    def poll(self):
+        return self.returncode
+
+
+class _Reader:
+    def __init__(self, value: str):
+        self._value = value
+
+    def read(self):
+        return self._value
+
+
+class App:
+    def __init__(self, name: str, client: Client):
+        self.name = name
+        self.client = client
+
+    @classmethod
+    def lookup(
+        cls,
+        name: str,
+        create_if_missing: bool = True,
+        client: Optional[Client] = None,
+        **client_options,
+    ) -> "App":
+        return cls(name, client or Client(**client_options))
+
+    def create_sandbox(self, image=None, **options):
+        return Sandbox.create(app=self, image=image, **options)
+
+
+class Sandbox:
+    def __init__(self, native: NativeSandbox, app: Optional[App] = None):
+        self.native = native
+        self.app = app
+
+    @property
+    def object_id(self):
+        return self.native.id
+
+    @classmethod
+    def create(
+        cls,
+        *args,
+        app: Optional[App] = None,
+        image=None,
+        cpu=None,
+        memory=None,
+        timeout=None,
+        idle_timeout=None,
+        name=None,
+        region=None,
+        command=None,
+        volumes=None,
+        **_ignored,
+    ):
+        if volumes:
+            raise UnsupportedCompatibilityFeatureError("Modal", "volumes")
+        if isinstance(cpu, tuple):
+            raise UnsupportedCompatibilityFeatureError(
+                "Modal", "CPU request/limit tuples", "pass one CPU reservation"
+            )
+        client = app.client if app else Client()
+        image_ref = image.ref if isinstance(image, Image) else image
+        native = client.create(
+            image=image_ref or "runcloud/agent-base",
+            cpu=cpu,
+            memory=memory,
+            timeout_seconds=timeout,
+            idle_pause_seconds=idle_timeout,
+            name=name,
+            region=region,
+        )
+        sandbox = cls(native, app)
+        entrypoint = list(args) if args else command
+        if entrypoint:
+            sandbox._entrypoint = sandbox.exec(*entrypoint)
+        return sandbox
+
+    @classmethod
+    def from_id(cls, sandbox_id: str, client: Optional[Client] = None):
+        actual = client or Client()
+        return cls(actual.get(sandbox_id))
+
+    @classmethod
+    def from_name(cls, app: App, name: str):
+        match = next((item for item in app.client.list() if item.name == name), None)
+        if match is None:
+            raise LookupError(f"no sandbox named {name}")
+        return cls(match, app)
+
+    @classmethod
+    def list(cls, app: Optional[App] = None):
+        client = app.client if app else Client()
+        return [cls(item, app) for item in client.list()]
+
+    def exec(self, *args, timeout=None, workdir=None, env=None, **_ignored):
+        cmd = list(args) if len(args) > 1 else args[0]
+        return Process(self.native.exec(cmd, cwd=workdir, env=env, timeout=timeout))
+
+    def terminate(self, wait=True):
+        self.native.destroy()
+
+    def poll(self):
+        self.native.refresh()
+        return None if self.native.state in {"running", "starting", "pending"} else 0
+
+    def tunnels(self):
+        raise UnsupportedCompatibilityFeatureError(
+            "Modal",
+            "tunnels",
+            "run.cloud public port capabilities are not available in the SDK yet",
+        )

runcloud_sdk-0.7.0/runcloud/compat/sprites.py

@@ -0,0 +1,50 @@
+"""Fly Sprites-shaped compatibility adapter."""
+
+from runcloud.client import Client, UnsupportedCompatibilityFeatureError
+
+
+class Sprite:
+    def __init__(self, native, name):
+        self.native = native
+        self.name = name
+
+    def exec(self, command, args=None, cwd=None, env=None):
+        return self.native.exec([command] + list(args or []), cwd=cwd, env=env)
+
+    def filesystem(self, _base="/"):
+        raise UnsupportedCompatibilityFeatureError("Fly Sprites", "filesystem writes")
+
+    def url(self, _port=8080):
+        raise UnsupportedCompatibilityFeatureError(
+            "Fly Sprites",
+            "public URLs",
+            "run.cloud public port capabilities are not available in the SDK yet",
+        )
+
+    def delete(self):
+        self.native.destroy()
+
+
+class SpritesClient:
+    def __init__(self, client=None, api_key=None, base_url=None):
+        self.client = client or Client(api_key=api_key, api_url=base_url)
+
+    def create_sprite(self, name, config=None):
+        config = config or {}
+        return Sprite(
+            self.client.create(
+                image=config.get("image", "runcloud/agent-base"),
+                name=name,
+                region=config.get("region"),
+            ),
+            name,
+        )
+
+    def get_sprite(self, name):
+        match = next((item for item in self.client.list() if item.name == name), None)
+        if match is None:
+            raise LookupError(f"no sprite named {name}")
+        return Sprite(match, name)
+
+    def destroy_sprite(self, name):
+        self.get_sprite(name).delete()

runcloud_sdk-0.7.0/runcloud/compat/vercel.py

@@ -0,0 +1,55 @@
+"""Vercel Sandbox-shaped compatibility adapter."""
+
+from runcloud.client import Client, UnsupportedCompatibilityFeatureError
+
+
+class Sandbox:
+    def __init__(self, native):
+        self.native = native
+
+    @classmethod
+    def create(
+        cls,
+        client=None,
+        token=None,
+        runtime=None,
+        resources=None,
+        timeout=None,
+        **options,
+    ):
+        actual = client or Client(api_key=token)
+        resources = resources or {}
+        return cls(
+            actual.create(
+                image=options.get("image", "runcloud/agent-base"),
+                name=options.get("name"),
+                cpu=resources.get("vcpus"),
+                timeout_seconds=(timeout // 1000 if timeout else None),
+                region=options.get("region"),
+            )
+        )
+
+    @property
+    def sandbox_id(self):
+        return self.native.id
+
+    def run_command(self, command, args=None, cwd=None, env=None):
+        return self.native.exec([command] + list(args or []), cwd=cwd, env=env)
+
+    def read_file(self, path):
+        return self.native.read_file(path)
+
+    def write_files(self, *_args, **_kwargs):
+        raise UnsupportedCompatibilityFeatureError(
+            "Vercel Sandbox", "file writes", "use an image or command"
+        )
+
+    def domain(self, _port):
+        raise UnsupportedCompatibilityFeatureError(
+            "Vercel Sandbox",
+            "domain",
+            "run.cloud public port capabilities are not available in the SDK yet",
+        )
+
+    def stop(self):
+        self.native.destroy()

runcloud_sdk-0.7.0/runcloud_sdk.egg-info/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: runcloud-sdk
+Version: 0.7.0
+Summary: Python SDK for run.cloud, including sandbox-provider compatibility adapters
+Author: Newly
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://run.cloud
+Project-URL: Documentation, https://docs.run.cloud
+Project-URL: Repository, https://github.com/newly-app/newly/tree/main/run-cloud/python-sdk
+Keywords: runcloud,run-cloud,sandbox,microvm,firecracker,sdk
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# runcloud
+
+Python SDK for [run.cloud](https://run.cloud).
+
+```bash
+pip install runcloud-sdk
+export RUN_CLOUD_API_KEY="rc_live_..."
+```
+
+```python
+from runcloud import Client
+
+cloud = Client()
+box = cloud.create(image="runcloud/agent-base", cpu=2, memory=4096)
+try:
+    result = box.exec("python -V")
+    print(result.stdout)
+finally:
+    box.destroy()
+```
+
+## Compatibility adapters
+
+The same distribution includes migration adapters:
+
+| Provider | Import |
+| --- | --- |
+| Modal | `from runcloud.compat import modal` |
+| E2B | `from runcloud.compat.e2b import Sandbox` |
+| Daytona | `from runcloud.compat.daytona import Daytona` |
+| Vercel Sandbox | `from runcloud.compat.vercel import Sandbox` |
+| Blaxel async | `from runcloud.compat.blaxel import SandboxInstance` |
+| Blaxel sync | `from runcloud.compat.blaxel import SyncSandboxInstance` |
+| Fly Sprites | `from runcloud.compat.sprites import SpritesClient` |
+
+Adapters cover creation, command execution, lookup/listing, and destruction
+where the upstream SDK exposes them. Blaxel's current `SandboxInstance` API is
+async; `SyncSandboxInstance` preserves its synchronous API. Unsupported
+provider-specific features raise `UnsupportedCompatibilityFeatureError` with a
+migration hint. They do not silently pretend that run.cloud implements a
+provider-specific feature.

runcloud_sdk-0.7.0/runcloud_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+runcloud/__init__.py
+runcloud/client.py
+runcloud/compat/__init__.py
+runcloud/compat/blaxel.py
+runcloud/compat/daytona.py
+runcloud/compat/e2b.py
+runcloud/compat/modal.py
+runcloud/compat/sprites.py
+runcloud/compat/vercel.py
+runcloud_sdk.egg-info/PKG-INFO
+runcloud_sdk.egg-info/SOURCES.txt
+runcloud_sdk.egg-info/dependency_links.txt
+runcloud_sdk.egg-info/top_level.txt
+tests/test_sdk.py

runcloud_sdk-0.7.0/runcloud_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

runcloud_sdk-0.7.0/runcloud_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+runcloud

runcloud_sdk-0.7.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

runcloud_sdk-0.7.0/tests/test_sdk.py

@@ -0,0 +1,79 @@
+import asyncio
+import base64
+import unittest
+
+from runcloud import Client, UnsupportedCompatibilityFeatureError
+from runcloud.compat import modal
+from runcloud.compat.blaxel import SandboxInstance, SyncSandboxInstance
+from runcloud.compat.daytona import Daytona
+from runcloud.compat.e2b import Sandbox as E2BSandbox
+from runcloud.compat.sprites import SpritesClient
+from runcloud.compat.vercel import Sandbox as VercelSandbox
+
+SANDBOX = {"id": "sb_python", "name": "compat", "state": "running"}
+
+
+class Recorder:
+    def __init__(self):
+        self.calls = []
+
+    def __call__(self, method, path, body):
+        self.calls.append((method, path, body))
+        if path.endswith("/exec"):
+            return {"exit_code": 0, "stdout": "ok\n", "stderr": ""}
+        if path.endswith("/fs"):
+            return {"content": base64.b64encode(b"artifact").decode()}
+        if path == "/run-cloud/sandboxes" and method == "GET":
+            return {"items": [SANDBOX]}
+        return SANDBOX
+
+
+class SDKTests(unittest.TestCase):
+    def setUp(self):
+        self.recorder = Recorder()
+        self.client = Client(api_key="rc_live_test", transport=self.recorder)
+
+    def test_native_routes(self):
+        box = self.client.create(cpu=1.5, memory=2048)
+        self.assertEqual(box.exec("echo ok").stdout, "ok\n")
+        self.assertEqual(box.read_file("/tmp/a"), b"artifact")
+        box.pause()
+        box.resume()
+        box.destroy()
+        self.assertIn(
+            (
+                "POST",
+                "/run-cloud/sandboxes",
+                {
+                    "image": "runcloud/agent-base",
+                    "cpu": 1.5,
+                    "memory": 2048,
+                },
+            ),
+            self.recorder.calls,
+        )
+
+    def test_compatibility_adapters_share_the_public_client(self):
+        app = modal.App.lookup("compat", client=self.client)
+        self.assertEqual(modal.Sandbox.create(app=app).exec("echo ok").wait(), 0)
+        self.assertEqual(
+            E2BSandbox.create(client=self.client).commands.run("echo ok").exit_code, 0
+        )
+        self.assertEqual(
+            Daytona(client=self.client).create().process.exec("echo ok").exit_code, 0
+        )
+        self.assertEqual(
+            VercelSandbox.create(client=self.client).run_command("echo").exit_code, 0
+        )
+        self.assertTrue(SyncSandboxInstance.create(client=self.client))
+        async_blaxel = asyncio.run(SandboxInstance.create(client=self.client))
+        asyncio.run(async_blaxel.delete())
+        self.assertTrue(SpritesClient(client=self.client).create_sprite("compat"))
+
+    def test_unsupported_features_fail_loudly(self):
+        with self.assertRaises(UnsupportedCompatibilityFeatureError):
+            modal.Image.debian_slim().pip_install("requests")
+
+
+if __name__ == "__main__":
+    unittest.main()