Workspaces

工作区是一组运行时资源，Mastra platform 会在部署时创建并交给你的 agents。每个环境都有自己的工作区，因此 production 和 staging 保持隔离。

每个工作区提供两项能力：

• 一个用于文件系统存储的 bucket，由 PlatformFilesystem 封装。该 bucket 是一个持久、环境作用域的存储，agents 可在多次运行之间读取和写入。
• 一个用于命令执行的按需 sandboxes 池，由 PlatformSandbox 封装。每个 PlatformSandbox 实例在 start() 时创建自己的远程 sandbox，并在 destroy() 时销毁它。Agents 通常会在每个会话中启动许多 sandboxes，用它们完成任务，然后释放。

工作区限定在单个环境，因此 production 和 staging 不共享 buckets 或 sandbox 池。平台负责创建、身份验证和空闲清理。

何时创建工作区

新项目默认启用工作区。当你创建环境时，平台会自动为其创建一个 bucket。sandbox 基础镜像会在后台预热，以便第一次 PlatformSandbox 调用快速启动。

尚未选择加入的现有项目会在 Workspaces 标签页中显示 Enable workspaces 操作。启用会为项目上的每个环境创建一个 bucket。

如果某个环境的创建失败，例如 sandbox 提供器负载过高，Workspaces 标签页会显示失败并提供重试。环境本身仍会创建。在重试之前，只有工作区不可用。

在代码中使用工作区

安装提供器包：

npm

npm install @mastra/platform-workspace

pnpm

pnpm add @mastra/platform-workspace

Yarn

yarn add @mastra/platform-workspace

Bun

bun add @mastra/platform-workspace

将提供器组合成工作区并注册到 Mastra：

src/mastra/workspace.ts

import { Workspace } from '@mastra/core/workspace'
import { PlatformFilesystem, PlatformSandbox } from '@mastra/platform-workspace'

export const workspace = new Workspace({
  filesystem: new PlatformFilesystem(),
  sandbox: new PlatformSandbox(),
})

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { workspace } from './workspace'

export const mastra = new Mastra({
  workspace,
})

PlatformFilesystem 和 PlatformSandbox 会从环境变量读取配置，因此在平台上无需传入任何选项。平台会在部署时注入它们。请参阅环境变量。

一个 bucket，多个 sandboxes

PlatformFilesystem 和 PlatformSandbox 的生命周期不同，这在设计 agents 时很重要。

PlatformFilesystem 是环境 bucket 的长生命周期句柄。 使用此提供器的所有请求和 agents 都会读写同一个对象存储。除非你明确删除，agent 写入的任何内容都会在下一个请求中可见。

PlatformSandbox 是用于创建临时 sandboxes 的客户端。 每个 PlatformSandbox 实例拥有一个远程 sandbox：

• start() 创建一个全新的 sandbox（或在你传入 sandboxId 时重新附加）。
• executeCommand() 对其运行命令。
• stop() 释放此进程的租约，但不触碰远程 sandbox。VM 会按环境的空闲策略继续运行，之后使用相同 id 或 sandboxId 的 start() 会重新附加到它。
• destroy() 释放 VM。在 Railway 上，它还会删除与调用方提供的 recovery id 关联的恢复检查点。在 E2B 上，它只会终止 VM，你捕获的任何快照仍由你管理。

静态配置的 PlatformSandbox 会在使用该配置的每个请求和 agent 之间共享，而不是为请求或 memory threads 创建单独的 sandboxes。PlatformFilesystem 也是独立的提供器：同时配置两个提供器并不会将环境 bucket 挂载到 sandbox 内。

当你的 agent 需要另一个隔离环境时，例如每个任务的 sandbox、每位用户的租户，或不应触碰共享 shell 状态的后台任务，请构造另一个 PlatformSandbox：

src/mastra/tools/run-in-fresh-sandbox.ts

import { PlatformSandbox } from '@mastra/platform-workspace'

export async function runInFreshSandbox(command: string) {
  const sandbox = new PlatformSandbox()
  await sandbox.start()
  try {
    return await sandbox.executeCommand(command)
  } finally {
    await sandbox.destroy()
  }
}

或克隆已配置的 sandbox 作为一组实例的模板。克隆会继承凭据、环境、网络隔离和默认值，无需重复配置：

const template = new PlatformSandbox({ networkIsolation: 'PRIVATE' })

const perProjectSandbox = template.clone({ id: `project-${projectId}` })
await perProjectSandbox.start()

完整生命周期、检查点恢复、重新附加和克隆选项请参阅 PlatformSandbox 参考。

环境变量

在带工作区的平台环境上运行的每次部署都会自动收到这些变量：

变量	内容
MASTRA_PLATFORM_ACCESS_TOKEN	平台签发的 JSON Web Token（JWT），工作区提供器用它进行身份验证。token 限定在部署所在的组织和项目。
MASTRA_PROJECT_ID	部署所属的项目。
MASTRA_ENVIRONMENT_ID	部署所属的环境。用于选择平台使用哪个 sandbox 池。
MASTRA_PLATFORM_BUCKET_NAME	附加到环境的 bucket 名称。用于选择 PlatformFilesystem 读写的 bucket。

这些名称是保留的。如果你的项目显式设置了其中任何一个，平台管理的值优先。

本地开发

将这四个变量放入 .env 文件，即可在本地复用相同的提供器。从项目的 Workspaces 标签页获取项目、环境和 bucket 值。对于 MASTRA_PLATFORM_ACCESS_TOKEN，请在组织设置页面的 API Tokens 下创建 sk_ API token。平台部署会改用注入的 JWT。

.env

MASTRA_PLATFORM_ACCESS_TOKEN=sk_your-api-token
MASTRA_PROJECT_ID=your-project-id
MASTRA_ENVIRONMENT_ID=your-environment-id
MASTRA_PLATFORM_BUCKET_NAME=your-bucket-name

PlatformFilesystem 和 PlatformSandbox 在本地与在平台上的行为相同，它们会连接到该环境的同一个 bucket 和 sandbox 池。如果你希望保持 production 数据隔离，请在本地运行时使用 staging 或 preview 环境的变量。

对于完全不接触平台的纯离线循环，请在本地构建中将提供器替换为 LocalFilesystem 和 LocalSandbox。

检查工作区

平台项目的 Workspaces 标签页会按环境显示：

• Bucket 状态及其内容，支持上传、下载和删除操作。
• 最近的 sandbox 会话及其命令、退出码和持续时间。
• 创建失败及 Retry 操作。

另请参阅

• PlatformFilesystem：文件系统提供器的参考。
• PlatformSandbox：sandbox 提供器的参考，包括检查点恢复和克隆。
• 环境：环境如何限定工作区、变量和数据库的作用域。