@lizard-build/sdk 0.1.71 → 0.1.72

package/README.md

@@ -1,6 +1,6 @@
 # Lizard SDK for TypeScript
 
-Run commands, work with files and execute code in Linux sandboxes with Firecracker support. The SDK also manages Lizard apps, databases, storage and projects.
+Run commands, work with files and execute code in Linux sandboxes that run as Firecracker microVMs. The SDK also manages Lizard apps, databases, storage and projects.
 
 ## Install
 
@@ -125,7 +125,7 @@ Pass `timeoutMs` to `create()` to set the sandbox lifetime. The default is five
 
 ## Runtime limits
 
-Lizard Sandboxes support Firecracker microVMs with their own kernel. Older pod volumes or snapshots, account or region settings, and some Firecracker startup failures can select a container that shares the host kernel. Check `getInfo().runtime` in TypeScript or `get_info().runtime` in Python before running code that requires a separate kernel. Use volumes mounted at `/workspace` to keep files after a sandbox ends. `pause()`/`resume()` keep memory and running processes; `snapshot()` is ready in about 2 s and `Sandbox.restore()` starts a copy in about 0.4 s; `fork()` clones a running sandbox. File watching and sandbox log streaming are not available on Firecracker sandboxes yet. Volumes can grow but not shrink, and a sandbox with a volume attached cannot be forked. See the [snapshot guide](../../docs/sandboxes.md#pause-resume-snapshots-and-fork).
+Lizard Sandboxes run as Firecracker microVMs, each with its own kernel. Use volumes mounted at `/workspace` to keep files after a sandbox ends. `pause()`/`resume()` keep memory and running processes; `snapshot()` is ready in about 2 s and `Sandbox.restore()` starts a copy in about 0.4 s; `fork()` clones a running sandbox. File watching and sandbox log streaming are not available yet. Volumes can grow but not shrink, and a sandbox with a volume attached cannot be forked. See the [snapshot guide](../../docs/sandboxes.md#pause-resume-snapshots-and-fork).
 
 `getHost()` returns a hostname without `https://`; the port is private, so send `sandbox.accessToken` as the `X-Lizard-Access-Token` header (or use `exposePort()`, which also returns a browser `url` carrying the token). File writes accept text or bytes (binary is sent exactly); `readBytes()` supports binary downloads.
 

package/dist/index.d.mts

@@ -714,7 +714,7 @@ declare class Fs {
      * }, 1000)
      * ```
      *
-     * Not available on Firecracker sandboxes yet: the call throws `LizardError` (501).
+     * Not available yet: the call throws `LizardError` (501).
      */
     watch(path: string, opts?: {
         recursive?: boolean;
@@ -864,12 +864,12 @@ interface SandboxInfo {
     /** Region the sandbox runs in — the volume's region when one is attached. */
     region?: string;
     status?: string;
-    /** The sandbox runtime: `'firecracker'` (a microVM), `'container'`, or `null` when unknown. */
+    /** The sandbox runtime: `'firecracker'` (a microVM), or `null` when unknown. */
     runtime?: 'firecracker' | 'container' | null;
     pauseError?: string | null;
-    /** Machine size (`'small' | 'medium' | 'large'`); may be `null` for a sandbox billed by measured usage, such as one restored from a container snapshot. */
+    /** Machine size (`'small' | 'medium' | 'large'`); may be `null` for a sandbox billed by measured usage. */
     size?: 'small' | 'medium' | 'large' | null;
-    /** Flat hourly price in USD for `size`, billed per second while running; may be `null` when billed by measured usage (a container snapshot). */
+    /** Flat hourly price in USD for `size`, billed per second while running; may be `null` when billed by measured usage. */
     pricePerHour?: number | null;
     cpus?: number;
     memoryMb?: number;
@@ -1011,7 +1011,7 @@ interface SandboxSnapshot {
  */
 type SnapshotScope = 'user' | 'workspace' | 'project';
 interface SnapshotOpts {
-    /** Warm copies to keep ready (container sandboxes only; ignored for Firecracker, whose snapshots restore from disk). */
+    /** Warm copies to keep ready for an older snapshot. Firecracker snapshots ignore it: they restore from disk. */
     poolSize?: number;
     /** Where it may be restored. Default `'user'`: any of your projects and workspaces; with a key
      *  limited to a workspace or project, only what the key covers (a wider scope is narrowed). */
@@ -1259,11 +1259,11 @@ declare class Sandbox extends SandboxClient {
      * snapshot. A Firecracker snapshot is `ready` as soon as this returns: about 2 s, up to
      * a few minutes for a sandbox that filled most of its memory (its memory is uploaded
      * first), so the call waits up to 11 minutes. Start copies of it with {@link Sandbox.restore}
-     * (about 0.4 s each). The source keeps running. `poolSize` applies to container sandboxes only.
+     * (about 0.4 s each). The source keeps running. Firecracker snapshots ignore `poolSize`.
      */
     snapshot(name?: string, opts?: SnapshotOpts): Promise<SandboxSnapshot>;
     unexpose(port: number): Promise<void>;
-    /** Stream the sandbox's logs. Not available on Firecracker sandboxes yet (`LizardError`, 501). */
+    /** Stream the sandbox's logs. Not available yet (`LizardError`, 501). */
     logs(opts?: {
         tail?: number;
         signal?: AbortSignal;
@@ -1286,7 +1286,7 @@ declare class Sandbox extends SandboxClient {
     /** Change where a snapshot you took may be restored. */
     static setSnapshotScope(snapshotId: string, scope: SnapshotScope, opts?: ConnectionOpts): Promise<SandboxSnapshot>;
     static setSnapshotWarmPool(snapshotId: string, poolSize: number, opts?: ConnectionOpts): Promise<SandboxSnapshot>;
-    /** Release idle warm copies (container snapshots); retain saved state and existing claimed sandboxes. */
+    /** Release idle warm copies of an older snapshot; retain saved state and existing claimed sandboxes. Firecracker snapshots have no warm copies. */
     static pauseSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<SandboxSnapshot>;
     /** Refill the configured warm pool without another capture. */
     static resumeSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<SandboxSnapshot>;
@@ -1957,7 +1957,7 @@ interface VolumeInfo {
     status: string;
     /** Id of the sandbox the volume is attached to, or `null` when it is free. */
     attachedTo?: string | null;
-    /** Creation time: an ISO-8601 string for Firecracker volumes, unix milliseconds for container volumes. */
+    /** Creation time: an ISO-8601 string, or unix milliseconds for an older volume. */
     createdAt: string | number;
     /**
      * Whether `sizeGb` is actually enforced as a hard limit on the volume's node.
@@ -2026,13 +2026,11 @@ declare class Volume {
     /**
      * Resize a volume, by name or by id, to `sizeGb`.
      *
-     * A Firecracker volume (the default) can only grow. The change is in place and
-     * online: a sandbox with the volume attached keeps running and sees the new size.
-     * A smaller size throws `LizardError` (400) with `code: 'volume_shrink_unsupported'`.
+     * A volume grows in place and online: a sandbox with the volume attached keeps
+     * running and sees the new size. A smaller size throws `LizardError` (400) with
+     * `code: 'volume_shrink_unsupported'`.
      *
-     * On a container volume the change is in place and online: the size is a quota,
-     * so no data is copied and a mounted sandbox sees the new size immediately. Both
-     * growing and shrinking are allowed, but a shrink must leave at least 10% of the
+     * An older volume can also shrink, but the shrink must leave at least 10% of the
      * new size free — otherwise it throws `ConflictError` with
      * `code: 'volume_too_full_to_shrink'`.
      *
@@ -2042,7 +2040,7 @@ declare class Volume {
      * `volume_capacity_unavailable`, and `volume_resize_timeout` (a `TimeoutError`;
      * the size is left unchanged).
      *
-     * @returns The volume's updated info, including `sizeEnforced` for a container volume.
+     * @returns The volume's updated info, including `sizeEnforced` for an older volume.
      */
     static resize(projectId: string, nameOrId: string, sizeGb: number, opts?: ConnectionOpts): Promise<VolumeInfo>;
     getInfo(projectId: string): Promise<VolumeInfo>;

package/dist/index.d.ts

@@ -714,7 +714,7 @@ declare class Fs {
      * }, 1000)
      * ```
      *
-     * Not available on Firecracker sandboxes yet: the call throws `LizardError` (501).
+     * Not available yet: the call throws `LizardError` (501).
      */
     watch(path: string, opts?: {
         recursive?: boolean;
@@ -864,12 +864,12 @@ interface SandboxInfo {
     /** Region the sandbox runs in — the volume's region when one is attached. */
     region?: string;
     status?: string;
-    /** The sandbox runtime: `'firecracker'` (a microVM), `'container'`, or `null` when unknown. */
+    /** The sandbox runtime: `'firecracker'` (a microVM), or `null` when unknown. */
     runtime?: 'firecracker' | 'container' | null;
     pauseError?: string | null;
-    /** Machine size (`'small' | 'medium' | 'large'`); may be `null` for a sandbox billed by measured usage, such as one restored from a container snapshot. */
+    /** Machine size (`'small' | 'medium' | 'large'`); may be `null` for a sandbox billed by measured usage. */
     size?: 'small' | 'medium' | 'large' | null;
-    /** Flat hourly price in USD for `size`, billed per second while running; may be `null` when billed by measured usage (a container snapshot). */
+    /** Flat hourly price in USD for `size`, billed per second while running; may be `null` when billed by measured usage. */
     pricePerHour?: number | null;
     cpus?: number;
     memoryMb?: number;
@@ -1011,7 +1011,7 @@ interface SandboxSnapshot {
  */
 type SnapshotScope = 'user' | 'workspace' | 'project';
 interface SnapshotOpts {
-    /** Warm copies to keep ready (container sandboxes only; ignored for Firecracker, whose snapshots restore from disk). */
+    /** Warm copies to keep ready for an older snapshot. Firecracker snapshots ignore it: they restore from disk. */
     poolSize?: number;
     /** Where it may be restored. Default `'user'`: any of your projects and workspaces; with a key
      *  limited to a workspace or project, only what the key covers (a wider scope is narrowed). */
@@ -1259,11 +1259,11 @@ declare class Sandbox extends SandboxClient {
      * snapshot. A Firecracker snapshot is `ready` as soon as this returns: about 2 s, up to
      * a few minutes for a sandbox that filled most of its memory (its memory is uploaded
      * first), so the call waits up to 11 minutes. Start copies of it with {@link Sandbox.restore}
-     * (about 0.4 s each). The source keeps running. `poolSize` applies to container sandboxes only.
+     * (about 0.4 s each). The source keeps running. Firecracker snapshots ignore `poolSize`.
      */
     snapshot(name?: string, opts?: SnapshotOpts): Promise<SandboxSnapshot>;
     unexpose(port: number): Promise<void>;
-    /** Stream the sandbox's logs. Not available on Firecracker sandboxes yet (`LizardError`, 501). */
+    /** Stream the sandbox's logs. Not available yet (`LizardError`, 501). */
     logs(opts?: {
         tail?: number;
         signal?: AbortSignal;
@@ -1286,7 +1286,7 @@ declare class Sandbox extends SandboxClient {
     /** Change where a snapshot you took may be restored. */
     static setSnapshotScope(snapshotId: string, scope: SnapshotScope, opts?: ConnectionOpts): Promise<SandboxSnapshot>;
     static setSnapshotWarmPool(snapshotId: string, poolSize: number, opts?: ConnectionOpts): Promise<SandboxSnapshot>;
-    /** Release idle warm copies (container snapshots); retain saved state and existing claimed sandboxes. */
+    /** Release idle warm copies of an older snapshot; retain saved state and existing claimed sandboxes. Firecracker snapshots have no warm copies. */
     static pauseSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<SandboxSnapshot>;
     /** Refill the configured warm pool without another capture. */
     static resumeSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<SandboxSnapshot>;
@@ -1957,7 +1957,7 @@ interface VolumeInfo {
     status: string;
     /** Id of the sandbox the volume is attached to, or `null` when it is free. */
     attachedTo?: string | null;
-    /** Creation time: an ISO-8601 string for Firecracker volumes, unix milliseconds for container volumes. */
+    /** Creation time: an ISO-8601 string, or unix milliseconds for an older volume. */
     createdAt: string | number;
     /**
      * Whether `sizeGb` is actually enforced as a hard limit on the volume's node.
@@ -2026,13 +2026,11 @@ declare class Volume {
     /**
      * Resize a volume, by name or by id, to `sizeGb`.
      *
-     * A Firecracker volume (the default) can only grow. The change is in place and
-     * online: a sandbox with the volume attached keeps running and sees the new size.
-     * A smaller size throws `LizardError` (400) with `code: 'volume_shrink_unsupported'`.
+     * A volume grows in place and online: a sandbox with the volume attached keeps
+     * running and sees the new size. A smaller size throws `LizardError` (400) with
+     * `code: 'volume_shrink_unsupported'`.
      *
-     * On a container volume the change is in place and online: the size is a quota,
-     * so no data is copied and a mounted sandbox sees the new size immediately. Both
-     * growing and shrinking are allowed, but a shrink must leave at least 10% of the
+     * An older volume can also shrink, but the shrink must leave at least 10% of the
      * new size free — otherwise it throws `ConflictError` with
      * `code: 'volume_too_full_to_shrink'`.
      *
@@ -2042,7 +2040,7 @@ declare class Volume {
      * `volume_capacity_unavailable`, and `volume_resize_timeout` (a `TimeoutError`;
      * the size is left unchanged).
      *
-     * @returns The volume's updated info, including `sizeEnforced` for a container volume.
+     * @returns The volume's updated info, including `sizeEnforced` for an older volume.
      */
     static resize(projectId: string, nameOrId: string, sizeGb: number, opts?: ConnectionOpts): Promise<VolumeInfo>;
     getInfo(projectId: string): Promise<VolumeInfo>;

package/dist/index.js

@@ -866,7 +866,7 @@ var Fs = class {
    * }, 1000)
    * ```
    *
-   * Not available on Firecracker sandboxes yet: the call throws `LizardError` (501).
+   * Not available yet: the call throws `LizardError` (501).
    */
   async watch(path, opts) {
     const res = await fetch(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/files/watch`, {
@@ -1331,7 +1331,7 @@ var Sandbox = class extends SandboxClient {
    * snapshot. A Firecracker snapshot is `ready` as soon as this returns: about 2 s, up to
    * a few minutes for a sandbox that filled most of its memory (its memory is uploaded
    * first), so the call waits up to 11 minutes. Start copies of it with {@link Sandbox.restore}
-   * (about 0.4 s each). The source keeps running. `poolSize` applies to container sandboxes only.
+   * (about 0.4 s each). The source keeps running. Firecracker snapshots ignore `poolSize`.
    */
   snapshot(name = `Snapshot ${this.sandboxId}`, opts = {}) {
     return new PlatformClient(this.resolveOpts()).post(`/api/sandboxes/${this.sandboxId}/snapshot`, { name, poolSize: opts.poolSize ?? 5, scope: opts.scope }, SNAPSHOT_TIMEOUT_MS);
@@ -1339,7 +1339,7 @@ var Sandbox = class extends SandboxClient {
   unexpose(port) {
     return new PlatformClient(this.resolveOpts()).delete(`/api/sandboxes/${this.sandboxId}/expose/${port}`);
   }
-  /** Stream the sandbox's logs. Not available on Firecracker sandboxes yet (`LizardError`, 501). */
+  /** Stream the sandbox's logs. Not available yet (`LizardError`, 501). */
   logs(opts = {}) {
     return new PlatformClient(this.resolveOpts()).events(query(`/api/sandboxes/${this.sandboxId}/logs`, { tail: opts.tail }), { signal: opts.signal });
   }
@@ -1378,7 +1378,7 @@ var Sandbox = class extends SandboxClient {
   static setSnapshotWarmPool(snapshotId, poolSize, opts) {
     return new PlatformClient(opts ?? {}).patch(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}`, { poolSize });
   }
-  /** Release idle warm copies (container snapshots); retain saved state and existing claimed sandboxes. */
+  /** Release idle warm copies of an older snapshot; retain saved state and existing claimed sandboxes. Firecracker snapshots have no warm copies. */
   static pauseSnapshot(snapshotId, opts) {
     return new PlatformClient(opts ?? {}).post(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}/pause`, {});
   }
@@ -1999,13 +1999,11 @@ var Volume = class _Volume {
   /**
    * Resize a volume, by name or by id, to `sizeGb`.
    *
-   * A Firecracker volume (the default) can only grow. The change is in place and
-   * online: a sandbox with the volume attached keeps running and sees the new size.
-   * A smaller size throws `LizardError` (400) with `code: 'volume_shrink_unsupported'`.
+   * A volume grows in place and online: a sandbox with the volume attached keeps
+   * running and sees the new size. A smaller size throws `LizardError` (400) with
+   * `code: 'volume_shrink_unsupported'`.
    *
-   * On a container volume the change is in place and online: the size is a quota,
-   * so no data is copied and a mounted sandbox sees the new size immediately. Both
-   * growing and shrinking are allowed, but a shrink must leave at least 10% of the
+   * An older volume can also shrink, but the shrink must leave at least 10% of the
    * new size free — otherwise it throws `ConflictError` with
    * `code: 'volume_too_full_to_shrink'`.
    *
@@ -2015,7 +2013,7 @@ var Volume = class _Volume {
    * `volume_capacity_unavailable`, and `volume_resize_timeout` (a `TimeoutError`;
    * the size is left unchanged).
    *
-   * @returns The volume's updated info, including `sizeEnforced` for a container volume.
+   * @returns The volume's updated info, including `sizeEnforced` for an older volume.
    */
   static async resize(projectId, nameOrId, sizeGb, opts) {
     const config = new ConnectionConfig(opts);

package/dist/index.mjs

@@ -812,7 +812,7 @@ var Fs = class {
    * }, 1000)
    * ```
    *
-   * Not available on Firecracker sandboxes yet: the call throws `LizardError` (501).
+   * Not available yet: the call throws `LizardError` (501).
    */
   async watch(path, opts) {
     const res = await fetch(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/files/watch`, {
@@ -1277,7 +1277,7 @@ var Sandbox = class extends SandboxClient {
    * snapshot. A Firecracker snapshot is `ready` as soon as this returns: about 2 s, up to
    * a few minutes for a sandbox that filled most of its memory (its memory is uploaded
    * first), so the call waits up to 11 minutes. Start copies of it with {@link Sandbox.restore}
-   * (about 0.4 s each). The source keeps running. `poolSize` applies to container sandboxes only.
+   * (about 0.4 s each). The source keeps running. Firecracker snapshots ignore `poolSize`.
    */
   snapshot(name = `Snapshot ${this.sandboxId}`, opts = {}) {
     return new PlatformClient(this.resolveOpts()).post(`/api/sandboxes/${this.sandboxId}/snapshot`, { name, poolSize: opts.poolSize ?? 5, scope: opts.scope }, SNAPSHOT_TIMEOUT_MS);
@@ -1285,7 +1285,7 @@ var Sandbox = class extends SandboxClient {
   unexpose(port) {
     return new PlatformClient(this.resolveOpts()).delete(`/api/sandboxes/${this.sandboxId}/expose/${port}`);
   }
-  /** Stream the sandbox's logs. Not available on Firecracker sandboxes yet (`LizardError`, 501). */
+  /** Stream the sandbox's logs. Not available yet (`LizardError`, 501). */
   logs(opts = {}) {
     return new PlatformClient(this.resolveOpts()).events(query(`/api/sandboxes/${this.sandboxId}/logs`, { tail: opts.tail }), { signal: opts.signal });
   }
@@ -1324,7 +1324,7 @@ var Sandbox = class extends SandboxClient {
   static setSnapshotWarmPool(snapshotId, poolSize, opts) {
     return new PlatformClient(opts ?? {}).patch(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}`, { poolSize });
   }
-  /** Release idle warm copies (container snapshots); retain saved state and existing claimed sandboxes. */
+  /** Release idle warm copies of an older snapshot; retain saved state and existing claimed sandboxes. Firecracker snapshots have no warm copies. */
   static pauseSnapshot(snapshotId, opts) {
     return new PlatformClient(opts ?? {}).post(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}/pause`, {});
   }
@@ -1945,13 +1945,11 @@ var Volume = class _Volume {
   /**
    * Resize a volume, by name or by id, to `sizeGb`.
    *
-   * A Firecracker volume (the default) can only grow. The change is in place and
-   * online: a sandbox with the volume attached keeps running and sees the new size.
-   * A smaller size throws `LizardError` (400) with `code: 'volume_shrink_unsupported'`.
+   * A volume grows in place and online: a sandbox with the volume attached keeps
+   * running and sees the new size. A smaller size throws `LizardError` (400) with
+   * `code: 'volume_shrink_unsupported'`.
    *
-   * On a container volume the change is in place and online: the size is a quota,
-   * so no data is copied and a mounted sandbox sees the new size immediately. Both
-   * growing and shrinking are allowed, but a shrink must leave at least 10% of the
+   * An older volume can also shrink, but the shrink must leave at least 10% of the
    * new size free — otherwise it throws `ConflictError` with
    * `code: 'volume_too_full_to_shrink'`.
    *
@@ -1961,7 +1959,7 @@ var Volume = class _Volume {
    * `volume_capacity_unavailable`, and `volume_resize_timeout` (a `TimeoutError`;
    * the size is left unchanged).
    *
-   * @returns The volume's updated info, including `sizeEnforced` for a container volume.
+   * @returns The volume's updated info, including `sizeEnforced` for an older volume.
    */
   static async resize(projectId, nameOrId, sizeGb, opts) {
     const config = new ConnectionConfig(opts);

package/package.json

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