0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00
mastra/workspaces/docker
History 2026-11-12 21:12:29 +00:00
..
src Add Docker Cloud Sandboxes microVM provider to @mastra/docker (#29356) 2026-11-11 01:23:38 -08:00
CHANGELOG.md chore: version - exit prerelease mode 2026-11-12 21:12:29 +00:00
lint-staged.config.js refactor(lint): replace ESLint with type-aware oxlint (#27476) 2026-10-18 10:38:35 -07:00
package.json chore: version - exit prerelease mode 2026-11-12 21:12:29 +00:00
README.md feat(docker): expose DockerTemplate build progress and bounded output (#26682) 2026-10-18 09:54:06 -07:00
tsconfig.build.json feat(docker): add Docker container sandbox provider [COR-399] (#14500) 2026-04-16 10:15:09 -07:00
tsconfig.json chore: migrate package builds to tsdown (#19829) 2026-07-28 12:32:21 +02:00
tsdown.config.ts feat(docker): add DockerTemplate API for reusable prepared images (#24199) 2026-09-16 16:05:58 -07:00
vitest.config.ts feat(docker): add Docker container sandbox provider [COR-399] (#14500) 2026-04-16 10:15:09 -07:00

@mastra/docker

Docker container sandbox provider for Mastra workspaces. Uses long-lived containers with docker exec for command execution. Targets local development, CI/CD, air-gapped deployments, and cost-sensitive scenarios where cloud sandboxes are unnecessary.

Installation

npm install @mastra/docker

Usage

import { Agent } from '@mastra/core/agent';
import { Workspace } from '@mastra/core/workspace';
import { DockerSandbox } from '@mastra/docker';

const workspace = new Workspace({
  sandbox: new DockerSandbox({
    image: 'node:22-slim',
    timeout: 60_000, // 60 second timeout (default: 5 minutes)
  }),
});

const agent = new Agent({
  name: 'my-agent',
  model: 'anthropic/claude-opus-4-6',
  workspace,
});

Volume subpath mounts

Use mounts (mapped 1:1 onto Docker's HostConfig.Mounts) when you need mount options that the -v/volumes syntax cannot express — most notably mounting a subdirectory of a named volume. Requires Docker Engine 26.0+ (API v1.45+) for subpath.

const workspace = new Workspace({
  sandbox: new DockerSandbox({
    image: 'node:22-slim',
    mounts: [
      // Read-only parent from a named volume
      { type: 'volume', source: 'project-data', target: '/shared', readOnly: true },
      // Writable per-conversation subdirectory of the same volume
      {
        type: 'volume',
        source: 'project-data',
        target: '/work',
        volumeOptions: { subpath: 'conversations/abc123' },
      },
    ],
  }),
});

volumes and mounts can be combined; both are passed through to Docker.

Note: Docker does not create volumeOptions.subpath for you — the subdirectory must already exist inside the named volume before the container 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.

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);

// Cancel repository resolution or template preparation when needed.
const controller = new AbortController();
await a.start({ abortSignal: controller.signal });
// Explicit builds accept the same option: template.build({ abortSignal: controller.signal }).

// 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. Concurrent callers share preparation work, but each caller can cancel its own wait independently; the underlying build is cancelled only after its last active caller aborts.

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+).

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.

Build progress

Pass onProgress to build() (or onTemplateBuildProgress to DockerSandbox) to follow a long preparation while it runs:

const result = await template.build({
  onProgress: event => {
    if (event.type === 'step-start') console.log(`> ${event.step.name}${event.step.cached ? ' (cached)' : ''}`);
    if (event.type === 'output') process.stdout.write(redact(event.text));
  },
  maxOutputBytes: 32 * 1024, // default 64 KiB
});
if (result.status === 'failed') {
  console.error(result.error, result.failedStep?.name, result.output, result.outputTruncated);
}

Events are reused (the image already exists, nothing is built), build-start (with builder: 'legacy' | 'buildkit'), step-start, step-complete (with cached when the builder reports a cache hit), output, and build-complete. Plain builds use the legacy builder, which reports Step N/M steps; builds with secrets use BuildKit, which reports build vertices. The callback contract:

  • Delivery is synchronous, in arrival order, with no backpressure — keep the callback fast and hand heavy work off elsewhere.
  • Errors thrown by the callback are ignored and never fail the build.
  • Concurrent callers sharing a build each receive its events from the moment they join (no replay). A caller that aborts stops receiving events; the build continues for the remaining callers.
  • Only the most recent maxOutputBytes of output are retained, and only to populate output on failed results; outputTruncated reports whether older output was dropped.
  • output text is raw command output. Commands run with runWithSecrets can echo secret values into it, so redact before logging or persisting.

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.

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
  }),
});

If baseImage runs as a non-root USER, set owner to that user (for example owner: 'node' or owner: '1000:1000'). The checkout is then copied with COPY --chown, so git and setup commands can write to it. Without owner, the checkout is owned by root.

Documentation

Changelog

See the package changelog for version history and release notes.

Support

We have an open community Discord. Come and say hello and let us know if you have any questions or need any help getting things running.