Deploying

note

The Agent Builder is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. Contact sales for more information.

Production deployments swap the local primitives in the Quickstart for cloud-backed equivalents. The shape of the Mastra and MastraEditor config doesn't change — only the providers behind it.

What a production deployment needs

1. EE license — a valid MASTRA_EE_LICENSE so the server will start with the Builder enabled.
2. Hosted storage — a shared store for agents, skills, runs, and memory.
3. Shared workspace filesystem — survives across instances; local is single-node only.
4. Cloud sandbox — runs agent commands safely; local is unsafe in shared environments.
5. Auth and RBAC — gates the Builder UI and /agent-builder/* routes.
6. Public base URL for channels — Slack and other channel providers need a reachable URL.

EE license

Set MASTRA_EE_LICENSE in the deployment environment. The server refuses to start when builder.enabled is truthy without a valid license. Treat the license key as a secret.

Storage

Replace the file-backed LibSQL store with a hosted backend. LibSQL Cloud, PostgreSQL, and any other Mastra storage adapter all work.

src/mastra/index.ts

import { Mastra } from '@mastra/core/mastra'
import { LibSQLStore } from '@mastra/libsql'

new Mastra({
  storage: new LibSQLStore({
    url: process.env.DATABASE_URL!,
    authToken: process.env.DATABASE_AUTH_TOKEN,
  }),
})

Workspace filesystem and sandbox

local filesystem works only on the node that owns the directory. For multi-instance deployments, register cloud filesystem and sandbox providers on MastraEditor and reference them by id in the inline workspace config.

npm

npm install @mastra/s3 @mastra/e2b

pnpm

pnpm add @mastra/s3 @mastra/e2b

Yarn

yarn add @mastra/s3 @mastra/e2b

Bun

bun add @mastra/s3 @mastra/e2b

src/mastra/index.ts

import { Mastra } from '@mastra/core/mastra'
import { MastraEditor } from '@mastra/editor'
import { s3FilesystemProvider } from '@mastra/s3'
import { e2bSandboxProvider } from '@mastra/e2b'

new Mastra({
  editor: new MastraEditor({
    filesystems: { [s3FilesystemProvider.id]: s3FilesystemProvider },
    sandboxes: { [e2bSandboxProvider.id]: e2bSandboxProvider },
    builder: {
      enabled: true,
      configuration: {
        agent: {
          workspace: {
            type: 'inline',
            config: {
              name: 'builder-workspace',
              filesystem: {
                provider: s3FilesystemProvider.id,
                config: {
                  bucket: process.env.S3_BUCKET!,
                  region: process.env.S3_REGION!,
                },
              },
              sandbox: {
                provider: e2bSandboxProvider.id,
                config: { apiKey: process.env.E2B_API_KEY! },
              },
            },
          },
        },
      },
    },
  }),
})

S3Filesystem uses the default AWS credential chain (environment variables, ~/.aws config, IAM roles, EC2 instance profile). For long-running deployments, use a credential provider function so credentials refresh automatically.

DockerSandbox and VercelSandbox are alternative cloud sandbox providers — pick whichever matches your runtime.

warning

A local sandbox can't run commands safely in a shared environment. Always register a cloud sandbox provider and reference it in the workspace config before deploying.

Auth and RBAC

A production deployment without authentication exposes the Builder to the public internet. Register a Mastra.server.auth provider (for example, WorkOS or your own provider) and a Mastra.server.rbac provider to gate access.

See Access control for the required role permissions and a WorkOS quickstart.

Public URL for channels

Slack needs to reach your server through a public URL. Pass baseUrl to SlackProvider with the deployed URL (no trailing slash). See Channels for the full setup.

Related

• Access control — auth and RBAC setup.
• Channels — Slack baseUrl and channel-specific setup.