sail-sdk 0.1.0__tar.gz

sail_sdk-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+.env
+.env.*
+*.env*.local
+*.pyc
+.venv
+openapi.documented.yml
+node_modules
+.DS_Store
+go.work
+go.work.sum
+.vercel
+.env*.local
+.cursor/skills/
+.claude/worktrees/
+.claude/plans/
+.idea/
+services/tokenizer/uv.lock
+*.test

sail_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: sail-sdk
+Version: 0.1.0
+Summary: Python SDK for the Sail sandbox platform
+Project-URL: Homepage, https://app.sailresearch.com
+Project-URL: Repository, https://github.com/sailresearch/sail
+Project-URL: Issues, https://github.com/sailresearch/sail/issues
+Author: Sail
+License-Expression: Apache-2.0
+Keywords: grpc,sail,sailbox,sandbox,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: grpcio>=1.80.0
+Requires-Dist: protobuf>=6.31.1
+Provides-Extra: dev
+Requires-Dist: grpcio-tools>=1.80.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# sail-sdk
+
+Python SDK for the Sail sandbox platform.
+
+## Install
+
+```bash
+pip install sail-sdk
+```
+
+```bash
+uv add sail-sdk
+```
+
+## Sailbox exec
+
+```python
+import sail
+
+app = sail.App.find(name="example-app", mint_if_missing=True)
+sb = sail.Sailbox.create(
+    image=sail.Image.debian_amd64,
+    app=app,
+    name="sandbox-1",
+)
+result = sb.exec("echo hi", timeout=5).wait()
+
+print(result.stdout)
+print(result.stderr)
+print(result.returncode)
+
+# Detached background launch. wait() waits for the launcher shell, not for the
+# long-lived background process to exit.
+sb.exec("python3 -m http.server 3000", background=True).wait()
+
+# Omitting timeout means Sail will not terminate the exec automatically.
+sb.exec("sleep 600").wait()
+```
+
+## Sailbox networking
+
+```python
+import sail
+
+app = sail.App.find(name="example-app", mint_if_missing=True)
+sb = sail.Sailbox.create(
+    image=sail.Image.debian_amd64,
+    app=app,
+    name="sandbox-net",
+    timeout=300,
+    ingress_ports=[3000],
+)
+
+listener = sb.listener(3000)
+print(listener.url)
+
+req = sb.request(
+    "POST",
+    "https://example.com/api",
+    json={"hello": "world"},
+    idempotency_key="example-1",
+)
+print(req.id, req.status)
+
+completed = req.wait()
+print(completed.status)
+print(completed.response.status_code)
+print(completed.response.text)
+```
+
+Explicit base images:
+
+```python
+amd64_image = sail.Image.debian_amd64
+amd_image = sail.Image.debian_amd
+arm64_image = sail.Image.debian_arm64
+arm_image = sail.Image.debian_arm
+```
+
+## Examples
+
+- `examples/sailbox_smoke.py`: start a sailbox from the amd64 Debian image.
+- `examples/sailbox_custom_image.py`: build a custom image with `apt_install`, `pip_install`, `run_commands`, and `env`, then launch a sailbox from it.
+
+## Publishing
+
+Build a distributable package locally from the repo root:
+
+```bash
+just python-sdk-build
+```
+
+Publish from a developer machine with a PyPI token:
+
+```bash
+export UV_PUBLISH_TOKEN=pypi-...
+just python-sdk-publish
+```
+
+The repository also includes a GitHub Actions release workflow at `.github/workflows/python-sdk-publish.yml`.
+It publishes when you push a tag like `python-sdk-v0.1.0`, after verifying that the tag version matches `sail.__version__`.
+
+Recommended setup:
+
+1. Create the `sail-sdk` project on PyPI.
+2. Configure PyPI Trusted Publishing for this GitHub repository and the `python-sdk-publish.yml` workflow.
+3. Bump `sdk/python/src/sail/__about__.py`.
+4. Push a matching tag: `git tag python-sdk-v0.1.0 && git push origin python-sdk-v0.1.0`

sail_sdk-0.1.0/README.md

