tyto.run 0.11.0__py3-none-any.whl

tyto/__init__.py

@@ -0,0 +1,62 @@
+from .client import Tyto
+from .config import TytoConfig
+from .errors import TytoAPIError, TytoError
+from .models import (
+    AuthPollResponse,
+    AuthStartResponse,
+    DeleteSnapshotResponse,
+    ForkResponse,
+    ForkStorage,
+    KeepaliveHoldData,
+    NestData,
+    NestLifecycle,
+    PreviewData,
+    ReadFileResult,
+    RestoreResponse,
+    SessionData,
+    SnapshotData,
+    SnapshotList,
+    User,
+    WakeResponse,
+)
+from .resources.auth import AuthResource
+from .resources.files import FileSystem
+from .resources.holds import HoldsResource
+from .resources.nests import Nest, NestsResource
+from .resources.previews import PreviewsResource, TopLevelPreviewsResource
+from .resources.sessions import Session, SessionsResource
+from .resources.snapshots import SnapshotsResource, TopLevelSnapshotsResource
+
+__all__ = [
+    "Tyto",
+    "TytoConfig",
+    "TytoError",
+    "TytoAPIError",
+    "User",
+    "AuthStartResponse",
+    "AuthPollResponse",
+    "NestData",
+    "NestLifecycle",
+    "WakeResponse",
+    "SessionData",
+    "PreviewData",
+    "SnapshotData",
+    "SnapshotList",
+    "RestoreResponse",
+    "ForkResponse",
+    "ForkStorage",
+    "DeleteSnapshotResponse",
+    "KeepaliveHoldData",
+    "ReadFileResult",
+    "Nest",
+    "NestsResource",
+    "Session",
+    "SessionsResource",
+    "FileSystem",
+    "PreviewsResource",
+    "TopLevelPreviewsResource",
+    "SnapshotsResource",
+    "TopLevelSnapshotsResource",
+    "HoldsResource",
+    "AuthResource",
+]

tyto/_http.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+import httpx
+
+from .config import TytoConfig
+from .errors import TytoAPIError
+
+
+class HttpClient:
+    def __init__(self, config: TytoConfig) -> None:
+        self._config = config
+        self._client = httpx.Client(
+            base_url=config.api_url,
+            headers={"Authorization": f"Bearer {config.api_key}"},
+            timeout=30.0,
+        )
+
+    def _raise_for_status(self, response: httpx.Response) -> None:
+        if response.is_success:
+            return
+        try:
+            body = response.json()
+            code = body.get("error")
+            message = body.get("message") or f"HTTP {response.status_code}"
+        except Exception:
+            code = None
+            message = f"HTTP {response.status_code}"
+        raise TytoAPIError(response.status_code, code, message)
+
+    def get(self, path: str, params: Optional[Dict[str, Any]] = None) -> Any:
+        resp = self._client.get(path, params={k: v for k, v in (params or {}).items() if v is not None})
+        self._raise_for_status(resp)
+        if resp.status_code == 204:
+            return None
+        return resp.json()
+
+    def post(self, path: str, json: Any = None, params: Optional[Dict[str, Any]] = None) -> Any:
+        resp = self._client.post(path, json=json, params={k: v for k, v in (params or {}).items() if v is not None})
+        self._raise_for_status(resp)
+        if resp.status_code == 204:
+            return None
+        return resp.json()
+
+    def put(self, path: str, json: Any = None) -> Any:
+        resp = self._client.put(path, json=json)
+        self._raise_for_status(resp)
+        if resp.status_code == 204:
+            return None
+        return resp.json()
+
+    def delete(self, path: str, params: Optional[Dict[str, Any]] = None) -> Any:
+        resp = self._client.delete(path, params={k: v for k, v in (params or {}).items() if v is not None})
+        self._raise_for_status(resp)
+        if resp.status_code == 204:
+            return None
+        return resp.json()
+
+    def put_binary(self, path: str, data: bytes, content_type: str, params: Dict[str, Any]) -> None:
+        resp = self._client.put(
+            path,
+            content=data,
+            headers={"Content-Type": content_type},
+            params={k: v for k, v in params.items() if v is not None},
+        )
+        self._raise_for_status(resp)
+
+    def get_binary(self, path: str, params: Optional[Dict[str, Any]] = None) -> tuple[bytes, str]:
+        resp = self._client.get(path, params={k: v for k, v in (params or {}).items() if v is not None})
+        self._raise_for_status(resp)
+        kind = resp.headers.get("X-Tyto-FS-Kind", "file")
+        return resp.content, kind
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "HttpClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()

