@lizard-build/sdk 0.1.1 → 0.1.7

package/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

package/dist/index.d.mts

@@ -156,6 +156,10 @@ declare class SandboxClient {
     protected static listSandboxes(opts?: ConnectionOpts): Promise<SandboxInfo[]>;
     protected static getSandboxInfo(sandboxId: string, opts?: ConnectionOpts): Promise<SandboxInfo>;
     protected static setTimeoutSandbox(sandboxId: string, timeoutMs: number, opts?: ConnectionOpts): Promise<void>;
+    protected static exposeSandboxPort(sandboxId: string, port: number, opts?: ConnectionOpts): Promise<{
+        hostname: string;
+        url: string;
+    }>;
 }
 
 /**
@@ -308,7 +312,7 @@ declare class Sandbox extends SandboxClient {
      * // https://{sandboxId}-3000.sandbox.lizard.run
      * ```
      */
-    getHost(port: number): string;
+    getHost(port: number, opts?: ConnectionOpts): Promise<string>;
     private resolveOpts;
 }
 

package/dist/index.d.ts

@@ -156,6 +156,10 @@ declare class SandboxClient {
     protected static listSandboxes(opts?: ConnectionOpts): Promise<SandboxInfo[]>;
     protected static getSandboxInfo(sandboxId: string, opts?: ConnectionOpts): Promise<SandboxInfo>;
     protected static setTimeoutSandbox(sandboxId: string, timeoutMs: number, opts?: ConnectionOpts): Promise<void>;
+    protected static exposeSandboxPort(sandboxId: string, port: number, opts?: ConnectionOpts): Promise<{
+        hostname: string;
+        url: string;
+    }>;
 }
 
 /**
@@ -308,7 +312,7 @@ declare class Sandbox extends SandboxClient {
      * // https://{sandboxId}-3000.sandbox.lizard.run
      * ```
      */
-    getHost(port: number): string;
+    getHost(port: number, opts?: ConnectionOpts): Promise<string>;
     private resolveOpts;
 }
 

package/dist/index.js

@@ -301,6 +301,15 @@ var SandboxClient = class {
     });
     if (!res.ok) await handleApiError(res);
   }
+  static async exposeSandboxPort(sandboxId, port, opts) {
+    const config = new ConnectionConfig(opts);
+    const res = await fetch(`${config.apiUrl}/api/sandboxes/${sandboxId}/expose/${port}`, {
+      method: "POST",
+      headers: config.headers
+    });
+    if (!res.ok) await handleApiError(res);
+    return res.json();
+  }
 };
 
 // src/sandbox/index.ts
