withruntime 0.10.0 → 0.11.0

package/dist/cli.js

@@ -88,7 +88,7 @@ Observability
                                                Events and metrics to an OpenTelemetry endpoint
 
 Products
-  sandbox   Linux microVMs: exec, shell, files, code, previews, network, desktop
+  sandbox   Linux microVMs: exec, shell, files, code, previews, network, desktop, browser
   snapshot  Saved sandboxes, disk and memory, to start or fork from
   image     Custom images from a Dockerfile, any public or private image, or a package list
   volume    Persistent disks to attach to sandboxes
@@ -97,7 +97,7 @@ Products
   port      A public TCP port to a sandbox: databases, game servers
   address   A dedicated outbound address, for allow-lists
   tunnel    A WireGuard tunnel from your own network into your sandboxes
-  network   Account-wide network settings: send outbound traffic through your own proxy
+  network   Account-wide network settings: your own proxy, sandboxes reaching each other by name
   Each has its own help: \`runtime sandbox help\`, \`runtime image help\`...
 
 Every command takes --json. Keys: RUNTIME_API_KEY, or the connection from \`runtime login\`.
@@ -131,11 +131,15 @@ const SANDBOX_HELP = `runtime sandbox <command>
   cat <id> <path>                             Print a file
   files <id> [path] [--depth 1] [--glob '**/*.py']
   stop <id> | pause <id> | wake <id> | restart <id>
+  stop --label k=v [--label k=v]...           Stop every live sandbox with all those labels
   rm <id>                                     Delete it for good: stops it, deletes its disk and
                                               paused memory, revokes its previews; snapshots stay
   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)
   extend <id> <seconds>                       More time before the lease ends
   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]
