跳至主要內容

E2BSandbox

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

安裝
「安裝」的直接連結

npm install @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 金鑰。若未提供，則使用 E2B_API_KEY 環境變數。

timeout?:

number
= 300000 (5 minutes)
執行逾時時間，單位為毫秒

template?:

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

env?:

Record<string, string>
要在 Sandbox 中設定的環境變數

id?:

string
= Auto-generated
此 Sandbox 執行個體的唯一識別碼

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。

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 工作階段之間分享資料

使用 mounts 設定
「使用 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）掛載雲端儲存空間：

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

自訂範本
「自訂範本」的直接連結

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

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

使用現有範本
「使用現有範本」的直接連結

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

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

自訂預設範本
「自訂預設範本」的直接連結

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

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

預先建置範本
「預先建置範本」的直接連結

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

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：

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

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

搭配 Code Mode 使用
「搭配 Code Mode 使用」的直接連結

Code Mode 讓 Agent 編寫單一 TypeScript 程式來協調其 Tool。由於 E2B 在遠端微型 VM 中執行該程式，因此需要一個將程式寫入 Sandbox 檔案系統而非主機的 Transport。@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 會自動啟動它；接著在主機上使用 esbuild 移除 TypeScript 語法（因此不受 Sandbox Node 版本影響）、在 VM 內執行 node，並在完成後清理程式檔案。@mastra/core 的預設 StdioCodeModeTransport 只適用於與主機共用檔案系統的 Sandbox，例如 LocalSandbox。

On this page