withruntime 0.18.0 → 0.23.0

package/dist/apps-cli.js

@@ -3,6 +3,7 @@ import { RuntimeError } from "./errors.js";
 import { logStream } from "./terminal.js";
 import { apps, } from "./products/apps.js";
 import { builds, } from "./products/builds.js";
+import { containers, } from "./products/containers.js";
 export const APP_HELP = `runtime apps <command>
 
   An App serves your web server from an image or a build. Copies start when
@@ -73,6 +74,34 @@ Examples
   runtime builds run <repoId> --ref main
   runtime builds ls --commit $(git rev-parse HEAD)
 `;
+export const CONTAINER_HELP = `runtime containers <command>
+
+  A container runs one OCI image's process on its own microVM, billed at the
+  sandbox rates. It never sleeps unless --sleep; on exit it restarts when it
+  serves a port, else it stops (--on-exit sets either).
+  In a private beta: outside it, each command says how to ask to join.
+
+  create <image> --vcpu <1-16> --memory <128-65536> [--name <name>] [--label key=value]...
+         [--env KEY[=VALUE]]... [--entrypoint <program>] [--workdir /app] [--user <user>]
+         [--port <1-65535>] [--on-exit restart|stop] [--sleep] [-- <command...>]
+                                              Run it; prints its id. The image's digest is pinned.
+                                              --env KEY alone sends KEY's value from your environment.
+                                              --entrypoint drops the image's command; after --, the
+                                              command replaces the image's
+  ls [--all] [--state <state>]... [--label key=value]...
+                                              Your containers: all but deleting and deleted, unless
+                                              --all or --state
+  get <container>                             One container, in full (an id or its name): its
+                                              environment's names, never their values
+  update <container> [--name <name>] [--label key=value]...
+                                              Rename it or replace its labels
+  rm <container> [--wait]                     Delete it and stop its process; --wait: until deleted
+
+Examples
+  runtime containers create nginx:1.27 --vcpu 1 --memory 512 --name web
+  runtime containers create python:3.12 --vcpu 1 --memory 1024 -- python3 -m http.server 8000
+  runtime containers rm web --wait
+`;
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const when = (ms) => (ms == null ? "-" : new Date(ms).toISOString());
 const ENDED = ["succeeded", "failed", "cancelled", "superseded"];
@@ -562,3 +591,147 @@ export async function buildsCommand(argv, out, client, kit) {
         "logs",
     ]);
 }