tyto/client.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from ._http import HttpClient
+from .config import TytoConfig, resolve_config
+from .models import User
+from .resources.auth import AuthResource
+from .resources.nests import Nest, NestsResource
+from .resources.previews import TopLevelPreviewsResource
+from .resources.snapshots import TopLevelSnapshotsResource
+
+
+class Tyto:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        api_url: Optional[str] = None,
+    ) -> None:
+        self._config = resolve_config(api_key=api_key, api_url=api_url)
+        self._http = HttpClient(self._config)
+        self.auth = AuthResource(self._http)
+        self.nests = NestsResource(self._http, self._config)
+        self.previews = TopLevelPreviewsResource(self._http)
+        self.snapshots = TopLevelSnapshotsResource(self._http)
+
+    def create(
+        self,
+        name: str,
+        template: str = "ubuntu-24-dev",
+        repo_url: Optional[str] = None,
+    ) -> Nest:
+        return self.nests.create(name=name, template=template, repo_url=repo_url)
+
+    def health(self) -> dict:
+        return self._http.get("/healthz")
+
+    def ready(self) -> dict:
+        return self._http.get("/readyz")
+
+    def me(self) -> User:
+        return User.from_dict(self._http.get("/me"))
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Tyto":
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.close()

tyto/config.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from .errors import TytoError
+
+
+@dataclass
+class TytoConfig:
+    api_key: str = ""
+    api_url: str = "https://api.tyto.run"
+
+
+def resolve_config(
+    api_key: str | None = None,
+    api_url: str | None = None,
+) -> TytoConfig:
+    key = api_key or os.environ.get("TYTO_API_KEY", "")
+    if not key:
+        raise TytoError(
+            "api_key is required. Pass it as an argument or set the TYTO_API_KEY environment variable."
+        )
+    url = (api_url or os.environ.get("TYTO_API_URL", "https://api.tyto.run")).rstrip("/")
+    return TytoConfig(api_key=key, api_url=url)

tyto/errors.py

@@ -0,0 +1,13 @@
+class TytoError(Exception):
+    pass
+
+
+class TytoAPIError(TytoError):
+    def __init__(self, status: int, code: str | None, message: str) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+
+    def __repr__(self) -> str:
+        return f"TytoAPIError(status={self.status}, code={self.code!r}, message={self.message!r})"

tyto/models.py