@@ -0,0 +1,108 @@
+# sail-sdk
+
+Python SDK for the Sail sandbox platform.
+
+## Install
+
+```bash
+pip install sail-sdk
+```
+
+```bash
+uv add sail-sdk
+```
+
+## Sailbox exec
+
+```python
+import sail
+
+app = sail.App.find(name="example-app", mint_if_missing=True)
+sb = sail.Sailbox.create(
+    image=sail.Image.debian_amd64,
+    app=app,
+    name="sandbox-1",
+)
+result = sb.exec("echo hi", timeout=5).wait()
+
+print(result.stdout)
+print(result.stderr)
+print(result.returncode)
+
+# Detached background launch. wait() waits for the launcher shell, not for the
+# long-lived background process to exit.
+sb.exec("python3 -m http.server 3000", background=True).wait()
+
+# Omitting timeout means Sail will not terminate the exec automatically.
+sb.exec("sleep 600").wait()
+```
+
+## Sailbox networking
+
+```python
+import sail
+
+app = sail.App.find(name="example-app", mint_if_missing=True)
+sb = sail.Sailbox.create(
+    image=sail.Image.debian_amd64,
+    app=app,
+    name="sandbox-net",
+    timeout=300,
+    ingress_ports=[3000],
+)
+
+listener = sb.listener(3000)
+print(listener.url)
+
+req = sb.request(
+    "POST",
+    "https://example.com/api",
+    json={"hello": "world"},
+    idempotency_key="example-1",
+)
+print(req.id, req.status)
+
+completed = req.wait()
+print(completed.status)
+print(completed.response.status_code)
+print(completed.response.text)
+```
+
+Explicit base images:
+
+```python
+amd64_image = sail.Image.debian_amd64
+amd_image = sail.Image.debian_amd
+arm64_image = sail.Image.debian_arm64
+arm_image = sail.Image.debian_arm
+```
+
+## Examples
+
+- `examples/sailbox_smoke.py`: start a sailbox from the amd64 Debian image.
+- `examples/sailbox_custom_image.py`: build a custom image with `apt_install`, `pip_install`, `run_commands`, and `env`, then launch a sailbox from it.
+
+## Publishing
+
+Build a distributable package locally from the repo root:
+
+```bash
+just python-sdk-build
+```
+
+Publish from a developer machine with a PyPI token:
+
+```bash
+export UV_PUBLISH_TOKEN=pypi-...
+just python-sdk-publish
+```
+
+The repository also includes a GitHub Actions release workflow at `.github/workflows/python-sdk-publish.yml`.
+It publishes when you push a tag like `python-sdk-v0.1.0`, after verifying that the tag version matches `sail.__version__`.
+
+Recommended setup:
+
+1. Create the `sail-sdk` project on PyPI.
+2. Configure PyPI Trusted Publishing for this GitHub repository and the `python-sdk-publish.yml` workflow.
+3. Bump `sdk/python/src/sail/__about__.py`.
+4. Push a matching tag: `git tag python-sdk-v0.1.0 && git push origin python-sdk-v0.1.0`

