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

# E2BSandbox

在隔離的 [E2B](https://e2b.dev) 雲端 Sandbox 中執行指令。提供安全的暫時性環境，並支援掛載雲端儲存空間。介面詳情請參閱 [WorkspaceSandbox 介面](https://mastra.zisheng.pro/zh-TW/reference/workspace/sandbox)。

## 安裝

**npm**:

```bash
npm install @mastra/e2b
```

**pnpm**:

```bash
pnpm add @mastra/e2b
```

**Yarn**:

```bash
yarn add @mastra/e2b
```

**Bun**:

```bash
bun add @mastra/e2b
```

## 使用方式

將 `E2BSandbox` 加入 Workspace，並指派給 Agent：

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { E2BSandbox } from '@mastra/e2b'

const workspace = new Workspace({
  sandbox: new E2BSandbox({
    id: 'dev-sandbox',
    timeout: 60_000, // 60 second timeout (default: 5 minutes)
  }),
})

const agent = new Agent({
  id: 'dev-agent',
  name: 'dev-agent',
  model: 'anthropic/claude-opus-4-7',
  workspace,
})
```

## 建構函式參數

**apiKey** (`string`): E2B API 金鑰。若未提供，則使用 E2B\_API\_KEY 環境變數。

**timeout** (`number`): 執行逾時時間，單位為毫秒 (Default: `300000 (5 minutes)`)

**template** (`string | TemplateBuilder | function`): Sandbox 範本規格。可以是範本 ID 字串、TemplateBuilder，或自訂預設範本的函式。

**env** (`Record<string, string>`): 要在 Sandbox 中設定的環境變數

**id** (`string`): 此 Sandbox 執行個體的唯一識別碼 (Default: `Auto-generated`)

**domain** (`string`): 自行託管 E2B 的網域。若未提供，則使用 E2B\_DOMAIN 環境變數。

**apiUrl** (`string`): 自行託管 E2B 的 API URL。若未提供，則使用 E2B\_API\_URL 環境變數。

**accessToken** (`string`): 用於驗證的存取 Token。若未提供，則使用 E2B\_ACCESS\_TOKEN 環境變數。

**metadata** (`Record<string, unknown>`): 附加至 Sandbox 執行個體的自訂中繼資料。

**instructions** (`string | ((opts: { defaultInstructions: string; requestContext?: RequestContext }) => string)`): getInstructions() 傳回的自訂指示。字串會完全取代預設值；函式會接收預設值，並可針對每個請求擴充或自訂。傳入空字串可完全隱藏指示。

## 屬性

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

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

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

**status** (`ProviderStatus`): 'pending' | 'initializing' | 'ready' | 'starting' | 'running' | 'stopping' | 'stopped' | 'destroying' | 'destroyed' | 'error'

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

## 背景處理程序

`E2BSandbox` 內建處理程序管理器，可產生及管理背景處理程序。處理程序在 E2B 雲端 Sandbox 中執行，並使用 E2B SDK 的 `commands.run()` 搭配 `background: true`。

```typescript
const sandbox = new E2BSandbox({ id: 'dev-sandbox' })
await sandbox.start()

// Spawn a background process
const handle = await sandbox.processes.spawn('node server.js', {
  env: { PORT: '3000' },
  onStdout: data => console.log(data),
})

// Interact with the process
console.log(handle.stdout)
await handle.sendStdin('input\n')
await handle.kill()
```

E2B 處理程序管理器支援重新連線至外部產生或在重新連線前產生的處理程序。使用 PID 呼叫 `get(pid)`，即可連線至現有處理程序：

```typescript
const handle = await sandbox.processes.get(existingPid)
if (handle) {
  console.log(handle.stdout)
}
```

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

## 掛載雲端儲存空間

E2B Sandbox 可以掛載 S3、GCS 與 Azure Blob 檔案系統，讓雲端儲存空間可作為 Sandbox 內的本機目錄存取。這適用於：

- 處理儲存在雲端 Bucket 中的大型資料集
- 將輸出檔案直接寫入雲端儲存空間
- 在 Sandbox 工作階段之間分享資料

### 使用 mounts 設定

掛載檔案系統最簡單的方式，是使用 Workspace 的 `mounts` 設定：

```typescript
import { Workspace } from '@mastra/core/workspace'
import { S3Filesystem } from '@mastra/s3'
import { GCSFilesystem } from '@mastra/gcs'
import { E2BSandbox } from '@mastra/e2b'

const workspace = new Workspace({
  mounts: {
    '/s3-data': new S3Filesystem({
      bucket: 'my-s3-bucket',
      region: 'us-east-1',
      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    }),
    '/gcs-data': new GCSFilesystem({
      bucket: 'my-gcs-bucket',
      projectId: 'my-project',
      credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY),
    }),
  },
  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
})
```

Sandbox 啟動時，檔案系統會自動掛載到指定路徑。在 Sandbox 中執行的程式碼可以像存取本機目錄一樣，存取 `/s3-data` 與 `/gcs-data` 中的檔案。

### 掛載的運作方式

E2B Sandbox 使用 FUSE（Filesystem in Userspace）掛載雲端儲存空間：

- **S3/R2**：透過 [s3fs-fuse](https://github.com/s3fs-fuse/s3fs-fuse) 掛載
- **GCS**：透過 [gcsfuse](https://github.com/GoogleCloudPlatform/gcsfuse) 掛載
- **Azure Blob**：透過 [blobfuse2](https://github.com/Azure/azure-storage-fuse) 掛載

使用掛載功能時，E2B Sandbox 會自動安裝所需的 FUSE 工具。為獲得最佳效能，請預先建置已安裝這些工具的自訂範本。

## 自訂範本

預設情況下，未指定範本時，E2BSandbox 會自動建置已安裝 `s3fs` 的範本，以支援 S3 掛載。此範本會快取並在不同 Sandbox 執行個體之間重複使用。

掛載 GCS 時，如果尚未安裝 `gcsfuse`，系統會在掛載時自動安裝。如需其他工具或更快的冷啟動速度，請使用自訂範本。

### 使用現有範本

如果已有預先建置的範本，請傳入其 ID：

```typescript
const workspace = new Workspace({
  sandbox: new E2BSandbox({
    id: 'dev-sandbox',
    template: 'my-custom-template',
  }),
})
```

### 自訂預設範本

傳入函式以自訂預設可掛載範本。此函式會接收 `TemplateBuilder`，且應傳回修改後的範本：

```typescript
const workspace = new Workspace({
  sandbox: new E2BSandbox({
    template: base =>
      base
        .aptInstall(['ffmpeg', 'imagemagick', 'poppler-utils'])
        .pipInstall(['pandas', 'numpy'])
        .npmInstall(['sharp']),
  }),
})
```

範本建構器支援鏈式呼叫下列操作：

- `aptInstall(packages)` - 安裝系統套件
- `pipInstall(packages)` - 安裝 Python 套件
- `npmInstall(packages)` - 安裝 Node.js 套件
- `runCmd(command)` - 執行 shell 指令
- `setEnvs(vars)` - 設定環境變數
- `copy(src, dest)` - 將檔案複製到範本中

可用方法的完整清單請參閱 [E2B 範本文件](https://e2b.dev/docs/template/defining-template)。

### 預先建置範本

預設範本會在首次使用時建置並快取。若要加快冷啟動速度或納入 GCS 支援，可以預先建置範本：

```typescript
import { createDefaultMountableTemplate } from '@mastra/e2b'
import { Template } from 'e2b'

