## Summary
- clarify that Mastra's Vercel Sandbox adapter does not implement the
Workspace filesystem mounting API
- distinguish that adapter limitation from Vercel Sandbox's native FUSE
mount support in both documentation and agent-facing default
instructions
- document the underlying SDK instance as an unmanaged escape hatch for
configuring mounts directly
- add regression coverage and a patch changeset for `@mastra/vercel`
## Test plan
- `pnpm exec vitest run src/microvm/index.test.ts` (from
`workspaces/vercel`)
- `pnpm lint` (from `workspaces/vercel`)
- `pnpm build` (from `workspaces/vercel`)
- `pnpm exec oxfmt-mdx --check
src/content/en/integrations/sandboxes/vercel.mdx` (from `docs`)
- focused Remark validation
- `git diff --check`
## Notes
- Vale was not available in this workspace, so the focused Vale check
could not run.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->
## ELI5
Mastra’s Vercel Sandbox adapter does not provide filesystem mounting
tools. Vercel Sandbox supports FUSE mounts, but users must configure
them directly on the underlying sandbox.
## Changes
- Clarifies in the documentation and default instructions that Mastra
does not manage Workspace filesystem mounts, while Vercel Sandbox
supports native FUSE mounts.
- Adds regression coverage for the updated default instructions.
- Adds a patch changeset for `@mastra/vercel`.
## Validation
The PR description reports successful Vitest, lint, build, formatting,
Remark, and `git diff --check` checks. It also reports that Vale was
unavailable. The supplied shell result showed no diff for the requested
files, so it does not independently confirm these changes or validation
results.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: labifrancis
## Summary
`WorkspaceSandbox.writeFiles` previously exposed only `path` and
`content`, so callers could not control the permissions of provisioned
files. This adds an optional per-file `mode` to the write input and
gives each sandbox provider a clear, honest contract for it.
- **Core**: `SandboxFileInput` gains an optional `mode` (validated
integer `0o001`–`0o777`, permission bits only). Adds
`validateSandboxFileMode`, `assertModesUnsupported`, and a
`SandboxUnsupportedFeatureError`.
- **Docker**: applies the requested `mode` to each uploaded tar entry,
falling back to `0644` when omitted.
- **Vercel, E2B, Daytona, Cloudflare**: their upload transports cannot
set permissions, so a `writeFiles` call that includes a `mode` is
rejected up front rather than silently ignored. Omitting `mode` is
unchanged and fully backward compatible.
`mode: 0` is rejected: it is not usefully provisionable and cannot be
represented by the tar transport Docker uses (tar-stream substitutes its
`0644` default for a falsy mode), so honoring it would be impossible.
Rejecting keeps the honor-or-reject guarantee intact.
Closes#23580.
## Test plan
- Core validator unit tests: valid range accepted,
zero/negative/out-of-range/non-integer rejected,
`assertModesUnsupported` rejects explicit modes.
- Docker unit tests: explicit modes honored on the tar entry, invalid
modes rejected without uploading, default `0644` when omitted.
Integration test verifies permissions end-to-end.
- Vercel, E2B, Daytona, Cloudflare unit tests: explicit modes rejected;
omitted modes unchanged.
- All affected packages build cleanly.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
You can now choose file permissions when uploading files to a Docker
sandbox. Other sandboxes report a clear error when they cannot support
custom permissions.
## Changes
- Added optional `mode` support to `WorkspaceSandbox.writeFiles`.
- Validated modes from `0o001` through `0o777`.
- Rejected `mode: 0` and other invalid values.
- Applied requested modes in Docker, with `0o644` as the default.
- Supported permission changes when Docker overwrites files.
- Added explicit unsupported-feature errors for Vercel, E2B, Daytona,
and Cloudflare.
- Added validation helpers and exported
`SandboxUnsupportedFeatureError`.
- Added unit tests, Docker integration coverage, and documentation.
- Updated built-in provider peer dependency minimums to `@mastra/core`
`1.67.0-0`.
- Reordered unrelated Tailwind classes in Playground UI files without
functional changes.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Abhi Aiyer <abhiaiyer91@gmail.com>
Co-authored-by: mastra-platform[bot] <284800079+mastra-platform[bot]@users.noreply.github.com>
Adds one instance-level `workingDirectory` option to
`MastraSandboxOptions` in `@mastra/core`, honored by every sandbox
provider as the default directory for command execution when a
per-command `cwd` isn't given. Per-command `cwd` always wins, and
behavior is unchanged when the option is omitted.
```ts
const sandbox = new E2BSandbox({ id: 'my-sandbox', workingDirectory: '/workspace/repo' });
await sandbox.executeCommand('pwd'); // /workspace/repo
await sandbox.executeCommand('pwd', { cwd: '/tmp' }); // /tmp — per-command cwd wins
```
Before this, the concept was fragmented: cloudflare had
`workingDirectory`, docker/apple-container had `workingDir`, modal had
`workdir`, daytona probed for it, and
e2b/railway/vercel/agentcore/blaxel/platform-workspace had nothing —
bare commands landed in the provider's home directory. The legacy names
still work as deprecated aliases feeding the same base field, so nothing
breaks; `workingDirectory` wins if both are set.
Notes for review: docker honors the option through the container's
`WorkingDir` (no per-exec fallback, so reconnected external containers
behave as before), daytona's probe still runs when the option is absent,
vercel serverless keeps its `/tmp` final fallback, and agentcore
requires absolute paths (`~` doesn't expand inside its quoted `cd`
prefix — documented on the option). Verified live against a real E2B VM:
bare `pwd` returns `/home/user` on main and the configured directory on
this branch.
Factory/SDK adoption (defaulting the factory checkout dir into this
option) is a small follow-up PR.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
You can set one default folder for sandbox commands. A command-specific
`cwd` still overrides it, and existing provider defaults continue to
work when no folder is set.
## Changes
- Added `workingDirectory` to `MastraSandboxOptions`.
- Applied it across sandbox providers and process managers.
- Added getter and protected setter support.
- Preserved deprecated aliases for Docker, Apple Container, and Modal.
- Made `workingDirectory` take precedence over aliases.
- Preserved provider fallbacks and Daytona directory detection.
- Required absolute paths for AgentCore. `$HOME` and `~` are not
expanded.
- Updated documentation, tests, and changesets.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: CalebBarnes <CalebBarnes@users.noreply.github.com>
Co-authored-by: Mastra Code (anthropic/claude-fable-5) <noreply@mastra.ai>
Sandboxes now own a runtime environment in `@mastra/core`, and every
workspace provider honors it. `MastraSandbox` accepts an `env`
constructor option and exposes `setEnv(updater)` + `getEnv()`, and the
base `SandboxProcessManager` merges that environment into every process
spawn (which also covers the built-in `executeCommand`). Providers whose
execution routes through their process manager pick this up with zero
provider code; providers with proprietary exec transports merge
`getEnv()` themselves.
The motivating case: the Factory installs a rotating `GH_TOKEN` into
session sandboxes after they're created. That used to go through an
optional `setEnvironmentVariable?.()` call that no provider implemented,
so the install silently no-opped and `gh` failed inside sandboxes. With
this change the capability lives in core, so hosts can call it on any
sandbox:
```ts
const sandbox = new LocalSandbox({ workingDirectory, env: { STAGE: 'dev' } });
// later, after minting a fresh credential
sandbox.setEnv(env => ({ ...env, GH_TOKEN: token }));
// every subsequent command sees it
await sandbox.executeCommand('gh', ['auth', 'status']);
```
The updater receives a copy of the current environment and returns the
replacement, so a single call can set, rotate, unset, or batch-update
values. Precedence is provider defaults < sandbox runtime env < per-call
`env`. The values are merged per spawn and never written into the VM, so
it survives pause/resume and VM replacement, and credentials never touch
VM disk. When the sandbox has no runtime env set, spawn options pass
through untouched.
`WorkspaceSandbox` declares `setEnv` as an optional method so hosts can
call it without structural casts.
## Provider pass (folded in from #22253)
Every `workspaces/*` sandbox provider now honors the runtime env:
- **Process-manager-routed providers** (E2B, Blaxel, Cloudflare,
Daytona, Docker, Modal, Vercel microVM spawns): duplicated per-manager
env plumbing deleted — the core spawn wrapper owns the merge.
- **Direct-exec transports** (AgentCore, Apple Container, Railway,
Vercel microVM + serverless, Platform
private-network/WS-lease/E2B-lease): now merge `getEnv()` under per-call
env in their own exec paths.
- **Bake-at-create env untouched** (Docker `Env` array,
Modal/Railway/Platform create bodies, Apple Container `--env`, Vercel VM
create): creation-time semantics are deliberately unchanged; constructor
`env` still seeds the runtime env through `super()`.
- Removed exported types `BlaxelProcessManagerOptions` and
`RailwayProcessManagerOptions` (they only configured the pm env option
core now owns) — `@mastra/blaxel` and `@mastra/railway` get minor bumps,
the rest patch.
## Test plan
8 core unit cases pin the contract (ctor seeding, set-after-construct,
rotation, per-call precedence, unset, empty-env passthrough, the
executeCommand route, and snapshot/alias safety), plus a real-process
`LocalSandbox` test that spawns `printenv` and observes a value set
after construction, then rotated. Each of the 11 providers gains a
setEnv-after-construction conformance test pinning its real wire shape
(Docker `Env` array, Platform `init_exec` frame, Apple `--env` flags,
agentcore inline shell assignments, etc.). All provider suites green
(~800 tests).
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
This PR lets sandboxes manage environment variables while they run.
Sandbox values apply to later commands, can be updated or removed, and
per-command values take priority.
## Changes
- Add `env`, `setEnv()`, and `getEnv()` to `MastraSandbox`.
- Merge environments with this precedence: provider defaults < sandbox
environment < per-call environment.
- Apply runtime environment values to process spawns and
`executeCommand()`.
- Preserve the environment overlay across pause/resume and VM
replacement.
- Keep the overlay in memory instead of writing it to VM disk.
- Add optional `setEnv()` support to `WorkspaceSandbox`.
- Update process-manager and direct-exec providers to use the runtime
environment.
- Remove obsolete provider-specific process-manager environment options
and exports.
- Add documentation, unit tests, real-process tests, and provider
conformance tests.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: CalebBarnes <CalebBarnes@users.noreply.github.com>
Co-authored-by: Mastra Code (anthropic/claude-fable-5) <noreply@mastra.ai>
## Summary
Makes MC Web's sandbox fleet work directly with core `WorkspaceSandbox`
instances instead of a bespoke provider seam, and rolls the underlying
`derive()` capability out across the entire sandbox provider matrix.
### Core: `derive()` on the sandbox contract
- Adds an optional `derive(options?: SandboxDeriveOptions)` method to
the `WorkspaceSandbox` interface (`@mastra/core/workspace`). `derive()`
constructs an independent, unstarted sibling sandbox that inherits the
template's configuration (credentials, image/template, network,
defaults) while overriding `id`, `sandboxId` (provider-native reattach
hint), `env`, and `idleTimeoutMinutes`. It performs no I/O — starting
the derived sandbox provisions a fresh instance or reattaches to an
existing one by id.
- Implements `derive()` on `LocalSandbox` (core) and across the provider
matrix: Railway, E2B, Daytona, Modal, Docker, Blaxel, Apple Container,
and Vercel (microVM). Each maps `idleTimeoutMinutes` onto its native
lifetime knob (ms timeout, auto-stop minutes, duration string) or
ignores it when the provider has no idle teardown.
- `MockSandbox` in `@mastra/workspaces-test-utils` implements `derive()`
for unit tests.
### MC Web: factory consumes sandboxes, not providers
- `MastraFactory` now accepts `sandbox?: WorkspaceSandbox` — a
never-started template used to stamp per-project sandboxes via
`derive()`. Boot-time validation fails fast with an actionable error if
the supplied sandbox doesn't implement `derive()`; omitting the slot
boots with sandbox features disabled (reported via diagnostics).
- Deletes the `WebSandboxProvider` seam (`RailwaySandboxProvider`,
`LocalSandboxProvider`, and the materialization wrapper) — any sandbox
implementing `derive()` now works with GitHub projects, including
third-party implementations, with zero factory changes.
- The web entry constructs `RailwaySandbox` or `LocalSandbox` instances
from env (Railway auto-selected when `RAILWAY_API_TOKEN` is set; local
requires explicit `MASTRACODE_SANDBOX_PROVIDER=local` opt-in).
- Moves the sandbox fleet module (provisioning, repo materialization,
worktrees, token-scoped push, PR creation) out of `github/` into its own
`src/web/sandbox/` module — it was never GitHub-specific.
- Per-project checkout paths use nested `owner/name` layout, preventing
collisions between repos with the same name.
Also aligns the web e2e driver/tests with upstream contract changes
(`running` moved off the transcript reducer to the connection layer;
events now carry `MastraDBMessage`).
## Test plan
- [x] `derive()` unit tests for all 9 providers (constructs unstarted
sibling, inherits config, applies env/timeout overrides, reattach
semantics) — Railway 40, E2B 120, Daytona 115, Modal 38, Docker 75,
Blaxel 87, Apple Container 42, Vercel 66 tests passing
- [x] MC Web full suite: 601 unit + 90 node e2e + 471 MSW tests passing
- [x] Fleet + factory tests cover template validation, workdir layout,
per-project derive + reattach, sandbox budget, and graceful degradation
when no sandbox is configured
- [x] `tsc --noEmit` and prettier clean; `pnpm build:mastracode` green
- [x] Changesets included for `@mastra/core` and all 7 workspace
provider packages
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
This PR lets one sandbox template create separate, independent sandboxes
for different projects. It also simplifies the web app’s sandbox setup
and makes sandbox behavior consistent across providers.
## What changed
- Added optional `WorkspaceSandbox.derive()` support with configurable
IDs, environment variables, reattachment IDs, and idle timeouts.
- Implemented derivation across Local, Railway, E2B, Daytona, Modal,
Docker, Blaxel, Apple Container, Vercel MicroVM, and test utilities.
- Replaced web-only sandbox providers with template-based
`WorkspaceSandbox` configuration.
- Added validation and diagnostics for missing or unsupported sandbox
configuration.
- Moved sandbox fleet management from GitHub modules into
`src/web/sandbox/fleet.ts`.
- Added per-project `owner/name` checkout paths and Railway/Local
environment-based sandbox construction.
- Updated lifecycle, reattachment, budgeting, and teardown handling.
- Updated E2E run-state tracking to use connection-level events and
refreshed message event fixtures.
- Added release changesets and comprehensive derivation tests.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Mastra Code (anthropic/claude-fable-5) <noreply@mastra.ai>
## Summary
Adds a new workspace sandbox provider, **`VercelMicroVMSandbox`**,
backed by the official
[`@vercel/sandbox`](https://vercel.com/docs/vercel-sandbox) SDK. It runs
commands inside ephemeral Firecracker MicroVMs with a persistent
filesystem, an interactive shell, and long-running processes — the
capabilities requested in #16704.
This is **purely additive**. The existing `VercelSandbox` (Vercel
Functions executor, provider id `vercel`) is left untouched. To avoid
the name confusion the issue explicitly warns about, the new class is
`VercelMicroVMSandbox` (provider id `vercel-microvm`), and the docs
cross-reference the two so users can tell them apart.
It plugs into the standard workspace sandbox contract like the
e2b/daytona/modal providers:
- `executeCommand` with streaming stdout/stderr, cwd/env, timeouts, and
abort handling
- Background process management (detached `runCommand` + streamed
`logs()`, `wait()`, `kill()`)
- `getInfo()` (runtime, timeout, exposed port domains) and
`getInstructions()`
- Credentials via Vercel OIDC by default, or an explicit `token` /
`teamId` / `projectId` (with env-var fallbacks)
- An editor provider descriptor (`vercelMicroVMSandboxProvider`) with a
config schema
`sendStdin()` throws a clear "not supported" error because the SDK has
no stdin channel.
## What's included
- `workspaces/vercel/src/microvm/index.ts` — `VercelMicroVMSandbox`
- `workspaces/vercel/src/microvm/process-manager.ts` —
`VercelMicroVMProcessManager` + handle
- `workspaces/vercel/src/microvm-provider.ts` — editor descriptor
- Updated `src/index.ts` exports and `@vercel/sandbox` dependency
- Reference docs page + sidebar entry, plus a disambiguation note on the
existing provider page
- Changeset (minor bump for `@mastra/vercel`)
## Test plan
- `pnpm --filter ./workspaces/vercel build` — clean (esm/cjs/dts)
- `pnpm --filter ./workspaces/vercel lint` — no errors
- `pnpm --filter ./workspaces/vercel test:unit` — 62/62 pass
- 18 sandbox unit tests (mocked SDK), incl. a **Workspace-tool
conformance test** that wires the sandbox into a real `Workspace` and
asserts `execute_command` / `get_process_output` / `kill_process`
resolve
- 6 process-manager tests (detached spawn, streaming, exit codes, kill,
env merge, stdin-unsupported)
- `src/microvm/index.integration.test.ts` — real-SDK tests gated on
`VERCEL_OIDC_TOKEN`/`VERCEL_TOKEN`; skip cleanly without credentials.
Not run in CI here due to no Vercel credentials in the environment.
Closes#16704
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
This PR adds a new option to run a tiny, full Linux "mini-computer" (a
Firecracker MicroVM) for each workspace session on Vercel, so commands
can run with a persistent filesystem, background processes, exposed
ports, and sudo—unlike the existing serverless-based Vercel provider.
---
## Overview
Implements VercelMicroVMSandbox (provider id: vercel-microvm), a Mastra
workspace sandbox that runs ephemeral Firecracker MicroVMs via the
official `@vercel/sandbox` SDK. It is explicitly separate from the
existing VercelSandbox (serverless functions) and offers a persistent
in-session filesystem, sudo access, exposed ports, and background
process support.
## Implementation Details
- VercelMicroVMSandbox
- MastraSandbox implementation with start/stop/destroy lifecycle.
- Configurable runtime ('node24' | 'node22' | 'node26' | 'python3.13'),
timeout, vCPUs, ports, env, metadata, and optional instructions
override.
- Credentials: defaults to Vercel OIDC (VERCEL_OIDC_TOKEN) or accepts
explicit token/teamId/projectId via constructor or env; enforces
all-or-nothing explicit credentials.
- executeCommand: merged env and cwd support, stdout/stderr streaming,
abort signal handling, per-call timeout (returns exit code 124 +
timedOut), aborts in-flight runCommand on timeout, and cleans
timers/listeners.
- getInfo: reports status, runtime, timeout, vCPU, ports and best-effort
port→domain mapping.
- getInstructions: default human-readable instructions with string or
function override support.
- VercelMicroVMProcessManager
- spawn(): runs detached commands (wrapped via sh -c), merges env,
streams logs into a ProcessHandle.
- ProcessHandle: wait() with optional timeout (kills on timeout), kill()
(defaults SIGKILL), wait drains logs before resolving; sendStdin()
throws a clear "not supported" error.
- list(): returns tracked processes with running status inferred from
exitCode.
- Editor integration
- vercelMicroVMSandboxProvider descriptor with JSON-schema for
serializable config (token, teamId, projectId, runtime, timeout, vcpus,
ports, env).
- createSandbox factory wiring of config to VercelMicroVMSandbox.
## Testing
- Unit tests: 62/62 passing (includes 18 sandbox tests covering
lifecycle, credential resolution, executeCommand behavior, timeout
handling, env/cwd merging, process manager behavior, and Workspace
conformance).
- Integration tests: present and gated on VERCEL_OIDC_TOKEN or the
VERCEL_TOKEN/VERCEL_TEAM_ID/VERCEL_PROJECT_ID triple; skipped cleanly
without credentials.
- workspaces/vercel: build and lint pass.
## Documentation
- New reference page: workspace/vercel-microvm-sandbox.mdx
(installation, auth, usage, params, limitations,
resource/port/filesystem/timeout limits).
- Updated vercel.mdx with a disambiguation note linking to the MicroVM
provider.
- Sidebar entry added for discoverability.
## Dependencies & Exports
- Adds production dependency `@vercel/sandbox`@2.0.2.
- Public exports added: VercelMicroVMSandbox (and types),
VercelMicroVMProcessManager, vercelMicroVMSandboxProvider.
- Changeset: minor bump for `@mastra/vercel`; closes `#16704`.
<!-- review_stack_entry_start -->
[](https://app.coderabbit.ai/change-stack/mastra-ai/mastra/pull/17332?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)
<!-- review_stack_entry_end -->
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Mastra Code (anthropic/claude-opus-4-8) <noreply@mastra.ai>