withruntime 0.16.0 → 0.17.1

package/dist/cli.js

@@ -124,12 +124,12 @@ 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 is deleted
+  run [--keep] [--root] [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]
+  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>]...
@@ -139,15 +139,16 @@ const SANDBOX_HELP = `runtime sandboxes <command>
                                                               Create one; prints its id
   ls [--all] [--label k=v]... [--state running]               List (live ones unless --all)
   get <id>                                                    One sandbox, in full
-  exec <id> [--cwd /workspace] [--env K=V]... [--timeout <s>] -- <command...>
-                                              Run and stream output; exits with its code
-  spawn <id> [--pty] -- <command...>          Start in the background; prints a process id
+  exec <id> [--cwd /workspace] [--env K[=V]]... [--timeout <s>] [--root] -- <command...>
+                                              Run and stream output; exits with its code.
+                                              --root runs it as root: no sudo needed
+  spawn <id> [--pty] [--root] -- <command...> Start in the background; prints a process id
   ps <id>                                     Running and recent processes
   logs <id> <processId> [-f] [--raw]          A process's output so far; -f follows it to the end;
                                               on a terminal control characters show as \\uXXXX
                                               unless --raw
   kill <id> <processId> [--signal SIGTERM]
-  shell <id> [--command "bash -l"]            An interactive terminal
+  shell <id> [--command "bash -l"] [--root]   An interactive terminal
   cp <src> <dst>                              Copy files or directories; name a sandbox
                                               path as <id>:/path, e.g. cp ./app sbx:/workspace/app
   cat <id> <path>                             Print a file
@@ -161,14 +162,17 @@ const SANDBOX_HELP = `runtime sandboxes <command>
   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)
-  resize <id> [--vcpu 2] [--memory 4096] --restart
-                                              Change its size by a restart: the whole disk stays,
-                                              programs stop (snapshot it first to keep memory)
+  resize <id> [--vcpu 2] [--memory 4096] [--disk 20480] --restart
+                                              Change its size by a restart: the whole disk stays and
+                                              --disk only grows it; programs stop (snapshot it first
+                                              to keep memory)
   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]
+  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
+                                              Change its settings; persistent keeps it running until stopped;
+                                              --env K alone sends K's value from your own environment,
+                                              so it is in no command line or shell history
   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]
         [--endpoint https://...] [--account-id id] [--read-only]
@@ -332,6 +336,20 @@ const pairs = (args, name) => Object.fromEntries((args.flags.get(name) ?? []).ma
         throw usage(`--${name} takes KEY=VALUE.`);
     return [pair.slice(0, at), pair.slice(at + 1)];
 }));