@@ -0,0 +1,250 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Type, TypeVar
+
+T = TypeVar("T")
+
+
+def _from_dict(cls: Type[T], d: dict) -> T:
+    known = {f for f in cls.__dataclass_fields__}  # type: ignore[attr-defined]
+    return cls(**{k: v for k, v in d.items() if k in known})  # type: ignore[call-arg]
+
+
+@dataclass
+class User:
+    id: str
+    email: str
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "User":
+        return _from_dict(cls, d)
+
+
+@dataclass
+class AuthStartResponse:
+    login_url: str
+    device_code: str
+    expires_in: int
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "AuthStartResponse":
+        return _from_dict(cls, d)
+
+
+@dataclass
+class AuthPollResponse:
+    status: str
+    api_key: Optional[str] = None
+    user: Optional[User] = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "AuthPollResponse":
+        obj = _from_dict(cls, d)
+        if isinstance(obj.user, dict):
+            obj.user = User.from_dict(obj.user)
+        return obj
+
+
+@dataclass
+class NestData:
+    id: str
+    user_id: str
+    name: str
+    template: str
+    status: str
+    created_at: str
+    updated_at: str
+    repo_url: Optional[str] = None
+    error_message: Optional[str] = None
+    sleep_source: Optional[str] = None
+    lifecycle_error: Optional[str] = None
+    last_activity_at: Optional[str] = None
+    last_wake_at: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "NestData":
+        return _from_dict(cls, d)
+
+
+@dataclass
+class WakeResponse:
+    nest_id: Optional[str] = None
+    from_: Optional[str] = None
+    to: Optional[str] = None
+    path: Optional[str] = None
+    reason: Optional[str] = None
+    duration_ms: Optional[int] = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "WakeResponse":
+        mapped = {("from_" if k == "from" else k): v for k, v in d.items()}
+        known = {f for f in cls.__dataclass_fields__}  # type: ignore[attr-defined]
+        return cls(**{k: v for k, v in mapped.items() if k in known})
+
+
+@dataclass
+class NestLifecycle:
+    nest_id: Optional[str] = None
+    status: Optional[str] = None
+    sleep_source: Optional[str] = None
+    last_activity_at: Optional[str] = None
+    last_wake_at: Optional[str] = None
+    lifecycle_error: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "NestLifecycle":
+        return _from_dict(cls, d)
+
+
+@dataclass
+class SessionData:
+    id: Optional[int] = None
+    nest_id: Optional[str] = None
+    tty: Optional[bool] = None
+    command: Optional[str] = None
+    cwd: Optional[str] = None
+    status: Optional[str] = None
+    attached: Optional[int] = None
+    started_at: Optional[str] = None
+    last_activity_at: Optional[str] = None
+    exit_code: Optional[int] = None
+    ended_at: Optional[str] = None
+    attach_url: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "SessionData":
+        return _from_dict(cls, d)
+
+
+@dataclass
+class PreviewData:
+    id: Optional[str] = None
+    nest_id: Optional[str] = None
+    name: Optional[str] = None
+    port: Optional[int] = None
+    auth: Optional[str] = None
+    public: Optional[bool] = None
+    url: Optional[str] = None
+    path_url: Optional[str] = None
+    created_at: Optional[str] = None
+    expires_at: Optional[str] = None
+    revoked_at: Optional[str] = None
+    expires_in: Optional[int] = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "PreviewData":
+        return _from_dict(cls, d)
+
+
+@dataclass
+class SnapshotData:
+    id: Optional[str] = None
+    nest_id: Optional[str] = None
+    user_id: Optional[str] = None
+    name: Optional[str] = None
+    description: Optional[str] = None
+    state: Optional[str] = None
+    template_id: Optional[str] = None
+    logical_dirty_bytes: Optional[int] = None
+    apparent_bytes: Optional[int] = None
+    physical_bytes: Optional[int] = None
+    reclaimable_bytes: Optional[int] = None
+    reclaimable_status: Optional[str] = None
+    index_status: Optional[str] = None
+    created_at: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "SnapshotData":
+        return _from_dict(cls, d)
+
+
+@dataclass
+class SnapshotList:
+    nest_id: Optional[str] = None
+    snapshots: Optional[List[SnapshotData]] = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "SnapshotList":
+        obj = _from_dict(cls, d)
+        if obj.snapshots:
+            obj.snapshots = [SnapshotData.from_dict(s) if isinstance(s, dict) else s for s in obj.snapshots]
+        return obj
+
+
+@dataclass
+class RestoreResponse:
+    nest_id: Optional[str] = None
+    restored_from: Optional[str] = None
+    status: Optional[str] = None
+    message: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "RestoreResponse":
+        return _from_dict(cls, d)
+
+
+@dataclass
+class ForkStorage:
+    copy_method: Optional[str] = None
+    physical_bytes_added_now: Optional[int] = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "ForkStorage":
+        return _from_dict(cls, d)
+
+
+@dataclass
+class ForkResponse:
+    id: Optional[str] = None
+    name: Optional[str] = None
+    source_nest_id: Optional[str] = None
+    status: Optional[str] = None
+    template_id: Optional[str] = None
+    source_restarted: Optional[bool] = None
+    source_restart_error: Optional[str] = None
+    storage: Optional[ForkStorage] = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "ForkResponse":
+        obj = _from_dict(cls, d)
+        if isinstance(obj.storage, dict):
+            obj.storage = ForkStorage.from_dict(obj.storage)
+        return obj
+
+
+@dataclass
+class DeleteSnapshotResponse:
+    snapshot_id: Optional[str] = None
+    can_delete: Optional[bool] = None
+    would_free_bytes: Optional[int] = None
+    would_remain_shared_bytes: Optional[int] = None
+    reclaimable_status: Optional[str] = None
+    blocked_by: Optional[List[str]] = None
+    deleted: Optional[bool] = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "DeleteSnapshotResponse":
+        return _from_dict(cls, d)
+
+
+@dataclass
+class KeepaliveHoldData:
+    nest_id: Optional[str] = None
+    name: Optional[str] = None
+    source: Optional[str] = None
+    reason: Optional[str] = None
+    expires_at: Optional[str] = None
+    last_heartbeat_at: Optional[str] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "KeepaliveHoldData":
+        return _from_dict(cls, d)
+
+
+@dataclass
+class ReadFileResult:
+    data: bytes
+    kind: str

tyto/resources/auth.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from .._http import HttpClient
+from ..models import AuthPollResponse, AuthStartResponse
+
+
+class AuthResource:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def start_cli(
+        self,
+        client: str = "tyto-cli",
+        hostname: Optional[str] = None,
+    ) -> AuthStartResponse:
+        body: dict = {"client": client}
+        if hostname is not None:
+            body["hostname"] = hostname
+        return AuthStartResponse.from_dict(self._http.post("/auth/cli/start", json=body))
+
+    def poll_cli(self, device_code: str) -> AuthPollResponse:
+        return AuthPollResponse.from_dict(
+            self._http.post("/auth/cli/poll", json={"device_code": device_code})
+        )

tyto/resources/files.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from .._http import HttpClient
+from ..models import ReadFileResult
+
+
+class FileSystem:
+    def __init__(self, nest_id: str, http: HttpClient) -> None:
+        self._nest_id = nest_id
+        self._http = http
+
+    def write(self, path: str, data: bytes, kind: str = "file") -> None:
+        content_type = "application/x-tar" if kind == "dir" else "application/octet-stream"
+        self._http.put_binary(
+            f"/nest/{self._nest_id}/fs/write",
+            data=data,
+            content_type=content_type,
+            params={"path": path, "kind": kind},
+        )
+
+    def read(self, path: str) -> ReadFileResult:
+        data, kind = self._http.get_binary(
+            f"/nest/{self._nest_id}/fs/read",
+            params={"path": path},
+        )
+        return ReadFileResult(data=data, kind=kind)