+const CONTAINER_STATES = [
+    "waiting",
+    "running",
+    "sleeping",
+    "stopped",
+    "failed",
+    "deleting",
+    "deleted",
+];
+const CONTAINER_VALUES = [
+    "vcpu",
+    "memory",
+    "name",
+    "label",
+    "env",
+    "entrypoint",
+    "workdir",
+    "user",
+    "port",
+    "on-exit",
+];
+export async function containersCommand(argv, env, out, client, kit) {
+    const { parse, flag, has, integer, need, pairs, envPairs, table, usage } = kit;
+    const [verb, ...rest] = argv;
+    const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
+    if (!verb || verb === "help" || verb === "--help") {
+        print(named(CONTAINER_HELP), { usage: named(CONTAINER_HELP) });
+        return 0;
+    }
+    const api = containers((await client()).transport);
+    /** A container's id from its id or its name: a name is looked up among the
+     * containers not deleted, and must be one container's alone. */
+    const idOf = async (target) => {
+        const given = need(target, "a container's id or name");
+        if (UUID.test(given))
+            return given;
+        const found = (await api.list({ name: given })).data;
+        if (found.length === 1)
+            return found[0].id;
+        throw usage(found.length
+            ? `${found.length} containers are named ${given}; give one's id (${me} containers ls).`
+            : `No container is named ${given}. Your containers: ${me} containers ls`);
+    };
+    switch (verb) {
+        case "create": {
+            const args = parse(rest, ["sleep"], CONTAINER_VALUES);
+            if (args.positional.length !== 1)
+                throw usage(`Give one image: ${me} containers create nginx:1.27 --vcpu 1 --memory 512 [-- <command...>]`);
+            const image = args.positional[0];
+            const vcpu = integer(args, "vcpu");
+            const memoryMiB = integer(args, "memory");
+            if (vcpu === undefined || memoryMiB === undefined)
+                throw usage(`Give --vcpu and --memory: ${me} containers create ${image} --vcpu 1 --memory 512`);
+            const onExit = flag(args, "on-exit");
+            if (onExit !== undefined && onExit !== "restart" && onExit !== "stop")
+                throw usage("--on-exit takes restart or stop.");
+            const port = integer(args, "port");
+            const entrypoint = flag(args, "entrypoint");
+            const workingDir = flag(args, "workdir");
+            const user = flag(args, "user");
+            const name = flag(args, "name");
+            const input = {
+                image,
+                vcpu,
+                memoryMiB,
+                ...(name === undefined ? {} : { name }),
+                ...(args.flags.has("label") ? { labels: pairs(args, "label") } : {}),
+                ...(args.flags.has("env") ? { env: envPairs(args, env) } : {}),
+                ...(entrypoint === undefined ? {} : { entrypoint: [entrypoint] }),
+                ...(args.rest?.length ? { command: args.rest } : {}),
+                ...(workingDir === undefined ? {} : { workingDir }),
+                ...(user === undefined ? {} : { user }),
+                ...(port === undefined ? {} : { port }),
+                ...(onExit === undefined ? {} : { onExit }),
+                ...(has(args, "sleep") ? { sleep: true } : {}),
+            };
+            const made = await api.create(input);
+            if (!out.json)
+                out.error(`${made.name ?? made.id} is ${made.state}, running ${made.image}. Read it: ${me} containers get ${made.name ?? made.id}`);
+            print(made.id, made);
+            return 0;
+        }
+        case "ls":
+        case "list": {
+            const args = parse(rest, ["all"], ["state", "label"]);
+            const states = args.flags.get("state");
+            for (const state of states ?? [])
+                if (!CONTAINER_STATES.includes(state))
+                    throw usage(`--state takes ${CONTAINER_STATES.join(", ")}.`);
+            // --label key=value, as the list's key:value filters.
+            const labels = Object.entries(pairs(args, "label")).map(([k, v]) => `${k}:${v}`);
+            const all = await (await api.list({
+                limit: 100,
+                ...(states
+                    ? { state: states }
+                    : has(args, "all")
+                        ? { state: CONTAINER_STATES }
+                        : {}),
+                ...(labels.length ? { label: labels } : {}),
+            })).toArray(Infinity);
+            print(all.length
+                ? table([
+                    ["ID", "NAME", "STATE", "IMAGE", "PORT", "SIZE", "CREATED"],
+                    ...all.map((c) => [
+                        c.id,
+                        c.name ?? "-",
+                        c.state,
+                        c.image,
+                        c.port === null ? "-" : String(c.port),
+                        `${c.vcpu} vCPU, ${c.memoryMiB} MiB`,
+                        when(c.createdAt),
+                    ]),
+                ])
+                : `No containers. Run one: ${me} containers create nginx:1.27 --vcpu 1 --memory 512`, all);
+            return 0;
+        }
+        case "get": {
+            const found = await api.get(await idOf(rest[0]));
+            print(JSON.stringify(found, null, 2), found);
+            return 0;
+        }
+        case "update": {
+            const args = parse(rest, [], ["name", "label"]);
+            const id = await idOf(args.positional[0]);
+            const change = {
+                ...(flag(args, "name") === undefined ? {} : { name: flag(args, "name") }),
+                ...(args.flags.has("label") ? { labels: pairs(args, "label") } : {}),
+            };
+            if (!Object.keys(change).length)
+                throw usage(`Give --name or --label: ${me} containers update ${args.positional[0]} --name web`);
+            const updated = await api.update(id, change);
+            print(`${updated.name ?? updated.id} updated.`, updated);
+            return 0;
+        }
+        case "rm":
+        case "delete": {
+            const args = parse(rest, ["wait"], []);
+            const gone = await api.delete(await idOf(args.positional[0]), { wait: has(args, "wait") });
+            print(`${gone.name ?? gone.id} ${gone.state}.`, gone);
+            return 0;
+        }
+    }
+    throw kit.unknown("containers command", verb, ["create", "ls", "get", "update", "rm"]);
+}

package/dist/builds/index.d.ts

