如何用 @mastra/deployer-sandbox 把 Mastra server 部署到 E2B、Daytona 或 Vercel 沙箱获得公网 URL

@mastra/deployer-sandbox 把完整的 Mastra server（包含 Studio）部署到临时（ephemeral）工作区沙箱中，并返回一个可直接访问的公网 URL。官方文档把这类部署用于：agent 生成 Mastra 项目后部署验证、CI 中拉起真实 server 做检查、合并前给团队分享一个可运行的 agent、以及按用户隔离运行不受信任的代码。沙箱有 provider 强制的运行时长上限且会过期，不适合生产托管；文档建议生产场景改用其他部署方式。

选择沙箱 provider

deployer 支持任何实现了 networking 能力（即支持公网端口 URL）的 WorkspaceSandbox，官方列出三家：

• Vercel Sandbox，包名 @mastra/vercel
• E2B，包名 @mastra/e2b
• Daytona，包名 @mastra/daytona

三家之间的关键差异（后面配置时要用到）：

• Vercel 只在创建时声明过的端口上暴露服务，所以必须在 ports 里声明 server 端口；且 timeout 不能超过你套餐的沙箱最长生命周期（Pro 计划为 45 分钟），超出会让部署以 Vercel API 的 400 错误失败。
• E2B 和 Daytona 不需要声明端口。
• E2B 停止时是整个 VM（含内存和进程）打快照，唤醒后 server 直接从断点恢复，无需重启。Vercel 和 Daytona 恢复文件系统但不恢复进程，唤醒时需要重新拉起 server（wake: true 时 resolver 会自动做这件事）。

安装 deployer 与 provider

在你的 Mastra 项目中安装 deployer 和你选择的 provider。以 Vercel 为例：

npm install @mastra/deployer-sandbox @mastra/vercel

选 E2B 或 Daytona 时，第二个包换成 @mastra/e2b 或 @mastra/daytona。

在 src/mastra/index.ts 中配置 SandboxDeployer

deployer 在 Mastra 入口文件 src/mastra/index.ts 中配置。sandboxName（Vercel）或 id（E2B/Daytona）是部署的身份标识：后续使用相同名称的部署会复用已有沙箱；重复部署在 package.json、安装命令和打包后的 lockfile 都没变化时会跳过依赖安装。

以下三条是并列的可选路径，按你选择的 provider 取其一。

路径 A：Vercel Sandbox

import { Mastra } from '@mastra/core/mastra'
import { SandboxDeployer } from '@mastra/deployer-sandbox'
import { VercelSandbox } from '@mastra/vercel'

export const mastra = new Mastra({
  deployer: new SandboxDeployer({
    sandbox: new VercelSandbox({
      sandboxName: 'my-preview',
      timeout: 2_400_000, // 40 minutes
      ports: [4111],
    }),
  }),
})

ports: [4111] 是 Vercel 的必选项——它只暴露创建时声明的端口。

路径 B：E2B

import { Mastra } from '@mastra/core/mastra'
import { SandboxDeployer } from '@mastra/deployer-sandbox'
import { E2BSandbox } from '@mastra/e2b'

export const mastra = new Mastra({
  deployer: new SandboxDeployer({
    sandbox: new E2BSandbox({
      id: 'my-preview',
      template: 'base',
      timeout: 3_600_000, // 1 hour
    }),
  }),
})

文档建议传 template: 'base'，除非你需要文件系统挂载；不传时 provider 会在首次使用时构建一个自定义 FUSE 模板，首次部署更慢。

路径 C：Daytona

import { Mastra } from '@mastra/core/mastra'
import { SandboxDeployer } from '@mastra/deployer-sandbox'
import { DaytonaSandbox } from '@mastra/daytona'

export const mastra = new Mastra({
  deployer: new SandboxDeployer({
    sandbox: new DaytonaSandbox({
      id: 'my-preview',
      public: true,
      autoStopInterval: 30, // minutes
    }),
  }),
})

public: true 让预览 URL 无需 token 即可访问。

配置 provider 凭证：mastra build 不加载 .env

这是最容易踩的一步。每个 provider 用自己的凭证变量：

# E2B
E2B_API_KEY=

# Daytona
DAYTONA_API_KEY=

# Vercel
VERCEL_TOKEN=
VERCEL_TEAM_ID=
VERCEL_PROJECT_ID=

这三个变量也可以作为构造器选项传入。自托管的 E2B 和 Daytona 分别用 E2B_DOMAIN 或 DAYTONA_API_URL 指定地址。

关键限制：与 mastra dev 不同，mastra build 不会加载 .env 文件。而部署发生在 build 过程中，读取环境变量取凭证的 provider（例如用 E2B_API_KEY 的 E2B）会拿到空值，部署以认证错误失败。

在 src/mastra/index.ts 里加 import 'dotenv/config' 也解决不了问题：build 为了定位 deployer 只从入口文件提取 deployer 选项，其余内容（包括这个 import）都会被 tree-shake 掉。