tyto/resources/holds.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from typing import List, Optional
+
+from .._http import HttpClient
+from ..models import KeepaliveHoldData
+
+
+class HoldsResource:
+    def __init__(self, nest_id: str, http: HttpClient) -> None:
+        self._nest_id = nest_id
+        self._http = http
+
+    def list(self) -> List[KeepaliveHoldData]:
+        result = self._http.get(f"/nest/{self._nest_id}/holds")
+        return [KeepaliveHoldData.from_dict(d) for d in result]
+
+    def put(
+        self,
+        name: str,
+        ttl: Optional[str] = None,
+        reason: Optional[str] = None,
+        source: Optional[str] = None,
+    ) -> KeepaliveHoldData:
+        body: dict = {}
+        if ttl is not None:
+            body["ttl"] = ttl
+        if reason is not None:
+            body["reason"] = reason
+        if source is not None:
+            body["source"] = source
+        result = self._http.put(f"/nest/{self._nest_id}/holds/{name}", json=body)
+        return KeepaliveHoldData.from_dict(result)
+
+    def delete(self, name: str) -> None:
+        self._http.delete(f"/nest/{self._nest_id}/holds/{name}")
+
+    def heartbeat(
+        self,
+        name: str,
+        ttl: Optional[str] = None,
+        reason: Optional[str] = None,
+        source: Optional[str] = None,
+    ) -> KeepaliveHoldData:
+        body: dict = {}
+        if ttl is not None:
+            body["ttl"] = ttl
+        if reason is not None:
+            body["reason"] = reason
+        if source is not None:
+            body["source"] = source
+        result = self._http.post(f"/nest/{self._nest_id}/holds/{name}/heartbeat", json=body)
+        return KeepaliveHoldData.from_dict(result)

tyto/resources/nests.py

