@mastra/platform-workspace 1.4.1 → 1.5.0-alpha.1

package/dist/index.d.ts

@@ -1,6 +1,8 @@
-export { PlatformClient, PlatformApiError, type PlatformClientOptions, type PlatformProxyError } from './client.js';
+export { PlatformClient, PlatformApiError, type PlatformClientOptions, type PlatformProxyError, type SandboxProvider, } from './client.js';
 export { PlatformFilesystem, type PlatformFilesystemOptions } from './filesystem.js';
-export { PlatformSandbox, SandboxExecTransportError, SandboxDestroyedError, type PlatformSandboxOptions, type PlatformSandboxNetworkIsolation, type SandboxAddressRegistry, } from './sandbox.js';
+export { Template, type AptInstallOptions, type JsonPrimitive, type JsonValue, type NpmInstallOptions, type PipInstallOptions, type SandboxTemplateBuildOptions, type SandboxTemplateBuildResult, type SandboxTemplateBuilder, type SandboxTemplateMethod, type SetEnvsOptions, type SandboxTemplateOperation, type SerializedSandboxTemplate, } from './template.js';
+export { PlatformSandbox, SandboxExecTransportError, SandboxDestroyedError, type PlatformSandboxOptions, type PlatformSandboxNetworkIsolation, type PlatformSandboxTemplate, type SandboxAddressRegistry, type SandboxTemplatePending, } from './sandbox.js';
+export { createRepoTemplate, type PlatformRepoTemplateOptions, type PlatformRepoTemplateResolver, } from './repo-template.js';
 export { platformFilesystemProvider, platformSandboxProvider } from './provider.js';
 export { execViaPrivateNetwork, PrivateNetExecHttpError, type PrivateNetExecOptions, type PrivateNetExecResult, type PrivateNetFetch, } from './private-net-exec.js';
 export { InProcessSandboxAddressRegistry } from './address-registry.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,KAAK,qBAAqB,EAAE,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACpH,OAAO,EAAE,kBAAkB,EAAE,KAAK,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AACrF,OAAO,EACL,eAAe,EACf,yBAAyB,EACzB,qBAAqB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,+BAA+B,EACpC,KAAK,sBAAsB,GAC5B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,0BAA0B,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AACpF,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,eAAe,GACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,+BAA+B,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,eAAe,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,KAAK,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AACrF,OAAO,EACL,QAAQ,EACR,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,SAAS,EACd,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,GAC/B,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,eAAe,EACf,yBAAyB,EACzB,qBAAqB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,+BAA+B,EACpC,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,GAC5B,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,kBAAkB,EAClB,KAAK,2BAA2B,EAChC,KAAK,4BAA4B,GAClC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,0BAA0B,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AACpF,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,eAAe,GACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,+BAA+B,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -1,7 +1,9 @@
-import { Buffer } from "buffer";
+import { Buffer as Buffer$1 } from "buffer";
 import nodePath from "path";
 import { FileExistsError, FileNotFoundError, MastraFilesystem, MastraSandbox, ProcessHandle, SandboxNotReadyError, SandboxProcessManager, UnsupportedStdinCloseError, WorkspaceReadOnlyError } from "@mastra/core/workspace";
 import { CommandExitError, Sandbox, TimeoutError } from "e2b";
+import { execFile } from "child_process";
+import { promisify } from "util";
 //#region src/client.ts
 const DEFAULT_PROXY_URL = "https://workspaces.mastra.ai";
 /**
@@ -15,19 +17,19 @@ function requireOption(value, name) {
 	return value;
 }
 function resolveSandboxProvider(value) {
-	const provider = value?.trim() || "railway";
+	const provider = value?.trim() || "e2b";
 	if (provider !== "railway" && provider !== "e2b") throw new Error("SANDBOX_PROVIDER must be either \"railway\" or \"e2b\"");
 	return provider;
 }
 function resolvePlatformOptions(options) {
-	const configuredSandboxProvider = process.env.SANDBOX_PROVIDER?.trim();
+	const environmentSandboxProvider = process.env.SANDBOX_PROVIDER?.trim();
+	const configuredSandboxProvider = options.sandboxProvider ?? environmentSandboxProvider;
 	return {
 		accessToken: requireOption(options.accessToken ?? process.env.MASTRA_PLATFORM_ACCESS_TOKEN, "accessToken"),
 		projectId: requireOption(options.projectId ?? process.env.MASTRA_PROJECT_ID, "projectId"),
 		actingUserId: options.actingUserId?.trim() || void 0,
 		proxyUrl: (process.env.MASTRA_WORKSPACE_PROXY_URL ?? DEFAULT_PROXY_URL).replace(/\/$/, ""),
 		sandboxProvider: resolveSandboxProvider(configuredSandboxProvider),
-		useLegacyRoutes: !configuredSandboxProvider,
 		sessionId: options.sessionId,
 		threadId: options.threadId,
 		fetch: options.fetch ?? fetch
@@ -75,7 +77,6 @@ var PlatformClient = class {
 	actingUserId;
 	proxyUrl;
 	sandboxProvider;
-	useLegacyRoutes;
 	/** Advisory session correlation id — see {@link PlatformClientOptions.sessionId}. */
 	sessionId;
 	/** Advisory thread correlation id — see {@link PlatformClientOptions.threadId}. */
