withruntime 0.10.0 → 0.11.1

package/dist/index.d.ts

@@ -25,6 +25,7 @@ export type { TailscaleJoin, TailscaleJoined, TailscaleNode, TailscaleStatus, }
 export type { Volume, VolumeBackup, CreateVolume, VolumeAttachment } from "./products/volumes.js";
 export type { CreateJob, Job, JobCompute, JobDefinition, JobLogs, JobRun, JobRunState, JobSchedule, } from "./products/jobs.js";
 export type { CheckedDomain, DnsRecord, Domain, EgressAddress, TcpPort, Tunnel as PrivateTunnel, TunnelPeer, TunnelPeerCreated, SetUpstreamProxy, UpstreamProxy, } from "./products/network-products.js";
+export type { PrivateNetwork } from "./products/private-network.js";
 export { verifyWebhook, WebhookVerificationError, type MetricPoint, type MetricRange, type OtelExport, type RuntimeEvent, type SandboxMetrics, type Webhook, type WebhookDelivery, type WebhookEventType, } from "./products/observability.js";
 export { Snapshots, type Snapshot, type SnapshotOptions } from "./snapshots.js";
 export { Transport, VERSION, apiOrigin, type RequestOptions, type Call } from "./transport.js";
@@ -34,7 +35,8 @@ export type * from "./types.js";
  * does the same with an explicit client. */
 export declare class Sandbox extends SandboxClass {
     /** Creates a sandbox (every field optional) and waits until it is running.
-     * `keepAlive: true` (or its options) extends its lease in the background
+     * With no `timeoutSeconds` it runs while it works and pauses when idle.
+     * `keepAlive: true` (or its options) carries one with a time limit past it
      * until you stop it; see `sandbox.keepAlive()`. */
     static create(input?: CreateSandbox & {
         wait?: boolean;

package/dist/index.js

@@ -14,7 +14,8 @@ export * from "./errors.js";
  * does the same with an explicit client. */
 export class Sandbox extends SandboxClass {
     /** Creates a sandbox (every field optional) and waits until it is running.
-     * `keepAlive: true` (or its options) extends its lease in the background
+     * With no `timeoutSeconds` it runs while it works and pauses when idle.
+     * `keepAlive: true` (or its options) carries one with a time limit past it
      * until you stop it; see `sandbox.keepAlive()`. */
     static async create(input = {}, options = {}) {
         const { client, ...rest } = options;

package/dist/mcp.d.ts

@@ -1,7 +1,8 @@
 /** Bridges an MCP client that speaks stdio to Runtime's hosted MCP endpoint.
  * Newline-delimited JSON-RPC in, the same out; every message is forwarded as
  * it is, so the server's tools, schemas and `instructions` reach the client
- * unchanged, and nothing here keeps a second catalogue. Starting it costs a
+ * unchanged, and nothing here keeps a second catalogue. The one change: the
+ * initialize answer's serverInfo.version is this package's. Starting it costs a
  * process and one TLS connection (undici loads only behind a proxy).
  *
  * With no key on this machine it does not fail: it serves one tool,

package/dist/mcp.js

@@ -14,7 +14,8 @@ const connectTool = {
 /** Bridges an MCP client that speaks stdio to Runtime's hosted MCP endpoint.
  * Newline-delimited JSON-RPC in, the same out; every message is forwarded as
  * it is, so the server's tools, schemas and `instructions` reach the client
- * unchanged, and nothing here keeps a second catalogue. Starting it costs a
+ * unchanged, and nothing here keeps a second catalogue. The one change: the
+ * initialize answer's serverInfo.version is this package's. Starting it costs a
  * process and one TLS connection (undici loads only behind a proxy).
  *
  * With no key on this machine it does not fail: it serves one tool,
@@ -79,6 +80,10 @@ export async function serveMcp(env = process.env, options = {}) {
             const result = reply.result;
             if (result?.protocolVersion)
                 protocolVersion = result.protocolVersion;
+            // The client runs this package: it reports the package's version, as
+            // before connecting, not the hosted API's contract version (0.2.0).
+            if (result?.serverInfo)
+                result.serverInfo.version = VERSION;
         }
         return { status: response.status, messages, text };
     }

package/dist/modal/index.js

@@ -164,8 +164,12 @@ export class SandboxService {
             vcpu: params.cpu,
             memoryMiB: params.memoryMiB,
             region: placement,
-            timeoutSeconds: Math.ceil((params.timeoutMs ?? 300_000) / 1000),
-            idlePauseSeconds: 0,
+            // A timeout is the customer's limit, and the sandbox never pauses
+            // for idleness before it. None is no time limit (0300): it runs while
+            // it works and pauses when idle.
+            ...(params.timeoutMs === undefined
+                ? {}
+                : { timeoutSeconds: Math.ceil(params.timeoutMs / 1000), idlePauseSeconds: 0 }),
             onLeaseEnd: "stop",
             network: {
                 internet: !params.blockNetwork,

package/dist/network-cli.js

@@ -25,7 +25,7 @@ export const NETWORK_HELP = {
   ls                                     Your domains
   get <hostname>                         One domain and its DNS records
   rm <hostname>                          Stop serving it
-  Paid accounts only. The first visit gets the certificate, in a few seconds.
+  Needs a kept top-up. The first visit gets the certificate, in a few seconds.
 `,
     port: `runtime port <command>
 
@@ -34,7 +34,7 @@ export const NETWORK_HELP = {
                                          Prints address:port for your client
   ls [--sandbox <id>]                    Your open ports
   close <portId>                         Close one, its open connections too
-  Paid accounts only. TCP, carried as it is: use your service's own password and TLS.
+  Needs a kept top-up. TCP, carried as it is: use your service's own password and TLS.
 `,
     address: `runtime address <command>
 
@@ -42,7 +42,7 @@ export const NETWORK_HELP = {
                                          account sends from it, for allow-lists
   ls                                     Your addresses
   release <addressId>                    Give it back; sandboxes use the shared addresses again
-  Paid accounts only.
+  Needs credit on the account.
 `,
     tunnel: `runtime tunnel <command>
 
@@ -56,7 +56,7 @@ export const NETWORK_HELP = {
   peer rotate <peerId> [--out runtime.conf]
                                          A new key; the old one stops working within seconds
   peer rm <peerId>                       Remove it; its tunnel ends within seconds
-  --route: your own ranges behind the peer that sandboxes may reach. Paid accounts only.
+  --route: your own ranges behind the peer that sandboxes may reach. Needs a kept top-up.
 `,
     network: `runtime network <command>
 
@@ -69,7 +69,13 @@ export const NETWORK_HELP = {
   upstream-proxy get                     The proxy in use
   upstream-proxy remove                  Connections leave directly again
   A proxy that refuses or cannot be reached fails the connection; nothing goes
-  around it. Paid accounts only.
+  around it. Needs a kept top-up.
+
+  private on                             Your sandboxes reach each other by name, over TCP:
+                                         <name>.sandbox.internal:<port> or <id>.sandbox.internal:<port>
+  private off                            They stop; open connections between them are cut
+  private status                         On or off
+  Only your own sandboxes answer. Needs a kept top-up; free.
 `,
 };
 function usage(product, message) {
@@ -400,6 +406,28 @@ export async function networkProductCommand(product, argv, args, out, client) {
             }
         }
     }
+    if (product === "network" && verb === "private") {
+        const describe = (state) => state.enabled
+            ? "On: your sandboxes reach each other at <name>.sandbox.internal:<port> over TCP."
+            : state.allowed
+                ? "Off. Turn it on: runtime network private on"
+                : "Off. Reaching your sandboxes by name needs a kept top-up.";
+        switch (rest[0]) {
+            case "on":
+            case "off": {
+                const state = await runtime.network.private.set({ enabled: rest[0] === "on" });
+                print(state.enabled ? describe(state) : "Off. Open connections between your sandboxes are cut.", state);
+                return 0;
+            }
+            case "status":
+            case undefined: {
+                const state = await runtime.network.private.get();
+                print(describe(state), state);
+                return 0;
+            }
+        }
+        throw usage(product, "private takes on, off or status.");
+    }
     if (product === "network") {
         if (verb !== "upstream-proxy")
             throw usage(product, `Unknown network command ${verb}.`);

package/dist/products/browser.d.ts

@@ -0,0 +1,61 @@
+import type { Sandbox } from "../sandbox.js";
+import type { RequestOptions, Transport } from "../transport.js";
+export type SandboxBrowser = {
+    running: false;
+} | {
+    running: true;
+    headless: boolean;
+    /** Chromium's version, e.g. "Chrome/154.0.8037.92". */
+    version: string;
+    /** The browser's DevTools WebSocket with its private token: give it as it
+     * is to Playwright's `chromium.connectOverCDP`, `puppeteer.connect({
+     * browserWSEndpoint })`, browser-use or Stagehand. */
+    cdpUrl: string;
+    /** The DevTools HTTP endpoint; send `headers` with it. */
+    httpUrl: string;
+    headers: Record<string, string>;
+    /** When the token in cdpUrl ends; `get()` returns a fresh one. */
+    expiresAt: string | null;
+    /** headless: false only: the desktop's live view. */
+    streamUrl?: string;
+};
+export type BrowserStartOptions = {
+    /** true (the default): no window. false: on the sandbox's desktop, with a live view. */
+    headless?: boolean;
+    width?: number;
+    height?: number;
+};
+/** `sbx.browser`: Chromium in the sandbox, for agents that speak CDP.
+ *
+ *   const { cdpUrl } = await sbx.browser.start();
+ *   const browser = await chromium.connectOverCDP(cdpUrl);
+ *
+ * Inside the sandbox the same browser is at http://127.0.0.1:9222. */
+export declare function sandboxBrowser(t: Transport, sandbox: Sandbox): {
+    /** Starts Chromium and returns its CDP address. The first start in a
+     * sandbox installs Chromium, about a minute; this waits for it (up to 10
+     * minutes, or the call's timeoutMs). Starting a running browser returns it
+     * as it is. */
+    start(input?: BrowserStartOptions, options?: RequestOptions): Promise<{
+        running: true;
+        headless: boolean;
+        /** Chromium's version, e.g. "Chrome/154.0.8037.92". */
+        version: string;
+        /** The browser's DevTools WebSocket with its private token: give it as it
+         * is to Playwright's `chromium.connectOverCDP`, `puppeteer.connect({
+         * browserWSEndpoint })`, browser-use or Stagehand. */
+        cdpUrl: string;
+        /** The DevTools HTTP endpoint; send `headers` with it. */
+        httpUrl: string;
+        headers: Record<string, string>;
+        /** When the token in cdpUrl ends; `get()` returns a fresh one. */
+        expiresAt: string | null;
+        /** headless: false only: the desktop's live view. */
+        streamUrl?: string;
+    }>;
+    /** Whether it runs, and a fresh cdpUrl when it does. */
+    get: (options?: RequestOptions) => Promise<SandboxBrowser>;
+    stop: (options?: RequestOptions) => Promise<{
+        stopped: boolean;
+    }>;
+};

package/dist/products/browser.js

@@ -0,0 +1,27 @@
+import { whileInstalling } from "../wait.js";
+/** `sbx.browser`: Chromium in the sandbox, for agents that speak CDP.
+ *
+ *   const { cdpUrl } = await sbx.browser.start();
+ *   const browser = await chromium.connectOverCDP(cdpUrl);
+ *
+ * Inside the sandbox the same browser is at http://127.0.0.1:9222. */
+export function sandboxBrowser(t, sandbox) {
+    const base = () => `/v1/sandboxes/${encodeURIComponent(sandbox.id)}/browser`;
+    return {
+        /** Starts Chromium and returns its CDP address. The first start in a
+         * sandbox installs Chromium, about a minute; this waits for it (up to 10
+         * minutes, or the call's timeoutMs). Starting a running browser returns it
+         * as it is. */
+        async start(input = {}, options) {
+            return whileInstalling(["browser_installing", "desktop_installing"], options, (request) => t.json({
+                method: "POST",
+                path: `${base()}:start`,
+                body: input,
+                ...request,
+            }));
+        },
+        /** Whether it runs, and a fresh cdpUrl when it does. */
+        get: (options) => t.json({ method: "GET", path: base(), ...options }),
+        stop: (options) => t.json({ method: "POST", path: `${base()}:stop`, ...options }),
+    };
+}

package/dist/products/desktop.d.ts

@@ -53,7 +53,8 @@ export type RecordOptions = {
  * Coordinates are pixels from the top left of the screen. */
 export declare function sandboxDesktop(t: Transport, sandbox: Sandbox): {
     /** Starts the desktop. The first start in a sandbox installs it, which
-     * takes a minute or two; this waits for that (up to 10 minutes). */
+     * takes a minute or two; this waits for that (up to 10 minutes, or the
+     * call's timeoutMs). */
     start(size?: {
         width?: number;
         height?: number;
@@ -115,8 +116,8 @@ export declare function sandboxDesktop(t: Transport, sandbox: Sandbox): {
     focus: (windowId: string, options?: RequestOptions) => Promise<{
         ok: true;
     }>;
-    /** Opens `url` in Firefox on the desktop. Right after a sandbox's first
-     * start, Firefox may still be installing; this waits for it. */
+    /** Opens `url` in Chromium on the desktop. Right after a sandbox's first
+     * start, Chromium may still be installing; this waits for it. */
     open(url: string, options?: RequestOptions): Promise<{
         ok: true;
     }>;

package/dist/products/desktop.js

@@ -1,3 +1,4 @@
+import { whileInstalling } from "../wait.js";
 /** `sbx.desktop`: a Linux desktop in the sandbox, driven like a person would.
  *
  *   const { streamUrl } = await sbx.desktop.start();
@@ -12,25 +13,10 @@ export function sandboxDesktop(t, sandbox) {
     const act = (body, options) => t.json({ method: "POST", path: `${base()}:act`, body, ...options });
     return {
         /** Starts the desktop. The first start in a sandbox installs it, which
-         * takes a minute or two; this waits for that (up to 10 minutes). */
+         * takes a minute or two; this waits for that (up to 10 minutes, or the
+         * call's timeoutMs). */
         async start(size = {}, options) {
-            const deadline = Date.now() + 600_000;
-            for (;;) {
-                try {
-                    return await t.json({
-                        method: "POST",
-                        path: `${base()}:start`,
-                        body: size,
-                        ...options,
-                    });
-                }
-                catch (error) {
-                    const code = error.code;
-                    if (code !== "desktop_installing" || Date.now() > deadline)
-                        throw error;
-                    await new Promise((resolve) => setTimeout(resolve, error.retryAfterMs ?? 10_000));
-                }
-            }
+            return whileInstalling(["desktop_installing"], options, (request) => t.json({ method: "POST", path: `${base()}:start`, body: size, ...request }));
         },
         stop: (options) => t.json({ method: "POST", path: `${base()}:stop`, ...options }),
         /** PNG bytes, or JPEG with `format: "jpeg"`. */
@@ -50,21 +36,10 @@ export function sandboxDesktop(t, sandbox) {
         cursor: (options) => act({ action: "cursor" }, options),
         windows: async (options) => (await act({ action: "windows" }, options)).windows,
         focus: (windowId, options) => act({ action: "focus", windowId }, options),
-        /** Opens `url` in Firefox on the desktop. Right after a sandbox's first
-         * start, Firefox may still be installing; this waits for it. */
+        /** Opens `url` in Chromium on the desktop. Right after a sandbox's first
+         * start, Chromium may still be installing; this waits for it. */
         async open(url, options) {
-            const deadline = Date.now() + 600_000;
-            for (;;) {
-                try {
-                    return await act({ action: "open", url }, options);
-                }
-                catch (error) {
-                    const code = error.code;
-                    if (code !== "desktop_installing" || Date.now() > deadline)
-                        throw error;
-                    await new Promise((resolve) => setTimeout(resolve, error.retryAfterMs ?? 10_000));
-                }
-            }
+            return whileInstalling(["desktop_installing"], options, (request) => act({ action: "open", url }, request));
         },
         /** Starts a program on the desktop, detached. */
         launch: (argv, options) => act({ action: "launch", argv }, options),

package/dist/products/images.d.ts

@@ -212,7 +212,9 @@ export declare function images(t: Transport): {
     /** Point `tag` of the image's name at this version. */
     tag(ref: string, tag: string, options?: RequestOptions): Promise<Image>;
     untag(ref: string, tag: string, options?: RequestOptions): Promise<Image>;
-    /** Delete one version (by id, name:tag or name@version) and its tags. */
+    /** Delete one version (by id, name:tag or name@version) and its tags. A
+     * bare name deletes its latest tag's version, or its only version when
+     * it has one and no latest tag; with several, the error names its tags. */
     delete(ref: string, options?: RequestOptions): Promise<Image>;
     /** Credentials for private registries. The secret is sealed on arrival
      * and never returned. */

package/dist/products/images.js

@@ -1,3 +1,4 @@
+import { RuntimeError } from "../errors.js";
 import { Page } from "../page.js";
 const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
 const PARALLEL_UPLOADS = 4;
@@ -189,11 +190,22 @@ export function images(t) {
                 ...options,
             });
         },
-        /** Delete one version (by id, name:tag or name@version) and its tags. */
+        /** Delete one version (by id, name:tag or name@version) and its tags. A
+         * bare name deletes its latest tag's version, or its only version when
+         * it has one and no latest tag; with several, the error names its tags. */
         async delete(ref, options) {
+            const id = await idOf(ref, options).catch(async (error) => {
+                if (!(error instanceof RuntimeError && error.code === "image_not_found") ||
+                    /[:@]/.test(ref))
+                    throw error;
+                const live = (await list({ name: ref, limit: 100 }, options)).data.filter((image) => image.state !== "deleted" && image.state !== "deleting");
+                if (live.length !== 1)
+                    throw error;
+                return live[0].id;
+            });
             return t.json({
                 method: "POST",
-                path: `/v1/images/${enc(await idOf(ref, options))}:delete`,
+                path: `/v1/images/${enc(id)}:delete`,
                 body: {},
                 ...options,
             });

package/dist/products/index.d.ts

@@ -2,6 +2,7 @@ import type { Transport } from "../transport.js";
 import type { Sandbox } from "../sandbox.js";
 import { images } from "./images.js";
 import { sandboxDesktop } from "./desktop.js";
+import { sandboxBrowser } from "./browser.js";
 import { sandboxInterpreter } from "./interpreter.js";
 import { sandboxNetwork } from "./network.js";
 import { addresses, domains, network, ports, tunnel } from "./network-products.js";
@@ -55,6 +56,7 @@ export declare const sandboxExtensions: {
     previews: typeof sandboxPreviews;
     network: typeof sandboxNetwork;
     desktop: typeof sandboxDesktop;
+    browser: typeof sandboxBrowser;
     mounts: typeof sandboxMounts;
     tailscale: typeof sandboxTailscale;
     metrics: typeof sandboxMetrics;

package/dist/products/index.js

@@ -1,5 +1,6 @@
 import { images } from "./images.js";
 import { sandboxDesktop } from "./desktop.js";
+import { sandboxBrowser } from "./browser.js";
 import { sandboxInterpreter } from "./interpreter.js";
 import { sandboxNetwork } from "./network.js";
 import { addresses, domains, network, ports, tunnel } from "./network-products.js";
@@ -68,6 +69,7 @@ export const sandboxExtensions = {
     previews: sandboxPreviews,
     network: sandboxNetwork,
     desktop: sandboxDesktop,
+    browser: sandboxBrowser,
     mounts: sandboxMounts,
     tailscale: sandboxTailscale,
     metrics: sandboxMetrics,

package/dist/products/jobs.d.ts

@@ -1,7 +1,7 @@
 import { Page } from "../page.js";
 import type { RequestOptions, Transport } from "../transport.js";
-/** A run's sandbox. Every field has a default; a run is a paid sandbox of this
- * size, billed at the sandbox rates. */
+/** A run's sandbox. Every field has a default; a run is a sandbox of this
+ * size, on the trial's hours first and then on credit at the sandbox rates. */
 export type JobCompute = {
     region: string;
     vcpu: number;
@@ -147,11 +147,12 @@ export declare const JOB_DEFAULTS: {
     startSeconds: number;
 };
 /** A run is one sandbox: at most 16 vCPU and 64 GiB, a disk no smaller than
- * the system image, and paid for at most an hour. */
+ * the system image and no larger than 400 GiB, and paid for at most an hour. */
 export declare const JOB_LIMITS: {
     maxVcpu: number;
     maxMemoryMiB: number;
     minDiskMiB: number;
+    maxDiskMiB: number;
     maxDurationSeconds: number;
     maxAttempts: number;
     maxSecrets: number;
@@ -167,8 +168,9 @@ export declare function jobBody(input: CreateJob): Record<string, unknown>;
  * request id, and says no retry will change it. */
 export declare function switchedOff(product: string): (error: unknown) => never;
 /** Scheduled jobs: a command run in a fresh sandbox, once or on a cron
- * schedule. Each run is a paid sandbox, charged at the sandbox rates through
- * the same holds and spending limits; the trial's hours do not fund jobs.
+ * schedule. Each run is a sandbox, paid for as one: from the free trial's
+ * hours first while the run fits the trial's size and count, then from credit
+ * at the sandbox rates, through the same holds and spending limits.
  *
  *   const job = await runtime.jobs.create({
  *     name: "nightly-report",

package/dist/products/jobs.js

@@ -15,11 +15,12 @@ export const JOB_DEFAULTS = {
     startSeconds: JOB_START_SECONDS,
 };
 /** A run is one sandbox: at most 16 vCPU and 64 GiB, a disk no smaller than
- * the system image, and paid for at most an hour. */
+ * the system image and no larger than 400 GiB, and paid for at most an hour. */
 export const JOB_LIMITS = {
     maxVcpu: 16,
     maxMemoryMiB: 65_536,
     minDiskMiB: 3072,
+    maxDiskMiB: 409_600,
     maxDurationSeconds: 3600,
     maxAttempts: 5,
     maxSecrets: 16,
@@ -88,6 +89,8 @@ export function jobBody(input) {
         throw invalid(`A run's sandbox is at most ${JOB_LIMITS.maxVcpu} vCPU and ${JOB_LIMITS.maxMemoryMiB / 1024} GiB of memory; asked for ${compute.vcpu} vCPU and ${compute.memoryMiB} MiB.`, compute.vcpu > JOB_LIMITS.maxVcpu ? "compute.vcpu" : "compute.memoryMiB");
     if (compute.diskMiB < JOB_LIMITS.minDiskMiB)
         throw invalid(`A run's disk is at least ${JOB_LIMITS.minDiskMiB} MiB, the size of the system image; asked for ${compute.diskMiB}.`, "compute.diskMiB");
+    if (compute.diskMiB > JOB_LIMITS.maxDiskMiB)
+        throw invalid(`A run's disk is at most ${JOB_LIMITS.maxDiskMiB} MiB (${JOB_LIMITS.maxDiskMiB / 1024} GiB); asked for ${compute.diskMiB}.`, "compute.diskMiB");
     if (timeoutSeconds > compute.durationSeconds ||
         compute.durationSeconds > JOB_LIMITS.maxDurationSeconds)
         throw invalid(`timeoutSeconds (${timeoutSeconds}) must fit in the time a run is paid for (compute.durationSeconds ${compute.durationSeconds}), which is at most ${JOB_LIMITS.maxDurationSeconds} seconds.`, "timeoutSeconds");
@@ -125,8 +128,9 @@ export function switchedOff(product) {
     };
 }
 /** Scheduled jobs: a command run in a fresh sandbox, once or on a cron
- * schedule. Each run is a paid sandbox, charged at the sandbox rates through
- * the same holds and spending limits; the trial's hours do not fund jobs.
+ * schedule. Each run is a sandbox, paid for as one: from the free trial's
+ * hours first while the run fits the trial's size and count, then from credit
+ * at the sandbox rates, through the same holds and spending limits.
  *
  *   const job = await runtime.jobs.create({
  *     name: "nightly-report",

package/dist/products/mcp.d.ts

@@ -68,10 +68,14 @@ export declare function sandboxMcp(t: Transport, sandbox: Sandbox): {
     }, options?: RequestOptions) => Promise<McpGateway>;
     /** Their state, and fresh URLs. */
     get: (options?: RequestOptions) => Promise<McpGateway>;
-    /** Wait until every server is ready (or one failed). */
+    /** Wait until every server is ready (or one failed). Past `timeoutMs`
+     * (default ten minutes), the last state read; a status request still
+     * unanswered then is cut off at the deadline, and throws its timeout when
+     * no state was read at all. */
     ready(input?: {
         timeoutMs?: number;
         intervalMs?: number;
+        signal?: AbortSignal;
     }): Promise<McpGateway>;
     stop: (options?: RequestOptions) => Promise<{
         stopped: boolean;

package/dist/products/mcp.js

@@ -1,3 +1,4 @@
+import { pause } from "../wait.js";
 /** `runtime.mcp`: the catalog of MCP servers a sandbox can run. */
 export function mcp(t) {
     return {
@@ -20,16 +21,36 @@ export function sandboxMcp(t, sandbox) {
         start: (servers, input = {}, options) => t.json({ method: "POST", path: path(), body: { servers, ...input }, ...options }),
         /** Their state, and fresh URLs. */
         get: (options) => t.json({ method: "GET", path: path(), ...options }),
-        /** Wait until every server is ready (or one failed). */
+        /** Wait until every server is ready (or one failed). Past `timeoutMs`
+         * (default ten minutes), the last state read; a status request still
+         * unanswered then is cut off at the deadline, and throws its timeout when
+         * no state was read at all. */
         async ready(input = {}) {
-            const deadline = Date.now() + (input.timeoutMs ?? 600_000);
+            const deadline = performance.now() + (input.timeoutMs ?? 600_000);
+            let last;
             for (;;) {
-                const state = await t.json({ method: "GET", path: path() });
-                if (!state.running || state.servers.every((server) => server.status !== "installing"))
-                    return state;
-                if (Date.now() > deadline)
-                    return state;
-                await new Promise((resolve) => setTimeout(resolve, input.intervalMs ?? 2_000));
+                const left = Math.ceil(deadline - performance.now());
+                if (left <= 0 && last)
+                    return last;
+                try {
+                    last = await t.json({
+                        method: "GET",
+                        path: path(),
+                        timeoutMs: Math.max(1, left),
+                        ...(input.signal ? { signal: input.signal } : {}),
+                    });
+                }
+                catch (error) {
+                    if (last && !input.signal?.aborted && error.code === "timeout")
+                        return last;
+                    throw error;
+                }
+                if (!last.running || last.servers.every((server) => server.status !== "installing"))
+                    return last;
+                const rest = deadline - performance.now();
+                if (rest <= 0)
+                    return last;
+                await pause(Math.min(input.intervalMs ?? 2_000, rest), input.signal);
             }
         },
         stop: (options) => t.json({ method: "DELETE", path: path(), ...options }),

package/dist/products/network-products.d.ts

@@ -193,8 +193,15 @@ export type SetUpstreamProxy = {
  * `upstreamProxy`: after Runtime's own rules allow a connection, the host
  * reaches it with CONNECT through your proxy, so your proxy's controls and
  * logs apply. A proxy that refuses or cannot be reached fails the connection
- * (upstream-proxy-failed); nothing goes around it. Paid accounts only. */
+ * (upstream-proxy-failed); nothing goes around it. Needs a kept top-up. */
 export declare function network(t: Transport): {
+    /** Your sandboxes reaching each other by name (`private-network.ts`). */
+    private: {
+        get: (options?: RequestOptions) => Promise<import("./private-network.js").PrivateNetwork>;
+        set: (input: {
+            enabled: boolean;
+        }, options?: RequestOptions) => Promise<import("./private-network.js").PrivateNetwork>;
+    };
     upstreamProxy: {
         /** Send outbound connections through your proxy, replacing any set before. */
         set: (input: SetUpstreamProxy, options?: RequestOptions) => Promise<UpstreamProxy & {

package/dist/products/network-products.js

@@ -1,3 +1,4 @@
+import { privateNetwork } from "./private-network.js";
 const enc = encodeURIComponent;
 /** `runtime.domains`: serve a sandbox's port at your own hostname, with HTTPS. */
 export function domains(t) {
@@ -87,10 +88,12 @@ export function tunnel(t) {
  * `upstreamProxy`: after Runtime's own rules allow a connection, the host
  * reaches it with CONNECT through your proxy, so your proxy's controls and
  * logs apply. A proxy that refuses or cannot be reached fails the connection
- * (upstream-proxy-failed); nothing goes around it. Paid accounts only. */
+ * (upstream-proxy-failed); nothing goes around it. Needs a kept top-up. */
 export function network(t) {
     const path = "/v1/network/upstream-proxy";
     return {
+        /** Your sandboxes reaching each other by name (`private-network.ts`). */
+        private: privateNetwork(t),
         upstreamProxy: {
             /** Send outbound connections through your proxy, replacing any set before. */
             set: (input, options) => t.json({

package/dist/products/observability.d.ts

@@ -35,7 +35,7 @@ export type SandboxMetrics = {
     latest: MetricPoint | null;
     points: MetricPoint[];
 };
-export type WebhookEventType = "sandbox.created" | "sandbox.running" | "sandbox.paused" | "sandbox.woken" | "sandbox.stopped" | "sandbox.start_failed" | "sandbox.wake_failed" | "snapshot.ready" | "snapshot.failed" | "snapshot.deleted" | "volume.ready" | "volume.failed" | "volume.deleted";
+export type WebhookEventType = "sandbox.created" | "sandbox.running" | "sandbox.paused" | "sandbox.woken" | "sandbox.stopped" | "sandbox.start_failed" | "sandbox.wake_failed" | "sandbox.host_unreachable" | "sandbox.host_reachable" | "sandbox.recovered" | "sandbox.recovery_failed" | "snapshot.ready" | "snapshot.failed" | "snapshot.deleted" | "volume.ready" | "volume.failed" | "volume.deleted";
 /** An event as /v1/events lists it and a webhook delivers it. */
 export type RuntimeEvent = {
     id: string;

package/dist/products/private-network.d.ts

@@ -0,0 +1,22 @@
+import type { RequestOptions, Transport } from "../transport.js";
+export type PrivateNetwork = {
+    /** Whether your sandboxes reach each other by name now. */
+    enabled: boolean;
+    /** `sandbox.internal`. */
+    suffix: string;
+    /** Whether this account may turn it on: it must have a kept top-up. */
+    allowed: boolean;
+    /** Why not, when `allowed` is false: `not_paid`, `revoked` or `suspended`. */
+    why: string | null;
+    enabledAt: string | null;
+    disabledAt: string | null;
+};
+export declare function privateNetwork(t: Transport): {
+    /** On or off, and whether this account may turn it on. */
+    get: (options?: RequestOptions) => Promise<PrivateNetwork>;
+    /** `enabled: true` lets your sandboxes reach each other by name; `false`
+     * stops it and cuts open connections between them within seconds. */
+    set: (input: {
+        enabled: boolean;
+    }, options?: RequestOptions) => Promise<PrivateNetwork>;
+};

package/dist/products/private-network.js

@@ -0,0 +1,10 @@
+export function privateNetwork(t) {
+    const path = "/v1/network/private";
+    return {
+        /** On or off, and whether this account may turn it on. */
+        get: (options) => t.json({ method: "GET", path, ...options }),
+        /** `enabled: true` lets your sandboxes reach each other by name; `false`
+         * stops it and cuts open connections between them within seconds. */
+        set: (input, options) => t.json({ method: "PUT", path, body: input, ...options }),
+    };
+}