@lizard-build/sdk 0.1.44 → 0.1.46

package/README.md

@@ -79,7 +79,7 @@ Pass `timeoutMs` to `create()` to set the sandbox lifetime. The default is five
 
 ## Runtime limits
 
-Sandboxes run on Kubernetes. Use volumes mounted at `/workspace` to keep files after a sandbox ends. Pause, resume, fork, snapshot creation, snapshot restore, and file watching return HTTP 501 on the current backend.
+Sandboxes run on Kubernetes. Use volumes mounted at `/workspace` to keep files after a sandbox ends. CRIU pause/resume and private snapshots preserve running memory and workspace files. Snapshot pools keep five copies warm by default and can be paused to release idle compute. Fork and file watching remain unsupported. See the [snapshot lifecycle guide](../../docs/sandboxes.md#snapshots-and-criu-pause-resume).
 
 `getHost()` returns a hostname without `https://`. File writes accept UTF-8 text or valid UTF-8 bytes; `readBytes()` supports binary downloads.
 

package/dist/index.d.mts

@@ -650,6 +650,9 @@ interface SandboxInfo {
     /** Region the sandbox runs in — the volume's region when one is attached. */
     region?: string;
     status?: string;
+    pauseError?: string | null;
+    size?: 'small' | 'medium' | 'large' | null;
+    pricePerHour?: number | null;
     cpus?: number;
     memoryMb?: number;
     metadata?: Record<string, string>;
@@ -665,6 +668,8 @@ interface SandboxOpts extends ConnectionOpts {
     /** Exact project ID — skips resolving {@link SandboxOpts.project}. */
     projectId?: string;
     template?: string;
+    snapshotId?: string;
+    size?: 'small' | 'medium' | 'large';
     metadata?: Record<string, string>;
     envs?: Record<string, string>;
     timeoutMs?: number;
@@ -731,6 +736,27 @@ declare class SandboxClient {
     }>;
 }
 
+interface SandboxSnapshot {
+    id: string;
+    name: string;
+    projectId: string;
+    workspaceId: string;
+    region: string;
+    sourceSandboxId: string;
+    status: 'building' | 'warming' | 'ready' | 'paused' | 'suspended' | 'failed';
+    poolSize: number;
+    readyCount: number;
+    error: string | null;
+    cpus: number;
+    memoryMb: number;
+    createdAt: number;
+}
+interface SnapshotOpts {
+    poolSize?: number;
+}
+interface SnapshotWaitOpts extends ConnectionOpts {
+    waitTimeoutMs?: number;
+}
 /**
  * A Linux sandbox running on Kubernetes.
  *
@@ -856,20 +882,12 @@ declare class Sandbox extends SandboxClient {
      * @returns `true` if the sandbox was terminated, `false` if it was already gone.
      */
     kill(opts?: ConnectionOpts): Promise<boolean>;
-    /**
-     * Request sandbox pause. The Kubernetes backend returns HTTP 501.
-     *
-     * @deprecated Unsupported on Kubernetes. Save files to a {@link Volume}
-     * and attach it to a new sandbox instead.
-     */
+    /** Queue a CRIU checkpoint and stop compute. Use waitForStatus('paused') before resuming. */
     pause(opts?: ConnectionOpts): Promise<boolean>;
-    /**
-     * Request sandbox resume. The Kubernetes backend returns HTTP 501.
-     *
-     * @deprecated Unsupported on Kubernetes. Use {@link Sandbox.connect} to
-     * reconnect to a running sandbox.
-     */
+    /** Queue restoration of saved memory and files. Use waitForStatus('running') before executing. */
     resume(opts?: ConnectionOpts): Promise<boolean>;
+    /** Wait for an asynchronous pause/resume operation to finish. */
+    waitForStatus(status: 'paused' | 'running', opts?: SnapshotWaitOpts): Promise<SandboxInfo>;
     /**
      * Get metadata and status information about this sandbox.
      */
@@ -899,18 +917,25 @@ declare class Sandbox extends SandboxClient {
         count?: number;
         timeoutMs?: number;
     }): Promise<unknown>;
-    /** Snapshot creation is unsupported on Kubernetes; the backend returns HTTP 501. */
-    snapshot(name?: string): Promise<unknown>;
+    /** Capture memory and workspace files. Disconnect active clients before capturing. */
+    snapshot(name?: string, opts?: SnapshotOpts): Promise<SandboxSnapshot>;
     unexpose(port: number): Promise<void>;
     logs(opts?: {
         tail?: number;
         signal?: AbortSignal;
     }): AsyncGenerator<StreamEvent, any, any>;
-    static snapshots(projectId: string, opts?: ConnectionOpts): Promise<unknown[]>;
-    /** Snapshot restore is unsupported on Kubernetes; the backend returns HTTP 501. */
+    static snapshots(projectId: string, opts?: ConnectionOpts): Promise<SandboxSnapshot[]>;
+    static getSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<SandboxSnapshot>;
+    /** Start a sandbox from an available warm copy in the snapshot's project and region. */
     static restore(snapshotId: string, opts?: ConnectionOpts & {
         timeoutMs?: number;
     }): Promise<Sandbox>;
+    static setSnapshotWarmPool(snapshotId: string, poolSize: number, opts?: ConnectionOpts): Promise<SandboxSnapshot>;
+    /** Release idle warm copies; retain saved state and existing claimed sandboxes. */
+    static pauseSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<SandboxSnapshot>;
+    /** Refill the configured warm pool without another capture. */
+    static resumeSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<SandboxSnapshot>;
+    static waitForSnapshot(snapshotId: string, opts?: SnapshotWaitOpts): Promise<SandboxSnapshot>;
     static deleteSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<void>;
     private resolveOpts;
 }