@@ -0,0 +1,285 @@
+from __future__ import annotations
+
+import io
+import os
+import shlex
+import tarfile
+import time
+import uuid
+from pathlib import Path
+from typing import List, Optional, Union
+
+from .._http import HttpClient
+from ..config import TytoConfig
+from ..models import (
+    DeleteSnapshotResponse,
+    ForkResponse,
+    NestData,
+    NestLifecycle,
+    PreviewData,
+    RestoreResponse,
+    SessionData,
+    SnapshotData,
+    WakeResponse,
+)
+from ..ws import connect_ws
+from .files import FileSystem
+from .holds import HoldsResource
+from .previews import PreviewsResource
+from .sessions import Session, SessionsResource
+from .snapshots import SnapshotsResource
+
+
+class Nest:
+    def __init__(self, data: NestData, http: HttpClient, config: TytoConfig) -> None:
+        self._data = data
+        self._http = http
+        self._config = config
+        self.fs = FileSystem(data.id, http)
+        self.sessions = SessionsResource(data.id, http, config)
+        self.previews = PreviewsResource(data.id, http)
+        self.snapshots = SnapshotsResource(data.id, http)
+        self.holds = HoldsResource(data.id, http)
+
+    @property
+    def id(self) -> str:
+        return self._data.id
+
+    @property
+    def user_id(self) -> str:
+        return self._data.user_id
+
+    @property
+    def name(self) -> str:
+        return self._data.name
+
+    @property
+    def template(self) -> str:
+        return self._data.template
+
+    @property
+    def status(self) -> str:
+        return self._data.status
+
+    @property
+    def repo_url(self) -> Optional[str]:
+        return self._data.repo_url
+
+    @property
+    def error_message(self) -> Optional[str]:
+        return self._data.error_message
+
+    @property
+    def sleep_source(self) -> Optional[str]:
+        return self._data.sleep_source
+
+    @property
+    def lifecycle_error(self) -> Optional[str]:
+        return self._data.lifecycle_error
+
+    @property
+    def last_activity_at(self) -> Optional[str]:
+        return self._data.last_activity_at
+
+    @property
+    def last_wake_at(self) -> Optional[str]:
+        return self._data.last_wake_at
+
+    @property
+    def created_at(self) -> str:
+        return self._data.created_at
+
+    @property
+    def updated_at(self) -> str:
+        return self._data.updated_at
+
+    @property
+    def data(self) -> NestData:
+        return self._data
+
+    def start(self) -> Union["Nest", WakeResponse]:
+        result = self._http.post(f"/nest/{self._data.id}/start")
+        if "user_id" in result:
+            self._data = NestData.from_dict(result)
+            return self
+        return WakeResponse.from_dict(result)
+
+    def stop(self) -> "Nest":
+        result = self._http.post(f"/nest/{self._data.id}/stop")
+        self._data = NestData.from_dict(result)
+        return self
+
+    def wake(self, reason: Optional[str] = None) -> WakeResponse:
+        body = {"reason": reason} if reason else {}
+        return WakeResponse.from_dict(self._http.post(f"/nest/{self._data.id}/wake", json=body))
+
+    def delete(self) -> Optional[NestData]:
+        result = self._http.delete(f"/nest/{self._data.id}")
+        return NestData.from_dict(result) if result else None
+
+    def lifecycle(self) -> NestLifecycle:
+        return NestLifecycle.from_dict(self._http.get(f"/nest/{self._data.id}/lifecycle"))
+
+    def restore(self, snapshot_id: str) -> RestoreResponse:
+        result = self._http.post(
+            f"/nest/{self._data.id}/restore",
+            json={"snapshot_id": snapshot_id},
+        )
+        return RestoreResponse.from_dict(result)
+
+    def fork(
+        self,
+        name: str,
+        stop_if_running: bool = False,
+        restart_source: bool = False,
+    ) -> ForkResponse:
+        result = self._http.post(
+            f"/nest/{self._data.id}/fork",
+            json={"name": name, "stop_if_running": stop_if_running, "restart_source": restart_source},
+        )
+        return ForkResponse.from_dict(result)
+
+    def run(
+        self,
+        argv: list,
+        cwd: Optional[str] = None,
+        cols: int = 80,
+        rows: int = 24,
+        timeout_s: float = 120.0,
+    ) -> str:
+        """Run a command in the nest and return its captured output.
+
+        The API runs managed sessions to completion server-side and only exposes
+        live output over a WebSocket, which is racy for short commands (the
+        session can finish before the stream attaches, yielding HTTP 410). So we
+        redirect the command's stdout+stderr and exit code to files, poll the
+        filesystem until the exit-code file appears, then read the output back
+        over the (reliable) filesystem API. No WebSocket required.
+        """
+        work_dir = "/home/tyto/.tyto-run"
+        run_id = uuid.uuid4().hex
+        out_abs = f"{work_dir}/{run_id}.out"
+        rc_abs = f"{work_dir}/{run_id}.rc"
+        out_rel = f".tyto-run/{run_id}.out"
+        rc_rel = f".tyto-run/{run_id}.rc"
+
+        effective_cwd = cwd or "/home/tyto"
+        inner = " ".join(shlex.quote(a) for a in argv)
+        script = (
+            f"mkdir -p {shlex.quote(work_dir)}; "
+            f"{{ cd {shlex.quote(effective_cwd)} && {inner} ; }} > {shlex.quote(out_abs)} 2>&1; "
+            f"echo $? > {shlex.quote(rc_abs)}"
+        )
+
+        self.sessions.create(
+            argv=["bash", "-lc", script], tty=True, cwd=cwd, cols=cols, rows=rows
+        )
+
+        # The exit-code file is written only after the command completes, so its
+        # presence is an unambiguous "done" signal. (Session status is unreliable
+        # here: a quiet tty session reports "idle" while still running.)
+        deadline = time.perf_counter() + timeout_s
+        while time.perf_counter() < deadline:
+            time.sleep(0.5)
+            try:
+                if self.fs.read(rc_rel).data.decode().strip():
+                    break
+            except Exception:
+                continue  # exit-code file not written yet
+
+        try:
+            return self.fs.read(out_rel).data.decode(errors="replace")
+        except Exception:
+            return ""
+
+    def create_snapshot(
+        self,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        stop_if_running: bool = False,
+    ) -> SnapshotData:
+        return self.snapshots.create(name=name, description=description, stop_if_running=stop_if_running)
+
+    def delete_snapshot(self, snapshot_id: str, dry_run: bool = False) -> DeleteSnapshotResponse:
+        params: dict = {"dry_run": dry_run} if dry_run else {}
+        result = self._http.delete(f"/snapshots/{snapshot_id}", params=params)
+        return DeleteSnapshotResponse.from_dict(result)
+
+    def create_session(
+        self,
+        argv: list,
+        tty: bool = False,
+        cwd: Optional[str] = None,
+        cols: Optional[int] = None,
+        rows: Optional[int] = None,
+        env: Optional[dict] = None,
+    ) -> Session:
+        return self.sessions.create(argv=argv, tty=tty, cwd=cwd, cols=cols, rows=rows, env=env)
+
+    def create_preview(
+        self,
+        port: int,
+        auth: str = "private",
+        public: bool = False,
+        name: Optional[str] = None,
+    ) -> PreviewData:
+        return self.previews.create(port=port, auth=auth, public=public, name=name)
+
+    def put(self, local_path: str, remote_path: str) -> None:
+        local = Path(local_path)
+        if local.is_dir():
+            buf = io.BytesIO()
+            with tarfile.open(fileobj=buf, mode="w:") as tf:
+                tf.add(str(local), arcname=".")
+            self.fs.write(remote_path, buf.getvalue(), kind="dir")
+        else:
+            self.fs.write(remote_path, local.read_bytes(), kind="file")
+
+    def get(self, remote_path: str, local_path: str) -> None:
+        result = self.fs.read(remote_path)
+        if result.kind == "dir":
+            dest = Path(local_path)
+            dest.mkdir(parents=True, exist_ok=True)
+            buf = io.BytesIO(result.data)
+            with tarfile.open(fileobj=buf, mode="r:") as tf:
+                tf.extractall(str(dest))
+        else:
+            dest = Path(local_path)
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            dest.write_bytes(result.data)
+
+    def console(self):
+        return connect_ws(self._config, f"/nest/{self._data.id}/console")
+
+    def exec(self):
+        return connect_ws(self._config, f"/nest/{self._data.id}/exec")
+
+    def __repr__(self) -> str:
+        return f"Nest(id={self.id!r}, name={self.name!r}, status={self.status!r})"
+
+
+class NestsResource:
+    def __init__(self, http: HttpClient, config: TytoConfig) -> None:
+        self._http = http
+        self._config = config
+
+    def create(
+        self,
+        name: str,
+        template: str = "ubuntu-24-dev",
+        repo_url: Optional[str] = None,
+    ) -> Nest:
+        body: dict = {"name": name, "template": template}
+        if repo_url is not None:
+            body["repo_url"] = repo_url
+        result = self._http.post("/nest/", json=body)
+        return Nest(NestData.from_dict(result), self._http, self._config)
+
+    def list(self) -> List[Nest]:
+        result = self._http.get("/nest/")
+        return [Nest(NestData.from_dict(d), self._http, self._config) for d in result]
+
+    def get(self, nest_id: str) -> Nest:
+        result = self._http.get(f"/nest/{nest_id}")
+        return Nest(NestData.from_dict(result), self._http, self._config)
+

