lizard-sdk 0.1.1__tar.gz

lizard_sdk-0.1.1/.gitignore

@@ -0,0 +1,11 @@
+node_modules/
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.pyc
+.env
+.venv/
+venv/
+*.tgz
+package-lock.json

lizard_sdk-0.1.1/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: lizard-sdk
+Version: 0.1.1
+Summary: Lizard SDK — cloud sandboxes for AI agents
+License: Apache-2.0
+Requires-Python: >=3.8
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Lizard SDK
+
+Firecracker microVM sandboxes for AI agents — boot a full Linux environment in milliseconds, run code, write files, and expose ports, all from your agent or CI pipeline.
+
+Each sandbox is an isolated microVM with its own filesystem, network, and process namespace. Sandboxes can be snapshotted and resumed instantly, so long-running agent sessions survive restarts without re-running setup.
+
+## Install
+
+```bash
+# JavaScript / TypeScript
+npm install @lizard-build/sdk
+
+# Python
+pip install lizard-sdk
+```
+
+## Quickstart
+
+### JavaScript / TypeScript
+
+```ts
+import { Sandbox } from '@lizard-build/sdk'
+
+// Boot a Node.js microVM from the 'node22' template
+const sandbox = await Sandbox.create('node22')
+
+// Write a file directly into the microVM filesystem
+await sandbox.fs.write('/app/server.js', `
+  const http = require('http')
+  http.createServer((_, res) => res.end('hello from Lizard')).listen(3000)
+`)
+
+// Execute a process inside the microVM
+await sandbox.process.exec('node /app/server.js &')
+
+// Get a public HTTPS URL for port 3000 inside the sandbox
+const url = sandbox.getHost(3000)
+console.log(`Live at https://${url}`)
+
+// Tear down the microVM when done
+await sandbox.kill()
+```
+
+### Python
+
+```python
+from lizard import Sandbox
+
+# Boot a Python microVM from the 'python312' template
+sandbox = Sandbox.create("python312")
+
+# Write a script into the microVM filesystem
+sandbox.fs.write("/app/main.py", """
+import http.server, socketserver
+
+class Handler(http.server.SimpleHTTPRequestHandler):
+    def do_GET(self):
+        self.send_response(200)
+        self.end_headers()
+        self.wfile.write(b"hello from Lizard")
+
+with socketserver.TCPServer(("", 3000), Handler) as httpd:
+    httpd.serve_forever()
+""")
+
+# Execute a process inside the microVM
+sandbox.process.exec_("python /app/main.py &")
+
+print(f"Live at https://{sandbox.get_host(3000)}")
+
+sandbox.kill()
+```
+
+## Pause and Resume
+
+Sandboxes can be snapshotted mid-execution and resumed exactly where they left off — including installed packages, in-memory state, and running processes. This makes Lizard sandboxes well-suited for long-running AI agent workflows where you want to checkpoint and continue across separate invocations.
+
+```ts
+// Boot and set up the environment once
+const sandbox = await Sandbox.create('python312')
+await sandbox.process.exec('pip install numpy pandas scikit-learn')
+const id = sandbox.sandboxId
+await sandbox.pause()
+
+// Later — resume instantly from the snapshot (no reinstall needed)
+const resumed = await Sandbox.connect(id)
+const result = await resumed.process.exec('python -c "import sklearn; print(sklearn.__version__)"')
+console.log(result.stdout)
+await resumed.kill()
+```
+
+```python
+from lizard import Sandbox
+
+sandbox = Sandbox.create("python312")
+sandbox.process.exec_("pip install numpy pandas scikit-learn")
+sandbox_id = sandbox.sandbox_id
+sandbox.pause()
+
+# Resume later — environment is exactly as left
+resumed = Sandbox.connect(sandbox_id)
+result = resumed.process.exec_("python -c 'import sklearn; print(sklearn.__version__)'")
+print(result.stdout)
+resumed.kill()
+```
+
+## API
+
+### `Sandbox.create(template?, opts?)`
+
+Boot a new Lizard microVM. Built-in templates: `base`, `node22`, `python312`. Custom templates can be pushed via `lizard push`.
+
+```ts
+const sandbox = await Sandbox.create('node22')
+const sandbox = await Sandbox.create('python312', { timeoutMs: 10 * 60 * 1000 })
+```
+
+### `Sandbox.connect(sandboxId, opts?)`
+
+Connect to an existing sandbox by ID. If the sandbox is paused, it is automatically resumed from its last snapshot.
+
+### `Sandbox.list(opts?)`
+
+List all running sandboxes for the authenticated account.
+
+---
+
+### `sandbox.fs`
+
+Read and write files inside the microVM filesystem.
+
+| Method | Description |
+|---|---|
+| `fs.write(path, data)` | Write a file (string or bytes) |
+| `fs.read(path)` | Read a file as a string |
+| `fs.list(path)` | List directory contents |
+| `fs.remove(path)` | Delete a file or directory |
+| `fs.makeDir(path)` | Create a directory and parents |
+
+### `sandbox.process`
+
+Execute commands inside the microVM.
+
+| Method | Description |
+|---|---|
+| `process.exec(cmd, opts?)` | Run a command and wait for it to finish |
+
+`exec` returns `{ stdout, stderr, exitCode }` (JS) or `ProcessResult` (Python). In Python the method is named `exec_` because `exec` is a reserved keyword.
+
+### `sandbox.getHost(port)`
+
+Returns a public HTTPS URL for a port listening inside the microVM — no tunneling required.
+
+```ts
+await sandbox.process.exec('npx -y serve -p 3000 &')
+const url = sandbox.getHost(3000)
+// https://{sandboxId}-3000.sandbox.lizard.run
+```
+
+### `sandbox.pause()` / `sandbox.resume()`
+
+Snapshot and restore the microVM state. Useful for checkpointing long agent sessions.
+
+### `sandbox.kill()`
+
+Terminate the sandbox and release all resources.
+
+### `sandbox.setTimeout(ms)`
+
+Extend or reduce the sandbox timeout.
+
+---
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `LIZARD_API_KEY` | API key (required — get one at [lizard.run](https://lizard.run)) |
+| `LIZARD_API_URL` | Override the API base URL (default: `https://api.lizard.run`) |
+
+The `X-API-Key` header is used for all authenticated requests.
+
+## Deploy What You Build
+
+Once your agent has produced a working app inside a sandbox, deploy it as a persistent Lizard service — no Dockerfile needed:
+
+```bash
+lizard up
+```
+
+Your sandbox template becomes the base, your code ships as a layer on top, and Lizard manages the Firecracker microVM fleet from there.
+
+## License
+
+Apache-2.0

