withruntime 0.12.0 → 0.16.0

package/dist/cli.js

@@ -24,12 +24,14 @@ Usage: runtime <product> <command> [options]      runtime <command> [options]
 
 Start
   sandboxes run [--keep] [create options] -- <command>
-                                               A fresh sandbox runs one command, then stops
+                                               A fresh sandbox runs one command, then is deleted
 
 Account
   login [--agent-name <name>] [--no-browser] [--wait]
                                                Connect this machine (no key to copy)
   login --with-key                             Or paste a key from withruntime.com/account/keys
+  billing topup <usd> --new-account --accept-terms [--wait]
+                                               No person? Open an account paid in USDC
   logout                                       Revoke this machine's connection
   whoami                                       The organization and agent you act as
   account [ls]                                 The accounts this machine is connected to
@@ -40,16 +42,22 @@ Account
                                                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 [--csv]                                Balance, included usage and charges; --csv, each resource
+  usage [--csv]                                Balance, free usage and charges; --csv, each resource
   usage export --since <UTC time> --until <UTC time>
                                                Every settlement in the range as CSV; --json, each page
   limits                                       Whether this key is read-only, and its daily spending limit
   secrets set <NAME> --host <host>... [--header <name> [--format '<text {value}>']]
             [--allow '[GET,HEAD] /path/*']...  Store a secret sandboxes use without seeing it; the
-                                               value is read from standard input, never an argument.
-                                               --allow (paid): only these methods and paths get it
+            [--only-label key=value[,k=v]]...  value is read from standard input, never an argument.
+            [--only-sandbox <id>]...           --allow (paid): only these methods and paths get it.
+            [--all-sandboxes]                  --only-label: only sandboxes with those labels (each
+                                               flag one selector, any may match); --only-sandbox:
+                                               only that sandbox. A new value keeps the scope;
+                                               --all-sandboxes gives it to every sandbox again
   secrets set <NAME> --jobs [--host ...]       A copy scheduled jobs put in their environment
                                                (job create --secret NAME); with --host, both
+  secrets scope <NAME> --only-label k=v... | --only-sandbox <id>... | --all-sandboxes
+                                               Change which sandboxes get it; no value needed
   secrets ls | get <NAME>                      Names, hosts, placeholders and jobs versions, never values
   secrets rotate <NAME>                        A new version of the jobs copy, from standard input
   secrets reveal <NAME> [--version N]          Print the jobs copy's value. The sandboxes' copy is
@@ -80,6 +88,8 @@ Account
 Connect
   sandboxes ssh <id|name> [-- <command...>]    Log in over SSH; \`runtime sandboxes ssh help\` for editors
   sandboxes ssh config [--install]             Make \`ssh <id|name>.runtime\` work (VS Code, JetBrains)
+  sandboxes code <id|name> [--editor vscode|cursor|windsurf]
+                                               Open it in VS Code, Cursor or Windsurf over SSH
   sandboxes port-forward <id|name> <port|local:remote>...
                                                Forward local ports to ports in a sandbox
 
@@ -114,14 +124,17 @@ const SANDBOX_HELP = `runtime sandboxes <command>
 
   Every <id> below can also be the sandbox's name.
 
-  run [--keep] [create options] -- <command>                  A fresh sandbox runs one command, then stops
+  run [--keep] [create options] -- <command>                  A fresh sandbox runs one command, then is deleted
   ssh <id|name> [-- <command...>] | ssh config [--install]    Log in over SSH, also from VS Code and JetBrains
+  code <id|name> [--editor vscode|cursor|windsurf] [--path /workspace] [--print]
+                                                              Open it in your editor over SSH, in one step
   port-forward <id|name> <port|local:remote>...               Forward local ports to ports in it
   create [--name n] [--label k=v]... [--env K=V]... [--vcpu 2] [--memory 4096] [--disk 4096]
          [--cpu shared|reserved] [--cpu-floor <thousandths>] [--max-cost <usd>] [--max-total-cost <usd>]
          [--timeout <60-86400>] [--on-timeout pause|stop|delete] [--no-wait]
          [--no-internet] [--allow <host>]... [--deny <host>]... [--connect <host:port>]...
          [--image <name:tag|imageId> | --snapshot <snapshotId>] [--volume <volumeId>:/data[:snapshot]]...
+         [--spread-from <id>]...
          [--idle-pause <seconds>] [--no-auto-wake] [--persistent] [--get-or-create]
                                                               Create one; prints its id
   ls [--all] [--label k=v]... [--state running]               List (live ones unless --all)