tyto/resources/previews.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import List, Optional
+
+from .._http import HttpClient
+from ..models import PreviewData
+
+
+class PreviewsResource:
+    def __init__(self, nest_id: str, http: HttpClient) -> None:
+        self._nest_id = nest_id
+        self._http = http
+
+    def create(
+        self,
+        port: int,
+        auth: str = "private",
+        public: bool = False,
+        name: Optional[str] = None,
+    ) -> PreviewData:
+        body: dict = {"port": port, "auth": auth, "public": public}
+        if name is not None:
+            body["name"] = name
+        result = self._http.post(f"/nest/{self._nest_id}/previews", json=body)
+        return PreviewData.from_dict(result)
+
+    def list(self) -> List[PreviewData]:
+        result = self._http.get(f"/nest/{self._nest_id}/previews")
+        return [PreviewData.from_dict(d) for d in result]
+
+
+class TopLevelPreviewsResource:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def get(self, preview_id: str) -> PreviewData:
+        return PreviewData.from_dict(self._http.get(f"/previews/{preview_id}"))
+
+    def revoke(self, preview_id: str) -> None:
+        self._http.delete(f"/previews/{preview_id}")

tyto/resources/sessions.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
+from .._http import HttpClient
+from ..config import TytoConfig
+from ..models import SessionData
+from ..ws import connect_ws
+
+
+class Session:
+    def __init__(self, data: SessionData, nest_id: str, http: HttpClient, config: TytoConfig) -> None:
+        self._data = data
+        self._nest_id = nest_id
+        self._http = http
+        self._config = config
+
+    @property
+    def id(self) -> Optional[int]:
+        return self._data.id
+
+    @property
+    def nest_id(self) -> Optional[str]:
+        return self._data.nest_id
+
+    @property
+    def tty(self) -> Optional[bool]:
+        return self._data.tty
+
+    @property
+    def command(self) -> Optional[str]:
+        return self._data.command
+
+    @property
+    def cwd(self) -> Optional[str]:
+        return self._data.cwd
+
+    @property
+    def status(self) -> Optional[str]:
+        return self._data.status
+
+    @property
+    def attached(self) -> Optional[int]:
+        return self._data.attached
+
+    @property
+    def started_at(self) -> Optional[str]:
+        return self._data.started_at
+
+    @property
+    def exit_code(self) -> Optional[int]:
+        return self._data.exit_code
+
+    @property
+    def ended_at(self) -> Optional[str]:
+        return self._data.ended_at
+
+    @property
+    def attach_url(self) -> Optional[str]:
+        return self._data.attach_url
+
+    @property
+    def data(self) -> SessionData:
+        return self._data
+
+    def kill(self, signal: str = "TERM", grace_ms: int = 5000) -> "Session":
+        result = self._http.post(
+            f"/nest/{self._nest_id}/sessions/{self._data.id}/kill",
+            json={"signal": signal, "grace_ms": grace_ms},
+        )
+        self._data = SessionData.from_dict(result)
+        return self
+
+    def attach(self):
+        return connect_ws(self._config, f"/nest/{self._nest_id}/sessions/{self._data.id}/attach")
+
+
+class SessionsResource:
+    def __init__(self, nest_id: str, http: HttpClient, config: TytoConfig) -> None:
+        self._nest_id = nest_id
+        self._http = http
+        self._config = config
+
+    def create(
+        self,
+        argv: List[str],
+        tty: bool = False,
+        cwd: Optional[str] = None,
+        cols: Optional[int] = None,
+        rows: Optional[int] = None,
+        env: Optional[Dict[str, str]] = None,
+    ) -> Session:
+        body: dict = {"tty": tty, "argv": argv}
+        if cwd is not None:
+            body["cwd"] = cwd
+        if cols is not None:
+            body["cols"] = cols
+        if rows is not None:
+            body["rows"] = rows
+        if env is not None:
+            body["env"] = env
+        result = self._http.post(f"/nest/{self._nest_id}/sessions", json=body)
+        return Session(SessionData.from_dict(result), self._nest_id, self._http, self._config)
+
+    def list(self, all: bool = False, history: bool = False) -> List[Session]:
+        params: dict = {}
+        if all:
+            params["all"] = True
+        if history:
+            params["history"] = True
+        result = self._http.get(f"/nest/{self._nest_id}/sessions", params=params)
+        return [Session(SessionData.from_dict(d), self._nest_id, self._http, self._config) for d in result]