@@ -88,13 +89,17 @@ var PlatformClient = class {
 		this.actingUserId = resolved.actingUserId;
 		this.proxyUrl = resolved.proxyUrl;
 		this.sandboxProvider = resolved.sandboxProvider;
-		this.useLegacyRoutes = resolved.useLegacyRoutes;
 		this.sessionId = resolved.sessionId;
 		this.threadId = resolved.threadId;
 		this.fetch = resolved.fetch;
 	}
 	async request(path, options = {}) {
-		const providerPath = this.useLegacyRoutes ? "" : `/${this.sandboxProvider}`;
+		return this.requestAtPath(`/${this.sandboxProvider}`, path, options);
+	}
+	async requestProvider(path, options = {}) {
+		return this.requestAtPath(`/${this.sandboxProvider}`, path, options);
+	}
+	async requestAtPath(providerPath, path, options) {
 		const url = new URL(`${this.proxyUrl}/v1${providerPath}/projects/${encodeURIComponent(this.projectId)}${path}`);
 		for (const [key, value] of Object.entries(options.query ?? {})) if (value !== void 0) url.searchParams.set(key, String(value));
 		const headers = new Headers(options.headers);
@@ -141,7 +146,7 @@ function nameFromPath(path) {
 }
 function contentToBody(content) {
 	if (typeof content === "string") return content;
-	return Buffer.from(content);
+	return Buffer$1.from(content);
 }
 function headerDate(headers, name) {
 	const value = headers.get(name);
@@ -193,7 +198,7 @@ var PlatformFilesystem = class extends MastraFilesystem {
 			if (isNotFound(error)) throw new FileNotFoundError(path);
 			throw error;
 		}
-		const buffer = Buffer.from(await response.arrayBuffer());
+		const buffer = Buffer$1.from(await response.arrayBuffer());
 		return options?.encoding ? buffer.toString(options.encoding) : buffer;
 	}
 	async writeFile(path, content, options) {
@@ -224,8 +229,8 @@ var PlatformFilesystem = class extends MastraFilesystem {
 	* Use `writeFile` with distinct keys for concurrent writers.
 	*/
 	async appendFile(path, content) {
-		const existing = await this.exists(path) ? await this.readFile(path) : Buffer.alloc(0);
-		await this.writeFile(path, Buffer.concat([Buffer.isBuffer(existing) ? existing : Buffer.from(existing), Buffer.from(content)]));
+		const existing = await this.exists(path) ? await this.readFile(path) : Buffer$1.alloc(0);
+		await this.writeFile(path, Buffer$1.concat([Buffer$1.isBuffer(existing) ? existing : Buffer$1.from(existing), Buffer$1.from(content)]));
 	}
 	async deleteFile(path, options) {
 		await this.ensureReady();
@@ -362,6 +367,185 @@ function matchesExtension(name, extension) {
 	return (Array.isArray(extension) ? extension : [extension]).some((ext) => name.endsWith(ext));
 }
 //#endregion
+//#region src/template.ts
+const SERIALIZE_TEMPLATE = Symbol("serializeTemplate");
+const GET_TEMPLATE_BUILD_ENVS = Symbol("getTemplateBuildEnvs");
+const MAX_OPERATIONS = 256;
+const MAX_SERIALIZED_BYTES = 256 * 1024;
+const MAX_STRING_LENGTH = 32 * 1024;
+const MAX_COLLECTION_ITEMS = 512;
+const MAX_FAMILY_LENGTH = 200;
+var SerializableSandboxTemplateBuilder = class SerializableSandboxTemplateBuilder {
+	#operations;
+	#family;
+	#buildEnvs;
+	constructor(operations = [], family, buildEnvs = {}) {
+		this.#operations = operations;
+		this.#family = family;
+		this.#buildEnvs = buildEnvs;
+	}
+	cpuCount(count) {
+		return this.#append("cpuCount", [validateResourceValue(count, "count")]);
+	}
+	memoryMB(memoryMB) {
+		return this.#append("memoryMB", [validateResourceValue(memoryMB, "memoryMB")]);
+	}
+	async build(options = {}) {
+		return buildSandboxTemplate(this, options);
+	}
+	runCmd(command) {
+		return this.#append("runCmd", [validateStringOrStrings(command, "command")]);
+	}
+	setWorkdir(path) {
+		return this.#append("setWorkdir", [validateString(path, "path")]);
+	}
+	setEnvs(envs, options) {
+		const copy = validateStringRecord(envs, "envs", "environment variable");
+		if ((options === void 0 ? void 0 : validateBooleanOptions(options, ["ephemeral"]))?.ephemeral === true) return new SerializableSandboxTemplateBuilder(this.#operations, this.#family, {
+			...this.#buildEnvs,
+			...copy
+		});
+		return this.#append("setEnvs", [copy]);
+	}
+	aptInstall(packages, options) {
+		const args = [validateStringOrStrings(packages, "packages")];
+		if (options !== void 0) args.push(validateBooleanOptions(options, ["noInstallRecommends", "fixMissing"]));
+		return this.#append("aptInstall", args);
+	}
+	pipInstall(packages, options) {
+		return this.#appendOptionalInstall("pipInstall", packages, options, ["g"]);
+	}
+	npmInstall(packages, options) {
+		return this.#appendOptionalInstall("npmInstall", packages, options, ["g", "dev"]);
+	}
+	withFamily(family) {
+		if (typeof family !== "string" || family.length === 0) throw new TypeError("family must be a non-empty string");
+		if (family.length > MAX_FAMILY_LENGTH) throw new RangeError(`family cannot exceed ${MAX_FAMILY_LENGTH} characters`);
+		assertSerializedSize(this.#operations, family);
+		return new SerializableSandboxTemplateBuilder(this.#operations, family, this.#buildEnvs);
+	}
+	[GET_TEMPLATE_BUILD_ENVS]() {
+		return Object.keys(this.#buildEnvs).length > 0 ? { ...this.#buildEnvs } : void 0;
+	}
+	[SERIALIZE_TEMPLATE]() {
+		return {
+			schemaVersion: 1,
+			operations: this.#operations.map((operation) => ({
+				method: operation.method,
+				args: cloneJson(operation.args)
+			})),
+			...this.#family !== void 0 && { family: this.#family }
+		};
+	}
+	#appendOptionalInstall(method, packages, options, optionKeys) {
+		const args = [];
+		if (packages !== void 0) args.push(validateStringOrStrings(packages, "packages"));
+		if (options !== void 0) {
+			if (packages === void 0) args.push(null);
+			args.push(validateBooleanOptions(options, optionKeys));
+		}
+		return this.#append(method, args);
+	}
+	#append(method, args) {
+		if (this.#operations.length >= MAX_OPERATIONS) throw new RangeError(`Sandbox template cannot contain more than ${MAX_OPERATIONS} operations`);
+		const operation = {
+			method,
+			args: cloneJson(args)
+		};
+		const operations = [...this.#operations, operation];
+		assertSerializedSize(operations, this.#family);
+		return new SerializableSandboxTemplateBuilder(operations, this.#family, this.#buildEnvs);
+	}
+};
+function assertSerializedSize(operations, family) {
+	const serialized = JSON.stringify({
+		schemaVersion: 1,
+		operations,
+		...family !== void 0 && { family }
+	});
+	if (new TextEncoder().encode(serialized).byteLength > MAX_SERIALIZED_BYTES) throw new RangeError(`Serialized sandbox template cannot exceed ${MAX_SERIALIZED_BYTES} bytes`);
+}
+function Template() {
+	return new SerializableSandboxTemplateBuilder();
+}
+function isSandboxTemplateBuilder(value) {
+	return value instanceof SerializableSandboxTemplateBuilder;
+}
+function serializeSandboxTemplate(template) {
+	if (!isSandboxTemplateBuilder(template)) throw new TypeError("template must be created with Template()");
+	return template[SERIALIZE_TEMPLATE]();
+}
+function getSandboxTemplateBuildEnvs(template) {
+	if (!isSandboxTemplateBuilder(template)) throw new TypeError("template must be created with Template()");
+	return template[GET_TEMPLATE_BUILD_ENVS]();
+}
+async function buildSandboxTemplate(template, options) {
+	const environmentId = options.environmentId ?? process.env.MASTRA_ENVIRONMENT_ID;
+	if (!environmentId) throw new Error("environmentId is required. Pass it or set MASTRA_ENVIRONMENT_ID.");
+	const client = new PlatformClient(options);
+	const templateBuildEnvs = getSandboxTemplateBuildEnvs(template);
+	return await (await client.requestProvider("/sandbox/templates/builds", {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify({
+			environmentId,
+			templateDefinition: serializeSandboxTemplate(template),
+			...templateBuildEnvs !== void 0 && { templateBuildEnvs }
+		})
+	})).json();
+}
+function validateResourceValue(value, name) {
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) throw new TypeError(`${name} must be a positive safe integer`);
+	return value;
+}
+function validateString(value, name, allowEmpty = false) {
+	if (typeof value !== "string") throw new TypeError(`${name} must be a string`);
+	if (!allowEmpty && value.length === 0) throw new TypeError(`${name} must not be empty`);
+	if (value.length > MAX_STRING_LENGTH) throw new RangeError(`${name} cannot exceed ${MAX_STRING_LENGTH} characters`);
+	return value;
+}
+function validateStringOrStrings(value, name) {
+	if (typeof value === "string") return validateString(value, name);
+	if (!Array.isArray(value)) throw new TypeError(`${name} must be a string or an array of strings`);
+	assertCollectionSize(value.length, name);
+	if (value.length === 0) throw new TypeError(`${name} must not be empty`);
+	return Array.from(value, (item, index) => validateString(item, `${name}[${index}]`));
+}
+function validateStringRecord(value, name, entryName) {
+	assertPlainObject(value, name);
+	const entries = Object.entries(value);
+	assertCollectionSize(entries.length, name);
+	return Object.fromEntries(entries.map(([key, item]) => [validateString(key, `${entryName} name`), validateString(item, `${entryName} ${key}`, true)]));
+}
+function validateBooleanOptions(value, keys) {
+	assertPlainObject(value, "options");
+	const options = value;
+	const unknownKey = Object.keys(options).find((key) => !keys.includes(key));
+	if (unknownKey) throw new TypeError(`Unsupported option: ${unknownKey}`);
+	const copy = {};
+	for (const key of keys) {
+		const option = options[key];
+		if (option === void 0) continue;
+		if (typeof option !== "boolean") throw new TypeError(`${key} must be a boolean`);
+		copy[key] = option;
+	}
+	return copy;
+}
+function assertPlainObject(value, name) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new TypeError(`${name} must be a plain object`);
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) throw new TypeError(`${name} must be a plain object`);
+}
+function assertCollectionSize(size, name) {
+	if (size > MAX_COLLECTION_ITEMS) throw new RangeError(`${name} cannot contain more than ${MAX_COLLECTION_ITEMS} items`);
+}
+function cloneJson(value) {
+	if (Array.isArray(value)) return value.map((item) => cloneJson(item));
+	if (typeof value === "object" && value !== null) return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, cloneJson(item)]));
+	if (typeof value === "number" && !Number.isFinite(value)) throw new TypeError("Sandbox template values must contain only finite numbers");
+	return value;
+}
+//#endregion
 //#region src/direct-exec.ts
 /**
 * Direct exec client — opens Railway's tcp-proxy exec WebSocket directly using
@@ -902,10 +1086,26 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 	name = "PlatformSandbox";
 	provider = "platform";
 	status = "pending";
+	/**
+	* Populated from the platform's create/reattach response when the sandbox
+	* booted from a prior member of the same template family or the provider
+	* base template while the requested exact template continues to build in
+	* the background.
+	* `undefined` when the sandbox booted on the exact template (or when no
+	* template was requested). Observability-only; consumers reconcile freshness
+	* in their own runtime setup and reprovision to pick up the ready template
+	* on a later start.
+	*/
+	templatePending;
 	_client;
