Mastra E2B Sandbox 集成指南：为 Workspace 与 Agent 搭建安全隔离的云端代码执行环境

Mastra E2B Sandbox 集成指南：为 Workspace 与 Agent 搭建安全隔离的云端代码执行环境

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra

@mastra/e2b是 Mastra 框架的 E2B 云沙箱 Provider，为 Workspace 提供安全、隔离的云端代码执行环境，并支持通过 FUSE 挂载 S3、GCS、Azure Blob 等云存储。读完本文，你将掌握如何安装配置E2BSandbox、理解其模板系统与沙箱生命周期、学会在 Agent 与 Workspace 中接入云端代码执行、挂载云存储，并掌握沙箱超时恢复、确定性重连与 Code Mode 等进阶能力。

什么是 E2B Sandbox Provider

E2B（E2B Cloud）提供托管在云端的、隔离的微虚拟机（micro-VM）执行环境。@mastra/e2b将该能力封装为符合 Mastra Workspace 接口的沙箱 Provider：应用代码运行在远端隔离 VM 中，不接触宿主文件系统，天然适合执行不可信代码、运行 Agent 生成的程序、批量跑数据分析等场景。

从源码结构看（workspaces/e2b/src），该包的核心由以下几部分组成：

• E2BSandbox：实现MastraSandbox接口的沙箱主类，负责沙箱的创建、连接、暂停、销毁、文件上传、云存储挂载与网络暴露；
• 模板工具 与 仓库模板：负责 E2B 模板的构建、缓存与按需重建；
• 进程管理器：封装 E2B 的后台命令 API，向 Workspace 暴露统一的进程句柄；
• Code Mode 传输层：让 Code Mode 工具在远程沙箱内运行；
• Provider 描述符：供MastraEditor等宿主识别与创建 E2B 沙箱。

安装

在项目中安装@mastra/e2b以及它依赖的核心包：

npm install @mastra/e2b

根据 package.json，该包以@mastra/core（>=1.67.0-0 <2.0.0-0）为 peer 依赖，底层使用官方e2bSDK（^2.36.0）与esbuild，要求 Node.js>=22.13.0，构建产物同时支持 ESM（dist/index.js）与 CommonJS（dist/index.cjs）引入方式。

快速开始