tyto/resources/snapshots.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from .._http import HttpClient
+from ..models import (
+    DeleteSnapshotResponse,
+    ForkResponse,
+    RestoreResponse,
+    SnapshotData,
+    SnapshotList,
+)
+
+
+class SnapshotsResource:
+    def __init__(self, nest_id: str, http: HttpClient) -> None:
+        self._nest_id = nest_id
+        self._http = http
+
+    def create(
+        self,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        stop_if_running: bool = False,
+    ) -> SnapshotData:
+        body: dict = {"stop_if_running": stop_if_running}
+        if name is not None:
+            body["name"] = name
+        if description is not None:
+            body["description"] = description
+        result = self._http.post(f"/nest/{self._nest_id}/snapshots", json=body)
+        return SnapshotData.from_dict(result)
+
+    def list(self) -> SnapshotList:
+        return SnapshotList.from_dict(self._http.get(f"/nest/{self._nest_id}/snapshots"))
+
+    def restore(self, snapshot_id: str) -> RestoreResponse:
+        result = self._http.post(
+            f"/nest/{self._nest_id}/restore",
+            json={"snapshot_id": snapshot_id},
+        )
+        return RestoreResponse.from_dict(result)
+
+    def fork(
+        self,
+        name: str,
+        stop_if_running: bool = False,
+        restart_source: bool = False,
+    ) -> ForkResponse:
+        result = self._http.post(
+            f"/nest/{self._nest_id}/fork",
+            json={"name": name, "stop_if_running": stop_if_running, "restart_source": restart_source},
+        )
+        return ForkResponse.from_dict(result)
+
+
+class TopLevelSnapshotsResource:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def delete(self, snapshot_id: str, dry_run: bool = False) -> DeleteSnapshotResponse:
+        params = {"dry_run": dry_run} if dry_run else {}
+        result = self._http.delete(f"/snapshots/{snapshot_id}", params=params)
+        return DeleteSnapshotResponse.from_dict(result)

tyto/ws.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from .config import TytoConfig
+
+
+def connect_ws(config: TytoConfig, path: str):
+    from websockets.sync.client import connect
+
+    ws_url = config.api_url.replace("https://", "wss://").replace("http://", "ws://") + path
+    return connect(ws_url, additional_headers={"Authorization": f"Bearer {config.api_key}"})

