smolmachines 1.25.2 → 1.27.0

package/README.md

@@ -87,10 +87,32 @@ try {
 }
 ```
 
-For a local VM whose published service starts through `exec()`, set
-`waitForPorts: false` on creation. The SDK still waits for the guest agent,
-so `exec()` is safe; call `waitUntilReady()` once the service is listening.
-The default keeps waiting for all published ports. This option is local-only.
+Local machines also accept a saved Docker/OCI image archive or an unpacked rootfs
+as `image`. The SDK stages an archive once and reuses its content hash; a
+missing local path fails immediately with the path in the error instead of
+trying to pull it from a registry. Build your image first, then save it:
+
+```sh
+docker save my-agent:latest -o my-agent.tar
+```
+
+```ts
+const m = await Machine.create(
+  { image: './my-agent.tar', network: false },
+  { target: 'local' },
+);
+try {
+  console.log((await m.exec(['sh', '-c', 'pwd'])).stdout);
+} finally {
+  await m.delete();
+}
+```
+
+When a published service starts through `exec()` (local or cloud), set
+`waitForPorts: false` on creation. The SDK waits for the guest agent so
+`exec()` can start the listener; call `waitUntilReady()` once the service is
+listening. The default waits for all published ports. Select
+`{ target: 'cloud' }` to use the same flow on Smol Cloud.
 
 ```ts
 const m = await Machine.create(
@@ -109,10 +131,13 @@ try {
 }
 ```
 
-When reconnecting to clean up a local machine whose published service has
+When reconnecting to a running local machine whose published service has
 stopped, `Machine.connect(name, { target: 'local', waitForPorts: false })`
-attaches after the agent is ready, so `delete()` can run without a listener.
-The default continues waiting for all published ports.
+attaches after the agent is ready, without waiting for the listener. Cloud
+`connect()` normally attaches without waiting; with `waitForPorts: false`, it
+waits for a successful guest-agent command without requiring the port to be
+open. Connect without that flag to inspect or delete a stopped or paused cloud
+machine.
 
 To reach a service **inside** the VM, use the authenticated connect bridge —
 **no Cloudflare/localhost.run tunnel, no public exposure, no egress allow-list.**
@@ -215,6 +240,9 @@ Existing network connections may need to reconnect.
 - `machine.exec(command, opts?)` / `machine.run(image, command, opts?)` → `ExecResult`.
 - `machine.execStream(command, opts?)` → `AsyncGenerator<ExecEvent>`.
 - `machine.readFile(path)` / `machine.writeFile(path, data, mode?)`.
+- `machine.readFileStream(path)` yields `Uint8Array` chunks without buffering
+  the full Cloud download; stopping iteration cancels the response. Local
+  machines currently yield one buffered chunk.
 - `machine.pullImage(image)` / `machine.listImages()`.
 - `machine.branch(name, options?)` / `machine.branchBatch(options)`.
 - `machine.checkpoint(output, { store? })`, `Machine.restoreCheckpoint(...)`,

package/dist/assets.d.ts

@@ -1,17 +1,21 @@
 /** Auto-wiring for bundled native assets.
  *
- *  Points the engine at the package's bundled, signed boot helper and hypervisor
- *  libraries so the SDK works on a plain `node` with no manual env setup:
- *    - SMOLVM_BOOT_BINARY → bundled `smol-vmm` helper (handles `_boot-vm`; on
- *      macOS codesigned with `com.apple.security.hypervisor`, so the user's
- *      `node` needs no entitlement).
- *    - SMOLVM_LIB_DIR     → the dir holding libkrun/libkrunfw.
- *    - SMOLVM_AGENT_ROOTFS_TAR → bundled guest rootfs tarball (the engine
- *      extracts it on first use), so a plain `npm i` is fully self-contained.
+ *  Resolves the package's bundled, signed boot helper, hypervisor libraries and
+ *  guest rootfs so the SDK works on a plain `node` with no manual env setup:
+ *    - bootBinary     → bundled `smol-vmm` helper (handles `_boot-vm`; on macOS
+ *      codesigned with `com.apple.security.hypervisor`, so the user's `node`
+ *      needs no entitlement).
+ *    - libDir         → the dir holding libkrun/libkrunfw.
+ *    - agentRootfsTar → bundled guest rootfs tarball (the engine extracts it
+ *      on first use), so a plain `npm i` is fully self-contained.
  *
- *  A user-provided value always wins. Called by `native.ts` right before the
- *  addon loads — i.e. on first LOCAL use, never at import — so importing the
- *  SDK (e.g. for cloud-only use) leaves `process.env` untouched.
+ *  The resolved paths are handed to the engine in-process by
+ *  `configureRuntimeAssets` and are never written to `process.env`: a `smolvm`
+ *  CLI this program spawns must not inherit this package's helper (it exits
+ *  when its parent does) or its libraries. A user-provided SMOLVM_BOOT_BINARY,
+ *  SMOLVM_LIB_DIR or SMOLVM_AGENT_ROOTFS(_TAR) always wins. Called by
+ *  `native.ts` right before the addon loads — i.e. on first LOCAL use, never at
+ *  import.
  */
 /** The per-platform npm package that carries the native addon, boot helper,
  *  hypervisor libraries and guest rootfs for each supported

package/dist/assets.js

@@ -1,18 +1,22 @@
 "use strict";
 /** Auto-wiring for bundled native assets.
  *
- *  Points the engine at the package's bundled, signed boot helper and hypervisor
- *  libraries so the SDK works on a plain `node` with no manual env setup:
- *    - SMOLVM_BOOT_BINARY → bundled `smol-vmm` helper (handles `_boot-vm`; on
- *      macOS codesigned with `com.apple.security.hypervisor`, so the user's
- *      `node` needs no entitlement).
- *    - SMOLVM_LIB_DIR     → the dir holding libkrun/libkrunfw.
- *    - SMOLVM_AGENT_ROOTFS_TAR → bundled guest rootfs tarball (the engine
- *      extracts it on first use), so a plain `npm i` is fully self-contained.
+ *  Resolves the package's bundled, signed boot helper, hypervisor libraries and
+ *  guest rootfs so the SDK works on a plain `node` with no manual env setup:
+ *    - bootBinary     → bundled `smol-vmm` helper (handles `_boot-vm`; on macOS
+ *      codesigned with `com.apple.security.hypervisor`, so the user's `node`
+ *      needs no entitlement).
+ *    - libDir         → the dir holding libkrun/libkrunfw.
+ *    - agentRootfsTar → bundled guest rootfs tarball (the engine extracts it
+ *      on first use), so a plain `npm i` is fully self-contained.
  *
- *  A user-provided value always wins. Called by `native.ts` right before the
- *  addon loads — i.e. on first LOCAL use, never at import — so importing the
- *  SDK (e.g. for cloud-only use) leaves `process.env` untouched.
+ *  The resolved paths are handed to the engine in-process by
+ *  `configureRuntimeAssets` and are never written to `process.env`: a `smolvm`
+ *  CLI this program spawns must not inherit this package's helper (it exits
+ *  when its parent does) or its libraries. A user-provided SMOLVM_BOOT_BINARY,
+ *  SMOLVM_LIB_DIR or SMOLVM_AGENT_ROOTFS(_TAR) always wins. Called by
+ *  `native.ts` right before the addon loads — i.e. on first LOCAL use, never at
+ *  import.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PLATFORM_PACKAGES = void 0;
@@ -77,18 +81,18 @@ function wireBundledAssets() {
         if (!(0, node_fs_1.existsSync)(nativeDir))
             continue;
         const helper = (0, node_path_1.join)(nativeDir, helperName);
+        // Resolved paths are handed to the engine by `configureRuntimeAssets`, never
+        // written to `process.env`: a `smolvm` CLI this program spawns must not
+        // inherit this package's helper, libraries or rootfs.
         if (!assets.bootBinary && (0, node_fs_1.existsSync)(helper)) {
             assets.bootBinary = helper;
-            process.env.SMOLVM_BOOT_BINARY = helper;
         }
         if (!assets.libDir) {
             assets.libDir = nativeDir;
-            process.env.SMOLVM_LIB_DIR = nativeDir;
         }
         const rootfsTar = (0, node_path_1.join)(nativeDir, 'agent-rootfs.tar');
         if (!assets.agentRootfs && !assets.agentRootfsTar && (0, node_fs_1.existsSync)(rootfsTar)) {
             assets.agentRootfsTar = rootfsTar;
-            process.env.SMOLVM_AGENT_ROOTFS_TAR = rootfsTar;
         }
         break;
     }

package/dist/binding.d.ts

@@ -287,6 +287,11 @@ export declare class NapiMachine {
    * for a failed boot. Never throws.
    */
   static checkHost(): HostAvailability
+  /**
+   * Stage a local archive or rootfs directory before creating the machine.
+   * Large archives are hashed off the JavaScript event loop.
+   */
+  static prepareImage(image: string): Promise<string>
   /** Create a new machine. Does not start the VM yet — call `start()`. */
   constructor(config: MachineConfig)
   /**

package/dist/machine.d.ts

@@ -15,8 +15,8 @@ export declare class Machine {
     private constructor();
     /**
      * Create and start a machine. By default this waits for the guest agent and
-     * all published ports. On local machines, `waitForPorts: false` returns when
-     * the agent is ready so `exec()` can start a service on a published port.
+     * all published ports. `waitForPorts: false` returns when the agent is
+     * ready so `exec()` can start a service on a published port.
      * A cloud state of `"started"` alone means only that the VM process launched.
      *
      * @param config  machine configuration (a name is generated if omitted; `image`
@@ -29,11 +29,14 @@ export declare class Machine {
      * machine made elsewhere (another process, the console, the REST API).
      *  - local (default): re-opens a persisted machine by NAME, starting it if
      *    stopped — pairs with `Machine.create({ name, … }, …)` + `persistent`.
+     *    A paused machine stays paused; call `resume()` to restore its saved
+     *    execution before running commands.
      *    Set `conn.waitForPorts: false` to attach after agent readiness when a
      *    published service is not listening (for example, to delete it).
      *  - cloud: looks up the machine by id; throws if it doesn't exist.
-     *    This does not wait for readiness; call `waitUntilReady()` before `exec`,
-     *    using a connect endpoint, or expecting the workload to respond.
+     *    This does not wait for readiness by default. With `waitForPorts: false`,
+     *    it waits for the guest agent so `exec()` can start a published service.
+     *    Call `waitUntilReady()` before expecting the published service to respond.
      *
      * @param id    local machine name, or cloud machine id (`mach-…`)
      * @param conn  backend selection (local by default; cloud via `{ target: 'cloud', apiKey }` or `SMOL_CLOUD_TOKEN`)
@@ -136,6 +139,10 @@ export declare class Machine {
     execStream(command: string[], opts?: ExecOptions): AsyncGenerator<ExecEvent>;
     /** Read a file from the machine. */
     readFile(path: string): Promise<Buffer>;
+    /** Read a file in chunks without buffering the entire Cloud response.
+     * Local machines currently yield one buffered chunk from the native binding.
+     * Stopping iteration early cancels the Cloud HTTP download. */
+    readFileStream(path: string): AsyncGenerator<Uint8Array>;
     /** Write a file into the machine. */
     writeFile(path: string, data: string | Uint8Array, mode?: number): Promise<void>;
     /** Pull an OCI image into the machine's storage. (local) */

package/dist/machine.js

@@ -57,8 +57,8 @@ class Machine {
     }
     /**
      * Create and start a machine. By default this waits for the guest agent and
-     * all published ports. On local machines, `waitForPorts: false` returns when
-     * the agent is ready so `exec()` can start a service on a published port.
+     * all published ports. `waitForPorts: false` returns when the agent is
+     * ready so `exec()` can start a service on a published port.
      * A cloud state of `"started"` alone means only that the VM process launched.
      *
      * @param config  machine configuration (a name is generated if omitted; `image`
@@ -78,11 +78,14 @@ class Machine {
      * machine made elsewhere (another process, the console, the REST API).
      *  - local (default): re-opens a persisted machine by NAME, starting it if
      *    stopped — pairs with `Machine.create({ name, … }, …)` + `persistent`.
+     *    A paused machine stays paused; call `resume()` to restore its saved
+     *    execution before running commands.
      *    Set `conn.waitForPorts: false` to attach after agent readiness when a
      *    published service is not listening (for example, to delete it).
      *  - cloud: looks up the machine by id; throws if it doesn't exist.
-     *    This does not wait for readiness; call `waitUntilReady()` before `exec`,
-     *    using a connect endpoint, or expecting the workload to respond.
+     *    This does not wait for readiness by default. With `waitForPorts: false`,
+     *    it waits for the guest agent so `exec()` can start a published service.
+     *    Call `waitUntilReady()` before expecting the published service to respond.
      *
      * @param id    local machine name, or cloud machine id (`mach-…`)
      * @param conn  backend selection (local by default; cloud via `{ target: 'cloud', apiKey }` or `SMOL_CLOUD_TOKEN`)
@@ -262,6 +265,12 @@ class Machine {
     readFile(path) {
         return this.transport.readFile(path);
     }
+    /** Read a file in chunks without buffering the entire Cloud response.
+     * Local machines currently yield one buffered chunk from the native binding.
+     * Stopping iteration early cancels the Cloud HTTP download. */
+    readFileStream(path) {
+        return this.transport.readFileStream(path);
+    }
     /** Write a file into the machine. */
     writeFile(path, data, mode) {
         const buf = typeof data === "string" ? Buffer.from(data) : Buffer.from(data);

package/dist/native.d.ts

@@ -150,6 +150,7 @@ export interface NapiMachine {
 }
 export interface NapiMachineCtor {
     new (config: NativeMachineConfig): NapiMachine;
+    prepareImage(image: string): Promise<string>;
     connect(name: string, interceptorAddress?: string, interceptorToken?: string): NapiMachine;
     list(): Promise<NativeMachineSummary[]>;
     restoreCheckpoint(name: string, artifact: string, keepIdentity?: boolean): NapiMachine;

package/dist/transport.d.ts

@@ -41,6 +41,7 @@ export interface Transport {
     run(image: string, command: string[], opts?: ExecOptions): Promise<RawExec>;
     execStream(command: string[], opts?: ExecOptions): AsyncGenerator<ExecEvent>;
     readFile(path: string): Promise<Buffer>;
+    readFileStream(path: string): AsyncGenerator<Uint8Array>;
     writeFile(path: string, data: Buffer, mode?: number): Promise<void>;
     pullImage(image: string): Promise<ImageInfo>;
     listImages(): Promise<ImageInfo[]>;
@@ -122,6 +123,13 @@ interface CloudConn {
     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;
@@ -468,6 +471,11 @@ class LocalTransport {
             throw (0, errors_1.wrapNativeError)(e);
         }
     }
+    // The native local binding currently returns a Buffer; keep the same API
+    // across targets until native streaming is available.
+    async *readFileStream(path) {
+        yield await this.readFile(path);
+    }
     async writeFile(path, data, mode) {
         try {
             await this.inner.writeFile(path, data, mode === undefined ? undefined : { mode });
@@ -699,6 +707,23 @@ function cloudConnOf(conn, baseUrl, apiKey) {
 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.
@@ -795,6 +820,8 @@ async function cloudFetch(conn, method, path, opts = {}) {
                 ? "UNAUTHORIZED"
                 : "SMOLVM_ERROR", `cloud ${method} ${path} → ${res.status}${text ? `: ${text}` : ""}${rid ? ` [request id: ${rid}]` : ""}`);
     }
+    if (opts.accept === "response")
+        return res;
     if (opts.accept === "text")
         return (await res.text());
     if (opts.accept === "bytes") {
@@ -816,11 +843,11 @@ async function cloudFetch(conn, method, path, opts = {}) {
  *  caller keeps polling until this passes or the deadline hits. */
 async function agentReachable(conn, id) {
     try {
-        await cloudFetch(conn, "POST", `/v1/machines/${id}/exec`, {
+        const result = await cloudFetch(conn, "POST", `/v1/machines/${id}/exec`, {
             json: { command: ["sh", "-c", "true"] },
             timeoutMs: 15_000,
         });
-        return true;
+        return result?.exitCode === 0;
     }
     catch {
         return false;
@@ -835,8 +862,10 @@ async function agentReachable(conn, id) {
  *  `started` is NOT yet usable: the guest is still booting, and acting then is
  *  the classic teardown race (works on a slow cold start, times out on a warm
  *  one). Older control planes omit `ready`; there we fall back to the coarse
- *  `started`/`running` state so this never hangs against them. */
-async function waitForReady(conn, id, timeoutMs = 120_000, intervalMs = 1_000) {
+ *  `started`/`running` state so this never hangs against them.
+ *  With `waitForPorts: false`, probe the agent even if ports are published:
+ *  the caller must be able to exec the service before any port can open. */
+async function waitForReady(conn, id, timeoutMs = 120_000, intervalMs = 1_000, waitForPorts = true) {
     const start = Date.now();
     const deadline = start + timeoutMs;
     for (;;) {
@@ -862,8 +891,15 @@ async function waitForReady(conn, id, timeoutMs = 120_000, intervalMs = 1_000) {
         if (state === "stopped" || state === "deleted") {
             throw new errors_1.SmolError("SMOLVM_ERROR", `machine ${id} entered ${state} before becoming ready`);
         }
+        // With deferred ports, even `started` and legacy servers' absent `ready`
+        // are insufficient: only a successful in-guest exec proves agent readiness.
+        if (!waitForPorts && (state === "started" || state === "running")) {
+            if (await agentReachable(conn, id))
+                return;
+        }
         // Back-compat: `ready` absent entirely → old server, gate on state.
-        if (m &&
+        if (waitForPorts &&
+            m &&
             m.ready === undefined &&
             (state === "started" || state === "running"))
             return;
@@ -873,7 +909,8 @@ async function waitForReady(conn, id, timeoutMs = 120_000, intervalMs = 1_000) {
         // into). After a grace (so `ready` can flip first and this never preempts a
         // machine legitimately about to become ready), confirm the guest agent is
         // reachable directly (a trivial exec) and treat that as ready.
-        if ((state === "started" || state === "running") &&
+        if (waitForPorts &&
+            (state === "started" || state === "running") &&
             !m?.ports?.length &&
             Date.now() - start >= NO_PORT_READY_PROBE_GRACE_MS &&
             (await agentReachable(conn, id)))
@@ -1132,11 +1169,59 @@ 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 *readFileStream(path) {
+        const route = `/v1/machines/${this.id}/files/${encodePath(path)}`;
+        const res = await cloudFetch(this.conn, "GET", route, {
+            accept: "response",
+            timeoutMs: transferTimeoutMs(exports.CLOUD_MAX_FILE_BYTES),
+        });
+        // A caller-supplied byte reader may transform the response. Honor it just
+        // as readFile does, even when the injected fetch exposes a body stream.
+        if (this.conn.readResponseBytes) {
+            const bytes = await this.conn.readResponseBytes(res);
+            if (bytes.length > 0)
+                yield bytes;
+            return;
+        }
+        if (!res.body)
+            return;
+        const reader = res.body.getReader();
+        try {
+            for (;;) {
+                let timer;
+                let chunk;
+                try {
+                    chunk = await Promise.race([
+                        reader.read(),
+                        new Promise((_, reject) => {
+                            timer = setTimeout(() => reject(new errors_1.SmolError("TIMEOUT", `cloud GET ${route} stalled for ${CLOUD_TIMEOUT_MS}ms`)), CLOUD_TIMEOUT_MS);
+                        }),
+                    ]);
+                }
+                finally {
+                    if (timer !== undefined)
+                        clearTimeout(timer);
+                }
+                if (chunk.done)
+                    return;
+                if (chunk.value.length > 0)
+                    yield chunk.value;
+            }
+        }
+        finally {
+            // `break`, a thrown error, or a stalled read must close the HTTP body.
+            await reader.cancel().catch(() => { });
+            reader.releaseLock();
+        }
+    }
     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.
@@ -1458,8 +1543,6 @@ async function makeTransport(config, conn) {
         // run the workload as the image's default user.
         if (config.user !== undefined)
             throw new errors_1.NotSupportedError("user is local-only.");
-        if (config.waitForPorts === false || conn.waitForPorts === false)
-            throw new errors_1.NotSupportedError("waitForPorts: false is local-only.");
         // Cloud is settled: NOW the CLI's stored login may supply the credential
         // and endpoint, which is the reuse `smol auth login` promises.
         const { apiKey: cliKey, endpoint: cliUrl } = cliSession(conn.target);
@@ -1563,7 +1646,7 @@ async function makeTransport(config, conn) {
                 startError = e instanceof Error ? e.message : String(e);
             }
             try {
-                await waitForReady(cloudConn, id);
+                await waitForReady(cloudConn, id, 120_000, 1_000, (config.waitForPorts ?? conn.waitForPorts) !== false);
             }
             catch (e) {
                 if (startError !== undefined && e instanceof errors_1.SmolError)
@@ -1589,6 +1672,9 @@ async function makeTransport(config, conn) {
         // Validate the config before loading the engine, so a config the local
         // target cannot honour fails the same way whether or not it is installed.
         const nativeConfig = toNativeConfig(name, config);
+        if (nativeConfig.image) {
+            nativeConfig.image = await (0, native_1.getNapiMachine)().prepareImage(nativeConfig.image);
+        }
         const inner = new ((0, native_1.getNapiMachine)())(nativeConfig);
         // A detached machine is nobody's to stop on a signal — it was created to
         // survive this process — and its branches inherit that.
@@ -1715,9 +1801,10 @@ async function connectTransport(id, conn) {
             const transport = new LocalTransport(conn.egressInterceptor
                 ? (0, native_1.getNapiMachine)().connect(id, conn.egressInterceptor.address, conn.egressInterceptor.token)
                 : (0, native_1.getNapiMachine)().connect(id), false, conn.egressInterceptor, conn.handleSignals ?? true);
-            // A frozen checkpoint is intentionally not agent-ready; it remains
-            // connectable so callers can fork its retained snapshot.
-            if ((await transport.state()) !== "frozen" && conn.waitForPorts !== false) {
+            // Frozen and durably paused machines are intentionally not agent-ready.
+            // A paused machine must be resumed explicitly before it can serve work.
+            const state = await transport.state();
+            if (state !== "frozen" && state !== "paused" && state !== "pausing" && conn.waitForPorts !== false) {
                 await transport.waitUntilReady();
             }
             return transport;
@@ -1728,8 +1815,6 @@ async function connectTransport(id, conn) {
     }
     if (conn.egressInterceptor)
         throw new errors_1.NotSupportedError("egressInterceptor is local-only.");
-    if (conn.waitForPorts === false)
-        throw new errors_1.NotSupportedError("waitForPorts: false is local-only.");
     // As in makeTransport: the CLI-login fallback applies only once the cloud
     // target is already selected.
     const { apiKey: cliKey, endpoint: cliUrl } = cliSession(conn.target);
@@ -1760,7 +1845,11 @@ async function connectTransport(id, conn) {
             throw e;
         m = hit;
     }
-    return new CloudTransport(cloudConn, m.name ?? id, m.id ?? id);
+    const resolvedId = m.id ?? id;
+    if (conn.waitForPorts === false && m.state !== "frozen") {
+        await waitForReady(cloudConn, resolvedId, 120_000, 1_000, false);
+    }
+    return new CloudTransport(cloudConn, m.name ?? id, resolvedId);
 }
 /** Restore a durable cloud checkpoint into a new machine, then return only once
  * the restored guest is ready. */

package/dist/types.d.ts

@@ -207,11 +207,11 @@ export interface MachineConfig {
      *  allocates the host port; readiness includes that published port accepting
      *  connections. */
     ports?: PortSpec[];
-    /** Locally, return from `Machine.create()` after the guest agent is ready,
-     *  even if a published port is not accepting connections yet. Use this when
-     *  `exec()` starts the service: the default port wait would deadlock before
-     *  `exec()` can run. Call `machine.waitUntilReady()` after starting it.
-     *  Default true; false is local-only and rejected on cloud. */
+    /** Return from `Machine.create()` after the guest agent is ready, even if a
+     *  published port is not accepting connections yet. Use this when `exec()`
+     *  starts the service: the default port wait would deadlock before `exec()`
+     *  can run. Call `machine.waitUntilReady()` after starting it.
+     *  Default true. On cloud, false probes in-guest execution before returning. */
     waitForPorts?: boolean;
     /** Resource allocation. */
     resources?: ResourceSpec;
@@ -497,11 +497,10 @@ export interface PortableCheckpointInfo {
 }
 /** Selects and configures the backend. Local (embedded) is the default. */
 export interface ConnectOptions {
-    /** Locally, allow `Machine.connect()` to return after the guest agent is
-     *  ready even when a published port is not serving. Useful when reconnecting
-     *  to stop or delete a worker whose listener has exited. Default true;
-     *  false is local-only and rejected on cloud. For `create`, put this setting
-     *  on `MachineConfig` instead. */
+    /** On local machines, allow `Machine.connect()` to return without waiting
+     *  for published ports. On cloud, false waits for successful in-guest exec
+     *  without requiring a published listener; the default connection only
+     *  attaches to the existing machine. For `create`, set this on MachineConfig. */
     waitForPorts?: boolean;
     /** Binding for a stopped local machine that requires intercepted egress. */
     egressInterceptor?: EgressInterceptor;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smolmachines",
-  "version": "1.25.2",
+  "version": "1.27.0",
   "description": "Embed isolated microVM sandboxes directly in your code — no server to run.",
   "license": "Apache-2.0",
   "author": "smol-machines",
@@ -51,8 +51,9 @@
     "test:e2e": "napi build --platform --js binding.js --dts binding.d.ts && tsx test/e2e.ts",
     "test:staged": "tsx test/staged-mount-e2e.ts",
     "test:agent-ready": "tsx test/local-agent-ready.ts",
+    "test:paused-connect": "tsx test/local-paused-connect.ts",
     "gen:openapi": "bash scripts/gen-openapi.sh",
-    "test:cloud": "tsx test/cloud-mock.ts",
+    "test:cloud": "tsx test/cloud-mock.ts && tsx test/cloud-deferred-ports.ts",
     "test:unit": "tsx test/unit.ts"
   },
   "devDependencies": {
@@ -63,8 +64,8 @@
     "typescript": "^5.6.0"
   },
   "optionalDependencies": {
-    "smolmachines-darwin-arm64": "1.25.2",
-    "smolmachines-linux-x64-gnu": "1.25.2",
-    "smolmachines-linux-arm64-gnu": "1.25.2"
+    "smolmachines-darwin-arm64": "1.27.0",
+    "smolmachines-linux-x64-gnu": "1.27.0",
+    "smolmachines-linux-arm64-gnu": "1.27.0"
   }
 }