0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00
mastra/workspaces/platform-workspace
History 2026-11-12 21:12:29 +00:00
..
src feat(factory): Factory-wide sandbox environment variables (#29923) 2026-11-10 17:14:26 -07:00
CHANGELOG.md chore: version - exit prerelease mode 2026-11-12 21:12:29 +00:00
lint-staged.config.js chore: run lint-staged for root files and the 16 packages without a config (#29898) 2026-11-10 14:08:55 +01:00
package.json chore: version - exit prerelease mode 2026-11-12 21:12:29 +00:00
README.md chore: update package READMEs and add conditional CI validation (#23488) 2026-09-10 13:46:36 +02:00
tsconfig.build.json feat(platform): add Platform workspace providers (#18908) 2026-07-14 10:20:10 -04:00
tsconfig.json chore: migrate package builds to tsdown (#19829) 2026-07-28 12:32:21 +02:00
tsdown.config.ts feat(workspace): native sandbox filesystem for E2B and Platform sandboxes (#27859) 2026-10-20 14:17:57 -07:00
vitest.config.ts feat(platform): add Platform workspace providers (#18908) 2026-07-14 10:20:10 -04:00

@mastra/platform-workspace

Mastra Platform workspace provider. It gives agents environment-scoped sandbox execution and bucket-backed filesystem access through the Mastra Platform workspace proxy.

Installation

npm install @mastra/platform-workspace

Usage

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

const workspace = new Workspace({
  filesystem: new PlatformFilesystem({}),
  sandbox: new PlatformSandbox({
    idleTimeoutMinutes: 30,
    networkIsolation: 'ISOLATED',
  }),
});

const agent = new Agent({
  name: 'code-analyzer',
  model: 'anthropic/claude-sonnet-4-5',
  workspace,
});

Documentation

Both providers authenticate through the workspace proxy with MASTRA_PROJECT_ID and a credential. Set MASTRA_PLATFORM_SECRET_KEY to your organization API key for local development. The deployed MASTRA_PLATFORM_ACCESS_TOKEN takes precedence when present; an explicit accessToken constructor option takes precedence over both. Blank environment credentials are ignored. PlatformSandbox also requires MASTRA_ENVIRONMENT_ID; PlatformFilesystem requires MASTRA_PLATFORM_BUCKET_NAME. Constructor values override environment variables, and MASTRA_WORKSPACE_PROXY_URL can point requests at a non-production proxy.

PlatformFilesystem implements the Mastra filesystem interface against a Platform bucket. It supports reading, writing, listing, moving, and deleting files, preserves reserved characters in object names, and can be mounted with readOnly: true to reject mutations.

PlatformSandbox starts or reconnects to an environment-scoped provider sandbox and implements command execution, lifecycle, and networking operations. The provider defaults to E2B and can be changed to Railway through sandboxProvider or SANDBOX_PROVIDER. Pass an existing sandboxId to reattach to a live sandbox, and actingUserId to partition and attribute project-token requests to a stable application user.

The exported Template() builder creates reusable sandbox images from commands, packages, environment values, repository checkouts, CPU, memory, and working-directory settings. Platform derives a content identity from the serialized template so matching definitions can reuse previous builds. Ephemeral environment values are excluded from that identity and are not persisted into the runtime image.

Proxy failures throw PlatformApiError, which includes the HTTP status, parsed machine-readable error code, proxy message, and raw response body. Use these fields to distinguish missing resources, authentication failures, and provider errors.

Configuration

All options can be passed to the constructor or read from environment variables:

Option Env var Required
accessToken MASTRA_PLATFORM_ACCESS_TOKEN or MASTRA_PLATFORM_SECRET_KEY Yes
projectId MASTRA_PROJECT_ID Yes
environmentId MASTRA_ENVIRONMENT_ID Yes (sandbox)
actingUserId — No (sandbox)
sandboxProvider SANDBOX_PROVIDER No (sandbox, defaults to e2b)
bucketName MASTRA_PLATFORM_BUCKET_NAME Yes (filesystem)

The proxy URL defaults to https://workspaces.mastra.ai. Set MASTRA_PLATFORM_REGION to us or eu (case-insensitive) to route to the regional replica at https://workspaces.us.mastra.ai or https://workspaces.eu.mastra.ai. An explicit MASTRA_WORKSPACE_PROXY_URL (useful for staging) overrides both.

Requests to the proxy are authenticated with Authorization: Bearer <accessToken>. For sandbox requests authenticated with a project access token, set actingUserId to the stable opaque user subject from your authentication system. It is sent as x-acting-user-id for token partitioning and attribution; it is not an authorization claim.

Changelog

See the package changelog for version history and release notes.

Support

We have an open community Discord. Come and say hello and let us know if you have any questions or need any help getting things running.