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

# LocalSandbox

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

在本機系統上執行指令。如需介面詳情，請參閱 [WorkspaceSandbox 介面](https://mastra.zisheng.pro/zh-HK/reference/workspace/sandbox)。

## 使用方式

將 `LocalSandbox` 加入 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',
    env: {
      NODE_ENV: 'development',
    },
  }),
})

const agent = new Agent({
  id: 'dev-agent',
  model: 'openai/gpt-5.6-sol',
  workspace,
})

// The agent now has the execute_command tool available
const response = await agent.generate('Run npm install')
```

### 自動啟動行為

如 `LocalSandbox` 尚未運行，首次執行指令時便會自動啟動。你亦可在應用程式啟動時呼叫 `workspace.init()`，明確啟動 Sandbox，以免首次執行指令時出現延遲。

## 建構函數參數

**id** (`string`): 此 Sandbox 執行個體的唯一識別碼 (Default: `自動產生`)

**workingDirectory** (`string`): 執行指令的目錄。預設為 process.cwd() 中的 .sandbox/，以便與 seatbelt 設定檔隔離。 (Default: `process.cwd()/.sandbox/`)

**env** (`NodeJS.ProcessEnv`): 要設定的環境變數。除非遭覆寫，否則預設會包括 PATH。

**timeout** (`number`): 操作的預設逾時時間（以毫秒為單位） (Default: `30000`)

**isolation** (`'none' | 'seatbelt' | 'bwrap'`): 原生作業系統 Sandbox 後端。macOS 使用 'seatbelt'，Linux 使用 'bwrap'。 (Default: `'none'`)

**instructions** (`string | ((opts: { defaultInstructions: string; requestContext?: RequestContext }) => string)`): 覆寫 getInstructions() 傳回之預設指示的自訂指示。傳入字串以完全取代指示，或傳入函數以擴充指示，並可存取目前的 requestContext，按個別請求自訂。

**nativeSandbox** (`NativeSandboxConfig`): 原生 Sandbox 的設定（請參閱下方的 NativeSandboxConfig）。

## `NativeSandboxConfig`

原生作業系統 Sandbox 的設定選項（與 `isolation: 'seatbelt'` 或 `'bwrap'` 配合使用）。

**allowNetwork** (`boolean`): 允許 Sandbox 內的指令存取網絡。 (Default: `false`)

**readOnlyPaths** (`string[]`): 允許唯讀存取的其他路徑（系統路徑一律可供讀取）。

**readWritePaths** (`string[]`): Workspace 目錄以外允許讀寫存取的其他路徑。

**seatbeltProfilePath** (`string`): 自訂 seatbelt 設定檔的路徑（只適用於 macOS）。如果檔案由你編寫，系統會原樣使用：Mastra 不會將已掛載路徑加入其中，因此設定檔必須已經允許你掛載的每個路徑。如果檔案不存在，系統會產生預設設定檔並寫入此路徑，而該設定檔會允許已掛載路徑。Mastra 會標記其產生的設定檔，因此日後運行時會重新產生檔案，而不會視為由你編寫並讀回。如要編輯已產生的設定檔並保留修改，請刪除其標記註解：檔案隨後便會視為由你編寫，系統亦不會再加入已掛載路徑。

**bwrapArgs** (`string[]`): 傳遞至 bwrap 的其他引數（只適用於 Linux）。

**allowSystemBinaries** (`boolean`): 允許讀取標準系統二進制檔案路徑（/bin、/usr/bin 等）。 (Default: `true`)

## 屬性

**id** (`string`): Sandbox 執行個體識別碼

**name** (`string`): Provider 名稱（'LocalSandbox'）

**provider** (`string`): Provider 識別碼（'local'）

**status** (`ProviderStatus`): 'starting' | 'running' | 'stopped' | 'error'

**workingDirectory** (`string`): 已設定的工作目錄

**processes** (`LocalProcessManager`): 背景程序管理器。請參閱 SandboxProcessManager 參考。

## 路徑解析

### 相對路徑及執行內容

為 `workingDirectory` 使用相對路徑時，系統會從 `process.cwd()` 解析。在 Mastra 項目中，目前工作目錄會因程式碼的運行方式而異：

| 內容             | 工作目錄                   | `./workspace` 解析為               |
| -------------- | ---------------------- | ------------------------------- |
| `mastra dev`   | `./src/mastra/public/` | `./src/mastra/public/workspace` |
| `mastra start` | `./.mastra/output/`    | `./.mastra/output/workspace`    |
| 直接執行指令碼        | 你運行指令的位置               | 相對於該位置                          |

同一個相對路徑可能會解析至不同位置，因而造成混淆。

### 建議：使用絕對路徑

如要在所有執行內容中使用一致的路徑，請配合絕對路徑使用環境變數：

```typescript
import { LocalSandbox } from '@mastra/core/workspace'

