Skip to main content

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
Direct link to 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:

.mastra-project.json
{
  "projectId": "06daaac4-89b1-40f0-9e3f-0993e039a627",
  "projectName": "my-project",
  "organizationId": "org_01KNA5YSP52SX4M6YVSXC2MAHP"
}
FieldDescription
projectIdUUID for the project. Assigned when the project is created.
projectNameHuman-readable project name. Used as a display label in the dashboard and CLI output.
organizationIdThe organization that owns the project. All deploys, API keys, and resources are scoped to this org.

Environment variables
Direct link to 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

Observability
Direct link to Observability

The following environment variables configure the Observability product on the Mastra platform.

VariableDescription
MASTRA_PLATFORM_ACCESS_TOKENOrg-scoped access token. The CLI writes this during observability provisioning and uses it for platform authentication.
MASTRA_PROJECT_IDUUID of the platform project. MastraPlatformExporter uses it to link observability data to the platform project. Studio and Server deploys read the project ID from .mastra-project.json.
MASTRA_PLATFORM_OBSERVABILITY_ENDPOINTOptional observability endpoint override. This is only set automatically for local platform development. Defaults to https://observability.mastra.ai.
MASTRA_ORG_IDOverrides the active organization for CLI commands. You can also set it with the --org flag on supported commands.

MastraPlatformExporter reads MASTRA_PLATFORM_ACCESS_TOKEN to authenticate platform export.

Multiple environments
Direct link to Multiple environments

A platform project maps to a single deployed instance with one set of env vars. Platform projects don't have built-in staging vs production slots. To run the same codebase across multiple environments, create one project per environment and use the matching .mastra-project.json file for each deploy.

# Create and deploy each environment for the first time.
mastra studio deploy --project "my-app-staging" --env-file .env.staging --yes
mastra studio deploy --project "my-app-production" --env-file .env.production --yes

# For subsequent deploys, restore the matching .mastra-project.json file before deploying.
cp .mastra-project.staging.json .mastra-project.json
mastra studio deploy --env-file .env.staging --yes

cp .mastra-project.production.json .mastra-project.json
mastra studio deploy --env-file .env.production --yes

Each project has its own Studio URL and can send observability data to the Mastra platform. When using MastraPlatformExporter, set MASTRA_PROJECT_ID and MASTRA_PLATFORM_ACCESS_TOKEN per environment so traces route to the matching platform project.

On this page