withruntime 0.4.0 → 0.5.0

package/dist/vercel/sandbox.d.ts

@@ -0,0 +1,317 @@
+import type { Writable } from "node:stream";
+import type { Runtime } from "../client.js";
+import { type Credentials, type RuntimeCreate, type RuntimeSandbox, type WithRuntime } from "./client.js";
+import { Command, CommandFinished } from "./command.js";
+import { FileSystem } from "./filesystem.js";
+import { Snapshot } from "./snapshot.js";
+/** Vercel's default machine: 2 vCPUs with 2048 MB each (checked 23 September
+ * 2026). Runtime gives 2 vCPU and 4096 MiB. */
+export declare const DEFAULT_VCPUS = 2;
+export declare const MEMORY_MIB_PER_VCPU = 2048;
+/** Vercel's default timeout, 5 minutes. */
+export declare const DEFAULT_TIMEOUT_MS = 300000;
+/** Vercel's working directory; `/workspace` on Runtime. */
+export declare const HOME = "/vercel/sandbox";
+export type NetworkPolicy = "allow-all" | "deny-all" | {
+    allow?: string[] | Record<string, unknown[]>;
+    subnets?: {
+        allow?: string[];
+        deny?: string[];
+    };
+};
+type Source = {
+    type: "git";
+    url: string;
+    depth?: number;
+    revision?: string;
+    username?: string;
+    password?: string;
+} | {
+    type: "tarball";
+    url: string;
+} | {
+    type: "snapshot";
+    snapshotId: string;
+};
+export interface CreateSandboxParams extends Credentials {
+    name?: string;
+    source?: Source;
+    /** Shared at public HTTPS addresses (Runtime previews); `domain(port)`
+     * answers from them. */
+    ports?: number[];
+    /** Milliseconds. Default 300 000; 60 s to 1 hour on Runtime. */
+    timeout?: number;
+    resources?: {
+        vcpus: number;
+    };
+    networkPolicy?: NetworkPolicy;
+    networkId?: string;
+    /** Given to every command run through this object. */
+    env?: Record<string, string>;
+    /** Stored as Runtime labels. */
+    tags?: Record<string, string>;
+    region?: string;
+    failoverRegions?: string[];
+    mounts?: Record<string, unknown>;
+    signal?: AbortSignal;
+    /** Default true: `stop()` pauses the sandbox, keeping its files (and its
+     * memory), and `Sandbox.get({ name })` wakes it. false: `stop()` ends it. */
+    persistent?: boolean;
+    /** Milliseconds a stopped persistent sandbox is kept, as Runtime's
+     * retention (whole days, 1 to 365; 0 is 365). */
+    snapshotExpiration?: number;
+    /** Accepted: a paused Runtime sandbox keeps exactly its latest state. */
+    keepLastSnapshots?: {
+        count: number;
+        expiration?: number;
+        deleteEvicted?: boolean;
+    };
+    onResume?: (sandbox: Sandbox) => Promise<void>;
+    /** A legacy Vercel runtime (node22, node24, node26, python3.13): Runtime's
+     * stock image, which has Node.js 24 and Python 3.12. */
+    runtime?: string;
+    /** A Vercel managed image (Runtime's stock image) or the name of a ready
+     * Runtime image. */
+    image?: string;
+    /** Runtime-only: an explicit client, or fields for the create. */
+    withruntime?: WithRuntime;
+}
+export interface RunCommandParams {
+    cmd: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    /** Runs the command under `sudo`, which needs no password. */
+    sudo?: boolean;
+    detached?: boolean;
+    stdout?: Writable;
+    stderr?: Writable;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+export interface SandboxRoute {
+    port: number;
+    subdomain: string;
+    url: string;
+}
+/** Vercel's network policy as Runtime's rules. Header injection and
+ * forwarding rules have no Runtime counterpart and are refused. */
+export declare function networkRules(policy: NetworkPolicy): NonNullable<RuntimeCreate["network"]>;
+/** Runtime's `/workspace` stands for Vercel's `/vercel/sandbox`: relative
+ * paths resolve against it, and paths under /vercel/sandbox are rewritten. */
+export declare function toRuntimePath(path: string, cwd?: string): string;
+type Resolved = {
+    runtime: RuntimeSandbox;
+    client: Runtime;
+    params: CreateSandboxParams;
+};
+/** A sandbox with Vercel's methods. `sandbox.withruntime` is the Runtime
+ * sandbox underneath, for anything Vercel has no name for. */
+export declare class Sandbox {
+    #private;
+    readonly fs: FileSystem;
+    /** Use Sandbox.create, Sandbox.get or Sandbox.getOrCreate. */
+    constructor(resolved: Resolved);
+    /** The Runtime sandbox underneath: previews, network, snapshots, desktop,
+     * interpreter, processes and the rest of Runtime's SDK. */
+    get withruntime(): RuntimeSandbox;
+    /** The sandbox's name, or its Runtime id when it was made without one. */
+    get name(): string;
+    get routes(): SandboxRoute[];
+    get persistent(): boolean;
+    get region(): string;
+    get failoverRegions(): string[];
+    get networkId(): string | undefined;
+    get vcpus(): number;
+    /** Megabytes. */
+    get memory(): number;
+    get runtime(): string | undefined;
+    get image(): string | undefined;
+    get createdAt(): Date;
+    get updatedAt(): Date;
+    get cwd(): string;
+    get status(): "pending" | "running" | "stopping" | "stopped";
+    /** Milliseconds. */
+    get timeout(): number;
+    get expiresAt(): Date;
+    get tags(): Record<string, string>;
+    get sourceSnapshotId(): string | undefined;
+    /** Creates a sandbox and waits until it runs. Vercel's defaults: 2 vCPUs,
+     * 2048 MiB per vCPU, a 5-minute timeout, persistent. 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(params?: CreateSandboxParams): Promise<Sandbox & AsyncDisposable>;
+    /** A sandbox by name (or Runtime id), woken if it is paused unless
+     * `resume: false`. */
+    static get(params: {
+        name: string;
+        resume?: boolean;
+        signal?: AbortSignal;
+        onResume?: (sandbox: Sandbox) => Promise<void>;
+    } & Credentials & {
+        withruntime?: WithRuntime;
+    }): Promise<Sandbox>;
+    /** The named sandbox, or a new one with that name when there is none. */
+    static getOrCreate(params?: CreateSandboxParams & {
+        resume?: boolean;
+        onCreate?: (sandbox: Sandbox) => Promise<void>;
+    }): Promise<Sandbox>;
+    /** A new sandbox copied from a running one, memory and all (a Runtime
+     * fork). `sourceSandbox` is its name. */
+    static fork(params: Omit<CreateSandboxParams, "source"> & {
+        sourceSandbox: string;
+    }): Promise<Sandbox & AsyncDisposable>;
+    /** Running and stopped (paused) sandboxes, oldest first, with Vercel's
+     * paginator: `for await (const s of await Sandbox.list())`. */
+    static list(params?: {
+        tags?: Record<string, string>;
+        limit?: number;
+        signal?: AbortSignal;
+    } & Credentials & {
+        withruntime?: WithRuntime;
+    } & Record<string, unknown>): Promise<{
+        sandboxes: ListItem[];
+        pagination: {
+            count: number;
+            next: string | null;
+        };
+    } & {
+        pages(): AsyncGenerator<{
+            sandboxes: ListItem[];
+            pagination: {
+                count: number;
+                next: string | null;
+            };
+        }, void, unknown>;
+        [Symbol.asyncIterator](): AsyncGenerator<ListItem, void, unknown>;
+        toArray(): Promise<ListItem[]>;
+    }>;
+    /** Runs a command. It waits and resolves with a CommandFinished (a
+     * non-zero exit is not an error), or with `detached: true` resolves at once
+     * with a Command. */
+    runCommand(command: string, args?: string[], opts?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<CommandFinished>;
+    runCommand(params: RunCommandParams & {
+        detached: true;
+    }): Promise<Command>;
+    runCommand(params: RunCommandParams): Promise<CommandFinished>;
+    /** A command started earlier, by its cmdId. */
+    getCommand(cmdId: string, _opts?: {
+        signal?: AbortSignal;
+    }): Promise<Command>;
+    mkDir(path: string, _opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** The file's bytes as a Node stream, or null when there is no file. */
+    readFile(file: {
+        path: string;
+        cwd?: string;
+    }, opts?: {
+        signal?: AbortSignal;
+    }): Promise<NodeJS.ReadableStream | null>;
+    /** The file as a Buffer, or null when there is no file. */
+    readFileToBuffer(file: {
+        path: string;
+        cwd?: string;
+    }, opts?: {
+        signal?: AbortSignal;
+    }): Promise<Buffer | null>;
+    /** Copies a sandbox file to the local disk; null when there is no file. */
+    downloadFile(src: {
+        path: string;
+        cwd?: string;
+    }, dst: {
+        path: string;
+        cwd?: string;
+    }, opts?: {
+        mkdirRecursive?: boolean;
+        signal?: AbortSignal;
+    }): Promise<string | null>;
+    /** Writes files, making their directories. Relative paths land in the
+     * working directory; `mode` sets permissions. */
+    writeFiles(files: {
+        path: string;
+        content: string | Uint8Array;
+        mode?: number;
+    }[], _opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** The public address of a port listed in `ports`, such as
+     * `https://3000-<id>.runtimehost.com`. A browser sees a one-time page
+     * naming Runtime before the site. */
+    domain(port: number): string;
+    /** Ends the session. A persistent sandbox is paused, keeping its files and
+     * memory, and wakes on the next call or Sandbox.get; any other ends. */
+    stop(opts?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        name: string;
+        status: string;
+    }>;
+    /** Ends the sandbox for good. */
+    delete(opts?: {
+        deleteOrphanSnapshots?: boolean;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+    /** Moves the end `duration` milliseconds later (at most an hour ahead of
+     * now on Runtime). */
+    extendTimeout(duration: number, opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** Replaces the network rules; returns the policy given. */
+    updateNetworkPolicy(networkPolicy: NetworkPolicy, _opts?: {
+        signal?: AbortSignal;
+    }): Promise<NetworkPolicy>;
+    /** Changes what Runtime can change on a sandbox: `timeout`, `ports`,
+     * `networkPolicy` and `snapshotExpiration`. Anything else is refused before
+     * anything changes. */
+    update(params: {
+        timeout?: number;
+        ports?: number[];
+        networkPolicy?: NetworkPolicy;
+        snapshotExpiration?: number;
+    } & Record<string, unknown>, _opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** Keeps the sandbox's whole machine as a Runtime snapshot (files, memory
+     * and running processes), then stops the sandbox, as Vercel does. Start
+     * from it with `Sandbox.create({ source: { type: "snapshot", snapshotId } })`. */
+    snapshot(opts?: {
+        expiration?: number;
+        signal?: AbortSignal;
+    }): Promise<Snapshot>;
+    openInteractive(): Promise<never>;
+    getDefaultUser(): Promise<{
+        username: string;
+        group: string;
+    }>;
+    createUser(): Promise<never>;
+    asUser(): never;
+    createGroup(): Promise<never>;
+    addUserToGroup(): Promise<never>;
+    removeUserFromGroup(): Promise<never>;
+    currentSession(): never;
+    listSessions(): Promise<never>;
+    listSnapshots(): Promise<never>;
+}
+/** Milliseconds as whole days for Runtime's retention: 1 to 365, and 0 (no
+ * expiration) as 365. */
+export declare function retentionDays(ms: number): number;
+type ListItem = {
+    name: string;
+    persistent: boolean;
+    createdAt: number;
+    updatedAt: number;
+    currentSessionId: string;
+    status: "pending" | "running" | "stopping" | "stopped";
+    region: string;
+    vcpus: number;
+    memory: number;
+    timeout: number;
+    expiresAt: number;
+    tags: Record<string, string>;
+};
+export {};