@@ -143,6 +156,8 @@ const SANDBOX_HELP = `runtime sandboxes <command>
   stop --label k=v [--label k=v]...           Stop every live sandbox with all those labels
   rm <id>                                     Delete it for good: stops it, deletes its disk and
                                               paused memory, revokes its previews; snapshots stay
+  rm --label k=v [--label k=v]...             Delete for good every sandbox with all those labels,
+                                              stopped ones too
   switch-image <id> <image> --keep-workspace  Move it to another image, keeping /workspace (your home),
                                               volumes, env and previews; processes restart, the rest of
                                               its disk is lost (snapshot it first to keep everything)
@@ -152,6 +167,7 @@ const SANDBOX_HELP = `runtime sandboxes <command>
   extend <id> <seconds>                       Move a time limit on (one with none needs nothing)
   update <id> [--name n] [--label k=v]... [--env K=V]... [--unset-env K]... [--idle-pause <seconds>] [--auto-wake on|off]
               [--persistent on|off] [--max-total-cost <usd>|none]
+              [--timeout <60-86400 from now>|0] [--on-timeout pause|stop|delete]
                                               Change its settings; persistent keeps it running until stopped
   snapshot <id> [--name n] [--retention days|credit] Keep its whole machine; prints the snapshot id
   mount <id> <s3|r2|gcs>://<bucket>[/prefix] <path> [--secret NAME] [--region r]
@@ -169,8 +185,9 @@ const SANDBOX_HELP = `runtime sandboxes <command>
                                               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]
+                             [--option SERVER.NAME=value]... [--port 8765] [--replace] [--public]
                                               Start them; prints each URL and the header to send
+                                              (--public: URLs that never expire, paid only)
   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 (--public: paid only)
   preview rotate <id> <port>                  Refuse every token given out for a private port so
@@ -242,7 +259,14 @@ commandAfter) {
             break;
         }
         if (arg.startsWith("--") || (arg.startsWith("-") && arg.length === 2 && !/^-\d/.test(arg))) {
-            const [name, inline] = arg.replace(/^-+/, "").split(/=(.*)/s, 2);
+            const [typed, inline] = arg.replace(/^-+/, "").split(/=(.*)/s, 2);
+            // A plural of an option is the option once per comma: --hosts a,b is
+            // --host a --host b (13 October 2026: a user's first try at a secret).
+            const plural = !known.has(typed) &&
+                typed.endsWith("s") &&
+                LISTS.has(typed.slice(0, -1)) &&
+                known.has(typed.slice(0, -1));
+            const name = plural ? typed.slice(0, -1) : typed;
             if (!known.has(name))
                 throw commandAfter && !meantOption(name, known)
                     ? usage(`Unknown option ${arg.split("=")[0]}. If it belongs to the command, put the command after --: ${commandAfter}`)
@@ -254,13 +278,16 @@ commandAfter) {
                 throw usage(`--${name} needs a value.`);
             if (boolean && value !== "true" && value !== "false")
                 throw usage(`--${name} takes true or false.`);
-            flags.set(name, [...(flags.get(name) ?? []), value]);
+            const values = plural ? value.split(",").filter(Boolean) : [value];
+            flags.set(name, [...(flags.get(name) ?? []), ...values]);
         }
         else
             positional.push(arg);
     }
     return { positional, flags, rest };
 }
+/** Options given once per item, which a plural takes as a comma list. */
+const LISTS = new Set(["host", "allow", "deny", "connect"]);
 /** The declared option a mistyped one most likely meant. --memory-mib for
  * --memory, --timeout-seconds for --timeout: the SDK's spelling of an option is
  * the CLI's with its unit added. */
@@ -408,6 +435,7 @@ const SANDBOX_MOVED = ["run", "ssh", "port-forward", "forward"];
 const SANDBOX_VERBS = [
     "run",
     "ssh",
+    "code",
     "port-forward",
     "create",
     "ls",
@@ -565,12 +593,12 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         out.error(`Warning: ${named(words.warning)}`);
     const [first, ...remaining] = words.argv;
     // Sandbox is one product of several, so its commands live under it
-    // (AGENTS.md, 23 September 2026): `runtime sandboxes run`, `sandbox ssh` and
+    // (23 September 2026): `runtime sandboxes run`, `sandbox ssh` and
     // `sandbox port-forward`. The old top-level forms were removed, not aliased.
     if (first && SANDBOX_MOVED.includes(first))
         throw usage(`\`${me} ${first}\` is now \`${me} sandboxes ${first === "forward" ? "port-forward" : first}\`.`);
     const nested = (first === "sandbox" || first === "sandboxes" || first === "sbx") &&
-        SANDBOX_MOVED.includes(remaining[0] ?? "");
+        [...SANDBOX_MOVED, "code"].includes(remaining[0] ?? "");
     const command = nested ? remaining[0] : first;
     const rest = nested ? remaining.slice(1) : remaining;
     // `runtime sandboxes create --help` is how an agent asks what a command takes:
