smolmachines 1.25.1 → 1.26.1

package/README.md

@@ -321,6 +321,17 @@ await m.publishCacheDisk();                                       // v1
 // Every machine created with cacheDisk: { cache: "deps" } now starts from v1.
 ```
 
+One checkpoint can resume with many caches. Create the base machine with an
+empty cache as a slot, which attaches it unmounted, and checkpoint it warm.
+Each restore then mounts its own cache there, no larger than the slot and at
+the slot's mount path:
+
+```ts
+const base = await Machine.create({ image: "node:22", cacheDisk: { cache: "slot-20g", slot: true } });
+const { id } = await base.checkpoint();
+const a = await Machine.restoreCheckpoint(id, "project-a", undefined, { cacheDisk: { cache: "project-a" } });
+```
+
 ## Building from source
 
 This package's native core lives alongside it (Rust, `src/*.rs`) and links the

package/dist/generated/smolfleet.d.ts

@@ -143,6 +143,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/account/plan/checkout": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Subscribe to a plan through Stripe Checkout.
+         * @description Returns a Stripe-hosted page that shows the plan and its monthly price, takes a card and collects the first month. Once Stripe confirms the payment the account moves onto the plan and keeps the card for later charges. For an account with no card on file; with one, change plan directly. Requires the `billing:write` scope.
+         */
+        post: operations["account_plan_checkout"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/account/plans": {
         parameters: {
             query?: never;
@@ -439,6 +459,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/billing/card": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get the card on file.
+         * @description Returns the brand, last four digits and expiry of the card the account's plan fee and auto top-ups are charged to. Requires the `usage:read` or `machine:read` scope.
+         */
+        get: operations["billing_card_get"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/billing/checkout-session": {
         parameters: {
             query?: never;
@@ -2323,8 +2363,7 @@ export interface components {
             scopes: string[];
         };
         /**
-         * @description Opt-in saved-card auto-recharge settings (`GET`/`POST /v1/billing/auto-recharge`).
-         *     Threshold/amount are the RESOLVED effective values (per-tenant override, else
+         * @description Threshold/amount are the RESOLVED effective values (per-tenant override, else
          *     fleet default), so the UI can render exactly what will happen.
          */
         AutoRechargeSettings: {
@@ -2388,6 +2427,21 @@ export interface components {
              */
             version: number;
         };
+        /**
+         * @description Opt-in saved-card auto-recharge settings (`GET`/`POST /v1/billing/auto-recharge`).
+         *     The card on file: what the account's plan fee and auto top-ups are charged
+         *     to, as Stripe describes it. Never the number itself.
+         */
+        CardOnFile: {
+            /** @description Card network, e.g. `visa`, `mastercard`, `amex`. */
+            brand: string;
+            /** Format: int32 */
+            expMonth: number;
+            /** Format: int32 */
+            expYear: number;
+            /** @description Last four digits. */
+            last4: string;
+        };
         /**
          * @description Ask to move this tenant onto a different plan. Only plans whose
          *     `self_serve` flag is set may be chosen; operator tiers are assigned by an
@@ -2982,7 +3036,11 @@ export interface components {
         /** @description The cache disk a machine runs with. */
         MachineCacheDisk: {
             cacheDiskId: string;
+            /** @description Put in a cache slot by a restore, which needs an engine that serves slots. */
+            intoSlot?: boolean;
             mountPath: string;
+            /** @description Attached unmounted, as a slot a restore can put another cache in. */
+            slot?: boolean;
             /** Format: int32 */
             version: number;
         };
@@ -2998,6 +3056,12 @@ export interface components {
              *     left out.
              */
             mountPath?: string | null;
+            /**
+             * @description Attach it as a slot: left unmounted, so a checkpoint of the machine can
+             *     be restored with a different cache mounted here (`cacheDisk` on restore).
+             *     The slot's size is this cache disk's size; its contents are never read.
+             */
+            slot?: boolean;
             /**
              * Format: int32
              * @description Version to start from; the latest when left out.
@@ -3729,6 +3793,7 @@ export interface components {
         };
         /** @description Create a stopped machine from a durable portable checkpoint. */
         RestorePortableCheckpointRequest: {
+            cacheDisk?: null | components["schemas"]["MachineCacheDiskSpec"];
             name: string;
         };
         ScaleRequest: {
@@ -4268,7 +4333,7 @@ export interface operations {
                     "application/json": components["schemas"]["ErrorResponse"];
                 };
             };
-            /** @description The plan's monthly fee has no saved card to bill, or the card was declined; the plan does not move. */
+            /** @description The plan's monthly fee has no saved card to bill (subscribe through /v1/account/plan/checkout instead), or the card was declined; the plan does not move. */
             402: {
                 headers: {
                     [name: string]: unknown;
@@ -4333,6 +4398,91 @@ export interface operations {
             };
         };
     };
+    account_plan_checkout: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ChangePlanRequest"];
+            };
+        };
+        responses: {
+            /** @description Returns {"url": <stripe-hosted url>} for a Stripe Checkout in subscription mode; the browser comes back to the console's billing page. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Missing or invalid API key */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Key lacks the required scope */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description The account is already on that plan, or already pays a plan fee */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description That plan is not self-serve, or has no monthly fee */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Rate limited; retry after the Retry-After header */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Internal error */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Paid plans are not enabled on this deployment */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
     account_plans_list: {
         parameters: {
             query?: never;
@@ -5549,6 +5699,80 @@ export interface operations {
             };
         };
     };
+    billing_card_get: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The card on file */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CardOnFile"];
+                };
+            };
+            /** @description Missing or invalid API key */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Key lacks the required scope */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description No card on file, or card payments are not enabled */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Rate limited; retry after the Retry-After header */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Internal error */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description The payment provider did not answer */
+            502: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
     billing_checkout_session: {
         parameters: {
             query?: never;

package/dist/index.d.ts

@@ -22,4 +22,4 @@ export type { BuildRolloutJobOptions, EnsureRolloutExecutorOptions, RolloutBatch
 export { SmolError, NotSupportedError, InvalidConfigError, ExecutionError } from './errors';
 export type { CloudCheckpointInfo } from './transport';
 export type { LocalAvailability, LocalUnavailableCode } from './availability';
-export type { MachineConfig, CredentialSpec, CacheDiskRef, CacheDiskInfo, CacheDiskVersion, CreateCacheDiskOptions, PublishedCacheDisk, NetworkPolicy, RestoreCheckpointOptions, MachineState, ResourceSpec, MountSpec, PortSpec, BranchOptions, BranchBatchOptions, CheckpointOptions, ResizeOptions, MachineResources, ForkOptions, ForkBatchOptions, AssignOptions, ExecOptions, ExecResult, MachineUsageReport, ShareLink, PortableCheckpointInfo, MachineUsageTotals, MachineCostBreakdown, ImageInfo, MachineSummary, ListOptions, ExecEvent, ConnectOptions, EgressInterceptor, StartOptions, WaitReadyOptions, PortEndpoint, } from './types';
+export type { MachineConfig, CredentialSpec, CacheDiskRef, CacheDiskInfo, CacheDiskVersion, CreateCacheDiskOptions, PublishedCacheDisk, NetworkPolicy, RestoreCheckpointOptions, MachineState, ResourceSpec, MountSpec, PortSpec, BranchOptions, BranchBatchOptions, CheckpointOptions, ResizeOptions, MachineResources, ForkOptions, ForkBatchOptions, AssignOptions, ExecOptions, ExecResult, MachineUsageReport, ShareLink, PortableCheckpointInfo, MachineUsageTotals, MachineCostBreakdown, ImageInfo, MachineSummary, ListOptions, ExecEvent, ConnectOptions, EgressInterceptor, StartOptions, ResumeOptions, WaitReadyOptions, PortEndpoint, } from './types';

package/dist/machine.d.ts

@@ -9,7 +9,7 @@
  */
 import { type LocalAvailability } from "./availability";
 import { type CloudCheckpointInfo, type Transport } from "./transport";
-import type { CacheDiskInfo, CreateCacheDiskOptions, PublishedCacheDisk, MachineResources, ResizeOptions, AssignOptions, BranchBatchOptions, BranchOptions, CheckpointOptions, ConnectOptions, ExecEvent, ExecOptions, ExecResult, ForkBatchOptions, ForkOptions, ImageInfo, ListOptions, MachineConfig, MachineSummary, NetworkPolicy, RestoreCheckpointOptions, StartOptions, MachineUsageReport, ShareLink, PortableCheckpointInfo, PortEndpoint, PortSpec, WaitReadyOptions } from "./types";
+import type { CacheDiskInfo, CreateCacheDiskOptions, PublishedCacheDisk, MachineResources, ResizeOptions, AssignOptions, BranchBatchOptions, BranchOptions, CheckpointOptions, ConnectOptions, ExecEvent, ExecOptions, ExecResult, ForkBatchOptions, ForkOptions, ImageInfo, ListOptions, MachineConfig, MachineSummary, NetworkPolicy, RestoreCheckpointOptions, StartOptions, ResumeOptions, MachineUsageReport, ShareLink, PortableCheckpointInfo, PortEndpoint, PortSpec, WaitReadyOptions } from "./types";
 export declare class Machine {
     private readonly transport;
     private constructor();
@@ -50,6 +50,10 @@ export declare class Machine {
      * @param options  `labels`: keep machines carrying every one of these
      */
     static list(conn?: ConnectOptions, options?: ListOptions): Promise<MachineSummary[]>;
+    /** Check that a cloud connection works: the key is accepted and the base URL
+     *  answers with a machine list. Throws otherwise, including when a proxy or
+     *  a wrong URL answers with something that is not a machine list. */
+    static probe(conn?: ConnectOptions): Promise<void>;
     /** Upload a `.checkpoint` file taken on this computer to the cloud, so it
      *  can be restored there by the returned id. Restoring the file with a cloud
      *  target uploads it for you. */
@@ -85,6 +89,15 @@ export declare class Machine {
      *  process launched; it does not mean the guest or workload is ready. Use
      *  `ready()` or `waitUntilReady()` before doing work. */
     state(): Promise<string>;
+    /** The machine's full cloud record, every field the control plane returns
+     *  (env, readiness, ports, …). Cloud only. */
+    info(): Promise<Record<string, unknown>>;
+    /** The last `tail` lines of the machine's console log. Cloud only. */
+    logs(tail?: number): Promise<string>;
+    /** Export this stopped machine as a `.smolmachine` in your registry
+     *  namespace, re-deployable anywhere. Distinct from a portable checkpoint,
+     *  which also keeps live memory. Cloud only. */
+    exportArtifact(): Promise<Record<string, unknown>>;
     /** Whether the machine is READY to do work. `state()` becoming "started"
      *  means only that the VM process launched — the guest is still booting and
      *  is NOT yet usable. `ready` becomes true once the in-VM agent is reachable
@@ -140,7 +153,7 @@ export declare class Machine {
     /** Save RAM and disk durably, then stop at that execution boundary. */
     pause(): Promise<void>;
     /** Resume saved execution in this machine. */
-    resume(): Promise<void>;
+    resume(options?: ResumeOptions): Promise<void>;
     /** Boot a stopped machine with its disk state, not its previous RAM.
      *  The local handle reuses its interceptor binding or accepts a fresh one. */
     start(options?: StartOptions): Promise<void>;

package/dist/machine.js

@@ -31,6 +31,7 @@ const transport_1 = require("./transport");
 function makeExecResult(r) {
     const success = r.exitCode === 0;
     return {
+        ...(r.pid !== undefined ? { pid: r.pid } : {}),
         exitCode: r.exitCode,
         stdout: r.stdout,
         stderr: r.stderr,
@@ -102,6 +103,14 @@ class Machine {
     static async list(conn = {}, options = {}) {
         return (0, transport_1.listMachines)(conn, options);
     }
+    /** Check that a cloud connection works: the key is accepted and the base URL
+     *  answers with a machine list. Throws otherwise, including when a proxy or
+     *  a wrong URL answers with something that is not a machine list. */
+    static async probe(conn = {}) {
+        if (conn.target === "local")
+            throw new errors_1.NotSupportedError("probe is cloud-only.");
+        await (0, transport_1.listMachines)({ ...conn, target: "cloud" });
+    }
     /** Upload a `.checkpoint` file taken on this computer to the cloud, so it
      *  can be restored there by the returned id. Restoring the file with a cloud
      *  target uploads it for you. */
@@ -167,6 +176,27 @@ class Machine {
     state() {
         return this.transport.state();
     }
+    /** The machine's full cloud record, every field the control plane returns
+     *  (env, readiness, ports, …). Cloud only. */
+    info() {
+        if (!this.transport.info)
+            throw new errors_1.NotSupportedError("info is cloud-only.");
+        return this.transport.info();
+    }
+    /** The last `tail` lines of the machine's console log. Cloud only. */
+    logs(tail = 100) {
+        if (!this.transport.logs)
+            throw new errors_1.NotSupportedError("logs is cloud-only.");
+        return this.transport.logs(tail);
+    }
+    /** Export this stopped machine as a `.smolmachine` in your registry
+     *  namespace, re-deployable anywhere. Distinct from a portable checkpoint,
+     *  which also keeps live memory. Cloud only. */
+    exportArtifact() {
+        if (!this.transport.exportArtifact)
+            throw new errors_1.NotSupportedError("exportArtifact is cloud-only.");
+        return this.transport.exportArtifact();
+    }
     /** Whether the machine is READY to do work. `state()` becoming "started"
      *  means only that the VM process launched — the guest is still booting and
      *  is NOT yet usable. `ready` becomes true once the in-VM agent is reachable
@@ -262,11 +292,13 @@ class Machine {
     /** Save RAM and disk durably, then stop at that execution boundary. */
     pause() { return this.transport.pause(); }
     /** Resume saved execution in this machine. */
-    resume() { return this.transport.resume(); }
+    resume(options = {}) {
+        return this.transport.resume(options.waitUntilReady ?? true);
+    }
     /** Boot a stopped machine with its disk state, not its previous RAM.
      *  The local handle reuses its interceptor binding or accepts a fresh one. */
     start(options = {}) {
-        return this.transport.start(options.egressInterceptor);
+        return this.transport.start(options.egressInterceptor, options.waitUntilReady ?? true);
     }
     delete(opts) {
         if (opts?.includeUsage)

package/dist/transport.d.ts

@@ -10,6 +10,8 @@ import { type NativeMachineConfig } from "./native";
 import type { CheckpointOptions, CacheDiskInfo, CreateCacheDiskOptions, PublishedCacheDisk, MachineResources, ResizeOptions, ConnectOptions, NetworkPolicy, RestoreCheckpointOptions, ExecEvent, ExecOptions, EgressInterceptor, AssignOptions, ForkBatchOptions, ForkOptions, ImageInfo, ListOptions, MachineConfig, MachineSummary, MachineUsageReport, ShareLink, PortableCheckpointInfo, PortEndpoint, PortSpec, WaitReadyOptions } from "./types";
 /** Raw exec result (the ergonomic wrapper is added in machine.ts). */
 export interface RawExec {
+    /** The detached process's pid, for a background exec. */
+    pid?: number;
     exitCode: number;
     stdout: string;
     stderr: string;
@@ -23,6 +25,12 @@ export interface RawExec {
 }
 export interface Transport {
     readonly name: string;
+    /** Cloud only: the machine's full record as the control plane returns it. */
+    info?(): Promise<Record<string, unknown>>;
+    /** Cloud only: the last `tail` lines of the machine's console log. */
+    logs?(tail: number): Promise<string>;
+    /** Cloud only: export the stopped machine as a `.smolmachine` in the registry. */
+    exportArtifact?(): Promise<Record<string, unknown>>;
     state(): Promise<string>;
     ready(): Promise<boolean>;
     readyAt(): Promise<string | null>;
@@ -41,8 +49,8 @@ export interface Transport {
     setNetworkPolicy(policy: NetworkPolicy): Promise<void>;
     stop(): Promise<void>;
     pause(): Promise<void>;
-    resume(): Promise<void>;
-    start(interceptor?: EgressInterceptor): Promise<void>;
+    resume(waitUntilReady?: boolean): Promise<void>;
+    start(interceptor?: EgressInterceptor, waitUntilReady?: boolean): Promise<void>;
     delete(): Promise<void>;
     /** Cloud only: delete and return the settled usage + cost in one call. */
     deleteWithUsage(): Promise<MachineUsageReport>;
@@ -110,7 +118,17 @@ export declare function toNativeConfig(name: string, config: MachineConfig): Nat
 interface CloudConn {
     baseUrl: string;
     apiKey: string;
+    /** The caller's `fetch` (ConnectOptions.fetch), when it supplied one. */
+    fetch?: typeof fetch;
+    readResponseBytes?: (response: Response) => Promise<Uint8Array>;
 }
+/** The largest file the cloud's file routes accept. */
+export declare const CLOUD_MAX_FILE_BYTES: number;
+/** How long moving `bytes` may take (ms): the request timeout plus the time
+ *  `bytes` needs at the floor rate. */
+export declare function transferTimeoutMs(bytes: number): number;
+/** Refuse a file the cloud would refuse, before sending any of it. */
+export declare function checkCloudFileSize(path: string, bytes: number): void;
 /** The sentence a person should read from a failed response's body. The
  *  control plane answers errors as RFC 9457 problem+json, whose `detail` is the
  *  sentence; older builds sent `{"error": …}` or plain text. A JSON object

package/dist/transport.js

@@ -8,6 +8,7 @@
  *  Cloud-only/local-only capability gaps surface as `NotSupportedError`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLOUD_MAX_FILE_BYTES = void 0;
 exports.cliConfigApiKey = cliConfigApiKey;
 exports.resolveNetwork = resolveNetwork;
 exports.networkMode = networkMode;
@@ -15,6 +16,8 @@ exports.cloudNetwork = cloudNetwork;
 exports.egressPolicy = egressPolicy;
 exports.resolveBranchable = resolveBranchable;
 exports.toNativeConfig = toNativeConfig;
+exports.transferTimeoutMs = transferTimeoutMs;
+exports.checkCloudFileSize = checkCloudFileSize;
 exports.errorSentence = errorSentence;
 exports.encodePath = encodePath;
 exports.selectsCloud = selectsCloud;
@@ -526,7 +529,7 @@ class LocalTransport {
         }
         liveLocal.delete(this);
     }
-    async resume() {
+    async resume(waitUntilReady = true) {
         try {
             await this.inner.resume();
         }
@@ -535,9 +538,10 @@ class LocalTransport {
         }
         if (this.cleanupOnExit)
             liveLocal.add(this);
-        await this.waitUntilReady();
+        if (waitUntilReady)
+            await this.waitUntilReady();
     }
-    async start(interceptor) {
+    async start(interceptor, waitUntilReady = true) {
         try {
             const binding = interceptor ?? this.interceptor;
             if (binding)
@@ -552,7 +556,8 @@ class LocalTransport {
         }
         if (this.cleanupOnExit)
             liveLocal.add(this);
-        await this.waitUntilReady();
+        if (waitUntilReady)
+            await this.waitUntilReady();
     }
     async delete() {
         liveLocal.delete(this);
@@ -685,9 +690,35 @@ class LocalTransport {
         throw new errors_1.NotSupportedError("getLease() is a cloud-only lease feature.");
     }
 }
+/** A cloud connection carrying the caller's transport hooks. */
+function cloudConnOf(conn, baseUrl, apiKey) {
+    return {
+        baseUrl,
+        apiKey,
+        ...(conn.fetch ? { fetch: conn.fetch } : {}),
+        ...(conn.readResponseBytes ? { readResponseBytes: conn.readResponseBytes } : {}),
+    };
+}
 const DEFAULT_CLOUD_URL = "https://api.smolmachines.com";
 /** Default per-request timeout for cloud calls (ms). Override via opts.timeoutMs. */
 const CLOUD_TIMEOUT_MS = 30_000;
+// A file transfer is given time for the slowest link it should survive: a
+// large file over a slow uplink must not fail at CLOUD_TIMEOUT_MS while it is
+// still moving. Same floor as the Rust and Python SDKs.
+const CLOUD_TRANSFER_FLOOR_BYTES_PER_S = 256 * 1024;
+/** The largest file the cloud's file routes accept. */
+exports.CLOUD_MAX_FILE_BYTES = 100 * 1024 * 1024;
+/** How long moving `bytes` may take (ms): the request timeout plus the time
+ *  `bytes` needs at the floor rate. */
+function transferTimeoutMs(bytes) {
+    return CLOUD_TIMEOUT_MS + Math.ceil(bytes / CLOUD_TRANSFER_FLOOR_BYTES_PER_S) * 1_000;
+}
+/** Refuse a file the cloud would refuse, before sending any of it. */
+function checkCloudFileSize(path, bytes) {
+    if (bytes > exports.CLOUD_MAX_FILE_BYTES) {
+        throw new errors_1.SmolError("SMOLVM_ERROR", `${path} is ${(bytes / (1024 * 1024)).toFixed(1)} MiB; cloud machines accept files up to ${exports.CLOUD_MAX_FILE_BYTES / (1024 * 1024)} MiB`);
+    }
+}
 // Starting can include a cold image pull. Keep ordinary API calls short, but
 // give this explicitly long-running operation the same bounded window already
 // used by checkpoint restore.
@@ -750,7 +781,7 @@ async function cloudFetch(conn, method, path, opts = {}) {
     opts.signal?.addEventListener("abort", onAbort, { once: true });
     let res;
     try {
-        res = await fetch(`${conn.baseUrl}${path}`, {
+        res = await (conn.fetch ?? fetch)(`${conn.baseUrl}${path}`, {
             method,
             headers,
             body: body ?? null,
@@ -763,6 +794,9 @@ async function cloudFetch(conn, method, path, opts = {}) {
         if (e.name === "AbortError") {
             throw new errors_1.SmolError("TIMEOUT", `cloud ${method} ${path} timed out after ${opts.timeoutMs ?? CLOUD_TIMEOUT_MS}ms`);
         }
+        // A caller's own fetch owns its failure modes (retries, typed errors).
+        if (conn.fetch)
+            throw e;
         throw new errors_1.SmolError("CONNECTION", `cloud request failed: ${e.message}`);
     }
     finally {
@@ -781,8 +815,15 @@ async function cloudFetch(conn, method, path, opts = {}) {
                 ? "UNAUTHORIZED"
                 : "SMOLVM_ERROR", `cloud ${method} ${path} → ${res.status}${text ? `: ${text}` : ""}${rid ? ` [request id: ${rid}]` : ""}`);
     }
-    if (opts.accept === "bytes")
+    if (opts.accept === "text")
+        return (await res.text());
+    if (opts.accept === "bytes") {
+        if (conn.readResponseBytes) {
+            const bytes = await conn.readResponseBytes(res);
+            return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        }
         return Buffer.from(await res.arrayBuffer());
+    }
     if (res.status === 204)
         return undefined;
     const ct = res.headers.get("content-type") ?? "";
@@ -947,6 +988,7 @@ class CloudTransport {
             cwd: opts?.workdir ?? null,
             timeoutSeconds: opts?.timeout ?? null,
             ...(opts?.user !== undefined ? { user: opts.user } : {}),
+            ...(opts?.background ? { background: true } : {}),
         };
         // The command may legitimately run far longer than the default cloud
         // timeout, so size the request abort timeout off the request's own timeout
@@ -971,7 +1013,10 @@ class CloudTransport {
         // `stdoutB64`/`stderrB64` are byte-exact and untruncated; the generated
         // schema type may lag the server, so read them off the raw object.
         const raw = r;
+        // A detached command reports its pid as `pid=<n>` on stdout.
+        const pidMatch = opts?.background ? /^pid=(\d+)/m.exec(stdout) : null;
         return {
+            ...(pidMatch ? { pid: Number(pidMatch[1]) } : {}),
             exitCode: r.exitCode ?? 0,
             stdout,
             stderr,
@@ -1002,7 +1047,7 @@ class CloudTransport {
         };
         let res;
         try {
-            res = await fetch(`${this.conn.baseUrl}/v1/machines/${this.id}/exec/stream`, {
+            res = await (this.conn.fetch ?? fetch)(`${this.conn.baseUrl}/v1/machines/${this.id}/exec/stream`, {
                 method: "POST",
                 headers: {
                     authorization: `Bearer ${this.conn.apiKey}`,
@@ -1107,11 +1152,14 @@ class CloudTransport {
     async readFile(path) {
         return cloudFetch(this.conn, "GET", `/v1/machines/${this.id}/files/${encodePath(path)}`, {
             accept: "bytes",
+            timeoutMs: transferTimeoutMs(exports.CLOUD_MAX_FILE_BYTES),
         });
     }
     async writeFile(path, data, mode) {
+        checkCloudFileSize(path, data.length);
         await cloudFetch(this.conn, "PUT", `/v1/machines/${this.id}/files/${encodePath(path)}`, {
             body: data,
+            timeoutMs: transferTimeoutMs(data.length),
         });
         // The cloud /files PUT carries no file mode, so apply it with chmod when
         // requested — e.g. writing an executable script the caller then runs.
@@ -1137,18 +1185,34 @@ class CloudTransport {
     async pause() {
         await cloudFetch(this.conn, "POST", `/v1/machines/${this.id}/pause`, { timeoutMs: CLOUD_START_TIMEOUT_MS });
     }
-    async resume() {
+    async resume(waitUntilReady = true) {
         await cloudFetch(this.conn, "POST", `/v1/machines/${this.id}/resume`, { timeoutMs: CLOUD_START_TIMEOUT_MS });
-        await waitForReady(this.conn, this.id);
+        if (waitUntilReady)
+            await waitForReady(this.conn, this.id);
     }
-    async start(interceptor) {
+    async start(interceptor, waitUntilReady = true) {
         if (interceptor)
             throw new errors_1.NotSupportedError("egressInterceptor is local-only.");
         // Resume a stopped machine, then wait for its agent so the handle is usable.
         await cloudFetch(this.conn, "POST", `/v1/machines/${this.id}/start`, {
             timeoutMs: CLOUD_START_TIMEOUT_MS,
         });
-        await waitForReady(this.conn, this.id);
+        if (waitUntilReady)
+            await waitForReady(this.conn, this.id);
+    }
+    async info() {
+        return cloudFetch(this.conn, "GET", `/v1/machines/${this.id}`);
+    }
+    async logs(tail) {
+        return cloudFetch(this.conn, "GET", `/v1/machines/${this.id}/logs?tail=${tail}`, {
+            accept: "text",
+        });
+    }
+    async exportArtifact() {
+        return cloudFetch(this.conn, "POST", `/v1/machines/${this.id}/export`, {
+            json: {},
+            timeoutMs: CLOUD_START_TIMEOUT_MS,
+        });
     }
     async delete() {
         await cloudFetch(this.conn, "DELETE", `/v1/machines/${this.id}`);
@@ -1443,7 +1507,7 @@ async function makeTransport(config, conn) {
             process.env.SMOL_CLOUD_URL ??
             cliUrl ??
             DEFAULT_CLOUD_URL).replace(/\/+$/, "");
-        const cloudConn = { baseUrl, apiKey: key };
+        const cloudConn = cloudConnOf(conn, baseUrl, key);
         await storeCloudCredentials(cloudConn, config.credentials);
         // smolfleet CreateMachineRequest (camelCase): source (tagged), nested
         // resources, network {mode}, autoStopSeconds, ttlSeconds. Optional numeric
@@ -1451,6 +1515,7 @@ async function makeTransport(config, conn) {
         // (exactOptionalPropertyTypes forbids passing `undefined` explicitly).
         const createBody = {
             name: config.name ?? null,
+            ...(config.labels && Object.keys(config.labels).length ? { labels: config.labels } : {}),
             source: { type: "image", reference: config.image },
             resources: {
                 ...(config.resources?.cpus !== undefined
@@ -1487,15 +1552,7 @@ async function makeTransport(config, conn) {
             ...(config.credentials?.length
                 ? { credentials: config.credentials.map((c) => c.name) }
                 : {}),
-            ...(config.cacheDisk
-                ? {
-                    cacheDisk: {
-                        cache: config.cacheDisk.cache,
-                        ...(config.cacheDisk.version !== undefined ? { version: config.cacheDisk.version } : {}),
-                        ...(config.cacheDisk.mountPath !== undefined ? { mountPath: config.cacheDisk.mountPath } : {}),
-                    },
-                }
-                : {}),
+            ...(config.cacheDisk ? { cacheDisk: cacheDiskBody(config.cacheDisk) } : {}),
             autoStopSeconds: config.autoStopSeconds ?? null,
             ttlSeconds: config.ttlSeconds ?? null,
             // Forkable is a CREATE-time property: the control plane persists it and the
@@ -1624,15 +1681,28 @@ async function listMachines(conn, options = {}) {
             process.env.SMOL_CLOUD_URL ??
             cliUrl ??
             DEFAULT_CLOUD_URL).replace(/\/+$/, "");
-        const listed = await cloudFetch({ baseUrl, apiKey: key }, "GET", "/v1/machines");
-        const rows = Array.isArray(listed) ? listed : (listed.machines ?? []);
+        // The control plane filters by label itself; the client-side filter below
+        // stays as the backstop for an older control plane that ignores it.
+        const labelQuery = Object.entries(options.labels ?? {})
+            .map(([k, v]) => `label=${encodeURIComponent(`${k}=${v}`)}`)
+            .join("&");
+        const listed = await cloudFetch(cloudConnOf(conn, baseUrl, key), "GET", `/v1/machines${labelQuery ? `?${labelQuery}` : ""}`);
+        // Anything but a machine list (a proxy's page, a wrong base URL) is an
+        // error, not an account with no machines.
+        const rows = Array.isArray(listed)
+            ? listed
+            : Array.isArray(listed?.machines)
+                ? listed.machines
+                : undefined;
+        if (!rows) {
+            throw new errors_1.SmolError("SMOLVM_ERROR", `cloud GET /v1/machines at ${baseUrl} did not return a machine list`);
+        }
         all = rows.map((m) => ({
             name: m.name ?? m.id,
             id: m.id,
             state: m.state,
             ...(m.source?.type === "image" && { image: m.source.reference }),
-            // The cloud API carries no caller labels yet.
-            labels: {},
+            labels: m.labels ?? {},
             persistent: !m.ephemeral,
             // Remote machines never depend on a client process.
             detached: true,
@@ -1694,7 +1764,7 @@ async function connectTransport(id, conn) {
         process.env.SMOL_CLOUD_URL ??
         cliUrl ??
         DEFAULT_CLOUD_URL).replace(/\/+$/, "");
-    const cloudConn = { baseUrl, apiKey: key };
+    const cloudConn = cloudConnOf(conn, baseUrl, key);
     // Resolve like the CLI does: try the id path first, and when that 404s,
     // list machines and match by NAME. `machine.name` returns the human name,
     // so `Machine.connect(other.name)` — the natural composition of this API —
@@ -1743,6 +1813,9 @@ async function restoreCheckpointTransport(checkpointId, name, conn, options) {
     }
     conn ??= { target: looksLikeLocalCheckpoint(checkpointId) ? "local" : "cloud" };
     if (!selectsCloud(conn)) {
+        if (options?.cacheDisk) {
+            throw new errors_1.InvalidConfigError("cacheDisk is cloud-only: a local restore has no cache slot.");
+        }
         const path = (0, node_path_1.resolve)(checkpointId);
         let restored;
         try {
@@ -1775,6 +1848,7 @@ async function restoreCheckpointTransport(checkpointId, name, conn, options) {
             ...(options?.networkPolicy !== undefined
                 ? { network: cloudNetwork(options.networkPolicy) }
                 : {}),
+            ...(options?.cacheDisk ? { cacheDisk: cacheDiskBody(options.cacheDisk) } : {}),
         },
     });
     const id = created.id;
@@ -1790,6 +1864,14 @@ async function restoreCheckpointTransport(checkpointId, name, conn, options) {
     }
     return new CloudTransport(cloudConn, created.name ?? name, id);
 }
+function cacheDiskBody(ref) {
+    return {
+        cache: ref.cache,
+        ...(ref.version !== undefined ? { version: ref.version } : {}),
+        ...(ref.mountPath !== undefined ? { mountPath: ref.mountPath } : {}),
+        ...(ref.slot ? { slot: true } : {}),
+    };
+}
 /** The control plane and key a cloud operation uses: explicit options, then
  *  the environment, then the CLI session. */
 function cloudConnFor(conn, operation) {
@@ -1803,7 +1885,7 @@ function cloudConnFor(conn, operation) {
         process.env.SMOL_CLOUD_URL ??
         cliUrl ??
         DEFAULT_CLOUD_URL).replace(/\/+$/, "");
-    return { baseUrl, apiKey: key };
+    return cloudConnOf(conn, baseUrl, key);
 }
 /** Create a cache disk; its version 0 is an empty filesystem. Cloud only. */
 function createCacheDisk(options, conn = {}) {

package/dist/types.d.ts

@@ -324,6 +324,12 @@ export interface RestoreCheckpointOptions {
      *  an earlier save point; do not run two machines from one checkpoint with
      *  it. Local target only. */
     keepIdentity?: boolean;
+    /** Mount this cache in the slot the checkpoint's machine was created with
+     *  (`cacheDisk: { cache, slot: true }`), in place of the cache it was
+     *  captured with. It must be no larger than the slot and mount at the
+     *  slot's path, so one base checkpoint resumes with each project's own
+     *  cache. Cloud only. */
+    cacheDisk?: CacheDiskRef;
 }
 /** Per-call execution options. */
 export interface ExecOptions {
@@ -354,6 +360,9 @@ export interface ExecOptions {
      *  Ignored (both families, as before) on older control planes and on the
      *  local target. */
     output?: "text" | "b64" | "both";
+    /** Cloud only: start the command detached and return at once with its
+     *  `pid`, leaving it running (a dev server, an agent) after the call ends. */
+    background?: boolean;
 }
 /** Result of a command execution. */
 export interface ExecResult {
@@ -377,6 +386,8 @@ export interface ExecResult {
      *  the lossy `stdout`); on the local target it is the UTF-8 encoding of `stdout`.
      *  Prefer this over `stdout` for binary or >1 MiB output. */
     stdoutBytes: Uint8Array;
+    /** The detached process's pid, for an exec run with `background: true`. */
+    pid?: number;
     /** Byte-exact, untruncated stderr; see `stdoutBytes`. */
     stderrBytes: Uint8Array;
     /** True when exitCode === 0. */
@@ -509,6 +520,14 @@ export interface ConnectOptions {
     baseUrl?: string;
     /** Cloud API key, `smk_…` (cloud target only). */
     apiKey?: string;
+    /** Cloud only: the `fetch` every cloud request goes through, for a proxy,
+     *  retries, tracing, or a runtime without a global `fetch`. Its own errors
+     *  reach the caller unchanged; timeouts and aborts are still reported as
+     *  `TIMEOUT` and the abort reason. Default: the global `fetch`. */
+    fetch?: typeof fetch;
+    /** Cloud only: read a binary response body, for a `fetch` whose responses
+     *  lack a working `arrayBuffer()`. */
+    readResponseBytes?: (response: Response) => Promise<Uint8Array>;
 }
 /** Per-launch trusted host service. Keep the token out of logs and persistent config. */
 export interface EgressInterceptor {
@@ -519,6 +538,15 @@ export interface EgressInterceptor {
 }
 export interface StartOptions {
     egressInterceptor?: EgressInterceptor;
+    /** Wait for the guest to be ready before returning (default true). Pass
+     *  false to return once the start is accepted, e.g. when starting many
+     *  machines and polling `ready()` yourself. */
+    waitUntilReady?: boolean;
+}
+/** Options for `Machine.resume`. */
+export interface ResumeOptions {
+    /** Wait for the guest to be ready before returning (default true). */
+    waitUntilReady?: boolean;
 }
 /** Which cache disk a machine starts from. */
 export interface CacheDiskRef {
@@ -528,6 +556,10 @@ export interface CacheDiskRef {
     version?: number;
     /** Absolute guest path to mount it at; the cache disk's own when omitted. */
     mountPath?: string;
+    /** On create, attach the cache unmounted as a slot: restoring a checkpoint
+     *  of the machine with `restoreCheckpoint(..., { cacheDisk })` mounts any
+     *  cache no larger than this one there, at this one's mount path. */
+    slot?: boolean;
 }
 /** Options for creating a cache disk. */
 export interface CreateCacheDiskOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smolmachines",
-  "version": "1.25.1",
+  "version": "1.26.1",
   "description": "Embed isolated microVM sandboxes directly in your code — no server to run.",
   "license": "Apache-2.0",
   "author": "smol-machines",
@@ -63,8 +63,8 @@
     "typescript": "^5.6.0"
   },
   "optionalDependencies": {
-    "smolmachines-darwin-arm64": "1.25.1",
-    "smolmachines-linux-x64-gnu": "1.25.1",
-    "smolmachines-linux-arm64-gnu": "1.25.1"
+    "smolmachines-darwin-arm64": "1.26.1",
+    "smolmachines-linux-x64-gnu": "1.26.1",
+    "smolmachines-linux-arm64-gnu": "1.26.1"
   }
 }