0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00
mastra/deployers/sandbox
History 2026-11-12 21:12:29 +00:00
..
src feat(platform-workspace): port URLs on PlatformSandbox (#29227) 2026-11-02 16:28:00 -07:00
CHANGELOG.md chore: version - exit prerelease mode 2026-11-12 21:12:29 +00:00
lint-staged.config.js refactor(lint): replace ESLint with type-aware oxlint (#27476) 2026-10-18 10:38:35 -07:00
package.json chore: version - exit prerelease mode 2026-11-12 21:12:29 +00:00
README.md chore(*): Update/unify/add READMEs (#22858) 2026-09-02 14:36:59 +02:00
tsconfig.build.json feat(deployer-sandbox): deploy Mastra servers to workspace sandboxes (Vercel, E2B, Daytona) (#19577) 2026-07-17 12:58:48 +02:00
tsconfig.json feat(deployer-sandbox): enforce worker resource limits (#21273) 2026-08-11 11:45:19 -07:00
tsdown.config.ts chore: migrate package builds to tsdown (#19829) 2026-07-28 12:32:21 +02:00
turbo.json chore: migrate package builds to tsdown (#19829) 2026-07-28 12:32:21 +02:00
vitest.config.ts feat(deployer-sandbox): deploy Mastra servers to workspace sandboxes (Vercel, E2B, Daytona) (#19577) 2026-07-17 12:58:48 +02:00
vitest.integration.config.ts feat(deployer-sandbox): enforce worker resource limits (#21273) 2026-08-11 11:45:19 -07:00

@mastra/deployer-sandbox

Deploy a full Mastra server or a non-HTTP worker into a workspace sandbox. It is intended for ephemeral previews, CI smoke deployments, isolated jobs, agent-built application verification, and untrusted tenant environments rather than permanent production hosting.

Installation

npm install @mastra/deployer-sandbox

Install a workspace sandbox provider separately. The examples below use @mastra/vercel.

Usage

// src/mastra/index.ts
import { Mastra } from '@mastra/core/mastra';
import { SandboxDeployer } from '@mastra/deployer-sandbox';
import { VercelSandbox } from '@mastra/vercel';

const deployer = new SandboxDeployer({
  sandbox: new VercelSandbox({
    sandboxName: 'my-preview',
    timeout: 2_400_000,
    ports: [4111],
  }),
});

export const mastra = new Mastra({ deployer });

Running mastra build bundles the project and deploys it into the sandbox, then prints the API and Studio URLs.

Documentation

Server deployments require a WorkspaceSandbox implementation with command execution and networking support. The sandbox name is the deployment identity, so subsequent processes can reconnect to the same deployment with the server-only @mastra/deployer-sandbox/client export:

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

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

console.log(deployment.status, deployment.url);
await deployment.stop(); // Resumable snapshot stop
await deployment.destroy(); // Permanent deletion

Use deployToSandbox() for one-shot programmatic deployments of a prebuilt .mastra/output directory. Pass wake: true to getDeployment() when a stopped server should be resumed and health-checked before it is returned.

The package also supports non-HTTP workers through deployWorkerToSandbox(). Workers only require command execution and can receive bounded input through stdin or a staged file. Their handles expose status checks, separate offset-based stdout and stderr reads, cancellation, snapshot stop, relaunch, and permanent destruction. attachWorkerDeployment() reconstructs a handle from persisted sandbox and execution IDs after a supervisor restart.

Dependency installation is serialized and cached from the artifact's package manifest and lockfile. Worker cancellation sends TERM before KILL when necessary, while server health checks surface startup logs when a deployment fails to become ready.

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.