@@ -1773,4 +1798,4 @@ declare class LizardCLI {
     }): Promise<CLIResult>;
 }
 
-export { type Account, type Addon, type AddonType, AddonsAPI, type ApiKey, type ApiKeyScope, ApiKeysAPI, AuthenticationError, type Balance, BillingAPI, type CLIOptions, type CLIResult, type CodeContext, CodeSandbox, ConfigApplyError, type ConfigResult, ConflictError, type ConnectionOpts, type CostMetrics, type CreateAddonOpts, type CreateApiKeyOpts, type CreateContextOpts, type CreateProjectOpts, type CreateServiceOpts, type CreateVolumeOpts, type CreateWorkspaceOpts, type CreatedApiKey, type DeployEvent, DeployHandle, type DomainInfo, type DomainStatus, DomainsAPI, Execution, ExecutionError, type FileInfo, type FsOpts, GitHubAPI, type ListTransactionsOpts, Lizard, LizardCLI, LizardError, type LizardOpts, type LogLine, type MetricPoint, type MetricRange, MetricsAPI, NotFoundError, PlatformClient, type ProcessOpts, type ProcessResult, type Project, type ProjectConfig, type ProjectCost, ProjectsAPI, type RawMetrics, type Region, RegionsAPI, type RunCodeLanguage, type RunCodeOpts, Sandbox, type SandboxInfo, type SandboxOpts, type ScaleOpts, type Secret, SecretsAPI, type Service, type ServiceMetrics, type ServiceUpdate, ServicesAPI, type SetSecretOpts, StorageAPI, type StreamEvent, TimeoutError, type Transaction, type TransactionPage, Volume, type VolumeInfo, type Workspace, WorkspacesAPI, resolveProjectId };
+export { type Account, type Addon, type AddonType, AddonsAPI, type ApiKey, type ApiKeyScope, ApiKeysAPI, AuthenticationError, type Balance, BillingAPI, type CLIOptions, type CLIResult, type CodeContext, CodeSandbox, ConfigApplyError, type ConfigResult, ConflictError, type ConnectionOpts, type CostMetrics, type CreateAddonOpts, type CreateApiKeyOpts, type CreateContextOpts, type CreateProjectOpts, type CreateServiceOpts, type CreateVolumeOpts, type CreateWorkspaceOpts, type CreatedApiKey, type DeployEvent, DeployHandle, type DomainInfo, type DomainStatus, DomainsAPI, Execution, ExecutionError, type FileInfo, type FsOpts, GitHubAPI, type ListTransactionsOpts, Lizard, LizardCLI, LizardError, type LizardOpts, type LogLine, type MetricPoint, type MetricRange, MetricsAPI, NotFoundError, PlatformClient, type ProcessOpts, type ProcessResult, type Project, type ProjectConfig, type ProjectCost, ProjectsAPI, type RawMetrics, type Region, RegionsAPI, type RunCodeLanguage, type RunCodeOpts, Sandbox, type SandboxInfo, type SandboxOpts, type SandboxSnapshot, type ScaleOpts, type Secret, SecretsAPI, type Service, type ServiceMetrics, type ServiceUpdate, ServicesAPI, type SetSecretOpts, type SnapshotOpts, type SnapshotWaitOpts, StorageAPI, type StreamEvent, TimeoutError, type Transaction, type TransactionPage, Volume, type VolumeInfo, type Workspace, WorkspacesAPI, resolveProjectId };

