withruntime 0.18.0 → 0.21.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
@@ -111,6 +112,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 +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)
@@ -183,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
@@ -427,6 +430,8 @@ const COMMANDS = [
     "jobs",
     "apps",
     "builds",
+    "containers",
+    "agents",
     "domains",
     "ports",
     "ips",
@@ -447,6 +452,8 @@ const OWN_HELP = [
     "jobs",
     "apps",
     "builds",
+    "containers",
+    "agents",
     "keys",
     "webhooks",
     "webhook",
@@ -600,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)))],
     ]);
 }
@@ -1111,6 +1132,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 +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) {
@@ -1444,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. */
@@ -1888,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")
@@ -2745,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 = [
@@ -3749,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
@@ -3818,6 +3876,7 @@ const CREATE_VALUES = [
     "image",
     "snapshot",
     "spread-from",
+    "secret",
     "volume",
     "env",
 ];
@@ -3836,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"])
@@ -3857,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") {