@mastra/core/dist/docs/references/docs-workspace-sandbox.md

Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.

# Sandbox

**Added in:** `@mastra/core@1.1.0`

Sandbox providers give agents the ability to execute shell commands. When you configure a sandbox on a workspace, agents can run commands as part of their tasks.

A sandbox provider executes commands in a controlled environment:

- **Command execution**: Run shell commands with arguments
- **Background processes**: Spawn long-running processes like dev servers and watchers
- **Working directory**: Commands run from a specific directory
- **Environment variables**: Control what variables are available
- **Timeouts**: Prevent long-running commands from hanging
- **Isolation**: Optional OS-level sandboxing for security

## Supported providers

- [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox): Executes commands on the local machine
- [`BlaxelSandbox`](https://mastra.ai/reference/workspace/blaxel-sandbox): Executes commands in isolated Blaxel cloud sandboxes
- [`DaytonaSandbox`](https://mastra.ai/reference/workspace/daytona-sandbox): Executes commands in isolated Daytona cloud sandboxes
- [`E2BSandbox`](https://mastra.ai/reference/workspace/e2b-sandbox): Executes commands in isolated E2B cloud sandboxes
- [`ModalSandbox`](https://mastra.ai/reference/workspace/modal-sandbox): Executes commands in isolated Modal cloud sandboxes

## Basic usage

Create a workspace with a sandbox and assign it to an agent. The agent can then execute shell commands:

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './workspace',
  }),
  sandbox: new LocalSandbox({
    workingDirectory: './workspace',
  }),
})

const agent = new Agent({
  id: 'dev-agent',
  model: 'openai/gpt-5.4',
  instructions: 'You are a helpful development assistant.',
  workspace,
})

// The agent now has the execute_command tool available
const response = await agent.generate('Run `ls -la` in the workspace directory')
```

See [`LocalSandbox` reference](https://mastra.ai/reference/workspace/local-sandbox) for configuration options including environment isolation and native OS sandboxing.

## Agent tools

When you configure a sandbox on a workspace, agents receive the `execute_command` tool for running shell commands.

If your sandbox provider supports running processes in the background, the `execute_command` tool also accepts `background: true` for starting long-running processes, and two additional tools are registered:

| Tool                 | Description                                                                                                                                |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `execute_command`    | Run a shell command. Returns stdout, stderr, and exit code. Supports `background: true` to spawn a long-running process and return a PID.  |
| `get_process_output` | Get stdout, stderr, and status of a background process by PID. Supports `tail` to limit output lines and `wait: true` to block until exit. |
| `kill_process`       | Stop a background process by PID. Returns recent output.                                                                                   |

These tools are registered automatically. See [Workspace class reference](https://mastra.ai/reference/workspace/workspace-class) for the full tool name list.

## Background process callbacks

When agents start background processes through the `execute_command` tool, you can receive lifecycle callbacks for stdout, stderr, and process exit. Configure these through the `backgroundProcesses` option on the `execute_command` tool:

```typescript
import { Workspace, LocalSandbox, WORKSPACE_TOOLS } from '@mastra/core/workspace'

const workspace = new Workspace({
  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
  tools: {
    [WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND]: {
      backgroundProcesses: {
        onStdout: (data, { pid }) => console.log(`[${pid}] ${data}`),
        onStderr: (data, { pid }) => console.error(`[${pid}] ${data}`),
        onExit: ({ pid, exitCode }) => console.log(`Process ${pid} exited: ${exitCode}`),
      },
    },
  },
})
```

These callbacks fire for all background processes started by the agent through the `execute_command` tool.

### Abort signal

By default, background processes inherit the agent's abort signal and are killed when the agent disconnects. Control this behavior with the `abortSignal` option:

- **`undefined`** (default): Uses the agent's abort signal
- **`AbortSignal`**: Uses a custom signal
- **`null` or `false`**: Disables abort — processes persist after agent shutdown

```typescript
import { Workspace, LocalSandbox, WORKSPACE_TOOLS } from '@mastra/core/workspace'

const workspace = new Workspace({
  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
  tools: {
    [WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND]: {
      backgroundProcesses: {
        abortSignal: null, // Processes survive agent disconnection
      },
    },
  },
})
```

Use `null` or `false` for cloud sandboxes (for example, E2B, Daytona, or Modal) where processes should outlive the agent.

> **Note:** For the full `SandboxProcessManager` API (spawning processes programmatically, reading output, sending stdin), see the [`SandboxProcessManager` reference](https://mastra.ai/reference/workspace/process-manager).

## Related

- [`SandboxProcessManager` reference](https://mastra.ai/reference/workspace/process-manager)
- [`LocalSandbox` reference](https://mastra.ai/reference/workspace/local-sandbox)
- [`ModalSandbox` reference](https://mastra.ai/reference/workspace/modal-sandbox)
- [`DaytonaSandbox` reference](https://mastra.ai/reference/workspace/daytona-sandbox)
- [`E2BSandbox` reference](https://mastra.ai/reference/workspace/e2b-sandbox)
- [Workspace overview](https://mastra.ai/docs/workspace/overview)
- [Filesystem](https://mastra.ai/docs/workspace/filesystem)