Sandbox

新增於： @mastra/core@1.1.0

Sandbox Provider 讓 Agent 能執行 Shell 命令。在 Workspace 上設定 Sandbox 後，Agent 可以在任務中執行命令。

Sandbox Provider 會在受控環境中執行命令：

• 命令執行：執行含引數的 Shell 命令
• 背景處理程序：啟動開發伺服器與 Watcher 等長時間執行的處理程序
• 工作目錄：從特定目錄執行命令
• 環境變數：控制可用的變數
• 逾時：避免長時間執行的命令卡住
• 隔離：選用的作業系統層級 Sandbox，可提升安全性

📹 觀看影片

觀看 Mastra 遠端 Sandbox 概觀，瞭解遠端 Sandbox 如何為 Agent 提供隔離的電腦環境。

支援的 Provider

• LocalSandbox：在本機執行命令
• AgentCoreRuntimeSandbox：在 AWS Bedrock AgentCore Runtime 工作階段中執行命令
• AppleContainerSandbox：使用 Apple 的 container CLI，在本機 OCI Linux Container 中執行命令
• BlaxelSandbox：在隔離的 Blaxel 雲端 Sandbox 中執行命令
• DaytonaSandbox：在隔離的 Daytona 雲端 Sandbox 中執行命令
• DockerSandbox：在本機長時間運作的 Docker Container 中執行命令
• E2BSandbox：在隔離的 E2B 雲端 Sandbox 中執行命令
• ModalSandbox：在隔離的 Modal 雲端 Sandbox 中執行命令
• PlatformSandbox：在連結至 Mastra Platform 環境的 Sandbox 中執行命令
• RailwaySandbox：在暫時且隔離的 Railway 雲端 Sandbox 中執行命令
• VercelSandbox：在暫時的 Vercel Sandbox Firecracker MicroVM 中執行命令
• VercelServerlessSandbox：以無狀態 Vercel Serverless Function 執行命令

基本用法

建立含 Sandbox 的 Workspace，並將它指派給 Agent。Agent 隨後便能執行 Shell 命令：

src/mastra/agents/dev-agent.ts

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.6-sol',
  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')

環境隔離與原生作業系統 Sandbox 等設定選項，請參閱 LocalSandbox 參考。

動態 Sandbox

sandbox 選項除了靜態執行個體，也接受解析器函式。解析器會接收 requestContext，並為每個請求傳回 Sandbox，讓單一 Workspace 能依呼叫端的身分、角色或租戶使用不同 Sandbox。

src/mastra/workspaces.ts

import { Agent } from '@mastra/core/agent'
import { Workspace, LocalSandbox } from '@mastra/core/workspace'

const workspace = new Workspace({
  sandbox: ({ requestContext }) => {
    const userId = requestContext.get('user-id') as string
    return new LocalSandbox({
      workingDirectory: `/workspaces/${userId}`,
    })
  },
})

const agent = new Agent({
  id: 'multi-tenant-agent',
  model: 'your-provider/your-model',
  workspace,
})

每個請求都會在 Tool 執行時解析自己的 Sandbox：

import { RequestContext } from '@mastra/core/request-context'

// User Alice — commands run in /workspaces/alice
const aliceCtx = new RequestContext([['user-id', 'alice']])
await agent.generate('List files in cwd', { requestContext: aliceCtx })

// User Bob — commands run in /workspaces/bob
const bobCtx = new RequestContext([['user-id', 'bob']])
await agent.generate('List files in cwd', { requestContext: bobCtx })

Workspace 指示預設會以穩定的預留位置文字描述執行階段 Sandbox。若要加入每個請求的具體細節，請參閱 Workspace 指示。

解析器也可以是非同步函式，例如從資料庫查詢租戶設定：

const workspace = new Workspace({
  sandbox: async ({ requestContext }) => {
    const tenant = await db.getTenant(requestContext.get('tenant-id'))
    return new LocalSandbox({ workingDirectory: tenant.workspacePath })
  },
})

生命週期擁有權

Sandbox 是靜態執行個體時，workspace.init() 會呼叫其 start() 方法，而 workspace.destroy() 會呼叫其 destroy() 方法。使用解析器時，Workspace 在建構時沒有可管理的執行個體，因此傳回 Sandbox 的生命週期由呼叫端負責。

解析器必須傳回已可使用的 Sandbox：它應已啟動，或能在未明確啟動的情況下處理呼叫。呼叫端也負責決定何時清理傳回的 Sandbox。

清理作業可以針對每個請求、租戶或使用者進行，也可以是長期 Sandbox Pool 的一部分。workspace.destroy() 不會銷毀解析器傳回的 Sandbox。

備註

sandbox 解析器與 mounts 及 lsp: true 不相容。兩者都需要在建構時取得具體 Sandbox 執行個體；與解析器併用時，mounts 會擲回 INVALID_CONFIG 錯誤，而 lsp: true 會顯示警告並停用 LSP。

Tool 註冊

