Environments
Every platform project contains one or more environments. An environment is an isolated deployment target with its own URL, its own environment variables, its own deploy history, and optionally its own hosted database. Use environments to run production, staging, and preview versions of the same codebase inside a single project.
Your first mastra deploy creates the production environment. Create more with the CLI or by deploying to a name that doesn't exist yet.
Create an environmentDirect link to Create an environment
Create an environment explicitly:
mastra env create staging
Or let a deploy create it, which prompts for confirmation:
mastra deploy --env staging
mastra env create defaults to the staging type. Pass --type to set staging or preview explicitly, and --region to choose where the environment runs:
mastra env create eu-preview --type preview --region eu
Each project has a single production environment, created by your first deploy. The region is fixed at creation. Databases attached to an environment are placed near the environment's region automatically. The number of environments per project depends on your plan.
List environmentsDirect link to List environments
mastra env list
The output shows each environment's name, region, active deploy status, and the managed environment variables injected by attached databases. Pass --json for machine-readable output in CI.
All mastra env commands resolve their project from MASTRA_PROJECT_ID, the --project flag, or the .mastra-project.json file written by your first deploy, in that order. Run them from your project directory and you never need to name the project.
Environment variablesDirect link to Environment variables
An environment resolves its variables from three scopes:
- Managed variables: Injected by attached hosted databases (for example
TURSO_DATABASE_URL). The platform defines these, and you can't edit them. - Environment-scoped variables: Stored on one environment through the dashboard. Use these for values that differ between environments, like API keys for staging and production services.
- Project-scoped variables: Stored on the project and shared by all environments.
Environment-scoped and project-scoped variables together are the stored variables described on the Deploy page.
Variables are applied when a deploy starts. To apply changed variables to a running service without a full redeploy:
mastra env restart staging
To see the full set an environment's deploys actually run with — environment-scoped and project-scoped values merged, with managed variables listed by name — pull them into a local env file:
mastra env vars pull staging --output .env.staging
Managed variable values are injected at deploy time and never written to the file; they appear as name-only comments.
Environment variables don't override managed database variables. To point an environment at a different database, attach an environment-scoped database instead.
Deploy historyDirect link to Deploy history
List deploys across all environments, or filter to one:
mastra env deploys
mastra env deploys staging
Each row shows the deploy status, environment, timestamp, and which deploy is currently active. A deploy transitions through queued → uploading → building → deploying → running, and the platform reports running only when the new version is serving traffic.
Isolate an environment's dataDirect link to Isolate an environment's data
By default a hosted database attached to the project is shared by all environments. To isolate production data from staging data, attach a separate database to each environment instead:
mastra env db create production --kind turso --name my-project-production-db
mastra env db create staging --kind turso --name my-project-staging-db
Each environment then reads and writes only its own database.
An environment can only use one database per provider. If the project already has a shared project-scoped database of the same provider, attaching an environment-scoped one is rejected with a variable name conflict — delete the shared database with mastra env db delete first. Deleting a database destroys it with the provider along with all of its data, so export anything you need to keep. See Hosted databases for the full scoping model.
Delete an environmentDirect link to Delete an environment
mastra env delete staging
The CLI asks for confirmation before deleting. Deleting an environment removes its deploys and stored variables.