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

# E2BSandbox

在隔離的 [E2B](https://e2b.dev) 雲端 Sandbox 中執行指令。提供安全的暫時環境，並支援掛載雲端儲存空間。有關介面詳情，請參閱 [WorkspaceSandbox 介面](https://mastra.zisheng.pro/zh-HK/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 key。如未提供，則使用 E2B\_API\_KEY 環境變數。

**timeout** (`number`): 執行逾時時間（毫秒） (Default: `300000（5 分鐘）`)

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

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

**id** (`string`): 此 Sandbox instance 的唯一識別符 (Default: `自動產生`)

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

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

**accessToken** (`string`): 用於驗證的 access token。如未提供，則使用 E2B\_ACCESS\_TOKEN 環境變數。

**metadata** (`Record<string, unknown>`): 附加至 Sandbox instance 的自訂 metadata。

**instructions** (`string | ((opts: { defaultInstructions: string; requestContext?: RequestContext }) => string)`): getInstructions() 傳回的自訂指示。字串會完全取代預設指示；函數會接收預設指示，並可按每個 request 加以擴充或自訂。傳入空字串可完全停用指示。

## 屬性

**id** (`string`): Sandbox instance 識別符

**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-HK/reference/workspace/process-manager)。

## 掛載雲端儲存空間

E2B Sandbox 可以掛載 S3、GCS 及 Azure Blob 檔案系統，讓 Sandbox 內的程式能以本機目錄的方式存取雲端儲存空間。適用情況包括：

- 處理儲存在雲端 bucket 的大型資料集
- 將輸出檔案直接寫入雲端儲存空間
- 在不同 Sandbox session 之間共用資料

### 使用 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 工具。為獲得最佳效能，請預先建置已安裝這些工具的自訂 template。

## 自訂 template

預設情況下，如未指定 template，E2BSandbox 會自動建置已安裝 `s3fs` 的 template，以支援掛載 S3。此 template 會快取並由不同 Sandbox instance 重複使用。

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

### 使用現有 template

如已有預先建置的 template，請傳入其 ID：

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

### 自訂預設 template

傳入函數以自訂預設的可掛載 template。函數會接收 `TemplateBuilder`，並應傳回修改後的 template：

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

Template builder 支援串連呼叫以下操作：

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

如需可用方法的完整列表，請參閱 [E2B template 文件](https://e2b.dev/docs/template/defining-template)。

### 預先建置 template

預設 template 會在首次使用時建置及快取。如需更快的冷啟動速度或加入 GCS 支援，你可以預先建置 template：

```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 冷啟動速度，請在自訂 template 中預先安裝 `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-HK/docs/agents/code-mode) 讓 Agent 編寫單一 TypeScript 程式來協調其 Tool。由於 E2B 會在遠端 micro-VM 中執行該程式，因此需要透過 transport 將程式寫入 Sandbox 檔案系統，而非主機檔案系統。`@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` 會自動啟動 Sandbox；它會在主機上使用 esbuild 移除 TypeScript 語法（因此不受 Sandbox Node 版本影響），在 VM 內執行 `node`，並於完成後清理程式檔案。`@mastra/core` 的預設 `StdioCodeModeTransport` 只適用於與主機共用檔案系統的 Sandbox，例如 `LocalSandbox`。

## 相關內容

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