withruntime 0.5.1 → 0.6.0

package/dist/e2b/filesystem.d.ts

@@ -21,6 +21,26 @@ export interface EntryInfo extends WriteInfo {
     modifiedTime?: Date;
     symlinkTarget?: string;
 }
+export declare enum FilesystemEventType {
+    CHMOD = "chmod",
+    CREATE = "create",
+    REMOVE = "remove",
+    RENAME = "rename",
+    WRITE = "write"
+}
+export interface FilesystemEvent {
+    /** Relative to the watched directory. */
+    name: string;
+    type: FilesystemEventType;
+}
+export interface WatchOpts extends FilesystemRequestOpts {
+    /** How long the watch runs; 0 is Runtime's maximum, 24 hours. Default 60000. */
+    timeoutMs?: number;
+    recursive?: boolean;
+}
+export interface E2BWatchHandle {
+    stop(): Promise<void>;
+}
 export type WriteEntry = {
     path: string;
     data: string | ArrayBuffer | Blob | ReadableStream;
@@ -78,5 +98,10 @@ export declare class Filesystem {
     remove(path: string, opts?: FilesystemRequestOpts): Promise<void>;
     exists(path: string, opts?: FilesystemRequestOpts): Promise<boolean>;
     getInfo(path: string, opts?: FilesystemRequestOpts): Promise<EntryInfo>;
-    watchDir(): Promise<never>;
+    /** E2B's watchDir on Runtime's file watch: the same events (CREATE, WRITE,
+     * REMOVE, RENAME, CHMOD) with names relative to the directory, stopped
+     * with `handle.stop()`. `timeoutMs` 0 is Runtime's 24-hour maximum. */
+    watchDir(path: string, onEvent: (event: FilesystemEvent) => void | Promise<void>, opts?: WatchOpts & {
+        onExit?: (err?: Error) => void | Promise<void>;
+    }): Promise<E2BWatchHandle>;
 }

package/dist/e2b/filesystem.js

@@ -6,6 +6,14 @@ export var FileType;
     FileType["DIR"] = "dir";
     FileType["SYMLINK"] = "symlink";
 })(FileType || (FileType = {}));
+export var FilesystemEventType;
+(function (FilesystemEventType) {
+    FilesystemEventType["CHMOD"] = "chmod";
+    FilesystemEventType["CREATE"] = "create";
+    FilesystemEventType["REMOVE"] = "remove";
+    FilesystemEventType["RENAME"] = "rename";
+    FilesystemEventType["WRITE"] = "write";
+})(FilesystemEventType || (FilesystemEventType = {}));
 /** Runtime's home, where E2B's relative paths land. */
 const HOME = "/workspace";
 function absolute(path) {
@@ -137,7 +145,27 @@ export class Filesystem {
             throw new FileNotFoundError(`${target} does not exist.`);
         return entryInfo(stat);
     }
-    watchDir() {
-        return Promise.reject(new NotSupportedError("Watching a directory (files.watchDir)", "Poll with files.list(path), or run your own watcher with commands.run(..., { background: true })."));
+    /** E2B's watchDir on Runtime's file watch: the same events (CREATE, WRITE,
+     * REMOVE, RENAME, CHMOD) with names relative to the directory, stopped
+     * with `handle.stop()`. `timeoutMs` 0 is Runtime's 24-hour maximum. */
+    async watchDir(path, onEvent, opts = {}) {
+        const target = await this.#path(path, opts);
+        const prefix = target.endsWith("/") ? target : `${target}/`;
+        const lifetime = opts.timeoutMs === 0 ? 86_400_000 : (opts.timeoutMs ?? 60_000);
+        const watch = await guard("file", () => this.#files.watch(target, (event) => onEvent({
+            name: event.path.startsWith(prefix) ? event.path.slice(prefix.length) : event.path,
+            type: event.type,
+        }), {
+            recursive: opts.recursive === true,
+            timeoutMs: Math.max(1_000, Math.min(86_400_000, lifetime)),
+            onExit: (reason) => {
+                if (reason === "stopped")
+                    return;
+                void opts.onExit?.(reason === "timeout" || reason === "paused"
+                    ? undefined
+                    : new Error(`The watch ended: ${reason}`));
+            },
+        }));
+        return { stop: () => watch.stop() };
     }
 }

