@lizard-build/sdk 0.1.59 → 0.1.61

package/README.md

@@ -61,7 +61,7 @@ if (result.exitCode !== 0) throw new Error(result.stderr)
 
 ## Desktop (computer use)
 
-The `desktop` template runs XFCE and Chromium you can watch in a browser and an agent can drive:
+The `desktop` template runs an Openbox desktop with Chromium, streamed to a browser over WebRTC (with noVNC as the fallback). You can watch it, and an agent can drive it:
 
 ```ts
 import { Sandbox } from '@lizard-build/sdk'
@@ -108,13 +108,14 @@ const sandbox = await CodeSandbox.create({ projectId: 'proj_123' });
 try {
   await sandbox.runCode('x = 21');
   const run = await sandbox.runCode('x * 2');
-  console.log(run.results[0].data); // "42"
+  const out = run.results[0];
+  if (out?.type === 'result') console.log(out.data); // "42"
 } finally {
   await sandbox.kill();
 }
 ```
 
-`language: 'bash'` (and `'javascript'` where `node` is installed; the `interpreter` template does not ship it) runs each call as a fresh process with no shared state.
+`language: 'bash'` and `language: 'javascript'` (the `interpreter` template ships Node 22) run each call as a fresh process with no shared state.
 
 ## Configuration
 
@@ -124,7 +125,7 @@ Pass `timeoutMs` to `create()` to set the sandbox lifetime. The default is five
 
 ## Runtime limits
 
