Deploy to Mastra platform

mastra deploy is the single command for shipping a Mastra application to the Mastra platform. One command builds your project, validates it before anything ships, creates the platform project and environment on your first run, deploys, streams build logs, and prints your public URL once the deploy is serving traffic.

mastra deploy

note

This page covers the unified deploy flow. The earlier split commands, mastra server deploy and mastra studio deploy, still work but mastra deploy is the recommended path.

Before you begin

You'll need a Mastra application and a Mastra platform account. If you're not authenticated, the CLI prompts you to log in on first use.

A local .env file is optional. Environment variables stored on the platform are used as-is at deploy time, and managed resources like hosted databases inject their own variables. Pass --env-file only when you want to layer local values on top.

Your first deploy

1. From your project directory, run:

   mastra deploy

   On the first run the CLI prompts you to create the platform project (named after your package.json) and the production environment. Accept the prompts, or pass --yes to accept defaults without confirmation.

2. The CLI runs a preflight check before anything ships. Storage that would fall back to a local file path blocks the deploy, because local files don't survive on the platform's ephemeral filesystem:

   [LOCAL_STORAGE_PATH] file:./mastra.db will be used at runtime because TURSO_DATABASE_URL is not set

   Attach a hosted database that provides the missing variables:

   mastra env db create --kind turso

   Provisioning takes a few seconds. The database's connection variables are injected into your deploys automatically, with nothing to copy into an .env file.

   note

   If preflight reports a hard-coded local path instead (Build contains a host-local storage URL), guard it with an environment variable first so the file is only used during local development:

   src/mastra/index.ts

   new LibSQLStore({
     // Uses the hosted database when deployed, a local file during development
     url: process.env.TURSO_DATABASE_URL ?? 'file:./mastra.db',
     authToken: process.env.TURSO_AUTH_TOKEN,
   })

3. Run mastra deploy again. Preflight passes, the build uploads, and the CLI streams build logs until the deploy is live. Expect the full build and deploy to take between 30 seconds and a few minutes. The success message prints only when the new version is serving traffic.

4. Verify your deployment at the URL printed by the CLI. Append /api/agents to confirm it returns a JSON list of your agents.

   warning

   Set up authentication before exposing your endpoints publicly.

The first deploy writes a .mastra-project.json file linking your directory to the platform project. Commit it so later deploys, CI runs, and mastra env commands target the same project without extra flags.

Deploy to another environment

mastra deploy targets the production environment by default. Pass --env to target a different one. If the environment doesn't exist yet, the CLI offers to create it:

mastra deploy --env staging

Each environment gets its own URL, its own environment variables, and optionally its own hosted database. See Environments for the full model.

Choose a region

Pass --region when a deploy creates a new environment to control where it runs. Use the us or eu shorthand:

mastra deploy --env production --region eu

The region is fixed when the environment is created. Databases attached to an environment are placed near that environment's region automatically.

Preflight checks

Preflight validates the built output before anything ships, and only flags issues in your own code:

• Local storage paths: A hard block. File-backed storage (for example file:./mastra.db) is lost on every deploy. Preflight passes when the path is guarded by an environment variable that is set locally, stored on the platform, or provided by a managed database:

  src/mastra/storage.ts

  import { LibSQLStore } from '@mastra/libsql'
  
  export const storage = new LibSQLStore({
    // Uses the hosted database when deployed, a local file during development
    url: process.env.TURSO_DATABASE_URL ?? 'file:./mastra.db',
    authToken: process.env.TURSO_AUTH_TOKEN,
  })

• Missing environment variables: A warning for variables your code reads but no source provides. Variables referenced only by library code are excluded.

The recommended response to a preflight block is to fix the cause, usually by attaching a hosted database or storing the variable on the platform. --skip-preflight exists as an escape hatch but skips the checks that prevent broken deploys.

Run the checks without deploying:

mastra lint --preflight

mastra lint only sees your local env files. Variables stored on the platform or injected by managed databases aren't visible to it, so a deploy can pass preflight where lint still reports an error.

Environment variables

Deploys resolve environment variables from three sources:

• Managed variables: Injected by platform resources like hosted databases (for example TURSO_DATABASE_URL). 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.

mastra deploy --env staging --env-file .env.staging

To change variables on a running service without a redeploy, update them in the dashboard and run mastra env restart.

Project resolution

Every deploy resolves its target project in this order:

1. The MASTRA_PROJECT_ID environment variable
2. The --project <name|slug|id> flag
3. The .mastra-project.json file in the current directory

In CI, set MASTRA_PROJECT_ID and MASTRA_API_TOKEN and pass --yes:

mastra deploy --env production --yes

Related

• Environments
• Hosted databases
• mastra deploy CLI reference
• Configuration