lizard_sdk-0.1.1/README.md

@@ -0,0 +1,195 @@
+# Lizard SDK
+
+Firecracker microVM sandboxes for AI agents — boot a full Linux environment in milliseconds, run code, write files, and expose ports, all from your agent or CI pipeline.
+
+Each sandbox is an isolated microVM with its own filesystem, network, and process namespace. Sandboxes can be snapshotted and resumed instantly, so long-running agent sessions survive restarts without re-running setup.
+
+## Install
+
+```bash
+# JavaScript / TypeScript
+npm install @lizard-build/sdk
+
+# Python
+pip install lizard-sdk
+```
+
+## Quickstart
+
+### JavaScript / TypeScript
+
+```ts
+import { Sandbox } from '@lizard-build/sdk'
+
+// Boot a Node.js microVM from the 'node22' template
+const sandbox = await Sandbox.create('node22')
+
+// Write a file directly into the microVM filesystem
+await sandbox.fs.write('/app/server.js', `
+  const http = require('http')
+  http.createServer((_, res) => res.end('hello from Lizard')).listen(3000)
+`)
+
+// Execute a process inside the microVM
+await sandbox.process.exec('node /app/server.js &')
+
+// Get a public HTTPS URL for port 3000 inside the sandbox
+const url = sandbox.getHost(3000)
+console.log(`Live at https://${url}`)
+
+// Tear down the microVM when done
+await sandbox.kill()
+```
+
+### Python
+
+```python
+from lizard import Sandbox
+
+# Boot a Python microVM from the 'python312' template
+sandbox = Sandbox.create("python312")
+
+# Write a script into the microVM filesystem
+sandbox.fs.write("/app/main.py", """
+import http.server, socketserver
+
+class Handler(http.server.SimpleHTTPRequestHandler):
+    def do_GET(self):
+        self.send_response(200)
+        self.end_headers()
+        self.wfile.write(b"hello from Lizard")
+
+with socketserver.TCPServer(("", 3000), Handler) as httpd:
+    httpd.serve_forever()
+""")
+
+# Execute a process inside the microVM
+sandbox.process.exec_("python /app/main.py &")
+
+print(f"Live at https://{sandbox.get_host(3000)}")
+
+sandbox.kill()
+```
+
+## Pause and Resume
+
+Sandboxes can be snapshotted mid-execution and resumed exactly where they left off — including installed packages, in-memory state, and running processes. This makes Lizard sandboxes well-suited for long-running AI agent workflows where you want to checkpoint and continue across separate invocations.
+
+```ts
+// Boot and set up the environment once
+const sandbox = await Sandbox.create('python312')
+await sandbox.process.exec('pip install numpy pandas scikit-learn')
+const id = sandbox.sandboxId
+await sandbox.pause()
+
+// Later — resume instantly from the snapshot (no reinstall needed)
+const resumed = await Sandbox.connect(id)
+const result = await resumed.process.exec('python -c "import sklearn; print(sklearn.__version__)"')
+console.log(result.stdout)
+await resumed.kill()
+```
+
+```python
+from lizard import Sandbox
+
+sandbox = Sandbox.create("python312")
+sandbox.process.exec_("pip install numpy pandas scikit-learn")
+sandbox_id = sandbox.sandbox_id
+sandbox.pause()
+
+# Resume later — environment is exactly as left
+resumed = Sandbox.connect(sandbox_id)
+result = resumed.process.exec_("python -c 'import sklearn; print(sklearn.__version__)'")
+print(result.stdout)
+resumed.kill()
+```
+
+## API
+
+### `Sandbox.create(template?, opts?)`
+
+Boot a new Lizard microVM. Built-in templates: `base`, `node22`, `python312`. Custom templates can be pushed via `lizard push`.
+
+```ts
+const sandbox = await Sandbox.create('node22')
+const sandbox = await Sandbox.create('python312', { timeoutMs: 10 * 60 * 1000 })
+```
+
+### `Sandbox.connect(sandboxId, opts?)`
+
+Connect to an existing sandbox by ID. If the sandbox is paused, it is automatically resumed from its last snapshot.
+
+### `Sandbox.list(opts?)`
+
+List all running sandboxes for the authenticated account.
+
+---
+
+### `sandbox.fs`
+
+Read and write files inside the microVM filesystem.
+
+| Method | Description |
+|---|---|
+| `fs.write(path, data)` | Write a file (string or bytes) |
+| `fs.read(path)` | Read a file as a string |
+| `fs.list(path)` | List directory contents |
+| `fs.remove(path)` | Delete a file or directory |
+| `fs.makeDir(path)` | Create a directory and parents |
+
+### `sandbox.process`
+
+Execute commands inside the microVM.
+
+| Method | Description |
+|---|---|
+| `process.exec(cmd, opts?)` | Run a command and wait for it to finish |
+
+`exec` returns `{ stdout, stderr, exitCode }` (JS) or `ProcessResult` (Python). In Python the method is named `exec_` because `exec` is a reserved keyword.
+
+### `sandbox.getHost(port)`
+
+Returns a public HTTPS URL for a port listening inside the microVM — no tunneling required.
+
+```ts
+await sandbox.process.exec('npx -y serve -p 3000 &')
+const url = sandbox.getHost(3000)
+// https://{sandboxId}-3000.sandbox.lizard.run
+```
+
+### `sandbox.pause()` / `sandbox.resume()`
+
+Snapshot and restore the microVM state. Useful for checkpointing long agent sessions.
+
+### `sandbox.kill()`
+
+Terminate the sandbox and release all resources.
+
+### `sandbox.setTimeout(ms)`
+
+Extend or reduce the sandbox timeout.
+
+---
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `LIZARD_API_KEY` | API key (required — get one at [lizard.run](https://lizard.run)) |
+| `LIZARD_API_URL` | Override the API base URL (default: `https://api.lizard.run`) |
+
+The `X-API-Key` header is used for all authenticated requests.
+
+## Deploy What You Build
+
+Once your agent has produced a working app inside a sandbox, deploy it as a persistent Lizard service — no Dockerfile needed:
+
+```bash
+lizard up
+```
+
+Your sandbox template becomes the base, your code ships as a layer on top, and Lizard manages the Firecracker microVM fleet from there.
+
+## License
+
+Apache-2.0

