Skip to main content

DockerSandbox

Executes commands inside Docker containers on the local machine. 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.

info

For interface details, see WorkspaceSandbox interface.

Installation
Direct link to Installation

npm install @mastra/docker

Requires Docker Engine running on the host machine.

Usage
Direct link to Usage

Add a DockerSandbox to a workspace and assign it to an agent:

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

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

Constructor parameters
Direct link to Constructor parameters

id?:

string
= Auto-generated
Unique identifier for this sandbox instance. Used for container naming and reconnection via labels.

image?:

string
= 'node:22-slim'
Docker image to use for the container.

command?:

string[]
= ['sleep', 'infinity']
Container entrypoint command. Must keep the container alive for exec-based command execution.

env?:

Record<string, string>
Environment variables to set in the container.

volumes?:

Record<string, string>
Host-to-container bind mounts. Keys are host paths, values are container paths.

network?:

string
Docker network to join.

privileged?:

boolean
= false
Run in privileged mode.

workingDir?:

string
= '/workspace'
Working directory inside the container.

labels?:

Record<string, string>
Additional container labels. Mastra labels (mastra.sandbox, mastra.sandbox.id) are always included.

timeout?:

number
= 300000 (5 minutes)
Default command timeout in milliseconds.

dockerOptions?:

Docker.DockerOptions
Pass-through dockerode connection options for custom socket paths, remote hosts, or TLS certificates.

instructions?:

string | function
Custom instructions that override the default instructions returned by getInstructions(). Pass an empty string to suppress instructions.

Properties
Direct link to Properties

id:

string
Sandbox instance identifier.

name:

string
Provider name ('DockerSandbox').

provider:

string
Provider identifier ('docker').

status:

ProviderStatus
'pending' | 'starting' | 'running' | 'stopping' | 'stopped' | 'destroying' | 'destroyed' | 'error'

container:

Container
The underlying dockerode Container instance. Throws SandboxNotReadyError if the sandbox has not been started.

processes:

DockerProcessManager
Background process manager. See [SandboxProcessManager reference](/reference/workspace/process-manager).

Background processes
Direct link to Background processes

DockerSandbox includes a built-in process manager for spawning and managing background processes. Processes run inside the container using docker exec.

const sandbox = new DockerSandbox({ id: 'dev-sandbox' })
await sandbox._start()

// Spawn a background process
const handle = await sandbox.processes.spawn('node server.js', {
  env: { PORT: '3000' },
  onStdout: data => console.log(data),
})

// Interact with the process
console.log(handle.stdout)
await handle.sendStdin('input\n')
await handle.kill()

See SandboxProcessManager reference for the full API.

Environment variables
Direct link to Environment variables

Set environment variables at the container level with env. Per-command environment variables can also be passed when spawning processes:

const sandbox = new DockerSandbox({
  image: 'node:22-slim',
  env: {
    NODE_ENV: 'production',
    DATABASE_URL: 'postgres://localhost:5432/mydb',
  },
})

Bind mounts
Direct link to Bind mounts

Mount host directories into the container using the volumes option:

const sandbox = new DockerSandbox({
  image: 'node:22-slim',
  volumes: {
    '/my/project': '/workspace/project',
    '/shared/data': '/data',
  },
})

Bind mounts are applied at container creation time. The host paths must exist before the sandbox starts.

Reconnection
Direct link to Reconnection

DockerSandbox can reconnect to existing containers by matching labels. When start() is called, it checks for a container with the mastra.sandbox.id label matching the sandbox ID. If found:

  • A running container is reused directly.
  • A stopped container is restarted.
// First run — creates a new container
const sandbox = new DockerSandbox({ id: 'persistent-sandbox' })
await sandbox._start()

// Later — reconnects to the existing container
const sandbox2 = new DockerSandbox({ id: 'persistent-sandbox' })
await sandbox2._start()

Docker connection options
Direct link to Docker connection options

Connect to remote Docker hosts or use custom socket paths via dockerOptions:

// Remote Docker host
const sandbox = new DockerSandbox({
  dockerOptions: {
    host: '192.168.1.100',
    port: 2376,
    ca: fs.readFileSync('ca.pem'),
    cert: fs.readFileSync('cert.pem'),
    key: fs.readFileSync('key.pem'),
  },
})

// Custom socket path
const sandbox = new DockerSandbox({
  dockerOptions: {
    socketPath: '/var/run/docker.sock',
  },
})
On this page