@lizard-build/sdk 0.1.48 → 0.1.51

package/README.md

@@ -1,6 +1,6 @@
 # Lizard SDK for TypeScript
 
-Run commands, work with files and execute code in Linux sandboxes on Kubernetes. The SDK also manages Lizard apps, databases, storage and projects.
+Run commands, work with files and execute code in Linux sandboxes (Firecracker microVMs). The SDK also manages Lizard apps, databases, storage and projects.
 
 ## Install
 
@@ -79,7 +79,7 @@ Treat `url` like a credential: anyone with it can see and control the desktop. S
 
 ## Run Python
 
-Run Python with the `interpreter` template. Each process command starts a separate Python process, so Python variables do not survive between calls. Save intermediate results to files. The API returns stdout, stderr, and an exit code; it does not return typed notebook results or chart objects.
+Run Python with the `interpreter` template. Each process command starts a separate Python process, so Python variables do not survive between calls; use `CodeSandbox` (below) when they should.
 
 ```ts
 import { Sandbox } from '@lizard-build/sdk';
@@ -95,7 +95,26 @@ try {
 }
 ```
 
-`CodeSandbox`, `runCode` / `run_code`, and execution-context methods remain in the SDK, but the hosted template catalog does not provide their required execution server. The legacy default `code-interpreter-v1` is unavailable. Changing its name to `interpreter` does not enable this API. Use `Sandbox.create("interpreter")` and process commands as shown below.
+To run code snippets with state carried between calls, use `CodeSandbox` (`runCode` / `run_code`): it boots the `interpreter` template and runs Python in a persistent Jupyter kernel inside the sandbox. See [Run code](https://github.com/lizard-build/lizard-sdk/blob/main/docs/sandboxes.md#run-code-codesandbox).
+
+## Run code with state (CodeSandbox)
+
+`CodeSandbox` boots the `interpreter` template and runs Python in a persistent Jupyter kernel inside the sandbox: variables survive between calls, the value of the last expression and matplotlib charts come back in `results`, and exceptions in `error`.
+
+```ts
+import { CodeSandbox } from '@lizard-build/sdk';
+
+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"
+} 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.
 
 ## Configuration
 
@@ -105,13 +124,13 @@ 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. 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).
+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).
 
-`getHost()` returns a hostname without `https://`. File writes accept UTF-8 text or valid UTF-8 bytes; `readBytes()` supports binary downloads.
+`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.
 
 ## Current command and lifetime limits
 
-Command results contain stdout, stderr, and the exit code. Command timeouts are limited to 1–600 seconds. The current runtime does not apply the SDK command options `envs`, `workdir`, or `user`; set the directory and environment in the shell command when needed. Create-time `envs` and `metadata` are also not applied.
+Command results contain stdout, stderr, and the exit code. Command timeouts are limited to 1–600 seconds. The command options `envs`, `workdir` and `user` apply to that command; create-time `envs` apply to every command, and create-time `metadata` is returned by `getInfo()` / `get_info()`.
 
 The SDK and CLI default to a five-minute lifetime. The raw API and dashboard default to no expiration. Set an explicit lifetime: `timeoutMs: 0` at creation disables expiration; a positive value sets a deadline. `setTimeout` accepts 1000–2147483647 ms, not zero. Commands do not reset the deadline. This is not an idle timer.
 

package/dist/index.d.mts

@@ -385,12 +385,19 @@ declare class GitHubAPI {
     checkout(serviceId: string, branch: string): Promise<DeployHandle>;
 }
 
-/** A process this sandbox is currently running. */
+/** A process this sandbox is currently running (one started through `exec`). */
 interface ProcessInfo {
     pid: number;
+    /** The argv: `['/bin/sh', '-c', 'npm test']` for a shell command. */
     cmd: string[];
-    /** When the process started, unix milliseconds. */
-    startedAt: number;
+    /** `cmd` joined with spaces, for display. */
+    command?: string;
+    /** Working directory the process was started in, when known. */
+    cwd?: string | null;
+    /** The process's tag, when it was started with one. */
+    tag?: string | null;
+    /** When the process started, unix milliseconds. Not reported by every sandbox. */
+    startedAt?: number;
 }
 /** Signals accepted by {@link Process.kill}. */
 type ProcessSignal = 'SIGTERM' | 'SIGKILL' | 'SIGINT' | 'SIGHUP' | 'SIGQUIT' | 'SIGUSR1' | 'SIGUSR2';
@@ -460,11 +467,6 @@ declare class Process {
      * ```
      */
     exec(cmd: string | string[], opts?: ProcessOpts): Promise<ProcessResult>;
-    /**
-     * Read an SSE exec stream, handing each line to the caller as it arrives while
-     * still accumulating the full result. Events are `{stream, line}` for output and
-     * `{exitCode}` at the end.
-     */
     /**
      * List the processes this sandbox is currently running.
      *
@@ -482,8 +484,8 @@ declare class Process {
     /**
      * Signal a running process. Defaults to `SIGTERM`.
      *
-     * The signal goes to the process group, so a shell's children die with it —
-     * killing `sh -c 'sleep 100'` otherwise leaves the sleep running.
+     * The signal goes to the whole process tree, so a shell's children die with
+     * it — killing `sh -c 'sleep 100'` otherwise leaves the sleep running.
      *
      * The pid comes from {@link list}, or from the `pid` event at the start of a
      * streaming `exec`.
@@ -495,6 +497,11 @@ declare class Process {
      * ```
      */
     kill(pid: number, signal?: ProcessSignal): Promise<void>;
+    /**
+     * Read an SSE exec stream, handing each line to the caller as it arrives while
+     * still accumulating the full result. Events are `{pid}` first (when asked for
+     * with `pidEvent`), `{stream, line}` for output and `{exitCode}` at the end.
+     */
     private consumeStream;
 }
 