-Each sandbox is a Firecracker microVM 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 on Firecracker sandboxes yet, volumes cannot be resized yet, and a sandbox with a volume attached cannot be forked. See the [snapshot guide](../../docs/sandboxes.md#pause-resume-snapshots-and-fork).
+Each sandbox is a Firecracker microVM 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 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).
 
 `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

@@ -145,7 +145,10 @@ declare class ProjectsAPI {
     }): Promise<Project[]>;
     /** Get a project by ID. */
     get(id: string): Promise<Project>;
-    /** Create a new project. */
+    /**
+     * Create a new project. A scoped key can create one only in a workspace it
+     * covers; anywhere else it gets HTTP 403 with `code: 'PROJECT_OUT_OF_SCOPE'`.
+     */
     create(opts: CreateProjectOpts): Promise<Project>;
     /** Update a project's name. */
     update(id: string, opts: {
@@ -671,7 +674,7 @@ declare class Watcher {
  * State of a sandbox's desktop, and the URLs that stream it.
  *
  * **Both URLs are credentials.** The port is published on a public hostname, and each
- * URL carries the stream token and a VNC password. Anyone holding `url` can see and
+ * URL carries the stream token and a password. Anyone holding `url` can see and
  * control the desktop; anyone holding `viewOnlyUrl` can watch it. Do not log them or
  * put them anywhere you would not put an API key.
  */
@@ -680,9 +683,9 @@ interface DesktopInfo {
     /** Screen width in pixels, or `null` when the desktop has never been started. */
     width: number | null;
     height: number | null;
-    /** noVNC page with full control (mouse and keyboard). Treat like a credential. */
+    /** Viewer page with full control (mouse and keyboard): WebRTC, with noVNC as the fallback. Treat like a credential. */
     url: string;
-    /** noVNC page that can only watch; enforced by the VNC server, not the page. */
+    /** Viewer page that can only watch; enforced by the stream server in the sandbox, not the page. */
     viewOnlyUrl: string;
 }
 interface DesktopStartOpts {
@@ -702,8 +705,9 @@ interface ClickOpts {
 /**
  * A graphical desktop in the sandbox, for computer-use agents and for people to watch.
  *
- * Only the `desktop` template has one (Xvfb + XFCE + Chromium on `DISPLAY=:1`); on
- * any other template the calls fail with `code === 'DESKTOP_NOT_SUPPORTED'`.
+ * Only the `desktop` template has one (Xvfb + Openbox + Chromium on `DISPLAY=:1`,
+ * streamed over WebRTC with noVNC as the fallback); on any other template the calls
+ * fail with `code === 'DESKTOP_NOT_SUPPORTED'`.
  *
  * Input and screenshots run inside the sandbox with `xdotool` and `scrot`. Every
  * argument goes to the sandbox as an argv array and is never parsed by a shell, so
@@ -792,9 +796,9 @@ interface SandboxInfo {
     /** The sandbox runtime: `'firecracker'` (a microVM), `'container'`, or `null` when unknown. */
     runtime?: 'firecracker' | 'container' | null;
     pauseError?: string | null;
-    /** Machine size (`'small' | 'medium' | 'large'`); may be `null` for a sandbox created from a private snapshot. */
+    /** Machine size (`'small' | 'medium' | 'large'`); may be `null` for a sandbox billed by measured usage, such as one restored from a container snapshot. */
     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 (private snapshot). */
+    /** Flat hourly price in USD for `size`, billed per second while running; may be `null` when billed by measured usage (a container snapshot). */
     pricePerHour?: number | null;
     cpus?: number;
     memoryMb?: number;
@@ -826,8 +830,8 @@ interface SandboxOpts extends ConnectionOpts {
     projectId?: string;
     template?: string;
     /**
-     * Create from a private saved snapshot. The sandbox runs on the machine the
-     * snapshot was captured on and is billed by measured usage; `size` is ignored.
+     * Create from a private saved snapshot. The sandbox runs at the source sandbox's
+     * size and is billed flat at that size; `size` is ignored.
      */
     snapshotId?: string;
     /**
@@ -1154,9 +1158,10 @@ declare class Sandbox extends SandboxClient {
      */
     exposePort(port: number, opts?: ConnectionOpts): Promise<ExposedPort>;
     /**
-     * Clone this running sandbox `count` times (1-10). Each fork is a copy of the
+     * Clone this running sandbox `count` times (1-100). Each fork is a copy of the
      * microVM at this instant -- memory, running processes and files -- and is
-     * billed like its source. The source keeps running.
+     * billed like its source. The source keeps running. Each copy counts as a
+     * sandbox start, so the account's running-sandbox limit is the real cap.
      *
      * Returns one entry per requested fork, in order: `{ sandbox, info }`, or
      * `{ error }` for a copy that could not be made (e.g. the account's sandbox
@@ -1420,14 +1425,22 @@ declare class WorkspacesAPI {
      * project. A full key returns every workspace the account belongs to.
      */
     list(): Promise<Workspace[]>;
-    /** Create a workspace. The caller becomes its owner. */
+    /**
+     * Create a workspace. The caller becomes its owner.
+     *
+     * Needs a key with no scopes: a scoped key gets HTTP 403 with
+     * `code: 'ACCOUNT_SCOPE_REQUIRED'`.
+     */
     create(opts: CreateWorkspaceOpts): Promise<Workspace>;
     /**
      * Delete a workspace.
      *
-     * Empty-only by default — the server refuses while any project or sandbox remains,
-     * so this cannot quietly destroy a user's work. Pass `{ force: true }` to delete a
-     * workspace and everything in it; that is irreversible.
+     * Empty-only by default — the server refuses while any project, sandbox or volume
+     * remains, so this cannot quietly destroy a user's work. `{ force: true }` deletes
+     * the workspace with its apps, addons and projects; that is irreversible. It does not
+     * delete sandboxes, sandbox volumes or snapshots: a running sandbox keeps running with
+     * no workspace left to find it in. Kill the workspace's sandboxes and delete its
+     * volumes and snapshots first.
      */
     delete(id: string, opts?: {
         force?: boolean;
@@ -1842,9 +1855,9 @@ declare class Volume {
     /**
      * Resize a volume, by name or by id, to `sizeGb`.
      *
-     * **Firecracker volumes cannot be resized yet**: volumes created for the default
-     * Firecracker sandboxes throw `LizardError` (400) with `code: 'volume_not_resizable'`.
-     * Create the volume at the size you need, or copy the data to a new, larger one.
+     * 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'`.
      *
      * 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
