# 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:

```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

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`:

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

### 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 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.

```bash
# 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`](https://mastra.ai/docs/observability/tracing/exporters/mastra-platform), set `MASTRA_PROJECT_ID` and `MASTRA_PLATFORM_ACCESS_TOKEN` per environment so traces route to the matching platform project.