@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 +140 -0
- package/dist/abort.d.ts +7 -0
- package/dist/abort.d.ts.map +1 -0
- package/dist/index.cjs +1559 -79
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.ts +2 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1553 -81
- package/dist/index.js.map +1 -1
- package/dist/provider.d.ts +2 -0
- package/dist/provider.d.ts.map +1 -1
- package/dist/sandbox/index.d.ts +150 -3
- package/dist/sandbox/index.d.ts.map +1 -1
- package/dist/sandbox/kill-helper-exit.fixture.d.ts +2 -0
- package/dist/sandbox/kill-helper-exit.fixture.d.ts.map +1 -0
- package/dist/sandbox/process-manager.d.ts.map +1 -1
- package/dist/template/build-session.d.ts +22 -0
- package/dist/template/build-session.d.ts.map +1 -0
- package/dist/template/dockerfile.d.ts +81 -0
- package/dist/template/dockerfile.d.ts.map +1 -0
- package/dist/template/index.d.ts +4 -0
- package/dist/template/index.d.ts.map +1 -0
- package/dist/template/repo-template.d.ts +119 -0
- package/dist/template/repo-template.d.ts.map +1 -0
- package/dist/template/template.d.ts +176 -0
- package/dist/template/template.d.ts.map +1 -0
- package/package.json +14 -10
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)
|
package/dist/abort.d.ts
ADDED
|
@@ -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"}
|