tyto_run-0.11.0.dist-info/METADATA

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: tyto.run
+Version: 0.11.0
+Summary: Official Python SDK for the Tyto API
+Project-URL: Homepage, https://tyto.run
+Author: Bonya
+License: MIT
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: websockets>=13.0
+Description-Content-Type: text/markdown
+
+# tyto
+
+Python SDK for the [Tyto API](https://api.tyto.run) — manage nests, sessions, files, previews, snapshots, and keepalive holds.
+
+## Install
+
+```bash
+pip install tyto
+```
+
+## Auth
+
+Export your API key:
+
+```bash
+export TYTO_API_KEY=your_key_here
+```
+
+Or pass it directly:
+
+```python
+from tyto import Tyto
+tyto = Tyto(api_key="your_key_here")
+```
+
+## Usage
+
+```python
+import os
+from tyto import Tyto
+
+tyto = Tyto(api_key=os.environ["TYTO_API_KEY"])
+
+# Who am I?
+me = tyto.me()
+print(me.email)
+
+# Create a nest
+nest = tyto.create(name="my-nest", template="ubuntu-24-dev")
+
+# Upload / download a file or directory
+nest.put("./hello.txt", "hello.txt")
+nest.get("hello.txt", "./hello.downloaded.txt")
+
+# Create a session and attach over WebSocket
+session = nest.create_session(argv=["bash", "-lc", "echo hi"], tty=False)
+with session.attach() as ws:
+    for message in ws:
+        print(message)
+
+# Open raw WebSocket connections
+with nest.exec() as ws: ...
+with nest.console() as ws: ...
+
+# Create a preview
+preview = nest.create_preview(port=3000, auth="private")
+print(preview.url)
+
+# Snapshot, fork, restore
+snap = nest.create_snapshot(name="v1")
+fork = nest.fork(name="my-fork")
+nest.delete_snapshot(snap.id)
+# nest.restore(snap.id)
+
+# Keepalive hold
+nest.holds.put("ci", ttl="30m", reason="CI job")
+nest.holds.heartbeat("ci", ttl="30m")
+nest.holds.delete("ci")
+
+# Lifecycle
+nest.stop()
+nest.start()
+nest.wake(reason="wakeup")
+nest.delete()
+```
+
+## Resources
+
+| Resource | Description |
+|---|---|
+| `tyto.create()` | Create a nest |
+| `tyto.nests` | Create / list / get nests |
+| `tyto.previews` | Inspect / revoke previews by ID |
+| `tyto.auth` | CLI browser auth flow |
+| `nest.put(local, remote)` | Upload a file or directory |
+| `nest.get(remote, local)` | Download a file or directory |
+| `nest.create_session()` | Create a managed session |
+| `nest.create_preview()` | Create a preview URL |
+| `nest.create_snapshot()` | Create a snapshot |
+| `nest.delete_snapshot()` | Delete a snapshot |
+| `nest.fs` | Low-level file upload / download |
+| `nest.sessions` | Managed sessions (create / list) |
+| `nest.previews` | Previews scoped to the nest |
+| `nest.snapshots` | Snapshots + fork/restore |
+| `nest.holds` | Keepalive holds |
+| `session.attach()` | WebSocket stream for a session |
+| `nest.console()` | Interactive shell WebSocket |
+| `nest.exec()` | Command WebSocket |
+
+## Configuration
+
+| Parameter | Env var | Default |
+|---|---|---|
+| `api_key` | `TYTO_API_KEY` | — (required) |
+| `api_url` | `TYTO_API_URL` | `https://api.tyto.run` |
+
+## Examples
+
+```bash
+python examples/quickstart.py
+python examples/files.py
+python examples/preview.py
+python examples/snapshot_fork.py
+python examples/websocket_exec.py
+```
+
+## Context manager
+
+The `Tyto` client can be used as a context manager to ensure the underlying HTTP connection pool is closed:
+
+```python
+with Tyto() as tyto:
+    nests = tyto.nests.list()
+```

tyto_run-0.11.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+tyto/__init__.py,sha256=5hkYjZd1XOcdWWnaRnsoDEblpejdJuVq-sg_m4TpSpU,1473
+tyto/_http.py,sha256=splieE2PMZITwLcfMVn-BDCGD0T-vCjih65pJGju03k,2940
+tyto/client.py,sha256=_t6qVm_DDWYhQq2iHb4hJxwJorTQDmWDNDTVOTQBorM,1486
+tyto/config.py,sha256=PcuP8opW09RUXj4Lwa2zGkP9GAyzFtbHPshMCqyBEbM,658
+tyto/errors.py,sha256=7dX-lK0MkNJYTUmp1ScCegl85g_3wzGNa7mBGoKHPmU,397
+tyto/models.py,sha256=e2gr8o42x7yzbIW12FB2kXaW1UHSSkA7LZ7zm-i3jug,6571
+tyto/ws.py,sha256=l8Dwu13YS_LDew4wm2Z_dBf93dG_2NBYvcWeQZsuoUM,350
+tyto/resources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tyto/resources/auth.py,sha256=lA1o84qCwoD_KWc254imj67FXmLdR3O5KwRrIovQUBo,787
+tyto/resources/files.py,sha256=fp5XqFgVa5ccES3O23g95b1l_OyKao-tdG_HcEnzz54,847
+tyto/resources/holds.py,sha256=c9Zy3Jh4fjcFuKlfR9Mmr7-DNyZVdrh8fKOxnlsTKxo,1656
+tyto/resources/nests.py,sha256=df8cCatt6T6cRovPiGuaVqtn_KhQWwlMGTeZ93Fn-2k,9342
+tyto/resources/previews.py,sha256=g89Xxn9J-EVt1hmaWDQn2ctybhZNTF_uTYnv4wAcNqY,1215
+tyto/resources/sessions.py,sha256=VX1n0lEEhbiuoGhV0wrkyLLucf7Y3Q2VTEIp24xZD9Y,3238
+tyto/resources/snapshots.py,sha256=MFi5wn7r2umbMFOyDbh-uHcRhhKfwnqkg7l8_KmKQFU,2023
+tyto_run-0.11.0.dist-info/METADATA,sha256=LJD0DElIyqkcz8UbPBCbAnEukou-18Qaqa_g_SGCINY,3217
+tyto_run-0.11.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+tyto_run-0.11.0.dist-info/RECORD,,

tyto_run-0.11.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any