withruntime 0.2.1 → 0.3.0

package/dist/products/interpreter.d.ts

@@ -0,0 +1,88 @@
+import type { Sandbox } from "../sandbox.js";
+import type { RequestOptions, Transport } from "../transport.js";
+export type InterpreterLanguage = "python" | "javascript";
+export type ResultRef = {
+    path: string;
+    bytes: number;
+    sha256: string;
+};
+/** One rich result: a MIME bundle (text/plain, text/html, image/png as base64,
+ * application/json, application/vnd.runtime.table+json for a DataFrame). */
+export type ExecutionResult = {
+    main: boolean;
+    data: Record<string, unknown>;
+    refs: Record<string, ResultRef>;
+};
+export type Execution = {
+    id: string;
+    contextId: string;
+    language: InterpreterLanguage;
+    executionCount: number | null;
+    status: "ok" | "error" | "interrupted" | "timeout" | "lost";
+    stdout: string;
+    stderr: string;
+    results: ExecutionResult[];
+    error: {
+        name: string;
+        value: string;
+        traceback: string;
+    } | null;
+    overflow: {
+        stream: "stdout" | "stderr";
+        path: string | null;
+        bytes: number;
+        dropped: number;
+    }[];
+    durationMs: number;
+    contextStarted: boolean;
+    lostBytes: number;
+};
+export type InterpreterContext = {
+    id: string;
+    language: InterpreterLanguage;
+    processId: string;
+    cwd: string;
+    state: string;
+    startedAt: number;
+};
+export type RunOptions = RequestOptions & {
+    language?: InterpreterLanguage;
+    /** A context id; "python" and "javascript" are the defaults, started on first use. */
+    context?: string;
+    timeoutMs?: number;
+    onStdout?: (text: string) => void;
+    onStderr?: (text: string) => void;
+    onResult?: (result: ExecutionResult) => void;
+    onError?: (error: {
+        name: string;
+        value: string;
+        traceback: string;
+    }) => void;
+};
+/** A stateful Python and JavaScript interpreter in the sandbox:
+ * `await sbx.interpreter.run("import pandas as pd; pd.DataFrame({'a': [1]})")`.
+ * Variables persist between runs of the same context, like a notebook. */
+export declare function sandboxInterpreter(t: Transport, sandbox: Sandbox): {
+    /** Run a cell. With any of the on* callbacks, output streams as it happens. */
+    run(code: string, options?: RunOptions): Promise<Execution>;
+    contexts: {
+        list: (options?: RequestOptions) => Promise<InterpreterContext[]>;
+        create: (input?: {
+            id?: string;
+            language?: InterpreterLanguage;
+            cwd?: string;
+            env?: Record<string, string>;
+        }, options?: RequestOptions) => Promise<InterpreterContext>;
+        restart: (id: string, options?: RequestOptions) => Promise<InterpreterContext>;
+        interrupt: (id: string, options?: RequestOptions) => Promise<{
+            interrupted: boolean;
+        }>;
+        remove: (id: string, options?: RequestOptions) => Promise<{
+            deleted: boolean;
+        }>;
+    };
+    /** The bytes of a result too large to travel inline (a `refs` entry). */
+    result(ref: ResultRef | {
+        path: string;
+    }, options?: RequestOptions): Promise<Uint8Array>;
+};

package/dist/products/interpreter.js