lizard_sdk-0.1.1/lizard/__init__.py

@@ -0,0 +1,18 @@
+from .sandbox import Sandbox, SandboxInfo, ProcessResult, FileInfo
+from .errors import LizardError, AuthenticationError, NotFoundError, TimeoutError
+from .code_interpreter import CodeSandbox, Execution, ExecutionError, CodeContext
+
+__all__ = [
+    "Sandbox",
+    "SandboxInfo",
+    "ProcessResult",
+    "FileInfo",
+    "LizardError",
+    "AuthenticationError",
+    "NotFoundError",
+    "TimeoutError",
+    "CodeSandbox",
+    "Execution",
+    "ExecutionError",
+    "CodeContext",
+]

lizard_sdk-0.1.1/lizard/code_interpreter/__init__.py

@@ -0,0 +1,23 @@
+from .sandbox import CodeSandbox
+from .types import (
+    Execution,
+    ExecutionError,
+    CodeContext,
+    ResultItem,
+    StdoutItem,
+    StderrItem,
+    ErrorItem,
+    OutputItem,
+)
+
+__all__ = [
+    "CodeSandbox",
+    "Execution",
+    "ExecutionError",
+    "CodeContext",
+    "ResultItem",
+    "StdoutItem",
+    "StderrItem",
+    "ErrorItem",
+    "OutputItem",
+]

