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

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

# WorkspaceSandbox

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

The `WorkspaceSandbox` interface defines how workspaces execute commands and manage background processes.

## Properties

**processes** (`SandboxProcessManager`): Background process manager. If not implemented, process management tools won't be available. See SandboxProcessManager reference.

## Methods

### `start()`

Start the sandbox. Called automatically by `workspace.init()` or on first `executeCommand()` call.

```typescript
await sandbox.start()
```

This method prepares the sandbox for command execution.

### `stop()`

Stop the sandbox.

```typescript
await sandbox.stop?.()
```

### `destroy()`

Clean up sandbox resources. Called by `workspace.destroy()`.

```typescript
await sandbox.destroy()
```

### `executeCommand(command, args?, options?)`

Execute a shell command.

```typescript
const result = await sandbox.executeCommand('ls', ['-la', '/docs'])
const result = await sandbox.executeCommand('npm', ['install', 'lodash'])
```

**Parameters:**

**command** (`string`): Command to execute

**args** (`string[]`): Command arguments

**options** (`Options`): Configuration options.

**options.timeout** (`number`): Execution timeout in milliseconds

**options.cwd** (`string`): Working directory for the command

**options.env** (`Record<string, string>`): Additional environment variables

**options.onStdout** (`(data: string) => void`): Callback for stdout streaming

**options.onStderr** (`(data: string) => void`): Callback for stderr streaming

### `getInfo()`

Get sandbox status and resource information.

```typescript
const info = await sandbox.getInfo()
// { status: 'running', resources: { memoryMB: 512, cpuPercent: 5 } }
```

### `getInstructions(opts?)`

Returns a description of how this sandbox works. Injected into the agent's system message when the workspace is assigned to an agent.

```typescript
const instructions = sandbox.getInstructions?.()
// 'Local command execution. Working directory: "/workspace".'
```

**Parameters:**

**opts.requestContext** (`RequestContext`): Forwarded to the \`instructions\` function if one was provided in the constructor.

**Returns:** `string`

## Related

- [SandboxProcessManager reference](https://mastra.ai/reference/workspace/process-manager)
- [Sandbox](https://mastra.ai/docs/workspace/sandbox)
- [Workspace Class](https://mastra.ai/reference/workspace/workspace-class)
- [Filesystem Interface](https://mastra.ai/reference/workspace/filesystem)