@@ -0,0 +1,81 @@
+/** A stateful Python and JavaScript interpreter in the sandbox:
+ * `await sbx.interpreter.run("import pandas as pd; pd.DataFrame({'a': [1]})")`.
+ * Variables persist between runs of the same context, like a notebook. */
+export function sandboxInterpreter(t, sandbox) {
+    const base = () => `/v1/sandboxes/${encodeURIComponent(sandbox.id)}/interpreter`;
+    return {
+        /** Run a cell. With any of the on* callbacks, output streams as it happens. */
+        async run(code, options = {}) {
+            const { language, context, timeoutMs, onStdout, onStderr, onResult, onError, ...request } = options;
+            const body = {
+                code,
+                ...(language ? { language } : {}),
+                ...(context ? { context } : {}),
+                ...(timeoutMs ? { timeoutMs } : {}),
+            };
+            if (!onStdout && !onStderr && !onResult && !onError)
+                return t.json({ method: "POST", path: `${base()}:run`, body, ...request });
+            for await (const event of t.events({
+                method: "POST",
+                path: `${base()}:run`,
+                body: { ...body, stream: true },
+                ...request,
+            })) {
+                if (event.k === "stdout")
+                    onStdout?.(event.text);
+                else if (event.k === "stderr")
+                    onStderr?.(event.text);
+                else if (event.k === "result")
+                    onResult?.({ main: event.main, data: event.data, refs: event.refs });
+                else if (event.k === "error")
+                    onError?.(event);
+                else if (event.k === "execution")
+                    return event.execution;
+                else if (event.k === "failure")
+                    throw new Error(`${event.code}: ${event.message}`);
+            }
+            throw new Error("The interpreter stream ended without a result");
+        },
+        contexts: {
+            list: async (options) => (await t.json({
+                method: "GET",
+                path: `${base()}/contexts`,
+                ...options,
+            })).data,
+            create: (input = {}, options) => t.json({
+                method: "POST",
+                path: `${base()}/contexts`,
+                body: input,
+                ...options,
+            }),
+            restart: (id, options) => t.json({
+                method: "POST",
+                path: `${base()}/contexts/${encodeURIComponent(id)}:restart`,
+                body: {},
+                ...options,
+            }),
+            interrupt: (id, options) => t.json({
+                method: "POST",
+                path: `${base()}/contexts/${encodeURIComponent(id)}:interrupt`,
+                body: {},
+                ...options,
+            }),
+            remove: (id, options) => t.json({
+                method: "DELETE",
+                path: `${base()}/contexts/${encodeURIComponent(id)}`,
+                ...options,
+            }),
+        },
+        /** The bytes of a result too large to travel inline (a `refs` entry). */
+        result(ref, options) {
+            const match = /^\/workspace\/\.runtime\/interpreter\/([a-z0-9][a-z0-9-]*)\/out\/([A-Za-z0-9][A-Za-z0-9_.-]*)$/.exec(ref.path);
+            if (!match)
+                throw new Error("Not an interpreter result path");
+            return t.bytes({
+                method: "GET",
+                path: `${base()}/contexts/${match[1]}/results/${match[2]}`,
+                ...options,
+            });
+        },
+    };
+}

package/dist/products/network.d.ts

@@ -0,0 +1,47 @@
+import type { Sandbox } from "../sandbox.js";
+import type { RequestOptions, Transport } from "../transport.js";
+/** A sandbox's own network rules. */
+export type NetworkRules = {
+    /** false refuses every outbound connection. */
+    internet: boolean;
+    /** When not empty, only these web destinations are reachable: `example.com`,
+     * `*.example.com` (subdomains, not the apex), an address or a CIDR range. */
+    allow?: string[];
+    /** Never reachable. Wins over everything. */
+    deny?: string[];
+    /** host:port pairs beyond ports 80 and 443, such as `db.example.com:5432` or
+     * `github.com:22`. Paid sandboxes of organizations with a paid purchase
+     * only. In the sandbox, `python3 /usr/local/lib/runtime/guest-egress.py
+     * forward 5432 db.example.com:5432` gives psql a local port. */
+    connect?: string[];
+};
+export type NetworkPolicy = Required<NetworkRules> & {
+    sandboxId: string;
+    version: number;
+    /** The sandbox's host confirmed it enforces this version. */
+    enforced: boolean;
+    enforcedVersion: number;
+    /** Ports reachable without a connect entry. */
+    ports: number[];
+    connectAllowed: boolean;
+    /** paid, granted, not_paid, revoked or suspended. */
+    connectReason: string;
+    forbiddenPorts: number[];
+    updatedAt: string | null;
+};
+/** `sbx.network`: turn the sandbox's internet off or on, narrow it to a list,
+ * refuse destinations, or open host:port pairs. Changes apply at once, to open
+ * connections too.
+ *
+ *   await sbx.network.set({ internet: true, allow: ["registry.npmjs.org"] });
+ *   await sbx.network.set({ internet: false });
+ */
+export declare function sandboxNetwork(t: Transport, sandbox: Sandbox): {
+    get: (options?: RequestOptions) => Promise<NetworkPolicy>;
+    /** Replaces the rules. */
+    set: (rules: NetworkRules, options?: RequestOptions) => Promise<NetworkPolicy>;
+    /** No outbound connections at all. */
+    off: (options?: RequestOptions) => Promise<NetworkPolicy>;
+    /** The host's public-web policy and nothing narrower. */
+    on: (options?: RequestOptions) => Promise<NetworkPolicy>;
+};