@@ -0,0 +1,10 @@
+/** `withruntime/builds`: Builds alone. An image built from a repository's
+ * commit, at the sandbox rates. In a private beta.
+ *
+ *   import { builds } from "withruntime/builds";
+ *   const client = builds(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime, type RuntimeOptions } from "../client.js";
+export type * from "../products/builds.js";
+/** `runtime.builds` of a client made with `options`. */
+export declare function builds(options?: RuntimeOptions): Runtime["builds"];

package/dist/builds/index.js

@@ -0,0 +1,11 @@
+/** `withruntime/builds`: Builds alone. An image built from a repository's
+ * commit, at the sandbox rates. In a private beta.
+ *
+ *   import { builds } from "withruntime/builds";
+ *   const client = builds(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime } from "../client.js";
+/** `runtime.builds` of a client made with `options`. */
+export function builds(options) {
+    return new Runtime(options).builds;
+}

package/dist/cli-words.js

@@ -26,6 +26,7 @@ const OPTIONS = {
     image: { flag: "--image" },
     snapshot: { flag: "--snapshot" },
     spreadFrom: { flag: "--spread-from" },
+    secrets: { flag: "--secret / --no-secrets" },
     volumes: { flag: "--volume" },
     network: { flag: "--allow / --deny / --connect / --no-internet" },
     maxCostMicros: { flag: "--max-cost", micros: true },

package/dist/cli.js

@@ -38,6 +38,7 @@ Account
   account switch <name|id>                     Use another of them for every command after
   account add                                  Connect another account (choose it in the browser)
   account close --confirm "<account name>"     Close the account for good (owner, key for every product)
+  account emails [<category> on|off]           Your optional emails from Runtime: own-deletions, billing, usage, tips
   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
@@ -54,6 +55,10 @@ Account
                                                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> --keep-value [--host <host>]... [--allow '[GET] /path']...
+                                               Narrow where it goes without its value: a subset of
+                                               its hosts, only requests its rules allow now.
+                                               Anything wider needs the value
   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
@@ -62,6 +67,9 @@ Account
   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
                                                never readable, by anyone
+  secrets share <NAME> --agent <id>... | --all | --none
+                                               Which of your keys may use the jobs copy besides the one
+                                               that stored it (ids: from 'me'); --all: every key
   secrets rm <NAME>                            Delete a secret, every copy
   keys create [--name <name>] [--read-only] [--daily-limit <usd>] [--account-wide]
                                                A new API key for CI, approved by an owner in the browser
@@ -111,6 +119,8 @@ Products
   jobs       A command in a fresh sandbox, once or on a cron schedule, with its logs
   apps       Your web server from an image or a build, copies started by requests (beta)
   builds     A connected repository's commits built into what an App deploys (beta)
+  containers One OCI image's process on its own microVM, at the sandbox rates (beta)
+  agents     Claude Code, Codex, Gemini CLI or your own agent in a sandbox per session (beta)
   domains    Your own hostname for a sandbox's port, with HTTPS
   ports      A public TCP port to a sandbox: databases, game servers
   ips        A dedicated outbound address, for allow-lists
@@ -136,7 +146,7 @@ const SANDBOX_HELP = `runtime sandboxes <command>
          [--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>]...
+         [--spread-from <id>]... [--secret NAME]... [--no-secrets]
          [--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)
@@ -183,7 +193,7 @@ const SANDBOX_HELP = `runtime sandboxes <command>
   tailscale up <id> --auth-key-secret NAME [--hostname h] [--tag tag:x]...
                                               Join your tailnet (paid); the key is a secret set with --jobs
   tailscale status <id> | tailscale down <id> Its tailnet address; take it off the tailnet
-  fork <id> [--count 3] [--name n] [--keep-snapshot]
+  fork <id> [--count 3] [--name n] [--keep-snapshot] [--secret NAME]... [--no-secrets]
                                               Copies of it as it is now, running; prints their ids
   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
@@ -427,6 +437,8 @@ const COMMANDS = [
     "jobs",
     "apps",
     "builds",
+    "containers",
+    "agents",
     "domains",
     "ports",
     "ips",
@@ -447,6 +459,8 @@ const OWN_HELP = [
     "jobs",
     "apps",
     "builds",
+    "containers",
+    "agents",
     "keys",
     "webhooks",
     "webhook",
@@ -600,6 +614,20 @@ function describe(info) {
                 .map(([k, v]) => `${k}=${v}`)
                 .join(", ") || "-",
         ],
+        // Null is every egress secret that reaches it; [] is none. Absent from
+        // older servers, so no line then rather than a guess.
+        ...(info.secrets === undefined
+            ? []
+            : [
+                [
+                    "secrets",
+                    info.secrets === null
+                        ? "every one that reaches it"
+                        : info.secrets.length
+                            ? info.secrets.join(", ")
+                            : "none",
+                ],
+            ]),
         ["charged", dollars(BigInt(Math.round(Number(info.chargedMicros) || 0)))],
     ]);
 }
