# Sandbox

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.

## How it works

A sandbox provider executes commands in a controlled environment:

- **Command execution** - Run shell commands with arguments
- **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

When you assign a workspace with a sandbox to an agent, Mastra automatically includes the `execute_command` tool in the agent's toolset.

## Supported providers

Each provider page includes configuration options and usage examples:

- [LocalSandbox](https://mastra.ai/reference/workspace/local-sandbox/llms.txt) - Executes commands on the local machine

## Basic usage

Create a workspace with a sandbox and assign it to an agent. The agent can then execute shell commands as part of its tasks:

```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-4o',
  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/llms.txt) 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. See [Workspace Class Reference](https://mastra.ai/reference/workspace/workspace-class/llms.txt) for details.

## Related

- [LocalSandbox Reference](https://mastra.ai/reference/workspace/local-sandbox/llms.txt)
- [Workspace Overview](https://mastra.ai/docs/workspace/overview/llms.txt)
- [Filesystem](https://mastra.ai/docs/workspace/filesystem/llms.txt)