package/dist/products/network.js

@@ -0,0 +1,19 @@
+/** `sbx.network`: turn the sandbox's internet off or on, narrow it to a list,
+ * refuse destinations, or open host:port pairs. Changes apply at once, to open
+ * connections too.
+ *
+ *   await sbx.network.set({ internet: true, allow: ["registry.npmjs.org"] });
+ *   await sbx.network.set({ internet: false });
+ */
+export function sandboxNetwork(t, sandbox) {
+    const path = () => `/v1/sandboxes/${encodeURIComponent(sandbox.id)}/network`;
+    return {
+        get: (options) => t.json({ method: "GET", path: path(), ...options }),
+        /** Replaces the rules. */
+        set: (rules, options) => t.json({ method: "PUT", path: path(), body: rules, ...options }),
+        /** No outbound connections at all. */
+        off: (options) => t.json({ method: "PUT", path: path(), body: { internet: false }, ...options }),
+        /** The host's public-web policy and nothing narrower. */
+        on: (options) => t.json({ method: "PUT", path: path(), body: { internet: true }, ...options }),
+    };
+}

package/dist/products/previews.d.ts

@@ -0,0 +1,51 @@
+import type { Sandbox } from "../sandbox.js";
+import type { RequestOptions, Transport } from "../transport.js";
+/** A public HTTPS address for a port inside a sandbox. */
+export type Preview = {
+    id: string;
+    sandboxId: string;
+    port: number;
+    visibility: "private" | "public";
+    /** `https://<port>-<sandbox>.<preview domain>/`. A private preview also
+     * needs the token. */
+    url: string;
+    /** Private previews: a fresh signed token. Send it as the
+     * `x-runtime-preview-token` header. */
+    token: string | null;
+    tokenExpiresAt: string | null;
+    /** Private previews: a link that carries the token once, for a browser. */
+    urlWithToken: string | null;
+    /** Turned off by Runtime after a report. */
+    disabled: boolean;
+    createdAt: string;
+};
+export type CreatePreview = {
+    /** private (default): a token is needed. public: anyone with the address;
+     * a browser sees a one-time warning page naming Runtime. */
+    visibility?: "private" | "public";
+    /** How long the returned token lasts, 60 s to 7 days (default 1 day). */
+    ttlSeconds?: number;
+};
+/** `sbx.previews`: share ports of this sandbox at public HTTPS addresses.
+ *
+ *   const { url, token } = await sbx.previews.create(3000);
+ *   await fetch(url, { headers: { "x-runtime-preview-token": token! } });
+ *
+ * WebSockets work. The server must listen on 0.0.0.0 or localhost. */
+export declare function sandboxPreviews(t: Transport, sandbox: Sandbox): {
+    /** Shares `port`, or changes its visibility if it is shared already. */
+    create: (port: number, input?: CreatePreview, options?: RequestOptions) => Promise<Preview>;
+    /** Every shared port, each private one with a fresh token. */
+    list: (options?: RequestOptions) => Promise<Preview[]>;
+    /** One preview, with a fresh token of `ttlSeconds` if it is private. */
+    get: (port: number, ttlSeconds?: number, options?: RequestOptions) => Promise<Preview>;
+    /** Refuses every token issued for this port so far and returns a new one. */
+    rotate: (port: number, options?: RequestOptions) => Promise<Preview>;
+    /** Stops sharing `port`. Open connections close within seconds. */
+    delete: (port: number, options?: RequestOptions) => Promise<{
+        id: string;
+        sandboxId: string;
+        port: number;
+        deleted: true;
+    }>;
+};

