@mastra/docker 0.0.0-knowledge-org-scope-20260902233451 → 0.0.0-knowledge-w2-20261007195847

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -29,6 +29,146 @@ const agent = new Agent({
29
29
  });
30
30
  ```
31
31
 
32
+ ### Volume subpath mounts
33
+
34
+ Use `mounts` (mapped 1:1 onto Docker's `HostConfig.Mounts`) when you need mount
35
+ options that the `-v`/`volumes` syntax cannot express — most notably mounting a
36
+ subdirectory of a named volume. Requires Docker Engine 26.0+ (API v1.45+) for
37
+ `subpath`.
38
+
39
+ ```typescript
40
+ const workspace = new Workspace({
41
+ sandbox: new DockerSandbox({
42
+ image: 'node:22-slim',
43
+ mounts: [
44
+ // Read-only parent from a named volume
45
+ { type: 'volume', source: 'project-data', target: '/shared', readOnly: true },
46
+ // Writable per-conversation subdirectory of the same volume
47
+ {
48
+ type: 'volume',
49
+ source: 'project-data',
50
+ target: '/work',
51
+ volumeOptions: { subpath: 'conversations/abc123' },
52
+ },
53
+ ],
54
+ }),
55
+ });
56
+ ```
57
+
58
+ `volumes` and `mounts` can be combined; both are passed through to Docker.
59
+
60
+ > **Note:** Docker does not create `volumeOptions.subpath` for you — the
61
+ > subdirectory must already exist inside the named volume before the container
62
+ > starts, otherwise the mount fails. Provision it ahead of time (for example,
63
+ > with a one-off container that creates `conversations/abc123` in the volume).
64
+
65
+ ### Templates
66
+
67
+ `DockerTemplate` prepares a reusable environment once — a base image plus ordered
68
+ setup commands, env vars, and package installs — then spawns multiple disposable
69
+ sandboxes from it. Each sandbox is a fresh container with its own writable layer
70
+ over the shared read-only image, so their filesystems are independent. The image
71
+ is produced by synthesizing a `Dockerfile` and running `docker build` (not
72
+ `docker commit`), so setup is baked into reproducible, cached, content-addressed
73
+ layers.
74
+
75
+ ```typescript
76
+ import { DockerSandbox, DockerTemplate } from '@mastra/docker';
77
+
78
+ const template = new DockerTemplate({ baseImage: 'node:22-slim' })
79
+ .aptInstall(['git', 'ca-certificates'])
80
+ .runCmd('git clone --depth=1 https://example.com/repo /workspace/app')
81
+ .setWorkdir('/workspace/app')
82
+ .runCmd('npm ci');
83
+
84
+ // Prepare once, spawn many — each has an independent writable filesystem.
85
+ // The sandbox builds the image on first start() and reuses it afterwards,
86
+ // and its working directory follows the template's last setWorkdir().
87
+ const a = new DockerSandbox({ template });
88
+ const b = new DockerSandbox({ template });
89
+
90
+ // Or build explicitly, e.g. to surface failures before creating sandboxes.
91
+ const result = await template.build();
92
+ if (result.status !== 'ready') throw new Error(result.error);
93
+
94
+ // Cancel repository resolution or template preparation when needed.
95
+ const controller = new AbortController();
96
+ await a.start({ abortSignal: controller.signal });
97
+ // Explicit builds accept the same option: template.build({ abortSignal: controller.signal }).
98
+
99
+ // Remove the built image when done (independent of any sandbox's destroy()).
100
+ await template.dispose();
101
+ ```
102
+
103
+ `template` also accepts an async factory (`() => Promise<DockerTemplate>`),
104
+ resolved once per container-creating `start()`; this is how repository
105
+ templates track a moving branch.
106
+
107
+ Builder methods (`from`, `setWorkdir`, `setEnvs`, `runCmd`, `aptInstall`,
108
+ `pipInstall`, `npmInstall`) are immutable and chainable — each returns a new
109
+ template, and their signatures match the E2B and platform template builders.
110
+ The image tag is content-addressed (`mastra-template:<hash>`), so `build()` is
111
+ idempotent and reuses an existing image unless you pass `{ force: true }`,
112
+ which also bypasses the daemon's layer cache so every step really re-runs.
113
+ Concurrent callers share preparation work, but each caller can cancel its own
114
+ wait independently; the underlying build is cancelled only after its last
115
+ active caller aborts.
116
+
117
+ Never put secrets in `setEnvs` — they are baked into the image. For a step that
118
+ needs a credential, use `runWithSecrets`: the command runs in a throwaway build
119
+ stage forked from the steps before it, and only `output` is copied into the
120
+ image. Secret values are passed by value (`new DockerTemplate({ secrets })` or
121
+ `build({ secrets })`, falling back to `process.env`) and never enter the template
122
+ identity. Values are delivered through BuildKit secret mounts, so they never
123
+ land in any layer, history entry, or build-cache metadata — only in a tmpfs
124
+ visible to that one `RUN`. Builds that use secrets require a BuildKit-capable
125
+ daemon (Docker 20.10+).
126
+
127
+ ```typescript
128
+ const template = new DockerTemplate({ secrets: { GITHUB_TOKEN: token } })
129
+ .aptInstall(['git', 'ca-certificates'])
130
+ .runWithSecrets(
131
+ 'git -c http.extraheader="AUTHORIZATION: bearer $GITHUB_TOKEN" clone https://github.com/acme/private.git /workspace/app',
132
+ {
133
+ secrets: ['GITHUB_TOKEN'],
134
+ output: '/workspace/app',
135
+ },
136
+ )
137
+ .setWorkdir('/workspace/app')
138
+ .runCmd('npm ci');
139
+ ```
140
+
141
+ `dispose()` removes the image; Docker refuses while a container still references
142
+ it, so destroy the template's sandboxes first.
143
+
144
+ #### Repository templates
145
+
146
+ `createDockerRepoTemplate` prepares a repository checkout plus setup commands,
147
+ with the same options as the E2B and platform repo templates. It returns a
148
+ template factory for the sandbox's `template` option: on each resolution it
149
+ calls `getRepositoryAccess`, resolves the current head of `ref` (default
150
+ branch when omitted) with `git ls-remote`, and pins that commit into the
151
+ template identity — so a moved branch yields a fresh image for the next sandbox
152
+ while an unmoved one reuses the cached image. The credential is used only for
153
+ the head lookup and the clone stage; it never enters the identity or the image.
154
+
155
+ ```typescript
156
+ import { DockerSandbox, createDockerRepoTemplate } from '@mastra/docker';
157
+
158
+ const sandbox = new DockerSandbox({
159
+ template: createDockerRepoTemplate({
160
+ getRepositoryAccess: async () => ({
161
+ cloneUrl: 'https://github.com/acme/app.git',
162
+ authorization: { scheme: 'bearer', token: await mintInstallationToken() }, // private repos
163
+ }),
164
+ ref: 'main', // branch, tag, or commit; omit for the default branch
165
+ setupCommand: ['npm ci', 'npm run build'],
166
+ buildEnv: { NPM_CONFIG_REGISTRY: 'https://registry.example.com' }, // non-secret, part of the identity
167
+ workingDirectory: '/workspace', // checkout lands at /workspace/app and becomes the cwd
168
+ }),
169
+ });
170
+ ```
171
+
32
172
  ## Documentation
33
173
 
34
174
  - [Docker Sandbox integration guide](https://mastra.ai/integrations/sandboxes/docker)
@@ -0,0 +1,7 @@
1
+ import { SandboxAbortError } from '@mastra/core/workspace';
2
+ export declare function createAbortError(signal: AbortSignal, operation: string): SandboxAbortError;
3
+ export declare function throwIfAborted(signal: AbortSignal | undefined, operation: string): void;
4
+ export declare function isAbortError(error: unknown): boolean;
5
+ export declare function normalizeAbortError(error: unknown, operation: string): unknown;
6
+ export declare function waitForAbortable<T>(promise: Promise<T>, signal: AbortSignal | undefined, operation: string, onAbort?: () => void): Promise<T>;
7
+ //# sourceMappingURL=abort.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../src/abort.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,iBAAiB,CAE1F;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAEvF;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKpD;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAM9E;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,IAAI,GACnB,OAAO,CAAC,CAAC,CAAC,CAqBZ"}