@@ -607,7 +635,7 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
             : `Runtime Cloud ${VERSION}. ${start}
 
   ${me} sandboxes run -- python3 < invoice.py
-                                   Run a local invoice script, then stop the sandbox
+                                   Run a local invoice script, then delete the sandbox
   ${me} sandboxes create                 A sandbox that stays; prints its id
   ${me} sandboxes exec <id> -- <command> Run in it
   ${me} help                             Everything else
@@ -629,24 +657,23 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         const onCapacityWait = waiting(out);
         const sbx = await withVolumeRelease((options) => runtime.sandboxes.create(input, { ...options, onCapacityWait }), out);
         let cleanup;
-        // SIGINT and normal completion share one stop. Keep an absolute deadline
-        // across the stop retries and final state check, so cleanup cannot hang.
+        // SIGINT and normal completion share one delete, with an absolute
+        // deadline across its retries, so cleanup cannot hang. A delete, not a
+        // stop: a stopped sandbox keeps its disk, billed, and an account without
+        // credit keeps at most 10, so ten runs that only stopped refused the
+        // eleventh (no_credit_kept_limit, 0685). --keep is how to keep one.
         const stop = () => (cleanup ??= (async () => {
             const signal = AbortSignal.timeout(30_000);
             try {
-                await sbx.stop({ wait: false, signal });
-                if (sbx.state !== "stopped")
-                    await sbx.waitFor("stopped", { timeoutSeconds: 25, signal });
-                if (sbx.state !== "stopped")
-                    throw new Error(`Sandbox is still ${sbx.state}.`);
+                await sbx.delete({ signal });
                 return true;
             }
             catch (error) {
                 out.error(describeError(new RuntimeError({
                     code: "cleanup_failed",
                     status: 0,
-                    message: `Could not confirm that sandbox ${sbx.id} stopped. ${error instanceof Error ? error.message : String(error)}`,
-                    hint: `Check it and retry cleanup with: ${me} sandboxes stop ${sbx.id}`,
+                    message: `Could not confirm that sandbox ${sbx.id} was deleted. ${error instanceof Error ? error.message : String(error)}`,
+                    hint: `Check it and retry cleanup with: ${me} sandboxes rm ${sbx.id}`,
                     cause: error,
                 }), out.json));
                 return false;
@@ -706,11 +733,11 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
                 ...(spend.pilot ? [pilotFunding(spend.pilot)] : []),
                 ...(trialLeft > 0
                     ? [
-                        `included usage, ${trialLeft.toLocaleString("en-US", { maximumFractionDigits: 1 })} hours left without credit`,
+                        `free usage, ${trialLeft.toLocaleString("en-US", { maximumFractionDigits: 1 })} hours left without credit`,
                     ]
                     : []),
                 ...(credit > 0n ? [`${dollars(credit)} of credit`] : []),
-            ].join("; ") || "no included usage or credit left: runtime billing";
+            ].join("; ") || "no free usage or credit left: runtime billing";
         print(table([
             ["organization", who.orgName ? `${who.orgName} (${who.orgId})` : who.orgId],
             ...(who.role ? [["role", who.role]] : []),
@@ -1015,6 +1042,10 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         product = "ssh";
         return (await import("./ssh.js")).sshCommand(rest, env, out, () => client(env), me);
     }
+    if (nested && command === "code") {
+        product = "ssh";
+        return (await import("./ssh.js")).editorCommand(rest, env, out, () => client(env), me);
+    }
     if (command === "port-forward" || command === "forward") {
         product = "ssh";
         return (await import("./ssh.js")).portForwardCommand(rest, out, () => client(env), me);
@@ -1049,7 +1080,7 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
     }
     throw unknown("command", command, COMMANDS);
 }
-/** `runtime usage` for a person: the balance, the included usage and what each kind
+/** `runtime usage` for a person: the balance, the free usage and what each kind
  * of resource was charged, in dollars. --json keeps every figure, and each
  * resource with its rates and CPU time. */
 /** One row per resource, for a spreadsheet: when it ran, how big it was, how
@@ -1104,15 +1135,15 @@ export function usageCsv(u) {
 /** Milliseconds as hours, to a tenth: "8,731.2". */
 const hours = (ms) => (ms / 3_600_000).toLocaleString("en-US", { maximumFractionDigits: 1 });
 /** The machine time left without credit, as `runtime usage` and `runtime
- * limits` say it: this month's included usage, as hours at 2 vCPU and 4 GiB,
+ * limits` say it: this month's free usage, as hours at 2 vCPU and 4 GiB,
  * or for an account given free hours before 5 October 2026, those hours too. */
 function trialLeft(trial) {
     const renews = trial.renewsAt ? `, renews ${trial.renewsAt.slice(0, 10)}` : "";
     return trial.totalMs > 0
-        ? `${hours(trial.availableMs)} hours left (${hours(trial.totalMs)} free hours given before 5 October 2026, and the included usage${renews})`
+        ? `${hours(trial.availableMs)} hours left (${hours(trial.totalMs)} free hours given before 5 October 2026, and the free usage${renews})`
         : `${hours(trial.availableMs)} hours at 2 vCPU and 4 GiB left this month${renews}`;
 }