package/dist/e2b/index.d.ts

@@ -9,7 +9,7 @@ import { type ConnectionOpts } from "./client.js";
 import { Sandbox } from "./sandbox.js";
 export { Sandbox, SandboxPaginator, DEFAULT_SHAPE, DEFAULT_TIMEOUT_MS, type SandboxOpts, type SandboxConnectOpts, type SandboxApiOpts, type SandboxInfo, type SandboxListOpts, type SandboxState, type SandboxLifecycle, type SandboxOnTimeout, type SnapshotInfo, } from "./sandbox.js";
 export { Commands, CommandHandle, pidOf, type CommandStartOpts, type CommandConnectOpts, type CommandRequestOpts, type ProcessInfo, type Username, } from "./commands.js";
-export { Filesystem, FileType, type EntryInfo, type WriteInfo, type WriteEntry, type FilesystemRequestOpts, type FilesystemReadOpts, type FilesystemWriteOpts, type FilesystemListOpts, } from "./filesystem.js";
+export { Filesystem, FileType, type EntryInfo, type WriteInfo, type WriteEntry, type FilesystemRequestOpts, type FilesystemReadOpts, type FilesystemWriteOpts, type FilesystemListOpts, FilesystemEventType, type FilesystemEvent, type WatchOpts, type E2BWatchHandle as WatchHandle, } from "./filesystem.js";
 export { SandboxError, TimeoutError, InvalidArgumentError, NotEnoughSpaceError, NotFoundError, FileNotFoundError, SandboxNotFoundError, TemplateError, RateLimitError, AuthenticationError, ServiceBusyError, CommandExitError, NotSupportedError, type CommandResult, } from "./errors.js";
 export type { ConnectionOpts, RuntimeOpts } from "./client.js";
 export { Template, TemplateBase, Volume, Secret, waitForPort, waitForURL, waitForProcess, waitForFile, waitForTimeout, } from "./unsupported.js";

package/dist/e2b/index.js

@@ -2,7 +2,7 @@ import { clientFor } from "./client.js";
 import { Sandbox } from "./sandbox.js";
 export { Sandbox, SandboxPaginator, DEFAULT_SHAPE, DEFAULT_TIMEOUT_MS, } from "./sandbox.js";
 export { Commands, CommandHandle, pidOf, } from "./commands.js";
-export { Filesystem, FileType, } from "./filesystem.js";
+export { Filesystem, FileType, FilesystemEventType, } from "./filesystem.js";
 export { SandboxError, TimeoutError, InvalidArgumentError, NotEnoughSpaceError, NotFoundError, FileNotFoundError, SandboxNotFoundError, TemplateError, RateLimitError, AuthenticationError, ServiceBusyError, CommandExitError, NotSupportedError, } from "./errors.js";
 export { Template, TemplateBase, Volume, Secret, waitForPort, waitForURL, waitForProcess, waitForFile, waitForTimeout, } from "./unsupported.js";
 export default Sandbox;

package/dist/errors.js