lizard_sdk-0.1.1/lizard/code_interpreter/sandbox.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+import json
+from typing import Callable, Iterator, Optional
+
+import httpx
+
+from ..sandbox.sandbox import Sandbox
+from .types import (
+    CodeContext,
+    Execution,
+    ExecutionError,
+    OutputItem,
+    ResultItem,
+    StdoutItem,
+    StderrItem,
+    ErrorItem,
+)
+
+_CODE_INTERPRETER_PORT = 8080
+
+
+class CodeSandbox(Sandbox):
+    """
+    A Lizard sandbox with built-in stateful code execution.
+
+    Extends the base Sandbox with ``run_code()`` — executes code in a
+    persistent kernel so variables and imports survive between calls.
+
+    Supports Python, JavaScript (Node.js), and Bash out of the box.
+
+    Example::
+
+        with CodeSandbox.create() as sandbox:
+            sandbox.run_code("x = 42")
+            result = sandbox.run_code("print(x * 2)")
+            print(result.stdout)  # "84\\n"
+
+    Example — JavaScript::
+
+        result = sandbox.run_code("1 + 1", language="javascript")
+        print(result.results[0].data)  # "2"
+    """
+
+    _DEFAULT_TEMPLATE = "code-interpreter-v1"
+
+    @property
+    def _server_url(self) -> str:
+        return f"https://{self.get_host(_CODE_INTERPRETER_PORT)}"
+
+    def run_code(
+        self,
+        code: str,
+        *,
+        language: str | None = None,
+        context: CodeContext | None = None,
+        envs: dict[str, str] | None = None,
+        timeout_ms: int = 60_000,
+        on_stdout: Callable[[str], None] | None = None,
+        on_stderr: Callable[[str], None] | None = None,
+        on_result: Callable[[ResultItem], None] | None = None,
+        on_error: Callable[[ExecutionError], None] | None = None,
+    ) -> Execution:
+        """
+        Execute code in a persistent kernel.
+
+        Variables, imports, and function definitions from previous calls are
+        available in subsequent calls within the same context.
+
+        :param code: Source code to run.
+        :param language: ``'python'``, ``'javascript'``, or ``'bash'``.
+            Defaults to ``'python'``.
+        :param context: Run in a specific context instead of the default one.
+        :param envs: Extra environment variables available to the code.
+        :param timeout_ms: Timeout in milliseconds. Default 60 000.
+        :param on_stdout: Callback invoked for each stdout chunk.
+        :param on_stderr: Callback invoked for each stderr chunk.
+        :param on_result: Callback invoked for each rich result item.
+        :param on_error: Callback invoked if the code throws an exception.
+        :returns: :class:`Execution` with stdout, stderr, results, and error.
+        """
+        if context and language:
+            raise ValueError("Provide context or language, not both")
+
+        body: dict = {"code": code, "env_vars": envs or {}}
+        if context:
+            body["context_id"] = context.id
+        elif language:
+            body["language"] = language
+
+        execution = Execution()
+
+        with httpx.stream(
+            "POST",
+            f"{self._server_url}/execute",
+            json=body,
+            timeout=timeout_ms / 1000,
+        ) as resp:
+            resp.raise_for_status()
+
+            for raw in resp.iter_lines():
+                if not raw.strip():
+                    continue
+                try:
+                    item = json.loads(raw)
+                except json.JSONDecodeError:
+                    continue
+
+                t = item.get("type")
+
+                if t == "stdout":
+                    execution.stdout += item["data"]
+                    on_stdout and on_stdout(item["data"])
+
+                elif t == "stderr":
+                    execution.stderr += item["data"]
+                    on_stderr and on_stderr(item["data"])
+
+                elif t == "result":
+                    r = ResultItem(mime=item.get("mime", "text/plain"), data=item.get("data", ""))
+                    execution.results.append(r)
+                    on_result and on_result(r)
+
+                elif t == "error":
+                    err = ExecutionError(
+                        name=item.get("name", "Error"),
+                        message=item.get("message", ""),
+                        traceback=item.get("traceback", ""),
+                    )
+                    execution.error = err
+                    on_error and on_error(err)
+
+                elif t == "done":
+                    execution.execution_count = item.get("execution_count", 0)
+                    break
+
+        return execution
+
+    def create_context(
+        self,
+        language: str = "python",
+        cwd: str = "/home/user",
+    ) -> CodeContext:
+        """Create a new isolated execution context."""
+        resp = httpx.post(
+            f"{self._server_url}/contexts",
+            json={"language": language, "cwd": cwd},
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        return CodeContext(**data)
+
+    def list_contexts(self) -> list[CodeContext]:
+        """List all active contexts in this sandbox."""
+        resp = httpx.get(f"{self._server_url}/contexts")
+        resp.raise_for_status()
+        return [CodeContext(**c) for c in resp.json()]
+
+    def delete_context(self, context: CodeContext | str) -> None:
+        """Delete a context and free its resources."""
+        ctx_id = context if isinstance(context, str) else context.id
+        resp = httpx.delete(f"{self._server_url}/contexts/{ctx_id}")
+        resp.raise_for_status()
+
+    def restart_context(self, context: CodeContext | str) -> None:
+        """Restart a context, clearing all variables and state."""
+        ctx_id = context if isinstance(context, str) else context.id
+        resp = httpx.post(f"{self._server_url}/contexts/{ctx_id}/restart")
+        resp.raise_for_status()

lizard_sdk-0.1.1/lizard/code_interpreter/types.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Literal, Union
+
+
+@dataclass
+class StdoutItem:
+    type: Literal["stdout"] = "stdout"
+    data: str = ""
+    ts: int = 0
+
+
+@dataclass
+class StderrItem:
+    type: Literal["stderr"] = "stderr"
+    data: str = ""
+    ts: int = 0
+
+
+@dataclass
+class ResultItem:
+    type: Literal["result"] = "result"
+    mime: str = "text/plain"
+    data: str = ""
+
+
+@dataclass
+class ErrorItem:
+    type: Literal["error"] = "error"
+    name: str = ""
+    message: str = ""
+    traceback: str = ""
+
+
+OutputItem = Union[StdoutItem, StderrItem, ResultItem, ErrorItem]
+
+
+class ExecutionError(Exception):
+    def __init__(self, name: str, message: str, traceback: str):
+        super().__init__(message)
+        self.name = name
+        self.message = message
+        self.traceback = traceback
+
+
+@dataclass
+class Execution:
+    stdout: str = ""
+    stderr: str = ""
+    results: list[ResultItem] = field(default_factory=list)
+    error: ExecutionError | None = None
+    execution_count: int = 0
+
+    @property
+    def success(self) -> bool:
+        return self.error is None
+
+    @property
+    def text(self) -> str:
+        return self.stdout
+
+
+@dataclass
+class CodeContext:
+    id: str
+    language: str
+    cwd: str

lizard_sdk-0.1.1/lizard/config.py

@@ -0,0 +1,28 @@
+import os
+
+DEFAULT_API_URL = "https://api.lizard.run"
+DEFAULT_SANDBOX_TIMEOUT_MS = 5 * 60 * 1000  # 5 minutes
+
+
+class ConnectionConfig:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        api_url: str | None = None,
+        timeout_ms: int | None = None,
+    ):
+        self.api_key = api_key or os.environ.get("LIZARD_API_KEY", "")
+        self.api_url = api_url or os.environ.get("LIZARD_API_URL", DEFAULT_API_URL)
+        self.timeout_ms = timeout_ms or DEFAULT_SANDBOX_TIMEOUT_MS
+
+        if not self.api_key:
+            raise ValueError(
+                "Lizard API key is required. Set LIZARD_API_KEY env var or pass api_key."
+            )
+
+    @property
+    def headers(self) -> dict[str, str]:
+        return {
+            "X-API-Key": self.api_key,
+            "Content-Type": "application/json",
+        }

