smolmachines 1.27.3 → 1.29.0

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2024-2026 smolvm contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -205,10 +205,14 @@ vLLM's unrestricted adapter loader.
 ```ts
 import { Machine } from 'smolmachines';
 
-const m = await Machine.create({ resources: { cpus: 2, memoryMb: 1024 } });
+// A machine of an image. The image is pulled once; later machines of the same
+// image start from it in about a second.
+const m = await Machine.create({
+  image: 'python:3.12',
+  resources: { cpus: 2, memoryMb: 1024, network: true },
+});
 try {
-  // Run a command in a container image
-  const res = await m.run('python:3.12', ['python', '-c', 'print(2 ** 10)']);
+  const res = await m.exec(['python', '-c', 'print(2 ** 10)']);
   res.assertSuccess();
   console.log(res.stdout); // "1024\n"
 

package/dist/assets.js

@@ -90,7 +90,9 @@ function wireBundledAssets() {
         if (!assets.libDir) {
             assets.libDir = nativeDir;
         }
-        const rootfsTar = (0, node_path_1.join)(nativeDir, 'agent-rootfs.tar');
+        // Shipped zstd-compressed; an older or locally built package has the plain tar.
+        const compressedRootfs = (0, node_path_1.join)(nativeDir, 'agent-rootfs.tar.zst');
+        const rootfsTar = (0, node_fs_1.existsSync)(compressedRootfs) ? compressedRootfs : (0, node_path_1.join)(nativeDir, 'agent-rootfs.tar');
         if (!assets.agentRootfs && !assets.agentRootfsTar && (0, node_fs_1.existsSync)(rootfsTar)) {
             assets.agentRootfsTar = rootfsTar;
         }

package/dist/binding.d.ts

@@ -77,6 +77,10 @@ export interface MachineSummary {
   branchable: boolean
   /** Creation time, seconds since the Unix epoch. */
   createdAt: number
+  /** CPU, memory and disk sizes, readable whether or not it runs. */
+  resources: MachineSizes
+  /** Published ports, readable whether or not it runs. */
+  ports: Array<PublishedPort>
 }
 /** Whether this host can run local machines, from the engine's own checks. */
 export interface HostAvailability {
@@ -214,6 +218,45 @@ export interface ExecOptions {
    * machines only; a bare VM rejects it rather than run as root.
    */
   user?: string
+  /**
+   * Text written to the command's stdin, which is then closed. It is
+   * passed over the agent connection and never written to the guest disk.
+   */
+  stdin?: string
+}
+/** How a stop or delete treats work still running on the machine. */
+export interface StopOptions {
+  /**
+   * Wait up to this many seconds for running commands and file transfers
+   * to finish first. What is still running then fails with code
+   * `INTERRUPTED`. Default: stop at once.
+   */
+  drainSecs?: number
+  /**
+   * Seconds the workload gets to exit after its stop signal, instead of
+   * the machine's stop timeout; 0 kills it at once. Stop only.
+   */
+  timeoutSecs?: number
+}
+/** CPU, memory and disk sizes of a machine. */
+export interface MachineSizes {
+  /** vCPUs. */
+  cpus: number
+  /** Memory in MiB. */
+  memoryMib: number
+  /** Storage disk in GiB. */
+  storageGib: number
+  /** Container overlay disk in GiB. */
+  overlayGib: number
+}
+/** One published port of a machine. */
+export interface PublishedPort {
+  /** Host port. */
+  host: number
+  /** Guest port. */
+  guest: number
+  /** `"tcp"` or `"udp"`. */
+  protocol: string
 }
 /** Options for writing a file into the VM. */
 export interface FileWriteOptions {
@@ -297,9 +340,21 @@ export declare class NapiMachine {
   /**
    * Attach to an existing machine by name, starting it if stopped
    * (start-or-reconnect). Lets a persisted machine be re-opened in a new
-   * process — backs the SDK's local `Machine.connect()`.
+   * process — backs the SDK's local `Machine.connect()`. The boot runs off
+   * the JavaScript thread, so the event loop keeps serving while it waits.
    */
-  static connect(name: string, interceptorAddress?: string | undefined | null, interceptorToken?: string | undefined | null): NapiMachine
+  static connect(name: string, interceptorAddress?: string | undefined | null, interceptorToken?: string | undefined | null): Promise<NapiMachine>
+  /**
+   * Open a handle to an existing machine without starting or connecting to
+   * it, to read its state, stop, resize or delete it. Fails when no machine
+   * of that name exists.
+   */
+  static open(name: string): NapiMachine
+  /**
+   * Delete a machine by name, whether it runs or not, without booting it.
+   * A machine that does not exist is already deleted.
+   */
+  static deleteByName(name: string, options?: StopOptions | undefined | null): Promise<void>
   /**
    * Every machine in this host's shared machine database, in name order.
    * The database is shared with the CLI and every other embedder on the
@@ -328,7 +383,7 @@ export declare class NapiMachine {
   /**
    * Start a command and return a live `ExecStream` of its output events. A
    * worker thread drives the engine's `exec_streaming_with` and feeds an mpsc
-   * channel the stream drains incrementally (no buffering).
+   * channel the stream drains incrementally (apart from partial UTF-8).
    */
   execStream(command: Array<string>, options?: ExecOptions | undefined | null): ExecStream
   /** Get the child PID if the VM is running. */
@@ -391,18 +446,45 @@ export declare class NapiMachine {
   execStreaming(command: Array<string>, options?: ExecOptions | undefined | null): Promise<Array<ExecStreamEvent>>
   /** Copy guest-local staged mounts back to their host sources. */
   sync(): Promise<void>
-  /** Stop the machine VM gracefully. */
-  stop(): Promise<void>
+  /**
+   * Stop the machine VM gracefully: its workload gets its stop signal and
+   * stop timeout first. A command or file transfer still running fails
+   * with code `INTERRUPTED` unless `drainSecs` lets it finish.
+   */
+  stop(options?: StopOptions | undefined | null): Promise<void>
   /** Save execution durably and stop the machine. */
   pause(): Promise<void>
   resume(): Promise<void>
-  /** Stop the machine and clean up all storage (disks, config). */
-  delete(): Promise<void>
+  /**
+   * The machine's published ports, read from its record whether or not it
+   * runs.
+   */
+  publishedPorts(): Array<PublishedPort>
+  /**
+   * Make `ports` the machine's published ports. A running machine changes
+   * its TCP ports now; UDP ports, or any port of a machine not on
+   * virtio-net, change only while it is stopped.
+   */
+  setPorts(ports: Array<PublishedPort>): Promise<void>
+  /**
+   * Pack this stopped machine into a `.smolmachine` at `output`; returns
+   * the artifact's path.
+   */
+  pack(output: string): Promise<string>
+  /** Create the stopped machine `name` from a `.smolmachine` artifact. */
+  static createFromPack(name: string, pack: string): Promise<NapiMachine>
+  /**
+   * Stop the machine and clean up all storage (disks, config). A command or
+   * file transfer still running fails with code `INTERRUPTED` unless
+   * `drainSecs` lets it finish.
+   */
+  delete(options?: StopOptions | undefined | null): Promise<void>
 }
 /**
  * A live, incremental exec stream. `next()` resolves with the next event as it
  * arrives (off the libuv loop via spawn_blocking), or `null` once the command
- * exits and the channel closes. Mirrors the Python SDK's ExecStream iterator.
+ * exits and the channel closes. Only an incomplete UTF-8 code point is held
+ * across events. Mirrors the Python SDK's ExecStream iterator.
  */
 export declare class ExecStream {
   next(): Promise<ExecStreamEvent | null>

package/dist/errors.d.ts

@@ -15,8 +15,28 @@ export interface CloudErrorDetail {
     /** How long the server asked callers to wait before retrying (ms). */
     retryAfterMs?: number | undefined;
 }
+/** The stable codes a `SmolError` carries, to branch on instead of matching
+ *  message text (which may change). Unknown codes from a newer engine or
+ *  control plane still type-check as plain strings.
+ *
+ *  - `NOT_FOUND`: no such machine, file (`readFile` of a missing path),
+ *    image or checkpoint.
+ *  - `INTERRUPTED`: a `stop()` or `delete()` cut off this command or file
+ *    transfer (local). `MACHINE_INTERRUPTED`: the same, on the cloud.
+ *  - `CONFLICT`: the machine's state does not allow it now (it is being
+ *    stopped or deleted, it has dependent branches, ...). `INVALID_STATE`:
+ *    the same, from an older engine path.
+ *  - `INVALID_CONFIG`: a usage error in the arguments. `CONFIG_ERROR`: the
+ *    engine refused a configuration value. `NOT_SUPPORTED`: not on this
+ *    target.
+ *  - `KVM_UNAVAILABLE`, `HYPERVISOR_UNAVAILABLE`: this host cannot run
+ *    machines. `STORAGE_ERROR`, `MOUNT_ERROR`: disk or mount failures.
+ *  - `COMMAND_FAILED`: a command exited non-zero (`assertSuccess()`).
+ *  - `TIMEOUT`, `CONNECTION`, `UNAUTHORIZED`: cloud transport failures.
+ *  - `SMOLVM_ERROR`: anything not classified above. */
+export type SmolErrorCode = "NOT_FOUND" | "INTERRUPTED" | "MACHINE_INTERRUPTED" | "CONFLICT" | "INVALID_STATE" | "FORBIDDEN" | "INVALID_CONFIG" | "CONFIG_ERROR" | "NOT_SUPPORTED" | "KVM_UNAVAILABLE" | "HYPERVISOR_UNAVAILABLE" | "STORAGE_ERROR" | "MOUNT_ERROR" | "COMMAND_FAILED" | "TIMEOUT" | "CONNECTION" | "UNAUTHORIZED" | "SMOLVM_ERROR" | (string & {});
 export declare class SmolError extends Error {
-    readonly code: string;
+    readonly code: SmolErrorCode;
     /** HTTP status, for an error the cloud API returned. */
     readonly status?: number | undefined;
     /** The server's stable problem code, for an error the cloud API returned. */
@@ -27,7 +47,7 @@ export declare class SmolError extends Error {
     readonly retryable: boolean;
     /** How long the server asked callers to wait before retrying (ms). */
     readonly retryAfterMs?: number | undefined;
-    constructor(code: string, message: string, detail?: CloudErrorDetail);
+    constructor(code: SmolErrorCode, message: string, detail?: CloudErrorDetail);
 }
 /** The active backend can't serve this operation (e.g. volumes on local). */
 export declare class NotSupportedError extends SmolError {

package/dist/index.d.ts

@@ -20,6 +20,7 @@ export { Machine, Episode, CacheDisk, Job } from './machine';
 export { RolloutClient, RolloutError, adapterSha256 } from './rollout';
 export type { BuildRolloutJobOptions, EnsureRolloutExecutorOptions, RolloutBatchItem, RolloutClientOptions, RolloutCompletion, RolloutExecutorInfo, RolloutGenerateResponse, RolloutJob, RolloutPolicyInfo, RolloutPrompt, RolloutSampling, } from './rollout';
 export { SmolError, NotSupportedError, InvalidConfigError, ExecutionError } from './errors';
+export type { SmolErrorCode } 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, JobInfo, JobOptions, JobOutput, JobOutputOptions, JobState, JobWaitOptions, ExecResult, MachineUsageReport, ShareLink, PortableCheckpointInfo, MachineUsageTotals, MachineCostBreakdown, ImageInfo, MachineSummary, ListOptions, ExecEvent, ConnectOptions, EgressInterceptor, StartOptions, ResumeOptions, 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, JobInfo, JobOptions, JobOutput, JobOutputOptions, JobState, JobWaitOptions, ExecResult, MachineUsageReport, ShareLink, PortableCheckpointInfo, MachineUsageTotals, MachineCostBreakdown, ImageInfo, MachineSummary, MachineSizes, PublishedPort, StopOptions, 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, JobInfo, JobOptions, JobOutput, JobOutputOptions, JobWaitOptions, ListOptions, MachineConfig, MachineSummary, NetworkPolicy, RestoreCheckpointOptions, StartOptions, ResumeOptions, 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, JobInfo, JobOptions, JobOutput, JobOutputOptions, JobWaitOptions, ListOptions, MachineConfig, MachineSummary, NetworkPolicy, RestoreCheckpointOptions, StartOptions, ResumeOptions, MachineUsageReport, ShareLink, PortableCheckpointInfo, PortEndpoint, PortSpec, PublishedPort, StopOptions, WaitReadyOptions } from "./types";
 export declare class Machine {
     private readonly transport;
     private constructor();
@@ -42,6 +42,22 @@ export declare class Machine {
      * @param conn  backend selection (local by default; cloud via `{ target: 'cloud', apiKey }` or `SMOL_CLOUD_TOKEN`)
      */
     static connect(id: string, conn?: ConnectOptions): Promise<Machine>;
+    /**
+     * Open a handle to an EXISTING machine without starting it or waiting for
+     * it — to describe, stop, resize or delete it, including one that can no
+     * longer boot (its image is gone, the host lost KVM). `state()` reports
+     * `"stopped"` for a stopped machine. Call `start()` to boot it.
+     *  - local: by name; rejects with code `NOT_FOUND` when none exists.
+     *  - cloud: by id or name, as `connect`.
+     */
+    static open(id: string, conn?: ConnectOptions): Promise<Machine>;
+    /**
+     * Delete a machine by name (cloud: id or name) without a handle and without
+     * booting it, whether it runs or not. Deleting one that does not exist
+     * succeeds. `drainSecs` lets running commands and transfers finish first
+     * (local).
+     */
+    static delete(id: string, conn?: ConnectOptions, opts?: Pick<StopOptions, "drainSecs">): Promise<void>;
     /**
      * List every machine the target knows about — including ones created by
      * other processes, or by this one before it last restarted. Locally that is
@@ -170,8 +186,43 @@ export declare class Machine {
      *  resumes saved memory (restored or paused) keeps its network backend, so a
      *  policy that would need a different one is refused. (local) */
     setNetworkPolicy(policy: NetworkPolicy): Promise<void>;
-    /** Stop the machine. */
-    stop(): Promise<void>;
+    /** The machine's published ports, whether or not it runs. On the cloud each
+     *  host port is the node's, and a port not placed yet reports host 0. */
+    ports(): Promise<PublishedPort[]>;
+    /**
+     * Publish a guest port on the host — on a running machine too, without a
+     * restart. Without `host`, a free host port is picked. Returns the mapping
+     * now in effect. A running machine takes a TCP port now; a UDP port, or a
+     * machine not on virtio-net networking, needs it stopped. On the cloud the
+     * machine's node picks the host port (`host` is ignored) and ports are TCP;
+     * reach the port with `connect` or the machine's URL.
+     */
+    publish(port: {
+        guest: number;
+        host?: number;
+        protocol?: "tcp" | "udp";
+    }): Promise<PublishedPort>;
+    /**
+     * Stop publishing a port, matched by `guest` port (every host port
+     * forwarding to it) or by `host` port. Connections already open carry on.
+     */
+    unpublish(port: {
+        guest?: number;
+        host?: number;
+        protocol?: "tcp" | "udp";
+    }): Promise<void>;
+    /**
+     * Pack this stopped machine into a `.smolmachine` at `path`: its disks and
+     * configuration in one artifact that stays on this host. Create machines
+     * from it with `Machine.create({ image: path })`. Returns the artifact's
+     * path. (local)
+     */
+    pack(path: string): Promise<string>;
+    /** Stop the machine. Its workload is sent its stop signal and given its
+     *  stop timeout to save state and exit first. A command or file transfer
+     *  still running rejects with code `INTERRUPTED` unless `drainSecs` lets it
+     *  finish; new ones are refused while the stop runs. */
+    stop(opts?: StopOptions): Promise<void>;
     /** Save RAM and disk durably, then stop at that execution boundary. */
     pause(): Promise<void>;
     /** Resume saved execution in this machine. */
@@ -183,7 +234,7 @@ export declare class Machine {
      *  `{ includeUsage: true }` to also get the fully settled usage + cost back
      *  in one call — the control plane takes a final metering sample before
      *  teardown, so nothing accrues after the returned report. */
-    delete(): Promise<void>;
+    delete(opts?: Pick<StopOptions, "drainSecs">): Promise<void>;
     delete(opts: {
         includeUsage: true;
     }): Promise<MachineUsageReport>;
@@ -200,6 +251,16 @@ export declare class Machine {
     /** Revoke this machine's anonymous share link (cloud target). The existing
      *  URL immediately stops granting access. */
     unshare(): Promise<void>;
+    /** A URL for each published port that reaches it with no login (cloud
+     *  target), keyed by guest port: for a client that cannot send an API key,
+     *  such as a sandbox framework calling its tunnel URLs. Anyone holding a link
+     *  reaches the port, so treat it as a credential. The machine keeps one
+     *  token, so calling again returns the same links; a port published later
+     *  appears on the next call. {@link revokePortLinks} revokes them. */
+    portLinks(): Promise<Record<number, string>>;
+    /** Revoke this machine's port links (cloud target): every link stops working
+     *  at once, and the next {@link portLinks} issues new ones. */
+    revokePortLinks(): Promise<void>;
     /** Publish this machine's cache disk, the version it started from plus
      *  everything it wrote, as its cache disk's next version (cloud target).
      *  Stop the machine first: a running machine is still writing it. */

package/dist/machine.js

@@ -24,10 +24,23 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CacheDisk = exports.Episode = exports.Job = exports.Machine = void 0;
 const node_crypto_1 = require("node:crypto");
 const node_path_1 = require("node:path");
+const node_net_1 = require("node:net");
 const errors_1 = require("./errors");
 const native_1 = require("./native");
 const availability_1 = require("./availability");
 const transport_1 = require("./transport");
+/** A host port free right now on loopback, for a publish that names none. */
+function freeHostPort() {
+    return new Promise((resolve, reject) => {
+        const server = (0, node_net_1.createServer)();
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            const port = typeof address === "object" && address ? address.port : 0;
+            server.close(() => (port ? resolve(port) : reject(new Error("no free port"))));
+        });
+    });
+}
 function makeExecResult(r) {
     const success = r.exitCode === 0;
     return {
@@ -93,6 +106,26 @@ class Machine {
     static async connect(id, conn = {}) {
         return new Machine(await (0, transport_1.connectTransport)(id, conn));
     }
+    /**
+     * Open a handle to an EXISTING machine without starting it or waiting for
+     * it — to describe, stop, resize or delete it, including one that can no
+     * longer boot (its image is gone, the host lost KVM). `state()` reports
+     * `"stopped"` for a stopped machine. Call `start()` to boot it.
+     *  - local: by name; rejects with code `NOT_FOUND` when none exists.
+     *  - cloud: by id or name, as `connect`.
+     */
+    static async open(id, conn = {}) {
+        return new Machine(await (0, transport_1.openTransport)(id, conn));
+    }
+    /**
+     * Delete a machine by name (cloud: id or name) without a handle and without
+     * booting it, whether it runs or not. Deleting one that does not exist
+     * succeeds. `drainSecs` lets running commands and transfers finish first
+     * (local).
+     */
+    static async delete(id, conn = {}, opts) {
+        return (0, transport_1.deleteMachine)(id, conn, opts);
+    }
     /**
      * List every machine the target knows about — including ones created by
      * other processes, or by this one before it last restarted. Locally that is
@@ -322,9 +355,62 @@ class Machine {
     setNetworkPolicy(policy) {
         return this.transport.setNetworkPolicy(policy);
     }
-    /** Stop the machine. */
-    stop() {
-        return this.transport.stop();
+    /** The machine's published ports, whether or not it runs. On the cloud each
+     *  host port is the node's, and a port not placed yet reports host 0. */
+    ports() {
+        return this.transport.ports();
+    }
+    /**
+     * Publish a guest port on the host — on a running machine too, without a
+     * restart. Without `host`, a free host port is picked. Returns the mapping
+     * now in effect. A running machine takes a TCP port now; a UDP port, or a
+     * machine not on virtio-net networking, needs it stopped. On the cloud the
+     * machine's node picks the host port (`host` is ignored) and ports are TCP;
+     * reach the port with `connect` or the machine's URL.
+     */
+    async publish(port) {
+        const protocol = port.protocol ?? "tcp";
+        const host = port.host ?? (await freeHostPort());
+        const current = await this.transport.ports();
+        const mapping = { host, guest: port.guest, protocol };
+        const next = current.filter((p) => !(p.host === host && p.protocol === protocol));
+        await this.transport.setPorts([...next, mapping]);
+        // Report what took effect: on the cloud the node chose the host port.
+        const now = await this.transport.ports();
+        const same = (p) => p.guest === port.guest && p.protocol === protocol;
+        return now.find((p) => same(p) && p.host === host) ?? now.find(same) ?? mapping;
+    }
+    /**
+     * Stop publishing a port, matched by `guest` port (every host port
+     * forwarding to it) or by `host` port. Connections already open carry on.
+     */
+    async unpublish(port) {
+        if (port.guest === undefined && port.host === undefined) {
+            throw new errors_1.InvalidConfigError("unpublish needs a guest or a host port.");
+        }
+        const protocol = port.protocol ?? "tcp";
+        const current = await this.transport.ports();
+        const next = current.filter((p) => p.protocol !== protocol ||
+            (port.guest !== undefined && p.guest !== port.guest) ||
+            (port.host !== undefined && p.host !== port.host));
+        if (next.length !== current.length)
+            await this.transport.setPorts(next);
+    }
+    /**
+     * Pack this stopped machine into a `.smolmachine` at `path`: its disks and
+     * configuration in one artifact that stays on this host. Create machines
+     * from it with `Machine.create({ image: path })`. Returns the artifact's
+     * path. (local)
+     */
+    pack(path) {
+        return this.transport.pack(path);
+    }
+    /** Stop the machine. Its workload is sent its stop signal and given its
+     *  stop timeout to save state and exit first. A command or file transfer
+     *  still running rejects with code `INTERRUPTED` unless `drainSecs` lets it
+     *  finish; new ones are refused while the stop runs. */
+    stop(opts) {
+        return this.transport.stop(opts);
     }
     /** Save RAM and disk durably, then stop at that execution boundary. */
     pause() { return this.transport.pause(); }
@@ -340,7 +426,7 @@ class Machine {
     delete(opts) {
         if (opts?.includeUsage)
             return this.transport.deleteWithUsage();
-        return this.transport.delete();
+        return this.transport.delete(opts?.drainSecs !== undefined ? { drainSecs: opts.drainSecs } : undefined);
     }
     /** Metered usage + cost for this machine (cloud target). Usage records
      *  survive deletion for 30 days. CPU/memory accrue via a rollup that samples
@@ -361,6 +447,20 @@ class Machine {
     unshare() {
         return this.transport.unshare();
     }
+    /** A URL for each published port that reaches it with no login (cloud
+     *  target), keyed by guest port: for a client that cannot send an API key,
+     *  such as a sandbox framework calling its tunnel URLs. Anyone holding a link
+     *  reaches the port, so treat it as a credential. The machine keeps one
+     *  token, so calling again returns the same links; a port published later
+     *  appears on the next call. {@link revokePortLinks} revokes them. */
+    portLinks() {
+        return this.transport.portLinks();
+    }
+    /** Revoke this machine's port links (cloud target): every link stops working
+     *  at once, and the next {@link portLinks} issues new ones. */
+    revokePortLinks() {
+        return this.transport.revokePortLinks();
+    }
     /** Publish this machine's cache disk, the version it started from plus
      *  everything it wrote, as its cache disk's next version (cloud target).
      *  Stop the machine first: a running machine is still writing it. */

package/dist/native.d.ts

@@ -16,6 +16,11 @@ export interface NativeExecOptions {
     workdir?: string | undefined;
     timeoutSecs?: number | undefined;
     user?: string | undefined;
+    stdin?: string | undefined;
+}
+export interface NativeStopOptions {
+    drainSecs?: number | undefined;
+    timeoutSecs?: number | undefined;
 }
 export interface NativeHostMount {
     source: string;
@@ -72,6 +77,17 @@ export interface NativeMachineSummary {
     detached: boolean;
     branchable: boolean;
     createdAt: number;
+    resources: {
+        cpus: number;
+        memoryMib: number;
+        storageGib: number;
+        overlayGib: number;
+    };
+    ports: {
+        host: number;
+        guest: number;
+        protocol: string;
+    }[];
 }
 export interface NativeExecResult {
     exitCode: number;
@@ -143,15 +159,29 @@ export interface NapiMachine {
         cidrs?: string[];
         hosts?: string[];
     }): void;
-    stop(): Promise<void>;
+    stop(options?: NativeStopOptions): Promise<void>;
+    publishedPorts(): {
+        host: number;
+        guest: number;
+        protocol: string;
+    }[];
+    setPorts(ports: {
+        host: number;
+        guest: number;
+        protocol: string;
+    }[]): Promise<void>;
+    pack(output: string): Promise<string>;
     pause(): Promise<void>;
     resume(): Promise<void>;
-    delete(): Promise<void>;
+    delete(options?: NativeStopOptions): Promise<void>;
 }
 export interface NapiMachineCtor {
     new (config: NativeMachineConfig): NapiMachine;
     prepareImage(image: string): Promise<string>;
-    connect(name: string, interceptorAddress?: string, interceptorToken?: string): NapiMachine;
+    connect(name: string, interceptorAddress?: string, interceptorToken?: string): Promise<NapiMachine>;
+    open(name: string): NapiMachine;
+    deleteByName(name: string, options?: NativeStopOptions): Promise<void>;
+    createFromPack(name: string, pack: string): Promise<NapiMachine>;
     list(): Promise<NativeMachineSummary[]>;
     restoreCheckpoint(name: string, artifact: string, keepIdentity?: boolean): NapiMachine;
     exportCheckpoint(source: string, output: string): number;

package/dist/transport.d.ts

@@ -7,7 +7,7 @@
  *  Cloud-only/local-only capability gaps surface as `NotSupportedError`.
  */
 import { type NativeMachineConfig } from "./native";
-import type { CheckpointOptions, JobInfo, JobOptions, JobOutput, JobOutputOptions, 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";
+import type { CheckpointOptions, JobInfo, JobOptions, JobOutput, JobOutputOptions, CacheDiskInfo, CreateCacheDiskOptions, PublishedCacheDisk, MachineResources, ResizeOptions, ConnectOptions, NetworkPolicy, RestoreCheckpointOptions, ExecEvent, ExecOptions, EgressInterceptor, AssignOptions, ForkBatchOptions, ForkOptions, ImageInfo, ListOptions, MachineConfig, MachineSummary, MachineUsageReport, ShareLink, PortableCheckpointInfo, PortEndpoint, PortSpec, PublishedPort, StopOptions, 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. */
@@ -58,11 +58,17 @@ export interface Transport {
     readonly machineId: string;
     sync(): Promise<void>;
     setNetworkPolicy(policy: NetworkPolicy): Promise<void>;
-    stop(): Promise<void>;
+    /** Published ports, whether or not the machine runs. */
+    ports(): Promise<PublishedPort[]>;
+    /** Replace the published ports. The cloud takes TCP guest ports and picks host ports. */
+    setPorts(ports: PublishedPort[]): Promise<void>;
+    /** Pack the stopped machine into a `.smolmachine`. (local) */
+    pack(output: string): Promise<string>;
+    stop(opts?: StopOptions): Promise<void>;
     pause(): Promise<void>;
     resume(waitUntilReady?: boolean): Promise<void>;
     start(interceptor?: EgressInterceptor, waitUntilReady?: boolean): Promise<void>;
-    delete(): Promise<void>;
+    delete(opts?: StopOptions): Promise<void>;
     /** Cloud only: delete and return the settled usage + cost in one call. */
     deleteWithUsage(): Promise<MachineUsageReport>;
     /** Cloud only: metered usage + cost; readable up to 30 days after delete. */
@@ -72,6 +78,10 @@ export interface Transport {
     share(): Promise<ShareLink>;
     /** Cloud only: revoke the machine's anonymous share link. */
     unshare(): Promise<void>;
+    /** Cloud only: a login-free URL for each published port, by port. */
+    portLinks(): Promise<Record<number, string>>;
+    /** Cloud only: revoke the machine's port links. */
+    revokePortLinks(): Promise<void>;
     /** Cloud only: publish a stopped machine's cache disk as its next version. */
     publishCacheDisk(): Promise<PublishedCacheDisk>;
     checkpoint(output?: string, options?: CheckpointOptions): Promise<PortableCheckpointInfo>;
@@ -175,6 +185,18 @@ export declare function makeTransport(config: MachineConfig, conn: ConnectOption
  * the account. Labels tell one owner's machines from another's.
  */
 export declare function listMachines(conn: ConnectOptions, options?: ListOptions): Promise<MachineSummary[]>;
+/**
+ * A handle to an existing machine that does not start it or wait for it —
+ * to read its state, stop, resize or delete it. Locally it fails with
+ * `NOT_FOUND` when no machine has that name; on the cloud it looks the
+ * machine up by id or name.
+ */
+export declare function openTransport(id: string, conn: ConnectOptions): Promise<Transport>;
+/**
+ * Delete a machine by name or id without a handle, whether or not it runs,
+ * and without booting it. Deleting a machine that does not exist succeeds.
+ */
+export declare function deleteMachine(id: string, conn: ConnectOptions, opts?: StopOptions): Promise<void>;
 /**
  * Attach to an EXISTING machine without creating a new one — for driving a
  * machine made elsewhere (another process, the console, the API).

package/dist/transport.js

@@ -25,6 +25,8 @@ exports.sdkMayRetry = sdkMayRetry;
 exports.selectsCloud = selectsCloud;
 exports.makeTransport = makeTransport;
 exports.listMachines = listMachines;
+exports.openTransport = openTransport;
+exports.deleteMachine = deleteMachine;
 exports.connectTransport = connectTransport;
 exports.deleteCheckpointTransport = deleteCheckpointTransport;
 exports.restoreCheckpointTransport = restoreCheckpointTransport;
@@ -42,6 +44,11 @@ const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const native_1 = require("./native");
 const errors_1 = require("./errors");
+/** A cloud machine's published ports, as the SDK reports ports everywhere. A
+ *  port not placed on a node yet has no host port, reported as 0. */
+function cloudPorts(m) {
+    return (m.ports ?? []).map((p) => ({ host: p.hostPort ?? 0, guest: p.port, protocol: "tcp" }));
+}
 /** Byte-exact exec output from a cloud response: prefer the base64 field
  *  (binary-safe, untruncated), fall back to the UTF-8 bytes of the lossy text
  *  when a control predates it or the value is malformed. */
@@ -139,10 +146,22 @@ function toNativeExecOptions(opts) {
         workdir: opts.workdir,
         timeoutSecs: opts.timeout,
         user: opts.user,
+        stdin: stdinText(opts.stdin),
         env: opts.env &&
             Object.entries(opts.env).map(([key, value]) => ({ key, value })),
     };
 }
+/** `ExecOptions.stdin` as the text the agent protocol carries. */
+function stdinText(stdin) {
+    if (stdin === undefined || typeof stdin === "string")
+        return stdin;
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(stdin);
+    }
+    catch {
+        throw new errors_1.InvalidConfigError("exec stdin must be UTF-8 text.");
+    }
+}
 /** Drain an exec stream into an exec result, for an `exec` that must be
  *  abortable (only the streaming path can kill a running command). */
 async function collectExec(events, signal) {
@@ -163,6 +182,13 @@ async function collectExec(events, signal) {
     }
     throw new errors_1.SmolError("SMOLVM_ERROR", "command stream ended without an exit status");
 }
+/** The cloud stop and delete take no drain or stop timeout yet; say so
+ *  rather than ignore them. */
+function refuseCloudStopOptions(opts) {
+    if (opts?.drainSecs !== undefined || opts?.timeoutSecs !== undefined) {
+        throw new errors_1.NotSupportedError("drainSecs and timeoutSecs are local-only.");
+    }
+}
 /** The control plane echoes the user it ran a command as; an older one, which
  *  predates the field, echoes nothing because it silently dropped it. */
 function assertCloudUserEcho(response, requested) {
@@ -510,6 +536,38 @@ class LocalTransport {
             throw (0, errors_1.wrapNativeError)(e);
         }
     }
+    async ports() {
+        try {
+            return this.inner.publishedPorts().map((p) => ({
+                host: p.host,
+                guest: p.guest,
+                protocol: p.protocol === "udp" ? "udp" : "tcp",
+            }));
+        }
+        catch (e) {
+            throw (0, errors_1.wrapNativeError)(e);
+        }
+    }
+    async setPorts(ports) {
+        try {
+            await this.inner.setPorts(ports.map((p) => {
+                if (p.host === undefined)
+                    throw new errors_1.InvalidConfigError(`port ${p.guest} has no host port`);
+                return { host: p.host, guest: p.guest, protocol: p.protocol };
+            }));
+        }
+        catch (e) {
+            throw (0, errors_1.wrapNativeError)(e);
+        }
+    }
+    async pack(output) {
+        try {
+            return await this.inner.pack((0, node_path_1.resolve)(output));
+        }
+        catch (e) {
+            throw (0, errors_1.wrapNativeError)(e);
+        }
+    }
     async setNetworkPolicy(policy) {
         try {
             this.inner.setEgressPolicy(egressPolicy(policy));
@@ -518,10 +576,10 @@ class LocalTransport {
             throw (0, errors_1.wrapNativeError)(e);
         }
     }
-    async stop() {
+    async stop(opts) {
         liveLocal.delete(this);
         try {
-            await this.inner.stop();
+            await this.inner.stop(opts && { drainSecs: opts.drainSecs, timeoutSecs: opts.timeoutSecs });
         }
         catch (e) {
             throw (0, errors_1.wrapNativeError)(e);
@@ -566,10 +624,10 @@ class LocalTransport {
         if (waitUntilReady)
             await this.waitUntilReady();
     }
-    async delete() {
+    async delete(opts) {
         liveLocal.delete(this);
         try {
-            await this.inner.delete();
+            await this.inner.delete(opts && { drainSecs: opts.drainSecs });
         }
         catch (e) {
             throw (0, errors_1.wrapNativeError)(e);
@@ -587,6 +645,12 @@ class LocalTransport {
     async unshare() {
         throw new errors_1.NotSupportedError("unshare() is cloud-only; a local machine has no share link to revoke.");
     }
+    async portLinks() {
+        throw new errors_1.NotSupportedError("portLinks() is cloud-only; a local machine's ports are on this host (see endpoint()).");
+    }
+    async revokePortLinks() {
+        throw new errors_1.NotSupportedError("revokePortLinks() is cloud-only; a local machine has no port links.");
+    }
     async publishCacheDisk() {
         throw new errors_1.NotSupportedError("publishCacheDisk() is cloud-only; a local machine has no cache disk.");
     }
@@ -1102,6 +1166,7 @@ class CloudTransport {
             timeoutSeconds: opts?.timeout ?? null,
             ...(opts?.user !== undefined ? { user: opts.user } : {}),
             ...(opts?.background ? { background: true } : {}),
+            ...(opts?.stdin !== undefined ? { stdin: stdinText(opts.stdin) ?? null } : {}),
         };
         // The command may legitimately run far longer than the default cloud
         // timeout, so size the request abort timeout off the request's own timeout
@@ -1327,10 +1392,29 @@ class CloudTransport {
     async sync() {
         throw new errors_1.NotSupportedError("sync() is local-only because cloud machines cannot carry host-directory mounts.");
     }
+    async ports() {
+        const m = await cloudFetch(this.conn, "GET", `/v1/machines/${this.id}`);
+        return cloudPorts(m);
+    }
+    async setPorts(ports) {
+        // The cloud publishes TCP guest ports and picks each one's host port on the
+        // machine's node; clients reach them through connect, tunnel and the proxy.
+        if (ports.some((p) => p.protocol === "udp")) {
+            throw new errors_1.NotSupportedError("UDP ports are local-only; the cloud publishes TCP ports.");
+        }
+        const guests = [...new Set(ports.map((p) => p.guest))];
+        await cloudFetch(this.conn, "PUT", `/v1/machines/${this.id}/ports`, {
+            json: { ports: guests.map((port) => ({ port })) },
+        });
+    }
+    async pack() {
+        throw new errors_1.NotSupportedError("pack() is local-only; use checkpoint() on the cloud.");
+    }
     async setNetworkPolicy() {
         throw new errors_1.NotSupportedError("setNetworkPolicy() is local-only.");
     }
-    async stop() {
+    async stop(opts) {
+        refuseCloudStopOptions(opts);
         await cloudFetch(this.conn, "POST", `/v1/machines/${this.id}/stop`, { idempotent: true });
     }
     async pause() {
@@ -1408,7 +1492,8 @@ class CloudTransport {
         // Cancelling twice is harmless, so a 503 may be resent.
         return cloudFetch(this.conn, "POST", `/v1/machines/${this.id}/jobs/${encodeURIComponent(jobId)}/cancel`, { idempotent: true });
     }
-    async delete() {
+    async delete(opts) {
+        refuseCloudStopOptions(opts);
         await cloudFetch(this.conn, "DELETE", `/v1/machines/${this.id}`);
     }
     async deleteWithUsage() {
@@ -1429,6 +1514,13 @@ class CloudTransport {
     async unshare() {
         await cloudFetch(this.conn, "DELETE", `/v1/machines/${this.id}/share`);
     }
+    async portLinks() {
+        const out = await cloudFetch(this.conn, "POST", `/v1/machines/${this.id}/port-links`);
+        return Object.fromEntries(Object.entries(out.urls ?? {}).map(([port, url]) => [Number(port), url]));
+    }
+    async revokePortLinks() {
+        await cloudFetch(this.conn, "DELETE", `/v1/machines/${this.id}/port-links`);
+    }
     async publishCacheDisk() {
         // Flattening and uploading a large cache can take minutes.
         return cloudFetch(this.conn, "POST", `/v1/machines/${this.id}/cache-disk/publish`, { timeoutMs: 30 * 60 * 1000 });
@@ -1800,6 +1892,21 @@ async function makeTransport(config, conn) {
         throw new errors_1.InvalidConfigError("egressInterceptor cannot be combined with branchable machines.");
     }
     let transport;
+    // A `.smolmachine` image is a packed machine: create from it (as
+    // `smolvm machine create --from`), then start it.
+    if (config.image?.endsWith(".smolmachine")) {
+        const owned = !config.detach && (conn.handleSignals ?? true);
+        try {
+            const inner = await (0, native_1.getNapiMachine)().createFromPack(name, (0, node_path_1.resolve)(config.image));
+            transport = new LocalTransport(inner, owned, interceptor, owned);
+            await transport.start(interceptor, config.waitForPorts !== false);
+            return transport;
+        }
+        catch (e) {
+            await transport?.delete().catch(() => { });
+            throw (0, errors_1.wrapNativeError)(e);
+        }
+    }
     try {
         // 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.
@@ -1862,6 +1969,16 @@ async function listMachines(conn, options = {}) {
             detached: r.detached,
             branchable: r.branchable,
             createdAt: new Date(r.createdAt * 1000).toISOString(),
+            resources: {
+                cpus: r.resources.cpus,
+                memoryMib: r.resources.memoryMib,
+                storageGib: r.resources.storageGib,
+            },
+            ports: r.ports.map((p) => ({
+                host: p.host,
+                guest: p.guest,
+                protocol: p.protocol === "udp" ? "udp" : "tcp",
+            })),
         }));
     }
     else {
@@ -1903,6 +2020,21 @@ async function listMachines(conn, options = {}) {
             detached: true,
             branchable: m.branchable ?? m.forkable ?? false,
             createdAt: m.createdAt,
+            ...(m.resources?.cpus != null &&
+                m.resources.memoryMb != null && {
+                resources: {
+                    cpus: m.resources.cpus,
+                    memoryMib: m.resources.memoryMb,
+                    storageGib: m.resources.diskGb ?? 20,
+                },
+            }),
+            ...(m.ports && {
+                ports: m.ports.map((p) => ({
+                    ...(p.hostPort != null && { host: p.hostPort }),
+                    guest: p.port,
+                    protocol: p.protocol === "udp" ? "udp" : "tcp",
+                })),
+            }),
         }));
     }
     const want = Object.entries(options.labels ?? {});
@@ -1910,6 +2042,44 @@ async function listMachines(conn, options = {}) {
         return all;
     return all.filter((m) => want.every(([k, v]) => m.labels[k] === v));
 }
+/**
+ * A handle to an existing machine that does not start it or wait for it —
+ * to read its state, stop, resize or delete it. Locally it fails with
+ * `NOT_FOUND` when no machine has that name; on the cloud it looks the
+ * machine up by id or name.
+ */
+async function openTransport(id, conn) {
+    if (!selectsCloud(conn)) {
+        try {
+            return new LocalTransport((0, native_1.getNapiMachine)().open(id), false, undefined, conn.handleSignals ?? true);
+        }
+        catch (e) {
+            throw (0, errors_1.wrapNativeError)(e);
+        }
+    }
+    // The cloud connect looks the machine up without starting it, and waits
+    // for nothing unless asked to.
+    const { waitForPorts: _ignored, ...rest } = conn;
+    return connectTransport(id, rest);
+}
+/**
+ * Delete a machine by name or id without a handle, whether or not it runs,
+ * and without booting it. Deleting a machine that does not exist succeeds.
+ */
+async function deleteMachine(id, conn, opts) {
+    if (!selectsCloud(conn)) {
+        try {
+            await (0, native_1.getNapiMachine)().deleteByName(id, opts && { drainSecs: opts.drainSecs });
+        }
+        catch (e) {
+            throw (0, errors_1.wrapNativeError)(e);
+        }
+        return;
+    }
+    refuseCloudStopOptions(opts);
+    const transport = await openTransport(id, conn);
+    await transport.delete();
+}
 /**
  * Attach to an EXISTING machine without creating a new one — for driving a
  * machine made elsewhere (another process, the console, the API).
@@ -1930,9 +2100,11 @@ async function connectTransport(id, conn) {
         try {
             // Connecting borrows an existing machine. A signal in this client must
             // not stop a durable checkpoint owned by another process/controller.
+            // The native connect boots off the JavaScript thread, so a slow boot
+            // does not hold the event loop.
             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);
+                ? await (0, native_1.getNapiMachine)().connect(id, conn.egressInterceptor.address, conn.egressInterceptor.token)
+                : await (0, native_1.getNapiMachine)().connect(id), false, conn.egressInterceptor, conn.handleSignals ?? true);
             // 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();

package/dist/types.d.ts

@@ -297,6 +297,37 @@ export interface MachineSummary {
     branchable: boolean;
     /** When the machine was created (RFC3339). */
     createdAt: string;
+    /** CPU, memory and disk sizes, whether or not the machine runs. Missing
+     *  only from a control plane that does not report them. */
+    resources?: MachineSizes;
+    /** Published ports, whether or not the machine runs. `host` is the host
+     *  port forwarding to `guest`; on the cloud it is the node port, set once
+     *  the machine has been placed. */
+    ports?: PublishedPort[];
+}
+/** CPU, memory and disk sizes of a machine, as `Machine.list()` reports them. */
+export interface MachineSizes {
+    cpus: number;
+    memoryMib: number;
+    storageGib: number;
+}
+/** A published port, as `Machine.list()` reports it. */
+export interface PublishedPort {
+    host?: number;
+    guest: number;
+    protocol: "tcp" | "udp";
+}
+/** How `stop()` and `delete()` treat work still running on the machine. */
+export interface StopOptions {
+    /** Wait up to this many seconds for running commands and file transfers to
+     *  finish before stopping. Whatever still runs then rejects with
+     *  `SmolError` code `INTERRUPTED`. Default: stop at once. (local) */
+    drainSecs?: number;
+    /** Seconds the workload (the image ENTRYPOINT/CMD) gets to exit after its
+     *  stop signal before it is killed, instead of the machine's own stop
+     *  timeout; `0` kills it at once. `stop()` only; `delete()` never waits.
+     *  (local) */
+    timeoutSecs?: number;
 }
 /** Filters for `Machine.list()`. */
 export interface ListOptions {
@@ -346,6 +377,10 @@ export interface ExecOptions {
      *  `NotSupportedError` — before running anything — if it predates them. It is
      *  never silently ignored. */
     user?: string;
+    /** Text written to the command's stdin, which is then closed. Passed over
+     *  the agent connection and never written to the machine's disk, so it can
+     *  carry a script or a secret. A `Uint8Array` must be UTF-8. */
+    stdin?: string | Uint8Array;
     /** Abort the command. Locally the command is killed in the machine and the
      *  call (or the `execStream` iteration) rejects with `signal.reason`. On the
      *  cloud target the request is cancelled and the call rejects the same way;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smolmachines",
-  "version": "1.27.3",
+  "version": "1.29.0",
   "description": "Embed isolated microVM sandboxes directly in your code — no server to run.",
   "license": "Apache-2.0",
   "author": "smol-machines",
@@ -54,7 +54,8 @@
     "test:paused-connect": "tsx test/local-paused-connect.ts",
     "gen:openapi": "bash scripts/gen-openapi.sh",
     "test:cloud": "tsx test/cloud-mock.ts && tsx test/cloud-deferred-ports.ts",
-    "test:unit": "tsx test/unit.ts"
+    "test:unit": "tsx test/unit.ts",
+    "test:host-daemon": "tsx test/host-daemon-e2e.ts"
   },
   "devDependencies": {
     "@napi-rs/cli": "^2.18.4",
@@ -64,8 +65,8 @@
     "typescript": "^5.6.0"
   },
   "optionalDependencies": {
-    "smolmachines-darwin-arm64": "1.27.3",
-    "smolmachines-linux-x64-gnu": "1.27.3",
-    "smolmachines-linux-arm64-gnu": "1.27.3"
+    "smolmachines-darwin-arm64": "1.29.0",
+    "smolmachines-linux-x64-gnu": "1.29.0",
+    "smolmachines-linux-arm64-gnu": "1.29.0"
   }
 }