> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# 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`](https://mastra.ai/docs/mastra-platform/deploy). It links your local project to a platform project. The [GitHub integration](https://mastra.ai/docs/mastra-platform/github) 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:

```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`](https://mastra.ai/docs/mastra-platform/deploy) resolves variables from three sources:

- **Managed variables**: Injected by platform resources like [hosted databases](https://mastra.ai/docs/mastra-platform/database). 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**: Deployments layer an explicit `--env-file` or the ambient `.env` and `.env.local` files on top. 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`:

```bash
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](https://mastra.ai/docs/mastra-platform/environments), such as `production` and `staging`. Each environment has its own URL and its own stored variables, plus its own deploy history. One `.mastra-project.json` file covers all of them:

```bash
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 environments instead.