lizard_sdk-0.1.1/lizard/errors.py

@@ -0,0 +1,20 @@
+class LizardError(Exception):
+    pass
+
+class AuthenticationError(LizardError):
+    pass
+
+class NotFoundError(LizardError):
+    pass
+
+class TimeoutError(LizardError):
+    pass
+
+def handle_api_error(status_code: int, message: str) -> None:
+    if status_code in (401, 403):
+        raise AuthenticationError(message)
+    if status_code == 404:
+        raise NotFoundError(message)
+    if status_code in (408, 504):
+        raise TimeoutError(message)
+    raise LizardError(f"API error {status_code}: {message}")

lizard_sdk-0.1.1/lizard/sandbox/__init__.py

@@ -0,0 +1,5 @@
+from .sandbox import Sandbox, SandboxInfo
+from .process import Process, ProcessResult
+from .fs import Fs, FileInfo
+
+__all__ = ["Sandbox", "SandboxInfo", "Process", "ProcessResult", "Fs", "FileInfo"]

lizard_sdk-0.1.1/lizard/sandbox/fs.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..config import ConnectionConfig
+
+
+@dataclass
+class FileInfo:
+    """Metadata for a file or directory inside a Lizard sandbox microVM."""
+
+    name: str
+    path: str
+    type: str  # 'file' | 'dir'
+    size: int
+
+
+class Fs:
+    """
+    Read and write files inside a Lizard sandbox microVM.
+
+    Access via ``sandbox.fs``.
+    """
+
+    def __init__(self, sandbox_id: str, config: "ConnectionConfig"):
+        self._sandbox_id = sandbox_id
+        self._config = config
+
+    def write(self, path: str, data: str | bytes, *, user: str | None = None) -> None:
+        """
+        Write a file into the microVM filesystem.
+
+        Parent directories are created automatically if they don't exist.
+
+        :param path: Absolute path inside the microVM.
+        :param data: File contents — string or bytes.
+        :param user: Write as this Linux user (default: ``root``).
+
+        Example::
+
+            sandbox.fs.write("/app/index.js", 'console.log("hello")')
+        """
+        import httpx
+
+        content = data if isinstance(data, str) else data.decode()
+        body: dict = {"path": path, "content": content}
+        if user:
+            body["user"] = user
+
+        res = httpx.post(
+            f"{self._config.api_url}/api/sandboxes/{self._sandbox_id}/files",
+            headers=self._config.headers,
+            json=body,
+        )
+        if not res.is_success:
+            from ..errors import handle_api_error
+            handle_api_error(res.status_code, res.text)
+
+    def read(self, path: str, *, user: str | None = None) -> str:
+        """
+        Read a file from the microVM filesystem.
+
+        :param path: Absolute path inside the microVM.
+        :returns: File contents as a UTF-8 string.
+
+        Example::
+
+            content = sandbox.fs.read("/app/index.js")
+        """
+        import httpx
+
+        params: dict = {"path": path}
+        if user:
+            params["user"] = user
+
+        res = httpx.get(
+            f"{self._config.api_url}/api/sandboxes/{self._sandbox_id}/files",
+            headers=self._config.headers,
+            params=params,
+        )
+        if not res.is_success:
+            from ..errors import handle_api_error
+            handle_api_error(res.status_code, res.text)
+        return res.text
+
+    def list(self, path: str, *, user: str | None = None) -> list[FileInfo]:
+        """
+        List files and directories at a path inside the microVM.
+
+        :param path: Directory path to list.
+
+        Example::
+
+            entries = sandbox.fs.list("/app")
+        """
+        import httpx
+
+        params: dict = {"path": path}
+        if user:
+            params["user"] = user
+
+        res = httpx.get(
+            f"{self._config.api_url}/api/sandboxes/{self._sandbox_id}/files/list",
+            headers=self._config.headers,
+            params=params,
+        )
+        if not res.is_success:
+            from ..errors import handle_api_error
+            handle_api_error(res.status_code, res.text)
+
+        return [FileInfo(**f) for f in res.json()]
+
+    def remove(self, path: str, *, user: str | None = None) -> None:
+        """Remove a file or directory from the microVM filesystem."""
+        import httpx
+
+        body: dict = {"path": path}
+        if user:
+            body["user"] = user
+
+        res = httpx.request(
+            "DELETE",
+            f"{self._config.api_url}/api/sandboxes/{self._sandbox_id}/files",
+            headers=self._config.headers,
+            json=body,
+        )
+        if not res.is_success:
+            from ..errors import handle_api_error
+            handle_api_error(res.status_code, res.text)
+
+    def make_dir(self, path: str, *, user: str | None = None) -> None:
+        """Create a directory (and any missing parents) inside the microVM."""
+        import httpx
+        import json
+
+        body: dict = {"cmd": f"mkdir -p {json.dumps(path)}"}
+        if user:
+            body["user"] = user
+
+        res = httpx.post(
+            f"{self._config.api_url}/api/sandboxes/{self._sandbox_id}/exec",
+            headers=self._config.headers,
+            json=body,
+        )
+        if not res.is_success:
+            from ..errors import handle_api_error
+            handle_api_error(res.status_code, res.text)

