ContextQMD
Back to Mastra

Reference: WorkspaceSandbox | Workspace

docs/src/content/en/reference/workspace/sandbox.mdx

2025-12-183.4 KB
Original Source

WorkspaceSandbox

Added in: @mastra/[email protected]

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

Properties

<PropertiesTable content={[ { name: 'processes', type: 'SandboxProcessManager', description: "Background process manager. If not implemented, process management tools won't be available. See SandboxProcessManager reference.", isOptional: true, }, ]} />

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:

<PropertiesTable content={[ { name: 'command', type: 'string', description: 'Command to execute', }, { name: 'args', type: 'string[]', description: 'Command arguments', isOptional: true, }, { name: 'options', type: 'Options', description: 'Configuration options.', isOptional: true, properties: [ { type: 'Options', parameters: [ { name: 'timeout', type: 'number', description: 'Execution timeout in milliseconds', isOptional: true, }, { name: 'cwd', type: 'string', description: 'Working directory for the command', isOptional: true, }, { name: 'env', type: 'Record<string, string>', description: 'Additional environment variables', isOptional: true, }, { name: 'onStdout', type: '(data: string) => void', description: 'Callback for stdout streaming', isOptional: true, }, { name: 'onStderr', type: '(data: string) => void', description: 'Callback for stderr streaming', isOptional: true, }, ], }, ], }, ]} />

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:

<PropertiesTable content={[ { name: 'opts.requestContext', type: 'RequestContext', description: 'Forwarded to the instructions function if one was provided in the constructor.', isOptional: true, }, ]} />

Returns: string