withruntime 0.8.1 → 0.8.3

package/dist/cli.js

@@ -7,7 +7,7 @@ import { connectionOrigins, connectionStore, resolveCredential } from "./credent
 import { me, named } from "./cli-name.js";
 import { Runtime } from "./client.js";
 import { Sandbox as SandboxHandle } from "./sandbox.js";
-import { RuntimeError } from "./errors.js";
+import { NotFoundError, RuntimeError } from "./errors.js";
 import { NETWORK_PRODUCTS, networkProductCommand } from "./network-cli.js";
 import { billingCommand } from "./billing-cli.js";
 import { envFetch } from "./proxy.js";
@@ -40,9 +40,12 @@ Account
             [--allow '[GET,HEAD] /path/*']...  Store a secret sandboxes use without seeing it; the
                                                value is read from standard input, never an argument.
                                                --allow (paid): only these methods and paths get it
-  secrets ls                                   Names, hosts and placeholders, never values
-  secrets rm <NAME>                            Delete a secret
-  keys create [--name <name>] [--read-only] [--daily-limit <usd>]
+  secrets ls | get <NAME>                      Names, hosts and placeholders, never values
+  secrets rotate <NAME>                        A new version of the jobs copy, from standard input
+  secrets reveal <NAME> [--version N]          Print the jobs copy's value. The sandboxes' copy is
+                                               never readable, by anyone
+  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
   referrals                                    Your referral link: you both get up to $500
   compare --from <provider> [--days 30]        What your usage would cost at e2b, daytona, vercel,
@@ -146,6 +149,11 @@ const SANDBOX_HELP = `runtime sandbox <command>
                                               far; prints the new token
   previews <id>                               Every shared port
   unshare <id> <port>                         Stop sharing a port
+  session create <id> [--origin <url>]... [--ttl <s>] [--name <n>]
+                                              A token a web page uses for this sandbox's commands,
+                                              files and previews; printed once
+  session ls <id> | session revoke <id> <session-id>
+                                              Its sessions; end one now
   network <id> [--no-internet|--internet] [--allow <host>]... [--deny <host>]... [--connect <host:port>]...
                                               Show its network rules, or replace them
   identity-token --audience <aud> [--lifetime <seconds>]
@@ -328,6 +336,7 @@ const COMMANDS = [
     "snapshot",
     "image",
     "volume",
+    "job",
     "domain",
     "port",
     "address",
@@ -350,6 +359,8 @@ const OWN_HELP = [
     "images",
     "volume",
     "volumes",
+    "job",
+    "jobs",
     "keys",
     "webhooks",
     "webhook",
@@ -397,6 +408,7 @@ const SANDBOX_VERBS = [
     "preview",
     "previews",
     "unshare",
+    "session",
     "network",
     "desktop",
     "metrics",
@@ -899,6 +911,10 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         product = "volume";
         return volume(rest, env, out);
     }
+    if (command === "job" || command === "jobs") {
+        product = "job";
+        return jobCommand(rest, env, out);
+    }
     const networkProduct = { domains: "domain", ports: "port", addresses: "address", tunnels: "tunnel" }[command] ??
         command;
     if (NETWORK_PRODUCTS.includes(networkProduct)) {
@@ -1089,6 +1105,38 @@ const RIVAL_NAMES = {
     fly: "Fly",
     blaxel: "Blaxel",
 };
+/** The rivals whose SDK runs on Runtime unchanged but for one import, and that
+ * import in JavaScript and Python. Held to the guides' own lines by
+ * `tests/cli-drop-in.test.ts`. */
+const DROP_IN = {
+    e2b: {
+        js: 'import { Sandbox } from "withruntime/e2b"; // was: from "e2b"',
+        py: "from withruntime.e2b import Sandbox  # was: from e2b import Sandbox",
+    },
+    daytona: {
+        js: 'import { Daytona } from "withruntime/daytona"; // was: from "@daytona/sdk"',
+        py: "from withruntime.daytona import Daytona  # was: from daytona import Daytona",
+    },
+    vercel: {
+        js: 'import { Sandbox } from "withruntime/vercel"; // was: from "@vercel/sandbox"',
+        py: "from withruntime.vercel import sandbox  # was: from vercel import sandbox",
+    },
+    blaxel: {
+        js: 'import { SandboxInstance } from "withruntime/blaxel"; // was: from "@blaxel/core"',
+        py: "from withruntime.blaxel import SandboxInstance  # was: from blaxel.core import SandboxInstance",
+    },
+};
+/** How to move a rival's code across, when one import does it. */
+export function dropInLines(provider) {
+    const drop = provider && DROP_IN[provider];
+    if (!drop)
+        return [];
+    return [
+        `Your ${RIVAL_NAMES[provider]} code runs on Runtime with one import changed:`,
+        `  ${drop.js}`,
+        `  ${drop.py}`,
+    ];
+}
 /** A date as the CLI writes one: 23 September 2026. */
 const longDate = (iso) => new Date(iso).toLocaleDateString("en-GB", {
     day: "numeric",
@@ -1175,7 +1223,10 @@ async function switching(command, argv, env, out) {
         if (!provider || from === "fly-machines")
             throw unknown("provider", from, Object.keys(RIVAL_NAMES));
         const summary = await api.record({ provider });
-        print(`Recorded: switching from ${RIVAL_NAMES[provider]}. ${switchingLine(summary) ?? ""}`.trim(), summary);
+        print([
+            `Recorded: switching from ${RIVAL_NAMES[provider]}. ${switchingLine(summary) ?? ""}`.trim(),
+            ...dropInLines(provider),
+        ].join("\n"), summary);
         return 0;
     }
     if (!from)
@@ -1217,9 +1268,13 @@ async function switching(command, argv, env, out) {
             `The example: ${figures}.`,
         ];
     lines.push(`${c.rival.name}'s published rates, checked ${longDate(`${c.rival.checked}T12:00:00Z`)}: ${c.rival.rates.join("; ")}. Compute only, with the disk where a rival bills it while running: storage at rest, network, plan fees and free allowances are left out.`);
