withruntime 0.3.0 → 0.4.0

package/dist/e2b/errors.js

@@ -0,0 +1,151 @@
+import { RuntimeError } from "../errors.js";
+function attach(error, detail) {
+    const target = error;
+    if (detail.code !== undefined)
+        target.code = detail.code;
+    if (detail.hint !== undefined)
+        target.hint = detail.hint;
+    if (detail.requestId !== undefined)
+        target.requestId = detail.requestId;
+    if (detail.cause !== undefined)
+        target.cause = detail.cause;
+}
+/** Base class for E2B's sandbox errors. */
+export class SandboxError extends Error {
+    statusCode;
+    code;
+    hint;
+    requestId;
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+export class TimeoutError extends SandboxError {
+}
+export class InvalidArgumentError extends SandboxError {
+}
+export class NotEnoughSpaceError extends SandboxError {
+}
+export class NotFoundError extends SandboxError {
+}
+export class FileNotFoundError extends NotFoundError {
+}
+export class SandboxNotFoundError extends NotFoundError {
+}
+export class TemplateError extends SandboxError {
+}
+export class RateLimitError extends SandboxError {
+}
+/** E2B's AuthenticationError extends Error, not SandboxError. */
+export class AuthenticationError extends Error {
+    code;
+    hint;
+    requestId;
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+/** E2B's ServiceBusyError extends Error, not SandboxError. */
+export class ServiceBusyError extends Error {
+    statusCode = 503;
+    code;
+    hint;
+    requestId;
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+/** 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
+ * Runtime instead. */
+export class NotSupportedError extends SandboxError {
+    feature;
+    alternative;
+    constructor(feature, alternative, message) {
+        super(message ?? `${feature} is not supported on Runtime. ${alternative}`);
+        this.feature = feature;
+        this.alternative = alternative;
+        this.code = "not_supported";
+    }
+}
+/** Thrown by `commands.run` and `CommandHandle.wait` when the command exits
+ * with a code other than 0. It carries the result, as in E2B. */
+export class CommandExitError extends SandboxError {
+    #result;
+    constructor(result) {
+        super(`Command exited with code ${result.exitCode} and error:\n${result.stderr}`);
+        this.#result = result;
+    }
+    get exitCode() {
+        return this.#result.exitCode;
+    }
+    get error() {
+        return this.#result.error;
+    }
+    get stdout() {
+        return this.#result.stdout;
+    }
+    get stderr() {
+        return this.#result.stderr;
+    }
+}
+/** Turns a Runtime SDK error into the E2B error a caller written for E2B
+ * expects. Anything that is not a Runtime error passes through unchanged. */
+export function translate(error, subject = "other") {
+    if (!(error instanceof RuntimeError))
+        return error;
+    const message = [
+        error.message,
+        error.hint ? `Hint: ${error.hint}` : "",
+        error.requestId ? `Request: ${error.requestId}` : "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+    let out;
+    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);
+    else if (error.status === 401 || error.status === 403)
+        out = new AuthenticationError(message);
+    else if (error.code === "file_not_found" || (error.status === 404 && subject === "file"))
+        out = new FileNotFoundError(message);
+    else if (error.status === 404 && subject === "sandbox")
+        out = new SandboxNotFoundError(message);
+    else if (error.status === 404)
+        out = new NotFoundError(message);
+    else if (error.status === 429)
+        out = new RateLimitError(message);
+    else if (/space|disk_full|no_room/.test(error.code))
+        out = new NotEnoughSpaceError(message);
+    else if (error.status === 400 || error.status === 413 || error.status === 422)
+        out = new InvalidArgumentError(message);
+    else if (error.status === 503)
+        out = new ServiceBusyError(message);
+    else if (error.code === "command_timeout")
+        out = new TimeoutError(message);
+    else
+        out = new SandboxError(message);
+    if (out instanceof SandboxError && error.status)
+        out.statusCode = error.status;
+    attach(out, {
+        code: error.code,
+        ...(error.hint ? { hint: error.hint } : {}),
+        ...(error.requestId ? { requestId: error.requestId } : {}),
+        cause: error,
+    });
+    return out;
+}
+/** Runs `work`, turning any Runtime error into its E2B counterpart. */
+export async function guard(subject, work) {
+    try {
+        return await work();
+    }
+    catch (error) {
+        throw translate(error, subject);
+    }
+}

package/dist/e2b/filesystem.d.ts

@@ -0,0 +1,82 @@
+import type { SandboxContext, Username } from "./commands.js";
+export declare enum FileType {
+    FILE = "file",
+    DIR = "dir",
+    SYMLINK = "symlink"
+}
+export interface WriteInfo {
+    name: string;
+    type?: FileType;
+    path: string;
+    metadata?: Record<string, string>;
+}
+export interface EntryInfo extends WriteInfo {
+    size: number;
+    mode: number;
+    permissions: string;
+    /** Runtime's listing does not say who owns a file: always "". */
+    owner: string;
+    /** Runtime's listing does not say a file's group: always "". */
+    group: string;
+    modifiedTime?: Date;
+    symlinkTarget?: string;
+}
+export type WriteEntry = {
+    path: string;
+    data: string | ArrayBuffer | Blob | ReadableStream;
+};
+export interface FilesystemRequestOpts {
+    requestTimeoutMs?: number;
+    signal?: AbortSignal;
+    /** Only the default user; see CommandStartOpts.user. */
+    user?: Username;
+}
+export interface FilesystemReadOpts extends FilesystemRequestOpts {
+    /** Accepted; Runtime's transfer is already compressed where it helps. */
+    gzip?: boolean;
+    streamIdleTimeoutMs?: number;
+}
+export interface FilesystemWriteOpts extends FilesystemRequestOpts {
+    /** Accepted; Runtime chooses the transfer. */
+    gzip?: boolean;
+    useOctetStream?: boolean;
+    /** Refused: Runtime does not keep metadata on files. */
+    metadata?: Record<string, string>;
+}
+export interface FilesystemListOpts extends FilesystemRequestOpts {
+    depth?: number;
+}
+/** `sandbox.files`: E2B's filesystem module over Runtime's files API. Relative
+ * paths resolve against the home directory, as in E2B (Runtime's is
+ * /workspace). */
+export declare class Filesystem {
+    #private;
+    constructor(ctx: SandboxContext);
+    read(path: string, opts?: FilesystemReadOpts & {
+        format?: "text";
+    }): Promise<string>;
+    read(path: string, opts: FilesystemReadOpts & {
+        format: "bytes";
+    }): Promise<Uint8Array>;
+    read(path: string, opts: FilesystemReadOpts & {
+        format: "blob";
+    }): Promise<Blob>;
+    read(path: string, opts: FilesystemReadOpts & {
+        format: "stream";
+    }): Promise<ReadableStream<Uint8Array>>;
+    /** Writes a file, making its directories, and overwrites one that exists. */
+    write(path: string, data: string | ArrayBuffer | Blob | ReadableStream, opts?: FilesystemWriteOpts): Promise<WriteInfo>;
+    write(files: WriteEntry[], opts?: FilesystemWriteOpts): Promise<WriteInfo[]>;
+    writeFiles(files: WriteEntry[], opts?: FilesystemWriteOpts): Promise<WriteInfo[]>;
+    /** A directory's entries, hidden ones included; `depth` goes deeper. */
+    list(path: string, opts?: FilesystemListOpts): Promise<EntryInfo[]>;
+    /** Makes a directory and its parents. False when it already existed. */
+    makeDir(path: string, opts?: FilesystemRequestOpts): Promise<boolean>;
+    /** Moves a file or directory, replacing a file at the new path, as E2B does. */
+    rename(oldPath: string, newPath: string, opts?: FilesystemRequestOpts): Promise<EntryInfo>;
+    /** Removes a file, or a directory with everything in it. */
+    remove(path: string, opts?: FilesystemRequestOpts): Promise<void>;
+    exists(path: string, opts?: FilesystemRequestOpts): Promise<boolean>;
+    getInfo(path: string, opts?: FilesystemRequestOpts): Promise<EntryInfo>;
+    watchDir(): Promise<never>;
+}

package/dist/e2b/filesystem.js

@@ -0,0 +1,143 @@
+import { request } from "./client.js";
+import { FileNotFoundError, guard, NotSupportedError } from "./errors.js";
+export var FileType;
+(function (FileType) {
+    FileType["FILE"] = "file";
+    FileType["DIR"] = "dir";
+    FileType["SYMLINK"] = "symlink";
+})(FileType || (FileType = {}));
+/** Runtime's home, where E2B's relative paths land. */
+const HOME = "/workspace";
+function absolute(path) {
+    return path.startsWith("/") ? path : `${HOME}/${path.replace(/^\.\//, "")}`;
+}
+function refuse(opts) {
+    if (opts.user !== undefined && opts.user !== "user")
+        throw new NotSupportedError(`File access as the user "${opts.user}"`, "Runtime's file calls act as the sandbox owner; use commands.run('sudo ...') for root-owned paths.");
+    if (opts.metadata && Object.keys(opts.metadata).length)
+        throw new NotSupportedError("File metadata (user.e2b.* extended attributes)", "Keep the metadata beside the file, for example in a JSON file.");
+}
+const PERMISSIONS = ["---", "--x", "-w-", "-wx", "r--", "r-x", "rw-", "rwx"];
+function entryInfo(entry) {
+    const mode = parseInt(entry.mode, 8) || 0;
+    const bits = mode & 0o777;
+    return {
+        name: entry.name,
+        path: entry.path,
+        ...(entry.type === "file"
+            ? { type: FileType.FILE }
+            : entry.type === "directory"
+                ? { type: FileType.DIR }
+                : entry.type === "symlink"
+                    ? { type: FileType.SYMLINK }
+                    : {}),
+        size: entry.size,
+        mode,
+        permissions: PERMISSIONS[(bits >> 6) & 7] + PERMISSIONS[(bits >> 3) & 7] + PERMISSIONS[bits & 7],
+        owner: "",
+        group: "",
+        modifiedTime: new Date(entry.modifiedAt),
+    };
+}
+async function bytesOf(data) {
+    if (typeof data === "string")
+        return new TextEncoder().encode(data);
+    if (data instanceof ArrayBuffer)
+        return new Uint8Array(data);
+    if (ArrayBuffer.isView(data)) {
+        const view = data;
+        return new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+    }
+    if (typeof Blob !== "undefined" && data instanceof Blob)
+        return new Uint8Array(await data.arrayBuffer());
+    return new Uint8Array(await new Response(data).arrayBuffer());
+}
+const basename = (path) => path.split("/").filter(Boolean).pop() ?? path;
+/** `sandbox.files`: E2B's filesystem module over Runtime's files API. Relative
+ * paths resolve against the home directory, as in E2B (Runtime's is
+ * /workspace). */
+export class Filesystem {
+    #ctx;
+    constructor(ctx) {
+        this.#ctx = ctx;
+    }
+    get #files() {
+        return this.#ctx.runtime.files;
+    }
+    async #path(path, opts) {
+        refuse(opts);
+        await this.#ctx.ensureHome(path);
+        return absolute(path);
+    }
+    async read(path, opts = {}) {
+        const file = await this.#path(path, opts);
+        const bytes = await guard("file", () => this.#files.read(file, request(opts)));
+        switch (opts.format) {
+            case "bytes":
+                return bytes;
+            case "blob":
+                return new Blob([bytes]);
+            case "stream":
+                return new Blob([bytes]).stream();
+            default:
+                return new TextDecoder().decode(bytes);
+        }
+    }
+    async write(pathOrFiles, dataOrOpts, maybeOpts) {
+        if (Array.isArray(pathOrFiles))
+            return this.writeFiles(pathOrFiles, (dataOrOpts ?? {}));
+        return this.#writeOne(pathOrFiles, dataOrOpts, maybeOpts ?? {});
+    }
+    async writeFiles(files, opts = {}) {
+        const written = [];
+        for (const file of files)
+            written.push(await this.#writeOne(file.path, file.data, opts));
+        return written;
+    }
+    async #writeOne(path, data, opts) {
+        const file = await this.#path(path, opts);
+        const bytes = await bytesOf(data);
+        await guard("file", () => this.#files.write(file, bytes, request(opts)));
+        return { name: basename(file), type: FileType.FILE, path: file };
+    }
+    /** A directory's entries, hidden ones included; `depth` goes deeper. */
+    async list(path, opts = {}) {
+        const dir = await this.#path(path, opts);
+        const entries = await guard("file", () => this.#files.list(dir, { depth: opts.depth ?? 1, hidden: true }));
+        return entries.map(entryInfo);
+    }
+    /** Makes a directory and its parents. False when it already existed. */
+    async makeDir(path, opts = {}) {
+        const dir = await this.#path(path, opts);
+        if (await guard("file", () => this.#files.exists(dir)))
+            return false;
+        await guard("file", () => this.#files.mkdir(dir, { parents: true }));
+        return true;
+    }
+    /** Moves a file or directory, replacing a file at the new path, as E2B does. */
+    async rename(oldPath, newPath, opts = {}) {
+        const from = await this.#path(oldPath, opts);
+        const to = await this.#path(newPath, opts);
+        await guard("file", () => this.#files.rename(from, to, { overwrite: true }));
+        return this.getInfo(to, opts);
+    }
+    /** Removes a file, or a directory with everything in it. */
+    async remove(path, opts = {}) {
+        const target = await this.#path(path, opts);
+        await guard("file", () => this.#files.remove(target, { recursive: true }));
+    }
+    async exists(path, opts = {}) {
+        const target = await this.#path(path, opts);
+        return guard("file", () => this.#files.exists(target));
+    }
+    async getInfo(path, opts = {}) {
+        const target = await this.#path(path, opts);
+        const stat = await guard("file", () => this.#files.stat(target));
+        if (!stat.exists)
+            throw new FileNotFoundError(`${target} does not exist.`);
+        return entryInfo(stat);
+    }
+    watchDir() {
+        return Promise.reject(new NotSupportedError("Watching a directory (files.watchDir)", "Poll with files.list(path), or run your own watcher with commands.run(..., { background: true })."));
+    }
+}

package/dist/e2b/index.d.ts

@@ -0,0 +1,28 @@
+/** Code written for E2B's SDK, on Runtime Cloud. Change the import:
+ *
+ *   import { Sandbox } from "withruntime/e2b"; // was: from "e2b"
+ *
+ * and set RUNTIME_API_KEY (or put a Runtime key in E2B_API_KEY). What Runtime
+ * cannot do the way E2B does throws NotSupportedError, naming what to use. */
+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 { 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, } from "./filesystem.js";
+export { SandboxError, TimeoutError, InvalidArgumentError, NotEnoughSpaceError, NotFoundError, FileNotFoundError, SandboxNotFoundError, TemplateError, RateLimitError, AuthenticationError, ServiceBusyError, CommandExitError, NotSupportedError, type CommandResult, } from "./errors.js";
+export type { ConnectionOpts, RuntimeOpts } from "./client.js";
+export { Template, TemplateBase, Volume, Secret, waitForPort, waitForURL, waitForProcess, waitForFile, waitForTimeout, } from "./unsupported.js";
+export default Sandbox;
+/** E2B's client with bound options: `new E2B({ apiKey }).Sandbox.create()`. */
+export declare class E2B {
+    readonly Sandbox: typeof Sandbox;
+    constructor(opts?: Omit<ConnectionOpts, "signal"> & {
+        client?: Runtime;
+    });
+}
+/** A subclass whose static calls use `opts`'s key or client unless a call
+ * names its own. */
+export declare function bind<S extends typeof Sandbox>(Base: S, opts: Omit<ConnectionOpts, "signal"> & {
+    client?: Runtime;
+}): S;

package/dist/e2b/index.js

@@ -0,0 +1,61 @@
+import { clientFor } from "./client.js";
+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, } from "./filesystem.js";
+export { SandboxError, TimeoutError, InvalidArgumentError, NotEnoughSpaceError, NotFoundError, FileNotFoundError, SandboxNotFoundError, TemplateError, RateLimitError, AuthenticationError, ServiceBusyError, CommandExitError, NotSupportedError, } from "./errors.js";
+export { Template, TemplateBase, Volume, Secret, waitForPort, waitForURL, waitForProcess, waitForFile, waitForTimeout, } from "./unsupported.js";
+export default Sandbox;
+/** E2B's client with bound options: `new E2B({ apiKey }).Sandbox.create()`. */
+export class E2B {
+    Sandbox;
+    constructor(opts = {}) {
+        this.Sandbox = bind(Sandbox, opts);
+    }
+}
+/** A subclass whose static calls use `opts`'s key or client unless a call
+ * names its own. */
+export function bind(Base, opts) {
+    const client = clientFor({
+        ...opts,
+        ...(opts.client ? { runtime: { client: opts.client } } : {}),
+    });
+    const withClient = (given) => ({
+        ...given,
+        runtime: { ...given?.runtime, client: given?.runtime?.client ?? client },
+    });
+    const Bound = class extends Base {
+    };
+    const create = Reflect.get(Base, "create");
+    const statics = {
+        create(first, second) {
+            return typeof first === "string"
+                ? create.call(this, first, withClient(second))
+                : create.call(this, withClient(first));
+        },
+    };
+    // The calls that take (id, opts) or (id, x, opts): the options come last.
+    for (const name of [
+        "connect",
+        "list",
+        "kill",
+        "getInfo",
+        "setTimeout",
+        "pause",
+        "betaPause",
+        "fork",
+        "createSnapshot",
+        "deleteSnapshot",
+    ]) {
+        const original = Reflect.get(Base, name);
+        const arity = name === "list" ? 1 : name === "setTimeout" ? 3 : 2;
+        statics[name] = function (...args) {
+            const padded = [...args];
+            padded[arity - 1] = withClient(padded[arity - 1]);
+            return original.apply(this, padded);
+        };
+    }
+    for (const [name, value] of Object.entries(statics))
+        Object.defineProperty(Bound, name, { value, writable: true, configurable: true });
+    return Bound;
+}

package/dist/e2b/sandbox.d.ts

@@ -0,0 +1,183 @@
+import type { Runtime } from "../client.js";
+import { type ConnectionOpts, type RuntimeOpts, type RuntimeSandbox } from "./client.js";
+import { Commands } from "./commands.js";
+import { Filesystem } from "./filesystem.js";
+/** E2B's default machine: 2 vCPU and 512 MiB (docs.e2b.dev/billing, checked
+ * 23 September 2026). Pass `runtime: { create: { memoryMiB } }` for another. */
+export declare const DEFAULT_SHAPE: {
+    readonly vcpu: 2;
+    readonly memoryMiB: 512;
+};
+/** E2B's default sandbox timeout, 300 s. */
+export declare const DEFAULT_TIMEOUT_MS = 300000;
+export type SandboxState = "running" | "paused";
+export type SandboxOnTimeout = "pause" | "kill" | {
+    action: "pause" | "kill";
+    keepMemory?: boolean;
+};
+export type SandboxLifecycle = {
+    onTimeout: SandboxOnTimeout;
+    autoResume?: boolean;
+};
+export interface SandboxOpts extends ConnectionOpts {
+    /** An E2B template name. "base" (the default) is Runtime's stock image; any
+     * other name must be a ready Runtime image of that name, and a UUID a
+     * Runtime image or snapshot id. */
+    template?: string;
+    /** Stored as the sandbox's labels (at most 32, values up to 256 characters). */
+    metadata?: Record<string, string>;
+    /** Given to every command and code run through this object. */
+    envs?: Record<string, string>;
+    /** Default 300 000. Runtime's leases run 60 s to 1 hour; shorter rounds up
+     * to 60 s (with a warning), longer is refused. */
+    timeoutMs?: number;
+    /** Accepted and ignored, as E2B ignores it. */
+    secure?: boolean;
+    /** false: no network at all. */
+    allowInternetAccess?: boolean;
+    /** What happens when the timeout ends: "kill" (E2B's default, Runtime stops
+     * the sandbox) or "pause". */
+    lifecycle?: SandboxLifecycle;
+    mcp?: unknown;
+    network?: unknown;
+    iam?: unknown;
+    volumeMounts?: unknown;
+    /** Runtime-only: an explicit client, or fields for the create. */
+    runtime?: RuntimeOpts;
+}
+export type SandboxConnectOpts = ConnectionOpts & {
+    timeoutMs?: number;
+    onResume?: "restore" | "reboot";
+    runtime?: RuntimeOpts;
+};
+export type SandboxApiOpts = Pick<ConnectionOpts, "apiKey" | "requestTimeoutMs" | "signal"> & {
+    runtime?: RuntimeOpts;
+};
+export interface SandboxInfo {
+    sandboxId: string;
+    /** "base" for Runtime's stock image, else the image or snapshot id. */
+    templateId: string;
+    name?: string;
+    metadata: Record<string, string>;
+    startedAt: Date;
+    endAt: Date;
+    state: SandboxState;
+    cpuCount: number;
+    memoryMB: number;
+    /** Runtime has no envd: "runtime". */
+    envdVersion: string;
+    lifecycle?: {
+        onTimeout: "pause" | "kill";
+        autoResume: boolean;
+    };
+}
+export interface SnapshotInfo {
+    snapshotId: string;
+    names: string[];
+}
+export type SandboxListOpts = SandboxApiOpts & {
+    query?: {
+        metadata?: Record<string, string>;
+        state?: SandboxState[];
+        startedAfter?: Date;
+        template?: string;
+    };
+    order?: "asc" | "desc";
+    limit?: number;
+    nextToken?: string;
+};
+/** A sandbox, with E2B's methods. `sandbox.runtime` is the Runtime sandbox
+ * underneath, for anything E2B has no name for. */
+export declare class Sandbox {
+    #private;
+    protected static readonly defaultTemplate: string;
+    readonly files: Filesystem;
+    readonly commands: Commands;
+    /** Use Sandbox.create or Sandbox.connect. */
+    constructor(runtime: RuntimeSandbox, client: Runtime, envs?: Record<string, string>);
+    get sandboxId(): string;
+    /** The Runtime sandbox underneath: previews, network, desktop, interpreter,
+     * processes, terminal and the rest of Runtime's SDK. */
+    get runtime(): RuntimeSandbox;
+    protected get client(): Runtime;
+    protected get envs(): Record<string, string>;
+    /** 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 free trial while the account has trial
+     * time, 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
+     * `timeoutMs` moves a running sandbox's end later, never earlier. */
+    static connect<S extends typeof Sandbox>(this: S, sandboxId: string, opts?: SandboxConnectOpts): Promise<InstanceType<S>>;
+    /** Wakes this sandbox if it is paused. */
+    connect(opts?: SandboxConnectOpts): Promise<this>;
+    /** Running and paused sandboxes, a page at a time, as E2B's paginator. */
+    static list(opts?: SandboxListOpts): SandboxPaginator;
+    /** Stops the sandbox. False when it was not found or had already ended. */
+    static kill(sandboxId: string, opts?: SandboxApiOpts): Promise<boolean>;
+    kill(opts?: Pick<ConnectionOpts, "requestTimeoutMs" | "signal">): Promise<boolean>;
+    /** Sets the sandbox to end `timeoutMs` from now. Runtime leases only move
+     * later: a shorter timeout than the one it has is refused. */
+    static setTimeout(sandboxId: string, timeoutMs: number, opts?: SandboxApiOpts): Promise<void>;
+    setTimeout(timeoutMs: number, opts?: Pick<ConnectionOpts, "requestTimeoutMs" | "signal">): Promise<void>;
+    static getInfo(sandboxId: string, opts?: SandboxApiOpts): Promise<SandboxInfo>;
+    getInfo(opts?: Pick<ConnectionOpts, "requestTimeoutMs" | "signal">): Promise<SandboxInfo>;
+    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>;
+    /** 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 & {
+        count?: number;
+        timeoutMs?: number;
+    }): Promise<Array<InstanceType<S> | Error>>;
+    fork(opts?: SandboxApiOpts & {
+        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>;
+    static deleteSnapshot(snapshotId: string, opts?: SandboxApiOpts): Promise<boolean>;
+    /** Refused: E2B answers getHost without a call, and a Runtime port becomes
+     * reachable only once it is shared. Use getPublicHost. */
+    getHost(port: number): string;
+    /** Shares `port` at a public HTTPS address (a Runtime preview) and returns
+     * its host, `<port>-<id>.<domain>`, like E2B's getHost. Anyone with the
+     * address can reach it; a browser sees a one-time page naming Runtime. */
+    getPublicHost(port: number): Promise<string>;
+    get pty(): never;
+    get git(): never;
+    getMetrics(): Promise<never>;
+    static getMetrics(): Promise<never>;
+    updateNetwork(): Promise<never>;
+    uploadUrl(): Promise<never>;
+    downloadUrl(): Promise<never>;
+    getMcpUrl(): never;
+    getMcpToken(): Promise<never>;
+}
+/** E2B's paginator: `while (p.hasNext) items.push(...(await p.nextItems()))`. */
+export declare class SandboxPaginator {
+    #private;
+    constructor(client: Runtime, opts: SandboxListOpts);
+    get hasNext(): boolean;
+    get nextToken(): string | undefined;
+    nextItems(): Promise<SandboxInfo[]>;
+}