package/dist/index.d.ts

@@ -650,6 +650,9 @@ interface SandboxInfo {
     /** Region the sandbox runs in — the volume's region when one is attached. */
     region?: string;
     status?: string;
+    pauseError?: string | null;
+    size?: 'small' | 'medium' | 'large' | null;
+    pricePerHour?: number | null;
     cpus?: number;
     memoryMb?: number;
     metadata?: Record<string, string>;
@@ -665,6 +668,8 @@ interface SandboxOpts extends ConnectionOpts {
     /** Exact project ID — skips resolving {@link SandboxOpts.project}. */
     projectId?: string;
     template?: string;
+    snapshotId?: string;
+    size?: 'small' | 'medium' | 'large';
     metadata?: Record<string, string>;
     envs?: Record<string, string>;
     timeoutMs?: number;
@@ -731,6 +736,27 @@ declare class SandboxClient {
     }>;
 }
 
+interface SandboxSnapshot {
+    id: string;
+    name: string;
+    projectId: string;
+    workspaceId: string;
+    region: string;
+    sourceSandboxId: string;
+    status: 'building' | 'warming' | 'ready' | 'paused' | 'suspended' | 'failed';
+    poolSize: number;
+    readyCount: number;
+    error: string | null;
+    cpus: number;
+    memoryMb: number;
+    createdAt: number;
+}
+interface SnapshotOpts {
+    poolSize?: number;
+}
+interface SnapshotWaitOpts extends ConnectionOpts {
+    waitTimeoutMs?: number;
+}
 /**
  * A Linux sandbox running on Kubernetes.
  *
@@ -856,20 +882,12 @@ declare class Sandbox extends SandboxClient {
      * @returns `true` if the sandbox was terminated, `false` if it was already gone.
      */
     kill(opts?: ConnectionOpts): Promise<boolean>;
-    /**
-     * Request sandbox pause. The Kubernetes backend returns HTTP 501.
-     *
-     * @deprecated Unsupported on Kubernetes. Save files to a {@link Volume}
-     * and attach it to a new sandbox instead.
-     */
+    /** Queue a CRIU checkpoint and stop compute. Use waitForStatus('paused') before resuming. */
     pause(opts?: ConnectionOpts): Promise<boolean>;
-    /**
-     * Request sandbox resume. The Kubernetes backend returns HTTP 501.
-     *
-     * @deprecated Unsupported on Kubernetes. Use {@link Sandbox.connect} to
-     * reconnect to a running sandbox.
-     */
+    /** Queue restoration of saved memory and files. Use waitForStatus('running') before executing. */
     resume(opts?: ConnectionOpts): Promise<boolean>;
+    /** Wait for an asynchronous pause/resume operation to finish. */
+    waitForStatus(status: 'paused' | 'running', opts?: SnapshotWaitOpts): Promise<SandboxInfo>;
     /**
      * Get metadata and status information about this sandbox.
      */
@@ -899,18 +917,25 @@ declare class Sandbox extends SandboxClient {
         count?: number;
         timeoutMs?: number;
     }): Promise<unknown>;
-    /** Snapshot creation is unsupported on Kubernetes; the backend returns HTTP 501. */
-    snapshot(name?: string): Promise<unknown>;
+    /** Capture memory and workspace files. Disconnect active clients before capturing. */
+    snapshot(name?: string, opts?: SnapshotOpts): Promise<SandboxSnapshot>;
     unexpose(port: number): Promise<void>;
     logs(opts?: {
         tail?: number;
         signal?: AbortSignal;
     }): AsyncGenerator<StreamEvent, any, any>;
