@mastra/platform-workspace 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,81 @@
 # @mastra/platform
 
+## 1.1.0
+
+### Minor Changes
+
+- `PlatformSandbox.executeCommand` can now dial the sandbox directly over Railway's private network instead of going through the platform's public exec proxy. On paths where the direct route is available, per-exec latency drops from ~400 ms p50 to ~16 ms p50, and the exec stops touching the platform control plane. This flows through to every filesystem call (`SandboxFilesystem.readFile`, `writeFile`, `readdir`, `mkdir`, `stat`, `exists`, `copyFile`, `moveFile`, `deleteFile`), which is where most agent tool time was going. ([#20664](https://github.com/mastra-ai/mastra/pull/20664))
+
+  Direct-path availability is a runtime property, not a configuration knob. When it's not available — no address registry wired up, the workspace-proxy hasn't discovered the sandbox address yet, or a direct dial fails — `executeCommand` transparently falls back to the existing exec-lease path with no behavior change. Timed-out execs are never retried on the fallback path (they're returned to the caller as-is), so this is safe for non-idempotent commands.
+
+  ### Enabling the direct path
+
+  Wire a `SandboxAddressRegistry` into `PlatformSandbox`:
+
+  ```ts
+  import { PlatformSandbox, InProcessSandboxAddressRegistry } from '@mastra/platform-workspace';
+
+  const registry = new InProcessSandboxAddressRegistry();
+
+  const sandbox = new PlatformSandbox({
+    accessToken: process.env.MASTRA_PLATFORM_ACCESS_TOKEN,
+    projectId: process.env.MASTRA_PLATFORM_PROJECT_ID,
+    environmentId: process.env.MASTRA_PLATFORM_ENVIRONMENT_ID,
+    addressRegistry: registry,
+  });
+  ```
+
+  `PlatformSandbox.start()` populates the registry from the workspace-proxy's response; `executeCommand` reads it, tries the direct path first, evicts on transport failure. `destroy()` also evicts. `clone()` shares the same registry — each child sandbox looks up its own id.
+
+  ### New public exports
+  - `SandboxAddressRegistry` — the `{ get, set, delete }` interface `PlatformSandbox` sees. Callers can implement their own (e.g. shared across a worker pool) or use the default.
+  - `InProcessSandboxAddressRegistry` — the default `Map`-backed implementation.
+  - `PlatformSandboxOptions.addressRegistry?` — DI seam. Optional; omitted keeps pre-existing behavior.
+  - `execViaPrivateNetwork`, `PrivateNetExecHttpError`, `PrivateNetExecOptions`, `PrivateNetExecResult`, `PrivateNetFetch` — standalone transport for callers that want to talk to a sandbox directly without going through `PlatformSandbox`.
+
+### Patch Changes
+
+- Updated dependencies [[`8d2399b`](https://github.com/mastra-ai/mastra/commit/8d2399b638f8e0945cf2cda0187dbea8dcf0b784), [`c8002da`](https://github.com/mastra-ai/mastra/commit/c8002da7775c468e2965b6ff5f82045450fa8cb9), [`92be47f`](https://github.com/mastra-ai/mastra/commit/92be47fbd26ffccec0e2131ef7c1d9e70dd5ef4a), [`89200ba`](https://github.com/mastra-ai/mastra/commit/89200bafa05444bb7949b363ce7b743e29867561), [`c950138`](https://github.com/mastra-ai/mastra/commit/c950138e72e4f317a40187e3800588731ab790ce), [`810c7e7`](https://github.com/mastra-ai/mastra/commit/810c7e74929989d8b8b5db52cd3af22cd0998af4), [`063c8b2`](https://github.com/mastra-ai/mastra/commit/063c8b2eb14e4e5ca021779bc33e8c3c031c8604), [`f9f9884`](https://github.com/mastra-ai/mastra/commit/f9f98848ee194dc71a787a709ec430b065cdc41b), [`e0904dc`](https://github.com/mastra-ai/mastra/commit/e0904dc538792e54e1806b70172e5900ac49bff4), [`9672fab`](https://github.com/mastra-ai/mastra/commit/9672fabfbcadb961a35c22a2d6722e077f7b24b9), [`f4e964c`](https://github.com/mastra-ai/mastra/commit/f4e964cad57057301d6bed5c55bcdd730175b941), [`1f7bbd7`](https://github.com/mastra-ai/mastra/commit/1f7bbd7785a8d230aad02454ecabeb4a0b2cc96f), [`e47ff36`](https://github.com/mastra-ai/mastra/commit/e47ff36945720f4ee4caa09f6e83514d7d188608), [`64d6781`](https://github.com/mastra-ai/mastra/commit/64d67814bccddd314f7e09643243821e57cb87b6), [`fb9a6ac`](https://github.com/mastra-ai/mastra/commit/fb9a6ac11c9560518742ece60b49d6b062845fd3), [`aa2cec8`](https://github.com/mastra-ai/mastra/commit/aa2cec8501f634d51c2f3ebfb3dd3aa7af8d2ca2), [`c848e65`](https://github.com/mastra-ai/mastra/commit/c848e655a64ff10331a8ceafafe7f18e70a0f092), [`2adf8eb`](https://github.com/mastra-ai/mastra/commit/2adf8eb4a70ed2b6cff2dd39281496ea0e025fac), [`0494489`](https://github.com/mastra-ai/mastra/commit/049448906e4c3d2d615bbe865b073a0d890ddb7c), [`8d1aeb8`](https://github.com/mastra-ai/mastra/commit/8d1aeb8acf7c20c4bb8e4d8e4bdc6569c83ac561), [`8264611`](https://github.com/mastra-ai/mastra/commit/8264611510e421b818bc7395dc2ae4d9c2d518b2), [`d8fa243`](https://github.com/mastra-ai/mastra/commit/d8fa2430d21113e330c4e676ac65e1235cf44f81), [`44fc98b`](https://github.com/mastra-ai/mastra/commit/44fc98b9d1242aa87a3ab44bdce9e9f12c44d8c9), [`f933ba3`](https://github.com/mastra-ai/mastra/commit/f933ba32700e1d0bf143311c1a08f88300b840b6), [`83065bf`](https://github.com/mastra-ai/mastra/commit/83065bfee9e47c3c6f09132a9034501f6cfb69cf), [`0f2ef41`](https://github.com/mastra-ai/mastra/commit/0f2ef4118da022e4f30dac4e9856cc3a8c97671c), [`01b162f`](https://github.com/mastra-ai/mastra/commit/01b162fe435295881aa7ea55f1759407ad5175ad)]:
+  - @mastra/core@1.57.0
+
+## 1.1.0-alpha.0
+
+### Minor Changes
+
+- `PlatformSandbox.executeCommand` can now dial the sandbox directly over Railway's private network instead of going through the platform's public exec proxy. On paths where the direct route is available, per-exec latency drops from ~400 ms p50 to ~16 ms p50, and the exec stops touching the platform control plane. This flows through to every filesystem call (`SandboxFilesystem.readFile`, `writeFile`, `readdir`, `mkdir`, `stat`, `exists`, `copyFile`, `moveFile`, `deleteFile`), which is where most agent tool time was going. ([#20664](https://github.com/mastra-ai/mastra/pull/20664))
+
+  Direct-path availability is a runtime property, not a configuration knob. When it's not available — no address registry wired up, the workspace-proxy hasn't discovered the sandbox address yet, or a direct dial fails — `executeCommand` transparently falls back to the existing exec-lease path with no behavior change. Timed-out execs are never retried on the fallback path (they're returned to the caller as-is), so this is safe for non-idempotent commands.
+
+  ### Enabling the direct path
+
+  Wire a `SandboxAddressRegistry` into `PlatformSandbox`:
+
+  ```ts
+  import { PlatformSandbox, InProcessSandboxAddressRegistry } from '@mastra/platform-workspace';
+
+  const registry = new InProcessSandboxAddressRegistry();
+
+  const sandbox = new PlatformSandbox({
+    accessToken: process.env.MASTRA_PLATFORM_ACCESS_TOKEN,
+    projectId: process.env.MASTRA_PLATFORM_PROJECT_ID,
+    environmentId: process.env.MASTRA_PLATFORM_ENVIRONMENT_ID,
+    addressRegistry: registry,
+  });
+  ```
+
+  `PlatformSandbox.start()` populates the registry from the workspace-proxy's response; `executeCommand` reads it, tries the direct path first, evicts on transport failure. `destroy()` also evicts. `clone()` shares the same registry — each child sandbox looks up its own id.
+
+  ### New public exports
+  - `SandboxAddressRegistry` — the `{ get, set, delete }` interface `PlatformSandbox` sees. Callers can implement their own (e.g. shared across a worker pool) or use the default.
+  - `InProcessSandboxAddressRegistry` — the default `Map`-backed implementation.
+  - `PlatformSandboxOptions.addressRegistry?` — DI seam. Optional; omitted keeps pre-existing behavior.
+  - `execViaPrivateNetwork`, `PrivateNetExecHttpError`, `PrivateNetExecOptions`, `PrivateNetExecResult`, `PrivateNetFetch` — standalone transport for callers that want to talk to a sandbox directly without going through `PlatformSandbox`.
+
+### Patch Changes
+
+- Updated dependencies [[`89200ba`](https://github.com/mastra-ai/mastra/commit/89200bafa05444bb7949b363ce7b743e29867561), [`c950138`](https://github.com/mastra-ai/mastra/commit/c950138e72e4f317a40187e3800588731ab790ce), [`063c8b2`](https://github.com/mastra-ai/mastra/commit/063c8b2eb14e4e5ca021779bc33e8c3c031c8604), [`f4e964c`](https://github.com/mastra-ai/mastra/commit/f4e964cad57057301d6bed5c55bcdd730175b941), [`1f7bbd7`](https://github.com/mastra-ai/mastra/commit/1f7bbd7785a8d230aad02454ecabeb4a0b2cc96f), [`e47ff36`](https://github.com/mastra-ai/mastra/commit/e47ff36945720f4ee4caa09f6e83514d7d188608), [`fb9a6ac`](https://github.com/mastra-ai/mastra/commit/fb9a6ac11c9560518742ece60b49d6b062845fd3), [`aa2cec8`](https://github.com/mastra-ai/mastra/commit/aa2cec8501f634d51c2f3ebfb3dd3aa7af8d2ca2), [`2adf8eb`](https://github.com/mastra-ai/mastra/commit/2adf8eb4a70ed2b6cff2dd39281496ea0e025fac), [`8264611`](https://github.com/mastra-ai/mastra/commit/8264611510e421b818bc7395dc2ae4d9c2d518b2), [`44fc98b`](https://github.com/mastra-ai/mastra/commit/44fc98b9d1242aa87a3ab44bdce9e9f12c44d8c9), [`0f2ef41`](https://github.com/mastra-ai/mastra/commit/0f2ef4118da022e4f30dac4e9856cc3a8c97671c)]:
+  - @mastra/core@1.57.0-alpha.1
+
 ## 1.0.0
 
 ### Major Changes

package/dist/address-registry.d.ts

@@ -0,0 +1,47 @@
+/**
+ * In-process `sandboxId → instanceUrl` registry populated by
+ * {@link PlatformSandbox.start} from the `instanceUrl` field workspace-proxy
+ * includes on create + get responses, and consumed by
+ * {@link PlatformSandbox.executeCommand} on the private-network fast path.
+ *
+ * The registry lives in the same Node process as the `PlatformSandbox`
+ * consumer — for shipyard, that is the Mastra runtime deployed from
+ * `mastracode/web`. There is no receiver route and no cross-service dance;
+ * the address is just a field copied from a response the runtime already
+ * receives.
+ *
+ * State intentionally does not persist:
+ *
+ *  - The IPv6 rotates on every sandbox recreate.
+ *  - The URL has no meaning after the sandbox is destroyed.
+ *  - The live sandbox binding, session context, and lease all die with the
+ *    runtime process; the address dying with them is correct.
+ *  - The proxy's `environment_sandboxes.instance_url` column is the durable
+ *    source of truth — a runtime restart re-populates the registry on the
+ *    next `start()` / reattach from the proxy's response.
+ */
+import type { SandboxAddressRegistry } from './sandbox.js';
+/**
+ * Concrete in-process {@link SandboxAddressRegistry}. Backed by a `Map`; no
+ * eviction policy, no TTL — entries live until an observed transport failure
+ * calls `delete`, until the sandbox is explicitly destroyed, or until the
+ * process exits.
+ */
+export declare class InProcessSandboxAddressRegistry implements SandboxAddressRegistry {
+    #private;
+    get(sandboxId: string): string | undefined;
+    /**
+     * Populate or overwrite the address for a sandbox. Called by
+     * {@link PlatformSandbox.start} on every fresh provision and every reattach;
+     * overwriting is intentional so a re-provision with a fresh IPv6 heals the
+     * map without a branch.
+     */
+    set(sandboxId: string, instanceUrl: string): void;
+    delete(sandboxId: string): void;
+    /**
+     * Test-only introspection. Not part of {@link SandboxAddressRegistry} —
+     * production callers must not read the registry as a whole.
+     */
+    get size(): number;
+}
+//# sourceMappingURL=address-registry.d.ts.map

package/dist/address-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"address-registry.d.ts","sourceRoot":"","sources":["../src/address-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAE3D;;;;;GAKG;AACH,qBAAa,+BAAgC,YAAW,sBAAsB;;IAG5E,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI1C;;;;;OAKG;IACH,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAIjD,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI/B;;;OAGG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/index.cjs

@@ -512,6 +512,175 @@ function execViaLease(lease, options) {
 	});
 }
 //#endregion
+//#region src/private-net-exec.ts
+/**
+* Thrown by {@link execViaPrivateNetwork} when the sidecar returns a non-2xx
+* HTTP response. This is an *application* error, not a transport error — the
+* sidecar is reachable and answered, it just refused the exec. Callers should
+* fall back to the lease path for this one call but MUST NOT invalidate the
+* cached `instanceUrl` (the address is still good).
+*/
+var PrivateNetExecHttpError = class extends Error {
+	status;
+	body;
+	constructor(status, body) {
+		super(`Sidecar /exec returned ${status}${body ? `: ${body.slice(0, 200)}` : ""}`);
+		this.name = "PrivateNetExecHttpError";
+		this.status = status;
+		this.body = body;
+	}
+};
+const DEFAULT_FETCH = (input, init) => {
+	const f = globalThis.fetch;
+	if (!f) throw new Error("Private-network exec requires a fetch implementation. Node 22+ provides one globally; on older runtimes, pass fetch explicitly.");
+	return f(input, init);
+};
+/**
+* Dial `${instanceUrl}/exec` and stream the response, resolving with the
+* accumulated stdout/stderr + exit code.
+*
+* Errors:
+* - Connection failure (DNS, refused, reset) → resolves with
+*   `{opened:false, exitCode:null, transportErrorMessage}`. Never throws for
+*   transport failures — the shape matches the lease-path result so the
+*   caller can treat both transports uniformly.
+* - Non-2xx HTTP response from the sidecar → throws {@link PrivateNetExecHttpError}.
+*   Application-level; caller decides whether to fall back.
+* - Stream ends without an `exit` frame → resolves with
+*   `{opened:true, exitCode:null}`, matching the lease-path semantics for a
+*   mid-stream drop.
+* - `timeoutMs` elapsed → aborts the request, resolves with
+*   `{timedOut:true, exitCode:124}`.
+*/
+async function execViaPrivateNetwork(instanceUrl, options) {
+	const fetchImpl = options.fetch ?? DEFAULT_FETCH;
+	const url = `${instanceUrl.replace(/\/$/, "")}/exec`;
+	const controller = new AbortController();
+	let timedOut = false;
+	let timeoutTimer;
+	if (options.timeoutMs !== void 0 && options.timeoutMs > 0) timeoutTimer = setTimeout(() => {
+		timedOut = true;
+		controller.abort();
+	}, options.timeoutMs);
+	const body = { command: options.command };
+	if (options.cwd) body.cwd = options.cwd;
+	if (options.env && Object.keys(options.env).length > 0) body.env = options.env;
+	if (options.timeoutMs !== void 0 && options.timeoutMs > 0) body.timeoutMs = options.timeoutMs;
+	const headers = { "content-type": "application/json" };
+	if (options.bearerToken) headers.authorization = `Bearer ${options.bearerToken}`;
+	let response;
+	try {
+		response = await fetchImpl(url, {
+			method: "POST",
+			headers,
+			body: JSON.stringify(body),
+			signal: controller.signal
+		});
+	} catch (error) {
+		if (timeoutTimer) clearTimeout(timeoutTimer);
+		if (timedOut) return {
+			exitCode: 124,
+			stdout: "",
+			stderr: "",
+			timedOut: true,
+			opened: false
+		};
+		return {
+			exitCode: null,
+			stdout: "",
+			stderr: "",
+			timedOut: false,
+			opened: false,
+			transportErrorMessage: error instanceof Error ? error.message : String(error)
+		};
+	}
+	if (!response.ok) {
+		if (timeoutTimer) clearTimeout(timeoutTimer);
+		const text = await response.text().catch(() => "");
+		throw new PrivateNetExecHttpError(response.status, text);
+	}
+	if (!response.body) {
+		if (timeoutTimer) clearTimeout(timeoutTimer);
+		return {
+			exitCode: null,
+			stdout: "",
+			stderr: "",
+			timedOut: false,
+			opened: true,
+			status: response.status
+		};
+	}
+	let stdout = "";
+	let stderr = "";
+	let exitCode = null;
+	const decoder = new TextDecoder();
+	let buffer = "";
+	const handleLine = (line) => {
+		if (!line) return;
+		let frame;
+		try {
+			frame = JSON.parse(line);
+		} catch {
+			return;
+		}
+		if (!frame || typeof frame !== "object") return;
+		if (frame.type === "stdout" && typeof frame.data === "string") {
+			stdout += frame.data;
+			options.onStdout?.(frame.data);
+		} else if (frame.type === "stderr" && typeof frame.data === "string") {
+			stderr += frame.data;
+			options.onStderr?.(frame.data);
+		} else if (frame.type === "exit" && typeof frame.code === "number") exitCode = frame.code;
+	};
+	try {
+		const reader = response.body.getReader();
+		while (true) {
+			const { value, done } = await reader.read();
+			if (done) break;
+			buffer += decoder.decode(value, { stream: true });
+			let newlineIdx = buffer.indexOf("\n");
+			while (newlineIdx !== -1) {
+				const line = buffer.slice(0, newlineIdx).trim();
+				buffer = buffer.slice(newlineIdx + 1);
+				handleLine(line);
+				newlineIdx = buffer.indexOf("\n");
+			}
+		}
+		buffer += decoder.decode();
+		const trailing = buffer.trim();
+		if (trailing) handleLine(trailing);
+	} catch (error) {
+		if (timeoutTimer) clearTimeout(timeoutTimer);
+		if (timedOut) return {
+			exitCode: 124,
+			stdout,
+			stderr,
+			timedOut: true,
+			opened: true,
+			status: response.status
+		};
+		return {
+			exitCode,
+			stdout,
+			stderr,
+			timedOut: false,
+			opened: true,
+			status: response.status,
+			transportErrorMessage: error instanceof Error ? error.message : String(error)
+		};
+	} finally {
+		if (timeoutTimer) clearTimeout(timeoutTimer);
+	}
+	return {
+		exitCode,
+		stdout,
+		stderr,
+		timedOut: false,
+		opened: true,
+		status: response.status
+	};
+}
+//#endregion
 //#region src/sandbox.ts
 /**
 * How long before a lease's stated `expiresAt` we should treat it as
@@ -662,6 +831,19 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 	_instructionsOverride;
 	_createdAt = null;
 	_webSocketFactory;
+	_privateNetFetch;
+	/**
+	* Registry that maps `sandboxId → instanceUrl` for the private-network
+	* exec path. Injected by the composition site via
+	* {@link PlatformSandboxOptions.addressRegistry} and populated by this
+	* class itself in `start()` when the workspace-proxy's create/reattach
+	* response includes an `instanceUrl` field. The registry IS the cache —
+	* there is no per-instance mirror on `PlatformSandbox`, so every exec is
+	* a `Map.get()` (in the default in-process impl) against the live view.
+	* When absent, executes go straight to the lease path with no extra
+	* round-trip.
+	*/
+	_addressRegistry;
 	/**
 	* Cached exec lease for this sandbox. `null` before the first exec and
 	* after {@link destroy}. Refreshed when `expiresAt - LEASE_REFRESH_MARGIN_MS < now`
@@ -693,6 +875,8 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 		this._timeout = options.timeout;
 		this._instructionsOverride = options.instructions;
 		this._webSocketFactory = options.webSocketFactory;
+		this._privateNetFetch = options.privateNetFetch;
+		this._addressRegistry = options.addressRegistry;
 	}
 	generateId() {
 		return `platform-sandbox-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
@@ -723,7 +907,9 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 			env: options.env ?? this._env,
 			...this._timeout !== void 0 && { timeout: this._timeout },
 			...this._instructionsOverride !== void 0 && { instructions: this._instructionsOverride },
-			...this._webSocketFactory !== void 0 && { webSocketFactory: this._webSocketFactory }
+			...this._webSocketFactory !== void 0 && { webSocketFactory: this._webSocketFactory },
+			...this._privateNetFetch !== void 0 && { privateNetFetch: this._privateNetFetch },
+			...this._addressRegistry !== void 0 && { addressRegistry: this._addressRegistry }
 		});
 	}
 	async start() {
@@ -731,6 +917,7 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 			const json = await (await this._client.request(`/sandbox/${encodeURIComponent(this._sandboxId)}`)).json();
 			if (!json.destroyedAt) {
 				this._createdAt = json.createdAt ? new Date(json.createdAt) : /* @__PURE__ */ new Date();
+				this._populateAddressFromResponse(json);
 				return;
 			}
 			this._sandboxId = void 0;
@@ -761,16 +948,40 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 		const json = await response.json();
 		this._sandboxId = json.id;
 		this._createdAt = json.createdAt ? new Date(json.createdAt) : /* @__PURE__ */ new Date();
+		this._populateAddressFromResponse(json);
+	}
+	/**
+	* Copy `response.instanceUrl` into the injected {@link SandboxAddressRegistry}
+	* when both are present. Called from both {@link start} branches (fresh
+	* provision + reattach) with the workspace-proxy response for this sandbox.
+	*
+	* The proxy discovers the IPv6 during `Sandbox.create()` and stores it in
+	* `environment_sandboxes.instance_url`; both the create response and
+	* `GET /sandbox/:id` echo the same field. The runtime does not do any
+	* discovery of its own — it only mirrors the field into an in-process map
+	* so {@link executeCommand} can `Map.get()` before every exec without an
+	* HTTP round-trip.
+	*
+	* `null`/absent `instanceUrl` (proxy discovery failed, or an older proxy
+	* that predates the field) leaves the registry untouched — executes fall
+	* through to the lease path with no branch here.
+	*/
+	_populateAddressFromResponse(json) {
+		if (!this._addressRegistry) return;
+		if (!json.instanceUrl) return;
+		this._addressRegistry.set(json.id, json.instanceUrl);
 	}
 	async stop() {
 		await this.destroy();
 	}
 	async destroy() {
 		if (!this._sandboxId) return;
-		await this._client.request(`/sandbox/${encodeURIComponent(this._sandboxId)}`, { method: "DELETE" });
+		const destroyedSandboxId = this._sandboxId;
+		await this._client.request(`/sandbox/${encodeURIComponent(destroyedSandboxId)}`, { method: "DELETE" });
 		this._sandboxId = void 0;
 		this._createdAt = null;
 		this._lease = null;
+		this._addressRegistry?.delete(destroyedSandboxId);
 	}
 	/**
 	* Execute a command on the remote sandbox.
@@ -795,6 +1006,22 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 		const started = Date.now();
 		const fullCommand = buildCommand(command, args);
 		const effectiveTimeout = options?.timeout ?? this._timeout;
+		const instanceUrl = this._addressRegistry?.get(this._sandboxId);
+		if (instanceUrl) {
+			const privateNet = await this._tryExecViaPrivateNetwork(instanceUrl, fullCommand, effectiveTimeout, options);
+			if (privateNet) {
+				const privateExit = privateNet.exitCode ?? 124;
+				return {
+					success: privateExit === 0,
+					exitCode: privateExit,
+					stdout: privateNet.stdout,
+					stderr: privateNet.stderr,
+					timedOut: privateNet.timedOut,
+					command: fullCommand,
+					executionTimeMs: Date.now() - started
+				};
+			}
+		}
 		const result = await this._runDirectExec(fullCommand, effectiveTimeout, options);
 		const exitCode = result.exitCode ?? 124;
 		return {
@@ -877,6 +1104,55 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 		});
 	}
 	/**
+	* Try to run the exec against the in-sandbox sidecar over Railway's private
+	* network. Returns the result on success (including non-zero exit codes and
+	* timeouts — those are real command results, not failures). Returns
+	* `undefined` when the caller should fall back to the lease path:
+	*
+	* - Transport failure (connection refused, mid-stream drop, no `exit`
+	*   frame). The registry entry is evicted so subsequent execs skip the
+	*   private-net dial until the sidecar re-registers.
+	* - Sidecar answered with a non-2xx HTTP status. Registry is left intact —
+	*   the address is still valid; something else is wrong (bad request,
+	*   sidecar bug). Only this specific exec falls back.
+	*/
+	async _tryExecViaPrivateNetwork(instanceUrl, fullCommand, effectiveTimeout, options) {
+		const filteredEnv = options?.env ? Object.fromEntries(Object.entries(options.env).filter((entry) => entry[1] !== void 0)) : void 0;
+		const execOptions = {
+			command: fullCommand,
+			...options?.cwd !== void 0 && { cwd: options.cwd },
+			...filteredEnv !== void 0 && { env: filteredEnv },
+			...effectiveTimeout != null && effectiveTimeout > 0 && { timeoutMs: effectiveTimeout },
+			...this._privateNetFetch && { fetch: this._privateNetFetch }
+		};
+		let result;
+		try {
+			result = await execViaPrivateNetwork(instanceUrl, execOptions);
+		} catch (error) {
+			if (error instanceof PrivateNetExecHttpError) return;
+			this._invalidateAddress();
+			return;
+		}
+		if (result.timedOut) {
+			if (!result.opened) this._invalidateAddress();
+			return result;
+		}
+		if (!result.opened || result.exitCode === null) {
+			this._invalidateAddress();
+			return;
+		}
+		return result;
+	}
+	/**
+	* Evict this sandbox's entry from the address registry after an observed
+	* transport failure. The entry stays gone until the next start() re-reads
+	* `instanceUrl` from a workspace-proxy response — until then, execs skip
+	* the private-net dial and go straight to the lease path.
+	*/
+	_invalidateAddress() {
+		if (this._sandboxId) this._addressRegistry?.delete(this._sandboxId);
+	}
+	/**
 	* Return a cached exec lease, minting a fresh one when the cache is empty
 	* or the JWT is within {@link LEASE_REFRESH_MARGIN_MS} of `expiresAt`.
 	*
@@ -1018,12 +1294,48 @@ const platformFilesystemProvider = {
 	createFilesystem: (config) => new PlatformFilesystem(config)
 };
 //#endregion
+//#region src/address-registry.ts
+/**
+* Concrete in-process {@link SandboxAddressRegistry}. Backed by a `Map`; no
+* eviction policy, no TTL — entries live until an observed transport failure
+* calls `delete`, until the sandbox is explicitly destroyed, or until the
+* process exits.
+*/
+var InProcessSandboxAddressRegistry = class {
+	#map = /* @__PURE__ */ new Map();
+	get(sandboxId) {
+		return this.#map.get(sandboxId);
+	}
+	/**
+	* Populate or overwrite the address for a sandbox. Called by
+	* {@link PlatformSandbox.start} on every fresh provision and every reattach;
+	* overwriting is intentional so a re-provision with a fresh IPv6 heals the
+	* map without a branch.
+	*/
+	set(sandboxId, instanceUrl) {
+		this.#map.set(sandboxId, instanceUrl);
+	}
+	delete(sandboxId) {
+		this.#map.delete(sandboxId);
+	}
+	/**
+	* Test-only introspection. Not part of {@link SandboxAddressRegistry} —
+	* production callers must not read the registry as a whole.
+	*/
+	get size() {
+		return this.#map.size;
+	}
+};
+//#endregion
+exports.InProcessSandboxAddressRegistry = InProcessSandboxAddressRegistry;
 exports.PlatformApiError = PlatformApiError;
 exports.PlatformClient = PlatformClient;
 exports.PlatformFilesystem = PlatformFilesystem;
 exports.PlatformSandbox = PlatformSandbox;
+exports.PrivateNetExecHttpError = PrivateNetExecHttpError;
 exports.SandboxDestroyedError = SandboxDestroyedError;
 exports.SandboxExecTransportError = SandboxExecTransportError;
+exports.execViaPrivateNetwork = execViaPrivateNetwork;
 exports.platformFilesystemProvider = platformFilesystemProvider;
 exports.platformSandboxProvider = platformSandboxProvider;