> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/llms.txt

# Sandbox

**新增於：** `@mastra/core@1.1.0`

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

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

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

> **📹 觀看影片:** 觀看 [Mastra 遠端 Sandbox 概觀](https://www.youtube.com/watch?v=Ix2X-sjVXjw)，瞭解遠端 Sandbox 如何為 Agent 提供隔離的電腦環境。

## 支援的 Provider

- [`LocalSandbox`](https://mastra.zisheng.pro/zh-TW/reference/workspace/local-sandbox)：在本機執行命令
- [`AgentCoreRuntimeSandbox`](https://mastra.zisheng.pro/zh-TW/reference/workspace/agentcore-runtime-sandbox)：在 AWS Bedrock AgentCore Runtime 工作階段中執行命令
- [`AppleContainerSandbox`](https://mastra.zisheng.pro/zh-TW/reference/workspace/apple-container-sandbox)：使用 Apple 的 `container` CLI，在本機 OCI Linux Container 中執行命令
- [`BlaxelSandbox`](https://mastra.zisheng.pro/zh-TW/reference/workspace/blaxel-sandbox)：在隔離的 Blaxel 雲端 Sandbox 中執行命令
- [`DaytonaSandbox`](https://mastra.zisheng.pro/zh-TW/reference/workspace/daytona-sandbox)：在隔離的 Daytona 雲端 Sandbox 中執行命令
- [`DockerSandbox`](https://mastra.zisheng.pro/zh-TW/reference/workspace/docker-sandbox)：在本機長時間運作的 Docker Container 中執行命令
- [`E2BSandbox`](https://mastra.zisheng.pro/zh-TW/reference/workspace/e2b-sandbox)：在隔離的 E2B 雲端 Sandbox 中執行命令
- [`ModalSandbox`](https://mastra.zisheng.pro/zh-TW/reference/workspace/modal-sandbox)：在隔離的 Modal 雲端 Sandbox 中執行命令
- [`PlatformSandbox`](https://mastra.zisheng.pro/zh-TW/reference/workspace/platform-sandbox)：在連結至 Mastra Platform 環境的 Sandbox 中執行命令
- [`RailwaySandbox`](https://mastra.zisheng.pro/zh-TW/reference/workspace/railway-sandbox)：在暫時且隔離的 Railway 雲端 Sandbox 中執行命令
- [`VercelSandbox`](https://mastra.zisheng.pro/zh-TW/reference/workspace/vercel-sandbox)：在暫時的 Vercel Sandbox Firecracker MicroVM 中執行命令
- [`VercelServerlessSandbox`](https://mastra.zisheng.pro/zh-TW/reference/workspace/vercel-serverless)：以無狀態 Vercel Serverless Function 執行命令

## 基本用法

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

```typescript
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` 參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/local-sandbox)。

## 動態 Sandbox

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

```typescript
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：

```typescript
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 指示](#workspace-instructions)。

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

```typescript
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 隨後會依該鍵快取，而不是依請求快取：

```typescript
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'`：

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

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

```typescript
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 類別參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/workspace-class)。

## 背景處理程序 Callback

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

```typescript
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 關閉後處理程序仍會持續執行

```typescript
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` 參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/process-manager)。

## 相關資源

- [`SandboxProcessManager` 參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/process-manager)
- [`AgentCoreRuntimeSandbox` 參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/agentcore-runtime-sandbox)
- [`AppleContainerSandbox` 參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/apple-container-sandbox)
- [`DaytonaSandbox` 參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/daytona-sandbox)
- [`E2BSandbox` 參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/e2b-sandbox)
- [`LocalSandbox` 參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/local-sandbox)
- [`ModalSandbox` 參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/modal-sandbox)
- [`VercelSandbox` 參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/vercel-sandbox)
- [`VercelServerlessSandbox` 參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/vercel-serverless)
- [Workspace 概觀](https://mastra.zisheng.pro/zh-TW/docs/workspace/overview)
- [檔案系統](https://mastra.zisheng.pro/zh-TW/docs/workspace/filesystem)