withruntime 0.5.0 → 0.5.1

package/DAYTONA.md

@@ -54,31 +54,31 @@ package talks only to Runtime.
 
 ## Mapping
 
-| Daytona                                                                       | On Runtime                                                                                                                                                                       |
-| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `daytona.create()`, `create({ snapshot })`                                    | `sandboxes.create`. Daytona's own snapshots (`daytona-*`) are Runtime's stock image. Any other name is a ready Runtime image of that name, then a Runtime snapshot of that name. |
-| `create({ image: "python:3.12" })`                                            | Built once as a Runtime image from the registry reference (named after it), then reused. `onSnapshotCreateLogs` receives the build log.                                          |
-| `create({ image: Image.debianSlim(...).pipInstall(...)... })`                 | The Dockerfile Daytona's `Image` stands for, with its local files, built as a Runtime image named after its content and reused.                                                  |
-| `resources`, `envVars`, `labels`, `name`, `volumes`                           | `vcpu`, `memoryMiB`, `diskMiB`; environment given to every command; labels; name; Runtime volumes by id or by name.                                                              |
-| `networkBlockAll`, `networkAllowList`, `domainAllowList`, `outboundProxyUrl`  | Runtime network rules (`internet: false`, or an `allow` list); the proxy as `HTTP_PROXY` and `HTTPS_PROXY` for commands.                                                         |
-| `public: true`                                                                | `getPreviewLink(port)` shares the port publicly; without it, privately with a token.                                                                                             |
-| `language`                                                                    | The language of `codeRun`, kept in Daytona's `code-toolbox-language` label so a sandbox found later keeps it.                                                                    |
-| `daytona.get(idOrName)`, `daytona.list({ labels, states, name })`             | `sandboxes.get`, or the newest live sandbox with that name; `sandboxes.list`. Awaiting `list()` gives the older `{ items, total }` shape.                                        |
-| `process.executeCommand(cmd, cwd, env, timeout)`                              | `exec` under bash with stderr joined to stdout, as Daytona's `result`. A non-zero exit is a result. Past `timeout` (seconds): `DaytonaProcessExecutionTimeoutError`.             |
-| `process.codeRun(code, { argv, env })`                                        | `python3 -c`, `node -e` or `bun -e` by the sandbox's language. `artifacts.charts` is always empty.                                                                               |
-| `createSession`, `executeSessionCommand`, `getSessionCommandLogs`             | One bash per session, kept running: directory, variables and functions carry from one command to the next. `runAsync` returns at once; logs stream to callbacks.                 |
-| `sendSessionCommandInput`, `getSession`, `getSessionCommand`, `deleteSession` | Input to the session's shell, which the running command reads; the commands sent through this object; killing the shell.                                                         |
-| `fs.uploadFile(s)`, `downloadFile(s)`, `listFiles`, `getFileDetails`          | Runtime's files API. Relative paths resolve from `/workspace`. `owner` and `group` are always `""`.                                                                              |
-| `fs.createFolder`, `deleteFile`, `moveFiles`, `setFilePermissions`            | `mkdir -m`, `files.remove`, `files.rename`, `chmod` and `sudo chown`.                                                                                                            |
-| `fs.findFiles`, `searchFiles`, `replaceInFiles`                               | `grep -rn`, a files glob, and a read and write of each file.                                                                                                                     |
-| `git.clone`, `status`, `add`, `commit`, `push`, `pull`, branches              | The sandbox's git. Credentials reach git through the environment, never the command line.                                                                                        |
-| `codeInterpreter.runCode`, contexts                                           | Runtime's Python interpreter. The sandbox's `envVars` reach code through a context made once for them.                                                                           |
-| `start`, `stop`, `pause`, `archive`, `delete`, `fork`, `createSnapshot`       | `wake`, `pause` (or `stop` when ephemeral), `pause`, `pause`, `stop`, Runtime's fork with memory, a Runtime snapshot with that name.                                             |
-| `getPreviewLink(port)`                                                        | A Runtime preview. Send its token as `x-runtime-preview-token`; Daytona's header is `x-daytona-preview-token`.                                                                   |
-| `getUserHomeDir`, `getWorkDir`, `user`                                        | `/workspace`, and `daytona`, so `/home/daytona` (linked to `/workspace` the first time something names it) works.                                                                |
-| `daytona.snapshot.create`, `get`, `list`, `delete`                            | Runtime images built, found, listed and deleted by name.                                                                                                                         |
-| `daytona.volume.get`, `list`, `delete`                                        | Runtime volumes by name.                                                                                                                                                         |
-| Error classes                                                                 | Daytona's names and parents, by HTTP status. Each also carries Runtime's `code`, `hint` and `requestId`, with the original error as `cause`.                                     |
+| Daytona                                                                       | On Runtime                                                                                                                                                                                                    |
+| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `daytona.create()`, `create({ snapshot })`                                    | `sandboxes.create`. Daytona's own snapshots (`daytona-*`) are Runtime's stock image. Any other name is a ready Runtime image of that name, then a Runtime snapshot of that name.                              |
+| `create({ image: "python:3.12" })`                                            | Built once as a Runtime image from the registry reference (named after it), then reused. `onSnapshotCreateLogs` receives the build log.                                                                       |
+| `create({ image: Image.debianSlim(...).pipInstall(...)... })`                 | The Dockerfile Daytona's `Image` stands for, with its local files, built as a Runtime image named after its content and reused.                                                                               |
+| `resources`, `envVars`, `labels`, `name`, `volumes`                           | `vcpu`, `memoryMiB`, `diskMiB`; environment given to every command; labels; name; Runtime volumes by id or by name.                                                                                           |
+| `networkBlockAll`, `networkAllowList`, `domainAllowList`, `outboundProxyUrl`  | Runtime network rules (`internet: false`, or an `allow` list); the proxy as `HTTP_PROXY` and `HTTPS_PROXY` for commands.                                                                                      |
+| `public: true`                                                                | `getPreviewLink(port)` shares the port publicly; without it, privately with a token.                                                                                                                          |
+| `language`                                                                    | The language of `codeRun`, kept in Daytona's `code-toolbox-language` label so a sandbox found later keeps it.                                                                                                 |
+| `daytona.get(idOrName)`, `daytona.list({ labels, states, name })`             | `sandboxes.get`, or the newest live sandbox with that name; `sandboxes.list`. Awaiting `list()` gives the older `{ items, total }` shape.                                                                     |
+| `process.executeCommand(cmd, cwd, env, timeout)`                              | `exec` under bash with stderr joined to stdout, as Daytona's `result`, streamed so the whole output comes back. A non-zero exit is a result. Past `timeout` (seconds): `DaytonaProcessExecutionTimeoutError`. |
+| `process.codeRun(code, { argv, env })`                                        | `python3 -c`, `node -e` or `bun -e` by the sandbox's language. `artifacts.charts` is always empty.                                                                                                            |
+| `createSession`, `executeSessionCommand`, `getSessionCommandLogs`             | One bash per session, kept running: directory, variables and functions carry from one command to the next. `runAsync` returns at once; logs stream to callbacks.                                              |
+| `sendSessionCommandInput`, `getSession`, `getSessionCommand`, `deleteSession` | Input to the session's shell, which the running command reads; the commands sent through this object; killing the shell.                                                                                      |
+| `fs.uploadFile(s)`, `downloadFile(s)`, `listFiles`, `getFileDetails`          | Runtime's files API. Relative paths resolve from `/workspace`. `owner` and `group` are always `""`.                                                                                                           |
+| `fs.createFolder`, `deleteFile`, `moveFiles`, `setFilePermissions`            | `mkdir -m`, `files.remove`, `files.rename`, `chmod` and `sudo chown`.                                                                                                                                         |
+| `fs.findFiles`, `searchFiles`, `replaceInFiles`                               | `grep -rn`, a files glob, and a read and write of each file.                                                                                                                                                  |
+| `git.clone`, `status`, `add`, `commit`, `push`, `pull`, branches              | The sandbox's git. Credentials reach git through the environment, never the command line.                                                                                                                     |
+| `codeInterpreter.runCode`, contexts                                           | Runtime's Python interpreter. The sandbox's `envVars` reach code through a context made once for them.                                                                                                        |
+| `start`, `stop`, `pause`, `archive`, `delete`, `fork`, `createSnapshot`       | `wake`, `pause` (or `stop` when ephemeral), `pause`, `pause`, `stop`, Runtime's fork with memory, a Runtime snapshot with that name.                                                                          |
+| `getPreviewLink(port)`                                                        | A Runtime preview. Send its token as `x-runtime-preview-token`; Daytona's header is `x-daytona-preview-token`.                                                                                                |
+| `getUserHomeDir`, `getWorkDir`, `user`                                        | `/workspace`, and `daytona`, so `/home/daytona` (linked to `/workspace` the first time something names it) works.                                                                                             |
+| `daytona.snapshot.create`, `get`, `list`, `delete`                            | Runtime images built, found, listed and deleted by name.                                                                                                                                                      |
+| `daytona.volume.get`, `list`, `delete`                                        | Runtime volumes by name.                                                                                                                                                                                      |
+| Error classes                                                                 | Daytona's names and parents, by HTTP status. Each also carries Runtime's `code`, `hint` and `requestId`, with the original error as `cause`.                                                                  |
 
 ## Gaps
 