@@ -514,10 +521,20 @@ interface FileInfo {
     path: string;
     type: 'file' | 'dir' | 'symlink';
     size: number;
-    /** Permission bits as a string, e.g. `-rw-r--r--`. Absent on older sandboxes. */
-    mode?: string;
-    /** Last modification time, unix milliseconds. Absent on older sandboxes. */
+    /** Permission bits as a number, e.g. `0o644` (420). */
+    mode?: number;
+    /** Permission bits as a string, e.g. `-rw-r--r--`. */
+    permissions?: string;
+    /** Owning user name. */
+    owner?: string;
+    /** Owning group name. */
+    group?: string;
+    /** Last modification time, unix milliseconds. */
     modTime?: number;
+    /** Same as `modTime`, unix milliseconds. */
+    modifiedAt?: number;
+    /** Where a symlink points, for a symlink. */
+    symlinkTarget?: string;
 }
 /**
  * Read and write files inside a Lizard sandbox.
@@ -531,25 +548,29 @@ declare class Fs {
     /**
      * Write a file into the sandbox filesystem.
      *
-     * Creates parent directories automatically if they don't exist.
-     * Byte input must contain valid UTF-8; arbitrary binary uploads are unsupported.
+     * Creates parent directories automatically if they don't exist. A string is
+     * written as UTF-8; bytes (`Uint8Array`, `Buffer` or `ArrayBuffer`) are written
+     * exactly as given, so binary files round-trip with {@link readBytes}.
+     *
+     * With `opts.user` the file is written as (and owned by) that user.
      *
      * @example
      * ```ts
      * await sandbox.fs.write('/app/index.js', 'console.log("hello")')
      * ```
      *
-     * @example Write UTF-8 bytes:
+     * @example Write binary data:
      * ```ts
-     * await sandbox.fs.write('/app/notes.txt', new TextEncoder().encode('hello'))
+     * await sandbox.fs.write('/app/logo.png', await readFile('logo.png'))
      * ```
      */
