# WorkspaceSandbox Interface

The `WorkspaceSandbox` interface defines how workspaces execute commands.

## 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.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

**Returns:** `Promise<CommandResult>`

```typescript
interface CommandResult {
  success: boolean;
  stdout: string;
  stderr: string;
  exitCode: number;
  executionTimeMs: number;
}
```

### `getInfo()`

Get sandbox status and resource information.

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

**Returns:** `Promise<SandboxInfo>`

```typescript
interface SandboxInfo {
  status: 'starting' | 'running' | 'stopped' | 'error';
  resources?: {
    memoryMB?: number;
    memoryUsedMB?: number;
    cpuCores?: number;
    cpuPercent?: number;
    diskMB?: number;
    diskUsedMB?: number;
  };
}
```

### `getInstructions()`

Get a description of how this sandbox works. Used in tool descriptions to help agents understand the execution context.

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

**Returns:** `string`

## Related

- [Workspace Class](https://mastra.ai/reference/workspace/workspace-class/llms.txt)
- [Filesystem Interface](https://mastra.ai/reference/workspace/filesystem/llms.txt)