@lizard-build/sdk 0.1.23 → 0.1.25

package/README.md

@@ -2,7 +2,7 @@
 
 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.
+Each sandbox is an isolated microVM with its own filesystem, network, and process namespace. Sandboxes can be paused — vCPUs frozen, memory and running processes kept — and resumed instantly, so a long-running agent session picks up without re-running setup.
 
 ## Install
 
@@ -26,7 +26,7 @@ import { Lizard } from '@lizard-build/sdk'
 // apiKey defaults to the LIZARD_API_KEY env var.
 const lizard = new Lizard({ project: 'my-project' })
 
-// Boot a microVM from the 'base' template (Debian + Node.js 20)
+// Boot a microVM from the 'base' template (Debian + Node.js 26)
 const sandbox = await lizard.create('base')
 
 // Write a file directly into the microVM filesystem
@@ -82,7 +82,9 @@ 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.
+Sandboxes can be paused mid-execution and resumed exactly where they left off — including installed packages, in-memory state, and running processes. Pausing freezes the microVM's vCPUs; memory and processes stay in the host's RAM and are not written to disk, so a paused sandbox does not survive a host failure. This makes Lizard sandboxes well-suited for long-running AI agent workflows where you want to stop and continue across separate invocations.
+
+Pausing does not stop the sandbox timeout — a paused sandbox is still deleted at its original expiry (default 5 minutes). Pass `timeoutMs: 0` (`timeout_ms=0` in Python) at create time to opt out of expiry.
 
 ```ts
 // Boot and set up the environment once (reusing the `lizard` client from above)
@@ -91,7 +93,7 @@ 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)
+// Later — resume instantly (no reinstall needed)
 const resumed = await lizard.connect(id)
 const result = await resumed.process.exec('python -c "import sklearn; print(sklearn.__version__)"')
 console.log(result.stdout)
@@ -126,7 +128,7 @@ const sandbox = await lizard.create('code-interpreter-v1', { timeoutMs: 10 * 60
 
 ### `Sandbox.create(template?, opts?)`
 
-Boot a new Lizard microVM. Built-in templates: `base` (Debian + Node.js 20) and `code-interpreter-v1` (Python 3.11 + Node.js 20). Custom templates can be pushed via `lizard push`. A project is required — pass `project` (ID, slug, or name) or an exact `projectId` in `opts`, or use a `Lizard` client, which pins one for you.
+Boot a new Lizard microVM. Built-in templates: `base` (Debian + Node.js 26) and `code-interpreter-v1` (Python 3.14 + Node.js 26). Custom templates can be pushed via `lizard push`. A project is required — pass `project` (ID, slug, or name) or an exact `projectId` in `opts`, or use a `Lizard` client, which pins one for you.
 
 ```ts
 const sandbox = await Sandbox.create('base', { project: 'my-project' })
