E2BSandbox

在隔離的 E2B 雲端 Sandbox 中執行指令。提供安全的暫時環境，並支援掛載雲端儲存空間。有關介面詳情，請參閱 WorkspaceSandbox 介面。

安裝

npm

npm install @mastra/e2b

pnpm

pnpm add @mastra/e2b

Yarn

yarn add @mastra/e2b

Bun

bun add @mastra/e2b

使用方法

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

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

= 300000（5 分鐘）

執行逾時時間（毫秒）

template?:

string | TemplateBuilder | function

Sandbox template 規格。可以是 template ID 字串、TemplateBuilder，或自訂預設 template 的函數。

env?:

Record<string, string>

要在 Sandbox 中設定的環境變數

id?:

string

= 自動產生

此 Sandbox instance 的唯一識別符

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。

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)，即可連接至現有程序：

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

如需完整 API，請參閱 SandboxProcessManager 參考。

掛載雲端儲存空間

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

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

使用 mounts 設定

掛載檔案系統最簡單的方法，是透過 Workspace 的 mounts 設定：

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 掛載
• GCS：透過 gcsfuse 掛載
• Azure Blob：透過 blobfuse2 掛載

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

自訂 template

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

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

使用現有 template

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

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

自訂預設 template

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

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 文件。

預先建置 template

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

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：

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

此步驟並非必要：如尚未安裝 gcsfuse，系統會在掛載時自動安裝。

配合 Code Mode 使用

Code Mode 讓 Agent 編寫單一 TypeScript 程式來協調其 Tool。由於 E2B 會在遠端 micro-VM 中執行該程式，因此需要透過 transport 將程式寫入 Sandbox 檔案系統，而非主機檔案系統。@mastra/e2b 為此提供 E2BCodeModeTransport。請將它作為第二個參數傳入 createCodeMode：

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 參考
• WorkspaceSandbox 介面
• LocalSandbox 參考
• S3Filesystem 參考
• GCSFilesystem 參考
• Azure Blob Filesystem 參考
• Workspace 概覽