-    static snapshots(projectId: string, opts?: ConnectionOpts): Promise<unknown[]>;
-    /** Snapshot restore is unsupported on Kubernetes; the backend returns HTTP 501. */
+    static snapshots(projectId: string, opts?: ConnectionOpts): Promise<SandboxSnapshot[]>;
+    static getSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<SandboxSnapshot>;
+    /** Start a sandbox from an available warm copy in the snapshot's project and region. */
     static restore(snapshotId: string, opts?: ConnectionOpts & {
         timeoutMs?: number;
     }): Promise<Sandbox>;
+    static setSnapshotWarmPool(snapshotId: string, poolSize: number, opts?: ConnectionOpts): Promise<SandboxSnapshot>;
+    /** Release idle warm copies; retain saved state and existing claimed sandboxes. */
+    static pauseSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<SandboxSnapshot>;
+    /** Refill the configured warm pool without another capture. */
+    static resumeSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<SandboxSnapshot>;
+    static waitForSnapshot(snapshotId: string, opts?: SnapshotWaitOpts): Promise<SandboxSnapshot>;
     static deleteSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<void>;
     private resolveOpts;
 }
@@ -1773,4 +1798,4 @@ declare class LizardCLI {
     }): Promise<CLIResult>;
 }
 
-export { type Account, type Addon, type AddonType, AddonsAPI, type ApiKey, type ApiKeyScope, ApiKeysAPI, AuthenticationError, type Balance, BillingAPI, type CLIOptions, type CLIResult, type CodeContext, CodeSandbox, ConfigApplyError, type ConfigResult, ConflictError, type ConnectionOpts, type CostMetrics, type CreateAddonOpts, type CreateApiKeyOpts, type CreateContextOpts, type CreateProjectOpts, type CreateServiceOpts, type CreateVolumeOpts, type CreateWorkspaceOpts, type CreatedApiKey, type DeployEvent, DeployHandle, type DomainInfo, type DomainStatus, DomainsAPI, Execution, ExecutionError, type FileInfo, type FsOpts, GitHubAPI, type ListTransactionsOpts, Lizard, LizardCLI, LizardError, type LizardOpts, type LogLine, type MetricPoint, type MetricRange, MetricsAPI, NotFoundError, PlatformClient, type ProcessOpts, type ProcessResult, type Project, type ProjectConfig, type ProjectCost, ProjectsAPI, type RawMetrics, type Region, RegionsAPI, type RunCodeLanguage, type RunCodeOpts, Sandbox, type SandboxInfo, type SandboxOpts, type ScaleOpts, type Secret, SecretsAPI, type Service, type ServiceMetrics, type ServiceUpdate, ServicesAPI, type SetSecretOpts, StorageAPI, type StreamEvent, TimeoutError, type Transaction, type TransactionPage, Volume, type VolumeInfo, type Workspace, WorkspacesAPI, resolveProjectId };
+export { type Account, type Addon, type AddonType, AddonsAPI, type ApiKey, type ApiKeyScope, ApiKeysAPI, AuthenticationError, type Balance, BillingAPI, type CLIOptions, type CLIResult, type CodeContext, CodeSandbox, ConfigApplyError, type ConfigResult, ConflictError, type ConnectionOpts, type CostMetrics, type CreateAddonOpts, type CreateApiKeyOpts, type CreateContextOpts, type CreateProjectOpts, type CreateServiceOpts, type CreateVolumeOpts, type CreateWorkspaceOpts, type CreatedApiKey, type DeployEvent, DeployHandle, type DomainInfo, type DomainStatus, DomainsAPI, Execution, ExecutionError, type FileInfo, type FsOpts, GitHubAPI, type ListTransactionsOpts, Lizard, LizardCLI, LizardError, type LizardOpts, type LogLine, type MetricPoint, type MetricRange, MetricsAPI, NotFoundError, PlatformClient, type ProcessOpts, type ProcessResult, type Project, type ProjectConfig, type ProjectCost, ProjectsAPI, type RawMetrics, type Region, RegionsAPI, type RunCodeLanguage, type RunCodeOpts, Sandbox, type SandboxInfo, type SandboxOpts, type SandboxSnapshot, type ScaleOpts, type Secret, SecretsAPI, type Service, type ServiceMetrics, type ServiceUpdate, ServicesAPI, type SetSecretOpts, type SnapshotOpts, type SnapshotWaitOpts, StorageAPI, type StreamEvent, TimeoutError, type Transaction, type TransactionPage, Volume, type VolumeInfo, type Workspace, WorkspacesAPI, resolveProjectId };

