withruntime 0.6.1 → 0.7.1

package/dist/client.d.ts

@@ -1,3 +1,4 @@
+import { RuntimeError } from "./errors.js";
 import type { Page } from "./page.js";
 import { type ClientExtensions } from "./products/index.js";
 import { Sandbox } from "./sandbox.js";
@@ -33,6 +34,7 @@ export declare class Runtime {
     readonly snapshots: Snapshots;
     readonly feedback: FeedbackApi;
     readonly support: SupportApi;
+    readonly account: AccountApi;
     constructor(options?: RuntimeOptions);
     /** Who this key is: organization, agent and credential. */
     me(options?: RequestOptions): Promise<{
@@ -49,6 +51,16 @@ export declare class Runtime {
     /** Credit, holds, trial time and per-resource charges. */
     usage(options?: RequestOptions): Promise<Usage>;
 }
+/** How `sandboxes.create` waits when every trial slot, the account's quota or
+ * the region is full. */
+export type CreateOptions = RequestOptions & {
+    /** How long to keep retrying a refusal that clears by itself. Default: the
+     * client's, two minutes; 0 fails at once. */
+    waitForCapacityMs?: number;
+    /** Called before each wait, with the refusal and the milliseconds until the
+     * next try: to tell a person why nothing has happened yet. */
+    onCapacityWait?: (refusal: RuntimeError, waitMs: number) => void;
+};
 export declare class Sandboxes {
     private readonly t;
     constructor(t: Transport);
@@ -59,18 +71,14 @@ export declare class Sandboxes {
      * free, up to `waitForCapacityMs` (the client's, two minutes by default). */
     create(input?: CreateSandbox & {
         wait?: boolean;
-    }, options?: RequestOptions & {
-        waitForCapacityMs?: number;
-    }): Promise<Sandbox>;
+    }, options?: CreateOptions): Promise<Sandbox>;
     /** The sandbox named `name` in this account, ready to use: running as it
      * is, woken if it is paused, restarted if it is stopped and persistent, or
      * created with `input` when no sandbox has the name. `sandbox.info.reused`
      * says which. The other fields apply only when it is created. */
     getOrCreate(name: string, input?: Omit<CreateSandbox, "name" | "getOrCreate"> & {
         wait?: boolean;
-    }, options?: RequestOptions & {
-        waitForCapacityMs?: number;
-    }): Promise<Sandbox>;
+    }, options?: CreateOptions): Promise<Sandbox>;
     get(id: string, options?: RequestOptions): Promise<Sandbox>;
     /** Live sandboxes, oldest first. Await for a page, or `for await` over all. */
     list(filter?: {
@@ -142,5 +150,26 @@ export declare class SupportApi {
     }): Promise<SupportReply>;
     read(conversationId: string): Promise<SupportReply>;
 }
+/** What closing the account answered. */
+export type ClosedAccount = {
+    orgId: string;
+    name: string;
+    closedAt: string;
+    /** False while what was running is still stopping; it is gone within minutes. */
+    released: boolean;
+};
+/** The account this key belongs to: `runtime.account`. */
+export declare class AccountApi {
+    private readonly t;
+    constructor(t: Transport);
+    /** Close the account for good: stop and delete everything it runs and
+     * stores, end every key and dissolve it. `confirm` must be the account's
+     * name exactly (`me().orgName`). Needs a key for every product made by an
+     * owner. Moves no money: what is unspent of a purchase made in the last 15
+     * days is refunded on request; other credit is forfeited. */
+    close(input: {
+        confirm: string;
+    }, options?: RequestOptions): Promise<ClosedAccount>;
+}
 /** The client behind the static helpers, from the environment. */
 export declare function defaultClient(): Runtime;

package/dist/client.js

@@ -20,6 +20,7 @@ export class Runtime {
     snapshots;
     feedback;
     support;
+    account;
     constructor(options = {}) {
         this.transport = new Transport({
             // A key given, then RUNTIME_API_KEY, then (in Node and Bun) the key
@@ -38,6 +39,7 @@ export class Runtime {
         this.snapshots = new Snapshots(this.transport);
         this.feedback = new FeedbackApi(this.transport);
         this.support = new SupportApi(this.transport);
+        this.account = new AccountApi(this.transport);
         for (const [name, make] of clientFactories())
             Object.defineProperty(this, name, { value: make(this.transport), enumerable: true });
     }
@@ -165,6 +167,27 @@ export class SupportApi {
         });
     }
 }
+/** The account this key belongs to: `runtime.account`. */
+export class AccountApi {
+    t;
+    constructor(t) {
+        this.t = t;
+    }
+    /** Close the account for good: stop and delete everything it runs and
+     * stores, end every key and dissolve it. `confirm` must be the account's
+     * name exactly (`me().orgName`). Needs a key for every product made by an
+     * owner. Moves no money: what is unspent of a purchase made in the last 15
+     * days is refunded on request; other credit is forfeited. */
+    close(input, options = {}) {
+        return this.t.json({
+            method: "POST",
+            path: "/v1/account:close",
+            body: { confirm: input.confirm },
+            retry: false,
+            ...options,
+        });
+    }
+}
 let shared;
 /** The client behind the static helpers, from the environment. */
 export function defaultClient() {

package/dist/credentials.js

@@ -3,8 +3,7 @@ import { constants } from "node:fs";
 import { lstat, mkdir, open, rename, unlink } from "node:fs/promises";
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
-import { apiOrigin } from "./index.js";
-import { missingKey } from "./transport.js";
+import { apiOrigin, missingKey } from "./transport.js";
 /** How many other accounts' connections one machine keeps beside the one in use. */
 const SAVED_ACCOUNTS = 20;
 export function connectionOrigins(env) {

package/dist/daytona/filesystem.d.ts

@@ -60,6 +60,8 @@ export declare class FileSystem {
     /** The file's bytes, or with a local path, the file written there. */
     downloadFile(remotePath: string, timeout?: number): Promise<Buffer>;
     downloadFile(remotePath: string, localPath: string, timeout?: number): Promise<void>;
+    /** The file as it arrives, without holding it in memory. It errors with
+     * `download_incomplete` if it ends short of the file's length. */
     downloadFileStream(remotePath: string): Promise<Readable>;
     /** Several files; a file that fails carries `error` instead of `result`. */
     downloadFiles(files: FileDownloadRequest[]): Promise<FileDownloadResponse[]>;

package/dist/daytona/filesystem.js

@@ -69,17 +69,19 @@ export class FileSystem {
     async downloadFile(remotePath, localOrTimeout) {
         const target = await this.#path(remotePath);
         const files = await this.#files();
-        const bytes = Buffer.from(await guard("file", () => files.read(target)));
         if (typeof localOrTimeout !== "string")
-            return bytes;
-        const { mkdir, writeFile } = await import("node:fs/promises");
-        const paths = await import("node:path");
-        await mkdir(paths.dirname(localOrTimeout), { recursive: true });
-        await writeFile(localOrTimeout, bytes);
+            return Buffer.from(await guard("file", () => files.read(target)));
+        // Streamed to disk, any size, checked against the file's length.
+        await guard("file", () => files.download(target, localOrTimeout));
     }
+    /** The file as it arrives, without holding it in memory. It errors with
+     * `download_incomplete` if it ends short of the file's length. */
     async downloadFileStream(remotePath) {
         const { Readable } = await import("node:stream");
-        return Readable.from([await this.downloadFile(remotePath)]);
+        const target = await this.#path(remotePath);
+        const files = await this.#files();
+        const stream = await guard("file", () => files.readStream(target));
+        return Readable.fromWeb(stream);
     }
     /** Several files; a file that fails carries `error` instead of `result`. */
     async downloadFiles(files) {

package/dist/e2b/commands.js

@@ -28,7 +28,8 @@ function timedOut(timeoutMs) {
         "Pass a larger 'timeoutMs', or 0 for no limit.");
 }
 /** A Runtime result as E2B's: a command killed by a signal has no exit code on
- * Runtime; E2B reports -1. */
+ * Runtime; E2B reports -1. E2B never loses output, so a result that did says
+ * so in `truncated` rather than passing as whole. */
 function toResult(result) {
     const exitCode = result.exitCode ?? -1;
     return {
@@ -40,12 +41,15 @@ function toResult(result) {
             : {
                 error: result.exitCode === null ? "terminated by a signal" : `exit status ${exitCode}`,
             }),
+        ...(result.truncated ? { truncated: true } : {}),
     };
 }
 function settle(result, timeoutMs) {
     if (result.timedOut)
         throw timedOut(timeoutMs);
     const out = toResult(result);
+    if (out.truncated && typeof process !== "undefined" && process.emitWarning)
+        process.emitWarning("Part of the command's output was dropped before it was read, so stdout and stderr are incomplete (result.truncated). Write large output to a file and read it with sandbox.files.read.", { code: "RUNTIME_E2B_OUTPUT_TRUNCATED" });
     if (out.exitCode !== 0)
         throw new CommandExitError(out);
     return out;
@@ -80,7 +84,7 @@ export class Commands {
             ...(onStderr ? { onStderr: (text) => void onStderr(text) } : {}),
             ...(opts.signal ? { signal: opts.signal } : {}),
         }));
-        return settle(result, timeoutMs);
+        return settle({ ...result, truncated: result.stdoutTruncated === true || result.stderrTruncated === true }, timeoutMs);
     }
     async #start(cmd, opts, timeoutMs) {
         const process = await guard("sandbox", () => this.#ctx.runtime.spawn(cmd, {
@@ -166,6 +170,7 @@ export class CommandHandle {
     #stdout = "";
     #stderr = "";
     #exit;
+    #truncated = false;
     #failure;
     #disconnected = false;
     constructor(process, options) {
@@ -189,6 +194,9 @@ export class CommandHandle {
                     this.#stderr += event.data;
                     await options.onStderr?.(event.data);
                 }
+                else if (event.type === "truncated") {
+                    this.#truncated = true;
+                }
                 else if (event.type === "exit") {
                     this.#exit = { exitCode: event.exitCode, timedOut: event.timedOut };
                 }
@@ -237,6 +245,7 @@ export class CommandHandle {
             stdout: this.#stdout,
             stderr: this.#stderr,
             timedOut: this.#exit.timedOut,
+            truncated: this.#truncated,
         }, this.#timeoutMs);
     }
     /** Stops receiving output; the command keeps running. */

package/dist/e2b/errors.d.ts

@@ -52,6 +52,10 @@ export interface CommandResult {
     error?: string;
     stdout: string;
     stderr: string;
+    /** Runtime's addition, present only when true: some of the command's
+     * output was dropped before it was read, so `stdout` and `stderr` are
+     * missing part of it. A warning says so too. */
+    truncated?: true;
 }
 /** Thrown by `commands.run` and `CommandHandle.wait` when the command exits
  * with a code other than 0. It carries the result, as in E2B. */
@@ -62,6 +66,7 @@ export declare class CommandExitError extends SandboxError implements CommandRes
     get error(): string | undefined;
     get stdout(): string;
     get stderr(): string;
+    get truncated(): true | undefined;
 }
 /** Which object a call was about, to name a 404 the way E2B would. */
 export type Subject = "sandbox" | "file" | "other";

package/dist/e2b/errors.js

@@ -92,6 +92,9 @@ export class CommandExitError extends SandboxError {
     get stderr() {
         return this.#result.stderr;
     }
+    get truncated() {
+        return this.#result.truncated;
+    }
 }
 /** 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. */

package/dist/e2b/filesystem.js

@@ -79,14 +79,15 @@ export class Filesystem {
     }
     async read(path, opts = {}) {
         const file = await this.#path(path, opts);
+        // A real stream, any size, never the whole file held first.
+        if (opts.format === "stream")
+            return guard("file", () => this.#files.readStream(file, request(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);
         }

package/dist/e2b/sandbox.d.ts

@@ -86,8 +86,6 @@ export type SandboxListOpts = SandboxApiOpts & {
     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;
@@ -156,12 +154,17 @@ export declare class Sandbox {
         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. */
+    /** E2B's getHost, answered at once as E2B answers it:
+     * `<port>-<id>.runtimehost.com`. A Runtime preview's address is made from
+     * the sandbox and the port alone, so it is known without a call; the port
+     * is shared publicly the first time it is asked for, in about a tenth of a
+     * second, beside the caller. A request that lands before the share may be
+     * answered 404 for up to two seconds; `await getPublicHost(port)` returns
+     * once the share has landed. */
     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. */
+     * its host, `<port>-<id>.<domain>`, once the share has landed. 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;

package/dist/e2b/sandbox.js

@@ -128,6 +128,8 @@ function unsupported(feature, alternative) {
 }
 /** A sandbox, with E2B's methods. `sandbox.runtime` is the Runtime sandbox
  * underneath, for anything E2B has no name for. */
+/** Where Runtime serves previews; getHost names a host under it. */
+const PREVIEW_DOMAIN = "runtimehost.com";
 export class Sandbox {
     static defaultTemplate = "base";
     files;
@@ -136,6 +138,8 @@ export class Sandbox {
     #runtime;
     #envs;
     #home;
+    /** Ports shared as public previews, by port: the one share each asked for. */
+    #shares = new Map();
     /** Use Sandbox.create or Sandbox.connect. */
     constructor(runtime, client, envs = {}) {
         this.#runtime = runtime;
@@ -332,17 +336,37 @@ export class Sandbox {
         }
     }
     // ---- ports ------------------------------------------------------------
-    /** Refused: E2B answers getHost without a call, and a Runtime port becomes
-     * reachable only once it is shared. Use getPublicHost. */
+    /** E2B's getHost, answered at once as E2B answers it:
+     * `<port>-<id>.runtimehost.com`. A Runtime preview's address is made from
+     * the sandbox and the port alone, so it is known without a call; the port
+     * is shared publicly the first time it is asked for, in about a tenth of a
+     * second, beside the caller. A request that lands before the share may be
+     * answered 404 for up to two seconds; `await getPublicHost(port)` returns
+     * once the share has landed. */
     getHost(port) {
-        throw new NotSupportedError(`sandbox.getHost(${port}), which answers without asking the server`, `Use \`await sandbox.getPublicHost(${port})\`: it shares the port at a public HTTPS address and returns its host, as getHost does.`);
+        if (!Number.isInteger(port) || port < 1 || port > 65_535)
+            throw new InvalidArgumentError(`port must be a whole number from 1 to 65535, not ${port}.`);
+        void this.#share(port).catch((error) => {
+            if (typeof process !== "undefined" && process.emitWarning)
+                process.emitWarning(`Sharing port ${port} for getHost failed: ${error instanceof Error ? error.message : String(error)}. getPublicHost(${port}) says why.`, { code: "RUNTIME_E2B_GET_HOST" });
+        });
+        return `${port}-${this.sandboxId.replaceAll("-", "").toLowerCase()}.${PREVIEW_DOMAIN}`;
     }
     /** 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. */
+     * its host, `<port>-<id>.<domain>`, once the share has landed. Anyone with
+     * the address can reach it; a browser sees a one-time page naming Runtime. */
     async getPublicHost(port) {
-        const preview = await guard("sandbox", () => this.#runtime.previews.create(port, { visibility: "public" }));
-        return new URL(preview.url).host;
+        return this.#share(port);
+    }
+    #share(port) {
+        let share = this.#shares.get(port);
+        if (!share) {
+            share = guard("sandbox", () => this.#runtime.previews.create(port, { visibility: "public" })).then((preview) => new URL(preview.url).host);
+            // A failed share is asked again next time, not remembered.
+            share.catch(() => this.#shares.delete(port));
+            this.#shares.set(port, share);
+        }
+        return share;
     }
     // ---- what Runtime does differently -----------------------------------
     get pty() {

package/dist/errors.d.ts

@@ -45,6 +45,11 @@ export declare class RateLimitError extends RuntimeError {
 }
 export declare class ServiceUnavailableError extends RuntimeError {
 }
+/** The account may not spend: a payment on it is disputed or under review
+ * (`account_blocked`, 402). The message says which and what clears it; a
+ * retry cannot, and adding credit alone may not. */
+export declare class AccountBlockedError extends RuntimeError {
+}
 /** No answer arrived. A write may or may not have happened; retrying with the
  * same idempotencyKey (the SDK does, automatically) settles it safely. */
 export declare class ConnectionError extends RuntimeError {

package/dist/errors.js

@@ -74,6 +74,11 @@ export class RateLimitError extends RuntimeError {
 }
 export class ServiceUnavailableError extends RuntimeError {
 }
+/** The account may not spend: a payment on it is disputed or under review
+ * (`account_blocked`, 402). The message says which and what clears it; a
+ * retry cannot, and adding credit alone may not. */
+export class AccountBlockedError extends RuntimeError {
+}
 /** No answer arrived. A write may or may not have happened; retrying with the
  * same idempotencyKey (the SDK does, automatically) settles it safely. */
 export class ConnectionError extends RuntimeError {
@@ -110,6 +115,8 @@ export function errorFor(status, body, idempotencyKey) {
         ...(typeof error.retryAfterMs === "number" ? { retryAfterMs: error.retryAfterMs } : {}),
         ...(idempotencyKey ? { idempotencyKey } : {}),
     };
+    if (init.code === "account_blocked")
+        return new AccountBlockedError(init);
     if (status === 401)
         return new AuthenticationError(init);
     if (status === 403)

package/dist/index.d.ts

@@ -5,22 +5,22 @@
  *   console.log((await sbx.exec("echo hello")).stdout);
  */
 import type { Runtime } from "./client.js";
-import { type RuntimeOptions } from "./client.js";
+import { type CreateOptions, type RuntimeOptions } from "./client.js";
 import { Sandbox as SandboxClass } from "./sandbox.js";
 import type { CreateSandbox, KeepAliveOptions } from "./types.js";
 import type { RequestOptions } from "./transport.js";
-export { Runtime, Sandboxes, FeedbackApi, SupportApi, type RuntimeOptions, type SupportReply, } from "./client.js";
+export { Runtime, Sandboxes, FeedbackApi, SupportApi, type CreateOptions, type RuntimeOptions, type SupportReply, } from "./client.js";
 export { Files, Process, Processes, Terminal } from "./sandbox.js";
 export { Tunnel, TunnelStream, type PortForward } from "./tunnel.js";
 export { Page } from "./page.js";
 export type { KeyLimits } from "./products/limits.js";
 export type { AuditEvent, AuditPage } from "./products/audit.js";
-export type { Secret, SetSecret } from "./products/secrets.js";
+export type { Secret, SecretRule, SetSecret } from "./products/secrets.js";
 export type { McpCatalogEntry, McpGateway, McpServerRequest } from "./products/mcp.js";
 export type { FileEvent, FileEventType, WatchHandle, WatchNotice, WatchOptions, } from "./products/watch.js";
 export type { Mount, MountBucket } from "./products/mounts.js";
 export type { Volume, VolumeBackup, CreateVolume } from "./products/volumes.js";
-export type { CheckedDomain, DnsRecord, Domain, EgressAddress, TcpPort, Tunnel as PrivateTunnel, TunnelPeer, TunnelPeerCreated, } from "./products/network-products.js";
+export type { CheckedDomain, DnsRecord, Domain, EgressAddress, TcpPort, Tunnel as PrivateTunnel, TunnelPeer, TunnelPeerCreated, SetUpstreamProxy, UpstreamProxy, } from "./products/network-products.js";
 export { verifyWebhook, WebhookVerificationError, type MetricPoint, type MetricRange, type OtelExport, type RuntimeEvent, type SandboxMetrics, type Webhook, type WebhookDelivery, type WebhookEventType, } from "./products/observability.js";
 export { Snapshots, type Snapshot, type SnapshotOptions } from "./snapshots.js";
 export { Transport, VERSION, apiOrigin, type RequestOptions, type Call } from "./transport.js";
@@ -35,7 +35,7 @@ export declare class Sandbox extends SandboxClass {
     static create(input?: CreateSandbox & {
         wait?: boolean;
         keepAlive?: boolean | KeepAliveOptions;
-    }, options?: RequestOptions & {
+    }, options?: CreateOptions & {
         client?: Runtime;
     }): Promise<SandboxClass>;
     /** The sandbox named `name` in this account, ready to use: running as it
@@ -45,7 +45,7 @@ export declare class Sandbox extends SandboxClass {
     static getOrCreate(name: string, input?: Omit<CreateSandbox, "name" | "getOrCreate"> & {
         wait?: boolean;
         keepAlive?: boolean | KeepAliveOptions;
-    }, options?: RequestOptions & {
+    }, options?: CreateOptions & {
         client?: Runtime;
     }): Promise<SandboxClass>;
     /** Reconnects to an existing sandbox by id. */
@@ -65,4 +65,6 @@ export declare class Sandbox extends SandboxClass {
 }
 export type { RuntimeOptions as ClientOptions };
 export { identityToken, type IdentityToken } from "./identity.js";
+export { openWalletAccount, claimWalletAccount, type OpenedWalletAccount, type WalletClaim, type WalletOptions, } from "./wallet.js";
+export type { Topup } from "./products/billing.js";
 export type { SsoConnection, SsoStatus } from "./products/sso.js";

package/dist/index.js

@@ -45,3 +45,4 @@ export class Sandbox extends SandboxClass {
     }
 }
 export { identityToken } from "./identity.js";
+export { openWalletAccount, claimWalletAccount, } from "./wallet.js";

package/dist/keys.js

@@ -4,7 +4,7 @@ import { hostname } from "node:os";
 import { promisify } from "node:util";
 import { connectionOrigins } from "./credentials.js";
 import { RuntimeError } from "./errors.js";
-import { named } from "./login.js";
+import { named } from "./cli-name.js";
 import { describeRoute, envFetch } from "./proxy.js";
 const KEY = /^rtcloud_([a-f0-9-]{36})_[A-Za-z0-9_-]{43}$/;
 /** How often to ask whether the owner has answered. The website answers

package/dist/login.d.ts

@@ -1,8 +1,5 @@
-/** How this CLI was started, so what it tells you to type works: through npx
- * the command is `npx withruntime`, installed it is `runtime`. */
-export declare const me: string;
-/** Text that names a command, with the command spelled the way it was run. */
-export declare function named(text: string, name?: string): string;
+import { me, named } from "./cli-name.js";
+export { me, named };
 type LoginOptions = {
     readKey?: () => Promise<string>;
     fetch?: typeof fetch;
@@ -116,4 +113,3 @@ export type PendingLogin = {
  * waiting: `runtime login` waits on it, and the MCP bridge gives the link to
  * the agent, which shows it to the person it works for. */
 export declare function beginDeviceLogin(env: NodeJS.ProcessEnv, agentName: string, options?: LoginOptions): Promise<PendingLogin>;
-export {};

package/dist/login.js

@@ -2,7 +2,8 @@ import { execFile } from "node:child_process";
 import { generateKeyPair, privateDecrypt } from "node:crypto";
 import { hostname } from "node:os";
 import { promisify } from "node:util";
-import { Runtime } from "./index.js";
+import { me, named } from "./cli-name.js";
+import { Runtime } from "./client.js";
 import { connectionOrigins, connectionStore } from "./credentials.js";
 import { describeRoute, envFetch } from "./proxy.js";
 class ConnectionError extends Error {
@@ -12,13 +13,7 @@ class ConnectionError extends Error {
         this.status = status;
     }
 }
-/** How this CLI was started, so what it tells you to type works: through npx
- * the command is `npx withruntime`, installed it is `runtime`. */
-export const me = /[\\/]_npx[\\/]/.test(process.argv[1] ?? "") ? "npx withruntime" : "runtime";
-/** Text that names a command, with the command spelled the way it was run. */
-export function named(text, name = me) {
-    return name === "runtime" ? text : text.replace(/(^|[\s`(])runtime(?= [a-z<[])/g, `$1${name}`);
-}
+export { me, named };
 /** The connection id recorded for a key pasted with `login --with-key`. */
 const PASTED = "pasted";
 /** A key from standard input: piped, or typed at a prompt that does not echo. */

package/dist/network-cli.d.ts

@@ -8,7 +8,7 @@ type Args = {
     positional: string[];
     flags: Map<string, string[]>;
 };
-export declare const NETWORK_PRODUCTS: readonly ["domain", "port", "address", "tunnel"];
+export declare const NETWORK_PRODUCTS: readonly ["domain", "port", "address", "tunnel", "network"];
 export type NetworkProduct = (typeof NETWORK_PRODUCTS)[number];
 export declare const NETWORK_HELP: Record<NetworkProduct, string>;
 export declare function networkProductCommand(product: NetworkProduct, argv: string[], args: Args, out: Out, client: () => Promise<Runtime>): Promise<number>;

package/dist/network-cli.js

@@ -1,6 +1,6 @@
 import { chmod, writeFile } from "node:fs/promises";
 import { RuntimeError } from "./errors.js";
-import { named } from "./login.js";
+import { named } from "./cli-name.js";
 import { generateWireGuardKeyPair } from "./wireguard.js";
 function fundingState(value) {
     if (value.funded === false)
@@ -11,7 +11,7 @@ function fundingState(value) {
         ? `Funded until ${value.fundedUntil}.`
         : "Funding active; no deadline reported.";
 }
-export const NETWORK_PRODUCTS = ["domain", "port", "address", "tunnel"];
+export const NETWORK_PRODUCTS = ["domain", "port", "address", "tunnel", "network"];
 export const NETWORK_HELP = {
     domain: `runtime domain <command>
 
@@ -54,6 +54,19 @@ export const NETWORK_HELP = {
                                          A new key; the old one stops working within seconds
   peer rm <peerId>                       Remove it; its tunnel ends within seconds
   --route: your own ranges behind the peer that sandboxes may reach. Paid accounts only.
+`,
+    network: `runtime network <command>
+
+  upstream-proxy set <http://host:port|https://host:port> [--secret NAME] [--host <host>]...
+                                         Send your sandboxes' outbound connections through your
+                                         own proxy, after Runtime's own rules allow them.
+                                         --secret: one of your secrets, sent as Proxy-Authorization
+                                         (its hosts must name the proxy's host). --host: only
+                                         these destinations (or *.domain) go through it
+  upstream-proxy get                     The proxy in use
+  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.
 `,
 };
 function usage(product, message) {
@@ -319,5 +332,54 @@ export async function networkProductCommand(product, argv, args, out, client) {
             }
         }
     }
+    if (product === "network") {
+        if (verb !== "upstream-proxy")
+            throw usage(product, `Unknown network command ${verb}.`);
+        const upstream = runtime.network.upstreamProxy;
+        const describe = (proxy) => [
+            `Outbound connections${proxy.hosts?.length ? ` to ${proxy.hosts.join(", ")}` : ""} go through ${proxy.url}.`,
+            ...(proxy.secret ? [`${proxy.secret} is sent as Proxy-Authorization.`] : []),
+        ].join("\n");
+        switch (rest[0]) {
+            case "set": {
+                const hosts = args.flags.get("host");
+                const secret = flag("secret");
+                const saved = await upstream.set({
+                    url: need(rest[1], "the proxy's url, such as http://proxy.example.com:3128"),
+                    ...(secret ? { secret } : {}),
+                    ...(hosts ? { hosts } : {}),
+                });
+                print([
+                    describe(saved),
+                    saved.enforced
+                        ? "A connection your proxy refuses fails; nothing goes around it."
+                        : "A host is catching up; running sandboxes use it within a minute.",
+                ].join("\n"), saved);
+                return 0;
+            }
+            case "get":
+            case undefined: {
+                let found;
+                try {
+                    found = await upstream.get();
+                }
+                catch (error) {
+                    if (!(error instanceof RuntimeError) || error.code !== "not_found")
+                        throw error;
+                    print(named("No upstream proxy. Set one: runtime network upstream-proxy set http://proxy.example.com:3128"), null);
+                    return 0;
+                }
+                print(describe(found), found);
+                return 0;
+            }
+            case "remove":
+            case "rm": {
+                const gone = await upstream.remove();
+                print("Connections leave directly again.", gone);
+                return 0;
+            }
+        }
+        throw usage(product, "upstream-proxy takes set, get or remove.");
+    }
     throw usage(product, `Unknown ${product} command ${verb}.`);
 }