+	_usesProviderRoutes;
 	_environmentId;
 	_sandboxId;
 	_seedCheckpointName;
+	_templateDefinition;
+	_templateBuildEnvs;
+	_template;
+	_templateResolutionInFlight;
 	_idleTimeoutMinutes;
 	_networkIsolation;
 	_env;
@@ -993,6 +1193,8 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 		if (!this._environmentId && !options.sandboxId) throw new Error("environmentId is required");
 		this._sandboxId = options.sandboxId;
 		this._seedCheckpointName = options.seedCheckpointName;
+		this._usesProviderRoutes = options.template !== void 0;
+		this._template = options.template;
 		this._idleTimeoutMinutes = options.idleTimeoutMinutes;
 		this._networkIsolation = options.networkIsolation;
 		this._env = options.env ?? {};
@@ -1006,6 +1208,9 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 	generateId() {
 		return `platform-sandbox-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
 	}
+	_request(path, options = {}) {
+		return this._usesProviderRoutes ? this._client.requestProvider(path, options) : this._client.request(path, options);
+	}
 	/**
 	* Construct a sibling {@link PlatformSandbox} that inherits this sandbox's
 	* credentials and defaults (access token, project, environment, network
@@ -1021,10 +1226,11 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 	clone(options = {}) {
 		const id = options.id ?? options.checkpointName;
 		const seedCheckpointName = options.seedCheckpointName ?? (this._client.sandboxProvider === "e2b" ? options.checkpointName : void 0) ?? this._seedCheckpointName;
-		return new PlatformSandbox({
+		const clone = new PlatformSandbox({
 			...id !== void 0 && { id },
 			accessToken: this._client.accessToken,
 			projectId: this._client.projectId,
+			...this._usesProviderRoutes || this._client.sandboxProvider !== "railway" ? { sandboxProvider: this._client.sandboxProvider } : {},
 			actingUserId: options.actingUserId ?? this._client.actingUserId,
 			...this._client.sessionId !== void 0 && { sessionId: this._client.sessionId },
 			...this._client.threadId !== void 0 && { threadId: this._client.threadId },
@@ -1032,6 +1238,7 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 			environmentId: this._environmentId,
 			...options.sandboxId !== void 0 && { sandboxId: options.sandboxId },
 			...seedCheckpointName !== void 0 && { seedCheckpointName },
+			...this._template !== void 0 && { template: this._template },
 			idleTimeoutMinutes: options.idleTimeoutMinutes ?? this._idleTimeoutMinutes,
 			...this._networkIsolation !== void 0 && { networkIsolation: this._networkIsolation },
 			env: options.env ?? this._env,
@@ -1042,6 +1249,9 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 			...this._privateNetFetch !== void 0 && { privateNetFetch: this._privateNetFetch },
 			...this._addressRegistry !== void 0 && { addressRegistry: this._addressRegistry }
 		});
+		clone._templateDefinition = this._templateDefinition ? structuredClone(this._templateDefinition) : void 0;
+		clone._templateBuildEnvs = this._templateBuildEnvs ? { ...this._templateBuildEnvs } : void 0;
+		return clone;
 	}
 	/**
 	* Start the sandbox: reattach to a known provider `sandboxId` when one is
@@ -1060,7 +1270,7 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 		const startedAt = Date.now();
 		if (this._sandboxId) try {
 			const requestStartedAt = Date.now();
-			const response = await this._client.request(`/sandbox/${encodeURIComponent(this._sandboxId)}`);
+			const response = await this._request(`/sandbox/${encodeURIComponent(this._sandboxId)}`);
 			const requestMs = Date.now() - requestStartedAt;
 			const json = await response.json();
 			if (!json.destroyedAt) {
@@ -1075,9 +1285,12 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 			this._sandboxId = void 0;
 		}
 		if (!this._environmentId) throw new Error("environmentId is required");
-		const body = JSON.stringify({
+		await this._prepareLazyTemplate();
+		const createBody = () => JSON.stringify({
 			id: this.id,
 			seedCheckpointName: this._seedCheckpointName,
+			templateDefinition: this._templateDefinition,
+			templateBuildEnvs: this._templateBuildEnvs,
 			environmentId: this._environmentId,
 			idleTimeoutMinutes: this._idleTimeoutMinutes,
 			networkIsolation: this._networkIsolation,
@@ -1086,10 +1299,10 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 		let response;
 		const requestStartedAt = Date.now();
 		for (let attempt = 1;; attempt++) try {
-			response = await this._client.request("/sandbox", {
+			response = await this._request("/sandbox", {
 				method: "POST",
 				headers: { "content-type": "application/json" },
-				body
+				body: createBody()
 			});
 			break;
 		} catch (error) {
@@ -1100,10 +1313,31 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 		const json = await response.json();
 		this._sandboxId = json.id;
 		this._createdAt = json.createdAt ? new Date(json.createdAt) : /* @__PURE__ */ new Date();
+		this.templatePending = json.templatePending;
 		this._populateAddressFromResponse(json);
 		this._logStartComplete(json.id, startedAt, requestMs, "provision");
 		return { outcome: "created" };
 	}
+	async _prepareLazyTemplate() {
+		if (this._templateDefinition !== void 0 || this._template === void 0) return;
+		if (!this._templateResolutionInFlight) {
+			const attempt = this._resolveTemplate();
+			this._templateResolutionInFlight = attempt.finally(() => {
+				this._templateResolutionInFlight = void 0;
+			});
+		}
+		await this._templateResolutionInFlight;
+	}
+	async _resolveTemplate() {
+		try {
+			const resolved = typeof this._template === "function" ? await this._template() : this._template;
+			if (!resolved) return;
+			this._templateDefinition = serializeSandboxTemplate(resolved);
+			this._templateBuildEnvs = getSandboxTemplateBuildEnvs(resolved);
+		} catch (error) {
+			this.logger.warn(`Platform sandbox template resolution failed; using provider default template: ${String(error)}`);
+		}
+	}
 	/**
 	* One timing summary per completed `start()` — the whole
 	* `PlatformSandbox`-visible boot in a single greppable line.
@@ -1268,7 +1502,7 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 		const destroyedSandboxId = this._sandboxId;
 		this._captureInFlight = null;
 		if (this._hasRecoveryKey || this._client.sandboxProvider === "e2b") try {
-			await this._client.request(`/sandbox/${encodeURIComponent(destroyedSandboxId)}/checkpoint`, {
+			await this._request(`/sandbox/${encodeURIComponent(destroyedSandboxId)}/checkpoint`, {
 				method: "DELETE",
 				headers: { "content-type": "application/json" },
 				body: JSON.stringify({ id: this.id })
@@ -1295,7 +1529,7 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 		this._probeGeneration++;
 		this._probeTarget = null;
 		this._transportReadyPromise = null;
-		await this._client.request(`/sandbox/${encodeURIComponent(destroyedSandboxId)}`, { method: "DELETE" });
+		await this._request(`/sandbox/${encodeURIComponent(destroyedSandboxId)}`, { method: "DELETE" });
 		this._sandboxId = void 0;
 		this._createdAt = null;
 		this._lease = null;
@@ -1385,7 +1619,7 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 	async _doCaptureCheckpoint(sandboxId) {
 		let response;
 		try {
-			response = await this._client.request(`/sandbox/${encodeURIComponent(sandboxId)}/checkpoint`, {
+			response = await this._request(`/sandbox/${encodeURIComponent(sandboxId)}/checkpoint`, {
 				method: "POST",
 				headers: { "content-type": "application/json" },
 				body: JSON.stringify({ id: this.id })
@@ -1516,8 +1750,20 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 	* Returns a result with a real `exitCode` OR `timedOut: true`. Never
 	* returns `{ exitCode: null, timedOut: false }` — that case throws.
 	*/
+	/**
+	* Drop undefined values so the result matches the Record<string, string>
+	* shape the exec transports expect (`ExecuteCommandOptions.env` is
+	* NodeJS.ProcessEnv). The sandbox's own env is already merged in by
+	* `executeCommand` before a transport sees these options. Returns undefined
+	* when there is nothing to send.
+	*/
+	_execEnv(options) {
+		if (!options?.env) return void 0;
+		const filtered = Object.fromEntries(Object.entries(options.env).filter((entry) => entry[1] !== void 0));
+		return Object.keys(filtered).length > 0 ? filtered : void 0;
+	}
 	async _runDirectExec(fullCommand, effectiveTimeout, options) {
-		const filteredEnv = options?.env ? Object.fromEntries(Object.entries(options.env).filter((entry) => entry[1] !== void 0)) : void 0;
+		const filteredEnv = this._execEnv(options);
 		let lastResult;
 		let lastLease;
 		let attemptsMade = 0;
@@ -1542,9 +1788,10 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 			}
 			lastLease = lease;
 			attemptsMade = attempt + 1;
+			const leaseCwd = options?.cwd ?? this.workingDirectory;
 			const execOptions = {
 				command: fullCommand,
-				...options?.cwd !== void 0 && { cwd: options.cwd },
+				...leaseCwd !== void 0 && { cwd: leaseCwd },
 				...filteredEnv !== void 0 && { env: filteredEnv },
 				...effectiveTimeout != null && effectiveTimeout > 0 && { timeoutMs: effectiveTimeout },
 				...this._webSocketFactory && { webSocketFactory: this._webSocketFactory }
@@ -1580,10 +1827,11 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 	*   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 filteredEnv = this._execEnv(options);
+		const privateNetCwd = options?.cwd ?? this.workingDirectory;
 		const execOptions = {
 			command: fullCommand,
-			...options?.cwd !== void 0 && { cwd: options.cwd },
+			...privateNetCwd !== void 0 && { cwd: privateNetCwd },
 			...filteredEnv !== void 0 && { env: filteredEnv },
 			...effectiveTimeout != null && effectiveTimeout > 0 && { timeoutMs: effectiveTimeout },
 			...this._privateNetFetch && { fetch: this._privateNetFetch }
@@ -1629,7 +1877,7 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 		if (!this._sandboxId) throw new SandboxNotReadyError(this.id);
 		const sandboxId = this._sandboxId;
 		const inFlight = (async () => {
-			const json = await (await this._client.request(`/sandbox/${encodeURIComponent(sandboxId)}/exec-lease`, { method: "POST" })).json();
+			const json = await (await this._request(`/sandbox/${encodeURIComponent(sandboxId)}/exec-lease`, { method: "POST" })).json();
 			const expiresAtMs = json.expiresAt ? Date.parse(json.expiresAt) : null;
 			const lease = {
 				provider: json.provider,
@@ -1667,7 +1915,7 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 			createdAt: this._createdAt ?? /* @__PURE__ */ new Date(),
 			metadata: { sandboxId: this._sandboxId }
 		};
-		const json = await (await this._client.request(`/sandbox/${encodeURIComponent(this._sandboxId)}`)).json();
+		const json = await (await this._request(`/sandbox/${encodeURIComponent(this._sandboxId)}`)).json();
 		return {
 			id: json.id,
 			name: this.name,
@@ -1692,6 +1940,122 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 	}
 };
 //#endregion
+//#region src/repo-template.ts
+const execFileAsync = promisify(execFile);
+const SHA_PATTERN = /^[0-9a-f]{7,40}$/i;
+const BUILD_TOKEN_ENV = "MASTRA_REPOSITORY_ACCESS_TOKEN";
+/**
+* Clone URLs interpolate into the template's build commands, so constrain
+* them to https plus plain host/path characters. Every regex here is a
+* single anchored character class, so matching stays linear on adversarial
+* input; the structural checks go through WHATWG URL parsing instead of one
+* big backtracking pattern.
+*/
+const CLONE_URL_ALLOWED_CHARS = /^[a-z0-9:/._-]+$/i;
+const CLONE_URL_HOST_PATTERN = /^[a-z0-9.-]+$/i;
+const CLONE_URL_SEGMENT_PATTERN = /^[\w.-]+$/;
+/**
+* Create a lazy repository template definition for PlatformSandbox, mirroring
+* `@mastra/e2b`'s `createRepoTemplate`: pass the sandbox context through and a
+* repo-less session boots the provider default.
+*
+* The resolver performs no work until a fresh sandbox starts. It clones the
+* URL `getRepositoryAccess` resolves — the only source of the clone URL, so
+* what gets cloned and what the template is identified by can't drift — and
+* pins repositories to their current default-branch commit. Private repository
+* credentials are used for head resolution and sent to the provider as
+* transient build envs; they never enter the serialized definition. If the
+* head cannot be resolved, the resolver returns undefined so PlatformSandbox
+* boots from the provider default and the caller's runtime setup materializes
+* the checkout instead.
+*/
+function createRepoTemplate(options) {
+	const getRepositoryAccess = options.getRepositoryAccess;
+	if (!getRepositoryAccess) return void 0;
+	const resolveHead = options.resolveHead ?? resolveDefaultBranchHead;
+	return async () => {
+		const access = await getRepositoryAccess().catch(() => void 0);
+		if (!access?.cloneUrl) return void 0;
+		const cloneUrl = normalizeCloneUrl(access.cloneUrl);
+		if (!isValidCloneUrl(cloneUrl)) return void 0;
+		const token = access.authorization?.token;
+		const sha = await (token ? resolveHead(cloneUrl, token) : resolveHead(cloneUrl)).catch(() => void 0);
+		if (!sha || !SHA_PATTERN.test(sha)) return void 0;
+		const workdir = defaultWorkdir(cloneUrl);
+		const auth = token ? `${gitAuthFlag()} ` : "";
+		const steps = [
+			`git ${auth}clone ${cloneUrl} "${workdir}"`,
+			`git -C "${workdir}" ${auth}fetch origin ${sha}`,
+			`git -C "${workdir}" checkout ${sha}`,
+			...options.setupCommand ? [`cd "${workdir}" && ${options.setupCommand}`] : []
+		];
+		const family = `repo:${cloneUrl}:${workdir}`;
+		let template = Template();
+		if (token) template = template.setEnvs({ [BUILD_TOKEN_ENV]: token }, { ephemeral: true });
+		if (options.cpuCount !== void 0) template = template.cpuCount(options.cpuCount);
+		if (options.memoryMB !== void 0) template = template.memoryMB(options.memoryMB);
+		return template.runCmd(steps).withFamily(family);
+	};
+}
+function isValidCloneUrl(cloneUrl) {
+	if (cloneUrl.length > 2048 || !CLONE_URL_ALLOWED_CHARS.test(cloneUrl)) return false;
+	let url;
+	try {
+		url = new URL(cloneUrl);
+	} catch {
+		return false;
+	}
+	if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash) return false;
+	if (!CLONE_URL_HOST_PATTERN.test(url.hostname)) return false;
+	const segments = url.pathname.split("/").slice(1);
+	return segments.length > 0 && segments.every((segment) => CLONE_URL_SEGMENT_PATTERN.test(segment));
+}
+/**
+* Canonical form used for identity, the family key, and the build's clone:
+* lowercase host, no trailing `.git` or slash. Two spellings of one
+* repository must not produce two templates.
+*/
+function normalizeCloneUrl(cloneUrl) {
+	let end = cloneUrl.length;
+	while (end > 0 && cloneUrl[end - 1] === "/") end--;
+	return cloneUrl.slice(0, end).replace(/\.git$/i, "").replace(/^(https:\/\/)([^/]+)/i, (_match, scheme, host) => {
+		return `${scheme.toLowerCase()}${host.toLowerCase()}`;
+	});
+}
+function defaultWorkdir(cloneUrl) {
+	return `$HOME/${(normalizeCloneUrl(cloneUrl).split("/").at(-1) ?? "").replace(/[^\w.-]/g, "-").replace(/^\.+/, "") || "repo"}`;
+}
+function gitAuthFlag() {
+	return `-c http.extraheader="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$${BUILD_TOKEN_ENV}" | base64 -w0)"`;
+}
+async function resolveDefaultBranchHead(cloneUrl, token, execute = execFileAsync) {
+	try {
+		const env = {
+			...process.env,
+			GIT_TERMINAL_PROMPT: "0"
+		};
+		if (token) {
+			env.GIT_CONFIG_COUNT = "1";
+			env.GIT_CONFIG_KEY_0 = "http.extraheader";
+			env.GIT_CONFIG_VALUE_0 = `AUTHORIZATION: basic ${Buffer.from(`x-access-token:${token}`).toString("base64")}`;
+		}
+		const { stdout } = await execute("git", [
+			"ls-remote",
+			"--",
+			cloneUrl,
+			"HEAD"
+		], {
+			timeout: 1e4,
+			maxBuffer: 1024 * 1024,
+			env
+		});
+		const sha = stdout.trim().split(/\s+/, 1)[0];
+		return sha && SHA_PATTERN.test(sha) ? sha : void 0;
+	} catch {
+		return;
+	}
+}
+//#endregion
 //#region src/provider.ts
 const platformSandboxProvider = {
 	id: "platform",
@@ -1712,6 +2076,12 @@ const platformSandboxProvider = {
 				type: "string",
 				description: "Opaque user subject attributed to sandbox requests"
 			},
+			sandboxProvider: {
+				type: "string",
+				description: "Sandbox provider (falls back to SANDBOX_PROVIDER, then e2b)",
+				enum: ["railway", "e2b"],
+				default: "e2b"
+			},
 			environmentId: {
 				type: "string",
 				description: "Platform environment ID (falls back to MASTRA_ENVIRONMENT_ID)"
@@ -1805,6 +2175,6 @@ var InProcessSandboxAddressRegistry = class {
 	}
 };
 //#endregion
-export { InProcessSandboxAddressRegistry, PlatformApiError, PlatformClient, PlatformFilesystem, PlatformSandbox, PrivateNetExecHttpError, SandboxDestroyedError, SandboxExecTransportError, execViaPrivateNetwork, platformFilesystemProvider, platformSandboxProvider };
+export { InProcessSandboxAddressRegistry, PlatformApiError, PlatformClient, PlatformFilesystem, PlatformSandbox, PrivateNetExecHttpError, SandboxDestroyedError, SandboxExecTransportError, Template, createRepoTemplate, execViaPrivateNetwork, platformFilesystemProvider, platformSandboxProvider };
 
 //# sourceMappingURL=index.js.map