Skip to main content

Deploy to Mastra platform

Mastra Server deploys your application as a production API server on cloud infrastructure. You get a stable API endpoint, environment variable management, custom domain support, and deploy history out of the box.

tip

This guide covers deploying the standalone server generated by mastra build. If you need to deploy Studio to the Mastra platform, see Studio deployment instead.

Before you begin
Direct link to Before you begin

You'll need a Mastra application and a Mastra platform account.

warning

Mastra platform uses an ephemeral filesystem, so any storage you configure (including observability storage) must be hosted externally. If you're using LibSQLStore with a file URL, switch to a remotely hosted database.

Installation
Direct link to Installation

Install the mastra CLI globally:

npm install -g mastra

Deploy
Direct link to Deploy

  1. Deploy your project:

    mastra server deploy

    If you're not already authenticated, the CLI will prompt you to log in. It'll store your credentials locally and any subsequent CLI commands will use these credentials.

    The command runs mastra build, uploads the artifact, builds a Docker image, and deploys it to Railway. On first deploy, the CLI creates a .mastra-project.json file linking your local project to the platform. Commit this file so subsequent deploys and CI/CD target the same project.

    note

    Environment variables from .env, .env.local, and .env.production are included automatically. On the first deploy, these seed the project if no env vars are set yet. After that, manage env vars through the web dashboard. Review and sanitize these files before first deploy to avoid uploading development-only or personal secrets.

    See the CLI reference for the full list of flags and CI/CD usage.

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

Deploy lifecycle
Direct link to Deploy lifecycle

A deploy transitions through queued → uploading → building → deploying → running (or failed, cancelled, crashed, or stopped). Only one build runs per project at a time. If multiple deploys queue up, only the latest proceeds and the rest are cancelled. Builds running longer than 15 minutes are automatically failed. The first deploy provisions Railway infrastructure and seeds environment variables from your local .env. Your server URL remains stable across deploys.

On this page