@@ -1852,16 +1865,17 @@ declare class Volume {
      * new size free — otherwise it throws `ConflictError` with
      * `code: 'volume_too_full_to_shrink'`.
      *
-     * Other failures carry a `code` too: `invalid_volume_size`, `volume_not_resizable`,
+     * Other failures carry a `code` too: `invalid_volume_size`, `volume_too_large`,
+     * `volume_not_resizable` (an app's volume, not a sandbox volume),
      * `volume_resize_in_progress`, `volume_not_provisioned`,
      * `volume_capacity_unavailable`, and `volume_resize_timeout` (a `TimeoutError`;
      * the size is left unchanged).
      *
-     * @returns The volume's updated info, including `sizeEnforced`.
+     * @returns The volume's updated info, including `sizeEnforced` for a container volume.
      */
     static resize(projectId: string, nameOrId: string, sizeGb: number, opts?: ConnectionOpts): Promise<VolumeInfo>;
     getInfo(projectId: string): Promise<VolumeInfo>;
-    /** Resize this volume — see the static {@link Volume.resize} (not supported for Firecracker volumes yet). */
+    /** Resize this volume — see the static {@link Volume.resize} (a Firecracker volume can only grow). */
     resize(projectId: string, sizeGb: number): Promise<VolumeInfo>;
     delete(projectId: string): Promise<void>;
 }
@@ -1968,11 +1982,11 @@ declare class Lizard {
     /**
      * The account this credential belongs to — the SDK's `lizard whoami`.
      *
-     * A **scoped** key gets identity only: `id`, `username`, `avatarUrl`, `scoped: true`
-     * and the key's own `scopes`. The account's email, balance, plan and billing status
-     * are withheld — they belong to the account, not to the key holder, and a scoped key
-     * is meant to be handed to an end user or injected into a sandbox. An unscoped key
-     * or a session sees the full account.
+     * A **scoped** key never learns whose account it is: it gets only `scoped: true` and
+     * its `scopes`, each project or workspace with its name. No id, username, avatar,
+     * email, balance or plan -- a scoped key is meant to be handed to someone who is not
+     * the account's member, or injected into a sandbox. An unscoped key or a session
+     * sees the full account.
      *
      * Reading back `scopes` is the cheapest way to answer "what can this key reach".
      */
@@ -1981,21 +1995,27 @@ declare class Lizard {
     get platform(): PlatformClient;
 }
 /**
- * The account behind a credential — see {@link Lizard.whoami}.
+ * The account behind a credential -- see {@link Lizard.whoami}.
  *
- * Everything past `avatarUrl` is present only for an unscoped key or a session; a
- * scoped key gets `scoped: true` and `scopes` in their place.
+ * A scoped key gets only `scoped: true` and `scopes`; every other field is present only
+ * for an unscoped key or a session.
  */
 interface Account {
-    id: string;
-    username: string;
+    /** Absent for a scoped key. */
+    id?: string;
+    /** Absent for a scoped key. */
+    username?: string;
     avatarUrl?: string | null;
-    /** True when the calling key is scoped, meaning the account fields below are absent. */
+    /** True when the calling key is scoped, meaning the account fields are absent. */
     scoped?: boolean;
-    /** What the calling key may reach. Present when `scoped` is true. */
+    /** What the calling key may reach, by name. Present when `scoped` is true. */
     scopes?: Array<{
         type: 'workspace' | 'project';
         id: string;
+        name?: string | null;
+        /** For a project scope: the workspace it belongs to. */
+        workspaceId?: string | null;
+        workspaceName?: string | null;
     }>;
     email?: string | null;
     plan?: string;
@@ -2154,7 +2174,7 @@ interface CreateContextOpts {
  * Limits, honestly:
  * - `javascript` (node) and `bash` run each call as a fresh process: no state
  *   carries over and `results` stays empty. `node` must be installed in the
- *   template; the `interpreter` template does not ship it.
+ *   template; the `interpreter` template ships Node 22.
  * - On a template without Jupyter (e.g. `base`), Python also runs as a fresh
  *   process per call.
  * - `stdout`/`stderr` are delivered in the chunks the kernel or process
@@ -2168,7 +2188,8 @@ interface CreateContextOpts {
  * const sandbox = await CodeSandbox.create({ project: 'my-project' })
  * await sandbox.runCode('x = 21')
  * const run = await sandbox.runCode('x * 2')
- * console.log(run.results[0].data) // "42"
+ * const out = run.results[0]
+ * if (out?.type === 'result') console.log(out.data) // "42"
  * await sandbox.kill()
  * ```
  */

package/dist/index.d.ts

@@ -145,7 +145,10 @@ declare class ProjectsAPI {
     }): Promise<Project[]>;
     /** Get a project by ID. */
     get(id: string): Promise<Project>;
-    /** Create a new project. */
+    /**
+     * Create a new project. A scoped key can create one only in a workspace it
+     * covers; anywhere else it gets HTTP 403 with `code: 'PROJECT_OUT_OF_SCOPE'`.
+     */
     create(opts: CreateProjectOpts): Promise<Project>;
     /** Update a project's name. */
     update(id: string, opts: {
@@ -671,7 +674,7 @@ declare class Watcher {
  * State of a sandbox's desktop, and the URLs that stream it.
  *
  * **Both URLs are credentials.** The port is published on a public hostname, and each
- * URL carries the stream token and a VNC password. Anyone holding `url` can see and
+ * URL carries the stream token and a password. Anyone holding `url` can see and
  * control the desktop; anyone holding `viewOnlyUrl` can watch it. Do not log them or
  * put them anywhere you would not put an API key.
  */
@@ -680,9 +683,9 @@ interface DesktopInfo {
     /** Screen width in pixels, or `null` when the desktop has never been started. */
     width: number | null;
     height: number | null;
-    /** noVNC page with full control (mouse and keyboard). Treat like a credential. */
+    /** Viewer page with full control (mouse and keyboard): WebRTC, with noVNC as the fallback. Treat like a credential. */
     url: string;
-    /** noVNC page that can only watch; enforced by the VNC server, not the page. */
+    /** Viewer page that can only watch; enforced by the stream server in the sandbox, not the page. */
     viewOnlyUrl: string;
 }
 interface DesktopStartOpts {
@@ -702,8 +705,9 @@ interface ClickOpts {
 /**
  * A graphical desktop in the sandbox, for computer-use agents and for people to watch.
  *
- * Only the `desktop` template has one (Xvfb + XFCE + Chromium on `DISPLAY=:1`); on
- * any other template the calls fail with `code === 'DESKTOP_NOT_SUPPORTED'`.
+ * Only the `desktop` template has one (Xvfb + Openbox + Chromium on `DISPLAY=:1`,
+ * streamed over WebRTC with noVNC as the fallback); on any other template the calls
+ * fail with `code === 'DESKTOP_NOT_SUPPORTED'`.
  *
  * Input and screenshots run inside the sandbox with `xdotool` and `scrot`. Every
  * argument goes to the sandbox as an argv array and is never parsed by a shell, so
@@ -792,9 +796,9 @@ interface SandboxInfo {
     /** The sandbox runtime: `'firecracker'` (a microVM), `'container'`, or `null` when unknown. */
     runtime?: 'firecracker' | 'container' | null;
     pauseError?: string | null;
-    /** Machine size (`'small' | 'medium' | 'large'`); may be `null` for a sandbox created from a private snapshot. */
+    /** Machine size (`'small' | 'medium' | 'large'`); may be `null` for a sandbox billed by measured usage, such as one restored from a container snapshot. */
     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 (private snapshot). */
+    /** Flat hourly price in USD for `size`, billed per second while running; may be `null` when billed by measured usage (a container snapshot). */
     pricePerHour?: number | null;
     cpus?: number;
     memoryMb?: number;
@@ -826,8 +830,8 @@ interface SandboxOpts extends ConnectionOpts {
     projectId?: string;
     template?: string;
     /**
-     * Create from a private saved snapshot. The sandbox runs on the machine the
-     * snapshot was captured on and is billed by measured usage; `size` is ignored.
+     * Create from a private saved snapshot. The sandbox runs at the source sandbox's
+     * size and is billed flat at that size; `size` is ignored.
      */
     snapshotId?: string;
     /**
@@ -1154,9 +1158,10 @@ declare class Sandbox extends SandboxClient {
      */
     exposePort(port: number, opts?: ConnectionOpts): Promise<ExposedPort>;
     /**
-     * Clone this running sandbox `count` times (1-10). Each fork is a copy of the
+     * Clone this running sandbox `count` times (1-100). Each fork is a copy of the
      * microVM at this instant -- memory, running processes and files -- and is
-     * billed like its source. The source keeps running.
+     * billed like its source. The source keeps running. Each copy counts as a
+     * sandbox start, so the account's running-sandbox limit is the real cap.
      *
      * Returns one entry per requested fork, in order: `{ sandbox, info }`, or
      * `{ error }` for a copy that could not be made (e.g. the account's sandbox
@@ -1420,14 +1425,22 @@ declare class WorkspacesAPI {
      * project. A full key returns every workspace the account belongs to.
      */
     list(): Promise<Workspace[]>;
-    /** Create a workspace. The caller becomes its owner. */
+    /**
+     * Create a workspace. The caller becomes its owner.
+     *
+     * Needs a key with no scopes: a scoped key gets HTTP 403 with
+     * `code: 'ACCOUNT_SCOPE_REQUIRED'`.
+     */
     create(opts: CreateWorkspaceOpts): Promise<Workspace>;
     /**
      * Delete a workspace.
      *
-     * Empty-only by default — the server refuses while any project or sandbox remains,
-     * so this cannot quietly destroy a user's work. Pass `{ force: true }` to delete a
-     * workspace and everything in it; that is irreversible.
+     * Empty-only by default — the server refuses while any project, sandbox or volume
+     * remains, so this cannot quietly destroy a user's work. `{ force: true }` deletes
+     * the workspace with its apps, addons and projects; that is irreversible. It does not
+     * delete sandboxes, sandbox volumes or snapshots: a running sandbox keeps running with
+     * no workspace left to find it in. Kill the workspace's sandboxes and delete its
+     * volumes and snapshots first.
      */
     delete(id: string, opts?: {
         force?: boolean;
@@ -1842,9 +1855,9 @@ declare class Volume {
     /**
      * Resize a volume, by name or by id, to `sizeGb`.
      *
-     * **Firecracker volumes cannot be resized yet**: volumes created for the default
-     * Firecracker sandboxes throw `LizardError` (400) with `code: 'volume_not_resizable'`.
-     * Create the volume at the size you need, or copy the data to a new, larger one.
+     * 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'`.
      *
      * 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
@@ -1852,16 +1865,17 @@ declare class Volume {
      * new size free — otherwise it throws `ConflictError` with
      * `code: 'volume_too_full_to_shrink'`.
      *
-     * Other failures carry a `code` too: `invalid_volume_size`, `volume_not_resizable`,
+     * Other failures carry a `code` too: `invalid_volume_size`, `volume_too_large`,
+     * `volume_not_resizable` (an app's volume, not a sandbox volume),
      * `volume_resize_in_progress`, `volume_not_provisioned`,
      * `volume_capacity_unavailable`, and `volume_resize_timeout` (a `TimeoutError`;
      * the size is left unchanged).
      *
-     * @returns The volume's updated info, including `sizeEnforced`.
+     * @returns The volume's updated info, including `sizeEnforced` for a container volume.
      */
     static resize(projectId: string, nameOrId: string, sizeGb: number, opts?: ConnectionOpts): Promise<VolumeInfo>;
     getInfo(projectId: string): Promise<VolumeInfo>;
-    /** Resize this volume — see the static {@link Volume.resize} (not supported for Firecracker volumes yet). */
+    /** Resize this volume — see the static {@link Volume.resize} (a Firecracker volume can only grow). */
     resize(projectId: string, sizeGb: number): Promise<VolumeInfo>;
     delete(projectId: string): Promise<void>;
 }
@@ -1968,11 +1982,11 @@ declare class Lizard {
     /**
      * The account this credential belongs to — the SDK's `lizard whoami`.
      *
-     * A **scoped** key gets identity only: `id`, `username`, `avatarUrl`, `scoped: true`
-     * and the key's own `scopes`. The account's email, balance, plan and billing status
-     * are withheld — they belong to the account, not to the key holder, and a scoped key
-     * is meant to be handed to an end user or injected into a sandbox. An unscoped key
-     * or a session sees the full account.
+     * A **scoped** key never learns whose account it is: it gets only `scoped: true` and
+     * its `scopes`, each project or workspace with its name. No id, username, avatar,
+     * email, balance or plan -- a scoped key is meant to be handed to someone who is not
+     * the account's member, or injected into a sandbox. An unscoped key or a session
+     * sees the full account.
      *
      * Reading back `scopes` is the cheapest way to answer "what can this key reach".
      */
@@ -1981,21 +1995,27 @@ declare class Lizard {
     get platform(): PlatformClient;
 }
 /**
- * The account behind a credential — see {@link Lizard.whoami}.
+ * The account behind a credential -- see {@link Lizard.whoami}.
  *
- * Everything past `avatarUrl` is present only for an unscoped key or a session; a
- * scoped key gets `scoped: true` and `scopes` in their place.
+ * A scoped key gets only `scoped: true` and `scopes`; every other field is present only
+ * for an unscoped key or a session.
  */
 interface Account {
-    id: string;
-    username: string;
+    /** Absent for a scoped key. */
+    id?: string;
+    /** Absent for a scoped key. */
+    username?: string;
     avatarUrl?: string | null;
-    /** True when the calling key is scoped, meaning the account fields below are absent. */
+    /** True when the calling key is scoped, meaning the account fields are absent. */
     scoped?: boolean;
-    /** What the calling key may reach. Present when `scoped` is true. */
+    /** What the calling key may reach, by name. Present when `scoped` is true. */
     scopes?: Array<{
         type: 'workspace' | 'project';
         id: string;
+        name?: string | null;
+        /** For a project scope: the workspace it belongs to. */
+        workspaceId?: string | null;
+        workspaceName?: string | null;
     }>;
     email?: string | null;
     plan?: string;
@@ -2154,7 +2174,7 @@ interface CreateContextOpts {
  * Limits, honestly:
  * - `javascript` (node) and `bash` run each call as a fresh process: no state
  *   carries over and `results` stays empty. `node` must be installed in the
- *   template; the `interpreter` template does not ship it.
+ *   template; the `interpreter` template ships Node 22.
  * - On a template without Jupyter (e.g. `base`), Python also runs as a fresh
  *   process per call.
  * - `stdout`/`stderr` are delivered in the chunks the kernel or process
@@ -2168,7 +2188,8 @@ interface CreateContextOpts {
  * const sandbox = await CodeSandbox.create({ project: 'my-project' })
  * await sandbox.runCode('x = 21')
  * const run = await sandbox.runCode('x * 2')
- * console.log(run.results[0].data) // "42"
+ * const out = run.results[0]
+ * if (out?.type === 'result') console.log(out.data) // "42"
  * await sandbox.kill()
  * ```
  */

package/dist/index.js

@@ -1258,9 +1258,10 @@ var Sandbox = class extends SandboxClient {
     return exposed;
   }
   /**
-   * Clone this running sandbox `count` times (1-10). Each fork is a copy of the
+   * Clone this running sandbox `count` times (1-100). Each fork is a copy of the
    * microVM at this instant -- memory, running processes and files -- and is
-   * billed like its source. The source keeps running.
+   * billed like its source. The source keeps running. Each copy counts as a
+   * sandbox start, so the account's running-sandbox limit is the real cap.
    *
    * Returns one entry per requested fork, in order: `{ sandbox, info }`, or
    * `{ error }` for a copy that could not be made (e.g. the account's sandbox
@@ -1381,7 +1382,10 @@ var ProjectsAPI = class {
   get(id) {
     return this.client.get(`/api/projects/${id}`);
   }
-  /** Create a new project. */
+  /**
+   * Create a new project. A scoped key can create one only in a workspace it
+   * covers; anywhere else it gets HTTP 403 with `code: 'PROJECT_OUT_OF_SCOPE'`.
+   */
   create(opts) {
     return this.client.post("/api/projects", opts);
   }
@@ -1650,16 +1654,24 @@ var WorkspacesAPI = class {
   list() {
     return this.client.get("/api/workspaces");
   }
-  /** Create a workspace. The caller becomes its owner. */
+  /**
+   * Create a workspace. The caller becomes its owner.
+   *
+   * Needs a key with no scopes: a scoped key gets HTTP 403 with
+   * `code: 'ACCOUNT_SCOPE_REQUIRED'`.
+   */
   create(opts) {
     return this.client.post("/api/workspaces", opts);
   }
   /**
    * Delete a workspace.
    *
-   * Empty-only by default — the server refuses while any project or sandbox remains,
-   * so this cannot quietly destroy a user's work. Pass `{ force: true }` to delete a
-   * workspace and everything in it; that is irreversible.
+   * Empty-only by default — the server refuses while any project, sandbox or volume
+   * remains, so this cannot quietly destroy a user's work. `{ force: true }` deletes
+   * the workspace with its apps, addons and projects; that is irreversible. It does not
+   * delete sandboxes, sandbox volumes or snapshots: a running sandbox keeps running with
+   * no workspace left to find it in. Kill the workspace's sandboxes and delete its
+   * volumes and snapshots first.
    */
   delete(id, opts) {
     const qs = opts?.force ? "" : "?requireEmpty=true";
@@ -1853,9 +1865,9 @@ var Volume = class _Volume {
   /**
    * Resize a volume, by name or by id, to `sizeGb`.
    *
-   * **Firecracker volumes cannot be resized yet**: volumes created for the default
-   * Firecracker sandboxes throw `LizardError` (400) with `code: 'volume_not_resizable'`.
-   * Create the volume at the size you need, or copy the data to a new, larger one.
+   * 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'`.
    *
    * 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
@@ -1863,12 +1875,13 @@ var Volume = class _Volume {
    * new size free — otherwise it throws `ConflictError` with
    * `code: 'volume_too_full_to_shrink'`.
    *
-   * Other failures carry a `code` too: `invalid_volume_size`, `volume_not_resizable`,
+   * Other failures carry a `code` too: `invalid_volume_size`, `volume_too_large`,
+   * `volume_not_resizable` (an app's volume, not a sandbox volume),
    * `volume_resize_in_progress`, `volume_not_provisioned`,
    * `volume_capacity_unavailable`, and `volume_resize_timeout` (a `TimeoutError`;
    * the size is left unchanged).
    *
-   * @returns The volume's updated info, including `sizeEnforced`.
+   * @returns The volume's updated info, including `sizeEnforced` for a container volume.
    */
   static async resize(projectId, nameOrId, sizeGb, opts) {
     const config = new ConnectionConfig(opts);
@@ -1887,7 +1900,7 @@ var Volume = class _Volume {
     if (!res.ok) await handleApiError(res);
     return res.json();
   }
-  /** Resize this volume — see the static {@link Volume.resize} (not supported for Firecracker volumes yet). */
+  /** Resize this volume — see the static {@link Volume.resize} (a Firecracker volume can only grow). */
   async resize(projectId, sizeGb) {
     return _Volume.resize(projectId, this.volumeId, sizeGb, {
       apiKey: this.config.apiKey,
@@ -1977,11 +1990,11 @@ var Lizard = class {
   /**
    * The account this credential belongs to — the SDK's `lizard whoami`.
    *
-   * A **scoped** key gets identity only: `id`, `username`, `avatarUrl`, `scoped: true`
-   * and the key's own `scopes`. The account's email, balance, plan and billing status
-   * are withheld — they belong to the account, not to the key holder, and a scoped key
-   * is meant to be handed to an end user or injected into a sandbox. An unscoped key
-   * or a session sees the full account.
+   * A **scoped** key never learns whose account it is: it gets only `scoped: true` and
+   * its `scopes`, each project or workspace with its name. No id, username, avatar,
+   * email, balance or plan -- a scoped key is meant to be handed to someone who is not
+   * the account's member, or injected into a sandbox. An unscoped key or a session
+   * sees the full account.
    *
    * Reading back `scopes` is the cheapest way to answer "what can this key reach".
    */

package/dist/index.mjs

@@ -1205,9 +1205,10 @@ var Sandbox = class extends SandboxClient {
     return exposed;
   }
   /**
-   * Clone this running sandbox `count` times (1-10). Each fork is a copy of the
+   * Clone this running sandbox `count` times (1-100). Each fork is a copy of the
    * microVM at this instant -- memory, running processes and files -- and is
-   * billed like its source. The source keeps running.
+   * billed like its source. The source keeps running. Each copy counts as a
+   * sandbox start, so the account's running-sandbox limit is the real cap.
    *
    * Returns one entry per requested fork, in order: `{ sandbox, info }`, or
    * `{ error }` for a copy that could not be made (e.g. the account's sandbox
@@ -1328,7 +1329,10 @@ var ProjectsAPI = class {
   get(id) {
     return this.client.get(`/api/projects/${id}`);
   }
-  /** Create a new project. */
+  /**
+   * Create a new project. A scoped key can create one only in a workspace it
+   * covers; anywhere else it gets HTTP 403 with `code: 'PROJECT_OUT_OF_SCOPE'`.
+   */
   create(opts) {
     return this.client.post("/api/projects", opts);
   }
@@ -1597,16 +1601,24 @@ var WorkspacesAPI = class {
   list() {
     return this.client.get("/api/workspaces");
   }
-  /** Create a workspace. The caller becomes its owner. */
+  /**
+   * Create a workspace. The caller becomes its owner.
+   *
+   * Needs a key with no scopes: a scoped key gets HTTP 403 with
+   * `code: 'ACCOUNT_SCOPE_REQUIRED'`.
+   */
   create(opts) {
     return this.client.post("/api/workspaces", opts);
   }
   /**
    * Delete a workspace.
    *
-   * Empty-only by default — the server refuses while any project or sandbox remains,
-   * so this cannot quietly destroy a user's work. Pass `{ force: true }` to delete a
-   * workspace and everything in it; that is irreversible.
+   * Empty-only by default — the server refuses while any project, sandbox or volume
+   * remains, so this cannot quietly destroy a user's work. `{ force: true }` deletes
+   * the workspace with its apps, addons and projects; that is irreversible. It does not
+   * delete sandboxes, sandbox volumes or snapshots: a running sandbox keeps running with
+   * no workspace left to find it in. Kill the workspace's sandboxes and delete its
+   * volumes and snapshots first.
    */
   delete(id, opts) {
     const qs = opts?.force ? "" : "?requireEmpty=true";
@@ -1800,9 +1812,9 @@ var Volume = class _Volume {
   /**
    * Resize a volume, by name or by id, to `sizeGb`.
    *
-   * **Firecracker volumes cannot be resized yet**: volumes created for the default
-   * Firecracker sandboxes throw `LizardError` (400) with `code: 'volume_not_resizable'`.
-   * Create the volume at the size you need, or copy the data to a new, larger one.
+   * 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'`.
    *
    * 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
@@ -1810,12 +1822,13 @@ var Volume = class _Volume {
    * new size free — otherwise it throws `ConflictError` with
    * `code: 'volume_too_full_to_shrink'`.
    *
-   * Other failures carry a `code` too: `invalid_volume_size`, `volume_not_resizable`,
+   * Other failures carry a `code` too: `invalid_volume_size`, `volume_too_large`,
+   * `volume_not_resizable` (an app's volume, not a sandbox volume),
    * `volume_resize_in_progress`, `volume_not_provisioned`,
    * `volume_capacity_unavailable`, and `volume_resize_timeout` (a `TimeoutError`;
    * the size is left unchanged).
    *
-   * @returns The volume's updated info, including `sizeEnforced`.
+   * @returns The volume's updated info, including `sizeEnforced` for a container volume.
    */
   static async resize(projectId, nameOrId, sizeGb, opts) {
     const config = new ConnectionConfig(opts);
@@ -1834,7 +1847,7 @@ var Volume = class _Volume {
     if (!res.ok) await handleApiError(res);
     return res.json();
   }
-  /** Resize this volume — see the static {@link Volume.resize} (not supported for Firecracker volumes yet). */
+  /** Resize this volume — see the static {@link Volume.resize} (a Firecracker volume can only grow). */
   async resize(projectId, sizeGb) {
     return _Volume.resize(projectId, this.volumeId, sizeGb, {
       apiKey: this.config.apiKey,
@@ -1924,11 +1937,11 @@ var Lizard = class {
   /**
    * The account this credential belongs to — the SDK's `lizard whoami`.
    *
-   * A **scoped** key gets identity only: `id`, `username`, `avatarUrl`, `scoped: true`
-   * and the key's own `scopes`. The account's email, balance, plan and billing status
-   * are withheld — they belong to the account, not to the key holder, and a scoped key
-   * is meant to be handed to an end user or injected into a sandbox. An unscoped key
-   * or a session sees the full account.
+   * A **scoped** key never learns whose account it is: it gets only `scoped: true` and
+   * its `scopes`, each project or workspace with its name. No id, username, avatar,
+   * email, balance or plan -- a scoped key is meant to be handed to someone who is not
+   * the account's member, or injected into a sandbox. An unscoped key or a session
+   * sees the full account.
    *
    * Reading back `scopes` is the cheapest way to answer "what can this key reach".
    */

package/package.json

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