Configuration

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

This page explains both mechanisms.

Project config

The .mastra-project.json file is auto-generated on your first mastra deploy. It links your local project to a platform project. The GitHub integration writes the same file into linked repositories.

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"
}

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

A local env file is optional. mastra deploy resolves variables from three sources:

• Managed variables: Injected by platform resources like hosted databases. The platform defines these, and you can't edit them.
• Stored variables: Saved on the project or environment through the dashboard. Used as-is on every deploy with no local file needed.
• Local env files: An explicit --env-file, or ambient .env and .env.local files, layered on top at deploy time. Variables from .env.local override those in .env.

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

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

Review and sanitize local env files before deploying to avoid uploading development-only or personal secrets.

Observability

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

Variable	Description
MASTRA_PLATFORM_ACCESS_TOKEN	Org-scoped access token. The CLI writes this during observability provisioning and uses it for platform authentication.
MASTRA_PROJECT_ID	UUID 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_ENDPOINT	Optional observability endpoint override. This is only set automatically for local platform development. Defaults to https://observability.mastra.ai.
MASTRA_ORG_ID	Overrides 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

A single project runs the same codebase across multiple environments, such as production and staging. Each environment has its own URL, its own stored variables, and its own deploy history. One .mastra-project.json file covers all of them:

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

note

Earlier platform versions required one project per environment. Environments replace that pattern, so keep one project and deploy to named environments instead.