@@ -180,6 +184,8 @@ const SANDBOX_HELP = `runtime sandbox <command>
                | type <text> | press <keys> | windows
   desktop <id> record start [--fps 10] [--max-seconds 1800] [--max-mib 512] | record stop <recId>
                | record ls | record fetch <recId> [file.mp4] | record rm <recId>
+  browser <id> start [--headed] [--width 1280] [--height 800] | get | stop
+                                              Chromium for CDP agents: prints its cdpUrl
 
 Examples
   id=$(runtime sandbox create)
@@ -410,6 +416,7 @@ const SANDBOX_VERBS = [
     "rm",
     "delete",
     "switch-image",
+    "resize",
     "pause",
     "wake",
     "restart",
@@ -437,6 +444,7 @@ const SANDBOX_VERBS = [
     "session",
     "network",
     "desktop",
+    "browser",
     "metrics",
     "watch",
     "mcp",
@@ -1495,6 +1503,21 @@ async function sandbox(argv, env, out) {
             print(describe(sbx.info), sbx.info);
             return 0;
         }
+        case "resize": {
+            const args = parse(rest, ["restart"], ["vcpu", "memory"]);
+            const sbx = await use(need(args.positional[0], `a sandbox, e.g. ${me} sandbox resize <id> --memory 4096 --restart`));
+            const size = {
+                ...(integer(args, "vcpu") !== undefined ? { vcpu: integer(args, "vcpu") } : {}),
+                ...(integer(args, "memory") !== undefined ? { memoryMiB: integer(args, "memory") } : {}),
+            };
+            if (size.vcpu === undefined && size.memoryMiB === undefined)
+                throw usage(`Name a new size, e.g. ${me} sandbox 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} sandbox snapshot ${sbx.id}) to keep its memory too.`);
+            await sbx.resize(size, { restart: true });
+            print(describe(sbx.info), sbx.info);
+            return 0;
+        }
         case "rm":
         case "delete": {
             const sbx = await use(need(rest[0], `a sandbox, e.g. ${me} sandbox rm <id>`));
@@ -1506,6 +1529,23 @@ async function sandbox(argv, env, out) {
         case "pause":
         case "wake":
         case "restart": {
+            if (verb === "stop" && rest.some((word) => /^--label(=|$)/.test(word))) {
+                const args = parse(rest, [], ["label"]);
+                if (args.positional.length)
+                    throw usage("Give a sandbox id or --label, not both.");
+                const { stopped, failed } = await runtime.sandboxes.stopAll({
+                    labels: pairs(args, "label"),
+                });
+                const said = (error) => (error instanceof Error ? error.message : String(error));
+                print([
+                    stopped.length || failed.length
+                        ? `${stopped.length} stopped${failed.length ? `, ${failed.length} failed` : ""}.`
+                        : "No live sandbox has those labels.",
+                    ...stopped.map((id) => `${id} stopped`),
+                    ...failed.map((f) => `${f.id} failed: ${said(f.error)}`),
+                ].join("\n"), { stopped, failed: failed.map((f) => ({ id: f.id, error: said(f.error) })) });
+                return failed.length ? 1 : 0;
+            }
             const sbx = await get(rest[0]);
             await sbx[verb]();
             print(`${sbx.id} ${sbx.state}`, sbx.info);
@@ -1893,6 +1933,8 @@ async function sandbox(argv, env, out) {
         }
         case "desktop":
             return desktop(await use(rest[0]), rest.slice(1), out);
+        case "browser":
+            return browser(await use(rest[0]), rest.slice(1), out);
         case "watch":
             return (await import("./cli-extras.js")).watchCommand(await use(rest[0]), rest.slice(1), out, kit);
         case "mcp":
@@ -2227,6 +2269,35 @@ async function desktop(sbx, argv, out) {
     }
     throw usage(`${me} sandbox desktop <id> start|stop|screenshot|open|click|type|press|windows|record`);
 }
+async function browser(sbx, argv, out) {
+    const [action, ...rest] = argv;
+    const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
+    switch (action) {
+        case "start": {
+            const args = parse(rest, ["headed"], ["width", "height"]);
+            const started = await sbx.browser.start({
+                ...(args.flags.has("headed") ? { headless: false } : {}),
+                ...(integer(args, "width") !== undefined ? { width: integer(args, "width") } : {}),
+                ...(integer(args, "height") !== undefined ? { height: integer(args, "height") } : {}),
+            });
+            print(`${started.version}${started.headless ? "" : `, on the desktop: ${started.streamUrl}`}\n` +
+                `CDP: ${started.cdpUrl}\n(private; it expires ${started.expiresAt ?? "never"})`, started);
+            return 0;
+        }
+        case "get":
+        case undefined: {
+            const state = await sbx.browser.get();
+            print(state.running ? `${state.version}\nCDP: ${state.cdpUrl}` : "No browser running.", state);
+            return 0;
+        }
+        case "stop": {
+            const stopped = await sbx.browser.stop();
+            print(stopped.stopped ? "Browser stopped." : "No browser was running.", stopped);
+            return 0;
+        }
+    }
+    throw usage(`${me} sandbox browser <id> start [--headed]|get|stop`);
+}
 const KEYS_HELP = `runtime keys <command>
 
   create [--name <name>] [--read-only] [--daily-limit <usd>] [--account-wide]

package/dist/client.d.ts

@@ -118,6 +118,18 @@ export declare class Sandboxes {
         name?: string;
         limit?: number;
     }, options?: RequestOptions): Promise<Page<Sandbox>>;
+    /** Stops every live sandbox whose labels all match, eight at a time, and
+     * says which stopped and which failed; one failure does not stop the rest.
+     * Needs at least one label, so stopping everything is never one call. */
+    stopAll(filter: {
+        labels: Record<string, string>;
+    }, options?: RequestOptions): Promise<{
+        stopped: string[];
+        failed: {
+            id: string;
+            error: unknown;
+        }[];
+    }>;
 }
 export declare class FeedbackApi {
     private readonly t;

package/dist/client.js

@@ -156,6 +156,33 @@ export class Sandboxes {
         };
         return sandboxPage(this.t, await this.t.json({ method: "GET", path: "/v1/sandboxes", query, ...options }), query, options);
     }
