withruntime 0.5.1 → 0.6.0

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { realpathSync } from "node:fs";
-import { readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { connectionStore, resolveCredential } from "./credentials.js";
@@ -8,8 +8,10 @@ import { authenticationCommand, me, named } from "./login.js";
 import { createKey, dailyLimitMicros } from "./keys.js";
 import { Runtime } from "./client.js";
 import { RuntimeError } from "./errors.js";
+import { NETWORK_PRODUCTS, networkProductCommand } from "./network-cli.js";
 import { envFetch } from "./proxy.js";
-import { portForwardCommand, sshCommand } from "./ssh.js";
+import { identityToken } from "./identity.js";
+import { portForwardCommand, resolveSandbox, sshCommand } from "./ssh.js";
 import { VERSION } from "./transport.js";
 const HELP = `Runtime Cloud CLI ${VERSION}
 
@@ -30,6 +32,8 @@ Account
   account add                                  Connect another account (choose it in the browser)
   audit [--action member.] [--limit 50] [--before <next>]
                                                The account's audit log (owner or admin keys)
+  sso                                          Single sign-on and SCIM directory sync (owner or
+                                               admin keys); an owner changes it on the website
   usage                                        Balance, trial time and charges
   limits                                       Whether this key is read-only, and its daily spending limit
   secrets set <NAME> --host <host>... [--header <name> [--format '<text {value}>']]
@@ -76,6 +80,10 @@ Products
   snapshot  Saved sandboxes, disk and memory, to start or fork from
   image     Custom images from a Dockerfile, any public or private image, or a package list
   volume    Persistent disks to attach to sandboxes
+  domain    Your own hostname for a sandbox's port, with HTTPS
+  port      A public TCP port to a sandbox: databases, game servers
+  address   A dedicated outbound address, for allow-lists
+  tunnel    A WireGuard tunnel from your own network into your sandboxes
   Each has its own help: \`runtime sandbox help\`, \`runtime image help\`...
 
 Every command takes --json. Keys: RUNTIME_API_KEY, or the connection from \`runtime login\`.
@@ -83,6 +91,8 @@ Behind a proxy: HTTPS_PROXY and NO_PROXY are read, on Node and Bun alike.
 `;
 const SANDBOX_HELP = `runtime sandbox <command>
 
+  Every <id> below can also be the sandbox's name.
+
   run [--keep] [create options] -- <command>                  A fresh sandbox runs one command, then stops
   ssh <id|name> [-- <command...>] | ssh config [--install]    Log in over SSH, also from VS Code and JetBrains
   port-forward <id|name> <port|local:remote>...               Forward local ports to ports in it
@@ -98,7 +108,7 @@ const SANDBOX_HELP = `runtime sandbox <command>
                                               Run and stream output; exits with its code
   spawn <id> [--pty] -- <command...>          Start in the background; prints a process id
   ps <id>                                     Running and recent processes
-  logs <id> <processId> [-f]                  A process's output (follow with -f)
+  logs <id> <processId> [-f]                  A process's output so far; -f follows it to the end
   kill <id> <processId> [--signal SIGTERM]
   shell <id> [--command "bash -l"]            An interactive terminal
   cp <src> <dst>                              Copy files or directories; name a sandbox
@@ -111,19 +121,35 @@ const SANDBOX_HELP = `runtime sandbox <command>
               [--persistent on|off] [--max-total-cost <usd>|none]
                                               Change its settings; persistent keeps it running
   snapshot <id> [--name n] [--retention days] Keep its whole machine; prints the snapshot id
+  mount <id> <s3|r2|gcs>://<bucket>[/prefix] <path> [--secret NAME] [--region r]
+        [--endpoint https://...] [--account-id id] [--read-only]
+                                              Your bucket as a directory; the proxy signs, the sandbox never sees the key
+  mounts <id> | unmount <id> <path>           Its bucket mounts; unmount one
   fork <id> [--count 3] [--name n] [--keep-snapshot] [--trial|--paid]
                                               Copies of it as it is now, running; prints their ids
-  run-code <id> <file|-> [--lang python|javascript] [--context c] [--out-dir .]
+  run-code <id> <file|-> [--lang python|javascript|typescript|r|java|bash|go] [--context c] [--out-dir .]
                                               Run a notebook-style cell; charts saved as PNG
+  watch <id> <path> [--recursive] [--include <glob>]... [--exclude <glob>]... [--events create,write,remove,rename,chmod]
+                                              Print file changes as they happen, until Ctrl-C
+  mcp catalog                                 MCP servers a sandbox can run (licence, settings, hosts)
+  mcp <id> start <server>... [--secret SERVER.SETTING=SECRET]... [--env SERVER.NAME=value]...
+                             [--option SERVER.NAME=value]... [--port 8765] [--replace]
+                                              Start them; prints each URL and the header to send
+  mcp <id> [status] | mcp <id> stop           Their state and fresh URLs; stop them
   preview <id> <port> [--public] [--ttl <s>]  Share a port at an HTTPS address
   previews <id>                               Every shared port
   unshare <id> <port>                         Stop sharing a port
   network <id> [--no-internet|--internet] [--allow <host>]... [--deny <host>]... [--connect <host:port>]...
                                               Show its network rules, or replace them
+  identity-token --audience <aud> [--lifetime <seconds>]
+                                              Inside a sandbox: an OIDC token naming it, for AWS,
+                                              Google Cloud or your own API. Needs no API key
   metrics <id> [--range 15m|1h|6h|24h|7d|30d]
                                               CPU and memory over time, and the latest reading
   desktop <id> start | stop | screenshot [file.png] | open <url> | click <x> <y>
                | type <text> | press <keys> | windows
+  desktop <id> record start [--fps 10] [--max-seconds 1800] [--max-mib 512] | record stop <recId>
+               | record ls | record fetch <recId> [file.mp4] | record rm <recId>
 
 Examples
   id=$(runtime sandbox create)
@@ -169,6 +195,17 @@ const pairs = (args, name) => Object.fromEntries((args.flags.get(name) ?? []).ma
         throw usage(`--${name} takes KEY=VALUE.`);
     return [pair.slice(0, at), pair.slice(at + 1)];
 }));
+/** What the commands in cli-extras.ts use of this file. */
+const kit = {
+    parse: (argv, booleans) => parse(argv, booleans),
+    flag,
+    has,
+    integer,
+    pairs,
+    need: (value, what) => need(value, what),
+    table: (rows) => table(rows),
+    usage: (message) => usage(message),
+};
 /** The product being run, so a mistake points at its own help. */
 let product = "";
 function usage(message) {
@@ -206,6 +243,7 @@ const COMMANDS = [
     "whoami",
     "usage",
     "limits",
+    "sso",
     "secrets",
     "keys",
     "referrals",
@@ -220,6 +258,10 @@ const COMMANDS = [
     "snapshot",
     "image",
     "volume",
+    "domain",
+    "port",
+    "address",
+    "tunnel",
     "webhooks",
     "otel",
     "events",
@@ -240,6 +282,9 @@ const SANDBOX_VERBS = [
     "wake",
     "restart",
     "snapshot",
+    "mount",
+    "mounts",
+    "unmount",
     "fork",
     "extend",
     "update",
@@ -259,6 +304,9 @@ const SANDBOX_VERBS = [
     "network",
     "desktop",
     "metrics",
+    "watch",
+    "mcp",
+    "identity-token",
 ];
 function need(value, what) {
     if (!value)
@@ -454,7 +502,7 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
     }
     if (command === "usage") {
         const value = await (await client(env)).usage();
-        print(JSON.stringify(value, null, 2), value);
+        print(usageSummary(value), value);
         return 0;
     }
     if (command === "limits") {
@@ -486,8 +534,10 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         return otelCommand(rest, env, out);
     if (command === "events") {
         const args = parse(rest);
-        const page = await (await client(env)).events.list({
-            ...(flag(args, "sandbox") ? { resourceId: flag(args, "sandbox") } : {}),
+        const rt = await client(env);
+        const sandbox = flag(args, "sandbox");
+        const page = await rt.events.list({
+            ...(sandbox ? { resourceId: await sandboxIdOf(rt, sandbox) } : {}),
             ...(flag(args, "type") ? { type: flag(args, "type") } : {}),
             ...(integer(args, "limit") ? { limit: integer(args, "limit") } : {}),
         });
@@ -501,6 +551,29 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
     }
     if (command === "keys")
         return keys(rest, env, out);
+    if (command === "sso") {
+        const status = await (await client(env)).sso.get();
+        print([
+            status.connections.length
+                ? table([
+                    ["domain", "provider", "verified", "required", "new people join as"],
+                    ...status.connections.map((c) => [
+                        c.domain,
+                        `${c.provider} ${c.protocol.toUpperCase()}`,
+                        c.domainVerifiedAt
+                            ? c.domainVerifiedAt.slice(0, 10)
+                            : `no: TXT ${c.verification.name}`,
+                        c.requireSso ? "yes" : "no",
+                        c.defaultRole,
+                    ]),
+                ])
+                : "No single sign-on yet.",
+            "",
+            `Directory sync (SCIM): ${status.scim.tokens} token${status.scim.tokens === 1 ? "" : "s"}, ${status.scim.activeUsers} of ${status.scim.users} people active, ${status.scim.groups.length} groups.`,
+            `An owner changes it at ${status.manage}`,
+        ].join("\n"), status);
+        return 0;
+    }
     if (command === "account" || command === "accounts")
         return accountCommand(rest, env, out);
     if (command === "audit") {
@@ -558,7 +631,11 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
     if (command === "mcp") {
         const { serveMcp } = await import("./mcp.js");
         await serveMcp(env);
-        return 0;
+        /* Its input closed or a signal came: leave once stdout has drained. An
+           idle keep-alive connection to the API would otherwise hold the process
+           for several seconds after the client asked it to go. */
+        await new Promise((resolve) => process.stdout.write("", () => resolve()));
+        process.exit(0);
     }
     if (command === "docs") {
         const topic = rest[0] ?? "index";
@@ -652,8 +729,101 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         product = "volume";
         return volume(rest, env, out);
     }
+    const networkProduct = { domains: "domain", ports: "port", addresses: "address", tunnels: "tunnel" }[command] ??
+        command;
+    if (NETWORK_PRODUCTS.includes(networkProduct)) {
+        product = networkProduct;
+        return networkProductCommand(networkProduct, rest, parse(rest, ["ipv6"]), out, () => client(env));
+    }
     throw unknown("command", command, COMMANDS);
 }
+/** `runtime usage` for a person: the balance, the trial and what each kind
+ * of resource was charged, in dollars. --json keeps every figure, and each
+ * resource with its rates and CPU time. */
+function usageSummary(u) {
+    const micros = (value) => typeof value === "string" || typeof value === "number" || typeof value === "bigint"
+        ? BigInt(value)
+        : 0n;
+    const hours = (ms) => (ms / 3_600_000).toLocaleString("en-US", { maximumFractionDigits: 1 });
+    const takenBack = micros(u.takenBack);
+    const rows = [
+        ["available", dollars(micros(u.available))],
+        ["credited", dollars(micros(u.credited))],
+        [
+            "spent",
+            `${dollars(micros(u.spent))}${takenBack > 0n ? `, ${dollars(takenBack)} of it refunded or disputed` : ""}`,
+        ],
+        ["held for running work", dollars(micros(u.held))],
+    ];
+    if (micros(u.expired) > 0n)
+        rows.push(["expired or taken back", dollars(micros(u.expired))]);
+    if (u.trial)
+        rows.push([
+            "free trial",
+            `${hours(u.trial.availableMs)} of ${hours(u.trial.totalMs)} hours left${u.trial.reservedMs > 0 ? `, ${hours(u.trial.reservedMs)} held by running sandboxes` : ""}`,
+        ]);
+    const kinds = new Map();
+    for (const resource of u.resources ?? []) {
+        const kind = typeof resource.kind === "string" ? resource.kind : "other";
+        const entry = kinds.get(kind) ?? { count: 0, charged: 0n, held: 0n };
+        entry.count++;
+        entry.charged += micros(resource.chargedMicros);
+        entry.held += micros(resource.heldMicros);
+        kinds.set(kind, entry);
+    }
+    const plural = (kind, n) => n === 1 ? kind : kind.endsWith("x") || kind.endsWith("s") ? `${kind}es` : `${kind}s`;
+    const byKind = [...kinds.entries()].sort((a, b) => b[1].count - a[1].count);
+    return [
+        table(rows),
+        "",
+        byKind.length
+            ? table([
+                ["RESOURCES", "COUNT", "CHARGED", "HELD"],
+                ...byKind.map(([kind, e]) => [
+                    plural(kind, e.count),
+                    e.count.toLocaleString("en-US"),
+                    dollars(e.charged),
+                    dollars(e.held),
+                ]),
+            ])
+            : "No resources yet.",
+        "",
+        `Each resource, with its rates and CPU time: ${me} usage --json`,
+    ].join("\n");
+}
+const SANDBOX_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** A sandbox's id from its id or its name, for the filters that take an id. */
+async function sandboxIdOf(runtime, target) {
+    return SANDBOX_UUID.test(target) ? target : (await resolveSandbox(runtime, target)).id;
+}
+/** What a process has printed so far, in order, without waiting for more. */
+async function outputSoFar(runtime, sandboxId, processId) {
+    const chunks = [];
+    let cursor = 0;
+    let truncated = false;
+    let latest = null;
+    // The guest keeps the latest 1 MiB; a read returns at most 192 KiB.
+    for (let page = 0; page < 16; page++) {
+        const read = await runtime.transport.json({
+            method: "GET",
+            path: `/v1/sandboxes/${encodeURIComponent(sandboxId)}/processes/${encodeURIComponent(processId)}/output`,
+            query: { cursor, maxBytes: 196_608 },
+        });
+        chunks.push(...read.chunks);
+        truncated ||= read.truncated;
+        latest = read.process ?? latest;
+        if (read.chunks.length === 0 || read.nextCursor <= cursor)
+            break;
+        cursor = read.nextCursor;
+    }
+    return {
+        processId,
+        state: latest?.state ?? null,
+        exitCode: latest?.exitCode ?? null,
+        truncated,
+        chunks,
+    };
+}
 /** Dollars from integer microdollars: cents from a dollar up, and four
  * places below one, so a few minutes of use does not round to $0.01. */
 function dollars(micros) {
@@ -769,13 +939,25 @@ async function switching(command, argv, env, out) {
         : `${c.rival.name} would cost ${dollars(-saving)} less${percent}`;
     const figures = `${dollars(c.runtimeMicros)} on Runtime; the same sandboxes on ${c.rival.name}: ${dollars(c.rivalMicros)}; ${verdict}`;
     const month = c.perMonth ? BigInt(c.perMonth.savingMicros) : undefined;
+    const monthly = month === undefined
+        ? ""
+        : month >= 0n
+            ? `about ${dollars(month)} a month`
+            : `about ${dollars(-month)} a month more on Runtime`;
+    /* The month is projected from the days the usage covers, not from the
+       window asked for: say which, or a young account's 7 and 90 days read the
+       same with nothing to say why. */
+    const covered = c.perMonth?.fromDays ?? c.window.days;
+    const pace = month === undefined
+        ? "."
+        : covered < c.window.days
+            ? `. Your first sandbox in this window ran ${covered <= 1 ? "within the last day" : `${covered.toLocaleString("en-US")} days ago`}; at that pace, ${monthly}.`
+            : c.window.days === 30
+                ? `, ${monthly}.`
+                : `. At that pace, ${monthly}.`;
     const lines = c.basis === "usage"
         ? [
-            `Your last ${c.window.days} days: ${figures}${month === undefined
-                ? "."
-                : month >= 0n
-                    ? `, about ${dollars(month)} a month.`
-                    : `, about ${dollars(-month)} a month more on Runtime.`}`,
+            `Your last ${c.window.days} days: ${figures}${pace}`,
             `Priced: ${c.usage.sandboxes.toLocaleString("en-US")} sandbox${c.usage.sandboxes === 1 ? "" : "es"}, ${(c.usage.runSeconds / 3600).toLocaleString("en-US", { maximumFractionDigits: 2 })} hours running.${trialNote(c.usage.trialSandboxes, c.usage.sandboxes)}${c.usage.unpricedSandboxes ? ` ${c.usage.unpricedSandboxes} left out: ${c.rival.name} publishes no price for their size.` : ""}`,
         ]
         : [
@@ -826,8 +1008,22 @@ async function sandbox(argv, env, out) {
         out.write(out.json ? JSON.stringify({ usage: named(SANDBOX_HELP) }) : named(SANDBOX_HELP));
         return 0;
     }
+    // Inside a sandbox, with no API key: the sandbox's own request token asks.
+    if (verb === "identity-token") {
+        const args = parse(rest);
+        const audience = need(flag(args, "audience"), "--audience, such as sts.amazonaws.com");
+        const lifetime = flag(args, "lifetime");
+        const token = await identityToken({
+            audience,
+            ...(lifetime === undefined ? {} : { lifetimeSeconds: Number(lifetime) }),
+        });
+        print(token.token, token);
+        return 0;
+    }
     const runtime = await client(env);
-    const get = (id) => runtime.sandboxes.get(need(id, "a sandbox id"));
+    /* By id or by name, for every command here, as ssh and port-forward
+       always took one. */
+    const get = (id) => resolveSandbox(runtime, need(id, "a sandbox id or name"));
     switch (verb) {
         case "create": {
             const args = parse(rest, CREATE_FLAGS);
@@ -888,6 +1084,50 @@ async function sandbox(argv, env, out) {
             print(`${sbx.id} ${sbx.state}`, sbx.info);
             return 0;
         }
+        case "mount": {
+            const args = parse(rest, ["read-only"]);
+            const sbx = await get(args.positional[0]);
+            const source = need(args.positional[1], "a bucket, as s3://bucket, r2://bucket or gcs://bucket");
+            const found = /^(s3|r2|gcs):\/\/([^/]+)(?:\/(.+))?$/.exec(source);
+            if (!found)
+                throw usage("The bucket is s3://bucket[/prefix], r2://bucket or gcs://bucket.");
+            const mounted = await sbx.mounts.add({
+                provider: found[1],
+                bucket: found[2],
+                path: need(args.positional[2], "a path to mount it at, such as /data"),
+                ...(found[3] ? { prefix: found[3] } : {}),
+                ...(flag(args, "secret") ? { secret: flag(args, "secret") } : {}),
+                ...(flag(args, "region") ? { region: flag(args, "region") } : {}),
+                ...(flag(args, "endpoint") ? { endpoint: flag(args, "endpoint") } : {}),
+                ...(flag(args, "account-id") ? { accountId: flag(args, "account-id") } : {}),
+                ...(has(args, "read-only") ? { readOnly: true } : {}),
+            });
+            print(`${mounted.path} ${mounted.provider}://${mounted.bucket}`, mounted);
+            return 0;
+        }
+        case "mounts": {
+            const sbx = await get(rest[0]);
+            const all = await sbx.mounts.list();
+            print(all.length
+                ? table([
+                    ["PATH", "BUCKET", "ENDPOINT", "SECRET", "MOUNTED"],
+                    ...all.map((m) => [
+                        m.path,
+                        `${m.provider}://${m.bucket}${m.prefix ? `/${m.prefix}` : ""}`,
+                        m.endpoint,
+                        m.secret ?? "-",
+                        m.mounted ? "yes" : "no",
+                    ]),
+                ])
+                : "No buckets mounted.", all);
+            return 0;
+        }
+        case "unmount": {
+            const sbx = await get(rest[0]);
+            const gone = await sbx.mounts.remove(need(rest[1], "the mounted path"));
+            print(`${gone.path} unmounted`, gone);
+            return 0;
+        }
         case "snapshot": {
             const args = parse(rest);
             const sbx = await get(args.positional[0]);
@@ -992,7 +1232,7 @@ async function sandbox(argv, env, out) {
             const args = parse(rest, ["f", "follow"]);
             const sbx = await get(args.positional[0]);
             const proc = await sbx.processes.get(need(args.positional[1], "a process id"));
-            if (has(args, "f") || has(args, "follow") || !out.json) {
+            if (has(args, "f") || has(args, "follow")) {
                 for await (const event of proc.output())
                     if (event.type === "stdout")
                         process.stdout.write(event.data);
@@ -1002,7 +1242,17 @@ async function sandbox(argv, env, out) {
                         out.write(JSON.stringify(event));
                 return 0;
             }
-            out.write(JSON.stringify(await proc.wait()));
+            /* Without -f, what it has printed so far, then back to the prompt, as
+               `docker logs` does: a server's log is read, not followed forever. */
+            const so = await outputSoFar(runtime, sbx.id, proc.id);
+            if (out.json) {
+                out.write(JSON.stringify(so));
+                return 0;
+            }
+            for (const chunk of so.chunks)
+                (chunk.stream === "stderr" ? process.stderr : process.stdout).write(chunk.text);
+            if (so.state === "running")
+                process.stderr.write(`[${proc.id} is still running; follow it: ${me} sandbox logs ${sbx.id} ${proc.id} -f]\n`);
             return 0;
         }
         case "kill": {
@@ -1031,7 +1281,7 @@ async function sandbox(argv, env, out) {
                 ...(flag(args, "glob") ? { glob: flag(args, "glob") } : {}),
             });
             print(entries
-                .map((e) => `${e.type === "directory" ? "d" : "-"} ${String(e.size).padStart(10)}  ${e.path}`)
+                .map((e) => `${e.type === "directory" ? "d" : e.type === "symlink" ? "l" : e.type === "other" ? "?" : "-"} ${String(e.size).padStart(10)}  ${e.path}`)
                 .join("\n") || "(empty)", entries);
             return 0;
         }
@@ -1101,6 +1351,27 @@ async function sandbox(argv, env, out) {
         }
         case "desktop":
             return desktop(await get(rest[0]), rest.slice(1), out);
+        case "watch":
+            return (await import("./cli-extras.js")).watchCommand(await get(rest[0]), rest.slice(1), out, kit);
+        case "mcp":
+            if (rest[0] === "catalog" || rest[0] === undefined) {
+                const catalog = await runtime.mcp.catalog();
+                print(table([
+                    ["ID", "LICENCE", "VERSION", "NEEDS", "WHAT"],
+                    ...catalog.map((entry) => [
+                        entry.id,
+                        entry.license,
+                        entry.version,
+                        entry.env
+                            .filter((item) => item.required)
+                            .map((item) => `${item.name}${item.secret ? " (secret)" : ""}`)
+                            .join(", ") || "-",
+                        entry.description,
+                    ]),
+                ]), catalog);
+                return 0;
+            }
+            return (await import("./cli-extras.js")).mcpCommand(await get(rest[0]), rest.slice(1), out, kit);
         case "metrics": {
             const args = parse(rest);
             const sbx = await get(args.positional[0]);
@@ -1236,8 +1507,20 @@ async function runCode(sbx, argv, out) {
     const args = parse(argv);
     const source = need(args.positional[0], "a file, or - to read the code from standard input");
     const code = await readInput(source);
+    const byExtension = {
+        js: "javascript",
+        mjs: "javascript",
+        ts: "typescript",
+        r: "r",
+        java: "java",
+        jsh: "java",
+        sh: "bash",
+        bash: "bash",
+        go: "go",
+    };
     const language = (flag(args, "lang") ??
-        (/\.(m?js|ts)$/.test(source) ? "javascript" : "python"));
+        byExtension[source.split(".").pop()?.toLowerCase() ?? ""] ??
+        "python");
     const timeout = integer(args, "timeout");
     const execution = await sbx.interpreter.run(code, {
         language,
@@ -1252,6 +1535,8 @@ async function runCode(sbx, argv, out) {
     });
     const saved = [];
     const outDir = flag(args, "out-dir") ?? ".";
+    if (execution.results.some((r) => r.data["image/png"] || r.refs["image/png"]))
+        await mkdir(outDir, { recursive: true });
     for (const [index, result] of execution.results.entries()) {
         const inline = result.data["image/png"];
         const ref = result.refs["image/png"];
@@ -1316,6 +1601,8 @@ async function desktop(sbx, argv, out) {
         case "press":
             print("Pressed.", await d.press(need(rest[0], "keys, e.g. ctrl+l")));
             return 0;
+        case "record":
+            return (await import("./cli-extras.js")).recordCommand(sbx, rest, out, kit);
         case "windows": {
             const windows = await d.windows();
             print(windows.length
@@ -1324,7 +1611,7 @@ async function desktop(sbx, argv, out) {
             return 0;
         }
     }
-    throw usage(`${me} sandbox desktop <id> start|stop|screenshot|open|click|type|press|windows`);
+    throw usage(`${me} sandbox desktop <id> start|stop|screenshot|open|click|type|press|windows|record`);
 }
 const KEYS_HELP = `runtime keys <command>
 
@@ -1483,7 +1770,9 @@ async function snapshot(argv, env, out) {
         case "list": {
             const args = parse(rest);
             const all = await (await api.list({
-                ...(flag(args, "sandbox") ? { sandboxId: flag(args, "sandbox") } : {}),
+                ...(flag(args, "sandbox")
+                    ? { sandboxId: await sandboxIdOf(await client(env), flag(args, "sandbox")) }
+                    : {}),
                 ...(flag(args, "name") ? { name: flag(args, "name") } : {}),
             })).toArray(1000);
             print(all.length
@@ -1744,10 +2033,17 @@ const VOLUME_HELP = `runtime volume <command>
 
   create --size-mib <N> [--name n]            A persistent ext4 disk; prints its id
   ls                                          Your volumes
-  get <id>                                    One volume and where it is attached
-  rm <id>                                     Delete it and everything on it
+  get <id>                                    One volume, its backups and where it is attached
+  rm <id>                                     Delete it and everything on it (its backups stay)
+  backup <id> [--retention-days N] [--no-wait]
+                                              Back it up now, off its host; prints the backup id
+  backups [<id>]                              Backups, newest first (of one volume, if given)
+  restore <backupId> [--name n]               A new volume from a backup, on any host
+  backup-rm <backupId>                        Delete a backup
+  backup-policy <id> [--daily on|off] [--retention-days N]
+                                              Daily backups on or off, and how long each is kept
   Attach one: runtime sandbox create --volume <id>:/data
-  A volume lives on one server and is not backed up off it.
+  Volumes are backed up off their host daily unless you turn it off.
 `;
 async function volume(argv, env, out) {
     const [verb, ...rest] = argv;
@@ -1764,8 +2060,6 @@ async function volume(argv, env, out) {
                 sizeMiB: integer(args, "size-mib") ?? Number(need(undefined, "--size-mib <N>")),
                 ...(flag(args, "name") ? { name: flag(args, "name") } : {}),
             });
-            if (!out.json)
-                out.error("Not backed up off its server.");
             print(created.id, created);
             return 0;
         }
@@ -1774,12 +2068,13 @@ async function volume(argv, env, out) {
             const all = await (await api.list()).toArray(1000);
             print(all.length
                 ? table([
-                    ["ID", "NAME", "STATE", "MIB", "ATTACHED"],
+                    ["ID", "NAME", "STATE", "MIB", "BACKED UP", "ATTACHED"],
                     ...all.map((v) => [
                         v.id,
                         v.name ?? "-",
                         v.state,
                         String(v.sizeMiB),
+                        v.backedUp ? (v.backups?.lastReadyAt ?? "yes") : "no",
                         v.attachments.map((a) => `${a.sandboxId}:${a.path}`).join(", ") || "-",
                     ]),
                 ])
@@ -1797,8 +2092,78 @@ async function volume(argv, env, out) {
             print(`${found.id} ${found.state}`, found);
             return 0;
         }
+        case "backup": {
+            const args = parse(rest, ["no-wait"]);
+            const id = need(args.positional[0], "a volume id");
+            const days = integer(args, "retention-days");
+            const made = await api.backup(id, days === undefined ? {} : { retentionDays: days }, has(args, "no-wait") ? { wait: 0 } : {});
+            if (!out.json && made.state === "pending")
+                out.error(`Copying it off the host; check with: ${me} volume backups ${id}`);
+            print(made.id, made);
+            return 0;
+        }
+        case "backups": {
+            const volumeId = rest[0];
+            const all = await (await api.backups(volumeId ? { volumeId } : {})).toArray(1000);
+            print(all.length
+                ? table([
+                    ["ID", "VOLUME", "STATE", "TRIGGER", "MIB", "STORED", "TAKEN", "EXPIRES"],
+                    ...all.map((b) => [
+                        b.id,
+                        b.volumeId,
+                        b.state,
+                        b.trigger,
+                        String(b.sizeMiB),
+                        b.storedBytes === null ? "-" : `${Math.ceil(b.storedBytes / 1048576)} MiB`,
+                        b.createdAt,
+                        b.expiresAt,
+                    ]),
+                ])
+                : "No backups yet.", all);
+            return 0;
+        }
+        case "restore": {
+            const args = parse(rest);
+            const created = await api.restore(need(args.positional[0], "a backup id"), flag(args, "name") ? { name: flag(args, "name") } : {});
+            if (!out.json && created.state === "creating")
+                out.error(`Restoring; check with: ${me} volume get ${created.id}`);
+            print(created.id, created);
+            return 0;
+        }
+        case "backup-rm":
+        case "backup-delete": {
+            const found = await api.deleteBackup(need(rest[0], "a backup id"));
+            print(`${found.id} ${found.state}`, found);
+            return 0;
+        }
+        case "backup-policy": {
+            const args = parse(rest);
+            const id = need(args.positional[0], "a volume id");
+            const daily = flag(args, "daily");
+            if (daily !== undefined && !["on", "off", "true", "false"].includes(daily))
+                throw usage("--daily takes on or off.");
+            const days = integer(args, "retention-days");
+            if (daily === undefined && days === undefined)
+                throw usage("Give --daily on|off, --retention-days N or both.");
+            const updated = await api.setBackupPolicy(id, {
+                ...(daily === undefined ? {} : { daily: daily === "on" || daily === "true" }),
+                ...(days === undefined ? {} : { retentionDays: days }),
+            });
+            print(`${updated.id} daily backups ${updated.backups.daily ? "on" : "off"}, kept ${updated.backups.retentionDays} days`, updated);
+            return 0;
+        }
     }
-    throw unknown("volume command", verb, ["create", "ls", "get", "rm"]);
+    throw unknown("volume command", verb, [
+        "create",
+        "ls",
+        "get",
+        "rm",
+        "backup",
+        "backups",
+        "restore",
+        "backup-rm",
+        "backup-policy",
+    ]);
 }
 /** Flags `sandbox create` and `run` take without a value. */
 const CREATE_FLAGS = [
@@ -1852,7 +2217,10 @@ function createInput(args) {
  * (124 on a timeout), so a script's `set -e` behaves. */
 async function execute(sbx, command, args, out, timeout) {
     const target = command.length === 1 ? command[0] : command;
+    const extras = await import("./cli-extras.js");
+    const stdin = await extras.pipedStdin();
     const options = {
+        ...(stdin ? { stdin } : {}),
         ...(flag(args, "cwd") ? { cwd: flag(args, "cwd") } : {}),
         ...(args.flags.has("env") ? { env: pairs(args, "env") } : {}),
         ...(timeout ? { timeoutMs: timeout * 1000 } : {}),
@@ -1868,7 +2236,12 @@ async function execute(sbx, command, args, out, timeout) {
         out.write(JSON.stringify(result));
     else if (result.timedOut)
         out.error(`runtime: timed out after ${timeout ?? 60} s; the command's process group was killed.`);
-    return result.timedOut ? 124 : Math.min(255, Math.max(0, result.exitCode ?? 1));
+    // Never drop output silently: say so, and do not exit 0.
+    const lost = extras.lostOutput(result, sbx.id);
+    if (lost && !out.json)
+        out.error(lost);
+    const code = result.timedOut ? 124 : Math.min(255, Math.max(0, result.exitCode ?? 1));
+    return lost && code === 0 ? 1 : code;
 }
 async function shell(sbx, command) {
     const stdin = process.stdin;