将E2BSandbox注入Workspace，再把 Workspace 挂到Agent上，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({ apiKey: 'my-api-key', // falls back to E2B_API_KEY env var timeout: 60_000, // 60 second timeout (default: 5 minutes) }), }); const agent = new Agent({ name: 'my-agent', model: 'anthropic/claude-opus-4-5', workspace, });

不显式传apiKey时，SDK 会依次回退到E2B_API_KEY、E2B_ACCESS_TOKEN环境变量（见下文配置解析）。更简洁的用法是直接通过 Workspace 执行代码（源码 JSDoc 示例，见 sandbox/index.ts）：

import { Workspace } from '@mastra/core/workspace'; import { E2BSandbox } from '@mastra/e2b'; const sandbox = new E2BSandbox({ timeout: 60_000 }); const workspace = new Workspace({ sandbox }); const result = await workspace.executeCode('console.log("Hello!")');

E2BSandboxOptions 完整配置解析

E2BSandbox的构造参数定义在 sandbox/index.ts，除继承MastraSandboxOptions外，还提供以下专属配置：

配置项	类型	默认值	说明
id	string	自动生成（e2b-sandbox-<时间戳>-<随机串>）	该沙箱实例的逻辑唯一标识
sandboxId	string	无	E2B 物理沙箱 ID；设置后start()会先精确定位并重连该沙箱（暂停则恢复），实现确定性恢复
template	TemplateSpec	默认挂载模板	模板规格，见下文"模板系统"
timeout	number	300_000（5 分钟）	执行超时（毫秒）
env	Record<string, string>	无	注入沙箱的环境变量
metadata	Record<string, unknown>	无	自定义元数据，会被写入 E2B 沙箱的 metadata
network	SandboxNetworkOpts	无	创建沙箱时的网络配置
lifecycle	SandboxLifecycle	{ onTimeout: 'pause' }	超时后的沙箱行为：pause保留快照，kill直接销毁
domain	string	E2B_DOMAIN环境变量	自托管 E2B 的域名
apiUrl	string	E2B_API_URL环境变量	自托管 E2B 的 API 地址
apiKey	string	E2B_API_KEY环境变量	认证 API Key
accessToken	string	E2B_ACCESS_TOKEN环境变量	认证访问令牌
instructions	string \| (opts) => string	默认指令	覆盖getInstructions()返回给 Agent 的环境描述

几个值得深入的点：

超时与生命周期。构造时timeout默认300_000（sandbox/index.ts），生命周期默认{ onTimeout: 'pause' }（sandbox/index.ts），即超时后 E2B 会为沙箱打快照并暂停，下次start()直接重连恢复，后台进程仍在运行。对于数据全部放在沙箱外（如挂载自 S3）的无状态 Workspace，应显式传{ onTimeout: 'kill' }，让空闲沙箱直接销毁、下次按需重建，避免保留暂停快照产生费用。注意：显式调用stop()始终执行暂停，与lifecycle无关。

沙箱死亡自动恢复。代码执行中若检测到沙箱已死（超时、崩溃），retryOnDead()会重置沙箱状态、自动重启沙箱并把操作重试一次（sandbox/index.ts）。重启后挂载状态会被重置为pending，重新执行挂载（sandbox/index.ts）。

模板系统：从默认模板到仓库模板

template配置决定了沙箱的镜像内容，其类型TemplateSpec定义在 utils/template.ts，支持四种形式：

1. 模板 ID 字符串：直接使用 E2B 上已存在的模板，如template: 'my-custom-template'。这也是性能最优的方式——官方建议预构建模板后传 ID。
2. TemplateBuilder：用e2bSDK 的Template()构建器现场定义：

import { Template } from 'e2b'; new E2BSandbox({ template: Template() .fromUbuntuImage('22.04') .aptInstall(['s3fs', 'curl']) .setEnvs({ NODE_ENV: 'production' }), });

3. 定制函数：在默认挂载模板基础上追加定制，(base) => base.aptInstall([...])：

new E2BSandbox({ template: base => base.aptInstall(['nodejs', 'npm']).runCmd('npm install -g typescript'), });

4. 命名模板规格 / 延迟命名模板规格（NamedTemplateSpec/DeferredNamedTemplateSpec）：按确定性名称"存在即复用、缺失才构建"的懒加载模板（详见createRepoTemplate）。

默认挂载模板

createDefaultMountableTemplate()（utils/template.ts）会构建一个预装了s3fs、fuse的模板，用于挂载云存储。它还有几个值得注意的设计：

• 模板 ID 由sha256(version + aptPackages + cpuCount + memoryMB + nodeVersion)的前 16 位哈希生成（mastra-<hash>），资源规格参与模板身份——改变机器大小会生成新模板，绝不会静默复用旧尺寸的构建；
• 默认安装钉死的 Node.js LTS 版本24.20.0（DEFAULT_NODE_VERSION，utils/template.ts），并启用 corepack（pnpm/yarn按仓库packageManager字段解析），同时持久化COREPACK_ENABLE_DOWNLOAD_PROMPT=0关闭非交互下载提示；
• 模板版本号为v3（MOUNTABLE_TEMPLATE_VERSION），修改模板依赖时需要递增该版本号以强制重建。

仓库模板：克隆即用的冷启动优化

createRepoTemplate()（utils/repo-template.ts）为"以某个 Git 仓库为工作对象"的场景而生：模板构建时就把仓库克隆好、依赖装好，沙箱启动后只需git fetch+ checkout 目标 ref，省去冷克隆与全量安装。

• 模板名是确定性的mastra-repo-<slug>-<hash>（由 cloneUrl、setup 命令、build 环境、资源规格哈希而来），commit sha 作为 docker 式 TAG 挂在名字上：mastra-repo-<hash>:sha-<sha>；
• 解析是延迟的：start()时通过git ls-remote（github.com 走 REST API）解析默认分支当前 HEAD，约 100ms 且不克隆；
• stale-build-first：当精确 sha tag 尚不存在、但存在上一次构建（name:currenttag）时，先用旧构建启动沙箱，同时在后台用Template.buildInBackground重建新 ref——只有模板的首次构建才会阻塞沙箱启动（repo-template.ts）；
• 构建失败会回退到 fallback 模板，运行时 setup 再做完整克隆，构建失败绝不会卡死会话；
• refreshRepoTemplate()（repo-template.ts）可被外部驱动（cron 或 merge-to-main 事件处理器），预热模板，让下一个会话"热启动"。

云存储挂载：S3 / GCS / Azure Blob

沙箱通过 FUSE 工具（s3fs、gcsfuse、blobfuse2）把云存储挂载为沙箱内的目录。挂载配置类型定义在 sandbox/mounts/types.ts，三种后端分别位于 s3.ts、gcs.ts、azure.ts。

挂载 S3（s3fs-fuse）

E2BS3MountConfig支持以下参数：

参数	必填	说明
bucket	是	S3 桶名（3-63 位小写字母、数字、连字符、点）
region	是	AWS 区域，如us-east-1（S3 兼容存储可用auto）
endpoint	否	S3 兼容存储（MinIO、Cloudflare R2 等）的端点
accessKeyId/secretAccessKey	否	凭证，必须成对提供
prefix	否	只挂载桶的子目录（bucket:/prefix语法，自动归一化首尾斜杠）
readOnly	否	只读挂载

组合使用示例（见 sandbox/index.ts 的 JSDoc）：

import { Workspace } from '@mastra/core/workspace'; import { E2BSandbox } from '@mastra/e2b'; import { S3Filesystem } from '@mastra/s3'; const workspace = new Workspace({ mounts: { '/bucket': new S3Filesystem({ bucket: 'my-bucket', region: 'us-east-1', }), }, sandbox: new E2BSandbox({ timeout: 60_000 }), });

实现要点（s3.ts）：

• 不带凭证时对公有桶以public_bucket=1只读挂载；S3 兼容服务（R2、MinIO）必须提供凭证，否则直接报错；
• 凭证写入按挂载路径哈希的独立文件（/tmp/.passwd-s3fs-<hash>，chmod 600），避免并发挂载竞争同一路径；
• 挂载命令使用sudo s3fs（访问/dev/fuse），并显式传uid/gid保证文件属主是当前用户；
• s3fs 守护进程化后父进程可能已返回退出码 0，因此挂载后会用mountpoint -q二次校验挂载点是否真正生效，失败会给出排查提示（区域不匹配、凭证错误、签名被拒等）。

挂载 GCS（gcsfuse）

E2BGCSMountConfig支持bucket、serviceAccountKey（服务账号 JSON，可省略以匿名只读访问公有桶）、prefix（通过--only-dir只挂载子目录）。gcsfuse 未安装时会自动探测 Ubuntu codename、以signed-bykeyring 方式配置 Google apt 仓库并安装（gcs.ts）。注意 gcsfuse 使用--uid/--gid参数而非-o uid=X风格（gcs.ts）。

挂载 Azure Blob（blobfuse2）

E2BAzureBlobMountConfig支持container、accountName、accountKey、sasToken、connectionString、useDefaultCredential（托管身份/MSI）、endpoint（主权云、Azurite）、prefix、readOnly。认证按优先级选择：useDefaultCredential→sasToken→accountKey→connectionString解析（azure.ts）。实现上会为每个挂载生成 YAML 配置文件（root 属主、chmod 600），blobfuse2 要求空缓存目录，安装失败时会回退到 GitHub 官方 .deb 包。

挂载安全与对账

所有挂载路径必须匹配白名单正则/^\/[a-zA-Z0-9_.\-/]+$/，拒绝非绝对路径与非法字符（sandbox/index.ts）；桶名、区域、端点、前缀在拼入 shell 命令前都经过校验，防止命令注入。挂载目标目录若已存在且非空会被拒绝（避免遮蔽已有文件）。

此外，每个由 Mastra 创建的挂载都会写入 marker 文件（/tmp/.mastra-mounts/mount-<hash>），记录挂载路径与配置哈希。重连已有沙箱时，reconcileMounts()（sandbox/index.ts）会比对/proc/mounts中的 FUSE 挂载与 marker 文件：配置匹配则跳过，配置变化则先卸载再重挂；只清理由 Mastra 自己创建（有 marker）的过期挂载，外部 FUSE 挂载不会被误动。

沙箱生命周期：start / stop / destroy

• start()：由基类编排，依次走find()（复用已有连接或按身份发现）→connect()（重连并恢复）→create()（模板解析 + 新建）。只有真正创建了新 VM 才记为outcome: 'created'，重连（含恢复暂停沙箱）记为'connected'；
• stop()：先尽力卸载所有挂载（FUSE 挂载无法跨越暂停），再pause()暂停 VM——冻结整个文件系统、内存与运行中进程并立即停止计费；下次start()恢复。若本进程未 attach，则通过身份查询后直接对远端沙箱执行Sandbox.pause()（sandbox/index.ts）；
• destroy()：杀掉所有后台进程、卸载挂载、kill()销毁 VM 并清空挂载状态（sandbox/index.ts）。

确定性重连：传入sandboxId后，start()会先精确查询并连接该物理沙箱（自动恢复暂停态），而不是按逻辑id元数据发现。只有"沙箱已消失"类错误（not found / killed / not running）才会回退到逻辑 id 发现与创建；认证、配额、限流、超时、网络错误会直接向上抛出，绝不创建重复 VM（sandbox/index.ts）。连接前还会校验沙箱属主：被其他mastra-sandbox-id标记的沙箱会被拒绝挂接。启动后可读取sandbox.sandboxId并持久化，下次用clone({ sandboxId })或新实例重连。

克隆与网络暴露：clone(options)会构造一个继承父沙箱全部配置（凭证、模板、网络、元数据、指令）的兄弟沙箱，适合"一个配置模板生成一队独立沙箱（如每个项目一个）"的场景；idleTimeoutMinutes会映射为毫秒级timeout。网络方面，E2B 会为每个端口暴露公网 HTTPS URL，getPortUrl(port)在已连接时通过sandbox.getHost(port)解析，未 attach 时按{port}-{sandboxId}.{domain}推导，其他进程无需唤醒暂停沙箱即可解析部署地址（sandbox/index.ts）。

进程管理与 Code Mode

进程管理：E2BProcessManager（process-manager.ts）封装 E2B 的commands.run(..., { background: true })，支持后台 spawn、sendStdin、list、按 PIDget（本进程跟踪不到时回退到commands.connect()连接既存进程）。spawn 全程包在retryOnDead()里，沙箱死亡会自动重启重试。

Code Mode：核心包默认的StdioCodeModeTransport把 runner/program 写到宿主机 tmpdir 并执行node <hostPath>，这只适用于与宿主共享文件系统的沙箱（如LocalSandbox）。E2BCodeModeTransport（code-mode/transport.ts）则把程序写入远程沙箱（/home/user/mastra-code-mode/<suffix>），在 VM 内跑node，并通过 stdout/stdin 复用与核心 stdio transport 相同的帧协议桥接 RPC 调用。它用 esbuild 在宿主机先把 TypeScript 剥离成纯 JS（target: 'es2022'），因此不依赖沙箱内 Node 版本（核心 transport 依赖 Node ≥ 22.6 的--experimental-strip-types）。RPC 层有工具白名单校验、超时（TimeoutError）、进程退出未产出结果（NoResultError）等兜底。用法：

import { createCodeMode } from '@mastra/core/tools'; import { E2BSandbox, E2BCodeModeTransport } from '@mastra/e2b'; const { tool, instructions } = createCodeMode( { tools: { getWeather, getForecast }, sandbox: new E2BSandbox() }, new E2BCodeModeTransport(), );

与 Agent、Editor 生态集成

• Agent 集成：上文快速开始示例展示了Workspace+E2BSandbox→Agent的完整链路。Agent 可通过sandbox.getInstructions()获得环境描述（默认"Cloud sandbox. N filesystem(s) mounted via FUSE."），instructions配置可整体替换或用函数基于默认指令扩展（sandbox/index.ts）；
• MastraEditor 集成：e2bSandboxProvider（provider.ts）是面向MastraEditor的可序列化 Provider 描述符，自带 JSON Schema（template、timeout、env、metadata、domain、apiUrl、apiKey、accessToken），编辑器通过createSandbox(config)实例化沙箱：

import { e2bSandboxProvider } from '@mastra/e2b'; const editor = new MastraEditor({ sandboxes: [e2bSandboxProvider], });

自托管与环境变量

对接自托管 E2B 时，通过domain/apiUrl/apiKey/accessToken配置项指定，或设置以下环境变量（优先级低于显式配置）：E2B_DOMAIN、E2B_API_URL、E2B_API_KEY、E2B_ACCESS_TOKEN。沙箱公网 host 的推导域名也使用domain或E2B_DOMAIN，默认e2b.app（sandbox/index.ts）。

验证与测试

该包自带完整的单元测试与云端集成测试：

• sandbox/index.test.ts：覆盖构造参数与 ID 生成、start()竞态防护、模板处理（含 repo 模板的 sha 解析）、环境变量、S3/GCS 挂载操作、marker 文件与挂载对账等，并复用@internal/workspace-test-utils提供的通用生命周期/挂载测试套件；
• sandbox/index.integration.test.ts：真实调用 E2B 云的集成测试，通过pnpm test（即vitest run ./src/**/*.integration.test.ts）运行；
• code-mode/transport.test.ts 与 utils/template.test.ts、utils/repo-template.test.ts 分别验证传输层与模板逻辑。

运行单元测试：pnpm test:unit（在workspaces/e2b目录下，等价于vitest run --exclude '**/*.integration.test.ts'）。

小结

@mastra/e2b把 E2B 云端沙箱无缝接入 Mastra 的 Workspace / Agent 生态：开箱即用的云端代码执行、基于 FUSE 的 S3/GCS/Azure Blob 挂载、按身份确定性重连、超时自动恢复、模板懒构建与仓库模板冷启动优化，以及面向 Code Mode 的远程执行传输层。其核心实现与全部配置均可进一步阅读 workspaces/e2b/src 下的源码与 包变更记录。

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra