WorkspaceSandbox
Added in: @mastra/core@1.1.0
The WorkspaceSandbox interface defines how workspaces execute commands and manage background processes.
PropertiesDirect link to Properties
processes?:
SandboxProcessManager
Background process manager. If not implemented, process management tools won't be available. See SandboxProcessManager reference.
MethodsDirect link to Methods
start()Direct link to start
Start the sandbox. Called automatically by workspace.init() or on first executeCommand() call.
await sandbox.start()
This method prepares the sandbox for command execution.
stop()Direct link to stop
Stop the sandbox.
await sandbox.stop?.()
destroy()Direct link to destroy
Clean up sandbox resources. Called by workspace.destroy().
await sandbox.destroy()
executeCommand(command, args?, options?)Direct link to executecommandcommand-args-options
Execute a shell command.
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
cwd?:
string
Working directory for the command
env?:
Record<string, string>
Additional environment variables
onStdout?:
(data: string) => void
Callback for stdout streaming
onStderr?:
(data: string) => void
Callback for stderr streaming
getInfo()Direct link to getinfo
Get sandbox status and resource information.
const info = await sandbox.getInfo()
// { status: 'running', resources: { memoryMB: 512, cpuPercent: 5 } }
getInstructions(opts?)Direct link to getinstructionsopts
Returns a description of how this sandbox works. Injected into the agent's system message when the workspace is assigned to an agent.
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