sail_sdk-0.1.0/examples/sailbox_custom_image.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+"""Build and run a sailbox with a custom Debian image.
+
+Usage:
+    cd sdk/python
+    export SAIL_MODE=dev
+    export SAIL_API_KEY=your_api_key_here
+    uv run python examples/sailbox_custom_image.py
+"""
+
+import os
+import sys
+
+import sail
+
+
+def main() -> int:
+    scheduler_url = os.environ.get("SAIL_SCHEDULER_URL", "")
+    sail_mode = os.environ.get("SAIL_MODE", "")
+    api_key = os.environ.get("SAIL_API_KEY", "")
+    if not api_key:
+        print(
+            "Set SAIL_API_KEY before running this script. Optionally set SAIL_MODE=dev or override SAIL_SCHEDULER_URL.",
+            file=sys.stderr,
+        )
+        return 2
+
+    if not scheduler_url:
+        scheduler_url = (
+            "sailbox-scheduler.dev.sailresearch.com:443"
+            if sail_mode.strip().lower() == "dev"
+            else "sailbox-scheduler.sailresearch.com:443"
+        )
+
+    print("Finding or minting app...")
+    app = sail.App.find(name="sailbox-custom-image", mint_if_missing=True)
+
+    print("Defining custom image...")
+    image = (
+        sail.Image.debian_amd64.apt_install("git", "curl")
+        .pip_install("requests")
+        .run_commands(
+            "git clone https://github.com/pallets/flask.git /opt/flask-src",
+            "python3 -m pip show requests >/tmp/requests.txt",
+        )
+        .env(
+            {
+                "APP_ENV": "custom-image-demo",
+                "DEMO_MESSAGE": "hello-from-custom-image",
+            }
+        )
+    )
+
+    print(f"Building image via scheduler {scheduler_url}...")
+    built_image = image.build(timeout=1800)
+
+    print("Creating sailbox from custom image...")
+    sb = sail.Sailbox.create(
+        app=app,
+        image=built_image,
+        name="custom-image-demo",
+        cpu=1,
+        memory=512,
+    )
+
+    print("Sailbox ready:")
+    print(f"  sailbox_id: {sb.sailbox_id}")
+    print(f"  worker:     {sb.worker_address}")
+    print(f"  vm_id:      {sb.vm_id}")
+
+    print("Verifying installed packages, build output, and runtime env...")
+    result = sb.exec(
+        "python3 - <<'PY'\n"
+        "import os\n"
+        "import requests\n"
+        "print('requests=' + requests.__version__)\n"
+        "print('app_env=' + os.environ['APP_ENV'])\n"
+        "print('demo_message=' + os.environ['DEMO_MESSAGE'])\n"
+        "PY\n"
+        "test -d /opt/flask-src/.git\n"
+        "cat /tmp/requests.txt | head -n 5\n",
+        timeout=30,
+    ).wait()
+    print(result.stdout)
+    if result.stderr:
+        print(result.stderr, file=sys.stderr)
+    print(f"return code: {result.returncode}")
+
+    print("Terminating sailbox...")
+    sb.terminate()
+    print("Terminated.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sail_sdk-0.1.0/examples/sailbox_smoke.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+"""Simple end-to-end sailbox smoke test.
+
+Usage:
+    cd sdk/python
+    export SAIL_MODE=dev
+    export SAIL_API_KEY=your_api_key_here
+    uv run python examples/sailbox_smoke.py
+
+You can generate a SAIL_API_KEY here: https://app.unkey.com/sail-research/apis/api_5XuHxk82XDqMSPAa/keys/ks_5XuHxpQQYsLp3omz
+"""
+
+import os
+import sys
+
+import sail
+
+
+def main() -> int:
+    scheduler_url = os.environ.get("SAIL_SCHEDULER_URL", "")
+    sail_mode = os.environ.get("SAIL_MODE", "")
+    api_key = os.environ.get("SAIL_API_KEY", "")
+    if not api_key:
+        print(
+            "Set SAIL_API_KEY before running this script. Optionally set SAIL_MODE=dev or override SAIL_SCHEDULER_URL.",
+            file=sys.stderr,
+        )
+        return 2
+
+    if not scheduler_url:
+        scheduler_url = (
+            "sailbox-scheduler.dev.sailresearch.com:443"
+            if sail_mode.strip().lower() == "dev"
+            else "sailbox-scheduler.sailresearch.com:443"
+        )
+
+    print("Finding or minting app...")
+    app = sail.App.find(name="sailbox-smoke", mint_if_missing=True)
+
+    print(f"Creating sailbox via scheduler {scheduler_url}...")
+    sb = sail.Sailbox.create(
+        app=app,
+        image=sail.Image.debian_amd64,
+        name="smoke-test",
+        cpu=1,
+        memory=512,
+    )
+
+    print("Sailbox ready:")
+    print(f"  sailbox_id: {sb.sailbox_id}")
+    print(f"  worker:     {sb.worker_address}")
+    print(f"  vm_id:      {sb.vm_id}")
+
+    print("Running `echo hi`...")
+    result = sb.exec("echo hi", timeout=5).wait()
+    print(f"  stdout: {result.stdout!r}")
+    print(f"  stderr: {result.stderr!r}")
+    print(f"  code:   {result.returncode}")
+
+    print("Running a failing command...")
+    failed = sb.exec("echo boom >&2; exit 7", timeout=5).wait()
+    print(f"  stdout: {failed.stdout!r}")
+    print(f"  stderr: {failed.stderr!r}")
+    print(f"  code:   {failed.returncode}")
+
+    print("Running another successful command after failure...")
+    recovered = sb.exec("echo still-ok", timeout=5).wait()
+    print(f"  stdout: {recovered.stdout!r}")
+    print(f"  stderr: {recovered.stderr!r}")
+    print(f"  code:   {recovered.returncode}")
+
+    print("Terminating sailbox...")
+    sb.terminate()
+    print("Terminated.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sail_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sail-sdk"
+dynamic = ["version"]
+description = "Python SDK for the Sail sandbox platform"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.11"
+authors = [
+    { name = "Sail" },
+]
+keywords = ["sail", "sandbox", "sailbox", "grpc", "sdk"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "grpcio>=1.80.0",
+    "protobuf>=6.31.1",
+]
+
+[project.urls]
+Homepage = "https://app.sailresearch.com"
+Repository = "https://github.com/sailresearch/sail"
+Issues = "https://github.com/sailresearch/sail/issues"
+
+[project.optional-dependencies]
+dev = [
+    "grpcio-tools>=1.80.0",
+    "pytest>=8.0",
+]
+
+[tool.hatch.version]
+path = "src/sail/__about__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sail"]

sail_sdk-0.1.0/src/sail/__about__.py

@@ -0,0 +1,3 @@
+"""Package metadata for the Sail Python SDK."""
+
+__version__ = "0.1.0"

sail_sdk-0.1.0/src/sail/__init__.py

@@ -0,0 +1,43 @@
+"""Sail SDK — Python client for the Sail sandbox platform."""
+
+from sail.__about__ import __version__
+from sail.app import App
+from sail.errors import (
+    ImageBuildError,
+    SailError,
+    SailboxCreationError,
+    SailboxError,
+    SailboxExecAlreadyRunningError,
+    SailboxExecutionError,
+    SailboxExecRequestNotFoundError,
+    SailboxTerminatedError,
+)
+from sail.image import Image
+from sail.sailbox import (
+    Sailbox,
+    SailboxExecRequest,
+    SailboxExecResult,
+    SailboxListener,
+    SailboxRequest,
+    SailboxResponse,
+)
+
+__all__ = [
+    "App",
+    "Image",
+    "ImageBuildError",
+    "SailError",
+    "Sailbox",
+    "SailboxCreationError",
+    "SailboxError",
+    "SailboxExecAlreadyRunningError",
+    "SailboxExecutionError",
+    "SailboxExecRequestNotFoundError",
+    "SailboxExecRequest",
+    "SailboxExecResult",
+    "SailboxListener",
+    "SailboxRequest",
+    "SailboxResponse",
+    "SailboxTerminatedError",
+    "__version__",
+]

sail_sdk-0.1.0/src/sail/_client.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+# The generated proto stubs use absolute imports (e.g. ``from scheduler.v1 import
+# scheduler_pb2``). Adding the ``pb/`` directory to sys.path makes those imports
+# resolve correctly.
+_PB_DIR = str(Path(__file__).resolve().parent / "pb")
+if _PB_DIR not in sys.path:
+    sys.path.insert(0, _PB_DIR)
+
+import grpc  # noqa: E402
+from scheduler.v1 import scheduler_pb2_grpc  # noqa: E402
+
+from sail._config import Config  # noqa: E402
+
+
+def open_channel(target: str) -> grpc.Channel:
+    if target.startswith(("localhost:", "127.0.0.1:", "[::1]:")):
+        return grpc.insecure_channel(target)
+    return grpc.secure_channel(target, grpc.ssl_channel_credentials())
+
+
+class Client:
+    """Manages the gRPC channel to the sailbox scheduler."""
+
+    _instance: Client | None = None
+
+    def __init__(self, config: Config | None = None) -> None:
+        self._config = config or Config.from_env()
+        self._channel = open_channel(self._config.scheduler_url)
+        self._stub = scheduler_pb2_grpc.SchedulerServiceStub(self._channel)
+
+    @classmethod
+    def get(cls) -> Client:
+        """Return the singleton client, creating it on first call."""
+        if cls._instance is None:
+            cls._instance = cls()
+        return cls._instance
+
+    @classmethod
+    def reset(cls) -> None:
+        """Close and discard the singleton (useful for tests)."""
+        if cls._instance is not None:
+            cls._instance.close()
+            cls._instance = None
+
+    @property
+    def stub(self) -> scheduler_pb2_grpc.SchedulerServiceStub:
+        return self._stub
+
+    def metadata(self) -> list[tuple[str, str]]:
+        """Return gRPC call metadata with the authorization header."""
+        return [("authorization", f"Bearer {self._config.api_key}")]
+
+    def close(self) -> None:
+        if self._channel is not None:
+            self._channel.close()
+
+
+def open_channel(target: str) -> grpc.Channel:
+    if _is_local_target(target):
+        return grpc.secure_channel(target, grpc.local_channel_credentials())
+    return grpc.secure_channel(target, grpc.ssl_channel_credentials())
+
+
+def _is_local_target(target: str) -> bool:
+    host = target.split(":", 1)[0].strip().lower()
+    return host in {"localhost", "127.0.0.1", "[::1]"}

sail_sdk-0.1.0/src/sail/_config.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import os
+
+_PROD_SCHEDULER_URL = "sailbox-scheduler.sailresearch.com:443"
+_DEV_SCHEDULER_URL = "sailbox-scheduler.dev.sailresearch.com:443"
+_PROD_API_URL = "https://api.sailresearch.com"
+_DEV_API_URL = "https://dev.sailresearch.com"
+
+
+class Config:
+    """SDK configuration loaded from environment variables."""
+
+    def __init__(self, *, scheduler_url: str, api_key: str, api_url: str = "") -> None:
+        self.scheduler_url = scheduler_url
+        self.api_key = api_key
+        self.api_url = api_url
+
+    @classmethod
+    def from_env(cls) -> Config:
+        mode = os.environ.get("SAIL_MODE", "").strip().lower()
+        if mode == "dev":
+            default_scheduler_url = _DEV_SCHEDULER_URL
+            default_api_url = _DEV_API_URL
+        else:
+            default_scheduler_url = _PROD_SCHEDULER_URL
+            default_api_url = _PROD_API_URL
+
+        scheduler_url = (
+            os.environ.get("SAIL_SCHEDULER_URL", "").strip() or default_scheduler_url
+        )
+        api_key = os.environ.get("SAIL_API_KEY", "")
+        if not api_key:
+            raise ValueError("SAIL_API_KEY must be set")
+        api_url = os.environ.get("SAIL_API_URL", "").strip() or default_api_url
+        return cls(scheduler_url=scheduler_url, api_key=api_key, api_url=api_url)

sail_sdk-0.1.0/src/sail/_http_client.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+
+from sail._config import Config
+
+
+class HTTPClient:
+    """Thin HTTP client for the Sail REST API."""
+
+    _instance: HTTPClient | None = None
+
+    def __init__(self, config: Config | None = None) -> None:
+        self._config = config or Config.from_env()
+        if not self._config.api_url:
+            raise ValueError(
+                "SAIL_API_URL must be set (e.g. https://api.sailresearch.com)"
+            )
+
+    @classmethod
+    def get(cls) -> HTTPClient:
+        """Return the singleton client, creating it on first call."""
+        if cls._instance is None:
+            cls._instance = cls()
+        return cls._instance
+
+    @classmethod
+    def reset(cls) -> None:
+        """Close and discard the singleton (useful for tests)."""
+        cls._instance = None
+
+    def post(self, path: str, body: dict) -> tuple[int, dict]:
+        """POST JSON to {api_url}{path}, return (status_code, parsed_json)."""
+        url = self._config.api_url.rstrip("/") + path
+        data = json.dumps(body).encode()
+        req = urllib.request.Request(
+            url,
+            data=data,
+            headers={
+                "Authorization": f"Bearer {self._config.api_key}",
+                "Content-Type": "application/json",
+            },
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(req) as resp:
+                return resp.status, json.loads(resp.read())
+        except urllib.error.HTTPError as e:
+            body_bytes = e.read()
+            try:
+                return e.code, json.loads(body_bytes)
+            except (json.JSONDecodeError, ValueError):
+                return e.code, {
+                    "error": {"message": body_bytes.decode(errors="replace")}
+                }