# 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 prompts you to log in. It stores your credentials locally and any subsequent CLI commands 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.

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.

## CI/CD

Automate deployments from GitHub Actions, GitLab CI, or any CI provider. After your first interactive deploy, CI/CD needs just two things: an API token and the `.mastra-project.json` file committed to your repository.

### Create an API token

1. Run the following command locally:

   ```bash
   mastra auth tokens create ci-deploy
   ```

   The CLI prints the token once. Copy it immediately — it cannot be retrieved again.

2. Add the token as a secret in your CI provider. In GitHub Actions, go to **Settings → Secrets and variables → Actions** and create a secret named `MASTRA_API_TOKEN`.

3. Ensure your `.mastra-project.json` file is committed to the repository. The CLI reads the `organizationId` and `projectId` from this file to target the correct project during CI deploys.

### The `--yes` flag

Pass `--yes` (or `-y`) to skip all confirmation prompts. Without it, the CLI waits for interactive input and your CI job hangs.

```bash
mastra server deploy --yes
```

### GitHub Actions

The following workflow deploys on every push to `main`:

```yaml
name: Deploy to Mastra platform

on:
  push:
    branches: [main]
    paths: ['src/mastra/**']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'
      - name: Install dependencies
        run: npm install
      - name: Deploy to Mastra platform
        run: npx mastra server deploy --yes
        env:
          MASTRA_API_TOKEN: ${{ secrets.MASTRA_API_TOKEN }}
```

Adjust the `paths` filter and `working-directory` if your Mastra project is in a subdirectory (e.g. a monorepo).

> **Note:** For Studio deploys, replace `mastra server deploy` with `mastra studio deploy`. The flags and environment variables are the same.

### GitLab CI

The following pipeline deploys on pushes to `main`:

```yaml
deploy:
  image: node:22
  stage: deploy
  only:
    - main
  before_script:
    - npm install
  script:
    - npx mastra server deploy --yes
```

Add `MASTRA_API_TOKEN` as a CI/CD variable in **Settings → CI/CD → Variables**.

### Other CI providers

Any CI system that runs Node.js and shell commands works with Mastra:

1. Install dependencies.
2. Set `MASTRA_API_TOKEN` as an environment variable.
3. Run `mastra server deploy --yes` (or `mastra studio deploy --yes`).

### Verify the deploy

After the workflow completes, verify the deployment by hitting the health endpoint:

```bash
curl -f https://<your-project>.server.mastra.cloud/health
```

Or check the agents endpoint, which returns a JSON list of your agents:

```bash
curl -f https://<your-project>.server.mastra.cloud/api/agents
```

The following example adds a verification step to a GitHub Actions workflow:

```yaml
- name: Verify deployment
  run: |
    sleep 30
    curl -f https://<your-project>.server.mastra.cloud/health
```

### Override project config with environment variables

The CLI reads `organizationId` and `projectId` from `.mastra-project.json` by default. To override these values (e.g. deploying to a different project from the same repository), set the following environment variables:

| Variable            | Description                                                |
| ------------------- | ---------------------------------------------------------- |
| `MASTRA_ORG_ID`     | Overrides the organization ID from `.mastra-project.json`. |
| `MASTRA_PROJECT_ID` | Overrides the project ID from `.mastra-project.json`.      |

## Related

- [CLI reference: `mastra server deploy`](https://mastra.ai/reference/cli/mastra)
- [CLI reference: `mastra server pause`](https://mastra.ai/reference/cli/mastra)
- [CLI reference: `mastra server restart`](https://mastra.ai/reference/cli/mastra)
- [CLI reference: `mastra studio deploy`](https://mastra.ai/reference/cli/mastra)
- [CLI reference: `mastra auth tokens`](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)