lizard_sdk-0.1.1/lizard/sandbox/process.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..config import ConnectionConfig
+
+
+@dataclass
+class ProcessResult:
+    """Result of a process executed inside a Lizard sandbox microVM."""
+
+    stdout: str
+    stderr: str
+    exit_code: int
+
+
+class Process:
+    """
+    Run processes inside a Lizard sandbox microVM.
+
+    Access via ``sandbox.process``.
+    """
+
+    def __init__(self, sandbox_id: str, config: "ConnectionConfig"):
+        self._sandbox_id = sandbox_id
+        self._config = config
+
+    def exec_(
+        self,
+        cmd: str,
+        *,
+        envs: dict[str, str] | None = None,
+        user: str | None = None,
+        workdir: str | None = None,
+        timeout_ms: int | None = None,
+    ) -> ProcessResult:
+        """
+        Execute a command inside the microVM and wait for it to finish.
+
+        The command runs in a shell inside the Lizard sandbox and returns
+        stdout, stderr, and the exit code when it completes.
+
+        :param cmd: Shell command to run inside the microVM.
+        :param envs: Additional environment variables for this execution.
+        :param user: Run as this Linux user (default: ``root``).
+        :param workdir: Working directory inside the microVM.
+        :param timeout_ms: Execution timeout in milliseconds.
+
+        Example::
+
+            result = sandbox.process.exec_("node index.js")
+            print(result.stdout)
+
+        Example with options::
+
+            result = sandbox.process.exec_(
+                "npm test",
+                workdir="/app",
+                envs={"NODE_ENV": "test"},
+            )
+        """
+        import httpx
+
+        body: dict = {"cmd": cmd}
+        if envs:
+            body["envs"] = envs
+        if user:
+            body["user"] = user
+        if workdir:
+            body["workdir"] = workdir
+        if timeout_ms:
+            body["timeoutMs"] = timeout_ms
+
+        timeout = (timeout_ms or 60_000) / 1000
+
+        res = httpx.post(
+            f"{self._config.api_url}/api/sandboxes/{self._sandbox_id}/exec",
+            headers=self._config.headers,
+            json=body,
+            timeout=timeout,
+        )
+
+        if not res.is_success:
+            from ..errors import handle_api_error
+            handle_api_error(res.status_code, res.text)
+
+        data = res.json()
+        return ProcessResult(
+            stdout=data.get("stdout", ""),
+            stderr=data.get("stderr", ""),
+            exit_code=data.get("exitCode", 0),
+        )