+/** --env KEY=VALUE, or --env KEY alone to take KEY's value from the CLI's own
+ * environment, as docker run -e does: the value stays out of the process's
+ * arguments and the shell's history. */
+const envPairs = (args, from) => Object.fromEntries((args.flags.get("env") ?? []).map((pair) => {
+    const at = pair.indexOf("=");
+    if (at > 0)
+        return [pair.slice(0, at), pair.slice(at + 1)];
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(pair))
+        throw usage(`--env takes KEY=VALUE, or KEY alone to send KEY's value from your environment.`);
+    const value = from[pair];
+    if (value === undefined)
+        throw usage(`--env ${pair} sends ${pair} from your environment, and it is not set there.`);
+    return [pair, value];
+}));
 /** What the commands in cli-extras.ts use of this file. */
 const kit = {
     parse: (argv, booleans, values) => parse(argv, booleans, values),
@@ -647,13 +665,13 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         return 0;
     }
     if (command === "run") {
-        const args = parse(rest, [...CREATE_FLAGS, "keep"], [...CREATE_VALUES, "cwd", "env"], `${me} sandboxes run -- python3 < invoice.py`);
+        const args = parse(rest, [...CREATE_FLAGS, "keep", "root"], [...CREATE_VALUES, "cwd", "env"], `${me} sandboxes run -- python3 < invoice.py`);
         const commandLine = args.rest ?? args.positional;
         if (!commandLine.length)
             throw usage(`Give the command after --: ${me} sandboxes run -- python3 < invoice.py`);
         const runtime = await client(env);
         const timeout = integer(args, "timeout");
-        const { timeoutSeconds: _lease, ...input } = createInput(args);
+        const { timeoutSeconds: _lease, ...input } = createInput(args, env);
         const onCapacityWait = waiting(out);
         const sbx = await withVolumeRelease((options) => runtime.sandboxes.create(input, { ...options, onCapacityWait }), out);
         let cleanup;
@@ -684,7 +702,7 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
             process.once("SIGINT", interrupted);
         let code = 1;
         try {
-            code = await execute(sbx, commandLine, args, out, timeout, has(args, "keep"));
+            code = await execute(sbx, commandLine, args, out, timeout, env, has(args, "keep"));
         }
         finally {
             try {
@@ -1654,7 +1672,7 @@ async function sandbox(argv, env, out) {
     switch (verb) {
         case "create": {
             const args = parse(rest, CREATE_FLAGS, CREATE_VALUES);
-            const input = createInput(args);
+            const input = createInput(args, env);
             const onCapacityWait = waiting(out);
             const sbx = await withVolumeRelease((options) => runtime.sandboxes.create(input, { ...options, onCapacityWait }), out);
             print(sbx.id, sbx.info);
@@ -1718,13 +1736,14 @@ async function sandbox(argv, env, out) {
             return 0;
         }
         case "resize": {
-            const args = parse(rest, ["restart"], ["vcpu", "memory"]);
+            const args = parse(rest, ["restart"], ["vcpu", "memory", "disk"]);
             const sbx = await use(need(args.positional[0], `a sandbox, e.g. ${me} sandboxes resize <id> --memory 4096 --restart`));
             const size = {
                 ...(integer(args, "vcpu") !== undefined ? { vcpu: integer(args, "vcpu") } : {}),
                 ...(integer(args, "memory") !== undefined ? { memoryMiB: integer(args, "memory") } : {}),
+                ...(integer(args, "disk") !== undefined ? { diskMiB: integer(args, "disk") } : {}),
             };
-            if (size.vcpu === undefined && size.memoryMiB === undefined)
+            if (size.vcpu === undefined && size.memoryMiB === undefined && size.diskMiB === undefined)
                 throw usage(`Name a new size, e.g. ${me} sandboxes resize ${sbx.id} --memory 4096 --restart`);
             if (!args.flags.has("restart"))
                 throw usage(`A resize restarts it: its whole disk stays and its programs stop. Add --restart to say so, or snapshot it first (${me} sandboxes snapshot ${sbx.id}) to keep its memory too.`);
@@ -1881,14 +1900,14 @@ async function sandbox(argv, env, out) {
             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.");
-            const env = {
-                ...(args.flags.has("env") ? pairs(args, "env") : {}),
+            const variables = {
+                ...(args.flags.has("env") ? envPairs(args, env) : {}),
                 ...Object.fromEntries((args.flags.get("unset-env") ?? []).map((name) => [name, null])),
             };
             const settings = {
                 ...(flag(args, "name") ? { name: flag(args, "name") } : {}),
                 ...(args.flags.has("label") ? { labels: pairs(args, "label") } : {}),
-                ...(Object.keys(env).length ? { env } : {}),
+                ...(Object.keys(variables).length ? { env: variables } : {}),
                 ...(integer(args, "idle-pause") !== undefined
                     ? { idlePauseSeconds: integer(args, "idle-pause") }
                     : {}),
@@ -1920,23 +1939,24 @@ async function sandbox(argv, env, out) {
             return 0;
         }
         case "exec": {
-            const args = parse(rest, [], ["cwd", "env", "timeout"], `${me} sandboxes exec <id> -- ls -la`);
+            const args = parse(rest, ["root"], ["cwd", "env", "timeout"], `${me} sandboxes exec <id> -- ls -la`);
             const command = args.rest ?? args.positional.slice(1);
             if (!command.length)
                 throw usage("Give the command after --: runtime sandboxes exec <id> -- ls -la");
             const sbx = await use(args.positional[0]);
-            return execute(sbx, command, args, out, integer(args, "timeout"));
+            return execute(sbx, command, args, out, integer(args, "timeout"), env);
         }
         case "spawn": {
-            const args = parse(rest, ["pty"], ["cwd", "env"], `${me} sandboxes spawn <id> -- npm run dev`);
+            const args = parse(rest, ["pty", "root"], ["cwd", "env"], `${me} sandboxes spawn <id> -- npm run dev`);
             const command = args.rest ?? [];
             if (!command.length)
                 throw usage("Give the command after --: runtime sandboxes spawn <id> -- npm run dev");
             const sbx = await use(args.positional[0]);
             const proc = await sbx.spawn(command.length === 1 ? command[0] : command, {
                 ...(has(args, "pty") ? { pty: { cols: 120, rows: 40 } } : {}),
+                ...(has(args, "root") ? { user: "root" } : {}),
                 ...(flag(args, "cwd") ? { cwd: flag(args, "cwd") } : {}),
-                ...(args.flags.has("env") ? { env: pairs(args, "env") } : {}),
+                ...(args.flags.has("env") ? { env: envPairs(args, env) } : {}),
             });
             print(proc.id, proc.info);
             return 0;
@@ -1946,12 +1966,13 @@ async function sandbox(argv, env, out) {
             const list = await sbx.processes.list();
             print(list.length
                 ? table([
-                    ["PROCESS", "STATE", "EXIT", "COMMAND"],
+                    ["PROCESS", "STATE", "EXIT", "USER", "COMMAND"],
                     // The command line is the guest's report: escaped, as a log is.
                     ...list.map((p) => [
                         terminalSafe(String(p.id)),
                         terminalSafe(String(p.state)),
                         `${typeof p.exitCode === "number" ? p.exitCode : "-"}${p.outOfMemory ? " (out of memory)" : ""}`,
+                        p.user === "root" ? "root" : "sandbox",
                         terminalSafe(String(p.command ?? "")),
                     ]),
                 ])
@@ -2019,9 +2040,9 @@ async function sandbox(argv, env, out) {
             return 0;
         }
         case "shell": {
-            const args = parse(rest, [], ["command"]);
+            const args = parse(rest, ["root"], ["command"]);
             const sbx = await use(args.positional[0]);
-            return shell(sbx, flag(args, "command"));
+            return shell(sbx, flag(args, "command"), has(args, "root"));
         }
         case "cat": {
             const sbx = await use(rest[0]);
@@ -2612,12 +2633,20 @@ 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
+      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
+      account route, no MCP.
   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 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
 
 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.
@@ -2786,8 +2815,16 @@ async function keys(argv, env, out) {
     }
     if (verb !== "create")
         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"]);
+    const args = parse(rest, ["read-only", "account-wide", "browser"], ["name", "daily-limit", "sandbox", "actions"]);
+    const known = new Set([
+        "name",
+        "read-only",
+        "daily-limit",
+        "account-wide",
+        "browser",
+        "sandbox",
+        "actions",
+    ]);
     for (const name of args.flags.keys())
         if (!known.has(name))
             throw usage(`Unknown option --${name}.`);
@@ -2795,6 +2832,8 @@ async function keys(argv, env, out) {
         throw usage(`Unexpected ${args.positional[0] ?? "--"}.`);
     const readOnly = has(args, "read-only");
     const limit = flag(args, "daily-limit");
+    if (flag(args, "sandbox") !== undefined || flag(args, "actions") !== undefined)
+        return limitedKey(args, env, out, limit === undefined ? null : limit);
     if (readOnly && limit !== undefined)
         throw usage("A read-only key cannot spend, so it takes no --daily-limit.");
     if (readOnly && has(args, "account-wide"))
@@ -2844,6 +2883,32 @@ async function keys(argv, env, out) {
     await confirm?.();
     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). */
+async function limitedKey(args, env, out, limit) {
+    for (const refused of ["read-only", "account-wide", "browser"])
+        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}.`);
+    const list = (name) => (flag(args, name) ?? "")
+        .split(",")
+        .map((each) => each.trim())
+        .filter(Boolean);
+    const sandboxes = list("sandbox");
+    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({
+        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}.`);
+    return 0;
+}
 const SNAPSHOT_HELP = `runtime snapshots <command>
 
   ls [--sandbox <id>] [--name n]              Your snapshots
@@ -3741,7 +3806,7 @@ function usdMicros(args, name) {
     return Number(micros);
 }
 /** A create body from the command line's flags. */
-function createInput(args) {
+function createInput(args, env) {
     for (const name of ["image", "snapshot", "volume", "name", "region", "connect"])
         if (args.flags.get(name)?.some((value) => !value.trim()))
             throw usage(`--${name} needs a non-empty value.`);
@@ -3772,7 +3837,7 @@ function createInput(args) {
             : {}),
         ...(flag(args, "name") ? { name: flag(args, "name") } : {}),
         ...(args.flags.has("label") ? { labels: pairs(args, "label") } : {}),
-        ...(args.flags.has("env") ? { env: pairs(args, "env") } : {}),
+        ...(args.flags.has("env") ? { env: envPairs(args, env) } : {}),
         ...(integer(args, "vcpu") !== undefined ? { vcpu: integer(args, "vcpu") } : {}),
         ...(integer(args, "memory") !== undefined ? { memoryMiB: integer(args, "memory") } : {}),
         ...(integer(args, "disk") !== undefined ? { diskMiB: integer(args, "disk") } : {}),
@@ -3809,7 +3874,7 @@ function createInput(args) {
 }
 /** Runs a command in a sandbox, streaming its output, and answers its exit code
  * (124 on a timeout), so a script's `set -e` behaves. */
-async function execute(sbx, command, args, out, timeout, 
+async function execute(sbx, command, args, out, timeout, env, 
 /** `run` stops its whole sandbox on Ctrl-C, so it handles the signal itself. */
 ownInterrupt = true) {
     const target = command.length === 1 ? command[0] : command;
@@ -3818,7 +3883,8 @@ ownInterrupt = true) {
     const options = {
         ...(stdin ? { stdin } : {}),
         ...(flag(args, "cwd") ? { cwd: flag(args, "cwd") } : {}),
-        ...(args.flags.has("env") ? { env: pairs(args, "env") } : {}),
+        ...(args.flags.has("env") ? { env: envPairs(args, env) } : {}),
+        ...(has(args, "root") ? { user: "root" } : {}),
         ...(timeout !== undefined ? { timeoutMs: timeout * 1000 } : {}),
     };
     // Ctrl-C stops the command in the sandbox too, and says so; without this
@@ -3867,12 +3933,13 @@ ownInterrupt = true) {
     const code = result.timedOut ? 124 : Math.min(255, exit < 0 ? 128 - exit : exit);
     return lost && code === 0 ? 1 : code;
 }
-async function shell(sbx, command) {
+async function shell(sbx, command, root = false) {
     const stdin = process.stdin;
     const size = () => ({ cols: process.stdout.columns || 80, rows: process.stdout.rows || 24 });
     const terminal = await sbx.terminal({
         ...size(),
         ...(command ? { command } : {}),
+        ...(root ? { user: "root" } : {}),
         onData: (data) => process.stdout.write(data),
     });
     if (stdin.isTTY)

package/dist/identity.js

@@ -1,29 +1,51 @@
 import { RuntimeError } from "./errors.js";
 import { sandboxMarker } from "./transport.js";
-/** The guest's environment file, which holds the sandbox's current request
- * token: the guest writes it again when the token changes (a wake on another
- * server, a restore), while a process keeps the environment it started with. */
+async function requestCredentials() {
+    const url = process.env.RUNTIME_ID_TOKEN_REQUEST_URL;
+    const token = process.env.RUNTIME_ID_TOKEN_REQUEST_TOKEN;
+    if (url && token)
+        return { url, token };
+    // A process started before the guest wrote its environment still finds it.
+    return fileCredentials();
+}
 async function fileCredentials() {
     try {
         // Loaded here, so the SDK still loads where there is no file system.
         const { readFile } = await import("node:fs/promises");
         const env = JSON.parse(await readFile(sandboxMarker.path, "utf8"));
-        return { url: env.RUNTIME_ID_TOKEN_REQUEST_URL, token: env.RUNTIME_ID_TOKEN_REQUEST_TOKEN };
+        const url = env.RUNTIME_ID_TOKEN_REQUEST_URL;
+        const token = env.RUNTIME_ID_TOKEN_REQUEST_TOKEN;
+        return url && token ? { url, token } : null;
     }
     catch {
         return null;
     }
 }
-async function requestCredentials() {
-    let url = process.env.RUNTIME_ID_TOKEN_REQUEST_URL;
-    let token = process.env.RUNTIME_ID_TOKEN_REQUEST_TOKEN;
-    if (!url || !token) {
-        // A process started before the guest wrote its environment still finds it.
-        const file = await fileCredentials();
-        url = file?.url;
-        token = file?.token;
+/** The sandbox's own listener (packages/cloud/src/linux/egress.ts). */
+const ENVIRONMENT_URL = "http://runtime.internal/v1/environment";
+/** The sandbox's request token as its host holds it now. The one in
+ * process.env was current when the process started: it changes with every
+ * renewal of the sandbox's lease (about every 30 minutes for one that keeps
+ * running), and a server restored from a snapshot (an App's copies, a fork)
+ * holds the statement of the sandbox it was saved from. The host's listener
+ * answers this sandbox's own; guest-net.py's file is a few seconds behind it. */
+async function currentCredentials(signal) {
+    try {
+        const response = await fetch(ENVIRONMENT_URL, {
+            signal: signal ?? AbortSignal.timeout(5_000),
+        });
+        if (response.ok) {
+            const env = (await response.json());
+            const url = env.RUNTIME_ID_TOKEN_REQUEST_URL;
+            const token = env.RUNTIME_ID_TOKEN_REQUEST_TOKEN;
+            if (typeof url === "string" && url && typeof token === "string" && token)
+                return { url, token };
+        }
+    }
+    catch {
+        // Not in a sandbox, or a host that predates the listener's environment.
     }
-    return url && token ? { url, token } : null;
+    return fileCredentials();
 }
 /**
  * Inside a Runtime sandbox: a short-lived OIDC token, signed by Runtime,
@@ -44,24 +66,25 @@ export async function identityToken(input) {
             status: 0,
             message: "Identity tokens are issued only inside a Runtime sandbox (RUNTIME_ID_TOKEN_REQUEST_TOKEN is not set).",
         });
-    const ask = (from) => {
-        const url = new URL(from.url);
+    const ask = (credentials) => {
+        const url = new URL(credentials.url);
         url.searchParams.set("audience", input.audience);
         if (input.lifetimeSeconds !== undefined)
             url.searchParams.set("lifetimeSeconds", String(input.lifetimeSeconds));
         return fetch(url, {
-            headers: { authorization: `Bearer ${from.token}` },
+            headers: { authorization: `Bearer ${credentials.token}` },
             signal: input.signal ?? AbortSignal.timeout(10_000),
         });
     };
     let response = await ask(found);
-    // Refused for a request token that has since changed: a long-running
-    // process asks again with the current one from the guest's file (the hub's
-    // own, 16 October 2026, from its start until it was restarted).
+    // Refused for a request token that is no longer this sandbox's current one:
+    // ask once more with the one its host holds now.
     if (response.status === 401 || response.status === 403) {
-        const file = await fileCredentials();
-        if (file?.url && file.token && file.token !== found.token)
-            response = await ask({ url: file.url, token: file.token });
+        const current = await currentCredentials(input.signal);
+        if (current && current.token !== found.token) {
+            await response.body?.cancel();
+            response = await ask(current);
+        }
     }
     const body = (await response.json().catch(() => ({})));
     if (!response.ok || !body.token)

package/dist/index.d.ts

@@ -74,5 +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 { NewKey, LimitedKey, LimitedKeyAction, MadeKey, ListedKey, KeyUsage, } from "./products/api-keys.js";
 export type { SsoConnection, SsoStatus } from "./products/sso.js";

package/dist/machine.d.ts

@@ -95,9 +95,12 @@ export declare abstract class Machine<Info extends MachineInfo, Settings extends
      * while a snapshot or fork of it is being taken. `restart` is optional:
      * true is the only value, and it is sent either way, so an API from before
      * it was optional accepts the call too. */
-    resize(size: {
+    resize(
+    /** diskMiB only grows; the filesystem fills it at the restart. */
+    size: {
         vcpu?: number;
         memoryMiB?: number;
+        diskMiB?: number;
     }, options?: RequestOptions & {
         restart?: true;
     }): Promise<this>;

package/dist/machine.js

@@ -175,7 +175,9 @@ export class Machine {
      * while a snapshot or fork of it is being taken. `restart` is optional:
      * true is the only value, and it is sent either way, so an API from before
      * it was optional accepts the call too. */
-    async resize(size, options = {}) {
+    async resize(
+    /** diskMiB only grows; the filesystem fills it at the restart. */
+    size, options = {}) {
         const { restart = true, ...rest } = options;
         this.#keep(await this.#t.json({
             method: "POST",

package/dist/products/api-keys.d.ts

@@ -1,5 +1,11 @@
 import type { RequestOptions, Transport } from "../transport.js";
-export type NewKey = {
+/** What a key limited to sandboxes may do to them. get reads them; create
+ *  starts, wakes and restarts them (never makes one), and is the one that
+ *  spends; stop stops and pauses them; exec runs commands and processes;
+ *  read_file and write_file reach their files. */
+export type LimitedKeyAction = "get" | "create" | "stop" | "exec" | "read_file" | "write_file";
+export type NewKey = FullOrReadKey | LimitedKey;
+type FullOrReadKey = {
     /** The key's name, and its agent's: up to 80 characters. */
     name: string;
     /** full (the default): every action. read: every read, nothing else. */
@@ -11,6 +17,19 @@ export type NewKey = {
      *  when the making key has a limit: the limits of the keys a key made add
      *  up to at most its own. */
     dailyLimitMicros?: number | null;
+    sandboxes?: never;
+    actions?: never;
+};
+/** A key limited to these sandboxes and these actions on them. */
+export type LimitedKey = {
+    name: string;
+    /** 1 to 20 sandbox ids this key acts on, outside every compartment. */
+    sandboxes: string[];
+    actions: LimitedKeyAction[];
+    /** Only with create, the one action that spends. */
+    dailyLimitMicros?: number | null;
+    access?: never;
+    reach?: never;
 };
 export type MadeKey = {
     /** The key itself. Shown once: store it now. */
@@ -19,9 +38,15 @@ export type MadeKey = {
     agentId: string;
     orgId: string;
     name: string;
-    access: "full" | "read";
-    reach: "agent" | "account";
+    /** selected: a key limited to sandboxes. */
+    access: "full" | "read" | "selected";
+    /** sandboxes: only the sandboxes it names. */
+    reach: "agent" | "account" | "sandboxes";
     dailyLimitMicros: number | null;
+    /** The sandboxes it is limited to, or null. */
+    sandboxes: string[] | null;
+    /** Its actions, when it has named ones, or null. */
+    actions: string[] | null;
     /** The making key's expiry, or null for until revoked. */
     expires: string | null;
     /** The id of the key that made it. */
@@ -32,8 +57,10 @@ export type ListedKey = {
     agentId: string;
     name: string;
     access: "full" | "read" | "selected";
-    reach: "agent" | "account";
+    reach: "agent" | "account" | "sandboxes";
     dailyLimitMicros: number | null;
+    sandboxes: string[] | null;
+    actions: string[] | null;
     /** Committed in the last 24 hours: settled plus held, as the limit counts. */
     dailyUsedMicros: number;
     /** The key that made it, or null for one made on the website. */
@@ -71,3 +98,4 @@ export declare function keys(t: Transport): {
     /** What one key spent: itself, or a key it made. */
     usage: (keyId: string, options?: RequestOptions) => Promise<KeyUsage>;
 };
+export {};

package/dist/products/apps.d.ts

@@ -90,6 +90,12 @@ export type DeployApp = ({
     image?: never;
 }) & {
     env?: Record<string, string>;
+    /** Carry the last deploy's environment, still sealed. With env, that
+     * environment with env's names set: change one value without sending the rest
+     * (needs a key that may reveal the App's secrets, secrets_reveal; else 403).
+     * Only for a build a push to the production branch made, from the repository the
+     * environment came with; otherwise refused with keep_env_refused (409). */
+    keepEnv?: boolean;
     port?: number;
     healthPath?: string;
     /** Return live, failed or superseded, including its URL/version or failure details. */
@@ -100,6 +106,10 @@ export type AppVersion = {
     live: boolean;
     previous: boolean;
     saved: boolean;
+    /** Its deploy's id, for GET /v1/apps/{id}/deploys/{deploy}. */
+    deploy: string;
+    /** The build it was deployed from, or null for an image. */
+    build: string | null;
 };
 export type AppCopy = {
     id: string;

package/dist/sandbox.d.ts

@@ -73,6 +73,8 @@ export declare class Sandbox extends Machine<SandboxInfo, SandboxSettings, Delet
         rows?: number;
         command?: string;
         cwd?: string;
+        /** "root" opens the shell (or runs `command`) as root. */
+        user?: "sandbox" | "root";
         /** Attach to a process started with a pty instead of a new shell. */
         processId?: string;
         onData?: (data: Uint8Array) => void;

package/dist/sandbox.js

@@ -79,6 +79,7 @@ function commandBody(command, options) {
         ...(typeof command === "string" ? { command } : { argv: [...command] }),
         ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
         ...(options.env === undefined ? {} : { env: options.env }),
+        ...(options.user === undefined ? {} : { user: options.user }),
         ...(options.stdin === undefined
             ? {}
             : typeof options.stdin === "string"
@@ -314,6 +315,7 @@ export class Sandbox extends Machine {
             rows: options.rows,
             command: options.command,
             cwd: options.cwd,
+            user: options.user,
             processId: options.processId,
         });
         return Terminal.open(socket, options.onData);

package/dist/transport.d.ts

@@ -1,5 +1,5 @@
 import { RuntimeError } from "./errors.js";
-export declare const VERSION = "0.16.0";
+export declare const VERSION = "0.17.1";
 export declare const DEFAULT_BASE_URL = "https://api.withruntime.com";
 /** Runtime's API as code inside a Runtime sandbox reaches it: the sandbox's
  * own host sends each request on to DEFAULT_BASE_URL over HTTPS. The API runs

package/dist/transport.js

@@ -1,7 +1,7 @@
 import { ConnectionError, DELIBERATE, errorFor, NOTHING_RAN, RuntimeError, WAITS_FOR_ROOM, } from "./errors.js";
 import { describeRoute, envFetch, openWebSocket } from "./proxy.js";
 import { warningText } from "./product-renames.js";
-export const VERSION = "0.16.0";
+export const VERSION = "0.17.1";
 export const DEFAULT_BASE_URL = "https://api.withruntime.com";
 /** Runtime's API as code inside a Runtime sandbox reaches it: the sandbox's
  * own host sends each request on to DEFAULT_BASE_URL over HTTPS. The API runs

package/dist/types.d.ts

@@ -200,6 +200,10 @@ export type CommandResult = {
 };
 export type ExecOptions = {
     cwd?: string;
+    /** Who runs it: "sandbox" (the default, uid 1000, HOME=/workspace) or
+     * "root", through the sandbox's passwordless sudo with the same
+     * environment and PATH and HOME=/root: no need to prefix it with sudo. */
+    user?: "sandbox" | "root";
     /** Merged over the sandbox's environment. Put secrets here, never in the command. */
     env?: Record<string, string>;
     /** Given to standard input, then closed. */
@@ -220,6 +224,8 @@ export type ProcessInfo = {
     state: "running" | "exited" | "killed" | "timed_out" | "unknown";
     exitCode: number | null;
     command: string;
+    /** Who it runs as; absent from APIs before 17 October 2026. */
+    user?: "sandbox" | "root";
     cwd: string;
     pty: boolean;
     stdinOpen: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "withruntime",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "license": "Apache-2.0",
   "mcpName": "com.withruntime/runtime",
   "type": "module",