@@ -1111,6 +1139,14 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         product = "builds";
         return (await import("./apps-cli.js")).buildsCommand(rest, out, () => client(env), kit);
     }
+    if (command === "container" || command === "containers") {
+        product = "containers";
+        return (await import("./apps-cli.js")).containersCommand(rest, env, out, () => client(env), kit);
+    }
+    if (command === "agent" || command === "agents") {
+        product = "agents";
+        return (await import("./agents-cli.js")).agentsCommand(rest, env, out, () => client(env), kit);
+    }
     // WireGuard is inside networks: `runtime networks wireguard peer add`.
     const wireguard = command === "networks" && rest[0] === "wireguard";
     const networkProduct = wireguard ? "wireguard" : command;
@@ -1437,6 +1473,11 @@ const DROP_IN = {
         js: 'import { SandboxInstance } from "withruntime/blaxel"; // was: from "@blaxel/core"',
         py: "from withruntime.blaxel import SandboxInstance  # was: from blaxel.core import SandboxInstance",
     },
+    // A Worker-only SDK: no Python. More than the import changes, so say what.
+    cloudflare: {
+        js: 'import { getSandbox } from "withruntime/cloudflare"; // was: from "@cloudflare/sandbox"',
+        also: "Change the `export { Sandbox }` line the same way, delete the `containers` block from the Wrangler config and run `npx wrangler secret put RUNTIME_API_KEY`.",
+    },
 };
 /** How to move a rival's code across, when one import does it. */
 export function dropInLines(provider) {
@@ -1444,9 +1485,10 @@ export function dropInLines(provider) {
     if (!drop)
         return [];
     return [
-        `Your ${RIVAL_NAMES[provider]} code runs on Runtime with one import changed:`,
+        `Your ${RIVAL_NAMES[provider]} code runs on Runtime with ${drop.also ? "this import changed" : "one import changed"}:`,
         `  ${drop.js}`,
-        `  ${drop.py}`,
+        ...(drop.py ? [`  ${drop.py}`] : []),
+        ...(drop.also ? [drop.also] : []),
     ];
 }
 /** A date as the CLI writes one: 23 September 2026. */
@@ -1888,12 +1930,14 @@ async function sandbox(argv, env, out) {
             return 0;
         }
         case "fork": {
-            const args = parse(rest, ["keep-snapshot", "trial", "paid"], ["count", "name"]);
+            const args = parse(rest, ["keep-snapshot", "trial", "paid", "no-secrets"], ["count", "name", "secret"]);
+            const secrets = secretsInput(args);
             const sbx = await get(args.positional[0]);
             const forks = await sbx.fork({
                 count: integer(args, "count") ?? 1,
                 ...(flag(args, "name") ? { name: flag(args, "name") } : {}),
                 ...(has(args, "keep-snapshot") ? { keepSnapshot: true } : {}),
+                ...secrets,
                 ...(has(args, "trial")
                     ? { funding: "trial" }
                     : has(args, "paid")
@@ -2385,7 +2429,17 @@ 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", "all-sandboxes"], ["host", "header", "format", "allow", "value", "version", "only-label", "only-sandbox"]);
+    const args = parse(rest, ["jobs", "all-sandboxes", "keep-value", "all", "none"], [
+        "host",
+        "header",
+        "format",
+        "allow",
+        "value",
+        "version",
+        "only-label",
+        "only-sandbox",
+        "agent",
+    ]);
     const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
     const rows = (list) => list.length
         ? table([
@@ -2427,13 +2481,38 @@ read = readSecret) {
                 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 (verb === "set" && has(args, "keep-value")) {
+            // Narrowing needs no value: it only takes places away (secrets.narrow).
+            if (jobs ||
+                args.flags.has("value") ||
+                args.flags.has("header") ||
+                args.flags.has("format") ||
+                args.flags.has("only-label") ||
+                args.flags.has("only-sandbox") ||
+                args.flags.has("all-sandboxes"))
+                throw usage(`--keep-value changes only --host and --allow, and only to narrower ones. Change who gets it with \`${me} secrets scope\`; anything else needs the value.`);
+            const allow = args.flags.get("allow");
+            if (!hosts.length && !allow)
+                throw usage("With --keep-value, give the narrower --host and/or --allow it keeps.");
+            const saved = await (await client(env)).secrets.narrow(name, {
+                ...(hosts.length ? { hosts } : {}),
+                ...(allow ? { rules: parseSecretRules(allow) } : {}),
+            });
+            print([
+                `Narrowed ${saved.name}; its value is unchanged. It goes only to ${saved.hosts.join(", ")}${saved.rules?.length ? `, only in these requests: ${ruleText(saved.rules)}` : ""}.`,
+                ...(saved.enforced
+                    ? []
+                    : ["A host is catching up; running sandboxes have it within a minute."]),
+            ].join("\n"), saved);
+            return 0;
+        }
         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.");
         if (args.flags.has("value"))
             throw usage('The value is read from standard input, never an argument: printf %s "$KEY" | runtime secrets set NAME --host ...');
         const value = await read();
         if (!value)
-            throw usage('The value is empty. Pipe it in: printf %s "$KEY" | runtime secrets set NAME --host ...');
+            throw usage('The value is empty. Pipe it in: printf %s "$KEY" | runtime secrets set NAME --host ...; or, to narrow its hosts and rules without it, add --keep-value.');
         const runtime = await client(env);
         if (verb === "rotate") {
             const rotated = await runtime.secrets.rotate(name, value);
@@ -2487,6 +2566,17 @@ read = readSecret) {
         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 === "share") {
+        const name = need(args.positional[0], "the secret's name");
+        const named = args.flags.get("agent") ?? [];
+        if (Number(named.length > 0) + Number(has(args, "all")) + Number(has(args, "none")) !== 1)
+            throw usage("Say who may use it: --agent <id> (once per agent), --all for every key of yours, or --none for only the key that stored it.");
+        const saved = await (await client(env)).secrets.share(name, has(args, "all") ? "all" : named);
+        print(`${saved.name}: ${saved.usableBy === "all"
+            ? "every key of yours"
+            : `only the key that stored it${saved.usableBy.length ? `, and ${saved.usableBy.length} named agent${saved.usableBy.length === 1 ? "" : "s"}` : ""}`}.`, saved);
+        return 0;
+    }
     if (verb === "reveal") {
         const name = need(args.positional[0], "the secret's name");
         const version = flag(args, "version");
@@ -2502,7 +2592,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, scope, ls, get, rotate, reveal or rm. Run `runtime help`.");
+    throw usage("secrets takes set, scope, ls, get, rotate, share, reveal or rm. Run `runtime help`.");
 }
 async function readInput(source) {
     if (source !== "-")
@@ -2664,9 +2754,11 @@ const KEYS_HELP = `runtime keys <command>
       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.
-  create --sandbox <id,...> --actions <action,...> [--name <name>] [--daily-limit <usd>]
-      A key limited to those sandboxes (up to 20, by id) and those actions on
-      them, made by the saved key: get reads them; create starts, wakes and
+  create --sandbox <id,...> --actions <action,...> [--name <name>] [--daily-limit <usd>] [--browser]
+      A key limited to those sandboxes (up to 20, by id, whichever key made
+      them) and those actions on them, made by the saved key, or with no saved
+      key (or --browser) approved by an owner or admin in the browser, as
+      above: get reads them; create starts, wakes and
       restarts them, and needs --daily-limit when the making key has one; stop
       stops and pauses them; exec runs commands; read_file and write_file reach
       their files. It is served nothing else: no list, no other sandbox, no
@@ -2678,6 +2770,7 @@ const KEYS_HELP = `runtime keys <command>
   runtime keys create --name worker-1 --daily-limit 5
   runtime keys create --name ci --daily-limit 25 --browser | gh secret set RUNTIME_API_KEY
   runtime keys create --name watcher --sandbox sbx_id --actions get,create --daily-limit 2
+  runtime keys create --name helper --sandbox sbx_a,sbx_b --actions get,exec,read_file,write_file --browser
 
 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.
@@ -2745,8 +2838,28 @@ async function accountCommand(argv, env, out) {
         ].join("\n"), closed);
         return 0;
     }
+    if (verb === "emails") {
+        /* 0921: which of Runtime's optional emails this key's person gets.
+           Bare, it lists them; `<category> on|off` changes one, for that person
+           only. */
+        const [category, state, ...extra] = rest;
+        const categories = ["own-deletions", "billing", "usage", "tips"];
+        if (extra.length || (category && !state) || (state && state !== "on" && state !== "off"))
+            throw usage(`${me} account emails [<${categories.join("|")}> on|off]`);
+        if (category && !categories.includes(category))
+            throw unknown("email", category, [...categories]);
+        const runtime = await client(env);
+        const settings = await runtime.account.emails(category
+            ? { category: category, enabled: state === "on" }
+            : undefined);
+        print([
+            ...settings.map((each) => `${each.category.padEnd(14)}${each.enabled ? "on" : "off"}`),
+            "Always sent: sign-in, invitations, revoked keys, support replies, credit expiry, service credits, and deletions Runtime decides.",
+        ].join("\n"), { settings });
+        return 0;
+    }
     if (verb !== "ls" && verb !== "list")
-        throw unknown("account command", verb, ["ls", "switch", "add", "close"]);
+        throw unknown("account command", verb, ["ls", "switch", "add", "close", "emails"]);
     await nameSaved(env).catch(() => undefined);
     const current = await store.read().catch(() => null);
     const saved = [
@@ -2915,12 +3028,14 @@ async function keys(argv, env, out) {
     return 0;
 }
 /** `runtime keys create --sandbox ... --actions ...`: a key limited to
- * sandboxes, made by the saved key (never in the browser: the keys page
- * makes none). */
+ * sandboxes, made by the saved key, or, with no key on this machine or with
+ * --browser, asked for and approved by an owner or admin in the browser
+ * (0921): an agent whose person reaches Runtime only through a connector
+ * holds no key to make one with. */
 async function limitedKey(args, env, out, limit) {
-    for (const refused of ["read-only", "account-wide", "browser"])
+    for (const refused of ["read-only", "account-wide"])
         if (has(args, refused))
-            throw usage(`A key limited to sandboxes reaches only them and is made by this machine's key, so it takes no --${refused}.`);
+            throw usage(`A key limited to sandboxes reaches only them, so it takes no --${refused}.`);
     const list = (name) => (flag(args, name) ?? "")
         .split(",")
         .map((each) => each.trim())
@@ -2929,15 +3044,30 @@ async function limitedKey(args, env, out, limit) {
     const actions = list("actions");
     if (!sandboxes.length || !actions.length)
         throw usage(`Usage: ${named("runtime keys create --sandbox <id,...> --actions <get,create,stop,exec,read_file,write_file> [--daily-limit <usd>]")}`);
-    const { dailyLimitMicros } = await import("./keys.js");
-    const made = await (await client(env)).keys.create({
+    const { createKey, dailyLimitMicros } = await import("./keys.js");
+    const request = {
         name: flag(args, "name") ?? "Sandbox key",
         sandboxes,
         actions: actions,
         dailyLimitMicros: limit === null ? null : dailyLimitMicros(limit),
-    });
-    out.write(out.json ? JSON.stringify(made) : made.key);
-    out.error(`Created key "${made.name}", limited to ${made.sandboxes?.length === 1 ? "sandbox" : "sandboxes"} ${(made.sandboxes ?? []).join(", ")} for ${(made.actions ?? []).join(", ")}${made.dailyLimitMicros === null ? "" : `, daily limit ${usdOf(made.dailyLimitMicros)}`}, made by this machine's key. Store it now: it is not shown again.\nIt calls those sandboxes by id and nothing else; revoke it with ${named("runtime keys revoke")} ${made.keyId}.`);
+    };
+    const saved = has(args, "browser")
+        ? null
+        : env.RUNTIME_API_KEY || (await connectionStore(env).read())?.key || null;
+    const asked = saved
+        ? null
+        : await createKey({ ...request, access: "full" }, env, { notify: out.error });
+    const made = asked
+        ? { ...asked, sandboxes, actions }
+        : await new Runtime({
+            apiKey: saved,
+            baseUrl: env.RUNTIME_API_URL,
+            maxRetries: 4,
+        }).keys.create(request);
+    const { confirm, ...shown } = made;
+    out.write(out.json ? JSON.stringify(shown) : shown.key);
+    out.error(`Created key "${shown.name}", limited to ${shown.sandboxes?.length === 1 ? "sandbox" : "sandboxes"} ${(shown.sandboxes ?? []).join(", ")} for ${(shown.actions ?? []).join(", ")}${shown.dailyLimitMicros === null ? "" : `, daily limit ${usdOf(shown.dailyLimitMicros)}`}, ${saved ? "made by this machine's key" : "approved in the browser"}. Store it now: it is not shown again.\nIt calls those sandboxes by id and nothing else; revoke it at https://withruntime.com/account/keys${saved ? ` or with ${named("runtime keys revoke")} ${shown.keyId}` : ""}.`);
+    await confirm?.();
     return 0;
 }
 const SNAPSHOT_HELP = `runtime snapshots <command>
@@ -3749,6 +3879,7 @@ const CREATE_FLAGS = [
     "no-auto-wake",
     "persistent",
     "get-or-create",
+    "no-secrets",
 ];
 /** Says on standard error, once for each reason, why a create has not
  * answered yet: it is waiting for a slot without credit or room, which can take up to
@@ -3818,6 +3949,7 @@ const CREATE_VALUES = [
     "image",
     "snapshot",
     "spread-from",
+    "secret",
     "volume",
     "env",
 ];
@@ -3836,6 +3968,28 @@ function usdMicros(args, name) {
         throw usage(`--${name} is too large to represent exactly in microdollars.`);
     return Number(micros);
 }
+/** The egress secrets a new sandbox may use: each --secret adds a name
+ * (commas also separate them), --no-secrets is none, and neither leaves it
+ * out, for every secret that reaches it. Fixed for the sandbox's life. */
+function secretsInput(args) {
+    const names = args.flags.get("secret");
+    if (has(args, "no-secrets")) {
+        if (names)
+            throw usage("Give --secret or --no-secrets, not both.");
+        return { secrets: [] };
+    }
+    if (!names)
+        return {};
+    return {
+        secrets: names
+            .flatMap((value) => value.split(","))
+            .map((name) => {
+            if (!name.trim())
+                throw usage("--secret needs a non-empty value.");
+            return name.trim();
+        }),
+    };
+}
 /** A create body from the command line's flags. */
 function createInput(args, env) {
     for (const name of ["image", "snapshot", "volume", "name", "region", "connect"])
@@ -3857,6 +4011,7 @@ function createInput(args, env) {
                 }),
             }
             : {}),
+        ...secretsInput(args),
         ...(args.flags.has("volume") ? { volumes: args.flags.get("volume").map(attachment) } : {}),
         ...(has(args, "no-internet") || rules.length
             ? {

package/dist/client.d.ts

@@ -153,6 +153,16 @@ export type ClosedAccount = {
     /** False while what was running is still stopping; it is gone within minutes. */
     released: boolean;
 };
+/** One of Runtime's optional emails: `own-deletions` (warnings for dates
+ * the account's own retention set), `billing` (credit low or out), `usage`
+ * (the month's free usage at 80% and all) or `tips` (getting started). */
+export type EmailCategory = "own-deletions" | "billing" | "usage" | "tips";
+/** Whether this key's person gets one optional email, in this account. */
+export type EmailSetting = {
+    category: EmailCategory;
+    enabled: boolean;
+    updatedAt: string | null;
+};
 /** The account this key belongs to: `runtime.account`. */
 export declare class AccountApi {
     private readonly t;
@@ -162,6 +172,15 @@ export declare class AccountApi {
      * name exactly (`me().orgName`). Needs a key for every product made by an
      * owner. Moves no money: what is unspent of a purchase made in the last 15
      * days is refunded on request; other credit is forfeited. */
+    /** Which of Runtime's optional emails this key's person gets for this
+     * account. Without `set`, reads them; with `{ category, enabled }`, turns
+     * one on or off for that person only, and answers all of them. Sign-in,
+     * support replies, credit expiry and deletions Runtime decides are always
+     * sent and are not listed. */
+    emails(set?: {
+        category: EmailCategory;
+        enabled: boolean;
+    }, options?: RequestOptions): Promise<EmailSetting[]>;
     close(input: {
         confirm: string;
     }, options?: RequestOptions): Promise<ClosedAccount>;