withruntime 0.11.0 → 0.11.1

package/dist/compat/lease.js

@@ -1,9 +1,11 @@
 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. */
+/* A rival's sandbox may be asked to live longer than one Runtime time limit
+   (an hour at most, ARCHITECTURE.md section 10): Vercel's `timeout` over an
+   hour, Daytona's `autoStopInterval` over an hour. The drop-ins keep the
+   limit reaching toward the time asked for while their sandbox object lives,
+   one extension at a time, never past that time. A sandbox created with no
+   time limit renews itself on the server (0300; `endsAt` null) and is left
+   alone. */
 /** 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
@@ -39,7 +41,10 @@ export class LeaseKeeper {
     #schedule() {
         if (this.#ended || this.#timer)
             return;
-        const expiresAt = Date.parse(this.#sandbox().info.expiresAt);
+        const info = this.#sandbox().info;
+        if (info.endsAt === null)
+            return;
+        const expiresAt = Date.parse(info.endsAt ?? info.expiresAt);
         if (!Number.isFinite(expiresAt) || this.#until() <= expiresAt)
             return;
         this.#timer = setTimeout(() => {
@@ -61,9 +66,10 @@ export class LeaseKeeper {
     }
     async #extend(now) {
         const sandbox = this.#sandbox();
-        if (sandbox.state !== "running")
+        // No time limit: the server renews it, and an extension would change nothing.
+        if (sandbox.state !== "running" || sandbox.info.endsAt === null)
             return;
-        const seconds = extensionSeconds(Date.parse(sandbox.info.expiresAt), this.#until(), Date.now(), now ? Infinity : this.#marginMs());
+        const seconds = extensionSeconds(Date.parse(sandbox.info.endsAt ?? sandbox.info.expiresAt), this.#until(), Date.now(), now ? Infinity : this.#marginMs());
         if (seconds < 1)
             return;
         try {

package/dist/credentials.d.ts

@@ -10,6 +10,15 @@ export type SavedConnection = {
     /** The account's name when it was saved, for `runtime account`. */
     orgName?: string;
 };
