cubepod 0.4.0__tar.gz

cubepod-0.4.0/.gitignore

@@ -0,0 +1,60 @@
+# Binaries and build artifacts
+bin/
+dist/
+target/
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+*.test
+*.out
+coverage.txt
+coverage.xml
+
+# Go workspace / vendor
+go.work
+go.work.sum
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+.eggs/
+
+# Node / TypeScript
+node_modules/
+.pnpm-store/
+*.tsbuildinfo
+
+# Local development & runtime artifacts
+.env
+.env.*
+!.env.example
+deploy/k8s/env.local
+*.img
+*.qcow2
+*.raw
+tmp/
+logs/
+.cubepod-data/
+
+# Kubernetes / Helm secrets
+deploy/helm/cubepod/values.local.yaml
+*ca-secret.yaml
+*.pem
+*.key
+*.crt
+
+# IDE / OS
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store

cubepod-0.4.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.5
+Name: cubepod
+Version: 0.4.0
+Summary: Async-first Python SDK for CubePod (E2B-compatible persistent MicroVM sandboxes)
+Project-URL: Homepage, https://github.com/cubeplexai/cubepod
+Project-URL: Repository, https://github.com/cubeplexai/cubepod
+Project-URL: Issues, https://github.com/cubeplexai/cubepod/issues
+Author: CubePlex Maintainers
+License-Expression: Apache-2.0
+Keywords: ai-agents,cubepod,e2b,kata-containers,microvm,sandbox
+Classifier: Development Status :: 4 - Beta
+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: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: test
+Requires-Dist: e2b-code-interpreter>=2.0.0; extra == 'test'
+Requires-Dist: e2b>=2.0.0; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
+Requires-Dist: pytest>=8.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# CubePod Python SDK
+
+Async-first Python client for **CubePod** — a persistent, writable-RootFS MicroVM execution platform for AI agents with an E2B-compatible Control & Data Plane API.
+
+## Installation
+
+```bash
+pip install cubepod
+```
+
+Requires Python 3.11+.
+
+## Quickstart (Async & Sync)
+
+```python
+import asyncio
+from cubepod import AsyncCubePod, CubePod
+
+async def main() -> None:
+    async with AsyncCubePod(base_url="http://localhost:8080", api_key="...") as client:
+        box = await client.create("cubeplex-ubuntu24-desktop")
+        res = await client.execute(box.sandbox_id, "python3 --version")
+        print(res.output)
+        await client.delete(box.sandbox_id)
+
+asyncio.run(main())
+
+# Synchronous client
+with CubePod(base_url="http://localhost:8080", api_key="...") as client:
+    box = client.create("cubeplex-ubuntu24-desktop")
+    print(client.execute(box.sandbox_id, "uname -a").output)
+    client.delete(box.sandbox_id)
+```
+
+## Command Execution & Cursor Logs
+
+- **Foreground**: `await client.execute(sandbox_id, "echo hello", workdir="/workspace", envs={"FOO": "bar"})`
+- **Background & Incremental Polling**:
+  ```python
+  cmd = await client.start_command(sandbox_id, "for i in 1 2 3; do echo $i; sleep 1; done")
+  logs = await client.poll_command(sandbox_id, cmd.id, cursor=0)
+  # Or stream until completion:
+  async for chunk in client.stream_command(sandbox_id, cmd.id):
+      print(chunk.content, end="")
+  ```
+
+## Files & Streaming Archive Sync
+
+```python
+await client.write_file(sandbox_id, "/workspace/hello.txt", "hello cubepod\n")
+
+# Stream large files incrementally
+stream = await client.stream_file(sandbox_id, "/workspace/hello.txt")
+async for chunk in stream:
+    print(chunk)
+
+# Atomic tar.gz directory sync into the sandbox
+await client.archive_sync(
+    sandbox_id,
+    {"app/main.py": "print('synced')\n"},
+    dest="/workspace",
+)
+```
+
+## Persistent Lifecycle, Reset & 1s CoW Fork
+
+CubePod decouples the container RootFS `upperdir` from `/workspace`:
+
+- `await client.pause(sandbox_id)` — suspend compute while retaining both RootFS Upper and Workspace block PVCs.
+- `await client.connect(sandbox_id)` — resume a paused sandbox automatically.
+- `await client.reset_rootfs(sandbox_id)` — wipe RootFS `upperdir` changes while keeping `/workspace` intact.
+- `await client.fork(sandbox_id)` — create a Copy-on-Write clone of both RootFS and Workspace volumes.
+
+## Zero-Trust `cpodref_` Egress
+
+Never inject raw API credentials into agent sandboxes. Pass `secret_bindings` with `cpodref_` placeholders at `create(...)` time; `cubepod-egress` swaps placeholders for real credentials over per-sandbox mTLS only when outbound requests leave the sandbox toward allowed target hosts.