@@ -399,10 +408,9 @@ var Sandbox = class extends SandboxClient {
    * // https://{sandboxId}-3000.sandbox.lizard.run
    * ```
    */
-  getHost(port) {
-    const apiHost = new URL(this.connectionConfig.apiUrl).host;
-    const baseHost = apiHost.replace(/^api\./, "");
-    return `${this.sandboxId}-${port}.sandbox.${baseHost}`;
+  async getHost(port, opts) {
+    const { hostname } = await SandboxClient.exposeSandboxPort(this.sandboxId, port, this.resolveOpts(opts));
+    return hostname;
   }
   resolveOpts(opts) {
     return { ...this.connectionConfig, ...opts };
@@ -442,7 +450,7 @@ var Execution = class {
 var CODE_INTERPRETER_PORT = 8080;
 var CodeSandbox = class extends Sandbox {
   get serverUrl() {
-    return `https://${this.getHost(CODE_INTERPRETER_PORT)}`;
+    return this.getHost(CODE_INTERPRETER_PORT).then((h) => `https://${h}`);
   }
   /**
    * Execute code in a persistent kernel.
@@ -477,7 +485,7 @@ var CodeSandbox = class extends Sandbox {
     const controller = new AbortController();
     const timer = opts?.timeoutMs ? setTimeout(() => controller.abort(), opts.timeoutMs) : void 0;
     try {
-      const res = await fetch(`${this.serverUrl}/execute`, {
+      const res = await fetch(`${await this.serverUrl}/execute`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify(body),
@@ -537,7 +545,7 @@ var CodeSandbox = class extends Sandbox {
    * ```
    */
   async createContext(opts) {
-    const res = await fetch(`${this.serverUrl}/contexts`, {
+    const res = await fetch(`${await this.serverUrl}/contexts`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
@@ -552,7 +560,7 @@ var CodeSandbox = class extends Sandbox {
    * List all active execution contexts in this sandbox.
    */
   async listContexts() {
-    const res = await fetch(`${this.serverUrl}/contexts`);
+    const res = await fetch(`${await this.serverUrl}/contexts`);
     if (!res.ok) throw new Error(`Failed to list contexts: ${await res.text()}`);
     return res.json();
   }
@@ -561,7 +569,7 @@ var CodeSandbox = class extends Sandbox {
    */
   async deleteContext(context) {
     const id = typeof context === "string" ? context : context.id;
-    const res = await fetch(`${this.serverUrl}/contexts/${id}`, { method: "DELETE" });
+    const res = await fetch(`${await this.serverUrl}/contexts/${id}`, { method: "DELETE" });
     if (!res.ok) throw new Error(`Failed to delete context: ${await res.text()}`);
   }
   /**
@@ -569,7 +577,7 @@ var CodeSandbox = class extends Sandbox {
    */
   async restartContext(context) {
     const id = typeof context === "string" ? context : context.id;
-    const res = await fetch(`${this.serverUrl}/contexts/${id}/restart`, { method: "POST" });
+    const res = await fetch(`${await this.serverUrl}/contexts/${id}/restart`, { method: "POST" });
     if (!res.ok) throw new Error(`Failed to restart context: ${await res.text()}`);
   }
   static async create(templateOrOpts, opts) {

package/dist/index.mjs

@@ -270,6 +270,15 @@ var SandboxClient = class {
     });
     if (!res.ok) await handleApiError(res);
   }
+  static async exposeSandboxPort(sandboxId, port, opts) {
+    const config = new ConnectionConfig(opts);
+    const res = await fetch(`${config.apiUrl}/api/sandboxes/${sandboxId}/expose/${port}`, {
+      method: "POST",
+      headers: config.headers
+    });
+    if (!res.ok) await handleApiError(res);
+    return res.json();
+  }
 };
 
 // src/sandbox/index.ts
@@ -368,10 +377,9 @@ var Sandbox = class extends SandboxClient {
    * // https://{sandboxId}-3000.sandbox.lizard.run
    * ```
    */
-  getHost(port) {
-    const apiHost = new URL(this.connectionConfig.apiUrl).host;
-    const baseHost = apiHost.replace(/^api\./, "");
-    return `${this.sandboxId}-${port}.sandbox.${baseHost}`;
+  async getHost(port, opts) {
+    const { hostname } = await SandboxClient.exposeSandboxPort(this.sandboxId, port, this.resolveOpts(opts));
+    return hostname;
   }
   resolveOpts(opts) {
     return { ...this.connectionConfig, ...opts };
@@ -411,7 +419,7 @@ var Execution = class {
 var CODE_INTERPRETER_PORT = 8080;
 var CodeSandbox = class extends Sandbox {
   get serverUrl() {
-    return `https://${this.getHost(CODE_INTERPRETER_PORT)}`;
+    return this.getHost(CODE_INTERPRETER_PORT).then((h) => `https://${h}`);
   }
   /**
    * Execute code in a persistent kernel.
@@ -446,7 +454,7 @@ var CodeSandbox = class extends Sandbox {
     const controller = new AbortController();
     const timer = opts?.timeoutMs ? setTimeout(() => controller.abort(), opts.timeoutMs) : void 0;
     try {
-      const res = await fetch(`${this.serverUrl}/execute`, {
+      const res = await fetch(`${await this.serverUrl}/execute`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify(body),
@@ -506,7 +514,7 @@ var CodeSandbox = class extends Sandbox {
    * ```
    */
   async createContext(opts) {
-    const res = await fetch(`${this.serverUrl}/contexts`, {
+    const res = await fetch(`${await this.serverUrl}/contexts`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
@@ -521,7 +529,7 @@ var CodeSandbox = class extends Sandbox {
    * List all active execution contexts in this sandbox.
    */
   async listContexts() {
-    const res = await fetch(`${this.serverUrl}/contexts`);
+    const res = await fetch(`${await this.serverUrl}/contexts`);
     if (!res.ok) throw new Error(`Failed to list contexts: ${await res.text()}`);
     return res.json();
   }
@@ -530,7 +538,7 @@ var CodeSandbox = class extends Sandbox {
    */
   async deleteContext(context) {
     const id = typeof context === "string" ? context : context.id;
-    const res = await fetch(`${this.serverUrl}/contexts/${id}`, { method: "DELETE" });
+    const res = await fetch(`${await this.serverUrl}/contexts/${id}`, { method: "DELETE" });
     if (!res.ok) throw new Error(`Failed to delete context: ${await res.text()}`);
   }
   /**
@@ -538,7 +546,7 @@ var CodeSandbox = class extends Sandbox {
    */
   async restartContext(context) {
     const id = typeof context === "string" ? context : context.id;
-    const res = await fetch(`${this.serverUrl}/contexts/${id}/restart`, { method: "POST" });
+    const res = await fetch(`${await this.serverUrl}/contexts/${id}/restart`, { method: "POST" });
     if (!res.ok) throw new Error(`Failed to restart context: ${await res.text()}`);
   }
   static async create(templateOrOpts, opts) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lizard-build/sdk",
-  "version": "0.1.1",
+  "version": "0.1.7",
   "description": "Lizard SDK — cloud sandboxes for AI agents",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",