sandforge-sdk 0.1.0__py3-none-any.whl

sandforge/__init__.py

@@ -0,0 +1,66 @@
+"""Sandforge Python SDK.
+
+A client library for interacting with the Sandforge hypervisor sandbox platform.
+
+Example:
+    from sandforge import Client, SandboxSpec
+
+    # Create a client
+    client = Client("http://localhost:8080")
+
+    # Create a sandbox
+    sandbox = client.create_sandbox(SandboxSpec(cpu=2, memory_mb=512))
+
+    # Run a command
+    result = sandbox.commands.run(["echo", "Hello, Sandforge!"])
+    print(result.stdout)
+
+    # Get sandbox info
+    info = sandbox.info()
+    print(f"Sandbox {info.id} is {info.state}")
+
+    # Clean up
+    sandbox.kill()
+"""
+
+from .client import Client, SandboxHandle, CommandsAPI, FilesAPI, GitAPI
+
+# Alias for cleaner ergonomics
+Sandbox = SandboxHandle
+from .types import (
+    SandboxSpec,
+    WorkspaceMount,
+    ExecRequest,
+    ExecResult,
+    SandboxInfo,
+    EntryInfo,
+    GitStatus,
+    SandforgeException,
+    SandboxNotFoundError,
+    ExecutionError,
+    NetworkError,
+    InvalidSpecError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Client",
+    "Sandbox",
+    "SandboxHandle",
+    "CommandsAPI",
+    "FilesAPI",
+    "GitAPI",
+    "SandboxSpec",
+    "WorkspaceMount",
+    "ExecRequest",
+    "ExecResult",
+    "SandboxInfo",
+    "EntryInfo",
+    "GitStatus",
+    "SandforgeException",
+    "SandboxNotFoundError",
+    "ExecutionError",
+    "NetworkError",
+    "InvalidSpecError",
+]

sandforge/client.py