cubepod-0.4.0/README.md

@@ -0,0 +1,76 @@
+# CubePod Python SDK
+
+Async-first Python client for **CubePod** — a persistent, writable-RootFS MicroVM execution platform for AI agents with an E2B-compatible Control & Data Plane API.
+
+## Installation
+
+```bash
+pip install cubepod
+```
+
+Requires Python 3.11+.
+
+## Quickstart (Async & Sync)
+
+```python
+import asyncio
+from cubepod import AsyncCubePod, CubePod
+
+async def main() -> None:
+    async with AsyncCubePod(base_url="http://localhost:8080", api_key="...") as client:
+        box = await client.create("cubeplex-ubuntu24-desktop")
+        res = await client.execute(box.sandbox_id, "python3 --version")
+        print(res.output)
+        await client.delete(box.sandbox_id)
+
+asyncio.run(main())
+
+# Synchronous client
+with CubePod(base_url="http://localhost:8080", api_key="...") as client:
+    box = client.create("cubeplex-ubuntu24-desktop")
+    print(client.execute(box.sandbox_id, "uname -a").output)
+    client.delete(box.sandbox_id)
+```
+
+## Command Execution & Cursor Logs
+
+- **Foreground**: `await client.execute(sandbox_id, "echo hello", workdir="/workspace", envs={"FOO": "bar"})`
+- **Background & Incremental Polling**:
+  ```python
+  cmd = await client.start_command(sandbox_id, "for i in 1 2 3; do echo $i; sleep 1; done")
+  logs = await client.poll_command(sandbox_id, cmd.id, cursor=0)
+  # Or stream until completion:
+  async for chunk in client.stream_command(sandbox_id, cmd.id):
+      print(chunk.content, end="")
+  ```
+
+## Files & Streaming Archive Sync
+
+```python
+await client.write_file(sandbox_id, "/workspace/hello.txt", "hello cubepod\n")
+
+# Stream large files incrementally
+stream = await client.stream_file(sandbox_id, "/workspace/hello.txt")
+async for chunk in stream:
+    print(chunk)
+
+# Atomic tar.gz directory sync into the sandbox
+await client.archive_sync(
+    sandbox_id,
+    {"app/main.py": "print('synced')\n"},
+    dest="/workspace",
+)
+```
+
+## Persistent Lifecycle, Reset & 1s CoW Fork
+
+CubePod decouples the container RootFS `upperdir` from `/workspace`:
+
+- `await client.pause(sandbox_id)` — suspend compute while retaining both RootFS Upper and Workspace block PVCs.
+- `await client.connect(sandbox_id)` — resume a paused sandbox automatically.
+- `await client.reset_rootfs(sandbox_id)` — wipe RootFS `upperdir` changes while keeping `/workspace` intact.
+- `await client.fork(sandbox_id)` — create a Copy-on-Write clone of both RootFS and Workspace volumes.
+
+## Zero-Trust `cpodref_` Egress
+
+Never inject raw API credentials into agent sandboxes. Pass `secret_bindings` with `cpodref_` placeholders at `create(...)` time; `cubepod-egress` swaps placeholders for real credentials over per-sandbox mTLS only when outbound requests leave the sandbox toward allowed target hosts.