const sandbox = new LocalSandbox({
  workingDirectory: process.env.WORKSPACE_PATH!,
})
```

將環境中的 `WORKSPACE_PATH` 設定為絕對路徑，例如 `/home/user/my-project/workspace`。無論你如何運行程式碼，這都可確保指令從一致的目錄執行。

## 背景程序

`LocalSandbox` 包含內置程序管理器，可用來產生及管理背景程序。程序會使用 `child_process.spawn`，以子程序形式在本機上運行。

```typescript
const sandbox = new LocalSandbox({ workingDirectory: './workspace' })
await sandbox.start()

// Spawn a background process
const handle = await sandbox.processes.spawn('node server.js')

// Read output, send stdin, kill
console.log(handle.stdout)
await handle.sendStdin('input\n')
await handle.kill()
```

啟用原生隔離（`seatbelt` 或 `bwrap`）時，產生的程序亦會以相同的隔離後端包裝。

如需完整 API，請參閱 [`SandboxProcessManager` 參考](https://mastra.zisheng.pro/zh-HK/reference/workspace/process-manager)。

## 靜態方法

### `detectIsolation()`

偵測目前平台上最合適的可用隔離後端。

```typescript
const detection = LocalSandbox.detectIsolation()
// { backend: 'seatbelt', available: true, message: 'Seatbelt available on macOS' }
```

## 環境隔離

預設情況下，`LocalSandbox` 的環境只包括 `PATH`。指令可以正常運行，同時避免意外洩露 API 金鑰及機密資料。

```typescript
// Default: only PATH is available (commands work, secrets protected)
const secureSandbox = new LocalSandbox({
  workingDirectory: './workspace',
})

// Explicit: pass specific variables
const sandbox = new LocalSandbox({
  workingDirectory: './workspace',
  env: {
    NODE_ENV: 'development',
    API_URL: 'https://api.example.com',
  },
})

// Full access (use with caution)
const devSandbox = new LocalSandbox({
  workingDirectory: './workspace',
  env: process.env,
})
```

## 原生作業系統 Sandbox

`LocalSandbox` 支援原生作業系統層級的 Sandbox，以提供額外保安：

- **macOS**：使用 Seatbelt（`sandbox-exec`）隔離檔案系統及網絡
- **Linux**：使用 Bubblewrap（`bwrap`）隔離命名空間

```typescript
// Detect the best available backend for this platform
const detection = LocalSandbox.detectIsolation()
console.log(detection)
// { backend: 'seatbelt', available: true, message: '...' }

// Enable native sandboxing
const sandbox = new LocalSandbox({
  workingDirectory: './workspace',
  isolation: 'seatbelt', // or 'bwrap' on Linux
  nativeSandbox: {
    allowNetwork: false, // Block network access (default)
    readWritePaths: ['/tmp/extra'], // Additional writable paths
  },
})
```

啟用隔離時：

- 檔案寫入只限 Workspace 目錄（及已設定的路徑）
- 所有位置均可讀取檔案（系統二進制檔案需要此權限）
- 預設封鎖網絡存取
- 程序隔離可防止影響主機系統

### Sandbox 設定檔位置

在 macOS 上使用 seatbelt 隔離時，`LocalSandbox` 會在 `process.cwd()` 內的 `.sandbox-profiles/` 資料夾產生設定檔，並與工作目錄分開：

```text
project/
├── .sandbox/                      # Default working directory (sandboxed)
│   └── ... files created by sandbox
├── .sandbox-profiles/             # Seatbelt profiles (outside sandbox)
│   └── seatbelt-a1b2c3d4.sb       # Hash based on workspace + config
└── ... your project files
```

設定檔名稱是 Workspace 路徑及設定的雜湊值，因此設定相同的 Sandbox 會共用同一份設定檔，而不同設定則會使用不同檔案。這可防止同時運行多個 Sandbox 時發生衝突。

這種分隔方式可防止 Sandbox 內的程序讀取或修改本身的保安設定檔。設定檔會在 Sandbox 啟動時建立，並在銷毀時清除。

## 相關內容

- [SandboxProcessManager 參考](https://mastra.zisheng.pro/zh-HK/reference/workspace/process-manager)
- [WorkspaceSandbox 介面](https://mastra.zisheng.pro/zh-HK/reference/workspace/sandbox)
- [Workspace 類別](https://mastra.zisheng.pro/zh-HK/reference/workspace/workspace-class)
- [Workspace 概覽](https://mastra.zisheng.pro/zh-HK/docs/workspace/overview)