withruntime 0.10.0 → 0.11.0

package/dist/network-cli.js

@@ -70,6 +70,12 @@ export const NETWORK_HELP = {
   upstream-proxy remove                  Connections leave directly again
   A proxy that refuses or cannot be reached fails the connection; nothing goes
   around it. Paid accounts only.
+
+  private on                             Your sandboxes reach each other by name, over TCP:
+                                         <name>.sandbox.internal:<port> or <id>.sandbox.internal:<port>
+  private off                            They stop; open connections between them are cut
+  private status                         On or off
+  Only your own sandboxes answer. Paid accounts only, and free.
 `,
 };
 function usage(product, message) {
@@ -400,6 +406,28 @@ export async function networkProductCommand(product, argv, args, out, client) {
             }
         }
     }
+    if (product === "network" && verb === "private") {
+        const describe = (state) => state.enabled
+            ? "On: your sandboxes reach each other at <name>.sandbox.internal:<port> over TCP."
+            : state.allowed
+                ? "Off. Turn it on: runtime network private on"
+                : "Off. Reaching your sandboxes by name is for paid accounts; add credit to turn it on.";
+        switch (rest[0]) {
+            case "on":
+            case "off": {
+                const state = await runtime.network.private.set({ enabled: rest[0] === "on" });
+                print(state.enabled ? describe(state) : "Off. Open connections between your sandboxes are cut.", state);
+                return 0;
+            }
+            case "status":
+            case undefined: {
+                const state = await runtime.network.private.get();
+                print(describe(state), state);
+                return 0;
+            }
+        }
+        throw usage(product, "private takes on, off or status.");
+    }
     if (product === "network") {
         if (verb !== "upstream-proxy")
             throw usage(product, `Unknown network command ${verb}.`);

package/dist/products/browser.d.ts

@@ -0,0 +1,60 @@
+import type { Sandbox } from "../sandbox.js";
+import type { RequestOptions, Transport } from "../transport.js";
+export type SandboxBrowser = {
+    running: false;
+} | {
+    running: true;
+    headless: boolean;
+    /** Chromium's version, e.g. "Chrome/154.0.8037.92". */
+    version: string;
+    /** The browser's DevTools WebSocket with its private token: give it as it
+     * is to Playwright's `chromium.connectOverCDP`, `puppeteer.connect({
+     * browserWSEndpoint })`, browser-use or Stagehand. */
+    cdpUrl: string;
+    /** The DevTools HTTP endpoint; send `headers` with it. */
+    httpUrl: string;
+    headers: Record<string, string>;
+    /** When the token in cdpUrl ends; `get()` returns a fresh one. */
+    expiresAt: string | null;
+    /** headless: false only: the desktop's live view. */
+    streamUrl?: string;
+};
+export type BrowserStartOptions = {
+    /** true (the default): no window. false: on the sandbox's desktop, with a live view. */
+    headless?: boolean;
+    width?: number;
+    height?: number;
+};
+/** `sbx.browser`: Chromium in the sandbox, for agents that speak CDP.
+ *
+ *   const { cdpUrl } = await sbx.browser.start();
+ *   const browser = await chromium.connectOverCDP(cdpUrl);
+ *
+ * Inside the sandbox the same browser is at http://127.0.0.1:9222. */
+export declare function sandboxBrowser(t: Transport, sandbox: Sandbox): {
+    /** Starts Chromium and returns its CDP address. The first start in a
+     * sandbox installs Chromium, about a minute; this waits for it (up to 10
+     * minutes). Starting a running browser returns it as it is. */
+    start(input?: BrowserStartOptions, options?: RequestOptions): Promise<{
+        running: true;
+        headless: boolean;
+        /** Chromium's version, e.g. "Chrome/154.0.8037.92". */
+        version: string;
+        /** The browser's DevTools WebSocket with its private token: give it as it
+         * is to Playwright's `chromium.connectOverCDP`, `puppeteer.connect({
+         * browserWSEndpoint })`, browser-use or Stagehand. */
+        cdpUrl: string;
+        /** The DevTools HTTP endpoint; send `headers` with it. */
+        httpUrl: string;
+        headers: Record<string, string>;
+        /** When the token in cdpUrl ends; `get()` returns a fresh one. */
+        expiresAt: string | null;
+        /** headless: false only: the desktop's live view. */
+        streamUrl?: string;
+    }>;
+    /** Whether it runs, and a fresh cdpUrl when it does. */
+    get: (options?: RequestOptions) => Promise<SandboxBrowser>;
+    stop: (options?: RequestOptions) => Promise<{
+        stopped: boolean;
+    }>;
+};

package/dist/products/browser.js

@@ -0,0 +1,37 @@
+/** `sbx.browser`: Chromium in the sandbox, for agents that speak CDP.
+ *
+ *   const { cdpUrl } = await sbx.browser.start();
+ *   const browser = await chromium.connectOverCDP(cdpUrl);
+ *
+ * Inside the sandbox the same browser is at http://127.0.0.1:9222. */
+export function sandboxBrowser(t, sandbox) {
+    const base = () => `/v1/sandboxes/${encodeURIComponent(sandbox.id)}/browser`;
+    return {
+        /** Starts Chromium and returns its CDP address. The first start in a
+         * sandbox installs Chromium, about a minute; this waits for it (up to 10
+         * minutes). Starting a running browser returns it as it is. */
+        async start(input = {}, options) {
+            const deadline = Date.now() + 600_000;
+            for (;;) {
+                try {
+                    return await t.json({
+                        method: "POST",
+                        path: `${base()}:start`,
+                        body: input,
+                        ...options,
+                    });
+                }
+                catch (error) {
+                    const code = error.code;
+                    if ((code !== "browser_installing" && code !== "desktop_installing") ||
+                        Date.now() > deadline)
+                        throw error;
+                    await new Promise((resolve) => setTimeout(resolve, error.retryAfterMs ?? 10_000));
+                }
+            }
+        },
+        /** Whether it runs, and a fresh cdpUrl when it does. */
+        get: (options) => t.json({ method: "GET", path: base(), ...options }),
+        stop: (options) => t.json({ method: "POST", path: `${base()}:stop`, ...options }),
+    };
+}

package/dist/products/desktop.d.ts

@@ -115,8 +115,8 @@ export declare function sandboxDesktop(t: Transport, sandbox: Sandbox): {
     focus: (windowId: string, options?: RequestOptions) => Promise<{
         ok: true;
     }>;
-    /** Opens `url` in Firefox on the desktop. Right after a sandbox's first
-     * start, Firefox may still be installing; this waits for it. */
+    /** Opens `url` in Chromium on the desktop. Right after a sandbox's first
+     * start, Chromium may still be installing; this waits for it. */
     open(url: string, options?: RequestOptions): Promise<{
         ok: true;
     }>;

package/dist/products/desktop.js

@@ -50,8 +50,8 @@ export function sandboxDesktop(t, sandbox) {
         cursor: (options) => act({ action: "cursor" }, options),
         windows: async (options) => (await act({ action: "windows" }, options)).windows,
         focus: (windowId, options) => act({ action: "focus", windowId }, options),
-        /** Opens `url` in Firefox on the desktop. Right after a sandbox's first
-         * start, Firefox may still be installing; this waits for it. */
+        /** Opens `url` in Chromium on the desktop. Right after a sandbox's first
+         * start, Chromium may still be installing; this waits for it. */
         async open(url, options) {
             const deadline = Date.now() + 600_000;
             for (;;) {

package/dist/products/images.d.ts

@@ -212,7 +212,9 @@ export declare function images(t: Transport): {
     /** Point `tag` of the image's name at this version. */
     tag(ref: string, tag: string, options?: RequestOptions): Promise<Image>;
     untag(ref: string, tag: string, options?: RequestOptions): Promise<Image>;
-    /** Delete one version (by id, name:tag or name@version) and its tags. */
+    /** Delete one version (by id, name:tag or name@version) and its tags. A
+     * bare name deletes its latest tag's version, or its only version when
+     * it has one and no latest tag; with several, the error names its tags. */
     delete(ref: string, options?: RequestOptions): Promise<Image>;
     /** Credentials for private registries. The secret is sealed on arrival
      * and never returned. */

package/dist/products/images.js

@@ -1,3 +1,4 @@
+import { RuntimeError } from "../errors.js";
 import { Page } from "../page.js";
 const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
 const PARALLEL_UPLOADS = 4;
@@ -189,11 +190,22 @@ export function images(t) {
                 ...options,
             });
         },
-        /** Delete one version (by id, name:tag or name@version) and its tags. */
+        /** Delete one version (by id, name:tag or name@version) and its tags. A
+         * bare name deletes its latest tag's version, or its only version when
+         * it has one and no latest tag; with several, the error names its tags. */
         async delete(ref, options) {
+            const id = await idOf(ref, options).catch(async (error) => {
+                if (!(error instanceof RuntimeError && error.code === "image_not_found") ||
+                    /[:@]/.test(ref))
+                    throw error;
+                const live = (await list({ name: ref, limit: 100 }, options)).data.filter((image) => image.state !== "deleted" && image.state !== "deleting");
+                if (live.length !== 1)
+                    throw error;
+                return live[0].id;
+            });
             return t.json({
                 method: "POST",
-                path: `/v1/images/${enc(await idOf(ref, options))}:delete`,
+                path: `/v1/images/${enc(id)}:delete`,
                 body: {},
                 ...options,
             });

package/dist/products/index.d.ts

@@ -2,6 +2,7 @@ import type { Transport } from "../transport.js";
 import type { Sandbox } from "../sandbox.js";
 import { images } from "./images.js";
 import { sandboxDesktop } from "./desktop.js";
+import { sandboxBrowser } from "./browser.js";
 import { sandboxInterpreter } from "./interpreter.js";
 import { sandboxNetwork } from "./network.js";
 import { addresses, domains, network, ports, tunnel } from "./network-products.js";
@@ -55,6 +56,7 @@ export declare const sandboxExtensions: {
     previews: typeof sandboxPreviews;
     network: typeof sandboxNetwork;
     desktop: typeof sandboxDesktop;
+    browser: typeof sandboxBrowser;
     mounts: typeof sandboxMounts;
     tailscale: typeof sandboxTailscale;
     metrics: typeof sandboxMetrics;

package/dist/products/index.js

@@ -1,5 +1,6 @@
 import { images } from "./images.js";
 import { sandboxDesktop } from "./desktop.js";
+import { sandboxBrowser } from "./browser.js";
 import { sandboxInterpreter } from "./interpreter.js";
 import { sandboxNetwork } from "./network.js";
 import { addresses, domains, network, ports, tunnel } from "./network-products.js";
@@ -68,6 +69,7 @@ export const sandboxExtensions = {
     previews: sandboxPreviews,
     network: sandboxNetwork,
     desktop: sandboxDesktop,
+    browser: sandboxBrowser,
     mounts: sandboxMounts,
     tailscale: sandboxTailscale,
     metrics: sandboxMetrics,

package/dist/products/network-products.d.ts

@@ -195,6 +195,13 @@ export type SetUpstreamProxy = {
  * logs apply. A proxy that refuses or cannot be reached fails the connection
  * (upstream-proxy-failed); nothing goes around it. Paid accounts only. */
 export declare function network(t: Transport): {
+    /** Your sandboxes reaching each other by name (`private-network.ts`). */
+    private: {
+        get: (options?: RequestOptions) => Promise<import("./private-network.js").PrivateNetwork>;
+        set: (input: {
+            enabled: boolean;
+        }, options?: RequestOptions) => Promise<import("./private-network.js").PrivateNetwork>;
+    };
     upstreamProxy: {
         /** Send outbound connections through your proxy, replacing any set before. */
         set: (input: SetUpstreamProxy, options?: RequestOptions) => Promise<UpstreamProxy & {

package/dist/products/network-products.js

@@ -1,3 +1,4 @@
+import { privateNetwork } from "./private-network.js";
 const enc = encodeURIComponent;
 /** `runtime.domains`: serve a sandbox's port at your own hostname, with HTTPS. */
 export function domains(t) {
@@ -91,6 +92,8 @@ export function tunnel(t) {
 export function network(t) {
     const path = "/v1/network/upstream-proxy";
     return {
+        /** Your sandboxes reaching each other by name (`private-network.ts`). */
+        private: privateNetwork(t),
         upstreamProxy: {
             /** Send outbound connections through your proxy, replacing any set before. */
             set: (input, options) => t.json({

package/dist/products/private-network.d.ts

@@ -0,0 +1,22 @@
+import type { RequestOptions, Transport } from "../transport.js";
+export type PrivateNetwork = {
+    /** Whether your sandboxes reach each other by name now. */
+    enabled: boolean;
+    /** `sandbox.internal`. */
+    suffix: string;
+    /** Whether this account may turn it on: paid accounts only. */
+    allowed: boolean;
+    /** Why not, when `allowed` is false: `not_paid`, `revoked` or `suspended`. */
+    why: string | null;
+    enabledAt: string | null;
+    disabledAt: string | null;
+};
+export declare function privateNetwork(t: Transport): {
+    /** On or off, and whether this account may turn it on. */
+    get: (options?: RequestOptions) => Promise<PrivateNetwork>;
+    /** `enabled: true` lets your sandboxes reach each other by name; `false`
+     * stops it and cuts open connections between them within seconds. */
+    set: (input: {
+        enabled: boolean;
+    }, options?: RequestOptions) => Promise<PrivateNetwork>;
+};

package/dist/products/private-network.js

@@ -0,0 +1,10 @@
+export function privateNetwork(t) {
+    const path = "/v1/network/private";
+    return {
+        /** On or off, and whether this account may turn it on. */
+        get: (options) => t.json({ method: "GET", path, ...options }),
+        /** `enabled: true` lets your sandboxes reach each other by name; `false`
+         * stops it and cuts open connections between them within seconds. */
+        set: (input, options) => t.json({ method: "PUT", path, body: input, ...options }),
+    };
+}

package/dist/sandbox.d.ts

@@ -127,6 +127,21 @@ export declare class Sandbox implements AsyncDisposable {
     switchImage(image: string, options: RequestOptions & {
         keep: "workspace";
     }): Promise<this>;
+    /** Gives it more or fewer vCPUs or more or less memory by a restart: its id,
+     * whole disk, volumes, environment, name and previews stay, and its
+     * programs stop, which `restart: true` says you know (snapshot it first to
+     * keep its memory too). A running sandbox is paused, or stopped if it is
+     * persistent, and comes back running at the new size on the same server; a
+     * paused or stopped one is started. Memory bills on the new size from then.
+     * Refused, with nothing changed, when the server has no room
+     * (`no_capacity`), above your quota or the trial's 2 vCPU and 4 GiB, or
+     * while a snapshot or fork of it is being taken. */
+    resize(size: {
+        vcpu?: number;
+        memoryMiB?: number;
+    }, options: RequestOptions & {
+        restart: true;
+    }): Promise<this>;
     /** Keeps a running sandbox's lease ahead of now, in the background, until
      * stop() or the returned function ends it: every `everySeconds` (60) it
      * extends the lease so that `marginSeconds` (600) remain, never more than
@@ -229,6 +244,13 @@ export declare class Process {
     info: ProcessInfo;
     constructor(t: Transport, sandboxId: string, info: ProcessInfo);
     get id(): string;
+    /** The command line as the sandbox reports it. */
+    get command(): string;
+    /** As of the last answer: spawn, `wait()` or `refresh()`. */
+    get state(): ProcessInfo["state"];
+    /** null while it runs, and when it was killed or timed out. */
+    get exitCode(): number | null;
+    toJSON(): ProcessInfo;
     /** Every output event from the start (or `cursor`) until exit. */
     output(options?: {
         cursor?: number;

package/dist/sandbox.js

@@ -427,6 +427,27 @@ export class Sandbox {
         }));
         return this;
     }
+    /** Gives it more or fewer vCPUs or more or less memory by a restart: its id,
+     * whole disk, volumes, environment, name and previews stay, and its
+     * programs stop, which `restart: true` says you know (snapshot it first to
+     * keep its memory too). A running sandbox is paused, or stopped if it is
+     * persistent, and comes back running at the new size on the same server; a
+     * paused or stopped one is started. Memory bills on the new size from then.
+     * Refused, with nothing changed, when the server has no room
+     * (`no_capacity`), above your quota or the trial's 2 vCPU and 4 GiB, or
+     * while a snapshot or fork of it is being taken. */
+    async resize(size, options) {
+        const { restart, ...rest } = options;
+        this.#keep(await this.#t.json({
+            method: "POST",
+            path: `/v1/sandboxes/${enc(this.id)}:resize`,
+            body: { ...size, restart },
+            // A pause or stop and a cold boot.
+            wait: 120,
+            ...pick(rest),
+        }));
+        return this;
+    }
     /** Keeps a running sandbox's lease ahead of now, in the background, until
      * stop() or the returned function ends it: every `everySeconds` (60) it
      * extends the lease so that `marginSeconds` (600) remain, never more than
@@ -839,6 +860,26 @@ export class Process {
     get id() {
         return this.info.id;
     }
+    /** The command line as the sandbox reports it. */
+    get command() {
+        return this.info.command;
+    }
+    /** As of the last answer: spawn, `wait()` or `refresh()`. */
+    get state() {
+        return this.info.state;
+    }
+    /** null while it runs, and when it was killed or timed out. */
+    get exitCode() {
+        return this.info.exitCode;
+    }
+    toJSON() {
+        return this.info;
+    }
+    /** console.log shows what the process is, not the client inside it. */
+    [Symbol.for("nodejs.util.inspect.custom")](_depth, options, show) {
+        const { id, sandboxId, command, state, exitCode } = this;
+        return `Process ${show({ id, sandboxId, command, state, exitCode }, options)}`;
+    }
     /** Every output event from the start (or `cursor`) until exit. */
     output(options = {}) {
         return new Processes(this.t, this.sandboxId).follow(this.id, options);
@@ -884,6 +925,12 @@ export class Process {
             if (event.type === "exit")
                 exit = event;
         }
+        if (exit)
+            this.info = {
+                ...this.info,
+                state: exit.state,
+                exitCode: exit.exitCode,
+            };
         return {
             exitCode: exit?.exitCode ?? null,
             ...out,

package/dist/transport.d.ts

@@ -1,5 +1,5 @@
 import { RuntimeError } from "./errors.js";
-export declare const VERSION = "0.10.0";
+export declare const VERSION = "0.11.0";
 export declare const DEFAULT_BASE_URL = "https://api.withruntime.com";
 /** Runtime's API as code inside a Runtime sandbox reaches it: the sandbox's
  * own host sends each request on to DEFAULT_BASE_URL over HTTPS. The API runs

package/dist/transport.js

@@ -1,6 +1,6 @@
 import { ConnectionError, DELIBERATE, errorFor, RuntimeError, WAITS_FOR_ROOM } from "./errors.js";
 import { describeRoute, envFetch, openWebSocket } from "./proxy.js";
-export const VERSION = "0.10.0";
+export const VERSION = "0.11.0";
 export const DEFAULT_BASE_URL = "https://api.withruntime.com";
 /** Runtime's API as code inside a Runtime sandbox reaches it: the sandbox's
  * own host sends each request on to DEFAULT_BASE_URL over HTTPS. The API runs

package/dist/types.d.ts

@@ -42,8 +42,9 @@ export type SandboxInfo = {
     /** The names of its own environment variables (`env`), on a create, an
      * update and a read of one sandbox. Values are never shown. */
     envNames?: string[];
-    /** On a create from an image with a start command: whether it started,
-     * became ready (readyMs), timed out, or exited first. The create's answer
+    /** On a create from an image with a start command: whether it started
+     * (and was still running half a second later), became ready (readyMs),
+     * timed out, or exited first (exitCode, and stderr's last lines). The create's answer
      * alone carries it, and the Sandbox that create returned keeps it through
      * later reads; `sandboxes.get` and `list` have none, because the API keeps
      * no record of it. */
@@ -52,6 +53,8 @@ export type SandboxInfo = {
         processId?: string;
         exitCode?: number | null;
         readyMs?: number;
+        /** With exited: the last lines the start command wrote to stderr. */
+        stderr?: string;
     };
     /** Present and true when getOrCreate answered a sandbox that already held the name. */
     reused?: boolean;

package/dist/vercel/index.d.ts

@@ -1,6 +1,7 @@
 export { Sandbox, DEFAULT_TIMEOUT_MS, DEFAULT_VCPUS, MEMORY_MIB_PER_VCPU, networkRules, toRuntimePath, type CreateSandboxParams, type RunCommandParams, type NetworkPolicy, type SandboxRoute, } from "./sandbox.js";
 export { Command, CommandFinished, type CommandOutput, type LogOutputLine, type Signal, } from "./command.js";
 export { FileSystem, Stats, Dirent } from "./filesystem.js";
+export { SandboxUser, SandboxUserAlreadyExistsError } from "./sandbox-user.js";
 export { Snapshot } from "./snapshot.js";
 export { APIError, StreamError, AuthenticationError, NotSupportedError } from "./errors.js";
 export type { Credentials, WithRuntime } from "./client.js";
@@ -16,13 +17,6 @@ export declare const Session: {
     new (...args: unknown[]): never;
     readonly [key: string]: (...args: unknown[]) => never;
 };
-export declare const SandboxUser: {
-    (...args: unknown[]): never;
-    new (...args: unknown[]): never;
-    readonly [key: string]: (...args: unknown[]) => never;
-};
-export declare class SandboxUserAlreadyExistsError extends Error {
-}
 export declare const defineSandboxProxy: {
     (...args: unknown[]): never;
     new (...args: unknown[]): never;

package/dist/vercel/index.js

@@ -9,6 +9,7 @@ import { NotSupportedError } from "./errors.js";
 export { Sandbox, DEFAULT_TIMEOUT_MS, DEFAULT_VCPUS, MEMORY_MIB_PER_VCPU, networkRules, toRuntimePath, } from "./sandbox.js";
 export { Command, CommandFinished, } from "./command.js";
 export { FileSystem, Stats, Dirent } from "./filesystem.js";
+export { SandboxUser, SandboxUserAlreadyExistsError } from "./sandbox-user.js";
 export { Snapshot } from "./snapshot.js";
 export { APIError, StreamError, AuthenticationError, NotSupportedError } from "./errors.js";
 /** Vercel's default region; Runtime runs in one US region. */
@@ -32,7 +33,4 @@ function unsupportedExport(name, alternative) {
 }
 export const Drive = unsupportedExport("Drive", "Use a Runtime volume (runtime.volumes) and mount it with withruntime: { create: { volumes: [{ volumeId, path }] } }.");
 export const Session = unsupportedExport("Session", "A Runtime sandbox is its own session: call the methods on the sandbox.");
-export const SandboxUser = unsupportedExport("SandboxUser", "Commands run as the sandbox owner with passwordless sudo; create users with `sudo useradd` in runCommand.");
-export class SandboxUserAlreadyExistsError extends Error {
-}
 export const defineSandboxProxy = unsupportedExport("sandbox proxy (defineSandboxProxy)", "Share a port with sandbox.withruntime.previews.create(port) instead.");

package/dist/vercel/sandbox-user.d.ts

@@ -0,0 +1,70 @@
+import type { Command, CommandFinished } from "./command.js";
+import type { RunCommandParams, Sandbox } from "./sandbox.js";
+/** A Linux user or group name Vercel accepts, which is also safe to pass to
+ * useradd, groupadd and sudo. */
+export declare function validateName(name: string, kind: string): void;
+/** Thrown when `sandbox.createUser` is called for an existing username. */
+export declare class SandboxUserAlreadyExistsError extends Error {
+    readonly username: string;
+    constructor(username: string);
+}
+type Signal = {
+    signal?: AbortSignal;
+};
+/** A user in a sandbox, made with `sandbox.createUser` or found with
+ * `sandbox.asUser`. Commands and file calls run as this user. */
+export declare class SandboxUser {
+    #private;
+    readonly username: string;
+    /** `/root` for root, else `/home/<username>`. */
+    readonly homeDir: string;
+    /** Use sandbox.createUser or sandbox.asUser. */
+    constructor({ sandbox, username }: {
+        sandbox: Sandbox;
+        username: string;
+    });
+    /** Runs a command as this user. `sudo: true` runs it as root instead. */
+    runCommand(command: string, args?: string[], opts?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<CommandFinished>;
+    runCommand(params: RunCommandParams & {
+        detached: true;
+    }): Promise<Command>;
+    runCommand(params: RunCommandParams): Promise<CommandFinished>;
+    /** Writes files into this user's home (or absolute paths), then gives them
+     * and the directories made for them to this user. */
+    writeFiles(files: {
+        path: string;
+        content: string | Uint8Array;
+        mode?: number;
+    }[], opts?: Signal): Promise<void>;
+    /** The file as this user may read it, as a stream; null when missing. */
+    readFile(file: {
+        path: string;
+        cwd?: string;
+    }, opts?: Signal): Promise<NodeJS.ReadableStream | null>;
+    /** The file as this user may read it; null when missing. */
+    readFileToBuffer(file: {
+        path: string;
+        cwd?: string;
+    }, opts?: Signal): Promise<Buffer | null>;
+    /** Copies a file this user may read to the local disk; null when missing. */
+    downloadFile(src: {
+        path: string;
+        cwd?: string;
+    }, dst: {
+        path: string;
+        cwd?: string;
+    }, opts?: {
+        mkdirRecursive?: boolean;
+        signal?: AbortSignal;
+    }): Promise<string | null>;
+    /** Makes a directory owned by this user. */
+    mkDir(path: string, opts?: Signal): Promise<void>;
+    addToGroup(groupname: string, opts?: Signal): Promise<void>;
+    removeFromGroup(groupname: string, opts?: Signal): Promise<void>;
+}
+/** Runs `cmd args` under sudo; a non-zero exit throws `what(): <stderr>`. */
+export declare function rootOrThrow(sandbox: Sandbox, cmd: string, args: string[], signal: AbortSignal | undefined, what: () => string): Promise<CommandFinished>;
+export {};