cubepod-0.4.0/cubepod/__init__.py

@@ -0,0 +1,33 @@
+"""CubePod Python SDK — Sync & Async client for persistent MicroVM agent sandboxes."""
+
+from .async_client import AsyncCubePod
+from .exceptions import CubePodFileTooLargeError
+from .models import (
+    CommandInfo,
+    CommandLogs,
+    DesktopSession,
+    ExecutionResult,
+    FileEntry,
+    PanelEndpoint,
+    SandboxInfo,
+    _build_tar_gz_bytes,
+)
+from .sync_client import CubePod, SyncCubePod
+
+__version__ = "0.4.0"
+
+__all__ = [
+    "__version__",
+    "SandboxInfo",
+    "ExecutionResult",
+    "CommandInfo",
+    "CommandLogs",
+    "PanelEndpoint",
+    "FileEntry",
+    "DesktopSession",
+    "CubePodFileTooLargeError",
+    "_build_tar_gz_bytes",
+    "AsyncCubePod",
+    "CubePod",
+    "SyncCubePod",
+]

cubepod-0.4.0/cubepod/_helpers.py

@@ -0,0 +1,306 @@
+"""Shared payload builders and response parsers for sync and async CubePod clients."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any, cast
+
+import httpx
+
+from .models import (
+    CommandInfo,
+    CommandLogs,
+    DesktopSession,
+    ExecutionResult,
+    FileEntry,
+    PanelEndpoint,
+    SandboxInfo,
+    _build_tar_gz_bytes,
+)
+
+
+def _normalize_base_url(base_url: str) -> str:
+    normalized = base_url.strip().rstrip("/")
+    if normalized and not normalized.startswith(("http://", "https://")):
+        normalized = f"http://{normalized}"
+    return normalized
+
+
+def _json_dict(resp: httpx.Response) -> dict[str, Any]:
+    return cast(dict[str, Any], resp.json())
+
+
+def _json_list(resp: httpx.Response, wrapper_key: str) -> list[dict[str, Any]]:
+    data = resp.json()
+    if isinstance(data, list):
+        return cast(list[dict[str, Any]], data)
+    return cast(list[dict[str, Any]], data.get(wrapper_key, []))
+
+
+def _parse_info(data: dict[str, Any]) -> SandboxInfo:
+    raw_metadata = data.get("metadata")
+    metadata: dict[str, str] = (
+        {str(k): str(v) for k, v in raw_metadata.items()}
+        if isinstance(raw_metadata, dict)
+        else {}
+    )
+    envd_port_raw = data.get("envdPort")
+    rootfs_gen_raw = data.get("rootfsGeneration")
+    return SandboxInfo(
+        sandbox_id=str(data["sandboxID"]),
+        template_id=str(data["templateID"]),
+        state=str(data["state"]),
+        envd_port=int(envd_port_raw) if envd_port_raw is not None else 49983,
+        rootfs_generation=int(rootfs_gen_raw) if rootfs_gen_raw is not None else 1,
+        metadata=metadata,
+        raw=dict(data),
+    )
+
+
+def _parse_panel_endpoint(data: dict[str, Any]) -> PanelEndpoint:
+    return PanelEndpoint(
+        url=str(data["url"]),
+        token=str(data["token"]),
+        expires_at=str(data["expiresAt"]) if data.get("expiresAt") is not None else None,
+    )
+
+
+def _parse_desktop_session(data: dict[str, Any]) -> DesktopSession:
+    cdp_raw = data.get("cdpUrl") if "cdpUrl" in data else data.get("cdp_url")
+    expires_raw = data.get("expiresAt") if "expiresAt" in data else data.get("expires_at")
+    return DesktopSession(
+        status=str(data.get("status", "")),
+        desktop_url=str(data.get("desktopUrl") or data.get("desktop_url") or ""),
+        terminal_url=str(data.get("terminalUrl") or data.get("terminal_url") or ""),
+        cdp_url=str(cdp_raw) if cdp_raw is not None else None,
+        expires_at=str(expires_raw) if expires_raw is not None else None,
+    )
+
+
+def _parse_execution_result(data: dict[str, Any]) -> ExecutionResult:
+    exit_code = data.get("exit_code") if "exit_code" in data else data.get("exitCode")
+    output = data.get("output", "") or data.get("stdout", "")
+    cmd_id = data.get("id") or data.get("cmdID", "")
+    return ExecutionResult(
+        id=str(cmd_id),
+        exit_code=int(exit_code) if exit_code is not None else None,
+        output=str(output),
+        running=bool(data.get("running", False)),
+        pid=int(data["pid"]) if data.get("pid") is not None else None,
+        cursor=int(data.get("cursor", 0)),
+    )
+
+
+def _parse_command_info(
+    data: dict[str, Any],
+    *,
+    default_id: str = "",
+    default_running: bool = False,
+) -> CommandInfo:
+    cmd_id = data.get("id") or data.get("cmdID", default_id)
+    exit_code = data.get("exit_code") if "exit_code" in data else data.get("exitCode")
+    output = data.get("output", "") or data.get("stdout", "")
+    return CommandInfo(
+        id=str(cmd_id),
+        pid=int(data["pid"]) if data.get("pid") is not None else None,
+        running=bool(data.get("running", default_running)),
+        exit_code=int(exit_code) if exit_code is not None else None,
+        cursor=int(data.get("cursor", 0)),
+        output=str(output),
+    )
+
+
+def _parse_command_logs(
+    data: dict[str, Any],
+    *,
+    command_id: str,
+    default_cursor: int,
+) -> CommandLogs:
+    cmd_id = data.get("id") or data.get("cmdID", command_id)
+    exit_code = data.get("exit_code") if "exit_code" in data else data.get("exitCode")
+    return CommandLogs(
+        id=str(cmd_id),
+        content=str(data.get("content", "")),
+        cursor=int(data.get("cursor", default_cursor)),
+        running=bool(data.get("running", False)),
+        exit_code=int(exit_code) if exit_code is not None else None,
+    )
+
+
+def _parse_file_entries(data: Any) -> list[FileEntry]:
+    entries = data if isinstance(data, list) else data.get("entries", [])
+    result: list[FileEntry] = []
+    for e in entries:
+        raw_mod = e.get("modified_at") or e.get("modifiedAt") or e.get("mtime")
+        result.append(
+            FileEntry(
+                name=str(e.get("name", "")),
+                path=str(e.get("path", "")),
+                is_dir=bool(e.get("is_dir", False)),
+                size=int(e.get("size", 0)),
+                mode=str(e.get("mode", "0644")),
+                modified_at=str(raw_mod) if raw_mod is not None else None,
+            )
+        )
+    return result
+
+
+def _build_create_payload(
+    template_id: str,
+    *,
+    volume_key: str | None = None,
+    metadata: dict[str, str] | None = None,
+    network_policy: dict[str, Any] | None = None,
+    secret_bindings: list[dict[str, Any]] | None = None,
+    timeout_seconds: int | None = None,
+    warm_pool_ref: str | None = None,
+    resource: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    payload: dict[str, Any] = {"templateID": template_id, "metadata": metadata or {}}
+    if timeout_seconds is not None:
+        payload["timeoutSeconds"] = timeout_seconds
+
+    ext: dict[str, Any] = {}
+    if volume_key:
+        ext["volumeKey"] = volume_key
+    if warm_pool_ref:
+        ext["warmPoolRef"] = warm_pool_ref
+    if resource:
+        ext["resource"] = resource
+    if ext:
+        payload["extension"] = ext
+
+    if network_policy is not None:
+        payload["networkPolicy"] = dict(network_policy)
+    if secret_bindings is not None:
+        if "networkPolicy" not in payload:
+            payload["networkPolicy"] = {}
+        payload["networkPolicy"]["secretBindings"] = secret_bindings
+    return payload
+
+
+def _build_fork_payload(
+    *,
+    volume_key: str | None = None,
+    metadata: dict[str, str] | None = None,
+) -> dict[str, Any] | None:
+    payload: dict[str, Any] = {}
+    if metadata is not None:
+        payload["metadata"] = metadata
+    if volume_key:
+        payload["extension"] = {"volumeKey": volume_key}
+    return payload or None
+
+
+def _build_command_payload(
+    command: str,
+    *,
+    background: bool,
+    workdir: str | None = None,
+    envs: dict[str, str] | None = None,
+    uid: int | None = 1000,
+    gid: int | None = 1000,
+) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "command": command,
+        "background": background,
+    }
+    if uid is not None:
+        payload["uid"] = uid
+    if gid is not None:
+        payload["gid"] = gid
+    if workdir is not None:
+        payload["workdir"] = workdir
+    if envs is not None:
+        payload["envs"] = envs
+    return payload
+
+
+def _build_archive_sync_request(
+    files: dict[str, str | bytes] | bytes,
+    *,
+    dest: str = "/workspace",
+    uid: int | None = None,
+    gid: int | None = None,
+    remove_paths: Sequence[str] | None = None,
+) -> tuple[bytes, dict[str, str]]:
+    if isinstance(files, (bytes, bytearray)):
+        tar_bytes = bytes(files)
+    else:
+        tar_bytes = _build_tar_gz_bytes(
+            files,
+            uid=uid if uid is not None else 1000,
+            gid=gid if gid is not None else 1000,
+        )
+    params: dict[str, str] = {"dest": dest}
+    if uid is not None:
+        params["uid"] = str(uid)
+    if gid is not None:
+        params["gid"] = str(gid)
+    if remove_paths:
+        joined = ",".join(p for p in remove_paths if p)
+        if joined:
+            params["remove_paths"] = joined
+    return tar_bytes, params
+
+
+def _build_desktop_start_payload(
+    *,
+    resolution: str | None = None,
+    initial_url: str | None = None,
+    expires_in_seconds: int = 3600,
+) -> dict[str, Any]:
+    payload: dict[str, Any] = {"expiresInSeconds": expires_in_seconds}
+    if resolution is not None:
+        payload["resolution"] = resolution
+    if initial_url is not None:
+        payload["initialUrl"] = initial_url
+    return payload
+
+
+def _build_template_register_payload(
+    *,
+    name: str | None,
+    alias: str | None,
+    tags: list[str] | None,
+    cpu_count: int | None,
+    memory_mb: int | None,
+    min_free_disk_mb: int | None,
+) -> dict[str, Any]:
+    payload: dict[str, Any] = {}
+    if name is not None:
+        payload["name"] = name
+    if alias is not None:
+        payload["alias"] = alias
+    if tags is not None:
+        payload["tags"] = tags
+    if cpu_count is not None:
+        payload["cpuCount"] = cpu_count
+    if memory_mb is not None:
+        payload["memoryMB"] = memory_mb
+    if min_free_disk_mb is not None:
+        payload["minFreeDiskMb"] = min_free_disk_mb
+    return payload
+
+
+def _build_template_result(created: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "templateID": str(created.get("templateID", "")),
+        "buildID": str(created.get("buildID", "")),
+        "aliases": created.get("aliases", []),
+        "names": created.get("names", []),
+        "tags": created.get("tags", []),
+    }
+
+
+def _format_build_error(build_id: str, reason: Any) -> str:
+    if isinstance(reason, dict):
+        msg = reason.get("message") or str(reason)
+        step = reason.get("step")
+        if step:
+            msg = f"{msg} (step: {step})"
+    elif reason:
+        msg = str(reason)
+    else:
+        msg = "unknown build error"
+    return f"Template build {build_id} failed: {msg}"