## 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>