package/dist/products/previews.js

@@ -0,0 +1,30 @@
+/** `sbx.previews`: share ports of this sandbox at public HTTPS addresses.
+ *
+ *   const { url, token } = await sbx.previews.create(3000);
+ *   await fetch(url, { headers: { "x-runtime-preview-token": token! } });
+ *
+ * WebSockets work. The server must listen on 0.0.0.0 or localhost. */
+export function sandboxPreviews(t, sandbox) {
+    const base = () => `/v1/sandboxes/${encodeURIComponent(sandbox.id)}/previews`;
+    return {
+        /** Shares `port`, or changes its visibility if it is shared already. */
+        create: (port, input = {}, options) => t.json({ method: "POST", path: base(), body: { port, ...input }, ...options }),
+        /** Every shared port, each private one with a fresh token. */
+        list: async (options) => (await t.json({ method: "GET", path: base(), ...options })).data,
+        /** One preview, with a fresh token of `ttlSeconds` if it is private. */
+        get: (port, ttlSeconds, options) => t.json({
+            method: "GET",
+            path: `${base()}/${port}`,
+            ...(ttlSeconds ? { query: { ttlSeconds } } : {}),
+            ...options,
+        }),
+        /** Refuses every token issued for this port so far and returns a new one. */
+        rotate: (port, options) => t.json({ method: "POST", path: `${base()}/${port}:rotate`, ...options }),
+        /** Stops sharing `port`. Open connections close within seconds. */
+        delete: (port, options) => t.json({
+            method: "DELETE",
+            path: `${base()}/${port}`,
+            ...options,
+        }),
+    };
+}

package/dist/products/referrals.d.ts

@@ -0,0 +1,36 @@
+import type { RequestOptions, Transport } from "../transport.js";
+/** Your organization's referral link and what it has earned. Money is integer
+ * microdollars in strings (1,000,000 = $1). */
+export type ReferralSummary = {
+    code: string;
+    /** Share this: https://withruntime.com/r/<code>. */
+    link: string;
+    /** The least each side gets: a first top-up is matched, never below this. */
+    rewardMicros: string;
+    /** The most each side gets: a first top-up is matched up to this. */
+    maxRewardMicros: string;
+    /** The smallest first top-up that pays a referral. */
+    minPurchaseMicros: string;
+    /** The most referral credit you can earn in one calendar year (UTC). */
+    yearlyCapMicros: string;
+    enabled: boolean;
+    year: number;
+    signedUp: number;
+    pending: number;
+    paid: number;
+    capped: number;
+    reversed: number;
+    earnedMicros: string;
+    earnedThisYearMicros: string;
+    capRemainingMicros: string;
+    referredBy: {
+        status: "pending" | "paid" | "refused" | "reversed";
+        creditMicros: string;
+    } | null;
+};
+/** `runtime.referrals.get()`: when a company that signs up with your link makes
+ * its first top-up of at least $10, you and it each get credit equal to that
+ * top-up, at least $25 and at most $500. */
+export declare function referrals(t: Transport): {
+    get: (options?: RequestOptions) => Promise<ReferralSummary>;
+};

package/dist/products/referrals.js

@@ -0,0 +1,8 @@
+/** `runtime.referrals.get()`: when a company that signs up with your link makes
+ * its first top-up of at least $10, you and it each get credit equal to that
+ * top-up, at least $25 and at most $500. */
+export function referrals(t) {
+    return {
+        get: (options) => t.json({ method: "GET", path: "/v1/referrals", ...options }),
+    };
+}