package/dist/index.js

@@ -849,6 +849,8 @@ var SandboxClient = class {
       headers: config.headers,
       body: JSON.stringify({
         template,
+        snapshotId: opts?.snapshotId,
+        size: opts?.size,
         timeoutMs,
         projectId,
         metadata: opts?.metadata,
@@ -981,24 +983,28 @@ var Sandbox = class extends SandboxClient {
   async kill(opts) {
     return SandboxClient.killSandbox(this.sandboxId, this.resolveOpts(opts));
   }
-  /**
-   * Request sandbox pause. The Kubernetes backend returns HTTP 501.
-   *
-   * @deprecated Unsupported on Kubernetes. Save files to a {@link Volume}
-   * and attach it to a new sandbox instead.
-   */
+  /** Queue a CRIU checkpoint and stop compute. Use waitForStatus('paused') before resuming. */
   async pause(opts) {
     return SandboxClient.pauseSandbox(this.sandboxId, this.resolveOpts(opts));
   }
-  /**
-   * Request sandbox resume. The Kubernetes backend returns HTTP 501.
-   *
-   * @deprecated Unsupported on Kubernetes. Use {@link Sandbox.connect} to
-   * reconnect to a running sandbox.
-   */
+  /** Queue restoration of saved memory and files. Use waitForStatus('running') before executing. */
   async resume(opts) {
     return SandboxClient.resumeSandbox(this.sandboxId, this.resolveOpts(opts));
   }
+  /** Wait for an asynchronous pause/resume operation to finish. */
+  async waitForStatus(status, opts) {
+    const deadline = Date.now() + (opts?.waitTimeoutMs ?? 6e5);
+    do {
+      const info = await this.getInfo(opts);
+      if (info.status === status) return info;
+      if (["failed", "stopped", "deleted"].includes(info.status ?? "") || info.pauseError) {
+        throw new ConflictError(info.pauseError ?? `Sandbox is ${info.status}`);
+      }
+      if (Date.now() >= deadline) break;
+      await new Promise((resolve) => setTimeout(resolve, 1e3));
+    } while (Date.now() < deadline);
+    throw new TimeoutError(`Sandbox did not become ${status} within the wait timeout`);
+  }
   /**
    * Get metadata and status information about this sandbox.
    */
@@ -1034,9 +1040,9 @@ var Sandbox = class extends SandboxClient {
   fork(opts = {}) {
     return new PlatformClient(this.resolveOpts()).post(`/api/sandboxes/${this.sandboxId}/fork`, { count: opts.count ?? 1, timeoutMs: opts.timeoutMs ?? 0 });
   }
-  /** Snapshot creation is unsupported on Kubernetes; the backend returns HTTP 501. */
-  snapshot(name) {
-    return new PlatformClient(this.resolveOpts()).post(`/api/sandboxes/${this.sandboxId}/snapshot`, { name });
+  /** Capture memory and workspace files. Disconnect active clients before capturing. */
+  snapshot(name = `Snapshot ${this.sandboxId}`, opts = {}) {
+    return new PlatformClient(this.resolveOpts()).post(`/api/sandboxes/${this.sandboxId}/snapshot`, { name, poolSize: opts.poolSize ?? 5 });
   }
   unexpose(port) {
     return new PlatformClient(this.resolveOpts()).delete(`/api/sandboxes/${this.sandboxId}/expose/${port}`);
@@ -1045,13 +1051,45 @@ var Sandbox = class extends SandboxClient {
     return new PlatformClient(this.resolveOpts()).events(query(`/api/sandboxes/${this.sandboxId}/logs`, { tail: opts.tail }), { signal: opts.signal });
   }
   static snapshots(projectId, opts) {
-    return new PlatformClient(opts ?? {}).get(`/api/projects/${projectId}/snapshots`);
+    return new PlatformClient(opts ?? {}).get(`/api/projects/${encodeURIComponent(projectId)}/snapshots`);
+  }
+  static getSnapshot(snapshotId, opts) {
+    return new PlatformClient(opts ?? {}).get(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}`);
   }
-  /** Snapshot restore is unsupported on Kubernetes; the backend returns HTTP 501. */
+  /** Start a sandbox from an available warm copy in the snapshot's project and region. */
   static async restore(snapshotId, opts) {
-    const result = await new PlatformClient(opts ?? {}).post(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}/fork`, { timeoutMs: opts?.timeoutMs ?? 0 });
+    const client = new PlatformClient(opts ?? {});
+    const snapshot = await this.getSnapshot(snapshotId, opts);
+    const result = await client.post("/api/sandboxes", {
+      snapshotId,
+      projectId: snapshot.projectId,
+      region: snapshot.region,
+      timeoutMs: opts?.timeoutMs ?? DEFAULT_SANDBOX_TIMEOUT_MS
+    });
     return new this({ ...opts, sandboxId: result.sandboxId ?? result.id });
   }
+  static setSnapshotWarmPool(snapshotId, poolSize, opts) {
+    return new PlatformClient(opts ?? {}).patch(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}`, { poolSize });
+  }
+  /** Release idle warm copies; retain saved state and existing claimed sandboxes. */
+  static pauseSnapshot(snapshotId, opts) {
+    return new PlatformClient(opts ?? {}).post(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}/pause`, {});
+  }
+  /** Refill the configured warm pool without another capture. */
+  static resumeSnapshot(snapshotId, opts) {
+    return new PlatformClient(opts ?? {}).post(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}/resume`, {});
+  }
+  static async waitForSnapshot(snapshotId, opts) {
+    const deadline = Date.now() + (opts?.waitTimeoutMs ?? 9e5);
+    do {
+      const snapshot = await this.getSnapshot(snapshotId, opts);
+      if (snapshot.status === "ready" && snapshot.readyCount >= Math.max(1, snapshot.poolSize ?? 1)) return snapshot;
+      if (["failed", "paused", "suspended"].includes(snapshot.status)) throw new ConflictError(snapshot.error ?? `Snapshot is ${snapshot.status}`);
+      if (Date.now() >= deadline) break;
+      await new Promise((resolve) => setTimeout(resolve, 1e3));
+    } while (Date.now() < deadline);
+    throw new TimeoutError("Snapshot did not become ready within the wait timeout");
+  }
   static deleteSnapshot(snapshotId, opts) {
     return new PlatformClient(opts ?? {}).delete(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}`);
   }

package/dist/index.mjs

@@ -798,6 +798,8 @@ var SandboxClient = class {
       headers: config.headers,
       body: JSON.stringify({
         template,
+        snapshotId: opts?.snapshotId,
+        size: opts?.size,
         timeoutMs,
         projectId,
         metadata: opts?.metadata,
@@ -930,24 +932,28 @@ var Sandbox = class extends SandboxClient {
   async kill(opts) {
     return SandboxClient.killSandbox(this.sandboxId, this.resolveOpts(opts));
   }
-  /**
-   * Request sandbox pause. The Kubernetes backend returns HTTP 501.
-   *
-   * @deprecated Unsupported on Kubernetes. Save files to a {@link Volume}
-   * and attach it to a new sandbox instead.
-   */
+  /** Queue a CRIU checkpoint and stop compute. Use waitForStatus('paused') before resuming. */
   async pause(opts) {
     return SandboxClient.pauseSandbox(this.sandboxId, this.resolveOpts(opts));
   }
-  /**
-   * Request sandbox resume. The Kubernetes backend returns HTTP 501.
-   *
-   * @deprecated Unsupported on Kubernetes. Use {@link Sandbox.connect} to
-   * reconnect to a running sandbox.
-   */
+  /** Queue restoration of saved memory and files. Use waitForStatus('running') before executing. */
   async resume(opts) {
     return SandboxClient.resumeSandbox(this.sandboxId, this.resolveOpts(opts));
   }
+  /** Wait for an asynchronous pause/resume operation to finish. */
+  async waitForStatus(status, opts) {
+    const deadline = Date.now() + (opts?.waitTimeoutMs ?? 6e5);
+    do {
+      const info = await this.getInfo(opts);
+      if (info.status === status) return info;
+      if (["failed", "stopped", "deleted"].includes(info.status ?? "") || info.pauseError) {
+        throw new ConflictError(info.pauseError ?? `Sandbox is ${info.status}`);
+      }
+      if (Date.now() >= deadline) break;
+      await new Promise((resolve) => setTimeout(resolve, 1e3));
+    } while (Date.now() < deadline);
+    throw new TimeoutError(`Sandbox did not become ${status} within the wait timeout`);
+  }
   /**
    * Get metadata and status information about this sandbox.
    */
@@ -983,9 +989,9 @@ var Sandbox = class extends SandboxClient {
   fork(opts = {}) {
     return new PlatformClient(this.resolveOpts()).post(`/api/sandboxes/${this.sandboxId}/fork`, { count: opts.count ?? 1, timeoutMs: opts.timeoutMs ?? 0 });
   }
-  /** Snapshot creation is unsupported on Kubernetes; the backend returns HTTP 501. */
-  snapshot(name) {
-    return new PlatformClient(this.resolveOpts()).post(`/api/sandboxes/${this.sandboxId}/snapshot`, { name });
+  /** Capture memory and workspace files. Disconnect active clients before capturing. */
+  snapshot(name = `Snapshot ${this.sandboxId}`, opts = {}) {
+    return new PlatformClient(this.resolveOpts()).post(`/api/sandboxes/${this.sandboxId}/snapshot`, { name, poolSize: opts.poolSize ?? 5 });
   }
   unexpose(port) {
     return new PlatformClient(this.resolveOpts()).delete(`/api/sandboxes/${this.sandboxId}/expose/${port}`);
@@ -994,13 +1000,45 @@ var Sandbox = class extends SandboxClient {
     return new PlatformClient(this.resolveOpts()).events(query(`/api/sandboxes/${this.sandboxId}/logs`, { tail: opts.tail }), { signal: opts.signal });
   }
   static snapshots(projectId, opts) {
-    return new PlatformClient(opts ?? {}).get(`/api/projects/${projectId}/snapshots`);
+    return new PlatformClient(opts ?? {}).get(`/api/projects/${encodeURIComponent(projectId)}/snapshots`);
+  }
+  static getSnapshot(snapshotId, opts) {
+    return new PlatformClient(opts ?? {}).get(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}`);
   }
-  /** Snapshot restore is unsupported on Kubernetes; the backend returns HTTP 501. */
+  /** Start a sandbox from an available warm copy in the snapshot's project and region. */
   static async restore(snapshotId, opts) {
-    const result = await new PlatformClient(opts ?? {}).post(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}/fork`, { timeoutMs: opts?.timeoutMs ?? 0 });
+    const client = new PlatformClient(opts ?? {});
+    const snapshot = await this.getSnapshot(snapshotId, opts);
+    const result = await client.post("/api/sandboxes", {
+      snapshotId,
+      projectId: snapshot.projectId,
+      region: snapshot.region,
+      timeoutMs: opts?.timeoutMs ?? DEFAULT_SANDBOX_TIMEOUT_MS
+    });
     return new this({ ...opts, sandboxId: result.sandboxId ?? result.id });
   }
+  static setSnapshotWarmPool(snapshotId, poolSize, opts) {
+    return new PlatformClient(opts ?? {}).patch(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}`, { poolSize });
+  }
+  /** Release idle warm copies; retain saved state and existing claimed sandboxes. */
+  static pauseSnapshot(snapshotId, opts) {
+    return new PlatformClient(opts ?? {}).post(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}/pause`, {});
+  }
+  /** Refill the configured warm pool without another capture. */
+  static resumeSnapshot(snapshotId, opts) {
+    return new PlatformClient(opts ?? {}).post(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}/resume`, {});
+  }
+  static async waitForSnapshot(snapshotId, opts) {
+    const deadline = Date.now() + (opts?.waitTimeoutMs ?? 9e5);
+    do {
+      const snapshot = await this.getSnapshot(snapshotId, opts);
+      if (snapshot.status === "ready" && snapshot.readyCount >= Math.max(1, snapshot.poolSize ?? 1)) return snapshot;
+      if (["failed", "paused", "suspended"].includes(snapshot.status)) throw new ConflictError(snapshot.error ?? `Snapshot is ${snapshot.status}`);
+      if (Date.now() >= deadline) break;
+      await new Promise((resolve) => setTimeout(resolve, 1e3));
+    } while (Date.now() < deadline);
+    throw new TimeoutError("Snapshot did not become ready within the wait timeout");
+  }
   static deleteSnapshot(snapshotId, opts) {
     return new PlatformClient(opts ?? {}).delete(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lizard-build/sdk",
-  "version": "0.1.44",
+  "version": "0.1.46",
   "description": "TypeScript SDK for Lizard: Kubernetes sandboxes, code execution and cloud apps.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",