package/E2B.md

@@ -58,7 +58,7 @@ machine. An E2B key (`e2b_...`) is never sent anywhere. If one is passed as
 | `envs`                                                                                   | Given to every command and code run through this object.                                                                                                                       |
 | `allowInternetAccess: false`                                                             | `network: { internet: false }`.                                                                                                                                                |
 | `lifecycle.onTimeout`                                                                    | `onLeaseEnd`: `kill` is `stop`, `pause` is `pause`.                                                                                                                            |
-| `commands.run(cmd, { cwd, envs, timeoutMs, onStdout, onStderr })`                        | `exec`. Default timeout 60 s. `0` means no limit (Runtime's longest, 24 hours).                                                                                                |
+| `commands.run(cmd, { cwd, envs, timeoutMs, onStdout, onStderr })`                        | `exec`, streamed, so the whole output comes back however large. Default timeout 60 s. `0` means no limit (Runtime's longest, 24 hours).                                        |
 | Non-zero exit                                                                            | Throws `CommandExitError` with `exitCode`, `stdout`, `stderr` and `error` (`exit status N`). A command killed by a signal has `exitCode` -1.                                   |
 | Command past its timeout                                                                 | Throws `TimeoutError`.                                                                                                                                                         |
 | `commands.run(cmd, { background: true })`                                                | `spawn`. Returns a `CommandHandle` with `pid`, `wait()`, `kill()` (SIGKILL), `sendStdin`, `closeStdin`, `disconnect`, `stdout`, `stderr`, `exitCode`.                          |

package/dist/cli.js

@@ -684,7 +684,16 @@ const RIVAL_NAMES = {
     cloudflare: "Cloudflare Sandbox",
     fly: "Fly",
 };
-/** One line on the switching credit: how to claim it, or what it did. */
+/** A date as the CLI writes one: 23 September 2026. */
+const longDate = (iso) => new Date(iso).toLocaleDateString("en-GB", {
+    day: "numeric",
+    month: "long",
+    year: "numeric",
+    timeZone: "UTC",
+});
+/** One line on the switching credit: how to claim it, or what it did. A
+ * switch already on record is named with its provider and date, so it never
+ * reads as if this command recorded it, or recorded the provider it names. */
 function switchingLine(summary, provider) {
     const cap = dollars(summary.maxMicros);
     const sw = summary.switch;
@@ -694,21 +703,32 @@ function switchingLine(summary, provider) {
         return `Switching from ${RIVAL_NAMES[provider]}? Run \`${me} switch --from ${provider}\` before your first top-up and we match that top-up, up to ${cap}.`;
     }
     const from = RIVAL_NAMES[sw.provider];
+    const recorded = `This organization's switch from ${from} was recorded on ${longDate(sw.recordedAt)}`;
+    const once = provider && provider !== sw.provider
+        ? ` A switch is recorded once, so it stays ${from}, not ${RIVAL_NAMES[provider]}.`
+        : "";
     switch (sw.status) {
         case "pending":
-            return `Your switch from ${from} is recorded: your first top-up is matched, up to ${cap}, once the payment settles.`;
+            return `${recorded}: its first top-up is matched, up to ${cap}, once the payment settles.${once}`;
         case "paid":
-            return `Your switch from ${from} matched your first top-up: ${dollars(sw.creditMicros)} of credit.`;
+            return `${recorded} and matched its first top-up: ${dollars(sw.creditMicros)} of credit.${once}`;
         case "superseded":
-            return `Your first top-up was matched by your referral instead, which is never less than the switching credit.`;
+            return `${recorded}; its first top-up was matched by a referral instead, which is never less than the switching credit.${once}`;
         case "reversed":
-            return `The top-up your switching credit matched was refunded, so the credit was taken back.`;
+            return `${recorded}; the top-up it matched was refunded, so the credit was taken back.${once}`;
         case "refused":
             return sw.refusedReason === "program_off"
-                ? "The switching credit was paused when your first top-up arrived."
-                : "Your first top-up was not matched. Ask support if you think that is wrong.";
+                ? `${recorded}; the switching credit was paused when its first top-up arrived.${once}`
+                : `${recorded}; its first top-up was not matched. Ask support if you think that is wrong.${once}`;
     }
 }
+/** The sandboxes the free trial paid for, said beside what was priced. */
+function trialNote(trial, all) {
+    if (!trial)
+        return "";
+    const which = trial === all ? (all === 1 ? "It" : "All of them") : `${trial} of them`;
+    return ` ${which} ran on the free trial, which charged nothing; Runtime's side prices ${trial === 1 ? "it" : "them"} at the standard rates, what the same work costs on paid credit.`;
+}
 async function switching(command, argv, env, out) {
     const args = parse(argv);
     const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
@@ -756,13 +776,13 @@ async function switching(command, argv, env, out) {
                 : month >= 0n
                     ? `, about ${dollars(month)} a month.`
                     : `, about ${dollars(-month)} a month more on Runtime.`}`,
-            `Priced: ${c.usage.sandboxes.toLocaleString("en-US")} sandbox${c.usage.sandboxes === 1 ? "" : "es"}, ${(c.usage.runSeconds / 3600).toLocaleString("en-US", { maximumFractionDigits: 2 })} hours running.${c.usage.unpricedSandboxes ? ` ${c.usage.unpricedSandboxes} left out: ${c.rival.name} publishes no price for their size.` : ""}`,
+            `Priced: ${c.usage.sandboxes.toLocaleString("en-US")} sandbox${c.usage.sandboxes === 1 ? "" : "es"}, ${(c.usage.runSeconds / 3600).toLocaleString("en-US", { maximumFractionDigits: 2 })} hours running.${trialNote(c.usage.trialSandboxes, c.usage.sandboxes)}${c.usage.unpricedSandboxes ? ` ${c.usage.unpricedSandboxes} left out: ${c.rival.name} publishes no price for their size.` : ""}`,
         ]
         : [
             `No settled sandboxes in your last ${c.window.days} days yet, so this prices an example: ${c.usage.sandboxes.toLocaleString("en-US")} runs of ${(c.usage.runSeconds / c.usage.sandboxes).toLocaleString("en-US")} seconds using ${(c.usage.activeCpuSeconds / c.usage.sandboxes).toLocaleString("en-US")} CPU-seconds each.`,
             `The example: ${figures}.`,
         ];
-    lines.push(`${c.rival.name}'s published rates, checked ${new Date(`${c.rival.checked}T12:00:00Z`).toLocaleDateString("en-GB", { day: "numeric", month: "long", year: "numeric", timeZone: "UTC" })}: ${c.rival.rates.join("; ")}. Compute only: storage, network, plan fees and free allowances are left out.`);
+    lines.push(`${c.rival.name}'s published rates, checked ${longDate(`${c.rival.checked}T12:00:00Z`)}: ${c.rival.rates.join("; ")}. Compute only: storage, network, plan fees and free allowances are left out.`);
     const line = switchingLine(c.switching, Object.hasOwn(SWITCH_FROM, from) ? SWITCH_FROM[from] : undefined);
     if (line)
         lines.push("", line);

package/dist/daytona/context.d.ts

@@ -19,6 +19,11 @@ export declare const HOME = "/workspace";
 export declare const HOME_LINK = "[ -e /home/daytona ] || sudo ln -s /workspace /home/daytona";
 /** Commands without a timeout run until the sandbox ends: Runtime's longest. */
 export declare const LONGEST_MS = 86400000;
+/** Given to exec so it streams and returns the whole output, as Daytona does:
+ * an exec with no output callback returns at most 64 KiB of each stream. */
+export declare const WHOLE_OUTPUT: {
+    readonly onStdout: () => undefined;
+};
 /** A Daytona path as a Runtime one: relative paths (and `~`) resolve from the
  * working directory, /workspace on Runtime. */
 export declare function resolvePath(path: string): string;

package/dist/daytona/context.js

@@ -5,6 +5,9 @@ export const HOME = "/workspace";
 export const HOME_LINK = `[ -e ${DAYTONA_HOME} ] || sudo ln -s ${HOME} ${DAYTONA_HOME}`;
 /** Commands without a timeout run until the sandbox ends: Runtime's longest. */
 export const LONGEST_MS = 86_400_000;
+/** Given to exec so it streams and returns the whole output, as Daytona does:
+ * an exec with no output callback returns at most 64 KiB of each stream. */
+export const WHOLE_OUTPUT = { onStdout: () => undefined };
 /** A Daytona path as a Runtime one: relative paths (and `~`) resolve from the
  * working directory, /workspace on Runtime. */
 export function resolvePath(path) {

package/dist/daytona/filesystem.js

@@ -1,4 +1,4 @@
-import { resolvePath } from "./context.js";
+import { resolvePath, WHOLE_OUTPUT } from "./context.js";
 import { DaytonaError, DaytonaFileNotFoundError, guard } from "./errors.js";
 const PERMISSIONS = ["---", "--x", "-w-", "-wx", "r--", "r-x", "rw-", "rwx"];
 function fileInfo(entry) {
@@ -112,7 +112,7 @@ export class FileSystem {
     async findFiles(path, pattern) {
         const target = await this.#path(path);
         const runtime = await this.#ctx.live();
-        const result = await guard("sandbox", () => runtime.exec(["grep", "-rnI", "--", pattern, target]));
+        const result = await guard("sandbox", () => runtime.exec(["grep", "-rnI", "--", pattern, target], WHOLE_OUTPUT));
         if (result.exitCode !== 0 && result.exitCode !== 1)
             throw new DaytonaError(result.stderr.trim() || "grep failed", 400);
         return result.stdout

package/dist/daytona/process.js

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { HOME, LONGEST_MS, quote, resolvePath } from "./context.js";
+import { HOME, LONGEST_MS, quote, resolvePath, WHOLE_OUTPUT, } from "./context.js";
 import { DaytonaCommandAlreadyCompletedError, DaytonaConflictError, DaytonaNotFoundError, DaytonaProcessExecutionTimeoutError, DaytonaSessionEndedError, guard, NotSupportedError, } from "./errors.js";
 export class CodeRunParams {
     argv;
@@ -76,6 +76,7 @@ export class Process {
             cwd: cwd === undefined ? HOME : resolvePath(cwd),
             ...this.#env(env),
             timeoutMs,
+            ...WHOLE_OUTPUT,
         }));
         if (result.timedOut)
             throw new DaytonaProcessExecutionTimeoutError(`Command timed out after ${timeout} s. Pass a larger timeout, or 0 for none.`, 408);
@@ -97,6 +98,7 @@ export class Process {
             cwd: HOME,
             ...this.#env(params.env),
             timeoutMs,
+            ...WHOLE_OUTPUT,
         }));
         if (result.timedOut)
             throw new DaytonaProcessExecutionTimeoutError(`Code run timed out after ${timeout} s.`, 408);

package/dist/e2b/commands.js

@@ -68,12 +68,16 @@ export class Commands {
             const handle = await this.#start(cmd, opts, timeoutMs);
             return opts.background ? handle : handle.wait();
         }
+        /* Always streamed, so the result holds the whole output as E2B's does: an
+           exec with no output callback returns at most 64 KiB of each stream. */
+        const onStdout = opts.onStdout;
+        const onStderr = opts.onStderr;
         const result = await guard("sandbox", () => this.#ctx.runtime.exec(cmd, {
             ...(opts.cwd === undefined ? {} : { cwd: opts.cwd }),
             ...this.#env(opts.envs),
             timeoutMs,
-            ...(opts.onStdout ? { onStdout: (text) => void opts.onStdout(text) } : {}),
-            ...(opts.onStderr ? { onStderr: (text) => void opts.onStderr(text) } : {}),
+            onStdout: (text) => void onStdout?.(text),
+            ...(onStderr ? { onStderr: (text) => void onStderr(text) } : {}),
             ...(opts.signal ? { signal: opts.signal } : {}),
         }));
         return settle(result, timeoutMs);

package/dist/products/switching.d.ts

@@ -52,7 +52,14 @@ export type UsageComparison = {
         runSeconds: number;
         activeCpuSeconds: number;
         unpricedSandboxes: number;
+        /** Of `sandboxes`, how many the free trial paid for, and their running
+         * time. The trial charged nothing for them; `runtimeMicros` prices them at
+         * Runtime's standard rates, what the same work costs on paid credit. */
+        trialSandboxes: number;
+        trialRunSeconds: number;
     };
+    /** What the usage costs on Runtime on paid credit: each paid sandbox at the
+     * rates it was quoted, a trial sandbox at the standard rates. */
     runtimeMicros: string;
     rivalMicros: string;
     /** Rival less Runtime: negative when the rival would cost less. */

package/dist/ssh.js

@@ -265,9 +265,21 @@ export async function portForwardCommand(argv, out, connect, me) {
     const sbx = await resolveSandbox(await connect(), target);
     const tunnel = await sbx.tunnel();
     const forwards = [];
+    /* A connection the sandbox refused is closed at once, which a browser or
+       curl reports only as an empty reply, so say why here, once per reason. */
+    const said = new Set();
+    const refused = (remote) => (error) => {
+        const line = `Port ${remote}: ${error.message}${error.hint ? ` ${error.hint}` : ""}`;
+        if (said.has(line))
+            return;
+        said.add(line);
+        out.error(out.json
+            ? JSON.stringify({ port: remote, error: { code: error.code, message: error.message } })
+            : line);
+    };
     try {
         for (const { local, remote } of ports)
-            forwards.push(await tunnel.forward(remote, { localPort: local, host: address }));
+            forwards.push(await tunnel.forward(remote, { localPort: local, host: address, onError: refused(remote) }));
     }
     catch (error) {
         tunnel.close();

package/dist/transport.d.ts

@@ -1,5 +1,5 @@
 import { RuntimeError } from "./errors.js";
-export declare const VERSION = "0.5.0";
+export declare const VERSION = "0.5.1";
 export declare const DEFAULT_BASE_URL = "https://api.withruntime.com";
 export type RequestOptions = {
     /** Sent as Idempotency-Key. Omit it: the SDK makes one per call and keeps

package/dist/transport.js

@@ -1,6 +1,6 @@
 import { ConnectionError, errorFor, RuntimeError, WAITS_FOR_ROOM } from "./errors.js";
 import { describeRoute, envFetch, openWebSocket } from "./proxy.js";
-export const VERSION = "0.5.0";
+export const VERSION = "0.5.1";
 export const DEFAULT_BASE_URL = "https://api.withruntime.com";
 export function apiOrigin(value) {
     const url = new URL(value);

package/dist/tunnel.d.ts

@@ -1,3 +1,4 @@
+import { RuntimeError } from "./errors.js";
 /** One TCP connection (or SSH login) inside a tunnel. Set the handlers before
  * data can arrive, which is as soon as the promise that gave you this resolves. */
 export declare class TunnelStream {
@@ -49,10 +50,12 @@ export declare class Tunnel {
      * (the text of an OpenSSH `.pub` file). Speak SSH over the stream. */
     ssh(publicKey: string): Promise<TunnelStream>;
     /** Listens on a local port and carries each connection to `port` in the
-     * sandbox. Node and Bun only. */
+     * sandbox. Node and Bun only. A connection the sandbox cannot open, such as
+     * one to a port nothing listens on, is closed at once; `onError` says why. */
     forward(port: number, options?: {
         localPort?: number;
         host?: string;
+        onError?: (error: RuntimeError) => void;
     }): Promise<PortForward>;
     /** Closes the tunnel and every connection in it. */
     close(): void;

package/dist/tunnel.js

@@ -160,7 +160,8 @@ export class Tunnel {
         return this.#open(`ssh ${publicKey.trim()}`);
     }
     /** Listens on a local port and carries each connection to `port` in the
-     * sandbox. Node and Bun only. */
+     * sandbox. Node and Bun only. A connection the sandbox cannot open, such as
+     * one to a port nothing listens on, is closed at once; `onError` says why. */
     async forward(port, options = {}) {
         const net = await import("node:net");
         const host = options.host ?? "127.0.0.1";
@@ -183,7 +184,11 @@ export class Tunnel {
                 socket.on("end", () => stream.end());
                 socket.on("close", () => stream.close());
                 socket.resume();
-            }, () => socket.destroy());
+            }, (error) => {
+                socket.destroy();
+                if (error instanceof RuntimeError)
+                    options.onError?.(error);
+            });
         });
         await new Promise((resolve, reject) => {
             server.once("error", reject);
@@ -217,7 +222,7 @@ export class Tunnel {
                         message: `Nothing is listening on port ${port} in the sandbox.`,
                         code: "port_closed",
                         status: 0,
-                        hint: "Start the server first, and let it listen on 127.0.0.1, ::1 or every address.",
+                        hint: "Start the server with spawn (`runtime sandbox spawn <id> -- <command>`, sbx.spawn()), which keeps it running: a process started by exec ends with its command. Let it listen on 127.0.0.1, ::1 or every address.",
                     })
                     : error.message === "reserved"
                         ? new RuntimeError({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "withruntime",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "mcpName": "com.withruntime/runtime",
   "type": "module",
   "exports": {