lizard_sdk-0.1.1/lizard/sandbox/sandbox.py

@@ -0,0 +1,287 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Any
+
+from ..config import ConnectionConfig, DEFAULT_SANDBOX_TIMEOUT_MS
+from .process import Process
+from .fs import Fs
+
+
+@dataclass
+class SandboxInfo:
+    sandbox_id: str
+    template: str
+    started_at: str
+    end_at: str
+    metadata: dict[str, str] | None = None
+
+
+class Sandbox:
+    """
+    A Lizard sandbox — an isolated Firecracker microVM that boots in milliseconds.
+
+    Each sandbox is a full Linux environment with its own filesystem, network,
+    and process namespace. Sandboxes are created from templates, can be paused
+    to a snapshot, and resumed instantly — ideal for stateful AI agent sessions
+    or ephemeral code execution.
+
+    Example::
+
+        from lizard import Sandbox
+
+        sandbox = Sandbox.create("node22")
+        sandbox.fs.write("/app/index.js", 'console.log("hello world")')
+        result = sandbox.process.exec_("node /app/index.js")
+        print(result.stdout)  # "hello world"
+        sandbox.kill()
+
+    Can also be used as a context manager::
+
+        with Sandbox.create("python312") as sandbox:
+            sandbox.fs.write("/app/main.py", "print('done')")
+            sandbox.process.exec_("python /app/main.py")
+    """
+
+    _default_template = "base"
+    _default_timeout_ms = DEFAULT_SANDBOX_TIMEOUT_MS
+
+    def __init__(
+        self,
+        sandbox_id: str,
+        *,
+        api_key: str | None = None,
+        api_url: str | None = None,
+        timeout_ms: int | None = None,
+    ):
+        self.sandbox_id = sandbox_id
+        self._config = ConnectionConfig(api_key=api_key, api_url=api_url, timeout_ms=timeout_ms)
+        self.fs = Fs(self.sandbox_id, self._config)
+        self.process = Process(self.sandbox_id, self._config)
+
+    @classmethod
+    def create(
+        cls,
+        template: str | None = None,
+        *,
+        api_key: str | None = None,
+        api_url: str | None = None,
+        timeout_ms: int | None = None,
+        metadata: dict[str, str] | None = None,
+        envs: dict[str, str] | None = None,
+    ) -> "Sandbox":
+        """
+        Boot a new Lizard sandbox from the specified template.
+
+        Available templates include ``base``, ``node22``, and ``python312``.
+        Custom templates can be built and pushed via ``lizard push``.
+
+        :param template: Template name. Defaults to ``base``.
+
+        Example::
+
+            sandbox = Sandbox.create("node22")
+            sandbox = Sandbox.create()  # uses 'base' template
+        """
+        import httpx
+
+        config = ConnectionConfig(api_key=api_key, api_url=api_url, timeout_ms=timeout_ms)
+        effective_template = template or cls._default_template
+        effective_timeout = timeout_ms or cls._default_timeout_ms
+
+        body: dict[str, Any] = {"template": effective_template, "timeoutMs": effective_timeout}
+        if metadata:
+            body["metadata"] = metadata
+        if envs:
+            body["envs"] = envs
+
+        res = httpx.post(
+            f"{config.api_url}/api/sandboxes",
+            headers=config.headers,
+            json=body,
+        )
+
+        if not res.is_success:
+            from ..errors import handle_api_error
+            handle_api_error(res.status_code, res.text)
+
+        data = res.json()
+        return cls(
+            data["sandboxId"],
+            api_key=api_key,
+            api_url=api_url,
+            timeout_ms=timeout_ms,
+        )
+
+    @classmethod
+    def connect(
+        cls,
+        sandbox_id: str,
+        *,
+        api_key: str | None = None,
+        api_url: str | None = None,
+    ) -> "Sandbox":
+        """
+        Connect to an existing sandbox by its ID.
+
+        If the sandbox is currently paused, it is automatically resumed from
+        its last snapshot before this call returns.
+
+        Example::
+
+            sandbox = Sandbox.connect("sandbox_abc123")
+        """
+        import httpx
+
+        config = ConnectionConfig(api_key=api_key, api_url=api_url)
+        res = httpx.post(
+            f"{config.api_url}/api/sandboxes/{sandbox_id}/resume",
+            headers=config.headers,
+        )
+        if res.status_code not in (200, 404):
+            from ..errors import handle_api_error
+            handle_api_error(res.status_code, res.text)
+
+        return cls(sandbox_id, api_key=api_key, api_url=api_url)
+
+    @classmethod
+    def list(cls, *, api_key: str | None = None, api_url: str | None = None) -> list[SandboxInfo]:
+        """List all running sandboxes for the authenticated account."""
+        import httpx
+
+        config = ConnectionConfig(api_key=api_key, api_url=api_url)
+        res = httpx.get(f"{config.api_url}/api/sandboxes", headers=config.headers)
+        if not res.is_success:
+            from ..errors import handle_api_error
+            handle_api_error(res.status_code, res.text)
+
+        return [
+            SandboxInfo(
+                sandbox_id=s["sandboxId"],
+                template=s["template"],
+                started_at=s["startedAt"],
+                end_at=s["endAt"],
+                metadata=s.get("metadata"),
+            )
+            for s in res.json()
+        ]
+
+    def kill(self) -> bool:
+        """
+        Kill the sandbox and release its resources immediately.
+
+        :returns: ``True`` if the microVM was terminated, ``False`` if it was already gone.
+        """
+        import httpx
+
+        res = httpx.delete(
+            f"{self._config.api_url}/api/sandboxes/{self.sandbox_id}",
+            headers=self._config.headers,
+        )
+        if res.status_code == 404:
+            return False
+        if not res.is_success:
+            from ..errors import handle_api_error
+            handle_api_error(res.status_code, res.text)
+        return True
+
+    def pause(self) -> bool:
+        """
+        Snapshot and pause the sandbox microVM.
+
+        The sandbox state — memory, filesystem, and running processes — is
+        saved to a snapshot. Resume with :meth:`resume` or
+        :meth:`Sandbox.connect`.
+
+        :returns: ``True`` if paused successfully.
+        """
+        import httpx
+
+        res = httpx.post(
+            f"{self._config.api_url}/api/sandboxes/{self.sandbox_id}/pause",
+            headers=self._config.headers,
+        )
+        if res.status_code == 404:
+            return False
+        if not res.is_success:
+            from ..errors import handle_api_error
+            handle_api_error(res.status_code, res.text)
+        return True
+
+    def resume(self) -> bool:
+        """
+        Resume a paused sandbox from its last snapshot.
+
+        :returns: ``True`` if resumed successfully.
+        """
+        import httpx
+
+        res = httpx.post(
+            f"{self._config.api_url}/api/sandboxes/{self.sandbox_id}/resume",
+            headers=self._config.headers,
+        )
+        if res.status_code == 404:
+            return False
+        if not res.is_success:
+            from ..errors import handle_api_error
+            handle_api_error(res.status_code, res.text)
+        return True
+
+    def set_timeout(self, timeout_ms: int) -> None:
+        """Extend or reduce the sandbox timeout."""
+        import httpx
+
+        res = httpx.post(
+            f"{self._config.api_url}/api/sandboxes/{self.sandbox_id}/timeout",
+            headers=self._config.headers,
+            json={"timeoutMs": timeout_ms},
+        )
+        if not res.is_success:
+            from ..errors import handle_api_error
+            handle_api_error(res.status_code, res.text)
+
+    def get_info(self) -> SandboxInfo:
+        """Get metadata and status information about this sandbox."""
+        import httpx
+
+        res = httpx.get(
+            f"{self._config.api_url}/api/sandboxes/{self.sandbox_id}",
+            headers=self._config.headers,
+        )
+        if not res.is_success:
+            from ..errors import handle_api_error
+            handle_api_error(res.status_code, res.text)
+
+        s = res.json()
+        return SandboxInfo(
+            sandbox_id=s["sandboxId"],
+            template=s["template"],
+            started_at=s["startedAt"],
+            end_at=s["endAt"],
+            metadata=s.get("metadata"),
+        )
+
+    def get_host(self, port: int) -> str:
+        """
+        Get the public HTTPS URL for a port exposed inside the sandbox.
+
+        Useful for reaching HTTP servers started inside the microVM from your
+        agent or tests without any additional tunneling.
+
+        :param port: Port number the service is listening on inside the microVM.
+
+        Example::
+
+            sandbox.process.exec_("npx -y serve -p 3000 &")
+            url = sandbox.get_host(3000)
+            # https://{sandboxId}-3000.sandbox.lizard.run
+        """
+        from urllib.parse import urlparse
+        api_host = urlparse(self._config.api_url).netloc
+        base_host = api_host.replace("api.", "", 1)
+        return f"{self.sandbox_id}-{port}.sandbox.{base_host}"
+
+    def __enter__(self) -> "Sandbox":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.kill()

lizard_sdk-0.1.1/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lizard-sdk"
+version = "0.1.1"
+description = "Lizard SDK — cloud sandboxes for AI agents"
+readme = {file = "README.md", content-type = "text/markdown"}
+license = { text = "Apache-2.0" }
+requires-python = ">=3.8"
+dependencies = [
+  "httpx>=0.24.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-asyncio", "mypy"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["lizard"]