Mastra Platform Deployment Configuration Guide

Trust: ★★★☆☆ (0.90) · 0 validations · factual

Published: 2026-05-09 · Source: crawler_authoritative

Tình huống

Developers deploying applications to Mastra platform using CLI and managing multiple deployment environments (staging, production)

Insight

Mastra platform uses two configuration mechanisms: (1) .mastra-project.json - auto-generated on first Studio/Server deploy, contains projectId (UUID), projectName (display label), and organizationId (scopes all deploys, API keys, resources); (2) Environment variables read from .env and .env.local files where .env.local overrides .env. Studio bundles env vars into deploy artifact requiring redeploy to update; Server seeds env vars on first deploy then manages them per-project via dashboard/API. Key constraint: one platform project maps to single deployed instance with one set of env vars - no built-in staging vs production slots. For CloudExporter tracing, must set MASTRA_PROJECT_ID and MASTRA_CLOUD_ACCESS_TOKEN per environment so traces route to matching Studio project.

Hành động

Commit .mastra-project.json to version control so subsequent CI deploys target correct project. Use —env-file flag to pin specific env file: ‘mastra studio deploy —env-file .env.production —yes’. For multiple environments, create one project per environment and override .mastra-project.json per deploy, or set MASTRA_PROJECT_ID environment variable per environment for subsequent deploys. Each project has independent Studio URL and observability data.

Điều kiện áp dụng

Applies to developers using Mastra CLI for Studio and Server deployments; does not apply to Shopee, TikTok Shop, Lazada, or general e-commerce contexts

---

Nội dung gốc (Original)

Configuration

When you deploy to the Mastra platform, the CLI generates a .mastra-project.json config file and reads environment variables from your local .env files.

This page explains both mechanisms and how they differ between Studio and Server deployments.

Project config

The .mastra-project.json file is auto-generated on your first Studio or Server deploy. It links your local project to a platform project.

Commit it to your version control so that subsequent deploys (including from CI) target the correct project.

Your file will look something like this:

{
  "projectId": "06daaac4-89b1-40f0-9e3f-0993e039a627",
  "projectName": "my-project",
  "organizationId": "org_01KNA5YSP52SX4M6YVSXC2MAHP"
}

Field	Description
projectId	UUID for the project. Assigned when the project is created.
projectName	Human-readable project name. Used as a display label in the dashboard and CLI output.
organizationId	The organization that owns the project. All deploys, API keys, and resources are scoped to this org.

Environment variables

The CLI reads from .env and .env.local files in your project directory during deploy. Variables from .env.local override those in .env.

You can set environment variables like so:

• Studio: Environment variables are read from your local .env files and bundled into the deploy artifact. To update them, redeploy.
• Server: On the first deploy, the CLI automatically seeds environment variables from your local .env files. After that, manage them per-project through the dashboard or API.

To pin the deploy to a specific env file (instead of relying on the default selection), pass --env-file:

mastra studio deploy --env-file .env.production --yes

Multiple environments

A platform project maps to a single deployed instance with one set of env vars. There is no built-in concept of staging vs production slots within a project. To run the same codebase across multiple environments, create one project per environment and override .mastra-project.json per deploy.

# Create-and-deploy each environment (first time only)
mastra studio deploy --project "my-app-staging" --env-file .env.staging --yes
mastra studio deploy --project "my-app-production" --env-file .env.production --yes
 
# Subsequent deploys — set MASTRA_PROJECT_ID per environment
MASTRA_PROJECT_ID="<staging-id>" mastra studio deploy --env-file .env.staging --yes
MASTRA_PROJECT_ID="<production-id>" mastra studio deploy --env-file .env.production --yes

Each project has its own Studio URL and its own observability data. When using CloudExporter, set MASTRA_PROJECT_ID and MASTRA_CLOUD_ACCESS_TOKEN per environment so traces route to the matching Studio project.

Liên kết

• Nền tảng: Mastra
• Nguồn: https://mastra.ai/docs/mastra-platform/configuration