+    /** Stops every live sandbox whose labels all match, eight at a time, and
+     * says which stopped and which failed; one failure does not stop the rest.
+     * Needs at least one label, so stopping everything is never one call. */
+    async stopAll(filter, options = {}) {
+        if (!filter?.labels || Object.keys(filter.labels).length === 0)
+            throw new RuntimeError({
+                message: "stopAll needs at least one label to match.",
+                code: "invalid_request",
+                status: 0,
+                hint: "Stop one sandbox with sandbox.stop(), or label the ones to stop together.",
+            });
+        const live = await (await this.list({ labels: filter.labels, limit: 100 }, options)).toArray(Infinity);
+        // One key cannot name several stops: each stop makes its own.
+        const { idempotencyKey: _one, ...each } = options;
+        // In list order, oldest first, whichever finishes first.
+        const errors = new Array(live.length);
+        let next = 0;
+        const worker = async () => {
+            for (let at = next++; at < live.length; at = next++)
+                await live[at].stop(each).catch((error) => (errors[at] = error ?? "failed"));
+        };
+        await Promise.all(Array.from({ length: Math.min(8, live.length) }, worker));
+        return {
+            stopped: live.filter((_, at) => errors[at] === undefined).map((sbx) => sbx.id),
+            failed: live.flatMap((sbx, at) => errors[at] === undefined ? [] : [{ id: sbx.id, error: errors[at] }]),
+        };
+    }
 }
 export class FeedbackApi {
     t;

package/dist/compat/lease.d.ts

@@ -0,0 +1,36 @@
+/** The most one lease runs ahead of now. */
+export declare const LEASE_MAX_SECONDS = 3600;
+/** What the keeper needs of a Runtime sandbox. */
+export interface Leased {
+    readonly state: string;
+    readonly info: {
+        expiresAt: string;
+    };
+    extend(seconds: number): Promise<unknown>;
+    refresh(): Promise<unknown>;
+}
+/** Whole seconds to add to a lease ending at `expiresAt` (epoch ms) so it
+ * reaches toward `until`, at most an hour ahead of `now`; 0 when more than
+ * `marginMs` is left or there is nothing to add. */
+export declare function extensionSeconds(expiresAt: number, until: number, now: number, marginMs: number): number;
+/** Keeps a running sandbox's lease reaching toward `until()`: on `check()`,
+ * and once a minute on a timer that never keeps a Node or Bun process alive.
+ * When the process ends, the lease runs out within the hour and the sandbox
+ * pauses or stops as it was told to at create. A paused or stopped sandbox is
+ * left alone; the adapter wakes it on its next call. */
+export declare class LeaseKeeper {
+    #private;
+    constructor(options: {
+        sandbox: () => Leased;
+        /** Epoch ms the lease should reach; Infinity for as long as this lives. */
+        until: () => number;
+        /** Extend only when less than this is left. */
+        marginMs: () => number;
+        everyMs?: number;
+    });
+    /** Extends the lease if it is near its end and should go further; `now`
+     * extends it as far as it may go whatever is left. One call at a time. */
+    check(now?: boolean): Promise<void>;
+    /** Stops extending: after stop() or delete(). */
+    end(): void;
+}

package/dist/compat/lease.js

@@ -0,0 +1,87 @@
+import { RuntimeError } from "../errors.js";
+/* A rival's sandbox may be asked to live longer than one Runtime lease (an
+   hour at most, ARCHITECTURE.md section 10): Vercel's `timeout` over an hour,
+   Daytona's `autoStopInterval` over an hour or 0. The drop-ins keep the lease
+   reaching toward the time asked for while their sandbox object lives, one
+   extension at a time, never past that time. */
+/** The most one lease runs ahead of now. */
+export const LEASE_MAX_SECONDS = 3600;
+/** Whole seconds to add to a lease ending at `expiresAt` (epoch ms) so it
+ * reaches toward `until`, at most an hour ahead of `now`; 0 when more than
+ * `marginMs` is left or there is nothing to add. */
+export function extensionSeconds(expiresAt, until, now, marginMs) {
+    // A lease with no readable end (one that never ends) is left alone.
+    if (!Number.isFinite(expiresAt) || expiresAt - now > marginMs)
+        return 0;
+    const target = Math.min(until, now + LEASE_MAX_SECONDS * 1000);
+    return Math.max(0, Math.floor((target - expiresAt) / 1000));
+}
+/** Keeps a running sandbox's lease reaching toward `until()`: on `check()`,
+ * and once a minute on a timer that never keeps a Node or Bun process alive.
+ * When the process ends, the lease runs out within the hour and the sandbox
+ * pauses or stops as it was told to at create. A paused or stopped sandbox is
+ * left alone; the adapter wakes it on its next call. */
+export class LeaseKeeper {
+    #sandbox;
+    #until;
+    #marginMs;
+    #everyMs;
+    #timer;
+    #pending;
+    #ended = false;
+    constructor(options) {
+        this.#sandbox = options.sandbox;
+        this.#until = options.until;
+        this.#marginMs = options.marginMs;
+        this.#everyMs = options.everyMs ?? 60_000;
+    }
+    /** Starts the timer when the lease must outlive the next extension. */
+    #schedule() {
+        if (this.#ended || this.#timer)
+            return;
+        const expiresAt = Date.parse(this.#sandbox().info.expiresAt);
+        if (!Number.isFinite(expiresAt) || this.#until() <= expiresAt)
+            return;
+        this.#timer = setTimeout(() => {
+            this.#timer = undefined;
+            void this.check().catch(() => undefined);
+        }, this.#everyMs);
+        this.#timer.unref?.();
+    }
+    /** Extends the lease if it is near its end and should go further; `now`
+     * extends it as far as it may go whatever is left. One call at a time. */
+    check(now = false) {
+        if (this.#ended)
+            return Promise.resolve();
+        this.#pending ??= this.#extend(now).finally(() => {
+            this.#pending = undefined;
+            this.#schedule();
+        });
+        return this.#pending;
+    }
+    async #extend(now) {
+        const sandbox = this.#sandbox();
+        if (sandbox.state !== "running")
+            return;
+        const seconds = extensionSeconds(Date.parse(sandbox.info.expiresAt), this.#until(), Date.now(), now ? Infinity : this.#marginMs());
+        if (seconds < 1)
+            return;
+        try {
+            await sandbox.extend(seconds);
+        }
+        catch (error) {
+            // The lease may have ended since the sandbox was last read; the next
+            // call through the adapter says what state it is in.
+            if (!(error instanceof RuntimeError && error.status === 409))
+                throw error;
+            await sandbox.refresh().catch(() => undefined);
+        }
+    }
+    /** Stops extending: after stop() or delete(). */
+    end() {
+        this.#ended = true;
+        if (this.#timer)
+            clearTimeout(this.#timer);
+        this.#timer = undefined;
+    }
+}

package/dist/daytona/computer-use.d.ts

@@ -0,0 +1,162 @@
+import type { RuntimeSandbox } from "./client.js";
+type Live = () => Promise<RuntimeSandbox>;
+export interface ScreenshotRegion {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface ScreenshotOptions {
+    showCursor?: boolean;
+    format?: string;
+    quality?: number;
+    scale?: number;
+}
+export interface Position {
+    x?: number;
+    y?: number;
+}
+export interface ScreenshotResponse {
+    cursorPosition?: Position;
+    /** The image, base64. */
+    screenshot?: string;
+    sizeBytes?: number;
+}
+export interface DisplayInfo {
+    height?: number;
+    id?: number;
+    isActive?: boolean;
+    width?: number;
+    x?: number;
+    y?: number;
+}
+export interface WindowInfo {
+    height?: number;
+    id?: number;
+    isActive?: boolean;
+    title?: string;
+    width?: number;
+    x?: number;
+    y?: number;
+}
+export interface ProcessStatus {
+    autoRestart?: boolean;
+    pid?: number;
+    priority?: number;
+    running?: boolean;
+}
+export interface ComputerUseStartResponse {
+    message?: string;
+    status?: Record<string, ProcessStatus>;
+}
+export type ComputerUseStopResponse = ComputerUseStartResponse;
+export interface ComputerUseStatusResponse {
+    status?: string;
+}
+export interface Recording {
+    durationSeconds?: number;
+    endTime?: string;
+    fileName: string;
+    filePath: string;
+    id: string;
+    sizeBytes?: number;
+    startTime: string;
+    status: string;
+}
+export interface ListRecordingsResponse {
+    recordings: Recording[];
+}
+/** `sandbox.computerUse.mouse`. */
+export declare class Mouse {
+    #private;
+    /** Use sandbox.computerUse.mouse. */
+    constructor(live: Live);
+    getPosition(): Promise<Position>;
+    move(x: number, y: number): Promise<Position>;
+    click(x: number, y: number, button?: string, double?: boolean): Promise<Position>;
+    drag(startX: number, startY: number, endX: number, endY: number, button?: string): Promise<Position>;
+    /** `amount` wheel clicks up or down at (x, y). */
+    scroll(x: number, y: number, direction: "up" | "down", amount?: number): Promise<boolean>;
+}
+/** `sandbox.computerUse.keyboard`. Key names are Daytona's (enter, esc,
+ * ctrl, cmd, pageup, f5) or xdotool's (Return, Escape, Prior). */
+export declare class Keyboard {
+    #private;
+    /** Use sandbox.computerUse.keyboard. */
+    constructor(live: Live);
+    /** Types `text`, `delay` milliseconds between keys. */
+    type(text: string, delay?: number): Promise<void>;
+    press(key: string, modifiers?: string[]): Promise<void>;
+    /** A combination such as "ctrl+c" or "ctrl+shift+t". */
+    hotkey(keys: string): Promise<void>;
+}
+/** `sandbox.computerUse.screenshot`: the whole screen, PNG or JPEG. */
+export declare class Screenshot {
+    #private;
+    /** Use sandbox.computerUse.screenshot. */
+    constructor(live: Live);
+    takeFullScreen(showCursor?: boolean): Promise<ScreenshotResponse>;
+    takeRegion(_region: ScreenshotRegion, _showCursor?: boolean): Promise<ScreenshotResponse>;
+    takeCompressed(options?: ScreenshotOptions): Promise<ScreenshotResponse>;
+    takeCompressedRegion(_region: ScreenshotRegion, _options?: ScreenshotOptions): Promise<ScreenshotResponse>;
+}
+/** `sandbox.computerUse.display`. */
+export declare class Display {
+    #private;
+    /** Use sandbox.computerUse.display. */
+    constructor(live: Live);
+    /** The one screen, its size read from a screenshot. */
+    getInfo(): Promise<{
+        displays?: DisplayInfo[];
+    }>;
+    getWindows(): Promise<{
+        windows?: WindowInfo[];
+    }>;
+}
+/** `sandbox.computerUse.recording`: screen recordings to MP4. */
+export declare class RecordingService {
+    #private;
+    /** Use sandbox.computerUse.recording. */
+    constructor(live: Live);
+    /** Starts recording. Runtime names the file itself; `label` is not used. */
+    start(_label?: string): Promise<Recording>;
+    stop(id: string): Promise<Recording>;
+    list(): Promise<ListRecordingsResponse>;
+    get(id: string): Promise<Recording>;
+    delete(id: string): Promise<void>;
+    /** Saves the MP4 to `localPath`, making its directory. */
+    download(id: string, localPath: string): Promise<void>;
+}
+/** `sandbox.computerUse.accessibility`: Runtime's desktop has no
+ * accessibility tree; every method throws NotSupportedError. */
+export declare class Accessibility {
+    #private;
+    getTree(_options?: unknown): Promise<never>;
+    findNodes(_options?: unknown): Promise<never>;
+    focusNode(_id: string): Promise<never>;
+    invokeNode(_id: string, _action?: string): Promise<never>;
+    setNodeValue(_id: string, _value: string): Promise<never>;
+}
+/** `sandbox.computerUse`: a Linux desktop driven like a person would. */
+export declare class ComputerUse {
+    #private;
+    readonly mouse: Mouse;
+    readonly keyboard: Keyboard;
+    readonly screenshot: Screenshot;
+    readonly display: Display;
+    readonly recording: RecordingService;
+    readonly accessibility: Accessibility;
+    /** Use sandbox.computerUse. */
+    constructor(live: Live);
+    /** Starts the desktop. A sandbox's first start installs it, which takes a
+     * minute or two; this waits for that. */
+    start(): Promise<ComputerUseStartResponse>;
+    stop(): Promise<ComputerUseStopResponse>;
+    /** "active" while the desktop runs, else "inactive". */
+    getStatus(): Promise<ComputerUseStatusResponse>;
+    getProcessStatus(_processName: string): Promise<never>;
+    restartProcess(_processName: string): Promise<never>;
+    getProcessLogs(_processName: string): Promise<never>;
+    getProcessErrors(_processName: string): Promise<never>;
+}
+export {};