-    const line = switchingLine(c.switching, Object.hasOwn(SWITCH_FROM, from) ? SWITCH_FROM[from] : undefined);
+    const rival = Object.hasOwn(SWITCH_FROM, from) ? SWITCH_FROM[from] : undefined;
+    const line = switchingLine(c.switching, rival);
     if (line)
         lines.push("", line);
+    const drop = dropInLines(rival);
+    if (drop.length)
+        lines.push("", ...drop);
     print(lines.join("\n"), c);
     return 0;
 }
@@ -1603,6 +1658,43 @@ async function sandbox(argv, env, out) {
                 : "No shared ports. Share one: runtime sandbox preview <id> 3000", list);
             return 0;
         }
+        case "session": {
+            const verb = rest[0];
+            if (verb === "ls") {
+                const list = await (await use(rest[1])).sessions.list();
+                print(list.length
+                    ? table([
+                        ["ID", "STATE", "EXPIRES", "ORIGINS"],
+                        ...list.map((one) => [
+                            one.id,
+                            one.state,
+                            one.expiresAt,
+                            one.origins.join(",") || "-",
+                        ]),
+                    ])
+                    : "No sessions. Make one: runtime sandbox session create <id> --origin https://app.example.com", list);
+                return 0;
+            }
+            if (verb === "revoke") {
+                const sessionId = need(rest[2], "a session id: runtime sandbox session revoke <id> <session-id>");
+                const ended = await (await use(rest[1])).sessions.revoke(sessionId);
+                print(`Session ${ended.id} ended.`, ended);
+                return 0;
+            }
+            if (verb !== "create")
+                throw usage("runtime sandbox session create <id> [--origin <url>]..., session ls <id>, or session revoke <id> <session-id>");
+            const args = parse(rest.slice(1), [], ["origin", "ttl", "name"]);
+            const origins = args.flags.get("origin") ?? [];
+            const ttl = integer(args, "ttl");
+            const name = flag(args, "name");
+            const made = await (await use(args.positional[0])).sessions.create({
+                ...(ttl === undefined ? {} : { ttlSeconds: ttl }),
+                ...(origins.length ? { origins } : {}),
+                ...(name === undefined ? {} : { name }),
+            });
+            print(`${made.token}\nFor sandbox ${made.sandboxId} until ${made.expiresAt}${made.origins.length ? `, from ${made.origins.join(", ")}` : ", from no browser page"}. Shown once: hand it to your page (Sandbox.fromSession), never log it.`, made);
+            return 0;
+        }
         case "unshare": {
             const port = portOf(rest[1], "runtime sandbox unshare <id> 3000");
             const sbx = await use(rest[0]);
@@ -1750,45 +1842,70 @@ 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, [], ["host", "header", "format", "allow", "value"]);
+    const args = parse(rest, ["jobs"], ["host", "header", "format", "allow", "value", "version"]);
     const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
     const rows = (list) => list.length
         ? table([
-            ["name", "hosts", "header", "placeholder", "allow"],
-            ...list.map((secret) => [
-                secret.name,
-                secret.hosts.join(","),
-                secret.header ? `${secret.header}: ${secret.format ?? "{value}"}` : "-",
-                secret.placeholder,
-                ruleText(secret.rules),
+            ["name", "hosts", "header", "placeholder", "allow", "jobs"],
+            ...list.map(({ name, sandboxes: secret, jobs }) => [
+                name,
+                secret ? secret.hosts.join(",") : "-",
+                secret?.header ? `${secret.header}: ${secret.format ?? "{value}"}` : "-",
+                secret ? secret.placeholder : "-",
+                secret ? ruleText(secret.rules) : "-",
+                jobs ? `v${jobs.version}` : "-",
             ]),
         ])
         : "No secrets.";
     if (verb === "ls" || verb === "list" || verb === undefined) {
-        const list = await (await client(env)).secrets.list();
-        print(rows(list), list);
+        const runtime = await client(env);
+        const all = await runtime.secrets.all();
+        // --json keeps the sandboxes' list it always printed; the jobs copies
+        // are in `runtime secrets get <NAME> --json`.
+        print(rows(all), all.flatMap((s) => (s.sandboxes ? [s.sandboxes] : [])));
+        return 0;
+    }
+    const jobsOnly = "Only a secret's copy for jobs has versions and can be read back";
+    if (verb === "get") {
+        const found = await (await client(env)).secrets.get(need(args.positional[0], "the secret's name"));
+        print(rows([found]), found);
         return 0;
     }
-    if (verb === "set") {
+    if (verb === "set" || verb === "rotate") {
         const name = need(args.positional[0], "the secret's name, such as OPENAI_API_KEY");
         const hosts = args.flags.get("host") ?? [];
-        if (!hosts.length)
-            throw usage("Give --host once for each host the value may go to, such as --host api.openai.com.");
+        const jobs = verb === "rotate" || has(args, "jobs");
+        if (verb === "rotate" && (hosts.length || args.flags.has("header") || args.flags.has("allow")))
+            throw usage(`rotate replaces the copy for jobs. ${jobsOnly}; to change the sandboxes' copy, set it again with --host.`);
+        if (!hosts.length && !jobs)
+            throw usage("Give --host once for each host the value may go to, such as --host api.openai.com, and/or --jobs to let scheduled jobs use it.");
         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 ...');
+        const runtime = await client(env);
+        if (verb === "rotate") {
+            const rotated = await runtime.secrets.rotate(name, value);
+            print(`Rotated ${name} for jobs to version ${rotated.version}. Runs bound to the old version are refused it.`, rotated);
+            return 0;
+        }
+        if (!hosts.length) {
+            const saved = await runtime.secrets.set(name, { value, jobs: true });
+            print(`Stored ${name} for jobs, version ${saved.jobs.version}. Bind it: ${me} job create ... --secret ${name}`, saved);
+            return 0;
+        }
         const header = flag(args, "header");
         const format = flag(args, "format");
         const allow = args.flags.get("allow");
         const rules = allow ? parseSecretRules(allow) : undefined;
-        const saved = await (await client(env)).secrets.set(name, {
+        const saved = await runtime.secrets.set(name, {
             value,
             hosts,
             ...(header ? { header } : {}),
             ...(format ? { format } : {}),
             ...(rules ? { rules } : {}),
+            ...(jobs ? { jobs: true } : {}),
         });
         print([
             `Stored ${saved.name}. Sandboxes see ${saved.name}=${saved.placeholder}.`,
@@ -1799,16 +1916,30 @@ read = readSecret) {
             ...(saved.enforced
                 ? []
                 : ["A host is catching up; running sandboxes have it within a minute."]),
+            ...(saved.jobs
+                ? [
+                    `Also stored for jobs, version ${saved.jobs.version}: --secret ${saved.name} on ${me} job create.`,
+                ]
+                : []),
         ].join("\n"), saved);
         return 0;
     }
+    if (verb === "reveal") {
+        const name = need(args.positional[0], "the secret's name");
+        const version = flag(args, "version");
+        if (version !== undefined && !/^\d+$/.test(version))
+            throw usage("--version takes a number.");
+        const shown = await (await client(env)).secrets.reveal(name, version === undefined ? {} : { version: Number(version) });
+        print(shown.value, shown);
+        return 0;
+    }
     if (verb === "rm" || verb === "delete") {
         const name = need(args.positional[0], "the secret's name");
         const removed = await (await client(env)).secrets.delete(name);
-        print(`Deleted ${name}.`, removed);
+        print(`Deleted ${name}${removed.from.length > 1 ? " for sandboxes and jobs" : removed.from[0] === "jobs" ? " for jobs" : ""}.`, removed);
         return 0;
     }
-    throw usage("secrets takes set, ls or rm. Run `runtime help`.");
+    throw usage("secrets takes set, ls, get, rotate, reveal or rm. Run `runtime help`.");
 }
 async function readInput(source) {
     if (source !== "-")
@@ -1930,11 +2061,14 @@ async function desktop(sbx, argv, out) {
 }
 const KEYS_HELP = `runtime keys <command>
 
-  create [--name <name>] [--read-only] [--daily-limit <usd>]
+  create [--name <name>] [--read-only] [--daily-limit <usd>] [--account-wide]
       A new API key, for a CI runner or any place with no browser. Prints a link
       and a code; an account owner approves the key in the browser, seeing its
       name, access and limit. The key is printed once, alone on stdout, and
       lasts until revoked. --json prints it as JSON, still alone on stdout.
+      --account-wide makes a key that sees and uses every sandbox and other
+      resource in the account, whichever key made it; only an owner or admin
+      can approve one. Without it, a key sees only what it makes.
 
   runtime keys create --name ci --daily-limit 25 | gh secret set RUNTIME_API_KEY
 
@@ -2060,8 +2194,8 @@ async function keys(argv, env, out) {
         throw usage("List and revoke keys at https://withruntime.com/account/keys. No key can list or revoke keys.");
     if (verb !== "create")
         throw unknown("keys command", verb, ["create"]);
-    const args = parse(rest, ["read-only"], ["name", "daily-limit"]);
-    const known = new Set(["name", "read-only", "daily-limit"]);
+    const args = parse(rest, ["read-only", "account-wide"], ["name", "daily-limit"]);
+    const known = new Set(["name", "read-only", "daily-limit", "account-wide"]);
     for (const name of args.flags.keys())
         if (!known.has(name))
             throw usage(`Unknown option --${name}.`);
@@ -2071,16 +2205,20 @@ async function keys(argv, env, out) {
     const limit = flag(args, "daily-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"))
+        throw usage("A read-only key already sees the whole account, so it takes no --account-wide.");
     const { createKey, dailyLimitMicros } = await import("./keys.js");
     const created = await createKey({
         name: flag(args, "name") ?? (readOnly ? "Read-only key" : "My API key"),
         access: readOnly ? "read" : "full",
+        ...(has(args, "account-wide") ? { reach: "account" } : {}),
         dailyLimitMicros: limit === undefined ? null : dailyLimitMicros(limit),
     }, env, { notify: out.error });
     const { confirm, ...key } = created;
     out.write(out.json ? JSON.stringify(key) : key.key);
     const terms = [
         key.access === "read" ? "read only" : "full access",
+        key.reach === "account" ? "account-wide" : undefined,
         key.access === "read"
             ? undefined
             : key.dailyLimitMicros === null
@@ -2398,6 +2536,257 @@ read = readSecret) {
         "registry",
     ]);
 }
+const JOB_HELP = `runtime job <command>
+
+  A job runs a command in a fresh sandbox, once or on a schedule. Each run is a
+  paid sandbox billed at the sandbox rates; the trial's hours do not fund jobs.
+
+  create <name> (--cron "<min hour day month weekday>" [--timezone Europe/Berlin] | --at <time|now>)
+         [--vcpu 2] [--memory 4096] [--disk 4096] [--cpu shared|reserved] [--cpu-floor <thousandths>]
+         [--timeout 1800] [--attempts 1] [--backoff 30] [--secret NAME[=ENV_NAME]]...
+         [--cwd /workspace/dir] [--max-cost <usd>] [--max-total-cost <usd>] [--region r] -- <command...>
+                                              Schedule it; prints its id. Nothing runs until its time.
+                                              --at takes an ISO time (2026-10-01T03:00:00Z) or now.
+                                              The command runs as given, no shell: -- bash -lc '...'
+                                              --attempts: tries per occurrence when it exits non-zero, 1 to 5.
+                                              --secret: a secret stored with --jobs, in the run's
+                                              environment as ENV_NAME (NAME by default)
+  ls                                          Your jobs: state, schedule and next run
+  get <id>                                    One job, in full
+  runs <id>                                   Its runs: state, exit code, when
+  logs <runId|jobId> [-f]                     A run's output (a job id: its latest run); -f follows it
+  pause <id> | resume <id>                    Stop or restart scheduling; a run already going finishes
+  cancel <id>                                 End it for good and stop a run in progress
+
+Examples
+  runtime job create nightly --cron "0 3 * * *" --timezone Europe/Berlin -- python3 /workspace/report.py
+  runtime job create once --at now -- bash -lc 'echo hello from a job'
+  runtime job logs <jobId> -f
+`;
+const when = (ms) => (ms == null ? "-" : new Date(ms).toISOString());
+function scheduleText(job) {
+    const s = job.definition.schedule;
+    return s.kind === "once" ? `once at ${when(s.at)}` : `${s.expression} ${s.timezone ?? "UTC"}`;
+}
+/** Seconds from the command line, `--at`: an ISO time, Unix milliseconds or
+ * `now`. A time well in the past is refused: the job would run at once, and
+ * that is what `now` says. */
+function atTime(value, now = Date.now()) {
+    if (value === "now")
+        return now;
+    const at = /^\d+$/.test(value) ? Number(value) : Date.parse(value);
+    if (!Number.isSafeInteger(at))
+        throw usage(`--at takes an ISO time such as 2026-10-01T03:00:00Z, or now; got ${value}.`);
+    if (at < now - 60_000)
+        throw usage(`--at ${value} is in the past. To run it at once, say --at now.`);
+    return at;
+}
+async function jobCommand(argv, env, out) {
+    const [verb, ...rest] = argv;
+    const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
+    if (!verb || verb === "help" || verb === "--help") {
+        print(named(JOB_HELP), { usage: named(JOB_HELP) });
+        return 0;
+    }
+    const runtime = await client(env);
+    const api = runtime.jobs;
+    switch (verb) {
+        case "create": {
+            const args = parse(rest, [], [
+                "cron",
+                "timezone",
+                "at",
+                "vcpu",
+                "memory",
+                "disk",
+                "cpu",
+                "cpu-floor",
+                "timeout",
+                "attempts",
+                "backoff",
+                "secret",
+                "cwd",
+                "max-cost",
+                "max-total-cost",
+                "region",
+            ], `${me} job create <name> --cron "0 3 * * *" -- python3 -c '...'`);
+            const name = need(args.positional[0], "the job's name, such as nightly-report");
+            if (args.positional.length > 1)
+                throw usage(`Put the command after --: ${me} job create ${name} ... -- ${args.positional.slice(1).join(" ")}`);
+            const argv = args.rest ?? [];
+            if (!argv.length)
+                throw usage(`Give the command after --: ${me} job create ${name} --at now -- echo hello`);
+            const cron = flag(args, "cron");
+            const at = flag(args, "at");
+            if ((cron === undefined) === (at === undefined))
+                throw usage('Give --cron "<five fields>" for a schedule, or --at <time|now> for one run.');
+            if (at !== undefined && flag(args, "timezone") !== undefined)
+                throw usage("--timezone goes with --cron; --at takes a time with its own offset.");
+            const attempts = integer(args, "attempts");
+            const backoff = integer(args, "backoff");
+            if (backoff !== undefined && attempts === undefined)
+                throw usage("--backoff goes with --attempts: the seconds between tries.");
+            const bindings = args.flags.get("secret") ?? [];
+            let secrets;
+            if (bindings.length) {
+                const known = await runtime.secrets.all();
+                secrets = bindings.map((binding) => {
+                    const [secret, env = secret] = binding.split("=", 2);
+                    const found = known.find((s) => s.name === secret)?.jobs;
+                    if (!found)
+                        throw usage(`${secret} has no copy for jobs. Store one: printf %s "$VALUE" | ${me} secrets set ${secret} --jobs`);
+                    return { name: env, secretId: found.id };
+                });
+            }
+            const cwd = flag(args, "cwd");
+            const job = await api.create({
+                name,
+                schedule: cron !== undefined
+                    ? { cron, ...(flag(args, "timezone") ? { timezone: flag(args, "timezone") } : {}) }
+                    : { at: atTime(at) },
+                command: cwd ? { argv, cwd } : argv,
+                ...(integer(args, "timeout") ? { timeoutSeconds: integer(args, "timeout") } : {}),
+                compute: {
+                    ...(integer(args, "vcpu") ? { vcpu: integer(args, "vcpu") } : {}),
+                    ...(integer(args, "memory") ? { memoryMiB: integer(args, "memory") } : {}),
+                    ...(integer(args, "disk") ? { diskMiB: integer(args, "disk") } : {}),
+                    ...(flag(args, "cpu")
+                        ? { cpuMode: oneOf(args, "cpu", ["shared", "reserved"]) }
+                        : {}),
+                    ...(integer(args, "cpu-floor") ? { cpuFloorMillis: integer(args, "cpu-floor") } : {}),
+                    ...(flag(args, "region") ? { region: flag(args, "region") } : {}),
+                    ...(usdMicros(args, "max-cost") ? { maxCostMicros: usdMicros(args, "max-cost") } : {}),
+                },
+                ...(attempts !== undefined
+                    ? { retry: { maxAttempts: attempts, backoffSeconds: backoff ?? 30 } }
+                    : {}),
+                ...(secrets ? { secrets } : {}),
+                ...(usdMicros(args, "max-total-cost")
+                    ? { maxTotalCostMicros: usdMicros(args, "max-total-cost") }
+                    : {}),
+            });
+            if (!out.json)
+                out.error(`Scheduled ${job.name}: ${scheduleText(job)}. Next run ${when(job.nextRunAt)}. Follow it: ${me} job logs ${job.id} -f`);
+            print(job.id, job);
+            return 0;
+        }
+        case "ls":
+        case "list": {
+            const all = await (await api.list({ limit: 100 })).toArray(1000);
+            print(all.length
+                ? table([
+                    ["ID", "NAME", "STATE", "SCHEDULE", "NEXT RUN", "BLOCKED"],
+                    ...all.map((j) => [
+                        j.id,
+                        j.name,
+                        j.state,
+                        scheduleText(j),
+                        when(j.nextRunAt),
+                        j.blockedReason ?? "-",
+                    ]),
+                ])
+                : `No jobs. Schedule one: ${me} job create hello --at now -- echo hello`, all);
+            return 0;
+        }
+        case "get": {
+            const found = await api.get(need(rest[0], "a job id"));
+            print(JSON.stringify(found, null, 2), found);
+            return 0;
+        }
+        case "runs": {
+            const jobId = need(rest[0], "a job id");
+            const all = await (await api.runs(jobId, { limit: 100 })).toArray(1000);
+            print(all.length
+                ? table([
+                    ["RUN", "ATTEMPT", "STATE", "EXIT", "SCHEDULED", "STARTED", "ENDED", "REASON"],
+                    ...all.map((r) => [
+                        r.id,
+                        String(r.attempt),
+                        r.state,
+                        r.exitCode === null ? "-" : String(r.exitCode),
+                        when(r.scheduledFor),
+                        when(r.startedAt),
+                        when(r.endedAt),
+                        r.reason ?? "-",
+                    ]),
+                ])
+                : "No runs yet.", all);
+            return 0;
+        }
+        case "logs": {
+            const args = parse(rest, ["f", "follow"], []);
+            const id = need(args.positional[0], "a run id or a job id");
+            let runId = id;
+            try {
+                await api.run(id);
+            }
+            catch (error) {
+                if (!(error instanceof NotFoundError))
+                    throw error;
+                // A job's id: its latest run.
+                const runs = await (await api.runs(id, { limit: 100 })).toArray(1000);
+                const latest = runs.at(-1);
+                if (!latest) {
+                    const job = await api.get(id);
+                    print(`${job.name} has not run yet. Next run ${when(job.nextRunAt)}.`, {
+                        chunks: [],
+                        nextCursor: 0,
+                        truncated: false,
+                        complete: false,
+                    });
+                    return 0;
+                }
+                runId = latest.id;
+            }
+            const follow = has(args, "f") || has(args, "follow");
+            let cursor = 0;
+            for (;;) {
+                const page = await api.logs(runId, { cursor, limitBytes: 65536 });
+                if (out.json)
+                    out.write(JSON.stringify(page));
+                else
+                    for (const chunk of page.chunks)
+                        (chunk.stream === "stderr" ? process.stderr : process.stdout).write(chunk.text);
+                cursor = page.nextCursor;
+                if (page.complete) {
+                    if (!out.json) {
+                        const run = await api.run(runId);
+                        if (page.truncated)
+                            process.stderr.write("[the run printed more than it keeps; this is its last part]\n");
+                        process.stderr.write(`[${run.state}${run.exitCode === null ? "" : `, exit code ${run.exitCode}`}${run.reason ? `, ${run.reason}` : ""}]\n`);
+                    }
+                    return 0;
+                }
+                if (page.chunks.length)
+                    continue;
+                if (!follow) {
+                    if (!out.json)
+                        process.stderr.write(`[${runId} is still going; follow it: ${me} job logs ${runId} -f]\n`);
+                    return 0;
+                }
+                await new Promise((resolve) => setTimeout(resolve, 1000));
+            }
+        }
+        case "pause":
+        case "resume":
+        case "cancel": {
+            const id = need(rest[0], "a job id");
+            const job = await api[verb](id);
+            print(`${job.name} ${job.state}.`, job);
+            return 0;
+        }
+    }
+    throw unknown("job command", verb, [
+        "create",
+        "ls",
+        "get",
+        "runs",
+        "logs",
+        "pause",
+        "resume",
+        "cancel",
+    ]);
+}
 const VOLUME_HELP = `runtime volume <command>
 
   create --size-mib <N> [--name n]            A persistent ext4 disk; prints its id

package/dist/daytona/daytona.js

@@ -170,7 +170,7 @@ export class Daytona {
         this.#create = config.withruntime?.create ?? {};
         this.snapshot = new SnapshotService(this.#client);
         this.volume = new VolumeService(this.#client);
-        this.secret = unsupportedService("secrets", "Pass credentials as envVars or per command, never in the command text.");
+        this.secret = unsupportedService("secrets", "Use a Runtime secret: `npx withruntime secrets set NAME --host api.example.com`. The sandbox sees a placeholder, and the egress proxy adds the value on HTTPS to that host.");
         this.warmPool = unsupportedService("warm pools", "Runtime starts sandboxes from warm templates already; nothing to configure.");
     }
     async [Symbol.asyncDispose]() { }
@@ -370,11 +370,15 @@ function refuseCreate(params) {
             "Linked sandboxes (linkedSandbox)",
             "Run both programs in one sandbox, or connect them through a preview address.",
         ],
-        ["secrets", "Daytona secrets", "Pass credentials as envVars, never in the command text."],
+        [
+            "secrets",
+            "Daytona secrets",
+            "Use a Runtime secret: `npx withruntime secrets set NAME --host api.example.com`. The sandbox sees a placeholder, and the egress proxy adds the value on HTTPS to that host.",
+        ],
         [
             "otelEndpointOverride",
             "Sending sandbox telemetry elsewhere (otelEndpointOverride)",
-            "Remove it: Runtime does not export sandbox telemetry.",
+            "Remove it: runtime.otel.create() exports every sandbox's events and CPU and memory metrics over OTLP/HTTP.",
         ],
     ];
     for (const [field, feature, alternative] of refusals)

package/dist/daytona/sandbox.js

@@ -386,7 +386,7 @@ export class Sandbox {
         return this.resize();
     }
     getMetrics() {
-        return refusal("Sandbox metrics", "Runtime reports CPU, memory and charges per sandbox in `npx withruntime usage` and runtime.usage().");
+        return refusal("Sandbox metrics", 'Use `await sandbox.withruntime.metrics({ range: "1h" })` for its CPU and memory over time; runtime.otel exports them to your own tools.');
     }
     getMetricsLatest() {
         return this.getMetrics();
@@ -395,7 +395,7 @@ export class Sandbox {
         throw new NotSupportedError("Daytona's language servers", "Start one in a session: process.executeSessionCommand(id, { command: 'pyright-langserver --stdio', runAsync: true }).");
     }
     updateSecrets() {
-        return refusal("Daytona secrets", "Pass credentials as envVars or per command, never in the command text.");
+        return refusal("Daytona secrets", "Use a Runtime secret: `npx withruntime secrets set NAME --host api.example.com`. The sandbox sees a placeholder, and the egress proxy adds the value on HTTPS to that host.");
     }
     getSignedPreviewUrl() {
         return refusal("Signed preview URLs", "Use getPreviewLink(port) and send its token as the x-runtime-preview-token header, or create the sandbox with public: true.");
@@ -413,7 +413,7 @@ export class Sandbox {
         return refusal("Signed download URLs", "Use sandbox.fs.downloadFile(path).");
     }
     createSshAccess() {
-        return refusal("SSH access", "Use `npx withruntime sandbox shell <id>` or sandbox.withruntime.terminal().");
+        return refusal("SSH access", "Use `npx withruntime sandbox ssh <id>` (also VS Code and JetBrains) or sandbox.withruntime.terminal().");
     }
     revokeSshAccess() {
         return this.createSshAccess();