文档给出的做法是把 .env 在 build 之前加载进 shell 环境，例如用 dotenv-cli：

npm install --save-dev dotenv-cli

在 package.json 中增加一个独立的 deploy 脚本：

{
  "scripts": {
    "deploy": "dotenv -e .env -- mastra build"
  }
}

然后把 npm run deploy 与普通的 build 脚本分开——因为配置了 SandboxDeployer() 之后 mastra build 就会部署，如果 CI 或托管平台跑 npm run build，会意外地部署一个沙箱。

在 CI 中则把凭证导出为 secrets。无论用哪种机制，变量必须存在于 shell 环境中，不能只写在 .env 文件里。注意区分两类变量：deployer 在你本机上需要的凭证按上面的方式提供；而部署出去的 server 需要的变量由 deployer 读取 .env、.env.production、.env.local 并注入到沙箱中（日志中会有警告），两者是独立处理的。

执行部署并验证公网 URL

运行：

npm run deploy

配置了 SandboxDeployer() 后，mastra build 会打包项目并部署进沙箱，输出 API 和 Studio 两个 URL，并把 sandbox-deployment.json 清单写入 .mastra/output。文档示例输出（URL 格式随 provider 变化）：

API:    https://<sandbox-id>-4111.vercel.run/api
Studio: https://<sandbox-id>-4111.vercel.run

清单在 provider 报告过期时间时会包含 expiresAt 字段。

两个 URL 的语义不同，验证时要分清：

• Studio URL 是沙箱根路径（不带 /api），在浏览器打开即可使用 Studio。部署时如果 studio: false，根路径返回 Mastra 欢迎页。
• API URL 只是下面各端点的路径前缀。/api 本身没有 handler，直接在浏览器打开会返回 "Not Found"——这不代表 server 没起来。

正确的验证方式是直接调用一个端点。文档给出的示例（E2B 域名，agent 名 weatherAgent）：

curl -s -X POST https://4111-<sandbox-id>.e2b.app/api/agents/weatherAgent/generate \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Weather in London"}]}' | jq -r '.text'

把域名、端口和 agent id 换成你自己部署的输出值和项目中的 agent。

在 CI 中，文档给出的 smoke check 是直接校验清单里的 URL：

curl --fail "$(jq -r .url .mastra/output/sandbox-deployment.json)/api"

已知限制与排查点

• 沙箱会过期，URL 会轮换。 沙箱按 provider 的运行时限制过期；日志会打印过期时间，deployment.expiresAt 以编程方式暴露。沙箱停止后恢复时 URL 可能变化，文档建议把 URL 当作管道、把沙箱身份（如 sandboxName）当作稳定句柄。

• 沙箱 URL 是公开的。 拿到 URL 的人可以直接访问你的 Mastra server（包括 Studio）。一次性预览没问题，更长时间的部署文档建议启用 server auth（见 Server authentication）。

• Daytona 出站流量按目标主机过滤。 部分主机 TLS 连接正常，另一些会在握手阶段被 reset，在 agent 或工具里表现为 Node 的通用 fetch failed。文档建议先用 curl 在沙箱内对同一主机发起请求来排除自己的代码：

  const sandbox = new DaytonaSandbox({ id: 'my-preview' })
  await sandbox.start()
  
  const result = await sandbox.executeCommand('curl -v --max-time 10 https://api.example.com')
  console.info(result.stdout, result.stderr)
  

  TLS 握手期间出现 Connection reset by peer 指向 Daytona 的过滤而非你的 agent，需要联系 Daytona 支持放行该目标。受限的 Daytona 层级还会屏蔽云存储端点，mount 工具会报专门的错误。

• Vercel timeout 超限直接 400。 timeout 不能超过你套餐的沙箱最长生命周期（Pro 为 45 分钟），否则 Vercel API 返回 400，部署失败。

后续：按名称解析当前 URL

沙箱停止或过期后，旧的公网 URL 不再可用。用 server-only 的 getDeployment()（来自 @mastra/deployer-sandbox/client）可以在运行时解析当前 URL，任何知道沙箱名称的服务端代码（包括另一个代码库或 CI）都能调用：

import { getDeployment } from '@mastra/deployer-sandbox/client'
import { VercelSandbox } from '@mastra/vercel'

const deployment = await getDeployment({
  sandbox: new VercelSandbox({ sandboxName: 'my-preview', ports: [4111] }),
  wake: true,
})

console.info(deployment.url, deployment.status)

wake: true 会恢复已停止的沙箱，并在 server 不健康时重新拉起；默认 wake: false 则只返回 { url, status }，不会唤醒沙箱，因此对已停止沙箱的解析、stop()、destroy() 都不会产生恢复或计费。注意该模块只能在服务端使用，在浏览器中 import 会直接抛错，因为解析需要 provider 凭证。

完整文档见 Sandbox 部署指南 和包说明 deployers/sandbox/README.md；如需给终端用户提供自己域名下的稳定 URL，源文档还给出了 createSandboxHandler() 代理和 Edge Config alias 两种 Tier 3 路由方案，可按需查阅。