@mastra/docker 0.8.0 → 0.9.0-alpha.0

package/dist/index.cjs

@@ -28,6 +28,10 @@ let dockerode = require("dockerode");
 dockerode = __toESM(dockerode, 1);
 let tar_stream = require("tar-stream");
 let crypto = require("crypto");
+let path_posix = require("path/posix");
+path_posix = __toESM(path_posix, 1);
+let _grpc_grpc_js = require("@grpc/grpc-js");
+let child_process = require("child_process");
 //#region src/sandbox/process-manager.ts
 /**
 * Docker Process Manager
@@ -451,7 +455,10 @@ var DockerSandbox = class DockerSandbox extends _mastra_core_workspace.MastraSan
 	_container = null;
 	/** Configuration */
 	_containerName;
+	/** Image the container boots from; rewritten by a template resolution on `start()`. */
 	_image;
+	_templateSpec;
+	_workingDirectoryWasSet;
 	_command;
 	_env;
 	_volumes;
@@ -492,7 +499,10 @@ var DockerSandbox = class DockerSandbox extends _mastra_core_workspace.MastraSan
 		});
 		this.id = options.id ?? this._generateId();
 		this._containerName = sanitizeContainerName(options.name ?? this.id);
+		if (options.image !== void 0 && options.template !== void 0) throw new TypeError("DockerSandbox: `image` and `template` are mutually exclusive");
+		this._templateSpec = options.template;
 		this._image = options.image ?? "node:22-slim";
+		this._workingDirectoryWasSet = options.workingDirectory !== void 0 || options.workingDir !== void 0;
 		this._command = options.command ?? ["sleep", "infinity"];
 		this._env = options.env ?? {};
 		this._volumes = options.volumes ?? {};
@@ -568,11 +578,14 @@ var DockerSandbox = class DockerSandbox extends _mastra_core_workspace.MastraSan
 				this.logger.debug(`${LOG_PREFIX} Container exists but not running (${actualState}), starting...`);
 				await this._container.start();
 			}
+			const reconnectedWorkingDir = info.Config?.WorkingDir;
+			if (!this._workingDirectoryWasSet && reconnectedWorkingDir) this.setWorkingDirectory(reconnectedWorkingDir);
 			this.processes.setContainer(this._container);
 			this.logger.debug(`${LOG_PREFIX} Reconnected to container ${existing.Id}`);
 			return;
 		}
 		this._warnOnPrivilegedHardeningConflict(this._privileged);
+		await this._resolveTemplate();
 		await this._ensureImage();
 		const envArray = Object.entries(this._env).map(([k, v]) => `${k}=${v}`);
 		const binds = Object.entries(this._volumes).map(([host, container]) => `${host}:${container}`);