package/dist/products/volumes.d.ts

@@ -0,0 +1,47 @@
+import { Page } from "../page.js";
+import type { RequestOptions, Transport } from "../transport.js";
+export type VolumeState = "creating" | "ready" | "failed" | "deleting" | "deleted";
+export type Volume = {
+    id: string;
+    kind: "volume";
+    status: string;
+    state: VolumeState;
+    name: string | null;
+    labels: Record<string, string>;
+    region: string;
+    sizeMiB: number;
+    filesystem: "ext4";
+    usedMiB: number | null;
+    measuredAt: string | null;
+    /** Always false: a volume lives on one host and is not copied off it. */
+    backedUp: false;
+    attachments: {
+        sandboxId: string;
+        mode: "rw" | "snapshot";
+        path: string;
+        attachedAt: string;
+    }[];
+    error: string | null;
+    createdAt: string;
+    readyAt: string | null;
+};
+export type CreateVolume = {
+    sizeMiB: number;
+    name?: string;
+    labels?: Record<string, string>;
+    region?: string;
+};
+/** Persistent disks: create once, attach when creating a sandbox with
+ * `volumes: [{ volumeId: v.id, path: "/data" }]`. Not backed up off its host. */
+export declare function volumes(t: Transport): {
+    /** Create and wait (up to 10 s) until it is ready. */
+    create: (input: CreateVolume, options?: RequestOptions) => Promise<Volume>;
+    get: (id: string, options?: RequestOptions) => Promise<Volume>;
+    list: (query?: {
+        state?: VolumeState;
+        name?: string;
+        limit?: number;
+        cursor?: string;
+    }, options?: RequestOptions) => Promise<Page<Volume>>;
+    delete: (id: string, options?: RequestOptions) => Promise<Volume>;
+};

package/dist/products/volumes.js

@@ -0,0 +1,27 @@
+import { Page } from "../page.js";
+/** Persistent disks: create once, attach when creating a sandbox with
+ * `volumes: [{ volumeId: v.id, path: "/data" }]`. Not backed up off its host. */
+export function volumes(t) {
+    const get = (id, options) => t.json({ method: "GET", path: `/v1/volumes/${encodeURIComponent(id)}`, ...options });
+    const list = async (query = {}, options) => {
+        const page = await t.json({
+            method: "GET",
+            path: "/v1/volumes",
+            query,
+            ...options,
+        });
+        return new Page(page.data, page.nextCursor, (cursor) => list({ ...query, cursor }, options));
+    };
+    return {
+        /** Create and wait (up to 10 s) until it is ready. */
+        create: (input, options) => t.json({ method: "POST", path: "/v1/volumes", body: input, wait: 10, ...options }),
+        get,
+        list,
+        delete: (id, options) => t.json({
+            method: "POST",
+            path: `/v1/volumes/${encodeURIComponent(id)}:delete`,
+            body: {},
+            ...options,
+        }),
+    };
+}

package/dist/sandbox.d.ts