-    write(path: string, data: string | Uint8Array, opts?: FsOpts): Promise<void>;
+    write(path: string, data: string | Uint8Array | ArrayBuffer, opts?: FsOpts): Promise<void>;
     /**
      * Read a file from the sandbox filesystem.
      *
-     * @returns The file contents as a UTF-8 string.
+     * @returns The file contents as a UTF-8 string. Use {@link readBytes} for binary files.
      *
+     * Throws `NotFoundError` if the path does not exist.
      * @example
      * ```ts
      * const content = await sandbox.fs.read('/app/index.js')
@@ -587,9 +608,7 @@ declare class Fs {
      * console.log(info.size, info.type)
      * ```
      *
-     * Throws `NotFoundError` if the path does not exist. Sandboxes created before
-     * this shipped run a guest agent without it and throw `LizardError` (501) —
-     * recreate the sandbox to use it.
+     * Throws `NotFoundError` if the path does not exist.
      */
     stat(path: string, opts?: FsOpts): Promise<FileInfo>;
     /**
@@ -599,9 +618,6 @@ declare class Fs {
      * ```ts
      * await sandbox.fs.move('/tmp/build.log', '/app/logs/build.log')
      * ```
-     *
-     * Sandboxes created before this shipped run a guest agent without it and throw
-     * `LizardError` (501) — recreate the sandbox to use it.
      */
     move(from: string, to: string): Promise<void>;
     /**
@@ -623,8 +639,7 @@ declare class Fs {
      * }, 1000)
      * ```
      *
-     * Sandboxes created before this shipped run a guest agent without it and throw
-     * `LizardError` (501) — recreate the sandbox to use it.
+     * Not available on Firecracker sandboxes yet: the call throws `LizardError` (501).
      */
     watch(path: string, opts?: {
         recursive?: boolean;
@@ -710,7 +725,8 @@ declare class Desktop {
     private readonly sandboxId;
     private readonly config;
     private readonly process;
-    constructor(sandboxId: string, config: ConnectionConfig, process: Process);
+    private readonly fs;
+    constructor(sandboxId: string, config: ConnectionConfig, process: Process, fs: Fs);
     private get client();
     private get path();
     /**
@@ -772,6 +788,8 @@ 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. */
+    runtime?: 'firecracker' | 'container' | null;
     pauseError?: string | null;
     /** Machine size (`'small' | 'medium' | 'large'`); may be `null` for a sandbox created from a private snapshot. */
     size?: 'small' | 'medium' | 'large' | null;
@@ -781,6 +799,19 @@ interface SandboxInfo {
     memoryMb?: number;
     metadata?: Record<string, string>;
 }
+/** A sandbox port published on a public HTTPS hostname. See {@link Sandbox.exposePort}. */
+interface ExposedPort {
+    /** Hostname without a scheme, e.g. `abc-3000.sandbox.eu-west-lim-a.onlizard.com`. */
+    hostname: string;
+    /** A browser URL that carries the access token (`?lizard_token=...`). */
+    url: string;
+    port: number;
+    /**
+     * The port is private: every request needs this token, either as the
+     * `X-Lizard-Access-Token` header or once as `?lizard_token=` (a browser then gets a cookie).
+     */
+    accessToken: string;
+}
 interface SandboxOpts extends ConnectionOpts {
     /**
      * The project this sandbox belongs to — its ID, slug, or name. Required:
@@ -807,7 +838,9 @@ interface SandboxOpts extends ConnectionOpts {
      * Measured CPU/RAM are not charged and egress is free. Ignored with {@link SandboxOpts.snapshotId}.
      */
     size?: 'small' | 'medium' | 'large';
+    /** Your own key/value labels for the sandbox, returned by `getInfo()` and `list()`. */
     metadata?: Record<string, string>;
+    /** Environment variables set in the sandbox, visible to every command it runs. */
     envs?: Record<string, string>;
     timeoutMs?: number;
     /**
@@ -867,10 +900,7 @@ declare class SandboxClient {
     }): Promise<SandboxInfo[]>;
     protected static getSandboxInfo(sandboxId: string, opts?: ConnectionOpts): Promise<SandboxInfo>;
     protected static setTimeoutSandbox(sandboxId: string, timeoutMs: number, opts?: ConnectionOpts): Promise<void>;
-    protected static exposeSandboxPort(sandboxId: string, port: number, opts?: ConnectionOpts): Promise<{
-        hostname: string;
-        url: string;
-    }>;
+    protected static exposeSandboxPort(sandboxId: string, port: number, opts?: ConnectionOpts): Promise<ExposedPort>;
 }
 
 interface SandboxSnapshot {
@@ -886,18 +916,37 @@ interface SandboxSnapshot {
     error: string | null;
     cpus: number;
     memoryMb: number;
+    /** Unix milliseconds. */
     createdAt: number;
 }
 interface SnapshotOpts {
+    /** Warm copies to keep ready (container sandboxes only; ignored for Firecracker, whose snapshots restore from disk). */
     poolSize?: number;
 }
+/**
+ * One entry of {@link Sandbox.fork}'s result: the new sandbox, or why that copy
+ * could not be made (e.g. the account's sandbox limit).
+ */
+type ForkResult<S extends Sandbox = Sandbox> = {
+    sandbox: S;
+    info: SandboxInfo;
+    error?: undefined;
+} | {
+    sandbox?: undefined;
+    info?: undefined;
+    error: string;
+};
 interface SnapshotWaitOpts extends ConnectionOpts {
     waitTimeoutMs?: number;
 }
 /**
- * A Linux sandbox running on Kubernetes.
+ * A Linux sandbox: a Firecracker microVM with its own kernel.
  *
- * Run commands, read and write files, and expose HTTP ports in a sandbox.
+ * Run commands, read and write files, and expose HTTP ports in a sandbox. A
+ * sandbox boots in well under a second; {@link pause} and {@link resume} keep its
+ * memory and running processes, {@link snapshot} saves it in about 2 s and
+ * {@link restore} starts a copy in about 0.4 s, and {@link fork} clones a running
+ * sandbox, processes and all.
  *
  * Sandboxes are **ephemeral**: killing one, or letting it hit its timeout, discards
  * everything written inside it. State that has to outlive a sandbox belongs on a
@@ -989,8 +1038,9 @@ declare class Sandbox extends SandboxClient {
      * Create a new Lizard sandbox from the specified template.
      *
      * Template availability and installed tools depend on the platform and region.
-     * Use `base` for shell commands or `interpreter` for Python process commands.
-     * Hosted templates do not support the legacy `CodeSandbox` execution API.
+     * Use `base` for shell commands, `interpreter` for Python with the data stack
+     * (use {@link CodeSandbox} to run code snippets in it), or `desktop` for a
+     * graphical desktop.
      *
      * @param template Name of the sandbox template to boot from.
      *
@@ -1032,9 +1082,15 @@ declare class Sandbox extends SandboxClient {
      * @returns `true` if the sandbox was terminated, `false` if it was already gone.
      */
     kill(opts?: ConnectionOpts): Promise<boolean>;
-    /** Queue a CRIU checkpoint and stop compute. Use waitForStatus('paused') before resuming. */
+    /**
+     * Pause the sandbox: its memory, running processes and files are kept and
+     * compute stops. Wait with `waitForStatus('paused')` before resuming.
+     */
     pause(opts?: ConnectionOpts): Promise<boolean>;
-    /** Queue restoration of saved memory and files. Use waitForStatus('running') before executing. */
+    /**
+     * Resume a paused sandbox exactly where it stopped, processes included. Wait
+     * with `waitForStatus('running')` before running commands.
+     */
     resume(opts?: ConnectionOpts): Promise<boolean>;
     /** Wait for an asynchronous pause/resume operation to finish. */
     waitForStatus(status: 'paused' | 'running', opts?: SnapshotWaitOpts): Promise<SandboxInfo>;
@@ -1049,39 +1105,81 @@ declare class Sandbox extends SandboxClient {
      */
     setTimeout(timeoutMs: number, opts?: ConnectionOpts): Promise<void>;
     /**
-     * Register a public HTTPS route and return its hostname without a scheme.
+     * The token that opens this sandbox's published ports. Set by {@link getHost}
+     * and {@link exposePort}; send it as the `X-Lizard-Access-Token` header.
+     */
+    accessToken?: string;
+    /**
+     * Publish a port on a public HTTPS hostname and return the hostname without a scheme.
      *
-     * Useful for accessing HTTP servers started inside the sandbox from your
-     * agent or tests without additional tunneling.
+     * The port is private: requests need {@link accessToken} (set by this call) as
+     * the `X-Lizard-Access-Token` header, or `?lizard_token=<token>` in a browser.
+     * {@link exposePort} returns the token and a ready-made browser URL together.
      *
      * @example
      * ```ts
      * // Start an HTTP server on port 3000 before exposing it.
      * const hostname = await sandbox.getHost(3000)
-     * console.log(`https://${hostname}`)
+     * const res = await fetch(`https://${hostname}/`, {
+     *   headers: { 'X-Lizard-Access-Token': sandbox.accessToken! },
+     * })
      * ```
      */
     getHost(port: number, opts?: ConnectionOpts): Promise<string>;
-    /** Fork is unsupported on Kubernetes; the backend returns HTTP 501. */
+    /**
+     * Publish a port and return everything needed to reach it: the hostname, a
+     * browser `url` that carries the token, and the `accessToken` for API clients.
+     *
+     * @example
+     * ```ts
+     * const { url, hostname, accessToken } = await sandbox.exposePort(3000)
+     * console.log(url) // open in a browser
+     * await fetch(`https://${hostname}/api`, { headers: { 'X-Lizard-Access-Token': accessToken } })
+     * ```
+     */
+    exposePort(port: number, opts?: ConnectionOpts): Promise<ExposedPort>;
+    /**
+     * Clone this running sandbox `count` times (1-10). 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.
+     *
+     * 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
+     * limit). A sandbox with a volume attached cannot be forked (`ConflictError`, 409).
+     *
+     * @param opts.timeoutMs Lifetime of each fork; defaults to the source's timeout.
+     *
+     * @example
+     * ```ts
+     * const forks = await sandbox.fork({ count: 2 })
+     * for (const f of forks) if (f.sandbox) await f.sandbox.process.exec('echo hi')
+     * ```
+     */
     fork(opts?: {
         count?: number;
         timeoutMs?: number;
-    }): Promise<unknown>;
-    /** Capture memory and workspace files. Disconnect active clients before capturing. */
+    }): Promise<ForkResult<this>[]>;
+    /**
+     * Save this sandbox -- memory, running processes and files -- as a private
+     * snapshot. A Firecracker snapshot is `ready` as soon as this returns (about 2 s);
+     * start copies of it with {@link Sandbox.restore} (about 0.4 s each). The source
+     * keeps running. `poolSize` applies to container sandboxes only.
+     */
     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). */
     logs(opts?: {
         tail?: number;
         signal?: AbortSignal;
     }): AsyncGenerator<StreamEvent, any, any>;
     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. */
+    /** Start a new sandbox from a snapshot, 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. */
+    /** Release idle warm copies (container snapshots); 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>;
@@ -1526,8 +1624,10 @@ interface VolumeInfo {
     /** Region the volume's node lives in. A sandbox mounting it runs here too. */
     region?: string;
     status: string;
+    /** Id of the sandbox the volume is attached to, or `null` when it is free. */
     attachedTo?: string | null;
-    createdAt: number;
+    /** Creation time: an ISO-8601 string for Firecracker volumes, unix milliseconds for container volumes. */
+    createdAt: string | number;
     /**
      * Whether `sizeGb` is actually enforced as a hard limit on the volume's node.
      * Returned by {@link Volume.resize}; `false` means the size was recorded but the
@@ -1536,7 +1636,7 @@ interface VolumeInfo {
     sizeEnforced?: boolean;
 }
 interface CreateVolumeOpts extends ConnectionOpts {
-    /** Whole GB, default 5. New volumes allow 1–50 GB unless the server config sets another maximum. Creating never changes an existing volume's size; use `Volume.resize` for that. */
+    /** Whole GB, default 5. New volumes allow 1–50 GB unless the server config sets another maximum. Creating never changes an existing volume's size. */
     sizeGb?: number;
     /**
      * Region to place the volume in, e.g. `'us-east-1'`. A volume is node-local, so
@@ -1559,7 +1659,9 @@ interface CreateVolumeOpts extends ConnectionOpts {
  * Names are slugs: lowercase letters, digits and dashes, starting and ending with a
  * letter or digit, up to 64 characters.
  *
- * Mount one to a sandbox via `Sandbox.create({ volumeName: 'my-data' })`.
+ * Mount one to a sandbox via `Sandbox.create({ volumeName: 'my-data' })`; it appears
+ * at `/workspace`. A volume is attached to one sandbox at a time (`attachedTo`), and
+ * a sandbox with a volume attached cannot be forked.
  */
 declare class Volume {
     /** The volume's generated id. Stable, but you rarely need it — address by name. */
@@ -1582,7 +1684,7 @@ declare class Volume {
      * "the scratch disk for this task" no longer has to store an id between runs.
      *
      * An existing volume is returned as-is — `sizeGb` applies only to a fresh create,
-     * so an existing volume keeps its size. Call {@link Volume.resize} to change it.
+     * so an existing volume keeps its size.
      */
     static getOrCreate(projectId: string, name: string, opts?: CreateVolumeOpts): Promise<Volume>;
     /** Look a volume up by name or by id. */
@@ -1593,11 +1695,15 @@ declare class Volume {
     /**
      * Resize a volume, by name or by id, to `sizeGb`.
      *
-     * The change is in place and online: the size is a quota, so no data is copied,
-     * it completes in well under a second, and a sandbox that has the volume mounted
-     * keeps running and sees the new size immediately. Both growing and shrinking are
-     * allowed, but a shrink must leave at least 10% of the new size free — otherwise
-     * it throws `ConflictError` with `code: 'volume_too_full_to_shrink'`.
+     * **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.
+     *
+     * 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
+     * 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`,
      * `volume_resize_in_progress`, `volume_not_provisioned`,
@@ -1608,7 +1714,7 @@ declare class Volume {
      */
     static resize(projectId: string, nameOrId: string, sizeGb: number, opts?: ConnectionOpts): Promise<VolumeInfo>;
     getInfo(projectId: string): Promise<VolumeInfo>;
-    /** Resize this volume in place — see the static {@link Volume.resize}. */
+    /** Resize this volume — see the static {@link Volume.resize} (not supported for Firecracker volumes yet). */
     resize(projectId: string, sizeGb: number): Promise<VolumeInfo>;
     delete(projectId: string): Promise<void>;
 }
@@ -1826,7 +1932,7 @@ declare class Execution {
     results: OutputItem[];
     /** Execution error if the code threw an exception. */
     error?: ExecutionError;
-    /** Monotonically increasing counter for this context. */
+    /** Monotonically increasing counter for this context (the Python kernel's `In[n]`). */
     executionCount: number;
     get success(): boolean;
     get text(): string;
@@ -1841,11 +1947,15 @@ type RunCodeLanguage = 'python' | 'javascript' | 'bash' | (string & Record<never
 interface RunCodeOpts {
     /** Language to run in. Defaults to python. */
     language?: RunCodeLanguage;
-    /** Use a specific context instead of the per-language default. */
+    /** Use a specific context (from `createContext`) instead of the per-language default. */
     context?: CodeContext;
     /** Extra environment variables available to the code. */
     envs?: Record<string, string>;
-    /** Client timeout in milliseconds. No client timer is set when omitted. */
+    /**
+     * Execution timeout in milliseconds, default 60 000. A Python kernel that runs
+     * past it is interrupted (its state is kept) and `execution.error.name` is
+     * `'TimeoutError'`; a process is killed.
+     */
     timeoutMs?: number;
     onStdout?: (data: string) => void;
     onStderr?: (data: string) => void;
@@ -1858,31 +1968,47 @@ interface CreateContextOpts {
 }
 
 /**
- * Legacy client for the code-interpreter execution server.
+ * A sandbox for running code snippets, built on {@link Sandbox.process}.
  *
- * Current hosted templates do not provide this server. The default
- * `code-interpreter-v1` template is unavailable; selecting `interpreter`
- * does not enable this API. Use `Sandbox.create('interpreter', options)`
- * and `sandbox.process.exec()` for Python commands instead.
+ * Boots the `interpreter` template by default. Python runs in a persistent
+ * Jupyter kernel per context, so variables, imports and functions carry over
+ * between calls, `execution.results` holds rich output (the value of the last
+ * expression, matplotlib charts as `image/png`, HTML, ...) and errors carry
+ * the exception name and traceback.
  *
- * The methods remain for compatibility with a separately provided server.
+ * 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.
+ * - 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
+ *   produced them, not per character.
+ *
+ * Kernels live inside the sandbox's microVM, so pause/resume, snapshots and
+ * forks keep their state.
+ *
+ * @example
+ * ```ts
+ * 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"
+ * await sandbox.kill()
+ * ```
  */
 declare class CodeSandbox extends Sandbox {
-    protected static readonly defaultTemplate = "code-interpreter-v1";
-    private get serverUrl();
+    protected static readonly defaultTemplate: string;
     /**
-     * Execute code in a persistent kernel.
+     * Execute code and wait for it to finish.
      *
-     * Variables, imports, and function definitions from previous calls are
-     * available in subsequent calls within the same context.
+     * Python keeps its state per context (the default context, per language,
+     * when none is given). Code errors appear in `execution.error`; request
+     * failures throw.
      *
      * @param code  Source code to run.
      * @param opts  Language, context, env vars, timeout, and streaming callbacks.
      *
-     * @returns Execution result with stdout, stderr, results, and any error.
-     *
-     * Code errors appear in `execution.error`; request failures throw.
-     *
      * @example
      * ```ts
      * const result = await sandbox.runCode(`
@@ -1896,8 +2022,8 @@ declare class CodeSandbox extends Sandbox {
     /**
      * Create a new isolated execution context.
      *
-     * Each context maintains its own variable namespace and process state.
-     * Useful for running multiple independent sessions in the same sandbox.
+     * A Python context is its own kernel: its own variables, and `cwd` as its
+     * working directory. Other languages get the working directory only.
      *
      * @example
      * ```ts
@@ -1907,18 +2033,14 @@ declare class CodeSandbox extends Sandbox {
      * ```
      */
     createContext(opts?: CreateContextOpts): Promise<CodeContext>;
-    /**
-     * List all active execution contexts in this sandbox.
-     */
+    /** List the contexts created with {@link createContext} in this sandbox. */
     listContexts(): Promise<CodeContext[]>;
-    /**
-     * Delete an execution context and free its resources.
-     */
+    /** Delete an execution context, stopping its kernel. */
     deleteContext(context: CodeContext | string): Promise<void>;
-    /**
-     * Restart a context, clearing all variables and state.
-     */
+    /** Restart a context, clearing all variables and state. */
     restartContext(context: CodeContext | string): Promise<void>;
+    /** Run the in-sandbox runner with `args` and hand each of its events to `onEvent`. */
+    private runner;
     static create(opts?: SandboxOpts): Promise<CodeSandbox>;
     static create(template: string, opts?: SandboxOpts): Promise<CodeSandbox>;
     static connect(sandboxId: string, opts?: ConnectionOpts): Promise<CodeSandbox>;
@@ -1948,4 +2070,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 ClickOpts, 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, Desktop, type DesktopInfo, type DesktopStartOpts, 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, type MouseButton, 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 ScrollDirection, 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 };
+export { type Account, type Addon, type AddonType, AddonsAPI, type ApiKey, type ApiKeyScope, ApiKeysAPI, AuthenticationError, type Balance, BillingAPI, type CLIOptions, type CLIResult, type ClickOpts, 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, Desktop, type DesktopInfo, type DesktopStartOpts, type DomainInfo, type DomainStatus, DomainsAPI, Execution, ExecutionError, type ExposedPort, type FileInfo, type ForkResult, type FsEvent, type FsOpts, GitHubAPI, type ListTransactionsOpts, Lizard, LizardCLI, LizardError, type LizardOpts, type LogLine, type MetricPoint, type MetricRange, MetricsAPI, type MouseButton, NotFoundError, PlatformClient, type ProcessInfo, type ProcessOpts, type ProcessResult, type ProcessSignal, 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 ScrollDirection, 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 };