-/** This month's included usage, one row per product, as `runtime usage`
+/** This month's free usage, one row per product, as `runtime usage`
  * says it. */
 function allowanceRows(allowances) {
     const amount = (n) => n.toLocaleString("en-US", { maximumFractionDigits: 1 });
@@ -1598,6 +1629,28 @@ async function sandbox(argv, env, out) {
     const use = async (id) => SANDBOX_UUID.test(id ?? "")
         ? new SandboxHandle(runtime.transport, { id })
         : get(id);
+    /* `stop --label` and `rm --label`: every sandbox with all the labels, each
+       named with what happened to it; exits 1 if any failed. */
+    const byLabel = (words) => words.some((word) => /^--label(=|$)/.test(word));
+    const everyLabelled = async (act, words) => {
+        const args = parse(words, [], ["label"]);
+        if (args.positional.length)
+            throw usage("Give a sandbox id or --label, not both.");
+        const labels = pairs(args, "label");
+        const { done, failed } = act === "stop"
+            ? await runtime.sandboxes.stopAll({ labels }).then((r) => ({ ...r, done: r.stopped }))
+            : await runtime.sandboxes.deleteAll({ labels }).then((r) => ({ ...r, done: r.deleted }));
+        const past = act === "stop" ? "stopped" : "deleted";
+        const said = (error) => (error instanceof Error ? error.message : String(error));
+        print([
+            done.length || failed.length
+                ? `${done.length} ${past}${failed.length ? `, ${failed.length} failed` : ""}.`
+                : `No ${act === "stop" ? "live " : ""}sandbox has those labels.`,
+            ...done.map((id) => `${id} ${past}`),
+            ...failed.map((f) => `${f.id} failed: ${said(f.error)}`),
+        ].join("\n"), { [past]: done, failed: failed.map((f) => ({ id: f.id, error: said(f.error) })) });
+        return failed.length ? 1 : 0;
+    };
     switch (verb) {
         case "create": {
             const args = parse(rest, CREATE_FLAGS, CREATE_VALUES);
@@ -1681,6 +1734,8 @@ async function sandbox(argv, env, out) {
         }
         case "rm":
         case "delete": {
+            if (byLabel(rest))
+                return everyLabelled("delete", rest);
             const sbx = await use(need(rest[0], `a sandbox, e.g. ${me} sandboxes rm <id>`));
             const gone = await sbx.delete();
             print(`${gone.id} deleted`, gone);
@@ -1690,23 +1745,8 @@ async function sandbox(argv, env, out) {
         case "pause":
         case "wake":
         case "restart": {
-            if (verb === "stop" && rest.some((word) => /^--label(=|$)/.test(word))) {
-                const args = parse(rest, [], ["label"]);
-                if (args.positional.length)
-                    throw usage("Give a sandbox id or --label, not both.");
-                const { stopped, failed } = await runtime.sandboxes.stopAll({
-                    labels: pairs(args, "label"),
-                });
-                const said = (error) => (error instanceof Error ? error.message : String(error));
-                print([
-                    stopped.length || failed.length
-                        ? `${stopped.length} stopped${failed.length ? `, ${failed.length} failed` : ""}.`
-                        : "No live sandbox has those labels.",
-                    ...stopped.map((id) => `${id} stopped`),
-                    ...failed.map((f) => `${f.id} failed: ${said(f.error)}`),
-                ].join("\n"), { stopped, failed: failed.map((f) => ({ id: f.id, error: said(f.error) })) });
-                return failed.length ? 1 : 0;
-            }
+            if (verb === "stop" && byLabel(rest))
+                return everyLabelled("stop", rest);
             const sbx = await get(rest[0]);
             await sbx[verb]();
             print(`${sbx.id} ${sbx.state}`, sbx.info);
@@ -1823,6 +1863,8 @@ async function sandbox(argv, env, out) {
                 "auto-wake",
                 "persistent",
                 "max-total-cost",
+                "timeout",
+                "on-timeout",
             ]);
             const sbx = await get(args.positional[0]);
             const onOff = (name) => {
@@ -1833,6 +1875,9 @@ async function sandbox(argv, env, out) {
                     throw usage(`--${name} takes on or off.`);
                 return value === "on";
             };
+            const onTimeout = flag(args, "on-timeout")
+                ? oneOf(args, "on-timeout", ["pause", "stop", "delete"])
+                : undefined;
             const cost = flag(args, "max-total-cost");
             if (cost !== undefined && cost !== "none" && !/^\d+(\.\d{1,6})?$/.test(cost))
                 throw usage("--max-total-cost takes dollars, such as 25 or 2.50, or none.");
@@ -1854,9 +1899,13 @@ async function sandbox(argv, env, out) {
                     : {
                         maxTotalCostMicros: cost === "none" ? null : usdMicros(args, "max-total-cost"),
                     }),
+                ...(integer(args, "timeout") !== undefined
+                    ? { timeoutSeconds: integer(args, "timeout") }
+                    : {}),
+                ...(onTimeout === undefined ? {} : { onTimeout }),
             };
             if (!Object.keys(settings).length)
-                throw usage("Say what to change: --name, --label, --env, --unset-env, --idle-pause, --auto-wake, --persistent or --max-total-cost.");
+                throw usage("Say what to change: --name, --label, --env, --unset-env, --idle-pause, --auto-wake, --persistent, --max-total-cost, --timeout or --on-timeout.");
             await sbx.update(settings);
             print(describe(sbx.info), sbx.info);
             return 0;
@@ -2160,15 +2209,24 @@ function attachment(spec) {
 /** A secret's value, from standard input only, so it never sits in shell
  * history or a process list. Piped: everything, less one trailing newline.
  * A terminal: one line, not shown. */
+/** A pasted secret as the header it becomes: no line breaks (a token copied
+ * from a terminal arrives wrapped), no bracketed-paste markers, no space at
+ * either end. 13 October 2026: a user's pasted Claude token was refused as
+ * "not visible ASCII". A header cannot hold a line break, so none is lost. */
+export function cleanSecret(raw) {
+    return raw
+        .replaceAll("\u001b[200~", "")
+        .replaceAll("\u001b[201~", "")
+        .replace(/[\r\n]/g, "")
+        .trim();
+}
 async function readSecret() {
     const stdin = process.stdin;
     if (!stdin.isTTY) {
         const chunks = [];
         for await (const chunk of stdin)
             chunks.push(chunk);
-        return Buffer.concat(chunks)
-            .toString("utf8")
-            .replace(/\r?\n$/, "");
+        return cleanSecret(Buffer.concat(chunks).toString("utf8"));
     }
     process.stderr.write("Value (not shown), then Enter: ");
     stdin.setRawMode(true);
@@ -2181,7 +2239,7 @@ async function readSecret() {
                     if (char === "\r" || char === "\n") {
                         stdin.off("data", onData);
                         process.stderr.write("\n");
-                        return done(value);
+                        return done(cleanSecret(value));
                     }
                     if (char === "\u0003") {
                         stdin.off("data", onData);
@@ -2224,6 +2282,48 @@ export function parseSecretRules(values) {
     }
     return [...byMethods.values()];
 }
+/** `--only-label role=hub,tier=x --only-sandbox <id>`: a sandbox whose labels
+ * hold every pair of any one --only-label gets the secret, and so does each
+ * --only-sandbox. `--all-sandboxes`: every sandbox again. Nothing: undefined,
+ * so a replacement keeps the scope it has. */
+export function parseSecretScope(labels, sandboxes, all) {
+    if (all && (labels?.length || sandboxes?.length))
+        throw usage("--all-sandboxes gives the secret to every sandbox; leave out --only-label and --only-sandbox.");
+    if (all)
+        return {};
+    if (!labels?.length && !sandboxes?.length)
+        return undefined;
+    const selectors = (labels ?? []).map((text) => {
+        const selector = {};
+        for (const pair of text.split(",").filter(Boolean)) {
+            const at = pair.indexOf("=");
+            if (at < 1)
+                throw usage(`--only-label takes key=value pairs, such as role=hub; got "${text}".`);
+            selector[pair.slice(0, at).trim()] = pair.slice(at + 1).trim();
+        }
+        if (!Object.keys(selector).length)
+            throw usage(`--only-label takes key=value pairs, such as role=hub; got "${text}".`);
+        return selector;
+    });
+    for (const id of sandboxes ?? [])
+        if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id))
+            throw usage(`--only-sandbox takes a sandbox id; "${id}" is not one.`);
+    return {
+        ...(selectors.length ? { labels: selectors } : {}),
+        ...(sandboxes?.length
+            ? { sandboxes: [...new Set(sandboxes.map((id) => id.toLowerCase()))] }
+            : {}),
+    };
+}
+/** Who gets a secret, in a few words. */
+export const scopeText = (only) => only && (only.labels?.length || only.sandboxes?.length)
+    ? [
+        ...(only.labels ?? []).map((selector) => Object.entries(selector)
+            .map(([key, value]) => `${key}=${value}`)
+            .join(",")),
+        ...(only.sandboxes ?? []),
+    ].join(" | ")
+    : "all";
 const ruleText = (rules) => rules?.length
     ? rules
         .map((rule) => `${rule.methods ? `${rule.methods.join(",")} ` : ""}${rule.paths.join(" ")}`)
@@ -2233,17 +2333,18 @@ export async function secretsCommand(argv, env, out,
 /** Tests give the value here; the CLI reads standard input. */
 read = readSecret) {
     const [verb, ...rest] = argv;
-    const args = parse(rest, ["jobs"], ["host", "header", "format", "allow", "value", "version"]);
+    const args = parse(rest, ["jobs", "all-sandboxes"], ["host", "header", "format", "allow", "value", "version", "only-label", "only-sandbox"]);
     const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
     const rows = (list) => list.length
         ? table([
-            ["name", "hosts", "header", "placeholder", "allow", "jobs"],
+            ["name", "hosts", "header", "placeholder", "allow", "sandboxes", "jobs"],
             ...list.map(({ name, sandboxes: secret, jobs }) => [
                 name,
                 secret ? secret.hosts.join(",") : "-",
                 secret?.header ? `${secret.header}: ${secret.format ?? "{value}"}` : "-",
                 secret ? secret.placeholder : "-",
                 secret ? ruleText(secret.rules) : "-",
+                secret ? scopeText(secret.only) : "-",
                 jobs ? `v${jobs.version}` : "-",
             ]),
         ])
@@ -2266,7 +2367,13 @@ read = readSecret) {
         const name = need(args.positional[0], "the secret's name, such as OPENAI_API_KEY");
         const hosts = args.flags.get("host") ?? [];
         const jobs = verb === "rotate" || has(args, "jobs");
-        if (verb === "rotate" && (hosts.length || args.flags.has("header") || args.flags.has("allow")))
+        if (verb === "rotate" &&
+            (hosts.length ||
+                args.flags.has("header") ||
+                args.flags.has("allow") ||
+                args.flags.has("only-label") ||
+                args.flags.has("only-sandbox") ||
+                args.flags.has("all-sandboxes")))
             throw usage(`rotate replaces the copy for jobs. ${jobsOnly}; to change the sandboxes' copy, set it again with --host.`);
         if (!hosts.length && !jobs)
             throw usage("Give --host once for each host the value may go to, such as --host api.openai.com, and/or --jobs to let scheduled jobs use it.");
@@ -2290,16 +2397,20 @@ read = readSecret) {
         const format = flag(args, "format");
         const allow = args.flags.get("allow");
         const rules = allow ? parseSecretRules(allow) : undefined;
+        const only = parseSecretScope(args.flags.get("only-label"), args.flags.get("only-sandbox"), has(args, "all-sandboxes"));
         const saved = await runtime.secrets.set(name, {
             value,
             hosts,
             ...(header ? { header } : {}),
             ...(format ? { format } : {}),
             ...(rules ? { rules } : {}),
+            ...(only ? { only } : {}),
             ...(jobs ? { jobs: true } : {}),
         });
         print([
-            `Stored ${saved.name}. Sandboxes see ${saved.name}=${saved.placeholder}.`,
+            saved.only
+                ? `Stored ${saved.name}. Only these sandboxes get it and see ${saved.name}=${saved.placeholder}: ${scopeText(saved.only)}.`
+                : `Stored ${saved.name}. Every sandbox sees ${saved.name}=${saved.placeholder}.`,
             saved.header
                 ? `Requests to ${saved.hosts.join(", ")} get ${saved.header}: ${saved.format ?? "{value}"} over HTTPS.`
                 : `Over HTTPS to ${saved.hosts.join(", ")}, the placeholder becomes the value in the Authorization header or another credential header (x-api-key, x-goog-api-key); in the URL it stays a placeholder.`,
@@ -2315,6 +2426,15 @@ read = readSecret) {
         ].join("\n"), saved);
         return 0;
     }
+    if (verb === "scope") {
+        const name = need(args.positional[0], "the secret's name");
+        const only = parseSecretScope(args.flags.get("only-label"), args.flags.get("only-sandbox"), has(args, "all-sandboxes"));
+        if (!only)
+            throw usage("Say who gets it: --only-label key=value (once per selector), --only-sandbox <id>, or --all-sandboxes.");
+        const saved = await (await client(env)).secrets.scope(name, only);
+        print(`${saved.name}: ${saved.only ? `only ${scopeText(saved.only)}` : "every sandbox"}.${saved.enforced ? "" : " A host is catching up; running sandboxes have it within a minute."}`, saved);
+        return 0;
+    }
     if (verb === "reveal") {
         const name = need(args.positional[0], "the secret's name");
         const version = flag(args, "version");
@@ -2330,7 +2450,7 @@ read = readSecret) {
         print(`Deleted ${name}${removed.from.length > 1 ? " for sandboxes and jobs" : removed.from[0] === "jobs" ? " for jobs" : ""}.`, removed);
         return 0;
     }
-    throw usage("secrets takes set, ls, get, rotate, reveal or rm. Run `runtime help`.");
+    throw usage("secrets takes set, scope, ls, get, rotate, reveal or rm. Run `runtime help`.");
 }
 async function readInput(source) {
     if (source !== "-")
@@ -2482,23 +2602,30 @@ async function browser(sbx, argv, out) {
 }
 const KEYS_HELP = `runtime keys <command>
 
-  create [--name <name>] [--read-only] [--daily-limit <usd>] [--account-wide]
-      A new API key, for a CI runner or any place with no browser. Prints a link
-      and a code; an account owner approves the key in the browser, seeing its
-      name, access and limit. The key is printed once, alone on stdout, and
-      lasts until revoked. --json prints it as JSON, still alone on stdout.
-      --account-wide makes a key that sees and uses every sandbox and other
-      resource in the account, whichever key made it; only an owner or admin
-      can approve one. Without it, a key sees only what it makes.
+  create [--name <name>] [--read-only] [--daily-limit <usd>] [--account-wide] [--browser]
+      A new API key. With a key saved on this machine (or RUNTIME_API_KEY), that
+      key makes it at once, with no browser: a key per worker in an agent swarm.
+      It never has more than the key that made it, and when that key has a daily
+      limit, the keys it made share it, so each needs --daily-limit. Without a
+      saved key, or with --browser, it prints a link and a code and an account
+      owner approves the key in the browser. The key is printed once, alone on
+      stdout, and lasts until revoked. --json prints it as JSON, still alone on
+      stdout. --account-wide makes a key that sees and uses every sandbox and
+      other resource in the account; without it, a key sees only what it makes.
+  ls                      This key and the keys it made, with what each spent today
+  usage <keyId>           What one of them has spent and holds
+  revoke <keyId>          Revoke one: a worker's key when the worker is done
 
-  runtime keys create --name ci --daily-limit 25 | gh secret set RUNTIME_API_KEY
+  runtime keys create --name worker-1 --daily-limit 5
+  runtime keys create --name ci --daily-limit 25 --browser | gh secret set RUNTIME_API_KEY
 
-List, limit and revoke keys at https://withruntime.com/account/keys.
+Making, listing and revoking keys with a key needs one an owner or admin made.
+Every key is also at https://withruntime.com/account/keys.
 `;
-/* `runtime keys create`: a key made from the terminal and approved in the
-   browser. Marc, 23 September 2026; ARCHITECTURE.md section 10, "Keys from the
-   terminal". Only the options the keys page offers. No key can list, create or
-   revoke keys through the API, so `ls` and `revoke` send you to the page. */
+/* `runtime keys`: a key made from the terminal, by this machine's key with no
+   browser (14 October 2026), or approved in the browser
+   (23 September 2026; ARCHITECTURE.md section 10, "Keys from the
+   terminal"). Only the options the keys page offers. */
 /* `runtime account`: the accounts this machine is connected to, and which one
    every command uses (ARCHITECTURE.md section 3.9). Each is its own saved
    connection with its own key; the SDK itself stays key-based. */
@@ -2604,19 +2731,63 @@ async function nameSaved(env) {
             await store.save({ ...again, orgName: who.orgName });
     }
 }
+/** Dollars from integer microdollars, for a person to read: "$5.00". */
+const usdOf = (micros) => `$${(Number(BigInt(micros) / 10000n) / 100).toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
 async function keys(argv, env, out) {
     product = "keys";
     const [verb, ...rest] = argv;
+    const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
     if (!verb || verb === "help" || verb === "--help" || verb === "-h") {
         out.write(out.json ? JSON.stringify({ usage: named(KEYS_HELP) }) : named(KEYS_HELP));
         return 0;
     }
-    if (verb === "ls" || verb === "list" || verb === "revoke")
-        throw usage("List and revoke keys at https://withruntime.com/account/keys. No key can list or revoke keys.");
+    if (verb === "ls" || verb === "list") {
+        const args = parse(rest, [], []);
+        if (args.flags.size || args.positional.length)
+            throw usage(`Usage: ${named("runtime keys ls")}`);
+        const all = await (await client(env)).keys.list();
+        print(all.length
+            ? table([
+                ["KEY", "NAME", "ACCESS", "REACH", "DAILY LIMIT", "LAST 24H", "MADE BY", "STATE"],
+                ...all.map((k) => [
+                    k.keyId,
+                    k.name,
+                    k.access,
+                    k.reach,
+                    k.dailyLimitMicros === null ? "none" : usdOf(k.dailyLimitMicros),
+                    usdOf(k.dailyUsedMicros),
+                    k.madeBy ?? "website",
+                    k.revokedAt ? "revoked" : "live",
+                ]),
+            ])
+            : "No keys.", all);
+        return 0;
+    }
+    if (verb === "revoke" || verb === "rm" || verb === "usage") {
+        const args = parse(rest, [], []);
+        const id = args.positional[0];
+        if (!id || args.positional.length > 1 || args.flags.size)
+            throw usage(`Usage: ${named(`runtime keys ${verb} <keyId>`)}`);
+        const api = (await client(env)).keys;
+        if (verb === "usage") {
+            const used = await api.usage(id);
+            print([
+                `${used.name} (${used.keyId})${used.revokedAt ? ", revoked" : ""}`,
+                `  last 24 hours  ${usdOf(used.dailyUsedMicros)}${used.dailyLimitMicros === null ? "" : ` of ${usdOf(used.dailyLimitMicros)}`}`,
+                `  spent          ${usdOf(used.spentMicros)}`,
+                `  held now       ${usdOf(used.heldMicros)}`,
+                `  sandboxes      ${used.runningSandboxes} running, ${used.resources} kept in all`,
+            ].join("\n"), used);
+            return 0;
+        }
+        const revoked = await api.revoke(id);
+        print(`Revoked ${revoked.keyId}. It stops working within ten seconds.`, revoked);
+        return 0;
+    }
     if (verb !== "create")
-        throw unknown("keys command", verb, ["create"]);
-    const args = parse(rest, ["read-only", "account-wide"], ["name", "daily-limit"]);
-    const known = new Set(["name", "read-only", "daily-limit", "account-wide"]);
+        throw unknown("keys command", verb, ["create", "ls", "usage", "revoke"]);
+    const args = parse(rest, ["read-only", "account-wide", "browser"], ["name", "daily-limit"]);
+    const known = new Set(["name", "read-only", "daily-limit", "account-wide", "browser"]);
     for (const name of args.flags.keys())
         if (!known.has(name))
             throw usage(`Unknown option --${name}.`);
@@ -2629,26 +2800,48 @@ async function keys(argv, env, out) {
     if (readOnly && has(args, "account-wide"))
         throw usage("A read-only key already sees the whole account, so it takes no --account-wide.");
     const { createKey, dailyLimitMicros } = await import("./keys.js");
-    const created = await createKey({
+    const request = {
         name: flag(args, "name") ?? (readOnly ? "Read-only key" : "My API key"),
         access: readOnly ? "read" : "full",
         ...(has(args, "account-wide") ? { reach: "account" } : {}),
         dailyLimitMicros: limit === undefined ? null : dailyLimitMicros(limit),
-    }, env, { notify: out.error });
-    const { confirm, ...key } = created;
-    out.write(out.json ? JSON.stringify(key) : key.key);
+    };
+    /* A key on this machine makes the new one itself, with no browser: an
+       agent with no person, a swarm's coordinator (14 October 2026). */
+    const saved = has(args, "browser")
+        ? null
+        : env.RUNTIME_API_KEY || (await connectionStore(env).read())?.key || null;
+    let key;
+    if (saved) {
+        key = await new Runtime({
+            apiKey: saved,
+            baseUrl: env.RUNTIME_API_URL,
+            maxRetries: 4,
+        }).keys.create({
+            name: request.name,
+            access: request.access,
+            reach: request.reach ?? "agent",
+            dailyLimitMicros: request.dailyLimitMicros,
+        });
+    }
+    else
+        key = await createKey(request, env, { notify: out.error });
+    const { confirm, ...made } = key;
+    out.write(out.json ? JSON.stringify(made) : made.key);
     const terms = [
-        key.access === "read" ? "read only" : "full access",
-        key.reach === "account" ? "account-wide" : undefined,
-        key.access === "read"
+        made.access === "read" ? "read only" : "full access",
+        made.reach === "account" ? "account-wide" : undefined,
+        made.access === "read"
             ? undefined
-            : key.dailyLimitMicros === null
+            : made.dailyLimitMicros === null
                 ? "no daily limit"
-                : `daily limit $${(Number(BigInt(key.dailyLimitMicros) / 10000n) / 100).toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`,
-        "until revoked",
+                : `daily limit ${usdOf(made.dailyLimitMicros)}`,
+        made.expires ? `until ${made.expires}` : "until revoked",
     ].filter(Boolean);
-    out.error(`Created key "${key.name}" (${terms.join(", ")}). Store it now: it is not shown again, and Runtime keeps only a hash of it.\nIn CI, give it to your jobs as RUNTIME_API_KEY from the secret store.`);
-    await confirm();
+    out.error(saved
+        ? `Created key "${made.name}" (${terms.join(", ")}), made by this machine's key. Store it now: it is not shown again, and Runtime keeps only a hash of it.\nGive it to one worker as RUNTIME_API_KEY; revoke it with ${named("runtime keys revoke")} ${made.keyId} when that worker is done.`
+        : `Created key "${made.name}" (${terms.join(", ")}). Store it now: it is not shown again, and Runtime keeps only a hash of it.\nIn CI, give it to your jobs as RUNTIME_API_KEY from the secret store.`);
+    await confirm?.();
     return 0;
 }
 const SNAPSHOT_HELP = `runtime snapshots <command>
@@ -2976,7 +3169,7 @@ read = readSecret) {
 const JOB_HELP = `runtime jobs <command>
 
   A job runs a command in a fresh sandbox, once or on a schedule. Each run spends
-  the included usage first, then credit at the sandbox rates.
+  the free usage first, then credit at the sandbox rates.
 
   create <name> (--cron "<min hour day month weekday>" [--timezone Europe/Berlin] | --at <time|now>)
          [--vcpu 2] [--memory 4096] [--disk 4096] [--cpu shared|reserved] [--cpu-floor <thousandths>]
@@ -3528,6 +3721,7 @@ const CREATE_VALUES = [
     "connect",
     "image",
     "snapshot",
+    "spread-from",
     "volume",
     "env",
 ];
@@ -3555,6 +3749,18 @@ function createInput(args) {
     return {
         ...(flag(args, "image") ? { image: flag(args, "image") } : {}),
         ...(flag(args, "snapshot") ? { snapshot: flag(args, "snapshot") } : {}),
+        ...(args.flags.has("spread-from")
+            ? {
+                spreadFrom: args.flags
+                    .get("spread-from")
+                    .flatMap((value) => value.split(","))
+                    .map((id) => {
+                    if (!id.trim())
+                        throw usage("--spread-from needs a non-empty value.");
+                    return id.trim();
+                }),
+            }
+            : {}),
         ...(args.flags.has("volume") ? { volumes: args.flags.get("volume").map(attachment) } : {}),
         ...(has(args, "no-internet") || rules.length
             ? {