# 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](https://mastra.ai/docs/studio/deployment) instead.

## Before you begin

You'll need a [Mastra application](https://mastra.ai/guides/getting-started/quickstart) and a [Mastra platform](https://projects.mastra.ai) 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](https://mastra.ai/reference/storage/libsql) with a file URL, switch to a remotely hosted database.

## Installation

Install the `mastra` CLI globally:

**npm**:

```bash
npm install -g mastra
```

**pnpm**:

```bash
pnpm add -g mastra
```

**Yarn**:

```bash
yarn global add mastra
```

**Bun**:

```bash
bun add --global mastra
```

## Deploy

1. Deploy your project:

   ```bash
   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](https://mastra.ai/reference/cli/mastra) 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](https://mastra.ai/docs/server/auth) before exposing your endpoints publicly.

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

## Related

- [CLI reference](https://mastra.ai/reference/cli/mastra)
- [Mastra platform overview](https://mastra.ai/docs/mastra-platform/overview)
- [Studio deployment](https://mastra.ai/docs/studio/deployment)
- [Deployment overview](https://mastra.ai/docs/deployment/overview)