KakaFlow KB

Sandbox - Shell Command Execution for Agents

6 phút đọc

Sandbox - Shell Command Execution for Agents

Trust: ★★★☆☆ (0.90) · 0 validations · developer_reference

Published: 2026-05-10 · Source: crawler_authoritative

Tình huống

Mastra workspace configuration guide for enabling agents to execute shell commands using sandbox providers, covering supported providers and agent tool availability.

Insight

Sandbox providers enable agents to execute shell commands within a workspace. Available since @mastra/[email protected], sandboxes provide command execution with arguments, background process spawning, working directory control, environment variable management, timeout configuration, and optional OS-level isolation. Five sandbox providers are supported: LocalSandbox executes commands on the local machine, while BlaxelSandbox, DaytonaSandbox, E2BSandbox, and ModalSandbox execute commands in isolated cloud sandbox environments. When a sandbox is configured on a workspace, agents automatically receive the execute_command tool for running shell commands, which returns stdout, stderr, and exit code. Providers supporting background processes enable the background: true flag on execute_command to spawn long-running processes like dev servers and watchers, returning a PID. Additional tools include get_process_output for retrieving stdout/stderr/status by PID (supports tail to limit output lines and wait: true to block until exit), and kill_process for stopping background processes by PID. Lifecycle callbacks can be configured via backgroundProcesses option on the execute_command tool: onStdout, onStderr, and onExit callbacks receive data along with process metadata including pid. The abortSignal option controls process termination on agent disconnect: undefined uses the agent’s abort signal (default), AbortSignal uses a custom signal, and null or false disables abort so processes persist after agent shutdown. This is recommended for cloud sandboxes like E2B, Daytona, or Modal.

Hành động

To configure a sandbox, import Workspace, LocalFilesystem, and LocalSandbox from @mastra/core/workspace. Create a Workspace instance with filesystem and sandbox configuration specifying workingDirectory. Assign the workspace to an Agent during initialization. The agent automatically gains the execute_command tool. For code: import { Agent } from ‘@mastra/core/agent’ and import { Workspace, LocalFilesystem, LocalSandbox } from ‘@mastra/core/workspace’. Create workspace with new Workspace({ filesystem: new LocalFilesystem({ basePath: ‘./workspace’ }), sandbox: new LocalSandbox({ workingDirectory: ‘./workspace’ }) }). Pass workspace to agent: new Agent({ id: ‘dev-agent’, model: ‘openai/gpt-5.4’, instructions: ‘You are a helpful development assistant.’, workspace }). Configure background process callbacks by importing WORKSPACE_TOOLS from @mastra/core/workspace and setting backgroundProcesses with onStdout, onStderr, onExit callback functions. Control abort behavior with the abortSignal option: set to null for cloud sandbox processes to persist after agent disconnect.

Kết quả

Agents configured with a sandbox gain shell command execution capabilities via the execute_command tool. Commands run in the configured working directory with specified environment variables. Background processes return a PID for output retrieval and process management. Lifecycle callbacks fire for stdout, stderr, and process exit events. Processes inherit the agent’s abort signal by default but can be configured to persist independently.

Điều kiện áp dụng

Requires @mastra/[email protected] or later. Abort signal behavior (null/false for persistent processes) recommended specifically for cloud sandboxes: E2B, Daytona, and Modal.

Nội dung gốc (Original)

Sandbox

Added in: @mastra/[email protected]

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.

A sandbox provider executes commands in a controlled environment:

  • Command execution: Run shell commands with arguments
  • Background processes: Spawn long-running processes like dev servers and watchers
  • 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

Supported providers

  • LocalSandbox: Executes commands on the local machine
  • BlaxelSandbox: Executes commands in isolated Blaxel cloud sandboxes
  • DaytonaSandbox: Executes commands in isolated Daytona cloud sandboxes
  • E2BSandbox: Executes commands in isolated E2B cloud sandboxes
  • ModalSandbox: Executes commands in isolated Modal cloud sandboxes

Basic usage

Create a workspace with a sandbox and assign it to an agent. The agent can then execute shell commands:

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-5.4',
  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 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.

If your sandbox provider supports running processes in the background, the execute_command tool also accepts background: true for starting long-running processes, and two additional tools are registered:

ToolDescription
execute_commandRun a shell command. Returns stdout, stderr, and exit code. Supports background: true to spawn a long-running process and return a PID.
get_process_outputGet stdout, stderr, and status of a background process by PID. Supports tail to limit output lines and wait: true to block until exit.
kill_processStop a background process by PID. Returns recent output.

These tools are registered automatically. See Workspace class reference for the full tool name list.

Background process callbacks

When agents start background processes through the execute_command tool, you can receive lifecycle callbacks for stdout, stderr, and process exit. Configure these through the backgroundProcesses option on the execute_command tool:

import { Workspace, LocalSandbox, WORKSPACE_TOOLS } from '@mastra/core/workspace'
 
const workspace = new Workspace({
  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
  tools: {
    [WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND]: {
      backgroundProcesses: {
        onStdout: (data, { pid }) => console.log(`[${pid}] ${data}`),
        onStderr: (data, { pid }) => console.error(`[${pid}] ${data}`),
        onExit: ({ pid, exitCode }) => console.log(`Process ${pid} exited: ${exitCode}`),
      },
    },
  },
})

These callbacks fire for all background processes started by the agent through the execute_command tool.

Abort signal

By default, background processes inherit the agent’s abort signal and are killed when the agent disconnects. Control this behavior with the abortSignal option:

  • undefined (default): Uses the agent’s abort signal
  • AbortSignal: Uses a custom signal
  • null or false: Disables abort — processes persist after agent shutdown
import { Workspace, LocalSandbox, WORKSPACE_TOOLS } from '@mastra/core/workspace'
 
const workspace = new Workspace({
  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
  tools: {
    [WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND]: {
      backgroundProcesses: {
        abortSignal: null, // Processes survive agent disconnection
      },
    },
  },
})

Use null or false for cloud sandboxes (for example, E2B, Daytona, or Modal) where processes should outlive the agent.

Note: For the full SandboxProcessManager API (spawning processes programmatically, reading output, sending stdin), see the SandboxProcessManager reference.

Liên kết

Xem thêm:

Sơ đồ

Liên kết ngược