@@ -135,7 +137,7 @@ const sandbox = await Sandbox.create('code-interpreter-v1', { project: 'my-proje
 
 ### `Sandbox.connect(sandboxId, opts?)`
 
-Connect to an existing sandbox by ID. If the sandbox is paused, it is automatically resumed from its last snapshot.
+Connect to an existing sandbox by ID. If the sandbox is paused, it is automatically resumed.
 
 ### `Sandbox.list(opts?)`
 
@@ -177,7 +179,7 @@ const url = sandbox.getHost(3000)
 
 ### `sandbox.pause()` / `sandbox.resume()`
 
-Snapshot and restore the microVM state. Useful for checkpointing long agent sessions.
+Freeze and unfreeze the microVM's vCPUs. Memory and running processes are kept in the host's RAM, not written to disk. The timeout keeps running while paused.
 
 ### `sandbox.kill()`
 

package/dist/index.d.mts

@@ -177,12 +177,13 @@ declare class SandboxClient {
  *
  * Each sandbox is a full Linux environment with its own filesystem, network,
  * and process namespace. Sandboxes are spun up from templates and can be
- * paused to a snapshot, then resumed instantly — perfect for stateful AI
- * agent sessions or ephemeral code execution.
+ * paused — vCPUs frozen, memory and running processes kept — then resumed
+ * instantly, perfect for stateful AI agent sessions or ephemeral code
+ * execution.
  *
  * @example Basic usage:
  * ```ts
- * import { Sandbox } from 'lizard'
+ * import { Sandbox } from '@lizard-build/sdk'
  *
  * const sandbox = await Sandbox.create('base', { project: 'my-project' })
  * await sandbox.fs.write('/app/index.js', 'console.log("hello world")')
@@ -245,8 +246,8 @@ declare class Sandbox extends SandboxClient {
     /**
      * Create a new Lizard sandbox from the specified template.
      *
-     * Available templates: `base` (Debian + Node.js 20) and `code-interpreter-v1`
-     * (Python 3.11 + Node.js 20). Custom templates can be built and pushed via
+     * Available templates: `base` (Debian + Node.js 26) and `code-interpreter-v1`
+     * (Python 3.14 + Node.js 26). Custom templates can be built and pushed via
      * `lizard push`.
      *
      * @param template Name of the sandbox template to boot from.
@@ -262,7 +263,7 @@ declare class Sandbox extends SandboxClient {
      * Connect to an existing sandbox by its ID.
      *
      * If the sandbox is currently paused, it will be automatically resumed
-     * from its last snapshot before this call returns.
+     * before this call returns.
      *
      * @example
      * ```ts
@@ -286,16 +287,21 @@ declare class Sandbox extends SandboxClient {
      */
     kill(opts?: ConnectionOpts): Promise<boolean>;
     /**
-     * Snapshot and pause the sandbox microVM.
+     * Pause the sandbox microVM by freezing its vCPUs.
      *
-     * The sandbox state — memory, filesystem, and running processes — is saved
-     * to a snapshot. Resume with `sandbox.resume()` or `Sandbox.connect(id)`.
+     * Memory, filesystem, and running processes are held in the host's RAM —
+     * nothing is written to disk, so a paused sandbox does not survive a host
+     * failure. Resume with `sandbox.resume()` or `Sandbox.connect(id)`.
+     *
+     * Pausing does not stop the timeout: a paused sandbox is still deleted at
+     * its original expiry (default 5 minutes). Pass `timeoutMs: 0` at create
+     * time to opt out of expiry.
      *
      * @returns `true` if paused successfully.
      */
     pause(opts?: ConnectionOpts): Promise<boolean>;
     /**
-     * Resume a paused sandbox from its last snapshot.
+     * Resume a paused sandbox by unfreezing its vCPUs.
      *
      * @returns `true` if resumed successfully.
      */
@@ -494,7 +500,7 @@ declare class ServicesAPI {
         limit?: number;
         since?: string;
     }): Promise<LogLine[]>;
-    /** Execute a command inside the running service VM. */
+    /** Execute a command inside the running service container. */
     exec(id: string, cmd: string, opts?: {
         timeoutMs?: number;
     }): Promise<{

package/dist/index.d.ts

@@ -177,12 +177,13 @@ declare class SandboxClient {
  *
  * Each sandbox is a full Linux environment with its own filesystem, network,
  * and process namespace. Sandboxes are spun up from templates and can be
- * paused to a snapshot, then resumed instantly — perfect for stateful AI
- * agent sessions or ephemeral code execution.
+ * paused — vCPUs frozen, memory and running processes kept — then resumed
+ * instantly, perfect for stateful AI agent sessions or ephemeral code
+ * execution.
  *
  * @example Basic usage:
  * ```ts
- * import { Sandbox } from 'lizard'
+ * import { Sandbox } from '@lizard-build/sdk'
  *
  * const sandbox = await Sandbox.create('base', { project: 'my-project' })
  * await sandbox.fs.write('/app/index.js', 'console.log("hello world")')
@@ -245,8 +246,8 @@ declare class Sandbox extends SandboxClient {
     /**
      * Create a new Lizard sandbox from the specified template.
      *
-     * Available templates: `base` (Debian + Node.js 20) and `code-interpreter-v1`
-     * (Python 3.11 + Node.js 20). Custom templates can be built and pushed via
+     * Available templates: `base` (Debian + Node.js 26) and `code-interpreter-v1`
+     * (Python 3.14 + Node.js 26). Custom templates can be built and pushed via
      * `lizard push`.
      *
      * @param template Name of the sandbox template to boot from.
@@ -262,7 +263,7 @@ declare class Sandbox extends SandboxClient {
      * Connect to an existing sandbox by its ID.
      *
      * If the sandbox is currently paused, it will be automatically resumed
-     * from its last snapshot before this call returns.
+     * before this call returns.
      *
      * @example
      * ```ts
@@ -286,16 +287,21 @@ declare class Sandbox extends SandboxClient {
      */
     kill(opts?: ConnectionOpts): Promise<boolean>;
     /**
-     * Snapshot and pause the sandbox microVM.
+     * Pause the sandbox microVM by freezing its vCPUs.
      *
-     * The sandbox state — memory, filesystem, and running processes — is saved
-     * to a snapshot. Resume with `sandbox.resume()` or `Sandbox.connect(id)`.
+     * Memory, filesystem, and running processes are held in the host's RAM —
+     * nothing is written to disk, so a paused sandbox does not survive a host
+     * failure. Resume with `sandbox.resume()` or `Sandbox.connect(id)`.
+     *
+     * Pausing does not stop the timeout: a paused sandbox is still deleted at
+     * its original expiry (default 5 minutes). Pass `timeoutMs: 0` at create
+     * time to opt out of expiry.
      *
      * @returns `true` if paused successfully.
      */
     pause(opts?: ConnectionOpts): Promise<boolean>;
     /**
-     * Resume a paused sandbox from its last snapshot.
+     * Resume a paused sandbox by unfreezing its vCPUs.
      *
      * @returns `true` if resumed successfully.
      */
@@ -494,7 +500,7 @@ declare class ServicesAPI {
         limit?: number;
         since?: string;
     }): Promise<LogLine[]>;
-    /** Execute a command inside the running service VM. */
+    /** Execute a command inside the running service container. */
     exec(id: string, cmd: string, opts?: {
         timeoutMs?: number;
     }): Promise<{

package/dist/index.js

@@ -370,7 +370,7 @@ var Sandbox = class extends SandboxClient {
    * Connect to an existing sandbox by its ID.
    *
    * If the sandbox is currently paused, it will be automatically resumed
-   * from its last snapshot before this call returns.
+   * before this call returns.
    *
    * @example
    * ```ts
@@ -401,10 +401,15 @@ var Sandbox = class extends SandboxClient {
     return SandboxClient.killSandbox(this.sandboxId, this.resolveOpts(opts));
   }
   /**
-   * Snapshot and pause the sandbox microVM.
+   * Pause the sandbox microVM by freezing its vCPUs.
    *
-   * The sandbox state — memory, filesystem, and running processes — is saved
-   * to a snapshot. Resume with `sandbox.resume()` or `Sandbox.connect(id)`.
+   * Memory, filesystem, and running processes are held in the host's RAM —
+   * nothing is written to disk, so a paused sandbox does not survive a host
+   * failure. Resume with `sandbox.resume()` or `Sandbox.connect(id)`.
+   *
+   * Pausing does not stop the timeout: a paused sandbox is still deleted at
+   * its original expiry (default 5 minutes). Pass `timeoutMs: 0` at create
+   * time to opt out of expiry.
    *
    * @returns `true` if paused successfully.
    */
@@ -412,7 +417,7 @@ var Sandbox = class extends SandboxClient {
     return SandboxClient.pauseSandbox(this.sandboxId, this.resolveOpts(opts));
   }
   /**
-   * Resume a paused sandbox from its last snapshot.
+   * Resume a paused sandbox by unfreezing its vCPUs.
    *
    * @returns `true` if resumed successfully.
    */
@@ -674,7 +679,7 @@ var ServicesAPI = class {
     const result = await this.client.get(`/api/apps/${id}/logs?${qs}`);
     return Array.isArray(result) ? result : result.logs ?? [];
   }
-  /** Execute a command inside the running service VM. */
+  /** Execute a command inside the running service container. */
   exec(id, cmd, opts) {
     return this.client.post(`/api/apps/${id}/exec`, { cmd, timeoutMs: opts?.timeoutMs });
   }

package/dist/index.mjs

@@ -335,7 +335,7 @@ var Sandbox = class extends SandboxClient {
    * Connect to an existing sandbox by its ID.
    *
    * If the sandbox is currently paused, it will be automatically resumed
-   * from its last snapshot before this call returns.
+   * before this call returns.
    *
    * @example
    * ```ts
@@ -366,10 +366,15 @@ var Sandbox = class extends SandboxClient {
     return SandboxClient.killSandbox(this.sandboxId, this.resolveOpts(opts));
   }
   /**
-   * Snapshot and pause the sandbox microVM.
+   * Pause the sandbox microVM by freezing its vCPUs.
    *
-   * The sandbox state — memory, filesystem, and running processes — is saved
-   * to a snapshot. Resume with `sandbox.resume()` or `Sandbox.connect(id)`.
+   * Memory, filesystem, and running processes are held in the host's RAM —
+   * nothing is written to disk, so a paused sandbox does not survive a host
+   * failure. Resume with `sandbox.resume()` or `Sandbox.connect(id)`.
+   *
+   * Pausing does not stop the timeout: a paused sandbox is still deleted at
+   * its original expiry (default 5 minutes). Pass `timeoutMs: 0` at create
+   * time to opt out of expiry.
    *
    * @returns `true` if paused successfully.
    */
@@ -377,7 +382,7 @@ var Sandbox = class extends SandboxClient {
     return SandboxClient.pauseSandbox(this.sandboxId, this.resolveOpts(opts));
   }
   /**
-   * Resume a paused sandbox from its last snapshot.
+   * Resume a paused sandbox by unfreezing its vCPUs.
    *
    * @returns `true` if resumed successfully.
    */
@@ -639,7 +644,7 @@ var ServicesAPI = class {
     const result = await this.client.get(`/api/apps/${id}/logs?${qs}`);
     return Array.isArray(result) ? result : result.logs ?? [];
   }
-  /** Execute a command inside the running service VM. */
+  /** Execute a command inside the running service container. */
   exec(id, cmd, opts) {
     return this.client.post(`/api/apps/${id}/exec`, { cmd, timeoutMs: opts?.timeoutMs });
   }

package/package.json

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