withruntime 0.17.2 → 0.21.0

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

@@ -1,3 +1,4 @@
+import { me } from "./cli-name.js";
 import { RuntimeError } from "./errors.js";
 import { cliWords } from "./product-renames.js";
 /* What the CLI says in its own words where the API's would mislead: the
@@ -25,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 },
@@ -48,6 +50,15 @@ function issueWords(path, message) {
  * a hint that names the options rather than the request's fields. Anything
  * else is left as the API said it. */
 export function cliRefusal(error) {
+    // A beta's refusal names the support tool an agent calls; here, the command.
+    if (error.code === "product_in_beta") {
+        const product = typeof error.details?.product === "string" ? error.details.product : "";
+        const open = (error.hint ?? "").replace(/;?\s*ask Runtime support \(runtime_support\) to join it\.?$/, ".");
+        return {
+            message: error.message,
+            hint: `${open ? `${open} ` : ""}Ask to join: ${me} support "Please add us to the ${product || "product"} beta"`,
+        };
+    }
     const issues = error.details?.issues;
     if (error.code === "invalid_request" && Array.isArray(issues) && issues.length) {
         const lines = issues

package/dist/cli.d.ts

@@ -24,9 +24,13 @@ declare const kit: {
     pairs: (args: Args, name: string) => {
         [k: string]: string;
     };
+    envPairs: (args: Args, from: NodeJS.ProcessEnv) => {
+        [k: string]: string;
+    };
     need: (value: string | undefined, what: string) => string;
     table: (rows: string[][]) => string;
     usage: (message: string) => RuntimeError;
+    unknown: (what: string, word: string, choices: readonly string[]) => RuntimeError;
 };
 export type CliKit = typeof kit;
 export declare function run(argv: string[], env?: NodeJS.ProcessEnv, out?: Out): Promise<number>;

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
@@ -109,6 +110,10 @@ Products
   images     Custom images from a Dockerfile, any public or private image, or a package list
   volumes    Persistent disks to attach to sandboxes
   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
@@ -134,7 +139,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)
@@ -181,7 +186,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
@@ -357,9 +362,11 @@ const kit = {
     has,
     integer,
     pairs,
+    envPairs,
     need: (value, what) => need(value, what),
     table: (rows) => table(rows),
     usage: (message) => usage(message),
+    unknown: (what, word, choices) => unknown(what, word, choices),
 };
 /** The product being run, so a mistake points at its own help. */
 let product = "";
@@ -421,6 +428,10 @@ const COMMANDS = [
     "images",
     "volumes",
     "jobs",
+    "apps",
+    "builds",
+    "containers",
+    "agents",
     "domains",
     "ports",
     "ips",
@@ -439,6 +450,10 @@ const OWN_HELP = [
     "images",
     "volumes",
     "jobs",
+    "apps",
+    "builds",
+    "containers",
+    "agents",
     "keys",
     "webhooks",
     "webhook",
@@ -592,6 +607,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)))],
     ]);
 }
@@ -1095,6 +1124,22 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         product = "job";
         return jobCommand(rest, env, out);
     }
