platinum-sdk 0.1.0__tar.gz

platinum_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kortix AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

platinum_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: platinum-sdk
+Version: 0.1.0
+Summary: Platinum Python SDK — client for hardware-isolated sandbox microVMs.
+License: MIT
+Project-URL: Homepage, https://github.com/kortix-ai/platinum
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.25
+Dynamic: license-file
+
+# platinum-sdk (Python)
+
+Python client for [Platinum](https://github.com/kortix-ai/platinum) — hardware-isolated
+sandbox microVMs (one Cloud Hypervisor VM per sandbox, sub-second boots via a warm pool).
+
+> **Not on PyPI yet.** Until the first publish, install from source:
+> `pip install -e packages/sdk-py` (the import name is `platinum`).
+
+## Quickstart
+
+```python
+from platinum import Platinum
+
+dn = Platinum(token="pt_live_...", api_url="https://api.platinum.dev")
+# or: PT_TOKEN / PT_API_URL env vars
+
+sbx = dn.sandboxes.create(template="pt-base", wait_for_running=True)
+r = sbx.exec(["uname", "-a"]).check()     # .check() raises on non-zero exit
+print(r.stdout)
+sbx.delete()
+```
+
+Expose a port at create time (URL comes back in the same response):
+
+```python
+sbx = dn.sandboxes.create(
+    template="pt-base",
+    expose=[{"port": 8000, "public": True}],
+    wait_for_running=True,
+)
+print(sbx.exposed_url(8000))
+```
+
+## Configuration
+
+| Arg / env | Default | Meaning |
+|---|---|---|
+| `token` / `PT_TOKEN` | — (required) | API key `pt_live_…`, org-scoped bearer token |
+| `api_url` / `PT_API_URL` | `http://127.0.0.1:3000` | Control-plane URL |
+| `timeout` | `60.0` | Per-request timeout (seconds) |
+
+Python ≥ 3.9. **Synchronous only** (httpx). No automatic retries — a 429 or a failed
+create is surfaced to you, never silently retried. Server-side use only; never ship an
+API key into client-side code.
+
+## Surface (at parity with the TypeScript SDK)
+
+The two SDKs expose the same operations — enforced in CI by `verify/sdk-parity.sh`.
+
+| Area | Methods |
+|---|---|
+| Sandboxes | `sandboxes.create(...)` · `get` · `list` · `rename` · `delete` |
+| Lifecycle | `pause` · `resume` · `fork` · `snapshot` · `archive` · `rename` · `backup` · `wait_running` · `refresh` |
+| Run | `exec(argv)` · `sh(script)` · `run_code(code, lang)` |
+| Networking | `expose(port)` · `unexpose(port)` · `exposed_url(port)` |
+| Files (vsock) | `files.read` · `write` · `delete` · `list` · `stat` · `mkdir` |
+| Share (virtio-fs) | `share.info` · `list` · `stat` · `get` · `put` · `mkdir` · `delete` |
+| Platform | `templates.list()` · `regions.list()` · `health.check()` · `me()` |
+| Results | `ExecResult(stdout, stderr, exit_code)` with `.check()` |
+
+Build images declaratively with the `Template` builder (parity with the TS `Template`):
+
+```python
+from platinum import Platinum, Template
+
+dn = Platinum()
+image = (Template.from_python_image("3.12-slim")
+                 .pip_install(["fastapi", "uvicorn"])
+                 .workdir("/app"))
+sbx = dn.sandboxes.create(image=image, wait_for_running=True, wait_timeout_ms=600_000)
+```
+
+## Limits worth knowing
+
+- `exec` is buffered, not streaming — output arrives after the command exits
+  (default timeout 30 s via `timeout_ms`).
+- The default `pt-base` template is busybox-based — no git/pip/node/`httpd` inside
+  (`nc` and `wget` are available); build a template from a real distro image when you
+  need tooling.
+- Background processes are reaped when their `exec` call returns. To leave a server
+  running, daemonize it: `setsid sh -c '<server loop>' >/dev/null 2>&1 < /dev/null &`
+  — see `examples/02_expose_service.py`.
+- Errors raise `PlatinumError` with `.status` (HTTP status; `0` for non-HTTP failures).
+
+## Examples
+
+Runnable scripts in [`examples/`](./examples):
+
+```sh
+pip install -e packages/sdk-py
+PT_API_URL=… PT_TOKEN=… python packages/sdk-py/examples/01_create_exec_delete.py
+```
+
+## License
+
+MIT

platinum_sdk-0.1.0/README.md

@@ -0,0 +1,96 @@
+# platinum-sdk (Python)
+
+Python client for [Platinum](https://github.com/kortix-ai/platinum) — hardware-isolated
+sandbox microVMs (one Cloud Hypervisor VM per sandbox, sub-second boots via a warm pool).
+
+> **Not on PyPI yet.** Until the first publish, install from source:
+> `pip install -e packages/sdk-py` (the import name is `platinum`).
+
+## Quickstart
+
+```python
+from platinum import Platinum
+
+dn = Platinum(token="pt_live_...", api_url="https://api.platinum.dev")
+# or: PT_TOKEN / PT_API_URL env vars
+
+sbx = dn.sandboxes.create(template="pt-base", wait_for_running=True)
+r = sbx.exec(["uname", "-a"]).check()     # .check() raises on non-zero exit
+print(r.stdout)
+sbx.delete()
+```
+
+Expose a port at create time (URL comes back in the same response):
+
+```python
+sbx = dn.sandboxes.create(
+    template="pt-base",
+    expose=[{"port": 8000, "public": True}],
+    wait_for_running=True,
+)
+print(sbx.exposed_url(8000))
+```
+
+## Configuration
+
+| Arg / env | Default | Meaning |
+|---|---|---|
+| `token` / `PT_TOKEN` | — (required) | API key `pt_live_…`, org-scoped bearer token |
+| `api_url` / `PT_API_URL` | `http://127.0.0.1:3000` | Control-plane URL |
+| `timeout` | `60.0` | Per-request timeout (seconds) |
+
+Python ≥ 3.9. **Synchronous only** (httpx). No automatic retries — a 429 or a failed
+create is surfaced to you, never silently retried. Server-side use only; never ship an
+API key into client-side code.
+
+## Surface (at parity with the TypeScript SDK)
+
+The two SDKs expose the same operations — enforced in CI by `verify/sdk-parity.sh`.
+
+| Area | Methods |
+|---|---|
+| Sandboxes | `sandboxes.create(...)` · `get` · `list` · `rename` · `delete` |
+| Lifecycle | `pause` · `resume` · `fork` · `snapshot` · `archive` · `rename` · `backup` · `wait_running` · `refresh` |
+| Run | `exec(argv)` · `sh(script)` · `run_code(code, lang)` |
+| Networking | `expose(port)` · `unexpose(port)` · `exposed_url(port)` |
+| Files (vsock) | `files.read` · `write` · `delete` · `list` · `stat` · `mkdir` |
+| Share (virtio-fs) | `share.info` · `list` · `stat` · `get` · `put` · `mkdir` · `delete` |
+| Platform | `templates.list()` · `regions.list()` · `health.check()` · `me()` |
+| Results | `ExecResult(stdout, stderr, exit_code)` with `.check()` |
+
+Build images declaratively with the `Template` builder (parity with the TS `Template`):
+
+```python
+from platinum import Platinum, Template
+
+dn = Platinum()
+image = (Template.from_python_image("3.12-slim")
+                 .pip_install(["fastapi", "uvicorn"])
+                 .workdir("/app"))
+sbx = dn.sandboxes.create(image=image, wait_for_running=True, wait_timeout_ms=600_000)
+```
+
+## Limits worth knowing
+
+- `exec` is buffered, not streaming — output arrives after the command exits
+  (default timeout 30 s via `timeout_ms`).
+- The default `pt-base` template is busybox-based — no git/pip/node/`httpd` inside
+  (`nc` and `wget` are available); build a template from a real distro image when you
+  need tooling.
+- Background processes are reaped when their `exec` call returns. To leave a server
+  running, daemonize it: `setsid sh -c '<server loop>' >/dev/null 2>&1 < /dev/null &`
+  — see `examples/02_expose_service.py`.
+- Errors raise `PlatinumError` with `.status` (HTTP status; `0` for non-HTTP failures).
+
+## Examples
+
+Runnable scripts in [`examples/`](./examples):
+
+```sh
+pip install -e packages/sdk-py
+PT_API_URL=… PT_TOKEN=… python packages/sdk-py/examples/01_create_exec_delete.py
+```
+
+## License
+
+MIT

platinum_sdk-0.1.0/platinum/__init__.py

@@ -0,0 +1,577 @@
+"""Platinum Python SDK — client for hardware-isolated sandbox microVMs.
+
+Quick start:
+
+    from platinum import Platinum
+    dn = Platinum(token="pt_live_...", api_url="https://api.platinum.dev")
+
+    sbx = dn.sandboxes.create(template="pt-base", wait_for_running=True)
+    print(sbx.exec(["uname", "-a"]).stdout)
+    print(sbx.expose(8000)["url"])
+    sbx.delete()
+
+Inline declarative image — build + boot in one call (cache-hit on repeat):
+
+    from platinum import Platinum, Template
+    image = Template.from_python_image("3.12-slim").pip_install(["fastapi", "uvicorn"])
+    sbx = dn.sandboxes.create(image=image, env={"PORT": "8080"},
+                              wait_for_running=True, wait_timeout_ms=600_000)
+
+The client is synchronous (httpx.Client). It performs no automatic retries —
+a 429 or a failed create is surfaced to the caller, never silently retried.
+"""
+
+from __future__ import annotations
+
+import base64
+import os
+import time
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Union
+
+import httpx
+
+__all__ = ["Platinum", "Sandbox", "Template", "PlatinumError", "ExecResult"]
+
+# Default per-request timeout (seconds). Share/file bulk I/O overrides per call.
+_DEFAULT_TIMEOUT = 60.0
+_SHARE_TIMEOUT = 5 * 60.0
+
+_Bytes = Union[bytes, bytearray, str]
+
+
+class PlatinumError(Exception):
+    """Raised on any non-2xx response, or on a client-side terminal condition
+    (status=0 for the latter, e.g. a wait timeout or a terminal sandbox state)."""
+
+    def __init__(self, status: int, body: Any, message: str):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+@dataclass
+class ExecResult:
+    stdout: str
+    stderr: str
+    exit_code: int
+    error: Optional[str] = None
+
+    def check(self) -> "ExecResult":
+        """Raise if exit_code != 0 (analogous to subprocess.check_output)."""
+        if self.exit_code != 0:
+            raise PlatinumError(0, self, f"exec exit_code={self.exit_code}: {self.stderr or self.error}")
+        return self
+
+
+# ───────────────────────── client ─────────────────────────
+
+
+class Platinum:
+    def __init__(self, token: Optional[str] = None, api_url: Optional[str] = None,
+                 timeout: float = _DEFAULT_TIMEOUT):
+        self.token = token or os.environ.get("PT_TOKEN")
+        if not self.token:
+            raise ValueError("Platinum(token=...) or PT_TOKEN env required")
+        self.api_url = (api_url or os.environ.get("PT_API_URL") or "http://127.0.0.1:3000").rstrip("/")
+        # No retries: httpx.Client does not retry by default, and we never wrap
+        # it in a retrying transport — the no-auto-retry / no-429-retry contract.
+        self._http = httpx.Client(timeout=timeout, headers={"authorization": f"Bearer {self.token}"})
+        self.sandboxes = _Sandboxes(self)
+        self.templates = _Templates(self)
+        self.regions = _Regions(self)
+        self.health = _Health(self)
+
+    def __enter__(self) -> "Platinum":
+        return self
+
+    def __exit__(self, *a) -> None:
+        self._http.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    # ──────────── low-level request (escape hatch) ────────────
+    def request(self, method: str, path: str, *,
+                json: Optional[dict] = None,
+                query: Optional[Dict[str, Any]] = None,
+                content: Optional[_Bytes] = None,
+                raw: bool = False,
+                timeout: Optional[float] = None) -> Any:
+        """Issue a raw request. Returns parsed JSON, or raw ``bytes`` when
+        ``raw=True``. Drops ``None``/empty query values. Raises PlatinumError
+        on any status >= 300."""
+        kwargs: dict = {}
+        if json is not None:
+            kwargs["json"] = json
+        if content is not None:
+            kwargs["content"] = content
+        if query:
+            params = {k: v for k, v in query.items() if v is not None and v != ""}
+            if params:
+                kwargs["params"] = params
+        if timeout is not None:
+            kwargs["timeout"] = timeout
+        r = self._http.request(method, self.api_url + path, **kwargs)
+        if raw:
+            if r.status_code >= 300:
+                raise PlatinumError(r.status_code, r.text, f"{method} {path} -> {r.status_code}")
+            return r.content
+        try:
+            body: Any = r.json()
+        except Exception:
+            body = r.text
+        if r.status_code >= 300:
+            raise PlatinumError(r.status_code, body, f"{method} {path} -> {r.status_code}")
+        return body
+
+    # Backward-compatible internal alias.
+    def _req(self, method: str, path: str, json: Optional[dict] = None) -> Any:
+        return self.request(method, path, json=json)
+
+    def me(self) -> dict:
+        """Identity + role of the current bearer token."""
+        return self.request("GET", "/v1/me")
+
+
+class _Sandboxes:
+    def __init__(self, client: "Platinum"):
+        self._c = client
+
+    def create(self, *,
+               template: Optional[str] = None,
+               image: Optional[Union["Template", dict]] = None,
+               type: Optional[str] = None,
+               region: Optional[str] = None,
+               name: Optional[str] = None,
+               cpu: Optional[int] = None,
+               ram_mb: Optional[int] = None,
+               disk_gb: Optional[int] = None,
+               gpus: Optional[int] = None,
+               env: Optional[dict] = None,
+               env_vars: Optional[dict] = None,
+               volume_ids: Optional[List[str]] = None,
+               ssh_keys: Optional[List[str]] = None,
+               language: Optional[str] = None,
+               auto_stop_minutes: Optional[int] = None,
+               auto_archive_days: Optional[int] = None,
+               auto_delete_days: Optional[int] = None,
+               metadata: Optional[dict] = None,
+               expose: Optional[list] = None,
+               wait_for_running: bool = False,
+               wait_timeout_ms: int = 60_000) -> "Sandbox":
+        """Create a sandbox. Pass ``template`` (pre-built name/id) or ``image``
+        (a ``Template`` builder or a raw image-spec dict) — mutually exclusive.
+
+        With ``wait_for_running=True`` the server holds the POST open until the
+        sandbox is ``running`` (no client-side polling). Inline-image builds can
+        run minutes — raise ``wait_timeout_ms`` accordingly (e.g. 600_000).
+
+        Each ``expose`` entry: ``{"port": int, "public": bool=False,
+        "ttl_seconds": int?}``. Max 8; the URL(s) fold into the create response.
+        """
+        body: Dict[str, Any] = {}
+        if template is not None:
+            body["template"] = template
+        if image is not None:
+            body["image"] = image.to_image_spec() if isinstance(image, Template) else image
+        for k, v in (
+            ("type", type), ("region", region), ("name", name), ("cpu", cpu),
+            ("ram_mb", ram_mb), ("disk_gb", disk_gb), ("gpus", gpus),
+            ("env", env), ("envVars", env_vars), ("volume_ids", volume_ids),
+            ("ssh_keys", ssh_keys), ("language", language),
+            ("auto_stop_minutes", auto_stop_minutes),
+            ("auto_archive_days", auto_archive_days),
+            ("auto_delete_days", auto_delete_days),
+            ("metadata", metadata), ("expose", expose),
+        ):
+            if v is not None:
+                body[k] = v
+
+        query = None
+        rpc_timeout = None
+        if wait_for_running:
+            query = {"wait_for_state": "running", "wait_timeout_ms": wait_timeout_ms}
+            # Keep the connection open slightly beyond the server-side hold.
+            rpc_timeout = wait_timeout_ms / 1000.0 + 30.0
+
+        r = self._c.request("POST", "/v1/sandboxes", json=body, query=query, timeout=rpc_timeout)
+        return Sandbox(self._c, r["id"], state=r.get("state"), name=r.get("name"),
+                       host_id=r.get("host_id"), warm=r.get("warm"), exposed=r.get("exposed") or [])
+
+    def get(self, sandbox_id: str) -> dict:
+        return self._c.request("GET", f"/v1/sandboxes/{sandbox_id}")
+
+    def list(self, *, limit: int = 50, offset: int = 0,
+             state: Optional[str] = None) -> dict:
+        """List sandboxes (paginated). Returns ``{rows, total, has_more}``."""
+        return self._c.request("GET", "/v1/sandboxes",
+                               query={"paginated": "true", "limit": limit,
+                                      "offset": offset, "state": state})
+
+    def delete(self, sandbox_id: str) -> None:
+        self._c.request("DELETE", f"/v1/sandboxes/{sandbox_id}")
+
+    def rename(self, sandbox_id: str, name: Optional[str]) -> dict:
+        """Set or clear a sandbox's display label. Pass ``None``/``""`` to clear.
+        Raises PlatinumError(409) if another active sandbox uses the name."""
+        return self._c.request("PATCH", f"/v1/sandboxes/{sandbox_id}", json={"name": name})
+
+
+class _Templates:
+    def __init__(self, client: "Platinum"):
+        self._c = client
+
+    def list(self) -> list:
+        return self._c.request("GET", "/v1/templates")
+
+
+class _Regions:
+    def __init__(self, client: "Platinum"):
+        self._c = client
+
+    def list(self) -> list:
+        """Regions with at least one ready host."""
+        return self._c.request("GET", "/v1/regions")
+
+
+class _Health:
+    def __init__(self, client: "Platinum"):
+        self._c = client
+
+    def check(self) -> dict:
+        return self._c.request("GET", "/health")
+
+
+# ───────────────────────── sandbox handle ─────────────────────────
+
+
+class Sandbox:
+    def __init__(self, client: Platinum, sandbox_id: str, *,
+                 state: Optional[str] = None, name: Optional[str] = None,
+                 host_id: Optional[str] = None, warm: Optional[bool] = None,
+                 exposed: Optional[list] = None):
+        self._c = client
+        self.id = sandbox_id
+        # True if create() returned a warm-pool VM (claim, not fresh spawn).
+        self.warm = bool(warm)
+        self.name = name
+        self.host_id = host_id
+        # Ports pre-exposed via the inline `expose:` field on create — list of
+        # {port, url, token?, public}. Empty when the spawn wasn't expose-on-create.
+        self.exposed: list = exposed or []
+        self.files = _SandboxFiles(self)
+        self.share = _SandboxShare(self)
+
+    def exposed_url(self, port: int) -> Optional[str]:
+        """URL of a port pre-exposed at create-time, or None. For ports added
+        later, call .expose()."""
+        for e in self.exposed:
+            if e.get("port") == port:
+                return e.get("url")
+        return None
+
+    # ── lifecycle ──
+    def refresh(self) -> dict:
+        s = self._c.sandboxes.get(self.id)
+        self.host_id = s.get("hostId", self.host_id)
+        self.name = s.get("name")
+        return s
+
+    def wait_running(self, timeout: float = 30.0, interval: float = 0.25) -> dict:
+        """Block until the sandbox reaches state='running'."""
+        deadline = time.time() + timeout
+        last: dict = {}
+        while time.time() < deadline:
+            last = self.refresh()
+            st = last.get("state")
+            if st == "running":
+                return last
+            if (st or "").startswith("failed") or st in ("lost", "deleted"):
+                raise PlatinumError(0, last, f"sandbox {self.id} terminal: {st}")
+            time.sleep(interval)
+        raise PlatinumError(0, last, f"timeout waiting for running ({last.get('state')})")
+
+    def delete(self) -> None:
+        self._c.sandboxes.delete(self.id)
+
+    def pause(self) -> None:
+        self._c.request("POST", f"/v1/sandboxes/{self.id}/pause", json={})
+
+    def resume(self) -> None:
+        self._c.request("POST", f"/v1/sandboxes/{self.id}/resume", json={})
+
+    def fork(self) -> dict:
+        return self._c.request("POST", f"/v1/sandboxes/{self.id}/fork", json={})
+
+    def snapshot(self, name: Optional[str] = None) -> dict:
+        return self._c.request("POST", f"/v1/sandboxes/{self.id}/snapshot",
+                               json={"name": name} if name else {})
+
+    def archive(self) -> None:
+        self._c.request("POST", f"/v1/sandboxes/{self.id}/archive", json={})
+
+    def rename(self, name: Optional[str]) -> dict:
+        """Set or clear this sandbox's display label. Raises PlatinumError(409)
+        if another active sandbox already uses the name."""
+        s = self._c.sandboxes.rename(self.id, name)
+        self.name = s.get("name")
+        return s
+
+    def backup(self) -> dict:
+        return self._c.request("POST", f"/v1/sandboxes/{self.id}/backup", json={})
+
+    # ── exec / run-code ──
+    def exec(self, cmd: list, timeout_ms: int = 30_000) -> ExecResult:
+        r = self._c.request("POST", f"/v1/sandboxes/{self.id}/exec",
+                            json={"cmd": cmd, "timeout_ms": timeout_ms},
+                            timeout=timeout_ms / 1000.0 + 5.0)
+        if r.get("error"):
+            raise PlatinumError(0, r, r["error"])
+        rr = r["result"]
+        return ExecResult(stdout=rr.get("stdout", ""), stderr=rr.get("stderr", ""),
+                          exit_code=rr.get("exit_code", 0), error=rr.get("error"))
+
+    def sh(self, script: str, timeout_ms: int = 30_000) -> ExecResult:
+        return self.exec(["sh", "-c", script], timeout_ms=timeout_ms)
+
+    def run_code(self, code: str, lang: str = "python", timeout_ms: int = 30_000) -> ExecResult:
+        r = self._c.request("POST", f"/v1/sandboxes/{self.id}/run-code",
+                            json={"code": code, "lang": lang, "timeout_ms": timeout_ms},
+                            timeout=timeout_ms / 1000.0 + 5.0)
+        return ExecResult(stdout=r.get("stdout", ""), stderr=r.get("stderr", ""),
+                          exit_code=r.get("exit_code", 0), error=r.get("error"))
+
+    # ── networking ──
+    def expose(self, port: int) -> dict:
+        return self._c.request("POST", f"/v1/sandboxes/{self.id}/expose", json={"port": port})
+
+    def unexpose(self, port: int) -> None:
+        self._c.request("DELETE", f"/v1/sandboxes/{self.id}/expose/{port}")
+
+    def __repr__(self) -> str:
+        return f"<Sandbox id={self.id}>"
+
+
+class _SandboxFiles:
+    """vsock file ops — small reads/writes anywhere in the guest FS."""
+
+    def __init__(self, sbx: "Sandbox"):
+        self._c = sbx._c
+        self._id = sbx.id
+
+    def read(self, path: str) -> bytes:
+        return self._c.request("GET", f"/v1/sandboxes/{self._id}/files",
+                               query={"path": path}, raw=True)
+
+    def write(self, path: str, body: _Bytes) -> None:
+        self._c.request("PUT", f"/v1/sandboxes/{self._id}/files",
+                        query={"path": path}, content=body)
+
+    def delete(self, path: str) -> None:
+        self._c.request("DELETE", f"/v1/sandboxes/{self._id}/files", query={"path": path})
+
+    def list(self, path: str) -> list:
+        # API returns {ok, entries?}; unwrap to the entries list (or []).
+        r = self._c.request("GET", f"/v1/sandboxes/{self._id}/files/list", query={"path": path})
+        if isinstance(r, dict) and r.get("ok") is False:
+            raise PlatinumError(0, r, r.get("error") or f"files.list {path} failed")
+        return (r or {}).get("entries") or []
+
+    def stat(self, path: str) -> dict:
+        return self._c.request("GET", f"/v1/sandboxes/{self._id}/files/stat", query={"path": path})
+
+    def mkdir(self, path: str) -> None:
+        self._c.request("POST", f"/v1/sandboxes/{self._id}/files/mkdir", query={"path": path})
+
+
+class _SandboxShare:
+    """virtio-fs bulk transfer — works while the sandbox is paused."""
+
+    def __init__(self, sbx: "Sandbox"):
+        self._c = sbx._c
+        self._id = sbx.id
+
+    def info(self) -> dict:
+        return self._c.request("GET", f"/v1/sandboxes/{self._id}/share/info")
+
+    def list(self, path: str = "") -> dict:
+        return self._c.request("GET", f"/v1/sandboxes/{self._id}/share/list", query={"path": path})
+
+    def stat(self, path: str) -> dict:
+        return self._c.request("GET", f"/v1/sandboxes/{self._id}/share/stat", query={"path": path})
+
+    def get(self, path: str, timeout: float = _SHARE_TIMEOUT) -> bytes:
+        return self._c.request("GET", f"/v1/sandboxes/{self._id}/share/get",
+                               query={"path": path}, raw=True, timeout=timeout)
+
+    def put(self, path: str, body: _Bytes, timeout: float = _SHARE_TIMEOUT) -> dict:
+        return self._c.request("POST", f"/v1/sandboxes/{self._id}/share/put",
+                               query={"path": path}, content=body, timeout=timeout)
+
+    def mkdir(self, path: str) -> None:
+        self._c.request("POST", f"/v1/sandboxes/{self._id}/share/mkdir", query={"path": path})
+
+    def delete(self, path: str, recursive: bool = False) -> None:
+        self._c.request("DELETE", f"/v1/sandboxes/{self._id}/share/delete",
+                        query={"path": path, "recursive": "1" if recursive else None})
+
+
+# ───────────────────────── template builder ─────────────────────────
+
+
+@dataclass
+class Template:
+    """Declarative image builder — parity with the TS ``Template``.
+
+        tpl = (Template.from_python_image("3.12-slim")
+                       .pip_install(["fastapi", "uvicorn"])
+                       .workdir("/app")
+                       .entrypoint("uvicorn app:app --host 0.0.0.0 --port 8000")
+                       .ready_cmd("curl -fsS http://127.0.0.1:8000/health"))
+        result = tpl.build(dn, name="my-agent")     # POST /v1/templates/from-spec
+
+    Or pass it inline to ``sandboxes.create(image=tpl, ...)`` (no explicit name;
+    Platinum derives a deterministic ``inline-<hash>`` template).
+    """
+
+    base: str
+    steps: List[dict] = field(default_factory=list)
+    _entrypoint: Optional[str] = None
+    _ready_cmd: Optional[str] = None
+
+    # ── base image factories ──
+    @staticmethod
+    def from_image(ref: str) -> "Template":
+        return Template(ref)
+
+    @staticmethod
+    def from_python_image(version: str) -> "Template":
+        return Template(f"python:{version}")
+
+    @staticmethod
+    def from_node_image(version: str) -> "Template":
+        return Template(f"node:{version}")
+
+    @staticmethod
+    def from_bun_image(version: str) -> "Template":
+        return Template(f"oven/bun:{version}")
+
+    @staticmethod
+    def from_ubuntu_image(version: str) -> "Template":
+        return Template(f"ubuntu:{version}")
+
+    @staticmethod
+    def from_debian_image(version: str) -> "Template":
+        return Template(f"debian:{version}")
+
+    @staticmethod
+    def from_alpine_image(version: str) -> "Template":
+        return Template(f"alpine:{version}")
+
+    # ── chain ops (return self for fluent chaining) ──
+    def env(self, key: str, value: str) -> "Template":
+        self.steps.append({"op": "env", "key": key, "value": value})
+        return self
+
+    def workdir(self, path: str) -> "Template":
+        self.steps.append({"op": "workdir", "path": path})
+        return self
+
+    def user(self, user: str) -> "Template":
+        self.steps.append({"op": "user", "user": user})
+        return self
+
+    def run_cmd(self, cmd: str) -> "Template":
+        self.steps.append({"op": "run", "cmd": cmd})
+        return self
+
+    def pip_install(self, packages: List[str]) -> "Template":
+        self.steps.append({"op": "pip", "packages": packages})
+        return self
+
+    def npm_install(self, packages: List[str]) -> "Template":
+        self.steps.append({"op": "npm", "packages": packages})
+        return self
+
+    def apt_install(self, packages: List[str]) -> "Template":
+        self.steps.append({"op": "apt", "packages": packages})
+        return self
+
+    def copy(self, src: Union[str, bytes], dst: str, mode: Optional[str] = None) -> "Template":
+        """Inline copy. Small files only (<256 KiB). ``src`` is a local path
+        (read from disk) or raw ``bytes``."""
+        raw = open(src, "rb").read() if isinstance(src, str) else bytes(src)
+        if len(raw) > 256 * 1024:
+            raise ValueError("copy(): file too large for inline (>256 KiB). PUT it after build.")
+        step = {"op": "copy", "content_b64": base64.b64encode(raw).decode(), "dst": dst}
+        if mode is not None:
+            step["mode"] = mode
+        self.steps.append(step)
+        return self
+
+    def entrypoint(self, cmd: str) -> "Template":
+        self._entrypoint = cmd
+        return self
+
+    def ready_cmd(self, cmd: str) -> "Template":
+        self._ready_cmd = cmd
+        return self
+
+    # ── build ──
+    def to_spec(self, name: str, version: str = "1.0.0", *,
+                default_cpu: int = 1, default_ram_mb: int = 512,
+                default_disk_gb: int = 2, size_mb: int = 1024) -> dict:
+        return {
+            "name": name,
+            "version": version,
+            "base_image": self.base,
+            "steps": self.steps,
+            "entrypoint": self._entrypoint,
+            "ready_cmd": self._ready_cmd,
+            "default_cpu": default_cpu,
+            "default_ram_mb": default_ram_mb,
+            "default_disk_gb": default_disk_gb,
+            "size_mb": size_mb,
+        }
+
+    def to_image_spec(self, *, default_cpu: Optional[int] = None,
+                      default_ram_mb: Optional[int] = None,
+                      default_disk_gb: Optional[int] = None,
+                      size_mb: Optional[int] = None) -> dict:
+        """Inline-image shape for ``POST /v1/sandboxes`` (no name/version —
+        Platinum derives a deterministic ``inline-<hash>`` template)."""
+        return {
+            "base_image": self.base,
+            "steps": self.steps,
+            "entrypoint": self._entrypoint,
+            "ready_cmd": self._ready_cmd,
+            "default_cpu": default_cpu,
+            "default_ram_mb": default_ram_mb,
+            "default_disk_gb": default_disk_gb,
+            "size_mb": size_mb,
+        }
+
+    def build(self, dn: "Platinum", name: str, version: str = "1.0.0", *,
+              default_cpu: int = 1, default_ram_mb: int = 512,
+              default_disk_gb: int = 2, size_mb: int = 1024,
+              wait_ms: int = 5 * 60_000) -> dict:
+        """POST the spec to /v1/templates/from-spec and poll until the template
+        leaves 'building'. Returns ``{id, name, state, build_logs?, content_hash?}``.
+        ``wait_ms=0`` fires and returns immediately with state='building'."""
+        spec = self.to_spec(name, version, default_cpu=default_cpu,
+                            default_ram_mb=default_ram_mb, default_disk_gb=default_disk_gb,
+                            size_mb=size_mb)
+        queued = dn.request("POST", "/v1/templates/from-spec", json=spec)
+        tid = queued["id"]
+        if wait_ms == 0:
+            return {"id": tid, "name": name, "state": "building"}
+        deadline = time.time() + wait_ms / 1000.0
+        while time.time() < deadline:
+            for t in dn.request("GET", "/v1/templates"):
+                if t.get("id") == tid and t.get("state") in ("ready", "failed"):
+                    return {"id": tid, "name": name, "state": t["state"],
+                            "build_logs": t.get("buildLogs") or t.get("build_logs"),
+                            "content_hash": t.get("contentHash") or t.get("content_hash")}
+            time.sleep(3.0)
+        return {"id": tid, "name": name, "state": "building"}

platinum_sdk-0.1.0/platinum_sdk.egg-info/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: platinum-sdk
+Version: 0.1.0
+Summary: Platinum Python SDK — client for hardware-isolated sandbox microVMs.
+License: MIT
+Project-URL: Homepage, https://github.com/kortix-ai/platinum
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.25
+Dynamic: license-file
+
+# platinum-sdk (Python)
+
+Python client for [Platinum](https://github.com/kortix-ai/platinum) — hardware-isolated
+sandbox microVMs (one Cloud Hypervisor VM per sandbox, sub-second boots via a warm pool).
+
+> **Not on PyPI yet.** Until the first publish, install from source:
+> `pip install -e packages/sdk-py` (the import name is `platinum`).
+
+## Quickstart
+
+```python
+from platinum import Platinum
+
+dn = Platinum(token="pt_live_...", api_url="https://api.platinum.dev")
+# or: PT_TOKEN / PT_API_URL env vars
+
+sbx = dn.sandboxes.create(template="pt-base", wait_for_running=True)
+r = sbx.exec(["uname", "-a"]).check()     # .check() raises on non-zero exit
+print(r.stdout)
+sbx.delete()
+```
+
+Expose a port at create time (URL comes back in the same response):
+
+```python
+sbx = dn.sandboxes.create(
+    template="pt-base",
+    expose=[{"port": 8000, "public": True}],
+    wait_for_running=True,
+)
+print(sbx.exposed_url(8000))
+```
+
+## Configuration
+
+| Arg / env | Default | Meaning |
+|---|---|---|
+| `token` / `PT_TOKEN` | — (required) | API key `pt_live_…`, org-scoped bearer token |
+| `api_url` / `PT_API_URL` | `http://127.0.0.1:3000` | Control-plane URL |
+| `timeout` | `60.0` | Per-request timeout (seconds) |
+
+Python ≥ 3.9. **Synchronous only** (httpx). No automatic retries — a 429 or a failed
+create is surfaced to you, never silently retried. Server-side use only; never ship an
+API key into client-side code.
+
+## Surface (at parity with the TypeScript SDK)
+
+The two SDKs expose the same operations — enforced in CI by `verify/sdk-parity.sh`.
+
+| Area | Methods |
+|---|---|
+| Sandboxes | `sandboxes.create(...)` · `get` · `list` · `rename` · `delete` |
+| Lifecycle | `pause` · `resume` · `fork` · `snapshot` · `archive` · `rename` · `backup` · `wait_running` · `refresh` |
+| Run | `exec(argv)` · `sh(script)` · `run_code(code, lang)` |
+| Networking | `expose(port)` · `unexpose(port)` · `exposed_url(port)` |
+| Files (vsock) | `files.read` · `write` · `delete` · `list` · `stat` · `mkdir` |
+| Share (virtio-fs) | `share.info` · `list` · `stat` · `get` · `put` · `mkdir` · `delete` |
+| Platform | `templates.list()` · `regions.list()` · `health.check()` · `me()` |
+| Results | `ExecResult(stdout, stderr, exit_code)` with `.check()` |
+
+Build images declaratively with the `Template` builder (parity with the TS `Template`):
+
+```python
+from platinum import Platinum, Template
+
+dn = Platinum()
+image = (Template.from_python_image("3.12-slim")
+                 .pip_install(["fastapi", "uvicorn"])
+                 .workdir("/app"))
+sbx = dn.sandboxes.create(image=image, wait_for_running=True, wait_timeout_ms=600_000)
+```
+
+## Limits worth knowing
+
+- `exec` is buffered, not streaming — output arrives after the command exits
+  (default timeout 30 s via `timeout_ms`).
+- The default `pt-base` template is busybox-based — no git/pip/node/`httpd` inside
+  (`nc` and `wget` are available); build a template from a real distro image when you
+  need tooling.
+- Background processes are reaped when their `exec` call returns. To leave a server
+  running, daemonize it: `setsid sh -c '<server loop>' >/dev/null 2>&1 < /dev/null &`
+  — see `examples/02_expose_service.py`.
+- Errors raise `PlatinumError` with `.status` (HTTP status; `0` for non-HTTP failures).
+
+## Examples
+
+Runnable scripts in [`examples/`](./examples):
+
+```sh
+pip install -e packages/sdk-py
+PT_API_URL=… PT_TOKEN=… python packages/sdk-py/examples/01_create_exec_delete.py
+```
+
+## License
+
+MIT

platinum_sdk-0.1.0/platinum_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+pyproject.toml
+platinum/__init__.py
+platinum_sdk.egg-info/PKG-INFO
+platinum_sdk.egg-info/SOURCES.txt
+platinum_sdk.egg-info/dependency_links.txt
+platinum_sdk.egg-info/requires.txt
+platinum_sdk.egg-info/top_level.txt

platinum_sdk-0.1.0/platinum_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

platinum_sdk-0.1.0/platinum_sdk.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx>=0.25

platinum_sdk-0.1.0/platinum_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+platinum

platinum_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "platinum-sdk"
+version = "0.1.0"
+description = "Platinum Python SDK — client for hardware-isolated sandbox microVMs."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+dependencies = ["httpx>=0.25"]
+
+[project.urls]
+Homepage = "https://github.com/kortix-ai/platinum"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["platinum"]

platinum_sdk-0.1.0/setup.cfg

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