withruntime 0.11.2 → 0.14.0

package/dist/daytona/sandbox.js

@@ -90,6 +90,7 @@ export class Sandbox {
     git;
     codeInterpreter;
     env;
+    /** Whether its previews are public; setPublic changes it. */
     public;
     snapshot;
     #rt;
@@ -349,8 +350,21 @@ export class Sandbox {
         const runtime = await this.#live();
         await guard("sandbox", () => runtime.network.set(rules ?? { internet: true }));
     }
+    /** Makes every port it shares public, or private with a token, and the
+     * ports getPreviewLink shares from now on. A port already shared changes
+     * at once, keeping its address, as on Daytona. Without credit, public is
+     * refused (public_preview_not_allowed) and nothing changes. */
+    async setPublic(isPublic) {
+        const visibility = isPublic ? "public" : "private";
+        const runtime = await this.#live();
+        const shared = await guard("sandbox", () => runtime.previews.list());
+        for (const preview of shared)
+            if (preview.visibility !== visibility)
+                await guard("sandbox", () => runtime.previews.create(preview.port, { visibility }));
+        this.public = isPublic;
+    }
     /** A preview address for `port`: public when the sandbox was created with
-     * `public: true`, else private with a token. */
+     * `public: true` or setPublic(true) since, else private with a token. */
     async getPreviewLink(port) {
         const runtime = await this.#live();
         const preview = await guard("sandbox", () => runtime.previews.create(port, { visibility: this.public ? "public" : "private" }));
@@ -440,7 +454,7 @@ export class Sandbox {
         return refusal("Signed download URLs", "Use sandbox.fs.downloadFile(path).");
     }
     createSshAccess() {
-        return refusal("SSH access", "Use `npx withruntime sandbox ssh <id>` (also VS Code and JetBrains) or sandbox.withruntime.terminal().");
+        return refusal("SSH access", "Use `npx withruntime sandboxes ssh <id>` (also VS Code and JetBrains) or sandbox.withruntime.terminal().");
     }
     revokeSshAccess() {
         return this.createSshAccess();

package/dist/domains/index.d.ts

@@ -0,0 +1,9 @@
+/** `withruntime/domains`: Domains alone. Your own hostname for a sandbox's port, with HTTPS.
+ *
+ *   import { domains } from "withruntime/domains";
+ *   const client = domains(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime, type RuntimeOptions } from "../client.js";
+export type { Domain, CheckedDomain, DnsRecord } from "../products/network-products.js";
+/** `runtime.domains` of a client made with `options`. */
+export declare function domains(options?: RuntimeOptions): Runtime["domains"];

package/dist/domains/index.js

@@ -0,0 +1,10 @@
+/** `withruntime/domains`: Domains alone. Your own hostname for a sandbox's port, with HTTPS.
+ *
+ *   import { domains } from "withruntime/domains";
+ *   const client = domains(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime } from "../client.js";
+/** `runtime.domains` of a client made with `options`. */
+export function domains(options) {
+    return new Runtime(options).domains;
+}

package/dist/e2b/commands.d.ts

@@ -1,6 +1,6 @@
 import type { Process } from "../sandbox.js";
 import type { OutputEvent, ProcessInfo as RuntimeProcessInfo } from "../types.js";
-import type { RequestOptions } from "../transport.js";
+import { type RequestOptions } from "../transport.js";
 import type { RuntimeSandbox } from "./client.js";
 import { TimeoutError, type CommandResult } from "./errors.js";
 export type { CommandResult };

package/dist/e2b/commands.js

@@ -1,4 +1,5 @@
-import { CommandExitError, guard, InvalidArgumentError, SandboxError, SandboxNotFoundError, TimeoutError, translate, } from "./errors.js";
+import { timeoutSignal } from "../transport.js";
+import { CommandExitError, guard, InvalidArgumentError, SandboxError, SandboxNotFoundError, SandboxNotRunningError, TimeoutError, translate, } from "./errors.js";
 import { commandAs, listedAs, runAs } from "./users.js";
 const DEFAULT_TIMEOUT_MS = 60_000;
 /** How long a command may run on Runtime: a day, E2B's longest sandbox. E2B's
@@ -25,7 +26,7 @@ export function timeoutFor(timeoutMs) {
 export function commandRequest(opts, defaultTimeoutMs = 60_000) {
     opts.signal?.throwIfAborted();
     const timeoutMs = timeoutFor(opts.requestTimeoutMs ?? defaultTimeoutMs);
-    const deadline = timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : undefined;
+    const deadline = timeoutMs > 0 ? timeoutSignal(timeoutMs) : undefined;
     const signal = opts.signal && deadline ? AbortSignal.any([opts.signal, deadline]) : (opts.signal ?? deadline);
     return { timeoutMs: 0, ...(signal ? { signal } : {}) };
 }
@@ -85,7 +86,7 @@ function toResult(result) {
 export function connectionRequest(opts, defaultTimeoutMs) {
     const timeoutMs = timeoutFor(opts.timeoutMs);
     const deadline = timeoutMs > 0 ? performance.now() + timeoutMs : undefined;
-    const connectionTimeout = timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : undefined;
+    const connectionTimeout = timeoutMs > 0 ? timeoutSignal(timeoutMs) : undefined;
     const signal = connectionTimeout && opts.signal
         ? AbortSignal.any([connectionTimeout, opts.signal])
         : (connectionTimeout ?? opts.signal);
@@ -243,11 +244,9 @@ function describe(info) {
         cwd: info.cwd,
     };
 }
-/** A command whose sandbox went away under it, as E2B says it: a
- * TimeoutError, which code written for E2B catches (5 October 2026: it was a
- * SandboxNotFoundError). */
+/** E2B 2.53's confirmed sandbox loss remains catchable as TimeoutError. */
 function sandboxEnded(cause) {
-    const error = new TimeoutError("The command ended before the stream completed: the sandbox was killed or reached its end of life.");
+    const error = new SandboxNotRunningError("The command ended before the stream completed: the sandbox was killed or reached its end of life.");
     error.cause = cause;
     return error;
 }

package/dist/e2b/errors.d.ts

@@ -8,6 +8,14 @@ export declare class SandboxError extends Error {
 }
 export declare class TimeoutError extends SandboxError {
 }
+/** The sandbox is confirmed stopped or paused; create or resume one. */
+export declare class SandboxNotRunningError extends TimeoutError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** The sandbox cannot be reached, without confirmation that it stopped. */
+export declare class SandboxUnreachableError extends TimeoutError {
+    constructor(message: string, options?: ErrorOptions);
+}
 export declare class InvalidArgumentError extends SandboxError {
 }
 export declare class NotEnoughSpaceError extends SandboxError {
@@ -62,6 +70,15 @@ export declare class SecretError extends Error {
 }
 export declare class SecretNotFoundError extends SecretError {
 }
+/** E2B 2.55's Dockerfile parse error, from `@e2b/dockerfile-utils`: a plain
+ * Error, not a SandboxError, with the line it names. Runtime parses no
+ * Dockerfile here (templates are Runtime images, built by
+ * `npx withruntime images build`), so nothing throws it; it exists so that
+ * code importing it or catching it still loads. */
+export declare class DockerfileSyntaxError extends Error {
+    readonly line: number | undefined;
+    constructor(message: string, line?: number);
+}
 /** A call that E2B supports and Runtime does not, or not in the same way.
  * Thrown before anything is done, never after doing something different.
  * `feature` names what was asked for; `alternative` says what to use on

package/dist/e2b/errors.js

@@ -23,6 +23,24 @@ export class SandboxError extends Error {
 }
 export class TimeoutError extends SandboxError {
 }
+/** The sandbox is confirmed stopped or paused; create or resume one. */
+export class SandboxNotRunningError extends TimeoutError {
+    constructor(message, options) {
+        super(message);
+        this.name = "SandboxNotRunningError";
+        if (options?.cause !== undefined)
+            this.cause = options.cause;
+    }
+}
+/** The sandbox cannot be reached, without confirmation that it stopped. */
+export class SandboxUnreachableError extends TimeoutError {
+    constructor(message, options) {
+        super(message);
+        this.name = "SandboxUnreachableError";
+        if (options?.cause !== undefined)
+            this.cause = options.cause;
+    }
+}
 export class InvalidArgumentError extends SandboxError {
 }
 export class NotEnoughSpaceError extends SandboxError {
@@ -92,6 +110,21 @@ export class SecretError extends Error {
 }
 export class SecretNotFoundError extends SecretError {
 }
+/** E2B 2.55's Dockerfile parse error, from `@e2b/dockerfile-utils`: a plain
+ * Error, not a SandboxError, with the line it names. Runtime parses no
+ * Dockerfile here (templates are Runtime images, built by
+ * `npx withruntime images build`), so nothing throws it; it exists so that
+ * code importing it or catching it still loads. */
+export class DockerfileSyntaxError extends Error {
+    line;
+    constructor(message, line) {
+        super(line === undefined
+            ? `Dockerfile parse error: ${message}`
+            : `Dockerfile parse error on line ${line}: ${message}`);
+        this.line = line;
+        this.name = "DockerfileSyntaxError";
+    }
+}
 /** A call that E2B supports and Runtime does not, or not in the same way.
  * Thrown before anything is done, never after doing something different.
  * `feature` names what was asked for; `alternative` says what to use on
@@ -159,7 +192,13 @@ export function translate(error, subject = "other") {
         .filter(Boolean)
         .join("\n");
     let out;
-    if (error.status === 503 && error.code.endsWith("_unavailable"))
+    // Runtime reports the sandbox state explicitly. A generic connection failure
+    // does not prove it stopped; never replay a command or write to classify it.
+    if (["sandbox_stopped", "sandbox_paused", "sandbox_not_running"].includes(error.code))
+        out = new SandboxNotRunningError(message);
+    else if (error.code === "sandbox_not_ready" || error.code === "host_unavailable")
+        out = new SandboxUnreachableError(message);
+    else if (error.status === 503 && error.code.endsWith("_unavailable"))
         // A product switched off on purpose (forks, previews): Runtime's own words
         // say what is off and what to use meanwhile.
         out = new NotSupportedError(error.code.replace(/_unavailable$/, ""), error.hint ?? "", message);

package/dist/e2b/index.d.ts

@@ -7,10 +7,10 @@
 import type { Runtime } from "../client.js";
 import { type ConnectionOpts } from "./client.js";
 import { Sandbox } from "./sandbox.js";
-export { Sandbox, SandboxPaginator, DEFAULT_SHAPE, DEFAULT_TIMEOUT_MS, type SandboxOpts, type SandboxConnectOpts, type SandboxApiOpts, type SandboxInfo, type SandboxListOpts, type SandboxState, type SandboxLifecycle, type SandboxOnTimeout, type SnapshotInfo, } from "./sandbox.js";
+export { Sandbox, SandboxPaginator, DEFAULT_SHAPE, DEFAULT_TIMEOUT_MS, type SandboxOpts, type SandboxConnectOpts, type SandboxApiOpts, type SandboxInfo, type SandboxListOpts, type SandboxState, type SandboxLifecycle, type SandboxOnTimeout, type SandboxPauseOpts, type CreateSnapshotOpts, type SnapshotMode, type SnapshotInfo, } from "./sandbox.js";
 export { Commands, CommandHandle, pidOf, type CommandStartOpts, type CommandConnectOpts, type CommandRequestOpts, type ProcessInfo, type Username, } from "./commands.js";
 export { Filesystem, FileType, type EntryInfo, type WriteInfo, type WriteEntry, type FilesystemRequestOpts, type FilesystemReadOpts, type FilesystemWriteOpts, type FilesystemListOpts, FilesystemEventType, type FilesystemEvent, type WatchOpts, type E2BWatchHandle as WatchHandle, } from "./filesystem.js";
-export { SandboxError, TimeoutError, InvalidArgumentError, NotEnoughSpaceError, NotFoundError, FileNotFoundError, SandboxNotFoundError, TemplateError, RateLimitError, AuthenticationError, ServiceBusyError, CommandExitError, NotSupportedError, PublicPreviewNotAllowedError, GitAuthError, GitUpstreamError, BuildError, FileUploadError, VolumeError, VolumeNotFoundError, VolumePathNotFoundError, SecretError, SecretNotFoundError, type CommandResult, } from "./errors.js";
+export { SandboxError, TimeoutError, InvalidArgumentError, NotEnoughSpaceError, NotFoundError, FileNotFoundError, SandboxNotFoundError, SandboxNotRunningError, SandboxUnreachableError, TemplateError, RateLimitError, AuthenticationError, ServiceBusyError, CommandExitError, NotSupportedError, PublicPreviewNotAllowedError, GitAuthError, GitUpstreamError, BuildError, FileUploadError, VolumeError, VolumeNotFoundError, VolumePathNotFoundError, SecretError, SecretNotFoundError, DockerfileSyntaxError, type CommandResult, } from "./errors.js";
 export type { ConnectionOpts, HttpVersion, RuntimeOpts } from "./client.js";
 export { Pty, type PtyCreateOpts, type PtyConnectOpts } from "./pty.js";
 export { Template, TemplateBase, Volume, Secret, waitForPort, waitForURL, waitForProcess, waitForFile, waitForTimeout, SecretPaginator, Git, ReadyCmd, LogEntry, LogEntryStart, LogEntryEnd, defaultBuildLogger, ConnectionConfig, ApiClient, getSignature, ALL_TRAFFIC, VolumeFileType, } from "./unsupported.js";

package/dist/e2b/index.js

@@ -3,7 +3,7 @@ import { Sandbox } from "./sandbox.js";
 export { Sandbox, SandboxPaginator, DEFAULT_SHAPE, DEFAULT_TIMEOUT_MS, } from "./sandbox.js";
 export { Commands, CommandHandle, pidOf, } from "./commands.js";
 export { Filesystem, FileType, FilesystemEventType, } from "./filesystem.js";
-export { SandboxError, TimeoutError, InvalidArgumentError, NotEnoughSpaceError, NotFoundError, FileNotFoundError, SandboxNotFoundError, TemplateError, RateLimitError, AuthenticationError, ServiceBusyError, CommandExitError, NotSupportedError, PublicPreviewNotAllowedError, GitAuthError, GitUpstreamError, BuildError, FileUploadError, VolumeError, VolumeNotFoundError, VolumePathNotFoundError, SecretError, SecretNotFoundError, } from "./errors.js";
+export { SandboxError, TimeoutError, InvalidArgumentError, NotEnoughSpaceError, NotFoundError, FileNotFoundError, SandboxNotFoundError, SandboxNotRunningError, SandboxUnreachableError, TemplateError, RateLimitError, AuthenticationError, ServiceBusyError, CommandExitError, NotSupportedError, PublicPreviewNotAllowedError, GitAuthError, GitUpstreamError, BuildError, FileUploadError, VolumeError, VolumeNotFoundError, VolumePathNotFoundError, SecretError, SecretNotFoundError, DockerfileSyntaxError, } from "./errors.js";
 export { Pty } from "./pty.js";
 export { Template, TemplateBase, Volume, Secret, waitForPort, waitForURL, waitForProcess, waitForFile, waitForTimeout, SecretPaginator, Git, ReadyCmd, LogEntry, LogEntryStart, LogEntryEnd, defaultBuildLogger, ConnectionConfig, ApiClient, getSignature, ALL_TRAFFIC, VolumeFileType, } from "./unsupported.js";
 export default Sandbox;

package/dist/e2b/sandbox.d.ts

@@ -18,9 +18,26 @@ export declare const DEFAULT_TIMEOUT_MS = 300000;
  * and list name it whichever client asks; it is not shown in `metadata`. */
 export declare const TEMPLATE_LABEL = "e2b-template";
 export type SandboxState = "running" | "paused";
+/** What a pause or snapshot keeps (E2B 2.55): `"full"` keeps memory and
+ * files, `"filesystem"` only files, so what starts from it boots afresh. */
+export type SnapshotMode = "full" | "filesystem";
 export type SandboxOnTimeout = "pause" | "kill" | {
-    action: "pause" | "kill";
+    action: "pause";
+    mode?: SnapshotMode;
+    /** @deprecated E2B 2.55: use `mode`. */
     keepMemory?: boolean;
+} | {
+    action: "kill";
+};
+/** E2B's pause options: `mode`, or the deprecated `keepMemory`. */
+export type SandboxPauseOpts = SandboxApiOpts & {
+    mode?: SnapshotMode;
+    /** @deprecated E2B 2.55: use `mode`. */
+    keepMemory?: boolean;
+};
+export type CreateSnapshotOpts = SandboxApiOpts & {
+    name?: string;
+    mode?: SnapshotMode;
 };
 export type SandboxLifecycle = {
     onTimeout: SandboxOnTimeout;
@@ -116,7 +133,7 @@ export declare class Sandbox {
     protected get client(): Runtime;
     /** Creates a sandbox from `template` (default "base", Runtime's stock image)
      * with E2B's default machine, 2 vCPU and 512 MiB, and waits until it runs.
-     * Funding is left to Runtime: the included usage first, then prepaid credit, exactly as withruntime's own create. */
+     * Funding is left to Runtime: the free usage first, then prepaid credit, exactly as withruntime's own create. */
     static create<S extends typeof Sandbox>(this: S, opts?: SandboxOpts): Promise<InstanceType<S>>;
     static create<S extends typeof Sandbox>(this: S, template: string, opts?: SandboxOpts): Promise<InstanceType<S>>;
     /** Connects to a sandbox by id, waking it if it is paused, as E2B does. A
@@ -145,18 +162,10 @@ export declare class Sandbox {
      * next call wakes it. False once paused on request, ended or deleted. */
     isRunning(opts?: Pick<ConnectionOpts, "requestTimeoutMs" | "signal">): Promise<boolean>;
     /** Pauses the sandbox, keeping memory and files. False when it was paused. */
-    static pause(sandboxId: string, opts?: SandboxApiOpts & {
-        keepMemory?: boolean;
-    }): Promise<boolean>;
-    static betaPause(sandboxId: string, opts?: SandboxApiOpts & {
-        keepMemory?: boolean;
-    }): Promise<boolean>;
-    pause(opts?: SandboxApiOpts & {
-        keepMemory?: boolean;
-    }): Promise<boolean>;
-    betaPause(opts?: SandboxApiOpts & {
-        keepMemory?: boolean;
-    }): Promise<boolean>;
+    static pause(sandboxId: string, opts?: SandboxPauseOpts): Promise<boolean>;
+    static betaPause(sandboxId: string, opts?: SandboxPauseOpts): Promise<boolean>;
+    pause(opts?: SandboxPauseOpts): Promise<boolean>;
+    betaPause(opts?: SandboxPauseOpts): Promise<boolean>;
     /** Copies of this sandbox, memory and all. While Runtime's forks are
      * switched off this throws NotSupportedError with Runtime's own words. */
     static fork<S extends typeof Sandbox>(this: S, sandboxId: string, opts?: SandboxApiOpts & {
@@ -167,14 +176,11 @@ export declare class Sandbox {
         count?: number;
         timeoutMs?: number;
     }): Promise<Array<this | Error>>;
-    /** Keeps the sandbox's whole machine as a Runtime snapshot; start from it
-     * with Sandbox.create(snapshotId). */
-    createSnapshot(opts?: SandboxApiOpts & {
-        name?: string;
-    }): Promise<SnapshotInfo>;
-    static createSnapshot(sandboxId: string, opts?: SandboxApiOpts & {
-        name?: string;
-    }): Promise<SnapshotInfo>;
+    /** Keeps the sandbox's whole machine as a Runtime snapshot, or with
+     * `mode: "filesystem"` its disk alone, from which a sandbox boots afresh;
+     * start from it with Sandbox.create(snapshotId). */
+    createSnapshot(opts?: CreateSnapshotOpts): Promise<SnapshotInfo>;
+    static createSnapshot(sandboxId: string, opts?: CreateSnapshotOpts): Promise<SnapshotInfo>;
     static deleteSnapshot(snapshotId: string, opts?: SandboxApiOpts): Promise<boolean>;
     /** E2B's getHost, answered at once as E2B answers it:
      * `<port>-<id>.runtimehost.com`. A Runtime preview's address is made from

package/dist/e2b/sandbox.js

@@ -28,6 +28,7 @@ export const TEMPLATE_LABEL = "e2b-template";
 /** E2B template names that mean "the stock environment": Runtime's default image. */
 const STOCK_TEMPLATES = new Set(["base", "code-interpreter-v1", "code-interpreter"]);
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SNAPSHOT_MODES = ["full", "filesystem"];
 let warnedShortLease = false;
 /** E2B's own bound since 2.52.0: refused before anything happens. */
 const MAX_FORK_COUNT = 20;
@@ -64,10 +65,28 @@ function onTimeout(lifecycle, timeoutAsked) {
     if (!lifecycle)
         return timeoutAsked ? "delete" : "pause";
     const action = typeof lifecycle.onTimeout === "string" ? lifecycle.onTimeout : lifecycle.onTimeout.action;
-    if (typeof lifecycle.onTimeout === "object" && lifecycle.onTimeout.keepMemory === false)
-        throw new NotSupportedError("A files-only pause (keepMemory: false)", "Runtime's pause keeps memory and files; leave keepMemory out.");
+    // As E2B 2.55 checks: mode (or keepMemory) belongs to a pause alone.
+    const pauseOpts = (typeof lifecycle.onTimeout === "string" ? {} : lifecycle.onTimeout);
+    if (("mode" in pauseOpts || "keepMemory" in pauseOpts) && action !== "pause")
+        throw new InvalidArgumentError("onTimeout.mode is only allowed when action is 'pause'.");
+    if (snapshotMemory("onTimeout.mode", pauseOpts.mode, pauseOpts.keepMemory) === false)
+        throw filesOnlyPause();
     return action === "pause" ? "pause" : "delete";
 }
+/** E2B 2.55's reading of `mode`, or the deprecated `keepMemory`: whether
+ * memory is kept, or undefined when neither was given. Both at once, or a
+ * mode E2B does not know, is E2B's InvalidArgumentError. */
+function snapshotMemory(field, mode, keepMemory) {
+    if (mode != null && keepMemory != null)
+        throw new InvalidArgumentError(`Pass either ${field} or the deprecated keepMemory, not both.`);
+    if (mode == null)
+        return keepMemory ?? undefined;
+    if (!SNAPSHOT_MODES.includes(mode))
+        throw new InvalidArgumentError(`${field} must be one of: ${SNAPSHOT_MODES.join(", ")} (got ${JSON.stringify(mode)}).`);
+    return mode === "full";
+}
+const filesOnlyPause = () => new NotSupportedError("A files-only pause (mode: 'filesystem', or keepMemory: false)", "Runtime's pause keeps memory and files; leave mode out or pass mode: 'full'. " +
+    "For a copy of the files alone, use createSnapshot({ mode: 'filesystem' }).");
 function refuseCreate(opts) {
     const refusals = [
         [
@@ -141,7 +160,7 @@ function templateMissing(template, cause, account) {
     const name = imageNameFor(template).replace(/[:@].*$/, "");
     const error = new TemplateError(`No Runtime image is named "${imageNameFor(template)}"${account ?? ""}. E2B templates do not run on Runtime; build the same ` +
         `environment as a Runtime image with that name and this call starts from it: ` +
-        `\`npx withruntime image build --dockerfile e2b.Dockerfile --name ${name}\`, or ` +
+        `\`npx withruntime images build --dockerfile e2b.Dockerfile --name ${name}\`, or ` +
         `runtime.images.build({ name: "${name}", dockerfile }).`);
     error.code = "template_not_found";
     error.cause = cause;
@@ -466,10 +485,17 @@ export class Sandbox {
         const Kind = this.constructor;
         return copies.map((copy) => new Kind(copy, this.#client));
     }
-    /** Keeps the sandbox's whole machine as a Runtime snapshot; start from it
-     * with Sandbox.create(snapshotId). */
+    /** Keeps the sandbox's whole machine as a Runtime snapshot, or with
+     * `mode: "filesystem"` its disk alone, from which a sandbox boots afresh;
+     * start from it with Sandbox.create(snapshotId). */
     async createSnapshot(opts = {}) {
-        const snapshot = await guard("sandbox", () => this.#runtime.snapshot({ ...(opts.name ? { name: opts.name } : {}), ...request(opts) }));
+        const memory = snapshotMemory("mode", opts.mode);
+        const mode = memory === undefined ? undefined : memory ? "memory" : "disk";
+        const snapshot = await guard("sandbox", () => this.#runtime.snapshot({
+            ...(opts.name ? { name: opts.name } : {}),
+            ...(mode ? { mode } : {}),
+            ...request(opts),
+        }));
         return { snapshotId: snapshot.id, names: snapshot.name ? [snapshot.name] : [] };
     }
     static async createSnapshot(sandboxId, opts = {}) {
@@ -601,8 +627,8 @@ async function extendTo(runtime, timeoutMs, opts) {
         await guard("sandbox", () => runtime.extend(Math.ceil(later), request(opts)));
 }
 async function pause(runtime, opts) {
-    if (opts.keepMemory === false)
-        throw new NotSupportedError("A files-only pause (keepMemory: false)", "Runtime's pause keeps memory and files; leave keepMemory out.");
+    if (snapshotMemory("mode", opts.mode, opts.keepMemory) === false)
+        throw filesOnlyPause();
     const current = state(runtime);
     if (current === "paused")
         return false;

package/dist/e2b/unsupported.js

@@ -15,7 +15,7 @@ export function unsupportedExport(name, alternative) {
         },
     });
 }
-const TEMPLATES = "Build a Runtime image instead: `npx withruntime image build --dockerfile e2b.Dockerfile --name <template>` or runtime.images.build({ name, dockerfile | recipe }), then Sandbox.create('<template>').";
+const TEMPLATES = "Build a Runtime image instead: `npx withruntime images build --dockerfile e2b.Dockerfile --name <template>` or runtime.images.build({ name, dockerfile | recipe }), then Sandbox.create('<template>').";
 export const Template = unsupportedExport("Template builder", TEMPLATES);
 export const TemplateBase = unsupportedExport("TemplateBase", TEMPLATES);
 export const waitForPort = unsupportedExport("waitForPort (a template ready check)", TEMPLATES);

package/dist/errors.d.ts

@@ -13,7 +13,7 @@ export declare const DELIBERATE: ReadonlySet<string>;
  * minutes when it has none), however many retries it allows otherwise. */
 export declare const NOTHING_RAN: ReadonlySet<string>;
 /** Refusals of a create that clear when a sandbox stops or pauses, or a host
- * frees room: an account without credit's eight at once and its total, an
+ * frees room: an account without credit's four at once and its total, an
  * email domain's, the account's quota and the region's capacity. `sandboxes.create` waits them out, retrying
  * with the same key and input, for up to `waitForCapacityMs`. */
 export declare const WAITS_FOR_ROOM: ReadonlySet<string>;
@@ -68,7 +68,9 @@ export declare class AccountBlockedError extends RuntimeError {
  * same idempotencyKey (the SDK does, automatically) settles it safely. */
 export declare class ConnectionError extends RuntimeError {
 }
-/** Raised by exec({ check: true }) when a command exits non-zero. */
+/** Raised by exec({ check: true }) when a command exits non-zero. Its code
+ * is `out_of_memory` when the sandbox's out-of-memory killer ended it, with
+ * the result's message and hint. */
 export declare class CommandError extends RuntimeError {
     readonly exitCode: number | null;
     readonly stdout: string;
@@ -78,6 +80,13 @@ export declare class CommandError extends RuntimeError {
         stdout: string;
         stderr: string;
         timedOut?: boolean;
+        outOfMemory?: {
+            code: string;
+            message: string;
+            hint: string;
+        };
     });
+    /** The same command in the same sandbox runs out of memory again. */
+    get retryable(): boolean;
 }
 export declare function errorFor(status: number, body: unknown, idempotencyKey?: string): RuntimeError;

package/dist/errors.js

@@ -15,6 +15,7 @@ export const DELIBERATE = new Set([
     "secrets_unavailable",
     "identity_unavailable",
     "env_unavailable",
+    "resize_unavailable",
 ]);
 /** Refusals that guarantee nothing ran: a sandbox running as many commands
  * as it can (`guest_busy`), and the API's own limits, which answer before any
@@ -26,7 +27,7 @@ export const NOTHING_RAN = new Set(["guest_busy", "busy", "rate_limited"]);
  * account without credit stops. */
 const PASSING = new Set(["no_capacity", "no_credit_running_limit", "no_credit_total_limit"]);
 /** Refusals of a create that clear when a sandbox stops or pauses, or a host
- * frees room: an account without credit's eight at once and its total, an
+ * frees room: an account without credit's four at once and its total, an
  * email domain's, the account's quota and the region's capacity. `sandboxes.create` waits them out, retrying
  * with the same key and input, for up to `waitForCapacityMs`. */
 export const WAITS_FOR_ROOM = new Set([
@@ -36,7 +37,8 @@ export const WAITS_FOR_ROOM = new Set([
     "no_credit_capacity_full",
     "quota_exceeded",
     "no_capacity",
-    // A volume whose last sandbox is stopping: free within seconds.
+    // A volume whose last sandbox is stopping: free once the stop lets go of
+    // its disk, up to about a minute (measured 50 to 60 s, 6 October 2026).
     "volume_releasing",
 ]);
 export class RuntimeError extends Error {
@@ -104,23 +106,33 @@ export class AccountBlockedError extends RuntimeError {
  * same idempotencyKey (the SDK does, automatically) settles it safely. */
 export class ConnectionError extends RuntimeError {
 }
-/** Raised by exec({ check: true }) when a command exits non-zero. */
+/** Raised by exec({ check: true }) when a command exits non-zero. Its code
+ * is `out_of_memory` when the sandbox's out-of-memory killer ended it, with
+ * the result's message and hint. */
 export class CommandError extends RuntimeError {
     exitCode;
     stdout;
     stderr;
     constructor(result) {
+        const memory = result.outOfMemory;
         super({
             message: result.timedOut
                 ? "Command timed out."
-                : `Command exited with ${result.exitCode}.${result.stderr ? ` ${result.stderr.trim().slice(-500)}` : ""}`,
-            code: result.timedOut ? "command_timeout" : "command_failed",
+                : memory
+                    ? `Command exited with ${result.exitCode}. ${memory.message}`
+                    : `Command exited with ${result.exitCode}.${result.stderr ? ` ${result.stderr.trim().slice(-500)}` : ""}`,
+            code: result.timedOut ? "command_timeout" : memory ? memory.code : "command_failed",
             status: 0,
+            ...(memory && !result.timedOut ? { hint: memory.hint } : {}),
         });
         this.exitCode = result.exitCode;
         this.stdout = result.stdout;
         this.stderr = result.stderr;
     }
+    /** The same command in the same sandbox runs out of memory again. */
+    get retryable() {
+        return this.code === "out_of_memory" ? false : super.retryable;
+    }
 }
 export function errorFor(status, body, idempotencyKey) {
     const error = body?.error ?? {};