+    if (command === "app" || command === "apps") {
+        product = "apps";
+        return (await import("./apps-cli.js")).appsCommand(rest, env, out, () => client(env), kit);
+    }
+    if (command === "build" || command === "builds") {
+        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;
@@ -1421,6 +1466,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) {
@@ -1428,9 +1478,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. */
@@ -1872,12 +1923,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")
@@ -2729,8 +2782,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 = [
@@ -3733,6 +3806,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
@@ -3802,6 +3876,7 @@ const CREATE_VALUES = [
     "image",
     "snapshot",
     "spread-from",
+    "secret",
     "volume",
     "env",
 ];
@@ -3820,6 +3895,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"])
@@ -3841,6 +3938,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>;

package/dist/client.js

@@ -167,6 +167,26 @@ export 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. */
+    async emails(set, options = {}) {
+        const answer = set
+            ? await this.t.json({
+                method: "POST",
+                path: "/v1/account/emails:update",
+                body: { category: set.category, enabled: set.enabled },
+                ...options,
+            })
+            : await this.t.json({
+                method: "GET",
+                path: "/v1/account/emails",
+                ...options,
+            });
+        return answer.settings;
+    }
     close(input, options = {}) {
         return this.t.json({
             method: "POST",

package/dist/cloudflare/errors.d.ts

@@ -119,6 +119,29 @@ export declare class OperationInterruptedError extends SandboxError<{
 }> {
     get reason(): string;
 }
+/** Cloudflare's transport error for its WebSocket sessions; Runtime's API
+ * has no such session, so the adapter never throws it. */
+export declare class RPCTransportError extends SandboxError<{
+    kind: string;
+    originalMessage: string;
+}> {
+    get kind(): string;
+    get originalMessage(): string;
+}
+/** Input the container refuses, such as content that is not base64. */
+export declare class ValidationFailedError extends SandboxError<{
+    validationErrors: {
+        field: string;
+        message: string;
+        code: string;
+    }[];
+}> {
+    get validationErrors(): {
+        field: string;
+        message: string;
+        code: string;
+    }[];
+}
 export declare class BucketMountError extends Error {
     readonly code: string;
     constructor(message: string, code?: string);

package/dist/cloudflare/errors.js

@@ -125,6 +125,22 @@ export class OperationInterruptedError extends SandboxError {
         return this.context.reason;
     }
 }
+/** Cloudflare's transport error for its WebSocket sessions; Runtime's API
+ * has no such session, so the adapter never throws it. */
+export class RPCTransportError extends SandboxError {
+    get kind() {
+        return this.context.kind;
+    }
+    get originalMessage() {
+        return this.context.originalMessage;
+    }
+}
+/** Input the container refuses, such as content that is not base64. */
+export class ValidationFailedError extends SandboxError {
+    get validationErrors() {
+        return this.context.validationErrors;
+    }
+}
 export class BucketMountError extends Error {
     code;
     constructor(message, code = "BUCKET_MOUNT_ERROR") {

package/dist/cloudflare/index.d.ts

@@ -6,8 +6,11 @@ export { CompatibilityError };
 export * from "./errors.js";
 export { CodeInterpreter } from "./interpreter.js";
 export type { CodeContext, CreateContextOptions, ExecutionError, OutputMessage, RunCodeOptions, } from "./interpreter.js";
-export { collectFile, isExecResult, isProcess, isProcessStatus, parseSSEStream, streamFile, } from "./streams.js";
+export { collectFile, isExecResult, isProcess, isProcessStatus, parseSSEStream, streamFile, asyncIterableToSSEStream, responseToAsyncIterable, } from "./streams.js";
 export type { FileChunk, FileMetadata, FileStreamEvent } from "./streams.js";
+export * from "./types.js";
+/** Cloudflare's interface for its Sandbox class. */
+export type ISandbox = Sandbox;
 export declare class SandboxSecurityError extends Error {
     readonly code: string;
     constructor(message: string, code: string);
@@ -58,6 +61,13 @@ export type CheckChangesResult = {
     version: string;
     timestamp: string;
 };
+export interface GitCheckoutOptions {
+    branch?: string;
+    targetDir?: string;
+    sessionId?: string;
+    depth?: number;
+    cloneTimeoutMs?: number;
+}
 export interface GitCheckoutResult {
     success: boolean;
     repoUrl: string;
@@ -96,6 +106,7 @@ export interface ReadFileResult {
     content: string;
     encoding: "utf-8" | "base64";
     isBinary: boolean;
+    mimeType: string;
     size: number;
     timestamp: string;
 }
@@ -115,6 +126,16 @@ export interface SessionOptions {
     isolation?: boolean;
     commandTimeoutMs?: number;
 }
+export interface WaitForPortOptions {
+    mode?: "http" | "tcp";
+    path?: string;
+    status?: number | {
+        min: number;
+        max: number;
+    };
+    timeout?: number;
+    interval?: number;
+}
 export interface ProcessOptions {
     timeout?: number;
     env?: Record<string, string | undefined>;
@@ -312,13 +333,7 @@ export declare class Sandbox {
         signal?: AbortSignal;
     }): Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>;
     /** Clones with git in the sandbox, as Cloudflare's container does. */
-    gitCheckout(repoUrl: string, options?: {
-        branch?: string;
-        targetDir?: string;
-        sessionId?: string;
-        depth?: number;
-        cloneTimeoutMs?: number;
-    }): Promise<GitCheckoutResult>;
+    gitCheckout(repoUrl: string, options?: GitCheckoutOptions): Promise<GitCheckoutResult>;
     /** Changes under a directory as `data:` lines of Cloudflare's watch events,
      * once the watch is established, until the stream is cancelled. */
     watch(path: string, options?: WatchOptions): Promise<ReadableStream<Uint8Array>>;
@@ -442,6 +457,57 @@ export declare class ExecutionSession {
         timestamp: string;
     }>;
     setEnvVars(env: Record<string, string | undefined>): Promise<void>;
+    moveFile(path: string, newPath: string): Promise<{
+        success: boolean;
+        path: string;
+        newPath: string;
+        timestamp: string;
+    }>;
+    readFileStream(path: string): Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>;
+    gitCheckout(repoUrl: string, options?: Omit<GitCheckoutOptions, "sessionId">): Promise<GitCheckoutResult>;
+    watch(path: string, options?: Omit<WatchOptions, "sessionId">): Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>;
+    checkChanges(path: string, options?: Omit<CheckChangesOptions, "sessionId">): Promise<CheckChangesResult>;
+    listProcesses(): Promise<Process[]>;
+    getProcess(id: string): Promise<Process | null>;
+    killProcess(id: string, signal?: string): Promise<void>;
+    killAllProcesses(): Promise<number>;
+    cleanupCompletedProcesses(): Promise<number>;
+    getProcessLogs(id: string): Promise<{
+        stdout: string;
+        stderr: string;
+        processId: string;
+    }>;
+    streamProcessLogs(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>;
+    createCodeContext(options?: CreateContextOptions): Promise<CodeContext>;
+    runCode(code: string, options?: RunCodeOptions): Promise<{
+        code: string;
+        logs: {
+            stdout: string[];
+            stderr: string[];
+        };
+        error: import("./interpreter.js").ExecutionError | undefined;
+        executionCount: number | undefined;
+        results: {
+            text: string | undefined;
+            html: string | undefined;
+            png: string | undefined;
+            jpeg: string | undefined;
+            svg: string | undefined;
+            latex: string | undefined;
+            markdown: string | undefined;
+            javascript: string | undefined;
+            json: unknown;
+            chart: undefined;
+            data: Record<string, unknown> | undefined;
+        }[];
+    }>;
+    runCodeStream(code: string, options?: RunCodeOptions): Promise<ReadableStream<any>>;
+    listCodeContexts(): Promise<CodeContext[]>;
+    deleteCodeContext(contextId: string): Promise<void>;
+    mountBucket(bucket: string, mountPath: string, options: MountBucketOptions): Promise<void>;
+    unmountBucket(mountPath: string): Promise<void>;
 }
 export declare class Process {
     #private;
@@ -466,7 +532,14 @@ export declare class Process {
         exitCode: number;
     }>;
     waitForLog(pattern: string | RegExp, timeout?: number): Promise<{
-        match?: true | RegExpMatchArray | undefined;
         line: string;
+        match?: undefined;
+    } | {
+        line: string;
+        match: RegExpMatchArray;
     }>;
+    /** Resolves once the port answers: an HTTP status in range (200-399 by
+     * default) at `path`, or a TCP connection in `tcp` mode. Throws if the
+     * process ends first, or after `timeout` milliseconds when one is given. */
+    waitForPort(port: number, options?: WaitForPortOptions): Promise<void>;
 }