@@ -15,6 +15,8 @@ export const WAITS_FOR_ROOM = new Set([
     "trial_capacity",
     "quota_exceeded",
     "no_capacity",
+    // A volume whose last sandbox is stopping: free within seconds.
+    "volume_releasing",
 ]);
 export class RuntimeError extends Error {
     code;

package/dist/identity.d.ts

@@ -0,0 +1,27 @@
+/** An identity token, as the API returns it. */
+export type IdentityToken = {
+    /** The OIDC ID token (a JWT), signed by Runtime. */
+    token: string;
+    expiresAt: string;
+    /** https://withruntime.com/oidc */
+    issuer: string;
+    /** org:<org>:image:<image>:sandbox:<sandbox> */
+    subject: string;
+    audience: string;
+};
+/**
+ * Inside a Runtime sandbox: a short-lived OIDC token, signed by Runtime,
+ * naming this sandbox, its organization and its image, for `audience`. Trade
+ * it for cloud credentials without storing a key: AWS
+ * AssumeRoleWithWebIdentity (audience `sts.amazonaws.com`), Google Cloud
+ * workload identity federation, Azure federated credentials, or your own API.
+ * Needs no API key. Lives ten minutes unless asked (60 to 3600 seconds).
+ *
+ *   import { Sandbox } from "withruntime";
+ *   const { token } = await Sandbox.identityToken({ audience: "sts.amazonaws.com" });
+ */
+export declare function identityToken(input: {
+    audience: string;
+    lifetimeSeconds?: number;
+    signal?: AbortSignal;
+}): Promise<IdentityToken>;

package/dist/identity.js

@@ -0,0 +1,56 @@
+import { RuntimeError } from "./errors.js";
+async function requestCredentials() {
+    let url = process.env.RUNTIME_ID_TOKEN_REQUEST_URL;
+    let token = process.env.RUNTIME_ID_TOKEN_REQUEST_TOKEN;
+    if (!url || !token) {
+        // A process started before the guest wrote its environment still finds it.
+        try {
+            // Loaded here, so the SDK still loads where there is no file system.
+            const { readFile } = await import("node:fs/promises");
+            const env = JSON.parse(await readFile("/run/runtime/environment.json", "utf8"));
+            url = env.RUNTIME_ID_TOKEN_REQUEST_URL;
+            token = env.RUNTIME_ID_TOKEN_REQUEST_TOKEN;
+        }
+        catch {
+            return null;
+        }
+    }
+    return url && token ? { url, token } : null;
+}
+/**
+ * Inside a Runtime sandbox: a short-lived OIDC token, signed by Runtime,
+ * naming this sandbox, its organization and its image, for `audience`. Trade
+ * it for cloud credentials without storing a key: AWS
+ * AssumeRoleWithWebIdentity (audience `sts.amazonaws.com`), Google Cloud
+ * workload identity federation, Azure federated credentials, or your own API.
+ * Needs no API key. Lives ten minutes unless asked (60 to 3600 seconds).
+ *
+ *   import { Sandbox } from "withruntime";
+ *   const { token } = await Sandbox.identityToken({ audience: "sts.amazonaws.com" });
+ */
+export async function identityToken(input) {
+    const found = await requestCredentials();
+    if (!found)
+        throw new RuntimeError({
+            code: "identity_unavailable",
+            status: 0,
+            message: "Identity tokens are issued only inside a Runtime sandbox (RUNTIME_ID_TOKEN_REQUEST_TOKEN is not set).",
+        });
+    const url = new URL(found.url);
+    url.searchParams.set("audience", input.audience);
+    if (input.lifetimeSeconds !== undefined)
+        url.searchParams.set("lifetimeSeconds", String(input.lifetimeSeconds));
+    const response = await fetch(url, {
+        headers: { authorization: `Bearer ${found.token}` },
+        signal: input.signal ?? AbortSignal.timeout(10_000),
+    });
+    const body = (await response.json().catch(() => ({})));
+    if (!response.ok || !body.token)
+        throw new RuntimeError({
+            code: body.error?.code ?? "identity_refused",
+            status: response.status,
+            message: body.error?.message ?? `Could not get an identity token (HTTP ${response.status}).`,
+            ...(body.error?.requestId ? { requestId: body.error.requestId } : {}),
+        });
+    return body;
+}

package/dist/index.d.ts

@@ -16,6 +16,11 @@ 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 { 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 { 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";
@@ -50,5 +55,14 @@ export declare class Sandbox extends SandboxClass {
     static list(filter?: Parameters<Runtime["sandboxes"]["list"]>[0], options?: {
         client?: Runtime;
     }): Promise<import("./page.js").Page<SandboxClass>>;
+    /** Inside a sandbox: an OIDC token naming this sandbox, for `audience`
+     * (AWS: "sts.amazonaws.com"). No API key needed. See `identityToken`. */
+    static identityToken(input: {
+        audience: string;
+        lifetimeSeconds?: number;
+        signal?: AbortSignal;
+    }): Promise<import("./identity.js").IdentityToken>;
 }
 export type { RuntimeOptions as ClientOptions };
+export { identityToken, type IdentityToken } from "./identity.js";
+export type { SsoConnection, SsoStatus } from "./products/sso.js";

package/dist/index.js

@@ -1,5 +1,6 @@
 import { defaultClient } from "./client.js";
 import { Sandbox as SandboxClass } from "./sandbox.js";
+import { identityToken } from "./identity.js";
 export { Runtime, Sandboxes, FeedbackApi, SupportApi, } from "./client.js";
 export { Files, Process, Processes, Terminal } from "./sandbox.js";
 export { Tunnel, TunnelStream } from "./tunnel.js";
@@ -37,4 +38,10 @@ export class Sandbox extends SandboxClass {
     static list(filter = {}, options = {}) {
         return (options.client ?? defaultClient()).sandboxes.list(filter);
     }
+    /** Inside a sandbox: an OIDC token naming this sandbox, for `audience`
+     * (AWS: "sts.amazonaws.com"). No API key needed. See `identityToken`. */
+    static identityToken(input) {
+        return identityToken(input);
+    }
 }
+export { identityToken } from "./identity.js";

package/dist/mcp.js

@@ -158,7 +158,7 @@ export async function serveMcp(env = process.env, options = {}) {
                     }));
                     await post(JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }));
                     write({ jsonrpc: "2.0", method: "notifications/tools/list_changed" });
