withruntime 0.12.0 → 0.14.0

package/dist/cli.js

@@ -30,6 +30,8 @@ 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
@@ -143,6 +151,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)
@@ -242,7 +252,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: Marc'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 +271,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. */
@@ -706,11 +726,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]] : []),
@@ -1049,7 +1069,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 +1124,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 +1618,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 +1723,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 +1734,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);
@@ -2160,15 +2189,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: Marc'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 +2219,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 +2262,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 +2313,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 +2347,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 +2377,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 +2406,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 +2430,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 +2582,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 (Marc, 14 October 2026, agent swarms), or approved in the browser
+   (Marc, 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 +2711,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 +2780,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 (Marc, 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 +3149,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>]

package/dist/credentials.d.ts

@@ -26,6 +26,9 @@ export declare function connectionOrigins(env: NodeJS.ProcessEnv): {
 /** Browser-issued production credentials must only reach the production API.
  * CLI and MCP share this boundary, including resumed device requests. */
 export declare function checkBrowserOrigins(origins: ReturnType<typeof connectionOrigins>): void;
+/** A wallet account's key, from its claim, saved as this machine's connection
+ * (the MCP bridge's runtime_wallet_claim; `billing claim` saves the same). */
+export declare function saveWalletConnection(env: NodeJS.ProcessEnv, key: string, orgId: string): Promise<void>;
 /** Private user storage, outside project files. Nothing reading this module
  * returns a secret to CLI output. Store names bind credentials to both origins. */
 export declare function connectionStore(env: NodeJS.ProcessEnv, directory?: string): {

package/dist/credentials.js

@@ -37,6 +37,21 @@ export function checkBrowserOrigins(origins) {
         (local(origins.auth) && local(origins.api))))
         throw new Error("Browser login supports Runtime's production endpoints or local test endpoints. Check RUNTIME_AUTH_URL and RUNTIME_API_URL.");
 }
+/** A wallet account's key, from its claim, saved as this machine's connection
+ * (the MCP bridge's runtime_wallet_claim; `billing claim` saves the same). */
+export function saveWalletConnection(env, key, orgId) {
+    const origins = connectionOrigins(env);
+    checkBrowserOrigins(origins);
+    return connectionStore(env).save({
+        version: 1,
+        apiOrigin: origins.api,
+        authOrigin: origins.auth,
+        key,
+        connectionId: "pasted",
+        orgId,
+        agentName: "Wallet agent",
+    });
+}
 function defaultDirectory(env) {
     const root = env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
     if (!isAbsolute(root))

package/dist/daytona/daytona.d.ts

@@ -183,7 +183,7 @@ export declare class Daytona implements AsyncDisposable {
     [Symbol.asyncDispose](): Promise<void>;
     /** Creates a sandbox and waits until it runs, with Daytona's defaults: 1
      * vCPU, 1 GiB, 3 GiB disk, pausing after 15 minutes without calls. Funding
-     * is left to Runtime: the included usage first, then prepaid credit, exactly as withruntime's own create. */
+     * is left to Runtime: the free usage first, then prepaid credit, exactly as withruntime's own create. */
     create(params?: CreateSandboxFromSnapshotParams | CreateSandboxFromImageParams, options?: {
         timeout?: number;
         onSnapshotCreateLogs?: (chunk: string) => void;

package/dist/daytona/daytona.js

@@ -184,7 +184,7 @@ export class Daytona {
     async [Symbol.asyncDispose]() { }
     /** Creates a sandbox and waits until it runs, with Daytona's defaults: 1
      * vCPU, 1 GiB, 3 GiB disk, pausing after 15 minutes without calls. Funding
-     * is left to Runtime: the included usage first, then prepaid credit, exactly as withruntime's own create. */
+     * is left to Runtime: the free usage first, then prepaid credit, exactly as withruntime's own create. */
     async create(params = {}, options = {}) {
         refuseCreate(params);
         const timeout = options.timeout;

package/dist/e2b/sandbox.d.ts

@@ -133,7 +133,7 @@ export declare class Sandbox {
     protected get client(): Runtime;
     /** Creates a sandbox from `template` (default "base", Runtime's stock image)
      * with E2B's default machine, 2 vCPU and 512 MiB, and waits until it runs.
-     * Funding is left to Runtime: the included usage first, then prepaid credit, exactly as withruntime's own create. */
+     * Funding is left to Runtime: the free usage first, then prepaid credit, exactly as withruntime's own create. */
     static create<S extends typeof Sandbox>(this: S, opts?: SandboxOpts): Promise<InstanceType<S>>;
     static create<S extends typeof Sandbox>(this: S, template: string, opts?: SandboxOpts): Promise<InstanceType<S>>;
     /** Connects to a sandbox by id, waking it if it is paused, as E2B does. A

package/dist/errors.d.ts

@@ -13,7 +13,7 @@ export declare const DELIBERATE: ReadonlySet<string>;
  * minutes when it has none), however many retries it allows otherwise. */
 export declare const NOTHING_RAN: ReadonlySet<string>;
 /** Refusals of a create that clear when a sandbox stops or pauses, or a host
- * frees room: an account without credit's eight at once and its total, an
+ * frees room: an account without credit's four at once and its total, an
  * email domain's, the account's quota and the region's capacity. `sandboxes.create` waits them out, retrying
  * with the same key and input, for up to `waitForCapacityMs`. */
 export declare const WAITS_FOR_ROOM: ReadonlySet<string>;

package/dist/errors.js

@@ -27,7 +27,7 @@ export const NOTHING_RAN = new Set(["guest_busy", "busy", "rate_limited"]);
  * account without credit stops. */
 const PASSING = new Set(["no_capacity", "no_credit_running_limit", "no_credit_total_limit"]);
 /** Refusals of a create that clear when a sandbox stops or pauses, or a host
- * frees room: an account without credit's eight at once and its total, an
+ * frees room: an account without credit's four at once and its total, an
  * email domain's, the account's quota and the region's capacity. `sandboxes.create` waits them out, retrying
  * with the same key and input, for up to `waitForCapacityMs`. */
 export const WAITS_FOR_ROOM = new Set([

package/dist/index.d.ts

@@ -16,7 +16,7 @@ export { Page } from "./page.js";
 export type { KeyLimits } from "./products/limits.js";
 export type { AuditEvent, AuditPage } from "./products/audit.js";
 export type { UsageExportQuery, UsageExportRow, UsageExportPage, } from "./products/observability.js";
-export type { JobSecret, Secret, SecretRule, SecretUse, SetSecret } from "./products/secrets.js";
+export type { JobSecret, Secret, SecretRule, SecretScope, SecretUse, SetSecret, } from "./products/secrets.js";
 export { SecretPartlyStoredError } from "./products/secrets.js";
 export type { McpCatalogEntry, McpGateway, McpServerRequest } from "./products/mcp.js";
 export type { FileEvent, FileEventType, WatchHandle, WatchNotice, WatchOptions, } from "./products/watch.js";
@@ -74,4 +74,5 @@ export type { RuntimeOptions as ClientOptions };
 export { identityToken, type IdentityToken } from "./identity.js";
 export { openWalletAccount, claimWalletAccount, type OpenedWalletAccount, type WalletClaim, type WalletOptions, } from "./wallet.js";
 export type { Topup } from "./products/billing.js";
+export type { NewKey, MadeKey, ListedKey, KeyUsage } from "./products/api-keys.js";
 export type { SsoConnection, SsoStatus } from "./products/sso.js";