+/** Saved accounts could not be updated because another command holds their
+ * lock: still `busy` after the whole wait, or `interrupted`, left by a command
+ * that died holding it. The message names the lock file to remove. */
+export declare class CredentialsLockedError extends Error {
+    readonly lockFile: string;
+    readonly reason: "busy" | "interrupted";
+    readonly name = "CredentialsLockedError";
+    constructor(message: string, lockFile: string, reason: "busy" | "interrupted");
+}
 export declare function connectionOrigins(env: NodeJS.ProcessEnv): {
     api: string;
     auth: string;

package/dist/credentials.js

@@ -4,6 +4,23 @@ import { lstat, mkdir, open, rename, unlink } from "node:fs/promises";
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import { apiOrigin, missingKey } from "./transport.js";
+/** Saved accounts could not be updated because another command holds their
+ * lock: still `busy` after the whole wait, or `interrupted`, left by a command
+ * that died holding it. The message names the lock file to remove. */
+export class CredentialsLockedError extends Error {
+    lockFile;
+    reason;
+    name = "CredentialsLockedError";
+    constructor(message, lockFile, reason) {
+        super(message);
+        this.lockFile = lockFile;
+        this.reason = reason;
+    }
+}
+/** How long a save waits for another command's update to finish. An update
+ * is one read, modify and write of small files, so only a heavily loaded
+ * machine comes near it. */
+const LOCK_WAIT_MS = 30_000;
 /** How many other accounts' connections one machine keeps beside the one in use. */
 const SAVED_ACCOUNTS = 20;
 export function connectionOrigins(env) {
@@ -107,7 +124,7 @@ export function connectionStore(env, directory = defaultDirectory(env)) {
      * Never steal a lock: stale cleanup can otherwise delete a new live lock. */
     async function updateAccounts(update) {
         await privateDirectory(true);
-        const until = performance.now() + 10_000;
+        const until = performance.now() + LOCK_WAIT_MS;
         let handle;
         for (;;) {
             try {
@@ -127,16 +144,21 @@ export function connectionStore(env, directory = defaultDirectory(env)) {
                 // The holder may not have finished writing its process id yet.
             }
             if (typeof pid === "number" && Number.isSafeInteger(pid) && pid > 0) {
+                let gone = false;
                 try {
                     process.kill(pid, 0);
                 }
                 catch (error) {
-                    if (error.code === "ESRCH")
-                        throw new Error(`A previous Runtime credential update was interrupted. Remove ${lockFile} and retry.`);
+                    gone = error.code === "ESRCH";
                 }
+                // A holder that finished between our read and our check has exited
+                // too, and its lock is gone or another's: wait for the lock again.
+                // Only a lock still naming the dead process was left by one that died.
+                if (gone && (await readPrivate(lockFile, 1024, "credential update lock")) === text)
+                    throw new CredentialsLockedError(`A previous Runtime credential update was interrupted. Remove ${lockFile} and retry.`, lockFile, "interrupted");
             }
             if (performance.now() >= until)
-                throw new Error(`Another Runtime command is updating saved accounts. Retry when it finishes. If no command is running, remove ${lockFile} and retry.`);
+                throw new CredentialsLockedError(`Another Runtime command is updating saved accounts. Retry when it finishes. If no command is running, remove ${lockFile} and retry.`, lockFile, "busy");
             await new Promise((resolve) => setTimeout(resolve, 25));
         }
         try {

package/dist/daytona/daytona.js

@@ -1,6 +1,7 @@
 import { clientFor, } from "./client.js";
 import { DaytonaError, DaytonaNotFoundError, guard, NotSupportedError } from "./errors.js";
-import { idleSeconds, networkRules, notFound, retentionDays, Sandbox, windowSeconds, } from "./sandbox.js";
+import { LEASE_MAX_SECONDS } from "../compat/lease.js";
+import { idlePauseOf, idleSeconds, networkRules, notFound, retentionDays, Sandbox, windowSeconds, } from "./sandbox.js";
 /* Daytona's client over Runtime's. `new Daytona()` then `daytona.create()`
    makes a Runtime sandbox with Daytona's defaults. */
 /** Daytona's default machine: 1 vCPU, 1 GiB memory, 3 GiB disk (checked
@@ -211,9 +212,15 @@ export class Daytona {
                     memoryMiB: Math.round(resources.memory * 1024),
                     diskMiB: Math.round(resources.disk * 1024),
                 }),
-            timeoutSeconds: lifecycle.deadline
-                ? Math.max(60, Math.min(lifecycle.windowSeconds, Math.floor((lifecycle.deadline - Date.now()) / 1000)))
-                : lifecycle.windowSeconds,
+            // A time to live is a time limit, kept by the lease. Without one there
+            // is none: it runs while it works and autoStopInterval is its idle
+            // pause, counted by the sandbox itself, so a long command is never
+            // frozen for want of calls from this client (0300).
+            ...(lifecycle.deadline
+                ? {
+                    timeoutSeconds: Math.max(60, Math.min(lifecycle.windowSeconds, Math.floor((lifecycle.deadline - Date.now()) / 1000))),
+                }
+                : { idlePauseSeconds: idlePauseOf(lifecycle.autoStopInterval) }),
             onLeaseEnd: lifecycle.ephemeral || lifecycle.deadline ? "stop" : "pause",
             ...(params.name ? { name: params.name } : {}),
             ...(labels ? { labels } : {}),
@@ -303,14 +310,24 @@ export class Daytona {
             language: runtime.info.labels[LANGUAGE_LABEL] ?? "python",
             public: false,
             ...(user ? { user } : {}),
-            lifecycle: {
-                windowSeconds: runtime.info.timeoutSeconds,
-                idleSeconds: runtime.info.timeoutSeconds,
-                ephemeral: onLeaseEnd === "stop",
-                autoStopInterval: Math.round(runtime.info.timeoutSeconds / 60),
-                autoArchiveInterval: 0,
-                autoDeleteInterval: -1,
-            },
+            lifecycle: runtime.info.timeoutSeconds
+                ? {
+                    windowSeconds: runtime.info.timeoutSeconds,
+                    idleSeconds: runtime.info.timeoutSeconds,
+                    ephemeral: onLeaseEnd === "stop",
+                    autoStopInterval: Math.round(runtime.info.timeoutSeconds / 60),
+                    autoArchiveInterval: 0,
+                    autoDeleteInterval: -1,
+                }
+                : {
+                    // No time limit: its idle pause is its autoStopInterval.
+                    windowSeconds: LEASE_MAX_SECONDS,
+                    idleSeconds: Infinity,
+                    ephemeral: onLeaseEnd === "stop",
+                    autoStopInterval: Math.round((runtime.info.idlePauseSeconds ?? 0) / 60),
+                    autoArchiveInterval: 0,
+                    autoDeleteInterval: -1,
+                },
         });
     }
     /** Live and stopped (paused) sandboxes, oldest first. Await it for the old

package/dist/daytona/sandbox.d.ts

@@ -134,8 +134,9 @@ export declare class Sandbox {
     refreshData(): Promise<void>;
     /** Counts as activity: moves the lease a full autoStop window on. */
     refreshActivity(): Promise<void>;
-    /** The sandbox pauses after `interval` minutes without a call from this
-     * client; 0 never. Past an hour, while this object lives. */
+    /** The sandbox pauses after `interval` minutes with nothing happening in
+     * it; 0 never. With a time to live, after that long without a call from
+     * this client, and past an hour only while this object lives. */
     setAutostopInterval(interval: number): Promise<void>;
     setAutoPauseInterval(interval: number): Promise<void>;
     /** Runtime has no archive tier; recorded only. */
@@ -192,8 +193,12 @@ export declare class Sandbox {
 }
 /** Daytona's autoStopInterval (minutes; 0 is off) as the lease window. */
 export declare function windowSeconds(autoStopMinutes: number): number;
+/** Daytona's autoStopInterval (minutes; 0 is never) as the idle pause of a
+ * sandbox with no time limit: seconds with nothing happening in it, counted
+ * by the sandbox itself (`idlePauseSeconds`, 0 never, at most a day). */
+export declare function idlePauseOf(autoStopMinutes: number): number;
 /** Daytona's autoStopInterval (minutes; 0 is never) as seconds without a
- * call before the sandbox pauses. */
+ * call before a sandbox with a time to live pauses. */
 export declare function idleSeconds(autoStopMinutes: number): number;
 /** Minutes as Runtime's retention: whole days, 1 to 365. */
 export declare function retentionDays(minutes: number): number;

package/dist/daytona/sandbox.js

@@ -238,7 +238,11 @@ export class Sandbox {
         if (state === "stopped" || state === "stopping")
             throw new DaytonaError(`Sandbox ${this.id} was deleted and cannot start.`, 410);
         if (state === "paused" || state === "pausing")
-            await guard("sandbox", () => this.#rt.wake({ timeoutSeconds: this.#options.lifecycle.windowSeconds }));
+            await guard("sandbox", () => 
+            // One with no time limit (timeoutSeconds 0) wakes with none.
+            this.#rt.wake(this.#rt.info.timeoutSeconds
+                ? { timeoutSeconds: this.#options.lifecycle.windowSeconds }
+                : {}));
         this.#pausedByPause = false;
     }
     /** Stops the sandbox: Runtime pauses it, keeping its files and memory, so
@@ -291,11 +295,16 @@ export class Sandbox {
     async refreshActivity() {
         await guard("sandbox", () => this.#live(true));
     }
-    /** The sandbox pauses after `interval` minutes without a call from this
-     * client; 0 never. Past an hour, while this object lives. */
+    /** The sandbox pauses after `interval` minutes with nothing happening in
+     * it; 0 never. With a time to live, after that long without a call from
+     * this client, and past an hour only while this object lives. */
     async setAutostopInterval(interval) {
         const lifecycle = this.#options.lifecycle;
         lifecycle.autoStopInterval = interval;
+        if (!this.#rt.info.timeoutSeconds) {
+            await guard("sandbox", () => this.#rt.update({ idlePauseSeconds: idlePauseOf(interval) }));
+            return;
+        }
         lifecycle.windowSeconds = windowSeconds(interval);
         lifecycle.idleSeconds = idleSeconds(interval);
         await guard("sandbox", () => this.#live());
@@ -321,6 +330,8 @@ export class Sandbox {
             delete this.#options.lifecycle.deadline;
             return;
         }
+        if (!this.#rt.info.timeoutSeconds)
+            throw new NotSupportedError("A time to live on a sandbox made without one", "It has no time limit and pauses when idle; pass ttlMinutes to create(), or call stop() or delete() when the work is done.");
         const deadline = Date.parse(this.#rt.info.createdAt) + ttlMinutes * 60_000;
         if (Date.parse(this.#rt.info.expiresAt) > deadline)
             throw new NotSupportedError("A time to live shorter than the current lease", "Runtime leases only move later; call stop() or delete() when the work is done.");
@@ -444,8 +455,16 @@ export function windowSeconds(autoStopMinutes) {
         return 3600;
     return Math.min(3600, Math.max(60, Math.round(autoStopMinutes * 60)));
 }
+/** Daytona's autoStopInterval (minutes; 0 is never) as the idle pause of a
+ * sandbox with no time limit: seconds with nothing happening in it, counted
+ * by the sandbox itself (`idlePauseSeconds`, 0 never, at most a day). */
+export function idlePauseOf(autoStopMinutes) {
+    if (autoStopMinutes <= 0)
+        return 0;
+    return Math.min(86_400, Math.max(60, Math.round(autoStopMinutes * 60)));
+}
 /** Daytona's autoStopInterval (minutes; 0 is never) as seconds without a
- * call before the sandbox pauses. */
+ * call before a sandbox with a time to live pauses. */
 export function idleSeconds(autoStopMinutes) {
     if (autoStopMinutes <= 0)
         return Infinity;

package/dist/e2b/sandbox.d.ts

@@ -9,7 +9,9 @@ export declare const DEFAULT_SHAPE: {
     readonly vcpu: 2;
     readonly memoryMiB: 512;
 };
-/** E2B's default sandbox timeout, 300 s. */
+/** E2B's default sandbox timeout, 300 s. Not sent: a sandbox created with no
+ * timeoutMs has no time limit on Runtime, running while it works and pausing
+ * when idle (0300). Kept for code that imports it. */
 export declare const DEFAULT_TIMEOUT_MS = 300000;
 export type SandboxState = "running" | "paused";
 export type SandboxOnTimeout = "pause" | "kill" | {
@@ -30,7 +32,8 @@ export interface SandboxOpts extends ConnectionOpts {
     /** The sandbox's own environment: every command, terminal and code run in it
      * gets these, whoever connects. Values are never shown again. */
     envs?: Record<string, string>;
-    /** Default 300 000, at most 24 hours. Runtime's leases run 60 s to 1 hour:
+    /** When it ends, at most 24 hours. Leave it out for no time limit: it runs
+     * while it works and pauses when idle. Runtime's limits run 60 s to 1 hour:
      * shorter rounds up to 60 s (with a warning); longer gets an hour, moved on
      * while this process runs, up to the time asked for. */
     timeoutMs?: number;
@@ -125,7 +128,8 @@ export declare class Sandbox {
     kill(opts?: Pick<ConnectionOpts, "requestTimeoutMs" | "signal">): Promise<boolean>;
     /** Sets the sandbox to end `timeoutMs` from now, up to 24 hours; past an
      * hour the lease is moved on while this process runs. Runtime cannot end a
-     * lease early, so an end sooner than the lease's is refused. */
+     * lease early, so an end sooner than the lease's is refused. A sandbox
+     * created with no timeout has no end to move, and nothing changes. */
     static setTimeout(sandboxId: string, timeoutMs: number, opts?: SandboxApiOpts): Promise<void>;
     setTimeout(timeoutMs: number, opts?: Pick<ConnectionOpts, "requestTimeoutMs" | "signal">): Promise<void>;
     static getInfo(sandboxId: string, opts?: SandboxApiOpts): Promise<SandboxInfo>;

package/dist/e2b/sandbox.js

@@ -9,7 +9,9 @@ import { Pty } from "./pty.js";
 /** E2B's default machine: 2 vCPU and 512 MiB (docs.e2b.dev/billing, checked
  * 23 September 2026). Pass `runtime: { create: { memoryMiB } }` for another. */
 export const DEFAULT_SHAPE = { vcpu: 2, memoryMiB: 512 };
-/** E2B's default sandbox timeout, 300 s. */
+/** E2B's default sandbox timeout, 300 s. Not sent: a sandbox created with no
+ * timeoutMs has no time limit on Runtime, running while it works and pausing
+ * when idle (0300). Kept for code that imports it. */
 export const DEFAULT_TIMEOUT_MS = 300_000;
 /** Runtime's lease bounds (MAX_TIMEOUT_SECONDS in the API). */
 const MIN_LEASE_SECONDS = 60;
@@ -93,6 +95,8 @@ async function renew(keeper) {
         if (current === "stopped")
             return stopKeeping(id);
         if (current === "running") {
+            if (keeper.runtime.info.endsAt === null)
+                return stopKeeping(id);
             const end = Date.parse(keeper.runtime.info.expiresAt);
             const want = Math.min(keeper.until, Date.now() + KEEP_AHEAD_MS);
             const later = Math.floor((want - end) / 1000);
@@ -200,7 +204,8 @@ function infoOf(runtime) {
         ...(info.name ? { name: info.name } : {}),
         metadata: info.labels ?? {},
         startedAt: new Date(info.createdAt),
-        endAt: new Date(info.expiresAt),
+        // With no time limit, where it is paid up to: always ahead, moving on.
+        endAt: new Date(info.endsAt ?? info.expiresAt),
         state: current === "stopped" ? "paused" : current,
         cpuCount: info.vcpu,
         memoryMB: info.memoryMiB,
@@ -301,9 +306,10 @@ export class Sandbox {
         options.signal?.throwIfAborted();
         refuseCreate(opts);
         const client = clientFor(opts);
-        const asked = Date.now() + (opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        // No timeoutMs, no time limit: it runs while it works (0300).
+        const asked = opts.timeoutMs === undefined ? undefined : Date.now() + opts.timeoutMs;
         const input = {
-            timeoutSeconds: leaseSeconds(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+            ...(opts.timeoutMs === undefined ? {} : { timeoutSeconds: leaseSeconds(opts.timeoutMs) }),
             onLeaseEnd: onLeaseEnd(opts.lifecycle),
             // With a lifecycle, E2B resumes a paused sandbox on traffic only when
             // asked (autoResume); Runtime's automatic wake is the same thing (0093).
@@ -324,7 +330,8 @@ export class Sandbox {
             ...opts.runtime?.create,
         };
         const runtime = await guard("sandbox", () => client.sandboxes.create(create, options));
-        keepUntil(runtime, asked);
+        if (asked !== undefined)
+            keepUntil(runtime, asked);
         return new this(runtime, client, opts.requestTimeoutMs);
     }
     /** Connects to a sandbox by id, waking it if it is paused, as E2B does. A
@@ -373,7 +380,8 @@ export class Sandbox {
     }
     /** Sets the sandbox to end `timeoutMs` from now, up to 24 hours; past an
      * hour the lease is moved on while this process runs. Runtime cannot end a
-     * lease early, so an end sooner than the lease's is refused. */
+     * lease early, so an end sooner than the lease's is refused. A sandbox
+     * created with no timeout has no end to move, and nothing changes. */
     static async setTimeout(sandboxId, timeoutMs, opts = {}) {
         const client = clientFor(opts);
         const runtime = await guard("sandbox", () => client.sandboxes.get(sandboxId, request(opts)));
@@ -547,6 +555,9 @@ async function resume(runtime, opts) {
     }
     else if (opts.timeoutMs !== undefined) {
         checkTimeout(opts.timeoutMs);
+        // No time limit: no end to move (0300).
+        if (runtime.info.endsAt === null)
+            return;
         const later = Math.min(asked, Date.now() + KEEP_AHEAD_MS) - Date.parse(runtime.info.expiresAt);
         if (later > 1000)
             await guard("sandbox", () => runtime.extend(Math.ceil(later / 1000), request(opts)));
@@ -562,8 +573,11 @@ async function stop(runtime, opts) {
 }
 async function extendTo(runtime, timeoutMs, opts) {
     checkTimeout(timeoutMs);
+    // No time limit: no end to move (0300).
+    if (runtime.info.endsAt === null)
+        return;
     const asked = Date.now() + timeoutMs;
-    const end = Date.parse(runtime.info.expiresAt);
+    const end = Date.parse(runtime.info.endsAt ?? runtime.info.expiresAt);
     if (asked - end < -1000)
         throw new NotSupportedError("Ending a sandbox sooner than its lease (a shorter setTimeout)", "Runtime cannot end a lease early. Call kill() when the work is done.");
     const later = Math.min(asked, Date.now() + KEEP_AHEAD_MS) - end;

package/dist/errors.d.ts

@@ -6,6 +6,12 @@
  * packages/cloud/src/api/respond.ts) and retrying cannot change them.
  * host_unavailable and busy pass, and are retried. */
 export declare const DELIBERATE: ReadonlySet<string>;
+/** Refusals that guarantee nothing ran: a sandbox running as many commands
+ * as it can (`guest_busy`), and the API's own limits, which answer before any
+ * work starts (`busy`, `rate_limited`). Sending such a call again is always
+ * safe, so the SDK does, with backoff, until the call's deadline (five
+ * minutes when it has none), however many retries it allows otherwise. */
+export declare const NOTHING_RAN: ReadonlySet<string>;
 /** Refusals of a create that clear when a sandbox stops or pauses, or a host
  * frees room: the trial's slots, an email domain's trial slots, the account's
  * quota and the region's capacity. `sandboxes.create` waits them out, retrying

package/dist/errors.js

@@ -16,6 +16,12 @@ export const DELIBERATE = new Set([
     "identity_unavailable",
     "env_unavailable",
 ]);
+/** Refusals that guarantee nothing ran: a sandbox running as many commands
+ * as it can (`guest_busy`), and the API's own limits, which answer before any
+ * work starts (`busy`, `rate_limited`). Sending such a call again is always
+ * safe, so the SDK does, with backoff, until the call's deadline (five
+ * minutes when it has none), however many retries it allows otherwise. */
+export const NOTHING_RAN = new Set(["guest_busy", "busy", "rate_limited"]);
 /** Refusals that pass on their own: a host frees room, a trial slot frees. */
 const PASSING = new Set(["no_capacity", "trial_busy"]);
 /** Refusals of a create that clear when a sandbox stops or pauses, or a host

package/dist/identity.js

@@ -1,4 +1,5 @@
 import { RuntimeError } from "./errors.js";
+import { sandboxMarker } from "./transport.js";
 async function requestCredentials() {
     let url = process.env.RUNTIME_ID_TOKEN_REQUEST_URL;
     let token = process.env.RUNTIME_ID_TOKEN_REQUEST_TOKEN;
@@ -7,7 +8,7 @@ async function requestCredentials() {
         try {
             // Loaded here, so the SDK still loads where there is no file system.
             const { readFile } = await import("node:fs/promises");
-            const env = JSON.parse(await readFile("/run/runtime/environment.json", "utf8"));
+            const env = JSON.parse(await readFile(sandboxMarker.path, "utf8"));
             url = env.RUNTIME_ID_TOKEN_REQUEST_URL;
             token = env.RUNTIME_ID_TOKEN_REQUEST_TOKEN;
         }

package/dist/index.d.ts

@@ -35,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/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,13 +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. Paid accounts only, and free.
+  Only your own sandboxes answer. Needs a kept top-up; free.
 `,
 };
 function usage(product, message) {
@@ -411,7 +411,7 @@ export async function networkProductCommand(product, argv, args, out, client) {
             ? "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 is for paid accounts; add credit to turn it on.";
+                : "Off. Reaching your sandboxes by name needs a kept top-up.";
         switch (rest[0]) {
             case "on":
             case "off": {

package/dist/products/browser.d.ts

@@ -34,7 +34,8 @@ export type BrowserStartOptions = {
 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). Starting a running browser returns it as it is. */
+     * 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;

package/dist/products/browser.js

@@ -1,3 +1,4 @@
+import { whileInstalling } from "../wait.js";
 /** `sbx.browser`: Chromium in the sandbox, for agents that speak CDP.
  *
  *   const { cdpUrl } = await sbx.browser.start();
@@ -9,26 +10,15 @@ export function sandboxBrowser(t, sandbox) {
     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). Starting a running browser returns it as it is. */
+         * minutes, or the call's timeoutMs). Starting a running browser returns it
+         * as it is. */
         async start(input = {}, options) {
-            const deadline = Date.now() + 600_000;
-            for (;;) {
-                try {
-                    return await t.json({
-                        method: "POST",
-                        path: `${base()}:start`,
-                        body: input,
-                        ...options,
-                    });
-                }
-                catch (error) {
-                    const code = error.code;
-                    if ((code !== "browser_installing" && code !== "desktop_installing") ||
-                        Date.now() > deadline)
-                        throw error;
-                    await new Promise((resolve) => setTimeout(resolve, error.retryAfterMs ?? 10_000));
-                }
-            }
+            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 }),

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;