@@ -827,6 +840,23 @@ var DockerSandbox = class DockerSandbox extends _mastra_core_workspace.MastraSan
 		}
 	}
 	/**
+	* Resolve the `template` option (if any) into the image to boot from,
+	* building it when no cached image exists. Runs on every `start()` that
+	* creates a container, so a resolver-form template re-resolves each time.
+	* Adopts the template's workdir unless the sandbox was given one explicitly.
+	*/
+	async _resolveTemplate() {
+		if (!this._templateSpec) return;
+		const template = typeof this._templateSpec === "function" ? await this._templateSpec() : this._templateSpec;
+		const result = await template.build({ docker: this._docker });
+		if (result.status !== "ready") throw new _mastra_core_workspace.SandboxError(`Docker template build failed: ${result.error ?? "unknown error"}`, "START_FAILED", {
+			templateId: result.templateId,
+			reason: "template_build_failed"
+		});
+		this._image = result.templateId;
+		if (!this._workingDirectoryWasSet && template.workdir !== void 0) this.setWorkingDirectory(template.workdir);
+	}
+	/**
 	* Ensure the Docker image is available locally. Pulls if needed.
 	*/
 	async _ensureImage() {
@@ -834,7 +864,7 @@ var DockerSandbox = class DockerSandbox extends _mastra_core_workspace.MastraSan
 			await this._docker.getImage(this._image).inspect();
 			this.logger.debug(`${LOG_PREFIX} Image ${this._image} available locally`);
 		} catch (error) {
-			if (!isImageNotFoundError(error)) throw error;
+			if (!isImageNotFoundError$1(error)) throw error;
 			this.logger.debug(`${LOG_PREFIX} Pulling image ${this._image}...`);
 			try {
 				const stream = await this._docker.pull(this._image);
@@ -870,7 +900,7 @@ function isContainerNotFoundError(error) {
 	}
 	return false;
 }
-function isImageNotFoundError(error) {
+function isImageNotFoundError$1(error) {
 	if (error instanceof Error) return error.message.toLowerCase().includes("no such image");
 	return false;
 }
@@ -1170,8 +1200,898 @@ const dockerSandboxProvider = {
 	createSandbox: (config) => new DockerSandbox(config)
 };
 //#endregion
+//#region src/template/build-session.ts
+/**
+* BuildKit session that serves build secrets to the daemon.
+*
+* `docker build` with BuildKit (`version=2`) can attach a long-lived gRPC
+* "session" that the daemon calls back into for things it needs mid-build.
+* `RUN --mount=type=secret,id=X` is resolved by calling
+* `/moby.buildkit.secrets.v1.Secrets/GetSecret` on that session, so the value
+* exists only in the tmpfs mount for the duration of that one RUN — never as a
+* build arg, layer, history entry, or cache metadata.
+*
+* dockerode's own session helper only registers the registry-auth service and
+* overwrites any `session` id passed to `buildImage`, so this module dials the
+* hijacked `/session` endpoint itself and registers both services.
+*/
+const SECRETS_GET_METHOD = "/moby.buildkit.secrets.v1.Secrets/GetSecret";
+const AUTH_CREDENTIALS_METHOD = "/moby.filesync.v1.Auth/Credentials";
+/**
+* Open a session that answers `GetSecret` from `secrets`. The returned id must
+* be sent as the `session` query parameter of the build request.
+*/
+function openBuildSession(docker, secrets) {
+	const id = (0, crypto.randomUUID)();
+	return new Promise((resolve, reject) => {
+		docker.modem.dial({
+			method: "POST",
+			path: "/session",
+			hijack: true,
+			headers: {
+				Upgrade: "h2c",
+				"X-Docker-Expose-Session-Uuid": id,
+				"X-Docker-Expose-Session-Name": "mastra-docker-template",
+				"X-Docker-Expose-Session-Grpc-Method": [SECRETS_GET_METHOD, AUTH_CREDENTIALS_METHOD]
+			},
+			statusCodes: {
+				200: true,
+				500: "server error"
+			}
+		}, (err, socket) => {
+			if (err) {
+				reject(err);
+				return;
+			}
+			const server = new _grpc_grpc_js.Server();
+			server.createConnectionInjector(_grpc_grpc_js.ServerCredentials.createInsecure()).injectConnection(socket);
+			server.addService(secretsService, { GetSecret(call, callback) {
+				const value = Object.hasOwn(secrets, call.request.id) ? secrets[call.request.id] : void 0;
+				if (value === void 0) {
+					callback(Object.assign(/* @__PURE__ */ new Error(`no build secret registered with id '${call.request.id}'`), { code: 5 }));
+					return;
+				}
+				callback(null, { data: Buffer.from(value, "utf8") });
+			} });
+			server.addService(authService, { Credentials(_call, callback) {
+				callback(null, {});
+			} });
+			resolve({
+				id,
+				close() {
+					server.forceShutdown();
+					socket.end();
+				}
+			});
+		});
+	});
+}
+/** @internal exported for tests */
+function decodeGetSecretRequest(buffer) {
+	let offset = 0;
+	let id = "";
+	const readVarint = () => {
+		let result = 0;
+		let shift = 0;
+		for (;;) {
+			if (offset >= buffer.length) throw new Error("truncated varint");
+			const byte = buffer[offset++];
+			result += (byte & 127) * 2 ** shift;
+			if ((byte & 128) === 0) return result;
+			shift += 7;
+		}
+	};
+	while (offset < buffer.length) {
+		const key = readVarint();
+		const field = Math.floor(key / 8);
+		const wireType = key % 8;
+		switch (wireType) {
+			case 0:
+				readVarint();
+				break;
+			case 1:
+				offset += 8;
+				break;
+			case 5:
+				offset += 4;
+				break;
+			case 2: {
+				const length = readVarint();
+				const value = buffer.subarray(offset, offset + length);
+				offset += length;
+				if (field === 1) id = value.toString("utf8");
+				break;
+			}
+			default: throw new Error(`unsupported protobuf wire type ${wireType}`);
+		}
+	}
+	return { id };
+}
+/** @internal exported for tests */
+function encodeGetSecretResponse(response) {
+	return Buffer.concat([
+		Buffer.from([10]),
+		encodeVarint(response.data.length),
+		response.data
+	]);
+}
+function encodeVarint(value) {
+	const bytes = [];
+	let remaining = value;
+	while (remaining >= 128) {
+		bytes.push(remaining % 128 | 128);
+		remaining = Math.floor(remaining / 128);
+	}
+	bytes.push(remaining);
+	return Buffer.from(bytes);
+}
+const secretsService = { GetSecret: {
+	path: SECRETS_GET_METHOD,
+	requestStream: false,
+	responseStream: false,
+	requestSerialize: () => {
+		throw new Error("server does not serialize requests");
+	},
+	requestDeserialize: decodeGetSecretRequest,
+	responseSerialize: encodeGetSecretResponse,
+	responseDeserialize: () => {
+		throw new Error("server does not deserialize responses");
+	}
+} };
+const authService = { Credentials: {
+	path: AUTH_CREDENTIALS_METHOD,
+	requestStream: false,
+	responseStream: false,
+	requestSerialize: () => {
+		throw new Error("server does not serialize requests");
+	},
+	requestDeserialize: () => ({}),
+	responseSerialize: () => Buffer.alloc(0),
+	responseDeserialize: () => {
+		throw new Error("server does not deserialize responses");
+	}
+} };
+//#endregion
+//#region src/template/dockerfile.ts
+/**
+* Pure Dockerfile synthesis and content-addressed identity for DockerTemplate.
+*
+* A `DockerTemplate` records an ordered list of operations (setWorkdir, setEnvs,
+* runCmd, runWithSecrets, aptInstall, pipInstall, npmInstall) over a base image. This module
+* turns that ordered list into a deterministic Dockerfile string and a stable
+* content hash. It performs no I/O, so it is fully unit-testable without a
+* Docker daemon.
+*/
+function toCommandList(command) {
+	return Array.isArray(command) ? command : [command];
+}
+function sortedEntries(record) {
+	return Object.entries(record).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+}
+function renderEnvLine(envs) {
+	const pairs = sortedEntries(envs);
+	if (pairs.length === 0) return void 0;
+	return `ENV ${pairs.map(([key, value]) => `${key}=${JSON.stringify(value)}`).join(" ")}`;
+}
+function renderAptInstall(packages, options) {
+	const flags = [];
+	if (options?.noInstallRecommends) flags.push("--no-install-recommends");
+	if (options?.fixMissing) flags.push("--fix-missing");
+	return `RUN apt-get update && apt-get install -y ${flags.length > 0 ? `${flags.join(" ")} ` : ""}${toCommandList(packages).join(" ")} && rm -rf /var/lib/apt/lists/*`;
+}
+function renderPipInstall(packages, options) {
+	return `RUN pip install${options?.g === false ? " --user" : ""} ${packages === void 0 ? "." : toCommandList(packages).join(" ")}`;
+}
+function renderNpmInstall(packages, options) {
+	const flags = [];
+	if (options?.g) flags.push("-g");
+	if (packages === void 0) {
+		if (options?.dev) flags.push("--include=dev");
+		return `RUN npm install${flags.length > 0 ? ` ${flags.join(" ")}` : ""}`;
+	}
+	return `RUN npm install${flags.length > 0 ? ` ${flags.join(" ")}` : ""} ${toCommandList(packages).join(" ")}`;
+}
+function secretStageName(index) {
+	return `mastra-secret-${index}`;
+}
+function mainStageName(index) {
+	return `mastra-main-${index}`;
+}
+/**
+* Render a deterministic Dockerfile from a template definition.
+*
+* Operations accumulate in a chain of "main" stages. Every `runWithSecrets`
+* operation forks a throwaway stage from the main stage as it stands at that
+* point (so it sees earlier WORKDIR/ENV/installs) and runs the command with
+* each secret exposed through a BuildKit secret mount, exported into the
+* command's environment for that single RUN. The next main stage then starts
+* from the same pre-secret snapshot and `COPY --from`s only the declared
+* output path. Secret mounts are tmpfs-backed and never part of a layer, its
+* history, or the build cache; the throwaway stage additionally keeps anything
+* else the command wrote (caches, logs) out of the template image.
+*/
+/**
+* `RUN --mount=type=secret,id=X,mode=0444 ... export X="$(cat /run/secrets/X)" && <command>`.
+* Reading the file into a shell variable keeps the value visible only to this
+* RUN's process tree, without depending on the newer `env=` mount option.
+* `mode=0444` because BuildKit's default is `0400 root`, which a base image
+* with a non-root `USER` cannot read; world-readable within the RUN is no
+* wider than the exported variable already is.
+*/
+function renderSecretRun(command, secrets) {
+	const names = [...secrets].sort();
+	const mounts = names.map((name) => `--mount=type=secret,id=${name},mode=0444`);
+	const exports = names.map((name) => `${name}="$(cat /run/secrets/${name})"`);
+	const prefix = names.length > 0 ? [`export ${exports.join(" ")}`] : [];
+	return `RUN ${[...mounts, ""].join(" ")}${[...prefix, ...toCommandList(command)].join(" && ")}`;
+}
+function synthesizeDockerfile(definition) {
+	const lines = [];
+	let mainIndex = 0;
+	const openMain = (from) => {
+		lines.push(`FROM ${from} AS ${mainStageName(mainIndex)}`);
+	};
+	openMain(definition.baseImage);
+	definition.operations.forEach((operation, index) => {
+		switch (operation.method) {
+			case "setWorkdir":
+				lines.push(`WORKDIR ${operation.args[0]}`);
+				break;
+			case "setEnvs": {
+				const line = renderEnvLine(operation.args[0]);
+				if (line) lines.push(line);
+				break;
+			}
+			case "runCmd":
+				lines.push(`RUN ${toCommandList(operation.args[0]).join(" && ")}`);
+				break;
+			case "runWithSecrets": {
+				const [command, { secrets, output }] = operation.args;
+				const snapshot = mainStageName(mainIndex);
+				const stage = secretStageName(index);
+				lines.push(`FROM ${snapshot} AS ${stage}`, renderSecretRun(command, secrets));
+				mainIndex += 1;
+				openMain(snapshot);
+				lines.push(`COPY --from=${stage} ${output} ${output}`);
+				break;
+			}
+			case "aptInstall":
+				lines.push(renderAptInstall(operation.args[0], operation.args[1]));
+				break;
+			case "pipInstall":
+				lines.push(renderPipInstall(operation.args[0], operation.args[1]));
+				break;
+			case "npmInstall":
+				lines.push(renderNpmInstall(operation.args[0], operation.args[1]));
+				break;
+		}
+	});
+	return `${lines.join("\n")}\n`;
+}
+/** Names of every secret referenced by `runWithSecrets` operations, deduplicated and sorted. */
+function secretNames(definition) {
+	const names = /* @__PURE__ */ new Set();
+	for (const operation of definition.operations) if (operation.method === "runWithSecrets") for (const name of operation.args[1].secrets) names.add(name);
+	return [...names].sort();
+}
+/** Prefix for template image tags built locally. */
+const TEMPLATE_IMAGE_REPO = "mastra-template";
+function canonicalOperation(operation) {
+	switch (operation.method) {
+		case "setEnvs": return {
+			method: "setEnvs",
+			args: [sortedEntries(operation.args[0])]
+		};
+		case "runWithSecrets": {
+			const [command, { secrets, output }] = operation.args;
+			return {
+				method: "runWithSecrets",
+				args: [command, {
+					secrets: [...secrets].sort(),
+					output
+				}]
+			};
+		}
+		default: return operation;
+	}
+}
+/**
+* Stable content hash over the base image and ordered operations. Env records
+* and secret name lists are canonicalized so insertion order does not change
+* the identity. Secret *values* never enter the definition, so the same
+* definition built with different credentials resolves to the same image tag.
+*/
+function templateIdentity(definition) {
+	const canonical = JSON.stringify({
+		schemaVersion: 1,
+		baseImage: definition.baseImage,
+		operations: definition.operations.map(canonicalOperation)
+	});
+	return (0, crypto.createHash)("sha256").update(canonical).digest("hex").slice(0, 24);
+}
+/** Full `mastra-template:<hash>` tag for a definition. */
+function templateImageTag(definition) {
+	return `${TEMPLATE_IMAGE_REPO}:${templateIdentity(definition)}`;
+}
+//#endregion
+//#region src/template/template.ts
+/**
+* DockerTemplate — a reusable prepared baseline for the local Docker sandbox.
+*
+* Prepare an environment once (base image + ordered setup commands + env +
+* package installs), `build()` it into a content-addressed local image, then
+* spawn multiple disposable `DockerSandbox`es from that image. Each sandbox is a
+* fresh container with its own writable layer over the shared read-only image,
+* so their filesystems are independent. The built image's lifecycle is
+* controlled by `dispose()`, independent of any sandbox's `destroy()`.
+*
+* Unlike `docker commit` (which cannot capture mounted volumes and skips layer
+* caching), the baseline is produced by synthesizing a Dockerfile and running
+* `docker build`, so repo/setup content is baked into reproducible, cached
+* image layers.
+*
+* @example Prepare once, spawn many
+* ```typescript
+* import { DockerTemplate } from '@mastra/docker';
+*
+* const template = new DockerTemplate({ baseImage: 'node:22-slim' })
+*   .runCmd('git clone --depth=1 https://example.com/repo /workspace/app')
+*   .setWorkdir('/workspace/app')
+*   .runCmd('npm ci');
+*
+* const result = await template.build();
+* if (result.status !== 'ready') throw new Error(result.error);
+*
+* const a = await template.createSandbox();
+* const b = await template.createSandbox(); // independent writable filesystem
+* ```
+*/
+const MAX_OPERATIONS = 256;
+const MAX_STRING_LENGTH = 32 * 1024;
+const MAX_COLLECTION_ITEMS = 512;
+/**
+* Immutable, chainable builder + build/lifecycle for a local Docker template.
+* Operation methods return a new instance (like the platform `Template()`
+* builder); `build`/`createSandbox`/`dispose` operate against the daemon.
+*/
+var DockerTemplate = class DockerTemplate {
+	#baseImage;
+	#operations;
+	#dockerOptions;
+	#secrets;
+	#docker;
+	#built = false;
+	#inFlight;
+	constructor(options = {}, state) {
+		this.#baseImage = state ? state.baseImage : validateString(options.baseImage ?? "node:22-slim", "baseImage");
+		this.#operations = state?.operations ?? [];
+		this.#dockerOptions = options.dockerOptions;
+		this.#secrets = options.secrets;
+	}
+	#clone(next) {
+		return new DockerTemplate({
+			dockerOptions: this.#dockerOptions,
+			secrets: this.#secrets
+		}, {
+			baseImage: next.baseImage ?? this.#baseImage,
+			operations: next.operations ?? this.#operations
+		});
+	}
+	#append(operation) {
+		if (this.#operations.length >= MAX_OPERATIONS) throw new RangeError(`Docker template cannot contain more than ${MAX_OPERATIONS} operations`);
+		return this.#clone({ operations: [...this.#operations, operation] });
+	}
+	/** Set the base image. */
+	from(image) {
+		return this.#clone({ baseImage: validateString(image, "image") });
+	}
+	/** Set the working directory for subsequent steps and the runtime container. */
+	setWorkdir(path) {
+		return this.#append({
+			method: "setWorkdir",
+			args: [validateString(path, "path")]
+		});
+	}
+	/**
+	* Set environment variables. They are baked into the image via `ENV` and
+	* participate in the template identity, so never put secrets here — use
+	* {@link runWithSecrets} for anything that must not persist in the image.
+	*/
+	setEnvs(envs) {
+		return this.#append({
+			method: "setEnvs",
+			args: [validateStringRecord(envs, "envs")]
+		});
+	}
+	/** Run a command (or `&&`-joined list of commands) as a build step. */
+	runCmd(command) {
+		return this.#append({
+			method: "runCmd",
+			args: [validateStringOrStrings(command, "command")]
+		});
+	}
+	/**
+	* Run a command that needs build-time secrets, without persisting them.
+	*
+	* The command runs in a throwaway build stage forked from the template as it
+	* stands at that point, so earlier WORKDIR/ENV/installs apply and later
+	* steps see the copied `output`. The named secrets are resolved when
+	* `build()` runs — from `build({ secrets })`, then the template's `secrets`
+	* option, then `process.env` — and exposed to the command as environment
+	* variables. Values reach the daemon through a BuildKit secret mount
+	* (`RUN --mount=type=secret`), which is tmpfs-backed and scoped to that one
+	* RUN — never a build arg, layer, history entry, or cache metadata. Only
+	* `output` is copied into the template image. Builds that use secrets
+	* require a BuildKit-capable daemon (Docker 20.10+).
+	*/
+	runWithSecrets(command, options) {
+		if (!Array.isArray(options.secrets)) throw new TypeError("secrets must be an array of strings");
+		if (options.secrets.length > MAX_COLLECTION_ITEMS) throw new RangeError(`secrets cannot contain more than ${MAX_COLLECTION_ITEMS} items`);
+		const secrets = options.secrets.map((name) => {
+			if (typeof name !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new TypeError(`secrets must be environment variable names, got ${JSON.stringify(name)}`);
+			return name;
+		});
+		const output = validateString(options.output, "output");
+		if (!output.startsWith("/")) throw new TypeError("output must be an absolute path");
+		return this.#append({
+			method: "runWithSecrets",
+			args: [validateStringOrStrings(command, "command"), {
+				secrets,
+				output
+			}]
+		});
+	}
+	/** Install apt packages. */
+	aptInstall(packages, options) {
+		return this.#append({
+			method: "aptInstall",
+			args: [validateStringOrStrings(packages, "packages"), options]
+		});
+	}
+	/** Install pip packages (or `pip install .` for the current workdir when omitted). */
+	pipInstall(packages, options) {
+		const validated = packages === void 0 ? void 0 : validateStringOrStrings(packages, "packages");
+		return this.#append({
+			method: "pipInstall",
+			args: [validated, options]
+		});
+	}
+	/** Install npm packages (or run `npm install` for the current workdir when omitted). */
+	npmInstall(packages, options) {
+		const validated = packages === void 0 ? void 0 : validateStringOrStrings(packages, "packages");
+		return this.#append({
+			method: "npmInstall",
+			args: [validated, options]
+		});
+	}
+	/** The resolved definition (base image + ordered operations). */
+	get definition() {
+		return {
+			baseImage: this.#baseImage,
+			operations: this.#operations
+		};
+	}
+	/** The synthesized Dockerfile for this template. */
+	get dockerfile() {
+		return synthesizeDockerfile(this.definition);
+	}
+	/** The content-addressed local image tag this template resolves to. */
+	get templateId() {
+		return templateImageTag(this.definition);
+	}
+	/**
+	* The working directory the built image ends up with, i.e. the last
+	* `setWorkdir` in the chain (resolved against earlier ones when relative).
+	* `undefined` when the template never sets one, in which case the base
+	* image's `WORKDIR` (or the sandbox default) applies.
+	*/
+	get workdir() {
+		let current;
+		for (const op of this.#operations) {
+			if (op.method !== "setWorkdir") continue;
+			const next = op.args[0];
+			current = next.startsWith("/") || current === void 0 ? next : path_posix.default.join(current, next);
+		}
+		return current;
+	}
+	#getDocker() {
+		if (!this.#docker) this.#docker = new dockerode.default(this.#dockerOptions);
+		return this.#docker;
+	}
+	/**
+	* Build (or reuse) the template's image. Idempotent: if an image with the
+	* computed tag already exists locally and `force` is not set, returns
+	* `ready` without rebuilding. Otherwise synthesizes a Dockerfile, runs
+	* `docker build`, and surfaces any build-step failure as `status: 'failed'`.
+	*
+	* @throws if a secret named by `runWithSecrets` cannot be resolved from
+	* `options.secrets`, the template's `secrets` option, or `process.env`.
+	*/
+	async build(options = {}) {
+		if (!options.force && options.secrets === void 0 && options.docker === void 0 && this.#inFlight) return this.#inFlight;
+		const run = (this.#inFlight?.catch(() => void 0) ?? Promise.resolve()).then(() => this.#build(options));
+		this.#inFlight = run;
+		run.finally(() => {
+			if (this.#inFlight === run) this.#inFlight = void 0;
+		}).catch(() => void 0);
+		return run;
+	}
+	async #build(options) {
+		const docker = options.docker ?? this.#getDocker();
+		const tag = this.templateId;
+		if (!options.force) try {
+			await docker.getImage(tag).inspect();
+			this.#built = true;
+			return {
+				status: "ready",
+				templateId: tag
+			};
+		} catch (error) {
+			if (!isImageNotFoundError(error)) throw error;
+		}
+		const secrets = await this.#resolveSecrets(options.secrets);
+		const context = (0, tar_stream.pack)();
+		context.entry({ name: "Dockerfile" }, this.dockerfile);
+		context.finalize();
+		try {
+			const nocache = options.force === true;
+			if (secrets) {
+				const { stream, session } = await this.#buildWithSecrets(docker, context, tag, secrets, nocache);
+				try {
+					await this.#followBuild(docker, stream);
+				} finally {
+					session.close();
+				}
+			} else await this.#followBuild(docker, await docker.buildImage(context, {
+				t: tag,
+				nocache
+			}));
+		} catch (error) {
+			this.#built = false;
+			return {
+				status: "failed",
+				templateId: tag,
+				error: error instanceof Error ? error.message : String(error)
+			};
+		}
+		this.#built = true;
+		return {
+			status: "ready",
+			templateId: tag
+		};
+	}
+	async #resolveSecrets(override) {
+		const names = secretNames(this.definition);
+		if (names.length === 0) return void 0;
+		const fromBuild = await readSecrets(override);
+		const fromTemplate = await readSecrets(this.#secrets);
+		const resolved = {};
+		for (const name of names) {
+			const value = fromBuild[name] ?? fromTemplate[name] ?? process.env[name];
+			if (value === void 0) throw new Error(`Docker template secret ${name} was not provided (secrets option) and is not set in the environment`);
+			resolved[name] = value;
+		}
+		return resolved;
+	}
+	/**
+	* BuildKit build with a session serving the secret mounts. Dials `/build`
+	* directly because `docker.buildImage` replaces any session id with its own
+	* auth-only session when `version` is `'2'`.
+	*/
+	async #buildWithSecrets(docker, context, tag, secrets, nocache) {
+		const session = await openBuildSession(docker, secrets);
+		let stream;
+		try {
+			stream = await new Promise((resolve, reject) => {
+				docker.modem.dial({
+					path: "/build?",
+					method: "POST",
+					file: context,
+					options: {
+						t: tag,
+						version: "2",
+						session: session.id,
+						nocache
+					},
+					isStream: true,
+					statusCodes: {
+						200: true,
+						500: "server error"
+					}
+				}, (err, data) => err ? reject(err) : resolve(data));
+			});
+		} catch (error) {
+			session.close();
+			throw error;
+		}
+		return {
+			stream,
+			session
+		};
+	}
+	#followBuild(docker, stream) {
+		return new Promise((resolve, reject) => {
+			docker.modem.followProgress(stream, (err, output) => {
+				if (err) {
+					reject(err);
+					return;
+				}
+				const failure = output?.find((entry) => entry && (entry.error !== void 0 || entry.errorDetail !== void 0));
+				if (failure) {
+					const detail = failure.errorDetail;
+					reject(new Error(String(detail?.message ?? failure.error ?? "docker build failed")));
+					return;
+				}
+				resolve();
+			});
+		});
+	}
+	/**
+	* Create a `DockerSandbox` bound to the built image. Lazily builds the
+	* template if it has not been built yet. Each call returns a fresh sandbox
+	* with an independent writable layer. Invocation-specific `env`/config passed
+	* via `options` reaches only the container and is never baked into the image.
+	*
+	* The sandbox's working directory follows the template's last `setWorkdir`
+	* unless `options.workingDirectory` overrides it, so relative paths resolve
+	* against the same directory the image was prepared in.
+	*
+	* @throws if the (lazy) build fails.
+	*/
+	async createSandbox(options = {}) {
+		if (!this.#built) {
+			const result = await this.build();
+			if (result.status !== "ready") throw new Error(`Docker template build failed: ${result.error ?? "unknown error"}`);
+		}
+		const workingDirectory = options.workingDirectory ?? options.workingDir ?? this.workdir;
+		return new DockerSandbox({
+			...options,
+			...workingDirectory !== void 0 && { workingDirectory },
+			template: this,
+			dockerOptions: options.dockerOptions ?? this.#dockerOptions
+		});
+	}
+	/**
+	* Remove the built image (`docker rmi`). Tolerant of an already-removed
+	* image. Independent of any sandbox created from this template, but the
+	* daemon refuses to remove an image that a container (running or stopped)
+	* still references, so destroy those sandboxes first.
+	*/
+	async dispose() {
+		const docker = this.#getDocker();
+		try {
+			await docker.getImage(this.templateId).remove();
+		} catch (error) {
+			if (!isImageNotFoundError(error)) throw error;
+		}
+		this.#built = false;
+	}
+};
+function validateString(value, name) {
+	if (typeof value !== "string") throw new TypeError(`${name} must be a string`);
+	if (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`);
+	if (value.length === 0) throw new TypeError(`${name} must not be empty`);
+	if (value.length > MAX_COLLECTION_ITEMS) throw new RangeError(`${name} cannot contain more than ${MAX_COLLECTION_ITEMS} items`);
+	return value.map((item, index) => validateString(item, `${name}[${index}]`));
+}
+function validateStringRecord(value, name) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new TypeError(`${name} must be a plain object`);
+	const entries = Object.entries(value);
+	if (entries.length > MAX_COLLECTION_ITEMS) throw new RangeError(`${name} cannot contain more than ${MAX_COLLECTION_ITEMS} items`);
+	return Object.fromEntries(entries.map(([key, item]) => {
+		if (typeof item !== "string") throw new TypeError(`${name}.${key} must be a string`);
+		return [validateString(key, `${name} key`), item];
+	}));
+}
+async function readSecrets(source) {
+	if (!source) return {};
+	return typeof source === "function" ? await source() : source;
+}
+function isImageNotFoundError(error) {
+	if (error instanceof Error) {
+		const msg = error.message.toLowerCase();
+		return msg.includes("no such image") || msg.includes("404");
+	}
+	return false;
+}
+//#endregion
+//#region ../../packages/_internals/workspace/dist/index.js
+/**
+* Setup completion marker shared by repo templates and their consumers.
+*
+* A repo template writes this file beside the checkout as its last build
+* step, so it exists only in images where every setup command succeeded. Its
+* content is a digest of the setup commands the image ran, letting a sandbox
+* booted from the image tell whether the setup it is about to run already
+* happened. Relative to the template's build cwd, which is also the runtime
+* working directory the repo was cloned into.
+*/
+const SETUP_MARKER_PATH = ".mastra-sandbox/setup";
+/** Blank entries never become build steps, so they never count toward the digest either. */
+function normalizeSetupCommands(setupCommand) {
+	return (setupCommand === void 0 ? [] : Array.isArray(setupCommand) ? setupCommand : [setupCommand]).filter((command) => command.trim() !== "");
+}
+/** The marker content for a setup command list: `sha256:<hex>` over the commands joined by newlines. */
+function setupMarkerContent(setupCommand) {
+	return `sha256:${(0, crypto.createHash)("sha256").update(normalizeSetupCommands(setupCommand).join("\n")).digest("hex")}`;
+}
+/** Shell step that writes the marker relative to the cwd. `content` is a digest, so it is shell-safe. */
+function setupMarkerCommand(content) {
+	return `mkdir -p "$(dirname "${SETUP_MARKER_PATH}")" && printf '%s' '${content}' > "${SETUP_MARKER_PATH}"`;
+}
+//#endregion
+//#region src/template/repo-template.ts
+/**
+* createDockerRepoTemplate — a repo checkout plus setup commands as a
+* reusable, content-addressed local image, with the same contract as the
+* E2B and platform repo templates (`getRepositoryAccess`, `setupCommand`,
+* `buildEnv`, `workingDirectory`).
+*
+* Returns a template RESOLVER for `DockerSandbox`'s `template` option rather
+* than a fixed template: each resolution calls `getRepositoryAccess`, looks up
+* the current head of `ref` (`git ls-remote`, no clone) and pins that sha into
+* the template identity. A moved branch therefore yields a fresh image on the
+* next new sandbox, and an unmoved one reuses the cached image. When the head
+* cannot be resolved the resolver rejects: an unpinned clone cached under a
+* stable tag would otherwise serve stale repository state forever.
+*
+* The clone runs in a throwaway build stage; the credential is passed by value
+* to that stage only and never enters the template identity or the image.
+*
+* @example
+* ```typescript
+* const sandbox = new DockerSandbox({
+*   template: createDockerRepoTemplate({
+*     getRepositoryAccess: async () => ({ cloneUrl: 'https://github.com/acme/app.git' }),
+*     setupCommand: ['npm ci', 'npm run build'],
+*   }),
+* });
+* ```
+*/
+const execFileAsync = (0, util.promisify)(child_process.execFile);
+/** Env var the build's clone reads the credential from (see `cloneFull`). */
+const BUILD_TOKEN_ENV = "GH_TOKEN";
+const DEFAULT_BASE_IMAGE = "node:22-slim";
+const DEFAULT_WORKING_DIRECTORY = "/workspace";
+const FULL_SHA_PATTERN = /^[0-9a-f]{40}$/i;
+const SHA_PATTERN = /^[0-9a-f]{40}$/i;
+const CLONE_URL_ALLOWED_CHARS = /^[a-z0-9:/._-]+$/i;
+const CLONE_URL_HOST_PATTERN = /^[a-z0-9.-]+$/i;
+const CLONE_URL_SEGMENT_PATTERN = /^[\w.-]+$/;
+/** Refs interpolate into shell too; git ref names are already restricted, so allowlist tightly. */
+const REF_PATTERN = /^[\w./-]+$/;
+function createDockerRepoTemplate(options) {
+	if (!options.getRepositoryAccess) return void 0;
+	if (options.ref !== void 0 && !REF_PATTERN.test(options.ref)) throw new Error(`Invalid ref '${options.ref}': expected a git ref name`);
+	const workingDirectory = trimTrailingSlashes(options.workingDirectory ?? DEFAULT_WORKING_DIRECTORY);
+	if (!workingDirectory.startsWith("/")) throw new Error(`workingDirectory must be an absolute path, got '${options.workingDirectory}'`);
+	return () => resolveRepoTemplate(options, workingDirectory);
+}
+async function resolveRepoTemplate(options, workingDirectory) {
+	const access = await options.getRepositoryAccess();
+	const cloneUrl = access?.cloneUrl;
+	if (!cloneUrl) throw new Error("Repo template has no clone URL: repository access returned none.");
+	assertCloneUrl(cloneUrl);
+	const token = access?.authorization?.token;
+	const buildEnv = typeof options.buildEnv === "function" ? await options.buildEnv() : options.buildEnv;
+	const sha = await resolveHead(cloneUrl, options.ref, token);
+	if (!sha) throw new Error(`Could not resolve ${options.ref ?? "HEAD"} of ${cloneUrl} with git ls-remote; check the ref, the credential and network access`);
+	return buildRepoTemplate({
+		cloneUrl,
+		sha,
+		token,
+		buildEnv,
+		setupCommand: options.setupCommand,
+		workingDirectory,
+		baseImage: options.baseImage,
+		dockerOptions: options.dockerOptions
+	});
+}
+/**
+* Pure assembly of the template from already-resolved inputs. Exported for
+* tests so the Dockerfile can be asserted without a network head lookup.
+* @internal
+*/
+function buildRepoTemplate(inputs) {
+	const { cloneUrl, sha, token, buildEnv } = inputs;
+	const destination = `${trimTrailingSlashes(inputs.workingDirectory)}/${repoDirName(cloneUrl)}`;
+	let template = new DockerTemplate({
+		baseImage: inputs.baseImage ?? DEFAULT_BASE_IMAGE,
+		dockerOptions: inputs.dockerOptions,
+		...token ? { secrets: { [BUILD_TOKEN_ENV]: token } } : {}
+	});
+	if (inputs.baseImage === void 0) template = template.aptInstall(["git", "ca-certificates"]);
+	if (buildEnv && Object.keys(buildEnv).length > 0) template = template.setEnvs(buildEnv);
+	const tokenEnv = token ? BUILD_TOKEN_ENV : void 0;
+	const clone = [cloneFull({
+		cloneUrl,
+		destination,
+		tokenEnv
+	}), `git -C ${shellQuote(destination)} checkout --detach ${shellQuote(sha)}`];
+	template = template.runWithSecrets(clone, {
+		secrets: tokenEnv ? [tokenEnv] : [],
+		output: destination
+	}).setWorkdir(destination);
+	const setupCommands = normalizeSetupCommands(inputs.setupCommand);
+	for (const command of setupCommands) template = template.runCmd(command);
+	if (setupCommands.length > 0) template = template.runCmd(setupMarkerCommand(setupMarkerContent(setupCommands)));
+	return template;
+}
+/**
+* Resolve `ref` (or the default branch) to a commit sha with `git ls-remote`
+* on the host, without cloning. A full sha is returned as is. Any failure
+* yields undefined; the caller decides how to surface it.
+* @internal exported for tests.
+*/
+async function resolveHead(cloneUrl, ref, token) {
+	if (ref && FULL_SHA_PATTERN.test(ref)) return ref.toLowerCase();
+	try {
+		const authEnv = token ? {
+			GIT_CONFIG_COUNT: "1",
+			GIT_CONFIG_KEY_0: "http.extraheader",
+			GIT_CONFIG_VALUE_0: `AUTHORIZATION: basic ${Buffer.from(`x-access-token:${token}`).toString("base64")}`
+		} : {};
+		const { stdout } = await execFileAsync("git", [
+			"ls-remote",
+			"--",
+			cloneUrl,
+			ref ?? "HEAD"
+		], {
+			timeout: 1e4,
+			env: {
+				...process.env,
+				...authEnv,
+				GIT_TERMINAL_PROMPT: "0"
+			}
+		});
+		const lines = stdout.split("\n").filter(Boolean).map((line) => line.split("	"));
+		const sha = (lines.find(([, name]) => name?.endsWith("^{}")) ?? lines[0])?.[0]?.trim();
+		return sha && SHA_PATTERN.test(sha) ? sha.toLowerCase() : void 0;
+	} catch {
+		return;
+	}
+}
+function cloneFull({ cloneUrl, destination, tokenEnv }) {
+	return `git ${tokenEnv ? `-c http.extraheader="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$${tokenEnv}" | base64 -w0)" ` : ""}clone ${shellQuote(cloneUrl)} ${shellQuote(destination)}`;
+}
+function assertCloneUrl(cloneUrl) {
+	if (cloneUrl.length > 2048 || !CLONE_URL_ALLOWED_CHARS.test(cloneUrl)) throw new Error(`Invalid cloneUrl '${cloneUrl}': expected an https URL with a plain host and path`);
+	let url;
+	try {
+		url = new URL(cloneUrl);
+	} catch {
+		throw new Error(`Invalid cloneUrl '${cloneUrl}': not a URL`);
+	}
+	const segments = url.pathname.split("/").slice(1);
+	if (!(url.protocol === "https:" && !url.username && !url.password && !url.search && !url.hash && CLONE_URL_HOST_PATTERN.test(url.hostname) && segments.length > 0 && segments.every((segment) => CLONE_URL_SEGMENT_PATTERN.test(segment)))) throw new Error(`Invalid cloneUrl '${cloneUrl}': expected an https URL such as https://host/owner/repo.git`);
+}
+function repoDirName(cloneUrl) {
+	return (trimTrailingSlashes(cloneUrl).split("/").at(-1) ?? "").replace(/\.git$/i, "").replace(/[^\w.-]/g, "-").replace(/^\.+/, "") || "repo";
+}
+function trimTrailingSlashes(path) {
+	let end = path.length;
+	while (end > 1 && path[end - 1] === "/") end--;
+	return path.slice(0, end);
+}
+function shellQuote(value) {
+	return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+//#endregion
 exports.DockerProcessManager = DockerProcessManager;
 exports.DockerSandbox = DockerSandbox;
+exports.DockerTemplate = DockerTemplate;
+exports.TEMPLATE_IMAGE_REPO = TEMPLATE_IMAGE_REPO;
+exports.createDockerRepoTemplate = createDockerRepoTemplate;
 exports.dockerSandboxProvider = dockerSandboxProvider;
+exports.secretNames = secretNames;
+exports.synthesizeDockerfile = synthesizeDockerfile;
+exports.templateIdentity = templateIdentity;
+exports.templateImageTag = templateImageTag;
 
 //# sourceMappingURL=index.cjs.map