-                    return text(`Connected as ${outcome.agentName}. Runtime's tools are available now: list the tools again, then start with runtime_sandboxes_create.`);
+                    return text(`Connected as ${outcome.agentName}. Runtime's tools are available now: list the tools again, then start with runtime_sandbox_create.`);
                 }
                 await new Promise((resolve) => setTimeout(resolve, 3000));
             }
@@ -208,9 +208,22 @@ export async function serveMcp(env = process.env, options = {}) {
             }
         });
         const finish = () => void Promise.allSettled([...inFlight]).then(() => resolve());
+        /* A signal ends the bridge at once: stop reading, give a reply already on
+           its way half a second to be written, and return. The client that sent
+           it has stopped listening; waiting on a long tool call, or on stdin it
+           left open, only makes it wait for us or kill us. */
+        const stop = () => {
+            process.stdin.removeAllListeners("data");
+            process.stdin.pause();
+            process.stdin.destroy();
+            void Promise.race([
+                Promise.allSettled([...inFlight]),
+                new Promise((settle) => setTimeout(settle, 500)),
+            ]).then(() => resolve());
+        };
         process.stdin.once("end", finish);
-        process.once("SIGINT", finish);
-        process.once("SIGTERM", finish);
+        process.once("SIGINT", stop);
+        process.once("SIGTERM", stop);
     });
 }
 async function openBrowser(url) {

package/dist/network-cli.d.ts

@@ -0,0 +1,15 @@
+import type { Runtime } from "./client.js";
+type Out = {
+    json: boolean;
+    write: (text: string) => void;
+    error: (text: string) => void;
+};
+type Args = {
+    positional: string[];
+    flags: Map<string, string[]>;
+};
+export declare const NETWORK_PRODUCTS: readonly ["domain", "port", "address", "tunnel"];
+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>;
+export {};

package/dist/network-cli.js

@@ -0,0 +1,323 @@
+import { chmod, writeFile } from "node:fs/promises";
+import { RuntimeError } from "./errors.js";
+import { named } from "./login.js";
+import { generateWireGuardKeyPair } from "./wireguard.js";
+function fundingState(value) {
+    if (value.funded === false)
+        return "Traffic disabled. Check balance, spending limits and account permissions. Reservation kept until you release it.";
+    if (value.funded !== true)
+        return "Funding status unavailable.";
+    return value.fundedUntil
+        ? `Funded until ${value.fundedUntil}.`
+        : "Funding active; no deadline reported.";
+}
+export const NETWORK_PRODUCTS = ["domain", "port", "address", "tunnel"];
+export const NETWORK_HELP = {
+    domain: `runtime domain <command>
+
+  add <hostname> <sandbox> <port>        Serve a sandbox's port at your own hostname, with HTTPS
+                                         Prints the DNS records to set: a TXT that proves the
+                                         name is yours, and a CNAME (an A for an apex name)
+  verify <hostname>                      Check the TXT record now; the name goes live when it matches
+  ls                                     Your domains
+  get <hostname>                         One domain and its DNS records
+  rm <hostname>                          Stop serving it
+  Paid accounts only. The first visit gets the certificate, in a few seconds.
+`,
+    port: `runtime port <command>
+
+  open <sandbox> <port>                  A public TCP port to a port in the sandbox: Postgres,
+                                         Redis, a game server, anything that is not HTTP
+                                         Prints address:port for your client
+  ls [--sandbox <id>]                    Your open ports
+  close <portId>                         Close one; open connections end within seconds
+  Paid accounts only. TCP, carried as it is: use your service's own password and TLS.
+`,
+    address: `runtime address <command>
+
+  reserve [--ipv6]                       A dedicated outbound address: every sandbox of your
+                                         account sends from it, for allow-lists
+  ls                                     Your addresses
+  release <addressId>                    Give it back; sandboxes use the shared addresses again
+  Paid accounts only.
+`,
+    tunnel: `runtime tunnel <command>
+
+  create [--subnet 10.250.0.0/16]        A WireGuard tunnel from your network into your sandboxes
+  get                                    The tunnel, its peers, and each sandbox's address in it
+  rm                                     Delete the tunnel and every peer
+  peer add <name> [--route 10.0.0.0/16]... [--out runtime.conf] [--public-key <key>]
+                                         Add a machine or router of yours; writes its wg-quick
+                                         file. The key pair is made here and the private key
+                                         never leaves this machine. Then: sudo wg-quick up ./runtime.conf
+  peer rotate <peerId> [--out runtime.conf]
+                                         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.
+`,
+};
+function usage(product, message) {
+    return new RuntimeError({
+        message,
+        code: "usage",
+        status: 0,
+        hint: `Run \`${named("runtime")} ${product} help\`.`,
+    });
+}
+function table(rows) {
+    const widths = rows[0].map((_, column) => Math.max(...rows.map((row) => (row[column] ?? "").length)));
+    return rows
+        .map((row) => row
+        .map((cell, column) => cell.padEnd(widths[column]))
+        .join("  ")
+        .trimEnd())
+        .join("\n");
+}
+function portNumber(product, text) {
+    const value = Number(text);
+    if (!text || !/^\d+$/.test(text) || value < 1 || value > 65_535)
+        throw usage(product, "Give a port from 1 to 65535.");
+    return value;
+}
+/** Writes a wg-quick file readable by its owner alone, or prints it. */
+async function deliver(out, config, path, hint, ready = true) {
+    if (!config) {
+        out.error(hint);
+        return;
+    }
+    if (path) {
+        await writeFile(path, config, { mode: 0o600 });
+        await chmod(path, 0o600);
+        out.error(ready
+            ? `Wrote ${path}. Bring it up with: sudo wg-quick up ${path.startsWith("/") ? path : `./${path}`}`
+            : `Wrote ${path}. ${hint}`);
+    }
+    else
+        out.write(config);
+}
+export async function networkProductCommand(product, argv, args, out, client) {
+    const [verb] = argv;
+    const flag = (name) => args.flags.get(name)?.at(-1);
+    const has = (name) => flag(name) === "true";
+    const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
+    const rest = args.positional.slice(1);
+    const need = (value, what) => {
+        if (!value)
+            throw usage(product, `Give ${what}.`);
+        return value;
+    };
+    if (!verb || verb === "help" || verb === "--help") {
+        print(named(NETWORK_HELP[product]), { usage: named(NETWORK_HELP[product]) });
+        return 0;
+    }
+    const runtime = await client();
+    if (product === "domain") {
+        const records = (domain) => table([
+            ["TYPE", "NAME", "VALUE"],
+            ...domain.records.map((record) => [record.type, record.name, record.value]),
+        ]);
+        switch (verb) {
+            case "add": {
+                const found = await runtime.domains.add({
+                    hostname: need(rest[0], "a hostname, such as app.example.com"),
+                    sandboxId: need(rest[1], "a sandbox id"),
+                    port: portNumber(product, rest[2]),
+                });
+                print(`${found.hostname}: ${found.state}\n\n${records(found)}\n\n${found.hint}`, found);
+                return 0;
+            }
+            case "verify": {
+                const found = await runtime.domains.verify(need(rest[0], "a hostname"));
+                print(`${found.hostname}: ${found.state}. ${found.hint}${found.checkError ? `\n${found.checkError}` : ""}`, found);
+                return found.state === "active" ? 0 : 1;
+            }
+            case "ls":
+            case "list": {
+                const all = await runtime.domains.list();
+                print(all.length
+                    ? table([
+                        ["HOSTNAME", "STATE", "SANDBOX", "PORT"],
+                        ...all.map((d) => [
+                            d.hostname,
+                            d.disabled ? "taken down" : d.state,
+                            d.sandboxId,
+                            String(d.port),
+                        ]),
+                    ])
+                    : named("No domains. Add one: runtime domain add app.example.com <sandbox> 3000"), all);
+                return 0;
+            }
+            case "get": {
+                const found = await runtime.domains.get(need(rest[0], "a hostname"));
+                print(`${found.hostname}: ${found.state}\n\n${records(found)}`, found);
+                return 0;
+            }
+            case "rm":
+            case "remove": {
+                const gone = await runtime.domains.remove(need(rest[0], "a hostname"));
+                print(`${gone.hostname} is no longer served. Remove its DNS records too.`, gone);
+                return 0;
+            }
+        }
+    }
+    if (product === "port") {
+        switch (verb) {
+            case "open": {
+                const opened = await runtime.ports.open({
+                    sandboxId: need(rest[0], "a sandbox id"),
+                    port: portNumber(product, rest[1]),
+                });
+                if (!out.json)
+                    out.error(opened.hint);
+                print(opened.connect, opened);
+                return 0;
+            }
+            case "ls":
+            case "list": {
+                const sandboxId = flag("sandbox");
+                const all = await runtime.ports.list(sandboxId ? { sandboxId } : {});
+                print(all.length
+                    ? table([
+                        ["ID", "CONNECT", "SANDBOX", "PORT"],
+                        ...all.map((p) => [p.id, p.connect, p.sandboxId, String(p.port)]),
+                    ])
+                    : named("No open ports. Open one: runtime port open <sandbox> 5432"), all);
+                return 0;
+            }
+            case "close":
+            case "rm": {
+                const gone = await runtime.ports.close(need(rest[0], "a port id"));
+                print(`Closed ${gone.id}.`, gone);
+                return 0;
+            }
+        }
+    }
+    if (product === "address") {
+        switch (verb) {
+            case "reserve": {
+                const reserved = await runtime.addresses.reserve({ family: has("ipv6") ? 6 : 4 });
+                if (!out.json)
+                    out.error(reserved.funded === true
+                        ? `Every sandbox of this account sends from it. ${fundingState(reserved)}`
+                        : fundingState(reserved));
+                print(reserved.address, reserved);
+                return 0;
+            }
+            case "ls":
+            case "list": {
+                const all = await runtime.addresses.list();
+                print(all.length
+                    ? table([
+                        ["ID", "ADDRESS", "FAMILY", "FUNDING"],
+                        ...all.map((a) => [a.id, a.address, `IPv${a.family}`, fundingState(a)]),
+                    ])
+                    : named("No dedicated address. Reserve one: runtime address reserve"), all);
+                return 0;
+            }
+            case "release":
+            case "rm": {
+                const gone = await runtime.addresses.release(need(rest[0], "an address id"));
+                print(`Released ${gone.address}.`, gone);
+                return 0;
+            }
+        }
+    }
+    if (product === "tunnel") {
+        const view = (tunnel) => [
+            fundingState(tunnel),
+            `Endpoint ${tunnel.endpoint}, subnet ${tunnel.subnet}, gateway key ${tunnel.gatewayPublicKey ?? "(starting)"}`,
+            "",
+            tunnel.peers.length
+                ? table([
+                    ["PEER", "NAME", "ADDRESS", "ROUTES"],
+                    ...tunnel.peers.map((p) => [p.id, p.name, p.address, p.routes.join(",") || "-"]),
+                ])
+                : named("No peers. Add one: runtime tunnel peer add office --route 10.0.0.0/16"),
+            "",
+            tunnel.sandboxes.length
+                ? table([
+                    ["SANDBOX", "NAME", "ADDRESS", "STATE"],
+                    ...tunnel.sandboxes.map((s) => [s.sandboxId, s.name ?? "-", s.address, s.state]),
+                ])
+                : "No sandboxes yet.",
+        ].join("\n");
+        switch (verb) {
+            case "create": {
+                const made = await runtime.tunnel.create(flag("subnet") ? { subnet: flag("subnet") } : {});
+                print(view(made), made);
+                return 0;
+            }
+            case "get":
+            case "ls": {
+                const found = await runtime.tunnel.get();
+                print(view(found), found);
+                return 0;
+            }
+            case "rm":
+            case "delete": {
+                const gone = await runtime.tunnel.delete();
+                print(`Deleted the tunnel ${gone.id}.`, gone);
+                return 0;
+            }
+            case "peer":
+            case "peers": {
+                const action = rest[0];
+                if (action === "add" || action === "rotate") {
+                    // The pair is made here unless a key is given: the private key never
+                    // leaves this machine, and goes only into the file written below.
+                    const given = flag("public-key");
+                    const pair = given ? undefined : generateWireGuardKeyPair();
+                    const publicKey = given ?? pair.publicKey;
+                    const answer = action === "add"
+                        ? await runtime.tunnel.addPeer({
+                            name: need(rest[1], "the peer's name, such as office"),
+                            publicKey,
+                            routes: args.flags.get("route") ?? [],
+                        })
+                        : await runtime.tunnel.rotatePeer(need(rest[1], "a peer id"), { publicKey });
+                    const configReady = answer.configReady ?? !!answer.config;
+                    const draftHint = "Keep this file: it preserves your private key. Read runtime tunnel get when the gateway is ready, replace PublicKey in [Peer] with gatewayPublicKey, then run wg-quick up.";
+                    // Older servers returned no config while the gateway was starting.
+                    // Preserve the locally generated key in a draft rather than discard it.
+                    const supplied = answer.config ??
+                        [
+                            "# DRAFT: gateway key missing. Keep this file; it preserves your private key.",
+                            "[Interface]",
+                            `PrivateKey = ${pair?.privateKey ?? "<your private key>"}`,
+                            `Address = ${answer.peer.address}/32`,
+                            "",
+                            "[Peer]",
+                            `PublicKey = ${answer.tunnel.gatewayPublicKey ?? "<gatewayPublicKey from runtime tunnel get>"}`,
+                            `Endpoint = ${answer.tunnel.endpoint}`,
+                            `AllowedIPs = ${answer.tunnel.subnet}`,
+                            "PersistentKeepalive = 25",
+                            "",
+                        ].join("\n");
+                    const config = pair
+                        ? supplied.replace(/^PrivateKey = .*$/m, `PrivateKey = ${pair.privateKey}`)
+                        : supplied;
+                    if (out.json) {
+                        print("", {
+                            ...answer,
+                            config,
+                            configReady,
+                            ...(!configReady ? { hint: draftHint } : {}),
+                        });
+                        return 0;
+                    }
+                    if (answer.tunnel.funded === false)
+                        out.error(fundingState(answer.tunnel));
+                    await deliver(out, config, flag("out") ?? (pair ? "runtime.conf" : undefined), configReady ? answer.hint : draftHint, configReady);
+                    return 0;
+                }
+                if (action === "rm" || action === "remove") {
+                    const after = await runtime.tunnel.removePeer(need(rest[1], "a peer id"));
+                    print(`Removed. ${after.peers.length} peer(s) left.`, after);
+                    return 0;
+                }
+                throw usage(product, "Use peer add, peer rotate or peer rm.");
+            }
+        }
+    }
+    throw usage(product, `Unknown ${product} command ${verb}.`);
+}