使用靜態 Sandbox 時，Workspace 會檢查執行個體以決定註冊哪些 Tool。使用解析器時，Workspace 會假設它具備完整功能，並註冊 execute_command（支援 background）、get_process_output 與 kill_process。若解析出的 Sandbox 未實作某項功能，執行階段會擲回明確的 SandboxFeatureNotSupportedError。

背景處理程序持續性

背景處理程序的存活時間可能超過單次 Tool 呼叫，因此 get_process_output 與 kill_process 必須連到啟動該處理程序的同一個 Sandbox。解析出的 Sandbox 預設會依請求快取。若要跨後續請求（例如稍後的對話回合）維持連續性，請將 sandboxCacheKey 設為穩定識別碼。解析出的 Sandbox 隨後會依該鍵快取，而不是依請求快取：

const workspace = new Workspace({
  sandbox: ({ requestContext }) => resolveSandbox(requestContext),
  sandboxCacheKey: ({ requestContext }) => requestContext.get('thread-id') as string,
})

若未設定 sandboxCacheKey，對於共用租戶、使用者或工作階段的後續呼叫，解析器本身必須傳回相同 Sandbox。

不再需要快取的 Sandbox 時，請在自己的生命週期程式碼中銷毀它，並呼叫 workspace.clearSandboxCache(cacheKey) 移除 Workspace 快取項目。呼叫 workspace.clearSandboxCache() 可清除所有具鍵值的 Sandbox 項目。

Workspace 指示

Workspace 指示會在 Agent 的系統訊息中描述環境。使用 Sandbox 解析器時，Workspace 不會為了建立這些指示而呼叫解析器，而是輸出穩定的預留位置文字。如此一來，建構 Prompt 時不會佈建由呼叫端擁有的 Sandbox，且系統訊息在不同請求間保持一致，有助於 Prompt 快取。

若要加入每個請求的具體 Sandbox 詳細資料，請將 instructions.dynamicSandbox 設為 'resolve'：

const workspace = new Workspace({
  sandbox: ({ requestContext }) => resolveSandbox(requestContext),
  instructions: { dynamicSandbox: 'resolve' },
})

'resolve' 會在每個請求中呼叫解析器，這可能佈建 Sandbox，並使系統訊息隨請求而異。也可以傳入函式，直接依 requestContext 傳回自訂文字，而不解析 Sandbox：

const workspace = new Workspace({
  sandbox: ({ requestContext }) => resolveSandbox(requestContext),
  instructions: {
    dynamicSandbox: ({ requestContext }) =>
      `Sandbox scoped to tenant ${requestContext.get('tenant-id')}.`,
  },
})

Agent Tool

在 Workspace 上設定 Sandbox 後，Agent 會取得用於執行 Shell 命令的 execute_command Tool。

若 Sandbox Provider 支援在背景執行處理程序，execute_command Tool 也接受 background: true 以啟動長時間執行的處理程序，並會註冊另外兩個 Tool：

Tool	說明
execute_command	執行 Shell 命令。傳回 stdout、stderr 與結束碼。支援以 background: true 啟動長時間執行的處理程序並傳回 PID。
get_process_output	依 PID 取得背景處理程序的 stdout、stderr 與狀態。支援以 tail 限制輸出行數，以及以 wait: true 阻塞至結束。
kill_process	依 PID 停止背景處理程序，並傳回近期輸出。

這些 Tool 會自動註冊。完整 Tool 名稱清單請參閱 Workspace 類別參考。

背景處理程序 Callback

Agent 透過 execute_command Tool 啟動背景處理程序時，你可以接收 stdout、stderr 及處理程序結束的生命週期 Callback。請在 execute_command Tool 的 backgroundProcesses 選項中設定：

src/mastra/workspaces.ts

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}`),
      },
    },
  },
})

Agent 透過 execute_command Tool 啟動的所有背景處理程序都會觸發這些 Callback。

Abort signal

背景處理程序預設會繼承 Agent 的 AbortSignal，並在 Agent 中斷連線時終止。使用 abortSignal 選項控制此行為：

• undefined（預設）：使用 Agent 的 AbortSignal
• AbortSignal：使用自訂 Signal
• null 或 false：停用 Abort；Agent 關閉後處理程序仍會持續執行

src/mastra/workspaces.ts

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
      },
    },
  },
})

對於處理程序應比 Agent 存活更久的雲端 Sandbox（例如 E2B、Daytona 或 Modal），請使用 null 或 false。

備註

完整的 SandboxProcessManager API（以程式方式產生處理程序及讀取輸出，以及傳送 stdin）請參閱 SandboxProcessManager 參考。

相關資源

• SandboxProcessManager 參考
• AgentCoreRuntimeSandbox 參考
• AppleContainerSandbox 參考
• DaytonaSandbox 參考
• E2BSandbox 參考
• LocalSandbox 參考
• ModalSandbox 參考
• VercelSandbox 參考
• VercelServerlessSandbox 參考
• Workspace 概觀
• 檔案系統