@@ -0,0 +1,192 @@
+import { Page } from "./page.js";
+import type { RequestOptions, Transport } from "./transport.js";
+import type { CommandResult, ExecOptions, FileEntry, OutputEvent, ProcessInfo, SandboxInfo } from "./types.js";
+import { type SandboxExtensions } from "./products/index.js";
+import type { Snapshot, SnapshotOptions } from "./snapshots.js";
+/** A running (or stopped) sandbox. Every method is one API call or a short
+ * sequence of them; `await using sbx = await Sandbox.create()` stops it for
+ * you at the end of the block. */
+export interface Sandbox extends SandboxExtensions {
+}
+export declare class Sandbox implements AsyncDisposable {
+    #private;
+    readonly files: Files;
+    readonly processes: Processes;
+    constructor(transport: Transport, info: SandboxInfo);
+    get id(): string;
+    /** What the API last said about this sandbox. `refresh()` asks again. */
+    get info(): SandboxInfo;
+    get state(): SandboxInfo["state"];
+    refresh(options?: RequestOptions): Promise<this>;
+    /** Waits (server-side, no polling) until the sandbox reaches `state`. */
+    waitFor(state: "running" | "paused" | "stopped", options?: {
+        timeoutSeconds?: number;
+    } & RequestOptions): Promise<this>;
+    /** Runs a command and returns its exit code and output. A string runs under
+     * `bash -c`; an array runs without a shell. With onStdout/onStderr the output
+     * streams as it happens. A timeout is a result (timedOut: true, the output so
+     * far), never an error; `check: true` throws CommandError on a non-zero exit. */
+    exec(command: string | readonly string[], options?: ExecOptions): Promise<CommandResult>;
+    /** The command's events as they happen: start, stdout, stderr, exit. Resumes
+     * by itself when the server ends a long stream, so it never drops output. */
+    execStream(command: string | readonly string[], options?: ExecOptions): AsyncGenerator<OutputEvent>;
+    /** Starts a background process (a server, a watcher, a REPL) and returns at
+     * once. `stdin: "pipe"` keeps its input open for write(); `pty` gives it a
+     * terminal. */
+    spawn(command: string | readonly string[], options?: Omit<ExecOptions, "onStdout" | "onStderr" | "check" | "stdin"> & {
+        /** "pipe" keeps input open for write(); any other text is given once, then closed. */
+        stdin?: string;
+        pty?: {
+            cols?: number;
+            rows?: number;
+        };
+    }): Promise<Process>;
+    /** An interactive terminal over a WebSocket. Bytes you write are typed;
+     * onData receives what the terminal prints. */
+    terminal(options?: {
+        cols?: number;
+        rows?: number;
+        command?: string;
+        cwd?: string;
+        /** Attach to a process started with a pty instead of a new shell. */
+        processId?: string;
+        onData?: (data: Uint8Array) => void;
+    }): Promise<Terminal>;
+    stop(options?: RequestOptions & {
+        wait?: boolean;
+    }): Promise<this>;
+    pause(options?: RequestOptions & {
+        wait?: boolean;
+    }): Promise<this>;
+    /** Carries on a paused sandbox; `timeoutSeconds` is its new lease. */
+    wake(options?: RequestOptions & {
+        wait?: boolean;
+        timeoutSeconds?: number;
+    }): Promise<this>;
+    /** More time before the lease ends (at most an hour ahead of now). */
+    extend(seconds: number, options?: RequestOptions): Promise<this>;
+    /** Days a paused sandbox is kept before deletion (1 to 365). */
+    setRetention(days: number, options?: RequestOptions): Promise<this>;
+    /** Keeps this sandbox's whole machine (files, memory, running processes) as
+     * a snapshot to start new sandboxes from. A running sandbox is paused for
+     * the moment it takes, then woken; a paused one stays paused. */
+    snapshot(options?: SnapshotOptions & RequestOptions): Promise<Snapshot>;
+    /** Copies of this sandbox as it is now (files, memory, running processes),
+     * each its own sandbox, answered once they run. A running sandbox is paused
+     * for the moment its snapshot takes, then woken. One without `count`; an
+     * array with it. */
+    fork(options?: {
+        name?: string;
+        labels?: Record<string, string>;
+        keepSnapshot?: boolean;
+    } & RequestOptions): Promise<Sandbox>;
+    fork(options: {
+        count: number;
+        name?: string;
+        labels?: Record<string, string>;
+        keepSnapshot?: boolean;
+    } & RequestOptions): Promise<Sandbox[]>;
+    /** Starts a stopped persistent sandbox again from its disk (memory is not kept). */
+    restart(options?: RequestOptions & {
+        wait?: boolean;
+    }): Promise<this>;
+    [Symbol.asyncDispose](): Promise<void>;
+    toJSON(): SandboxInfo;
+}
+export declare class Processes {
+    private readonly t;
+    private readonly sandboxId;
+    constructor(t: Transport, sandboxId: string);
+    list(): Promise<ProcessInfo[]>;
+    get(processId: string): Promise<Process>;
+    /** Output events from `cursor` until the process exits, across stream slices. */
+    follow(processId: string, options?: {
+        cursor?: number;
+        signal?: AbortSignal;
+    }): AsyncGenerator<OutputEvent>;
+}
+/** A background process: its output, its input, its end. */
+export declare class Process {
+    #private;
+    private readonly t;
+    readonly sandboxId: string;
+    info: ProcessInfo;
+    constructor(t: Transport, sandboxId: string, info: ProcessInfo);
+    get id(): string;
+    /** Every output event from the start (or `cursor`) until exit. */
+    output(options?: {
+        cursor?: number;
+        signal?: AbortSignal;
+    }): AsyncGenerator<OutputEvent>;
+    /** Waits for the process to end and returns its result. */
+    wait(options?: {
+        signal?: AbortSignal;
+    }): Promise<CommandResult>;
+    /** Sends input. Offsets are tracked for you, so a retried write is never typed twice. */
+    write(data: string | Uint8Array, options?: {
+        eof?: boolean;
+    }): Promise<void>;
+    kill(signal?: "SIGTERM" | "SIGKILL" | "SIGINT" | "SIGHUP" | "SIGQUIT" | "SIGUSR1" | "SIGUSR2"): Promise<void>;
+    resize(cols: number, rows: number): Promise<void>;
+    refresh(): Promise<ProcessInfo>;
+}
+export declare class Terminal {
+    #private;
+    private readonly socket;
+    readonly exited: Promise<number | null>;
+    private constructor();
+    get processId(): string | undefined;
+    static open(socket: WebSocket, onData?: (data: Uint8Array) => void): Promise<Terminal>;
+    write(data: string | Uint8Array): void;
+    resize(cols: number, rows: number): void;
+    close(): void;
+}
+/** Files in the sandbox. Paths are absolute; any path the sandbox user may use. */
+export declare class Files {
+    #private;
+    private readonly t;
+    private readonly sandboxId;
+    constructor(t: Transport, sandboxId: string);
+    /** A file's bytes, any size. */
+    read(path: string, options?: RequestOptions): Promise<Uint8Array>;
+    readText(path: string, options?: RequestOptions): Promise<string>;
+    /** Writes a file of any size, atomically, making parent directories. Large
+     * ones go in parallel 1 MiB chunks checked against their SHA-256. */
+    write(path: string, data: string | Uint8Array, options?: RequestOptions): Promise<{
+        path: string;
+        size: number;
+    }>;
+    /** Directory entries; `depth` goes deeper, `glob` filters (e.g. "**\/*.py"). */
+    list(path?: string, options?: {
+        depth?: number;
+        glob?: string;
+        hidden?: boolean;
+        limit?: number;
+    }): Promise<FileEntry[]>;
+    glob(pattern: string, root?: string): Promise<FileEntry[]>;
+    stat(path: string): Promise<(FileEntry & {
+        exists: true;
+    }) | {
+        exists: false;
+        path: string;
+    }>;
+    exists(path: string): Promise<boolean>;
+    mkdir(path: string, options?: {
+        parents?: boolean;
+    }): Promise<void>;
+    remove(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<boolean>;
+    rename(from: string, to: string, options?: {
+        overwrite?: boolean;
+    }): Promise<void>;
+    /** Copies a local file or directory into the sandbox. A directory travels as
+     * one gzipped tar and is unpacked in place. */
+    upload(localPath: string, remotePath: string): Promise<void>;
+    /** Copies a file or directory out of the sandbox. */
+    download(remotePath: string, localPath: string): Promise<void>;
+}
+export declare function sandboxPage(t: Transport, body: {
+    data: SandboxInfo[];
+    nextCursor: string | null;
+}, query: Record<string, unknown>): Page<Sandbox>;