@mastra/docker 0.8.0 → 0.9.0-alpha.1

package/README.md

@@ -62,6 +62,105 @@ const workspace = new Workspace({
 > starts, otherwise the mount fails. Provision it ahead of time (for example,
 > with a one-off container that creates `conversations/abc123` in the volume).
 
+### Templates
+
+`DockerTemplate` prepares a reusable environment once — a base image plus ordered
+setup commands, env vars, and package installs — then spawns multiple disposable
+sandboxes from it. Each sandbox is a fresh container with its own writable layer
+over the shared read-only image, so their filesystems are independent. The image
+is produced by synthesizing a `Dockerfile` and running `docker build` (not
+`docker commit`), so setup is baked into reproducible, cached, content-addressed
+layers.
+
+```typescript
+import { DockerSandbox, DockerTemplate } from '@mastra/docker';
+
+const template = new DockerTemplate({ baseImage: 'node:22-slim' })
+  .aptInstall(['git', 'ca-certificates'])
+  .runCmd('git clone --depth=1 https://example.com/repo /workspace/app')
+  .setWorkdir('/workspace/app')
+  .runCmd('npm ci');
+
+// Prepare once, spawn many — each has an independent writable filesystem.
+// The sandbox builds the image on first start() and reuses it afterwards,
+// and its working directory follows the template's last setWorkdir().
+const a = new DockerSandbox({ template });
+const b = new DockerSandbox({ template });
+
+// Or build explicitly, e.g. to surface failures before creating sandboxes.
+const result = await template.build();
+if (result.status !== 'ready') throw new Error(result.error);
+
+// Remove the built image when done (independent of any sandbox's destroy()).
+await template.dispose();
+```
+
+`template` also accepts an async factory (`() => Promise<DockerTemplate>`),
+resolved once per container-creating `start()`; this is how repository
+templates track a moving branch.
+
+Builder methods (`from`, `setWorkdir`, `setEnvs`, `runCmd`, `aptInstall`,
+`pipInstall`, `npmInstall`) are immutable and chainable — each returns a new
+template, and their signatures match the E2B and platform template builders.
+The image tag is content-addressed (`mastra-template:<hash>`), so `build()` is
+idempotent and reuses an existing image unless you pass `{ force: true }`,
+which also bypasses the daemon's layer cache so every step really re-runs.
+
+Never put secrets in `setEnvs` — they are baked into the image. For a step that
+needs a credential, use `runWithSecrets`: the command runs in a throwaway build
+stage forked from the steps before it, and only `output` is copied into the
+image. Secret values are passed by value (`new DockerTemplate({ secrets })` or
+`build({ secrets })`, falling back to `process.env`) and never enter the template
+identity. Values are delivered through BuildKit secret mounts, so they never
+land in any layer, history entry, or build-cache metadata — only in a tmpfs
+visible to that one `RUN`. Builds that use secrets require a BuildKit-capable
+daemon (Docker 20.10+).
+
+```typescript
+const template = new DockerTemplate({ secrets: { GITHUB_TOKEN: token } })
+  .aptInstall(['git', 'ca-certificates'])
+  .runWithSecrets(
+    'git -c http.extraheader="AUTHORIZATION: bearer $GITHUB_TOKEN" clone https://github.com/acme/private.git /workspace/app',
+    {
+      secrets: ['GITHUB_TOKEN'],
+      output: '/workspace/app',
+    },
+  )
+  .setWorkdir('/workspace/app')
+  .runCmd('npm ci');
+```
+
+`dispose()` removes the image; Docker refuses while a container still references
+it, so destroy the template's sandboxes first.
+
+#### Repository templates
+
+`createDockerRepoTemplate` prepares a repository checkout plus setup commands,
+with the same options as the E2B and platform repo templates. It returns a
+template factory for the sandbox's `template` option: on each resolution it
+calls `getRepositoryAccess`, resolves the current head of `ref` (default
+branch when omitted) with `git ls-remote`, and pins that commit into the
+template identity — so a moved branch yields a fresh image for the next sandbox
+while an unmoved one reuses the cached image. The credential is used only for
+the head lookup and the clone stage; it never enters the identity or the image.
+
+```typescript
+import { DockerSandbox, createDockerRepoTemplate } from '@mastra/docker';
+
+const sandbox = new DockerSandbox({
+  template: createDockerRepoTemplate({
+    getRepositoryAccess: async () => ({
+      cloneUrl: 'https://github.com/acme/app.git',
+      authorization: { scheme: 'bearer', token: await mintInstallationToken() }, // private repos
+    }),
+    ref: 'main', // branch, tag, or commit; omit for the default branch
+    setupCommand: ['npm ci', 'npm run build'],
+    buildEnv: { NPM_CONFIG_REGISTRY: 'https://registry.example.com' }, // non-secret, part of the identity
+    workingDirectory: '/workspace', // checkout lands at /workspace/app and becomes the cwd
+  }),
+});
+```
+
 ## Documentation
 
 - [Docker Sandbox integration guide](https://mastra.ai/integrations/sandboxes/docker)