// Get the default mountable template (includes s3fs)
const { template, id } = createDefaultMountableTemplate()

// Build and save to E2B
const result = await Template.build(template, id)
console.log('Template ID:', result.templateId)

// Use this ID in your E2BSandbox config for instant startup
const sandbox = new E2BSandbox({
  template: result.templateId,
})
```

若要加快 GCS 冷啟動速度，請在自訂範本中預先安裝 `gcsfuse`：

```typescript
const workspace = new Workspace({
  sandbox: new E2BSandbox({
    id: 'dev-sandbox',
    template: base => base.aptInstall(['gcsfuse']),
  }),
})
```

這是選用操作：如果尚未安裝 `gcsfuse`，系統會在掛載時自動安裝。

## 搭配 Code Mode 使用

[Code Mode](https://mastra.zisheng.pro/zh-TW/docs/agents/code-mode) 讓 Agent 編寫單一 TypeScript 程式來協調其 Tool。由於 E2B 在遠端微型 VM 中執行該程式，因此需要一個將程式寫入 Sandbox 檔案系統而非主機的 Transport。`@mastra/e2b` 為此提供 `E2BCodeModeTransport`。請將它作為第二個引數傳入 `createCodeMode`：

```typescript
import { createCodeMode } from '@mastra/core/tools'
import { E2BSandbox, E2BCodeModeTransport } from '@mastra/e2b'

const { tool, instructions } = createCodeMode(
  {
    tools: { getWeather, getForecast },
    sandbox: new E2BSandbox({ timeout: 60_000 }),
  },
  new E2BCodeModeTransport(),
)
```

如果 Sandbox 尚未執行，`E2BCodeModeTransport` 會自動啟動它；接著在主機上使用 esbuild 移除 TypeScript 語法（因此不受 Sandbox Node 版本影響）、在 VM 內執行 `node`，並在完成後清理程式檔案。`@mastra/core` 的預設 `StdioCodeModeTransport` 只適用於與主機共用檔案系統的 Sandbox，例如 `LocalSandbox`。

## 相關內容

- [SandboxProcessManager 參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/process-manager)
- [WorkspaceSandbox 介面](https://mastra.zisheng.pro/zh-TW/reference/workspace/sandbox)
- [LocalSandbox 參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/local-sandbox)
- [S3Filesystem 參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/s3-filesystem)
- [GCSFilesystem 參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/gcs-filesystem)
- [Azure Blob Filesystem 參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/azure-blob-filesystem)
- [Workspace 概觀](https://mastra.zisheng.pro/zh-TW/docs/workspace/overview)