@@ -0,0 +1,448 @@
+"""HTTP client for communicating with the Sandforge control plane."""
+
+import json
+import secrets
+from typing import Dict, Any, Optional
+import requests
+
+from .types import (
+    SandboxSpec,
+    ExecRequest,
+    ExecResult,
+    SandboxInfo,
+    EntryInfo,
+    GitStatus,
+    SandforgeException,
+    NetworkError,
+    SandboxNotFoundError,
+)
+
+
+class Client:
+    """Sandforge control plane HTTP client.
+
+    Example:
+        client = Client("http://localhost:8080")
+        sandbox = client.create_sandbox(SandboxSpec())
+        result = client.exec(sandbox.id, ExecRequest(command=["echo", "hello"]))
+    """
+
+    def __init__(self, base_url: str, timeout: int = 60):
+        """Initialize the Sandforge client.
+
+        Args:
+            base_url: The control plane base URL (e.g., "http://localhost:8080").
+            timeout: Request timeout in seconds.
+        """
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.session = requests.Session()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.session.close()
+        return False
+
+    def close(self) -> None:
+        """Close the underlying HTTP session."""
+        self.session.close()
+
+    def create_sandbox(self, spec: Optional[SandboxSpec] = None) -> "SandboxHandle":
+        """Create a new sandbox.
+
+        Args:
+            spec: SandboxSpec for the sandbox. If None, uses defaults.
+
+        Returns:
+            SandboxHandle: A handle to the created sandbox.
+
+        Raises:
+            NetworkError: If communication with the control plane fails.
+            SandforgeException: If sandbox creation fails.
+        """
+        if spec is None:
+            spec = SandboxSpec()
+
+        sandbox_id = self._generate_id()
+        payload = {
+            "id": sandbox_id,
+            "spec": spec.to_dict(),
+        }
+
+        response = self._do("POST", "/v1/sandboxes", payload)
+        return SandboxHandle(self, response.get("id", sandbox_id))
+
+    def exec(self, sandbox_id: str, request: ExecRequest) -> ExecResult:
+        """Execute a command in a sandbox.
+
+        Args:
+            sandbox_id: The sandbox ID.
+            request: The execution request.
+
+        Returns:
+            ExecResult: The command execution result.
+
+        Raises:
+            NetworkError: If communication with the control plane fails.
+            SandforgeException: If execution fails.
+        """
+        payload = request.to_dict()
+        response = self._do("POST", f"/v1/sandboxes/{sandbox_id}/exec", payload)
+        return ExecResult.from_dict(response)
+
+    def get_status(self, sandbox_id: str) -> str:
+        """Get the current state of a sandbox.
+
+        Args:
+            sandbox_id: The sandbox ID.
+
+        Returns:
+            str: The sandbox state (e.g., "ready", "executing", "destroyed").
+
+        Raises:
+            NetworkError: If communication with the control plane fails.
+            SandboxNotFoundError: If the sandbox is not found.
+        """
+        response = self._do("GET", f"/v1/sandboxes/{sandbox_id}", None)
+        return response.get("state", "unknown")
+
+    def get_info(self, sandbox_id: str) -> SandboxInfo:
+        """Get detailed information about a sandbox.
+
+        Args:
+            sandbox_id: The sandbox ID.
+
+        Returns:
+            SandboxInfo: Information about the sandbox.
+
+        Raises:
+            NetworkError: If communication with the control plane fails.
+            SandboxNotFoundError: If the sandbox is not found.
+        """
+        response = self._do("GET", f"/v1/sandboxes/{sandbox_id}", None)
+        return SandboxInfo.from_dict(response)
+
+    def destroy(self, sandbox_id: str) -> None:
+        """Destroy a sandbox.
+
+        Args:
+            sandbox_id: The sandbox ID.
+
+        Raises:
+            NetworkError: If communication with the control plane fails.
+            SandforgeException: If destruction fails.
+        """
+        self._do("DELETE", f"/v1/sandboxes/{sandbox_id}", None)
+
+    # ─── Private Methods ───────────────────────────────────────────────────────
+
+    def _do(self, method: str, path: str, body: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+        """Execute an HTTP request to the control plane.
+
+        Args:
+            method: HTTP method (GET, POST, DELETE, etc.).
+            path: API path (e.g., "/v1/sandboxes").
+            body: Request body (or None for GET/DELETE).
+
+        Returns:
+            dict: Parsed JSON response.
+
+        Raises:
+            NetworkError: If the request fails.
+            SandboxNotFoundError: If the resource is not found.
+            SandforgeException: If the response indicates an error.
+        """
+        url = self.base_url + path
+        headers = {"Content-Type": "application/json"}
+
+        try:
+            if method == "GET":
+                resp = self.session.get(url, headers=headers, timeout=self.timeout)
+            elif method == "POST":
+                resp = self.session.post(
+                    url, json=body, headers=headers, timeout=self.timeout
+                )
+            elif method == "PUT":
+                resp = self.session.put(
+                    url, json=body, headers=headers, timeout=self.timeout
+                )
+            elif method == "DELETE":
+                resp = self.session.delete(url, headers=headers, timeout=self.timeout)
+            else:
+                raise ValueError(f"Unsupported HTTP method: {method}")
+
+        except requests.RequestException as e:
+            raise NetworkError(f"Request failed: {e}") from e
+
+        # Handle error responses
+        if resp.status_code >= 400:
+            self._handle_error_response(resp)
+
+        # Parse response body
+        if resp.text:
+            try:
+                return resp.json()
+            except json.JSONDecodeError as e:
+                raise SandforgeException(f"Invalid JSON response: {e}") from e
+        return {}
+
+    def _handle_error_response(self, resp: requests.Response) -> None:
+        """Parse and raise an appropriate exception from an error response.
+
+        Args:
+            resp: The HTTP response object.
+
+        Raises:
+            SandboxNotFoundError: If the resource is not found (404).
+            SandforgeException: For other error responses.
+        """
+        status = resp.status_code
+        try:
+            error_data = resp.json()
+            error_msg = error_data.get("error", "Unknown error")
+        except json.JSONDecodeError:
+            error_msg = resp.text or f"HTTP {status}"
+
+        if status == 404:
+            raise SandboxNotFoundError(f"Sandbox not found: {error_msg}")
+        else:
+            raise SandforgeException(f"HTTP {status}: {error_msg}")
+
+    @staticmethod
+    def _generate_id() -> str:
+        """Generate a unique sandbox ID.
+
+        Returns:
+            str: A sandbox ID in the form "sbx-<hex>".
+        """
+        random_bytes = secrets.token_hex(8)
+        return f"sbx-{random_bytes}"
+
+
+class SandboxHandle:
+    """A handle to a sandbox, providing convenient command and file operations.
+
+    Example:
+        sandbox = client.create_sandbox()
+        result = sandbox.commands.run(["echo", "hello"])
+        content = sandbox.files.read("/etc/hostname")
+        sandbox.kill()
+        info = sandbox.info()
+    """
+
+    def __init__(self, client: Client, sandbox_id: str):
+        """Initialize a sandbox handle.
+
+        Args:
+            client: The Sandforge client.
+            sandbox_id: The sandbox ID.
+        """
+        self.id = sandbox_id
+        self._client = client
+        self.commands = CommandsAPI(self)
+        self.files = FilesAPI(self)
+        self.git = GitAPI(self)
+
+    def kill(self) -> None:
+        """Destroy the sandbox.
+
+        Raises:
+            NetworkError: If communication with the control plane fails.
+        """
+        self._client.destroy(self.id)
+
+    def info(self) -> SandboxInfo:
+        """Get information about the sandbox.
+
+        Returns:
+            SandboxInfo: Current sandbox state and ID.
+
+        Raises:
+            NetworkError: If communication with the control plane fails.
+        """
+        return self._client.get_info(self.id)
+
+
+class CommandsAPI:
+    """Commands API for executing commands in a sandbox."""
+
+    def __init__(self, sandbox: SandboxHandle):
+        """Initialize the commands API.
+
+        Args:
+            sandbox: The parent SandboxHandle.
+        """
+        self._sandbox = sandbox
+
+    def run(
+        self,
+        command: list,
+        cwd: str = "/",
+        env: Optional[Dict[str, str]] = None,
+        timeout_sec: int = 60,
+    ) -> ExecResult:
+        """Run a command in the sandbox.
+
+        Args:
+            command: Command and arguments as a list (e.g., ["echo", "hello"]).
+            cwd: Working directory for the command (default: "/").
+            env: Environment variables as a dict (default: empty).
+            timeout_sec: Command timeout in seconds (default: 60).
+
+        Returns:
+            ExecResult: Command execution result with exit code, stdout, stderr.
+
+        Raises:
+            NetworkError: If communication with the control plane fails.
+            SandforgeException: If execution fails.
+        """
+        if env is None:
+            env = {}
+
+        request = ExecRequest(
+            command=command,
+            cwd=cwd,
+            env=env,
+            timeout_sec=timeout_sec,
+        )
+        return self._sandbox._client.exec(self._sandbox.id, request)
+
+
+class FilesAPI:
+    """Files API for filesystem operations inside a sandbox."""
+
+    def __init__(self, sandbox: "SandboxHandle"):
+        self._sandbox = sandbox
+
+    def read(self, path: str, as_bytes: bool = False):
+        """Read a file from the sandbox.
+
+        Args:
+            path: Path to the file inside the sandbox.
+            as_bytes: If True, return raw bytes. Default returns str.
+
+        Returns:
+            str or bytes: File contents.
+        """
+        resp = self._sandbox._client._do(
+            "GET", f"/v1/sandboxes/{self._sandbox.id}/files/read?path={path}", None
+        )
+        data = bytes(resp.get("data", []))
+        return data if as_bytes else data.decode()
+
+    def write(self, path: str, data) -> int:
+        """Write data to a file inside the sandbox.
+
+        Args:
+            path: Destination path inside the sandbox.
+            data: str or bytes to write.
+
+        Returns:
+            int: Number of bytes written.
+        """
+        if isinstance(data, str):
+            data = data.encode()
+        payload = {"guest_path": path, "data": list(data)}
+        resp = self._sandbox._client._do(
+            "PUT", f"/v1/sandboxes/{self._sandbox.id}/files", payload
+        )
+        return resp.get("size", 0)
+
+    def list(self, path: str) -> list:
+        """List directory contents inside the sandbox.
+
+        Args:
+            path: Directory path inside the sandbox.
+
+        Returns:
+            List[EntryInfo]: Directory entries.
+        """
+        resp = self._sandbox._client._do(
+            "GET", f"/v1/sandboxes/{self._sandbox.id}/files?path={path}", None
+        )
+        return [EntryInfo.from_dict(e) for e in resp.get("entries", [])]
+
+    def stat(self, path: str) -> EntryInfo:
+        """Return metadata for a path inside the sandbox.
+
+        Args:
+            path: Path inside the sandbox.
+
+        Returns:
+            EntryInfo: Metadata for the path.
+        """
+        resp = self._sandbox._client._do(
+            "GET", f"/v1/sandboxes/{self._sandbox.id}/stat?path={path}", None
+        )
+        return EntryInfo.from_dict(resp)
+
+    def exists(self, path: str) -> bool:
+        """Return True if the path exists inside the sandbox."""
+        try:
+            self.stat(path)
+            return True
+        except SandforgeException:
+            return False
+
+    def remove(self, path: str) -> ExecResult:
+        """Delete a file or directory inside the sandbox via `rm -rf`."""
+        return self._sandbox._client.exec(
+            self._sandbox.id,
+            ExecRequest(command=["rm", "-rf", path], cwd="/", timeout_sec=30),
+        )
+
+
+class GitAPI:
+    """Git API — shell facade over `commands.run()` for common git operations."""
+
+    def __init__(self, sandbox: "SandboxHandle"):
+        self._sandbox = sandbox
+
+    def _exec(self, args: list, cwd: str = "/") -> ExecResult:
+        return self._sandbox._client.exec(
+            self._sandbox.id,
+            ExecRequest(command=["git"] + args, cwd=cwd, timeout_sec=120),
+        )
+
+    def clone(self, url: str, dest: str = ".", depth: Optional[int] = None) -> ExecResult:
+        args = ["clone"]
+        if depth:
+            args += ["--depth", str(depth)]
+        args += [url, dest]
+        return self._exec(args)
+
+    def init(self, cwd: str) -> ExecResult:
+        return self._exec(["init"], cwd)
+
+    def add(self, paths, cwd: str) -> ExecResult:
+        if isinstance(paths, str):
+            paths = [paths]
+        return self._exec(["add"] + paths, cwd)
+
+    def commit(self, message: str, cwd: str) -> ExecResult:
+        return self._exec(["commit", "-m", message], cwd)
+
+    def push(self, cwd: str, remote: str = "origin", branch: str = "HEAD") -> ExecResult:
+        return self._exec(["push", remote, branch], cwd)
+
+    def pull(self, cwd: str, remote: str = "origin") -> ExecResult:
+        return self._exec(["pull", remote], cwd)
+
+    def status(self, cwd: str) -> GitStatus:
+        branch_result = self._exec(["rev-parse", "--abbrev-ref", "HEAD"], cwd)
+        status_result = self._exec(["status", "--porcelain"], cwd)
+        return GitStatus(
+            branch=branch_result.stdout.strip(),
+            clean=status_result.stdout.strip() == "",
+            stdout=status_result.stdout,
+        )
+
+    def branches(self, cwd: str) -> list:
+        result = self._exec(["branch", "--list"], cwd)
+        return [
+            b.lstrip("* ").strip()
+            for b in result.stdout.splitlines()
+            if b.strip()
+        ]

sandforge/types.py

@@ -0,0 +1,146 @@
+"""Type definitions for the Sandforge Python SDK."""
+
+from dataclasses import dataclass, field, asdict
+from typing import Dict, List, Optional, Any
+
+
+@dataclass
+class WorkspaceMount:
+    """Represents a mount point for a workspace directory."""
+
+    host_path: str
+    guest_path: str
+    read_only: bool = False
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return asdict(self)
+
+
+@dataclass
+class SandboxSpec:
+    """Specification for creating a sandbox."""
+
+    backend: str = "macos-vz"  # "linux-kvm", "linux-firecracker", "macos-vz"
+    cpu: int = 2
+    memory_mb: int = 512
+    disk_gb: int = 10
+    timeout_sec: int = 3600
+    network_mode: str = "offline"  # "offline", "fetch", "full"
+    task_isolation: str = "container"  # "container", "process"
+    mounts: List[WorkspaceMount] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return asdict(self)
+
+
+@dataclass
+class ExecRequest:
+    """Request to execute a command in a sandbox."""
+
+    command: List[str]
+    cwd: str = "/"
+    env: Dict[str, str] = field(default_factory=dict)
+    timeout_sec: int = 60
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return asdict(self)
+
+
+@dataclass
+class ExecResult:
+    """Result of executing a command in a sandbox."""
+
+    exit_code: int
+    stdout: str
+    stderr: str
+    artifacts: List[str] = field(default_factory=list)
+
+    @staticmethod
+    def from_dict(data: Dict[str, Any]) -> "ExecResult":
+        """Create from dictionary returned by API."""
+        return ExecResult(
+            exit_code=data.get("exit_code", 0),
+            stdout=data.get("stdout", ""),
+            stderr=data.get("stderr", ""),
+            artifacts=data.get("artifacts", []),
+        )
+
+
+@dataclass
+class SandboxInfo:
+    """Information about a sandbox's current state."""
+
+    id: str
+    state: str
+
+    @staticmethod
+    def from_dict(data: Dict[str, Any]) -> "SandboxInfo":
+        """Create from dictionary returned by API."""
+        return SandboxInfo(
+            id=data.get("id", ""),
+            state=data.get("state", ""),
+        )
+
+
+@dataclass
+class EntryInfo:
+    """Metadata for a single filesystem entry inside a sandbox."""
+
+    name: str
+    path: str
+    size: int
+    is_dir: bool
+    mod_time: str
+
+    @staticmethod
+    def from_dict(data: Dict[str, Any]) -> "EntryInfo":
+        return EntryInfo(
+            name=data.get("name", ""),
+            path=data.get("path", ""),
+            size=data.get("size", 0),
+            is_dir=data.get("isDir", False),
+            mod_time=data.get("modTime", ""),
+        )
+
+
+@dataclass
+class GitStatus:
+    """Result of `git status` inside a sandbox."""
+
+    branch: str
+    clean: bool
+    stdout: str
+
+
+# Custom exceptions
+class SandforgeException(Exception):
+    """Base exception for Sandforge SDK."""
+
+    pass
+
+
+class SandboxNotFoundError(SandforgeException):
+    """Raised when a sandbox is not found."""
+
+    pass
+
+
+class ExecutionError(SandforgeException):
+    """Raised when command execution fails."""
+
+    pass
+
+
+class NetworkError(SandforgeException):
+    """Raised when there's a network error communicating with the control plane."""
+
+    pass
+
+
+class InvalidSpecError(SandforgeException):
+    """Raised when sandbox specification is invalid."""
+
+    pass

sandforge_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,391 @@
+Metadata-Version: 2.4
+Name: sandforge-sdk
+Version: 0.1.0
+Summary: Python SDK for Sandforge hypervisor sandbox platform
+Home-page: https://github.com/yanurag-dev/sandforge
+Author: Anurag Yadav
+Author-email: Anurag Yadav <yadavanurag1310@gmail.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/yanurag-dev/sandforge
+Project-URL: Repository, https://github.com/yanurag-dev/sandforge
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.33.0
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-cov>=2.10; extra == "dev"
+Requires-Dist: black>=21.0; extra == "dev"
+Requires-Dist: mypy>=0.910; extra == "dev"
+Requires-Dist: flake8>=3.9; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: requires-python
+
+# Sandforge Python SDK
+
+The Sandforge Python SDK provides a client library for interacting with the Sandforge hypervisor sandbox platform. It enables you to create, manage, and execute commands in isolated sandboxes programmatically.
+
+## Installation
+
+Install the SDK from the repository:
+
+```bash
+pip install -e .
+```
+
+Or with development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from sandforge import Client, SandboxSpec
+
+# Create a client pointing to your Sandforge control plane
+client = Client("http://localhost:8080")
+
+# Create a sandbox with default configuration
+sandbox = client.create_sandbox()
+
+# Run a command
+result = sandbox.commands.run(["echo", "Hello, Sandforge!"])
+print(result.stdout)  # "Hello, Sandforge!\n"
+
+# Clean up
+sandbox.kill()
+```
+
+### Custom Sandbox Configuration
+
+```python
+from sandforge import Client, SandboxSpec, WorkspaceMount
+
+spec = SandboxSpec(
+    cpu=4,
+    memory_mb=2048,
+    disk_gb=20,
+    timeout_sec=3600,
+    network_mode="fetch",  # Allow package downloads
+    mounts=[
+        WorkspaceMount(
+            host_path="/path/to/project",
+            guest_path="/workspace",
+            read_only=False,
+        ),
+    ],
+)
+
+client = Client("http://localhost:8080")
+sandbox = client.create_sandbox(spec)
+
+# Work with the mounted directory
+result = sandbox.commands.run(["ls", "-la", "/workspace"])
+print(result.stdout)
+
+sandbox.kill()
+```
+
+### Command Execution with Environment Variables
+
+```python
+from sandforge import Client
+
+client = Client("http://localhost:8080")
+sandbox = client.create_sandbox()
+
+# Run with custom environment variables
+result = sandbox.commands.run(
+    command=["python", "-c", "import os; print(os.environ.get('MY_VAR'))"],
+    cwd="/",
+    env={"MY_VAR": "Hello World"},
+    timeout_sec=30,
+)
+
+print(result.stdout)   # "Hello World\n"
+print(result.exit_code)  # 0
+
+sandbox.kill()
+```
+
+### Error Handling
+
+```python
+from sandforge import Client, NetworkError, SandboxNotFoundError
+
+client = Client("http://localhost:8080")
+
+try:
+    sandbox = client.create_sandbox()
+    result = sandbox.commands.run(["false"])  # Command that fails
+    
+    if result.exit_code != 0:
+        print(f"Command failed with exit code {result.exit_code}")
+        print(f"stderr: {result.stderr}")
+    
+    sandbox.kill()
+    
+except NetworkError as e:
+    print(f"Connection error: {e}")
+except SandboxNotFoundError as e:
+    print(f"Sandbox not found: {e}")
+```
+
+### Sandbox Information
+
+```python
+from sandforge import Client
+
+client = Client("http://localhost:8080")
+sandbox = client.create_sandbox()
+
+# Get sandbox information
+info = sandbox.info()
+print(f"Sandbox ID: {info.id}")
+print(f"State: {info.state}")  # "ready", "executing", "destroyed", etc.
+```
+
+## API Reference
+
+### Client
+
+The main entry point for interacting with Sandforge.
+
+#### Constructor
+
+```python
+Client(base_url: str, timeout: int = 60)
+```
+
+- `base_url`: The control plane URL (e.g., "http://localhost:8080")
+- `timeout`: Request timeout in seconds (default: 60)
+
+#### Methods
+
+##### `create_sandbox(spec: Optional[SandboxSpec] = None) -> SandboxHandle`
+
+Create a new sandbox.
+
+- Returns: A `SandboxHandle` to the created sandbox
+- Raises: `NetworkError` or `SandforgeException`
+
+##### `exec(sandbox_id: str, request: ExecRequest) -> ExecResult`
+
+Execute a command in a sandbox.
+
+- Returns: An `ExecResult` with exit code, stdout, and stderr
+- Raises: `NetworkError` or `SandforgeException`
+
+##### `get_status(sandbox_id: str) -> str`
+
+Get the current state of a sandbox.
+
+- Returns: The sandbox state as a string
+- Raises: `NetworkError`
+
+##### `get_info(sandbox_id: str) -> SandboxInfo`
+
+Get detailed information about a sandbox.
+
+- Returns: A `SandboxInfo` object
+- Raises: `NetworkError`
+
+##### `destroy(sandbox_id: str) -> None`
+
+Destroy a sandbox.
+
+- Raises: `NetworkError` or `SandforgeException`
+
+### SandboxHandle
+
+A handle to a created sandbox with convenience APIs.
+
+#### Properties
+
+- `id`: The sandbox ID (string)
+
+#### Methods
+
+##### `kill() -> None`
+
+Destroy the sandbox.
+
+```python
+sandbox.kill()
+```
+
+##### `info() -> SandboxInfo`
+
+Get sandbox information.
+
+```python
+info = sandbox.info()
+```
+
+#### Nested APIs
+
+##### `commands`
+
+The `CommandsAPI` for executing commands.
+
+###### `run(command, cwd="/", env=None, timeout_sec=60) -> ExecResult`
+
+Run a command in the sandbox.
+
+- `command`: List of command and arguments
+- `cwd`: Working directory (default: "/")
+- `env`: Dictionary of environment variables (default: {})
+- `timeout_sec`: Command timeout in seconds (default: 60)
+- Returns: `ExecResult` with exit code, stdout, and stderr
+
+```python
+result = sandbox.commands.run(
+    ["python", "script.py"],
+    cwd="/workspace",
+    env={"PYTHONUNBUFFERED": "1"},
+    timeout_sec=300,
+)
+```
+
+##### `files`
+
+The `FilesAPI` for reading files from the sandbox.
+
+###### `read(path: str) -> str`
+
+Read a file from the sandbox.
+
+**Note:** This method is currently not implemented and raises `NotImplementedError`. VSOCK copyout support is coming soon.
+
+```python
+try:
+    content = sandbox.files.read("/etc/hostname")
+except NotImplementedError:
+    print("files.read() not yet supported")
+```
+
+### Types
+
+#### SandboxSpec
+
+Specification for creating a sandbox.
+
+```python
+SandboxSpec(
+    backend: str = "macos-vz",        # "linux-kvm", "linux-firecracker", "macos-vz"
+    cpu: int = 2,                      # Number of vCPUs
+    memory_mb: int = 512,              # Memory in MB
+    disk_gb: int = 10,                 # Disk size in GB
+    timeout_sec: int = 3600,           # Sandbox lifetime in seconds
+    network_mode: str = "offline",     # "offline", "fetch", "full"
+    task_isolation: str = "container", # "container", "process"
+    mounts: List[WorkspaceMount] = [], # Mounted directories
+)
+```
+
+#### WorkspaceMount
+
+A directory mount from host to guest.
+
+```python
+WorkspaceMount(
+    host_path: str,   # Path on the host
+    guest_path: str,  # Path in the sandbox
+    read_only: bool = False,  # Whether the mount is read-only
+)
+```
+
+#### ExecRequest
+
+A request to execute a command.
+
+```python
+ExecRequest(
+    command: List[str],              # Command and arguments
+    cwd: str = "/",                  # Working directory
+    env: Dict[str, str] = {},        # Environment variables
+    timeout_sec: int = 60,           # Timeout in seconds
+)
+```
+
+#### ExecResult
+
+The result of command execution.
+
+```python
+ExecResult(
+    exit_code: int,              # Command exit code
+    stdout: str,                 # Standard output
+    stderr: str,                 # Standard error
+    artifacts: List[str] = [],   # Paths to generated artifacts
+)
+```
+
+#### SandboxInfo
+
+Information about a sandbox.
+
+```python
+SandboxInfo(
+    id: str,     # Sandbox ID
+    state: str,  # Current state (e.g., "ready", "executing", "destroyed")
+)
+```
+
+### Exceptions
+
+All exceptions inherit from `SandforgeException`.
+
+- **SandforgeException**: Base exception for all Sandforge errors
+- **NetworkError**: Network communication error with the control plane
+- **SandboxNotFoundError**: Sandbox does not exist
+- **ExecutionError**: Command execution failed
+- **InvalidSpecError**: Invalid sandbox specification
+
+## Error Handling
+
+The SDK provides specific exception types for different error scenarios:
+
+```python
+from sandforge import Client, NetworkError, SandboxNotFoundError, SandforgeException
+
+client = Client("http://localhost:8080")
+
+try:
+    sandbox = client.create_sandbox()
+    result = sandbox.commands.run(["exit", "1"])
+except NetworkError as e:
+    print(f"Network error: {e}")
+except SandboxNotFoundError as e:
+    print(f"Sandbox not found: {e}")
+except SandforgeException as e:
+    print(f"Sandforge error: {e}")
+```
+
+## Running Tests
+
+```bash
+pip install -e ".[dev]"
+pytest tests/
+```
+
+## Contributing
+
+Contributions are welcome! Please ensure code passes linting and type checks:
+
+```bash
+black sandforge/
+flake8 sandforge/
+mypy sandforge/
+```
+
+## License
+
+Apache License 2.0. See LICENSE in the repository root for details.

sandforge_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+sandforge/__init__.py,sha256=sGjKIZiKJYt-LnvnbervLuC0_Xvm2T-qQ7yx5o9sL2M,1342
+sandforge/client.py,sha256=AOxkAK742M-1PsWIxPlv6d3eiRGA-m0mDXb1cCqVJ5I,14150
+sandforge/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sandforge/types.py,sha256=3yuBRUl9zTc9k98_Ij-ClbK8gqA6x6zTpDbXxOkF4dE,3446
+tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tests/test_client.py,sha256=D81VzkRfdGCRF_fLWXrkzJ5qIcV8EuvoCQPN_Ei_meI,11886
+sandforge_sdk-0.1.0.dist-info/METADATA,sha256=NWVgoiJ-KZ_tKtGLEUpnljvOnaDy37V-BM6DF4CKeYY,8994
+sandforge_sdk-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+sandforge_sdk-0.1.0.dist-info/top_level.txt,sha256=b_lOeCG9LvqlW9TuzheYA4Nu6K_yuN6Lx9XwKcVpzQI,16
+sandforge_sdk-0.1.0.dist-info/RECORD,,

sandforge_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sandforge_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+sandforge
+tests

tests/test_client.py

@@ -0,0 +1,313 @@
+"""Unit tests for the Sandforge Python SDK client."""
+
+import unittest
+import sys
+import os
+from unittest.mock import MagicMock
+
+# Allow running tests from the sdks/python directory without installing the package.
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+# Stub the `requests` module so tests run without installing it.
+_requests_stub = MagicMock()
+sys.modules.setdefault("requests", _requests_stub)
+
+from sandforge import Client, SandboxHandle, Sandbox
+from sandforge.types import ExecResult, SandboxInfo, SandboxSpec
+
+
+class TestClientCreateSandbox(unittest.TestCase):
+    """Tests for Client.create_sandbox()."""
+
+    def _make_client(self):
+        client = Client("http://localhost:8080")
+        client.session = MagicMock()
+        return client
+
+    def test_create_sandbox_posts_to_v1_sandboxes(self):
+        """create_sandbox() should POST to /v1/sandboxes and return a SandboxHandle."""
+        client = self._make_client()
+
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.text = '{"id": "sbx-abc123"}'
+        mock_response.json.return_value = {"id": "sbx-abc123"}
+        client.session.post.return_value = mock_response
+
+        handle = client.create_sandbox(SandboxSpec())
+
+        # Verify POST was called with the right URL
+        call_args = client.session.post.call_args
+        self.assertIn("/v1/sandboxes", call_args[0][0])
+
+        # Verify the returned handle has the right ID
+        self.assertIsInstance(handle, SandboxHandle)
+        self.assertEqual(handle.id, "sbx-abc123")
+
+    def test_create_sandbox_uses_default_spec_when_none(self):
+        """create_sandbox(None) should use a default SandboxSpec."""
+        client = self._make_client()
+
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.text = '{"id": "sbx-def456"}'
+        mock_response.json.return_value = {"id": "sbx-def456"}
+        client.session.post.return_value = mock_response
+
+        handle = client.create_sandbox()
+
+        self.assertIsInstance(handle, SandboxHandle)
+        self.assertEqual(handle.id, "sbx-def456")
+
+    def test_sandbox_alias_equals_sandbox_handle(self):
+        """The Sandbox alias should be the same class as SandboxHandle."""
+        self.assertIs(Sandbox, SandboxHandle)
+
+
+class TestCommandsAPIRun(unittest.TestCase):
+    """Tests for sandbox.commands.run()."""
+
+    def _make_sandbox(self):
+        client = Client("http://localhost:8080")
+        client.session = MagicMock()
+        return SandboxHandle(client, "sbx-test01"), client
+
+    def test_run_posts_to_exec_endpoint(self):
+        """commands.run() should POST to /v1/sandboxes/{id}/exec."""
+        sandbox, client = self._make_sandbox()
+
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.text = '{"exit_code": 0, "stdout": "hi\\n", "stderr": ""}'
+        mock_response.json.return_value = {
+            "exit_code": 0,
+            "stdout": "hi\n",
+            "stderr": "",
+        }
+        client.session.post.return_value = mock_response
+
+        result = sandbox.commands.run(["echo", "hi"])
+
+        call_args = client.session.post.call_args
+        self.assertIn("/v1/sandboxes/sbx-test01/exec", call_args[0][0])
+
+        self.assertIsInstance(result, ExecResult)
+        self.assertEqual(result.exit_code, 0)
+        self.assertEqual(result.stdout, "hi\n")
+        self.assertEqual(result.stderr, "")
+
+    def test_run_returns_exec_result_fields(self):
+        """commands.run() should correctly populate all ExecResult fields."""
+        sandbox, client = self._make_sandbox()
+
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.text = '{"exit_code": 1, "stdout": "out", "stderr": "err", "artifacts": ["a.txt"]}'
+        mock_response.json.return_value = {
+            "exit_code": 1,
+            "stdout": "out",
+            "stderr": "err",
+            "artifacts": ["a.txt"],
+        }
+        client.session.post.return_value = mock_response
+
+        result = sandbox.commands.run(["false"])
+
+        self.assertEqual(result.exit_code, 1)
+        self.assertEqual(result.stdout, "out")
+        self.assertEqual(result.stderr, "err")
+        self.assertEqual(result.artifacts, ["a.txt"])
+
+
+class TestSandboxKill(unittest.TestCase):
+    """Tests for sandbox.kill()."""
+
+    def test_kill_calls_delete(self):
+        """sandbox.kill() should send DELETE to /v1/sandboxes/{id}."""
+        client = Client("http://localhost:8080")
+        client.session = MagicMock()
+        sandbox = SandboxHandle(client, "sbx-kill01")
+
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.text = ""
+        client.session.delete.return_value = mock_response
+
+        sandbox.kill()
+
+        call_args = client.session.delete.call_args
+        self.assertIn("/v1/sandboxes/sbx-kill01", call_args[0][0])
+
+
+class TestSandboxInfo(unittest.TestCase):
+    """Tests for sandbox.info()."""
+
+    def test_info_calls_get_and_returns_sandbox_info(self):
+        """sandbox.info() should GET /v1/sandboxes/{id} and return SandboxInfo."""
+        client = Client("http://localhost:8080")
+        client.session = MagicMock()
+        sandbox = SandboxHandle(client, "sbx-info01")
+
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.text = '{"id": "sbx-info01", "state": "ready"}'
+        mock_response.json.return_value = {"id": "sbx-info01", "state": "ready"}
+        client.session.get.return_value = mock_response
+
+        info = sandbox.info()
+
+        call_args = client.session.get.call_args
+        self.assertIn("/v1/sandboxes/sbx-info01", call_args[0][0])
+
+        self.assertIsInstance(info, SandboxInfo)
+        self.assertEqual(info.id, "sbx-info01")
+        self.assertEqual(info.state, "ready")
+
+
+class TestFilesAPI(unittest.TestCase):
+    """Tests for sandbox.files.*"""
+
+    def _make_sandbox(self):
+        client = Client("http://localhost:8080")
+        client.session = MagicMock()
+        return SandboxHandle(client, "sbx-fs01"), client
+
+    def _mock_put(self, client, body):
+        resp = MagicMock()
+        resp.status_code = 200
+        resp.text = body
+        resp.json.return_value = __import__("json").loads(body)
+        client.session.put = MagicMock(return_value=resp)
+
+    def _mock_get(self, client, body):
+        resp = MagicMock()
+        resp.status_code = 200
+        resp.text = body
+        resp.json.return_value = __import__("json").loads(body)
+        client.session.get = MagicMock(return_value=resp)
+
+    def test_read_returns_text_by_default(self):
+        sandbox, client = self._make_sandbox()
+        payload = __import__("json").dumps({"data": list(b"hello")})
+        self._mock_get(client, payload)
+        content = sandbox.files.read("/tmp/hello.txt")
+        self.assertIsInstance(content, str)
+        self.assertEqual(content, "hello")
+
+    def test_read_returns_bytes_when_requested(self):
+        sandbox, client = self._make_sandbox()
+        payload = __import__("json").dumps({"data": list(b"hello")})
+        self._mock_get(client, payload)
+        content = sandbox.files.read("/tmp/hello.txt", as_bytes=True)
+        self.assertIsInstance(content, bytes)
+        self.assertEqual(content, b"hello")
+
+    def test_write_puts_to_files_endpoint(self):
+        sandbox, client = self._make_sandbox()
+        self._mock_put(client, '{"size": 5}')
+        n = sandbox.files.write("/tmp/hello.txt", "hello")
+        url = client.session.put.call_args[0][0]
+        self.assertIn(f"/v1/sandboxes/{sandbox.id}/files", url)
+        self.assertEqual(n, 5)
+
+    def test_list_returns_entry_infos(self):
+        from sandforge.types import EntryInfo
+        sandbox, client = self._make_sandbox()
+        payload = '{"entries": [{"name": "a.txt", "path": "/tmp/a.txt", "size": 3, "isDir": false, "modTime": "2025-01-01T00:00:00Z"}]}'
+        self._mock_get(client, payload)
+        entries = sandbox.files.list("/tmp")
+        self.assertEqual(len(entries), 1)
+        self.assertIsInstance(entries[0], EntryInfo)
+        self.assertEqual(entries[0].name, "a.txt")
+
+    def test_stat_returns_entry_info(self):
+        from sandforge.types import EntryInfo
+        sandbox, client = self._make_sandbox()
+        payload = '{"name": "a.txt", "path": "/tmp/a.txt", "size": 3, "isDir": false, "modTime": "2025-01-01T00:00:00Z"}'
+        self._mock_get(client, payload)
+        info = sandbox.files.stat("/tmp/a.txt")
+        self.assertIsInstance(info, EntryInfo)
+        self.assertEqual(info.size, 3)
+
+    def test_exists_true_on_success(self):
+        sandbox, client = self._make_sandbox()
+        payload = '{"name": "a.txt", "path": "/tmp/a.txt", "size": 3, "isDir": false, "modTime": "2025-01-01T00:00:00Z"}'
+        self._mock_get(client, payload)
+        self.assertTrue(sandbox.files.exists("/tmp/a.txt"))
+
+    def test_exists_false_on_error(self):
+        sandbox, client = self._make_sandbox()
+        resp = MagicMock()
+        resp.status_code = 422
+        resp.text = '{"error": "not found"}'
+        resp.json.return_value = {"error": "not found"}
+        client.session.get = MagicMock(return_value=resp)
+        self.assertFalse(sandbox.files.exists("/tmp/missing.txt"))
+
+
+class TestGitAPI(unittest.TestCase):
+    """Tests for sandbox.git.*"""
+
+    def _make_sandbox(self):
+        client = Client("http://localhost:8080")
+        client.session = MagicMock()
+        return SandboxHandle(client, "sbx-git01"), client
+
+    def _mock_exec(self, client, stdout="", exit_code=0):
+        resp = MagicMock()
+        resp.status_code = 200
+        body = __import__("json").dumps({"exit_code": exit_code, "stdout": stdout, "stderr": ""})
+        resp.text = body
+        resp.json.return_value = __import__("json").loads(body)
+        client.session.post = MagicMock(return_value=resp)
+
+    def test_clone_runs_git_clone(self):
+        sandbox, client = self._make_sandbox()
+        self._mock_exec(client)
+        sandbox.git.clone("https://github.com/example/repo.git")
+        payload = client.session.post.call_args[1]["json"]
+        self.assertEqual(payload["command"][0], "git")
+        self.assertIn("clone", payload["command"])
+
+    def test_init_runs_git_init(self):
+        sandbox, client = self._make_sandbox()
+        self._mock_exec(client)
+        sandbox.git.init("/workspace")
+        payload = client.session.post.call_args[1]["json"]
+        self.assertEqual(payload["command"], ["git", "init"])
+        self.assertEqual(payload["cwd"], "/workspace")
+
+    def test_status_returns_git_status(self):
+        from sandforge.types import GitStatus
+        sandbox, client = self._make_sandbox()
+        call_count = [0]
+        responses = [
+            {"exit_code": 0, "stdout": "main\n", "stderr": ""},
+            {"exit_code": 0, "stdout": "", "stderr": ""},
+        ]
+        def side_effect(url, **kwargs):
+            resp = MagicMock()
+            resp.status_code = 200
+            body = __import__("json").dumps(responses[call_count[0]])
+            resp.text = body
+            resp.json.return_value = responses[call_count[0]]
+            call_count[0] += 1
+            return resp
+        client.session.post.side_effect = side_effect
+
+        status = sandbox.git.status("/workspace")
+        self.assertIsInstance(status, GitStatus)
+        self.assertEqual(status.branch, "main")
+        self.assertTrue(status.clean)
+
+    def test_branches_parses_output(self):
+        sandbox, client = self._make_sandbox()
+        self._mock_exec(client, stdout="* main\n  dev\n  feature/x\n")
+        result = sandbox.git.branches("/workspace")
+        self.assertIn("main", result)
+        self.assertIn("dev", result)
+        self.assertIn("feature/x", result)
+
+
+if __name__ == "__main__":
+    unittest.main()