@mastra/docker 0.8.0-alpha.2 → 0.9.0-alpha.0

package/dist/sandbox/index.d.ts

@@ -13,7 +13,10 @@ import type { SandboxInfo, ProviderStatus, MastraSandboxOptions, SandboxCloneOpt
 import { MastraSandbox } from '@mastra/core/workspace';
 import Docker from 'dockerode';
 import type { Container } from 'dockerode';
+import type { DockerTemplate } from '../template/template.js';
 import { DockerProcessManager } from './process-manager.js';
+/** A prepared template, or a resolver producing one (see `DockerSandboxOptions.template`). */
+export type DockerTemplateSpec = DockerTemplate | (() => DockerTemplate | Promise<DockerTemplate>);
 /**
  * Inlined from `@mastra/core/workspace` to avoid requiring a newer core peer dep.
  * Canonical type: packages/core/src/workspace/sandbox/mastra-sandbox.ts
@@ -105,6 +108,17 @@ export interface DockerSandboxOptions extends Omit<MastraSandboxOptions, 'proces
      * @default 'node:22-slim'
      */
     image?: string;
+    /**
+     * Prepared baseline to boot from, as an alternative to `image`. The
+     * template is built (or its cached image reused) lazily on `start()`, and
+     * the container boots from the resulting image. A function form is resolved
+     * once per `start()` that creates a container, so head-pinned repo
+     * templates can re-resolve on each new sandbox.
+     *
+     * When `workingDirectory` is not set, the template's last `setWorkdir`
+     * becomes the sandbox working directory. Mutually exclusive with `image`.
+     */
+    template?: DockerTemplateSpec;
     /** Container entrypoint command. Must keep the container alive.
      * @default ['sleep', 'infinity']
      */
@@ -227,7 +241,10 @@ export declare class DockerSandbox extends MastraSandbox {
     private _container;
     /** Configuration */
     private readonly _containerName;
-    private readonly _image;
+    /** Image the container boots from; rewritten by a template resolution on `start()`. */
+    private _image;
+    private readonly _templateSpec?;
+    private readonly _workingDirectoryWasSet;
     private readonly _command;
     private readonly _env;
     private readonly _volumes;
@@ -337,6 +354,13 @@ export declare class DockerSandbox extends MastraSandbox {
      * Find an existing container matching this sandbox's ID via labels.
      */
     private _findExistingContainer;
+    /**
+     * 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.
+     */
+    private _resolveTemplate;
     /**
      * Ensure the Docker image is available locally. Pulls if needed.
      */

package/dist/sandbox/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sandbox/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sandbox/index.ts"],"names":[],"mappings":"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"}

package/dist/template/build-session.d.ts

@@ -0,0 +1,22 @@
+import type Docker from 'dockerode';
+export declare const SECRETS_GET_METHOD = "/moby.buildkit.secrets.v1.Secrets/GetSecret";
+export interface BuildSession {
+    id: string;
+    close(): void;
+}
+/**
+ * Open a session that answers `GetSecret` from `secrets`. The returned id must
+ * be sent as the `session` query parameter of the build request.
+ */
+export declare function openBuildSession(docker: Docker, secrets: Record<string, string>): Promise<BuildSession>;
+export interface GetSecretRequest {
+    id: string;
+}
+export interface GetSecretResponse {
+    data: Buffer;
+}
+/** @internal exported for tests */
+export declare function decodeGetSecretRequest(buffer: Buffer): GetSecretRequest;
+/** @internal exported for tests */
+export declare function encodeGetSecretResponse(response: GetSecretResponse): Buffer;
+//# sourceMappingURL=build-session.d.ts.map

package/dist/template/build-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-session.d.ts","sourceRoot":"","sources":["../../src/template/build-session.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,MAAM,MAAM,WAAW,CAAC;AAEpC,eAAO,MAAM,kBAAkB,gDAAgD,CAAC;AAGhF,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAsDvG;AAcD,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;CACZ;AACD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,mCAAmC;AACnC,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAwCvE;AAED,mCAAmC;AACnC,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,CAE3E"}

package/dist/template/dockerfile.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 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.
+ */
+export interface AptInstallOptions {
+    /** Pass `--no-install-recommends` to `apt-get install`. */
+    noInstallRecommends?: boolean;
+    /** Pass `--fix-missing` to `apt-get install`. */
+    fixMissing?: boolean;
+}
+export interface PipInstallOptions {
+    /** Install system-wide (default). `false` installs for the current user (`--user`). */
+    g?: boolean;
+}
+export interface NpmInstallOptions {
+    /** Install globally (`npm install -g`). */
+    g?: boolean;
+    /** Include dev dependencies (`--include=dev`). Ignored when `packages` is set. */
+    dev?: boolean;
+}
+export interface RunWithSecretsOptions {
+    /**
+     * Names of environment variables whose values are read from the building
+     * process's `process.env` at `build()` time and exposed to the command. Only
+     * the names participate in the template identity.
+     */
+    secrets: string[];
+    /**
+     * Absolute path produced by the command. Only this path is copied into the
+     * template image; everything else the command does (including the secret
+     * values) stays in a throwaway build stage.
+     */
+    output: string;
+}
+export type DockerTemplateOperation = {
+    method: 'setWorkdir';
+    args: [string];
+} | {
+    method: 'setEnvs';
+    args: [Record<string, string>];
+} | {
+    method: 'runCmd';
+    args: [string | string[]];
+} | {
+    method: 'runWithSecrets';
+    args: [string | string[], RunWithSecretsOptions];
+} | {
+    method: 'aptInstall';
+    args: [string | string[], AptInstallOptions?];
+} | {
+    method: 'pipInstall';
+    args: [(string | string[])?, PipInstallOptions?];
+} | {
+    method: 'npmInstall';
+    args: [(string | string[])?, NpmInstallOptions?];
+};
+/** A fully-resolved template definition: the base image and the ordered operations. */
+export interface DockerTemplateDefinition {
+    baseImage: string;
+    operations: readonly DockerTemplateOperation[];
+}
+export declare function synthesizeDockerfile(definition: DockerTemplateDefinition): string;
+/** Names of every secret referenced by `runWithSecrets` operations, deduplicated and sorted. */
+export declare function secretNames(definition: DockerTemplateDefinition): string[];
+/** Prefix for template image tags built locally. */
+export declare const TEMPLATE_IMAGE_REPO = "mastra-template";
+/**
+ * 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.
+ */
+export declare function templateIdentity(definition: DockerTemplateDefinition): string;
+/** Full `mastra-template:<hash>` tag for a definition. */
+export declare function templateImageTag(definition: DockerTemplateDefinition): string;
+//# sourceMappingURL=dockerfile.d.ts.map

package/dist/template/dockerfile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dockerfile.d.ts","sourceRoot":"","sources":["../../src/template/dockerfile.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,MAAM,WAAW,iBAAiB;IAChC,2DAA2D;IAC3D,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,iDAAiD;IACjD,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,uFAAuF;IACvF,CAAC,CAAC,EAAE,OAAO,CAAC;CACb;AAED,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,CAAC,CAAC,EAAE,OAAO,CAAC;IACZ,kFAAkF;IAClF,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,uBAAuB,GAC/B;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,CAAC,MAAM,CAAC,CAAA;CAAE,GACxC;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAAE,GACrD;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC,CAAA;CAAE,GAC/C;IAAE,MAAM,EAAE,gBAAgB,CAAC;IAAC,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,EAAE,EAAE,qBAAqB,CAAC,CAAA;CAAE,GAC9E;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,EAAE,EAAE,iBAAiB,CAAC,CAAC,CAAA;CAAE,GACvE;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,CAAC,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAA;CAAE,GAC1E;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,CAAC,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAA;CAAE,CAAC;AAE/E,uFAAuF;AACvF,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,SAAS,uBAAuB,EAAE,CAAC;CAChD;AAsFD,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,wBAAwB,GAAG,MAAM,CA4CjF;AAED,gGAAgG;AAChG,wBAAgB,WAAW,CAAC,UAAU,EAAE,wBAAwB,GAAG,MAAM,EAAE,CAQ1E;AAMD,oDAAoD;AACpD,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AAerD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,wBAAwB,GAAG,MAAM,CAO7E;AAED,0DAA0D;AAC1D,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,wBAAwB,GAAG,MAAM,CAE7E"}

package/dist/template/index.d.ts

@@ -0,0 +1,4 @@
+export { DockerTemplate, type DockerTemplateOptions, type DockerTemplateBuildOptions, type DockerTemplateBuildResult, type DockerTemplateSecrets, } from './template.js';
+export { createDockerRepoTemplate, type DockerRepoTemplateOptions, type DockerRepoTemplateResolver, type RepositoryAccess, } from './repo-template.js';
+export { type AptInstallOptions, type DockerTemplateDefinition, type DockerTemplateOperation, type NpmInstallOptions, type PipInstallOptions, type RunWithSecretsOptions, secretNames, synthesizeDockerfile, templateIdentity, templateImageTag, TEMPLATE_IMAGE_REPO, } from './dockerfile.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/template/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/template/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,GAC3B,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,wBAAwB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAC/B,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,WAAW,EACX,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,cAAc,CAAC"}

package/dist/template/repo-template.d.ts

@@ -0,0 +1,115 @@
+/**
+ * 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'],
+ *   }),
+ * });
+ * ```
+ */
+import type { DockerOptions } from 'dockerode';
+import { DockerTemplate } from './template.js';
+/**
+ * Repository clone target plus an optional credential. Structurally identical
+ * to the E2B/platform type of the same name so a host can pass its context
+ * accessor straight through.
+ */
+export interface RepositoryAccess {
+    /** https clone URL, e.g. `https://github.com/acme/widgets.git`. */
+    cloneUrl: string;
+    /** Credential for private repositories; presented to git as `x-access-token:<token>` basic auth. */
+    authorization?: {
+        scheme: 'bearer';
+        token: string;
+    };
+}
+export interface DockerRepoTemplateOptions {
+    /**
+     * Resolves the clone URL and, for private repositories, a short-lived
+     * credential. Called once per template resolution (each container-creating
+     * `start()`): the credential authenticates the head lookup and the build's
+     * clone. It is passed to the build by value, never through `process.env`,
+     * and is excluded from the template identity so rotation does not rebuild.
+     *
+     * Pass `undefined` for the function itself to mean "no repository":
+     * {@link createDockerRepoTemplate} then returns undefined so
+     * `template: createDockerRepoTemplate(ctx)` needs no conditional. If the
+     * function resolves to `undefined` at start time, the resolver rejects.
+     */
+    getRepositoryAccess: (() => Promise<RepositoryAccess | undefined>) | undefined;
+    /**
+     * Branch, tag, or commit to prepare. The current head of a branch/tag is
+     * resolved at each template resolution and pinned into the identity.
+     * @default the remote's default branch
+     */
+    ref?: string;
+    /** Setup command(s) run inside the checkout as separate cached build steps. */
+    setupCommand?: string | string[];
+    /**
+     * Extra environment for every build step, including `setupCommand`. Baked
+     * into the image via `ENV` and hashed into the identity (keys and values),
+     * so it must be non-secret; put rotating credentials in
+     * {@link getRepositoryAccess} instead.
+     */
+    buildEnv?: Record<string, string> | (() => Promise<Record<string, string>>);
+    /**
+     * Absolute parent for the checkout; the repo lands at
+     * `<workingDirectory>/<repo>`, which becomes the build and runtime cwd.
+     * @default '/workspace'
+     */
+    workingDirectory?: string;
+    /**
+     * Base image. A custom base must provide `git` and `ca-certificates`; the
+     * default has them apt-installed as the first (cached) layer.
+     * @default 'node:22-slim'
+     */
+    baseImage?: string;
+    /** Pass-through dockerode connection options. */
+    dockerOptions?: DockerOptions;
+}
+/** A resolver producing a fresh, head-pinned template on each call. */
+export type DockerRepoTemplateResolver = () => Promise<DockerTemplate>;
+export declare function createDockerRepoTemplate(options: DockerRepoTemplateOptions): DockerRepoTemplateResolver | undefined;
+interface RepoTemplateInputs {
+    cloneUrl: string;
+    sha: string;
+    token?: string;
+    buildEnv?: Record<string, string>;
+    setupCommand?: string | string[];
+    workingDirectory: string;
+    baseImage?: string;
+    dockerOptions?: 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
+ */
+export declare function buildRepoTemplate(inputs: RepoTemplateInputs): DockerTemplate;
+/**
+ * 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.
+ */
+export declare function resolveHead(cloneUrl: string, ref: string | undefined, token: string | undefined): Promise<string | undefined>;
+export {};
+//# sourceMappingURL=repo-template.d.ts.map

package/dist/template/repo-template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-template.d.ts","sourceRoot":"","sources":["../../src/template/repo-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAkB5C;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,oGAAoG;IACpG,aAAa,CAAC,EAAE;QAAE,MAAM,EAAE,QAAQ,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACrD;AAED,MAAM,WAAW,yBAAyB;IACxC;;;;;;;;;;;OAWG;IACH,mBAAmB,EAAE,CAAC,MAAM,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAAC,GAAG,SAAS,CAAC;IAC/E;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAC5E;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,uEAAuE;AACvE,MAAM,MAAM,0BAA0B,GAAG,MAAM,OAAO,CAAC,cAAc,CAAC,CAAC;AAEvE,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,0BAA0B,GAAG,SAAS,CAUnH;AAiCD,UAAU,kBAAkB;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACjC,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,kBAAkB,GAAG,cAAc,CAwC5E;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,KAAK,EAAE,MAAM,GAAG,SAAS,GACxB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CA4B7B"}

package/dist/template/template.d.ts

@@ -0,0 +1,174 @@
+/**
+ * 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
+ * ```
+ */
+import Docker from 'dockerode';
+import { DockerSandbox, type DockerSandboxOptions } from '../sandbox/index.js';
+import { type AptInstallOptions, type DockerTemplateDefinition, type DockerTemplateOperation, type NpmInstallOptions, type PipInstallOptions, type RunWithSecretsOptions } from './dockerfile.js';
+export interface DockerTemplateOptions {
+    /**
+     * Base image for the template.
+     * @default 'node:22-slim'
+     */
+    baseImage?: string;
+    /** Pass-through dockerode connection options (socket path, host, TLS certs). */
+    dockerOptions?: Docker.DockerOptions;
+    /**
+     * Values for the secrets named by {@link DockerTemplate.runWithSecrets}.
+     * Supplying them here (rather than via `process.env`) keeps concurrent
+     * builds with different credentials from racing on shared process state.
+     * Not part of the template identity.
+     */
+    secrets?: DockerTemplateSecrets;
+}
+/**
+ * Values for the secrets named by `runWithSecrets`, keyed by name. Either a
+ * record or a function producing one (called once per real build, so rotated
+ * credentials are picked up without rebuilding the template object).
+ */
+export type DockerTemplateSecrets = Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+export interface DockerTemplateBuildOptions {
+    /**
+     * Rebuild even if an image with the computed tag already exists locally,
+     * re-executing every step instead of reusing the daemon's layer cache (the
+     * cache does not key on secret values or on what `git clone`/`npm install`
+     * would fetch today).
+     */
+    force?: boolean;
+    /**
+     * Build on this Docker client instead of the template's own. A sandbox
+     * passes its client so the image lands on the daemon that will run it.
+     */
+    docker?: Docker;
+    /**
+     * Secret values for this build. Overrides the template-level `secrets`
+     * source for names it provides. Names still missing after both sources are
+     * read from `process.env` as a last resort.
+     */
+    secrets?: DockerTemplateSecrets;
+}
+export interface DockerTemplateBuildResult {
+    status: 'ready' | 'failed';
+    /** The local image tag (`mastra-template:<hash>`) the template resolves to. */
+    templateId: string;
+    /** Failure detail when `status` is `'failed'`. */
+    error?: string;
+}
+/**
+ * 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.
+ */
+export declare class DockerTemplate {
+    #private;
+    constructor(options?: DockerTemplateOptions, state?: DockerTemplateState);
+    /** Set the base image. */
+    from(image: string): DockerTemplate;
+    /** Set the working directory for subsequent steps and the runtime container. */
+    setWorkdir(path: string): DockerTemplate;
+    /**
+     * 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: Record<string, string>): DockerTemplate;
+    /** Run a command (or `&&`-joined list of commands) as a build step. */
+    runCmd(command: string | string[]): DockerTemplate;
+    /**
+     * 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: string | string[], options: RunWithSecretsOptions): DockerTemplate;
+    /** Install apt packages. */
+    aptInstall(packages: string | string[], options?: AptInstallOptions): DockerTemplate;
+    /** Install pip packages (or `pip install .` for the current workdir when omitted). */
+    pipInstall(packages?: string | string[], options?: PipInstallOptions): DockerTemplate;
+    /** Install npm packages (or run `npm install` for the current workdir when omitted). */
+    npmInstall(packages?: string | string[], options?: NpmInstallOptions): DockerTemplate;
+    /** The resolved definition (base image + ordered operations). */
+    get definition(): DockerTemplateDefinition;
+    /** The synthesized Dockerfile for this template. */
+    get dockerfile(): string;
+    /** The content-addressed local image tag this template resolves to. */
+    get templateId(): string;
+    /**
+     * 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(): string | undefined;
+    /**
+     * 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`.
+     */
+    build(options?: DockerTemplateBuildOptions): Promise<DockerTemplateBuildResult>;
+    /**
+     * 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.
+     */
+    createSandbox(options?: Omit<DockerSandboxOptions, 'image' | 'template'>): Promise<DockerSandbox>;
+    /**
+     * 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.
+     */
+    dispose(): Promise<void>;
+}
+interface DockerTemplateState {
+    baseImage: string;
+    operations: readonly DockerTemplateOperation[];
+}
+export {};
+//# sourceMappingURL=template.d.ts.map

package/dist/template/template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../src/template/template.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/docker",
-  "version": "0.8.0-alpha.2",
+  "version": "0.9.0-alpha.0",
   "description": "Docker container sandbox provider for Mastra workspaces",
   "type": "module",
   "main": "dist/index.js",
@@ -20,6 +20,7 @@
   },
   "license": "Apache-2.0",
   "dependencies": {
+    "@grpc/grpc-js": "^1.14.4",
     "dockerode": "^4.0.9",
     "tar-stream": "^3.1.7"
   },
@@ -27,16 +28,17 @@
     "@types/dockerode": "^4.0.1",
     "@types/tar-stream": "^3.1.3",
     "@types/node": "22.20.1",
-    "@vitest/coverage-v8": "4.1.10",
-    "@vitest/ui": "4.1.10",
+    "@vitest/coverage-v8": "4.1.11",
+    "@vitest/ui": "4.1.11",
     "eslint": "^10.7.0",
     "tsdown": "0.22.9",
     "typescript": "^7.0.2",
-    "vitest": "4.1.10",
-    "@internal/types-builder": "0.0.107",
-    "@internal/workspace-test-utils": "0.0.76",
-    "@mastra/core": "1.67.0-alpha.6",
-    "@internal/lint": "0.0.132"
+    "vitest": "4.1.11",
+    "@internal/lint": "0.0.133",
+    "@internal/types-builder": "0.0.108",
+    "@internal/workspace": "0.0.5",
+    "@internal/workspace-test-utils": "0.0.77",
+    "@mastra/core": "1.68.0-alpha.5"
   },
   "peerDependencies": {
     "@mastra/core": ">=1.67.0-0 <2.0.0-0"