Skip to main content

Server on Mastra platform

Server on Mastra platform is a production deployment target that runs your Mastra application as an API server. Use it when you want the platform to build, deploy, host, and manage your Mastra server.

You get a stable API endpoint, environment variable management, custom domain support, and deploy history out of the box.

note

Server deploy provisions hosted storage automatically. If you override storage with LibSQLStore and a file URL, switch to a remotely hosted database because Mastra platform uses an ephemeral filesystem.

Quickstart
Direct link to Quickstart

  1. Follow the get started guide to create your first Mastra project.

  2. Install the mastra CLI globally:

    npm install -g mastra

  3. Deploy your project:

    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 for the full list of flags.

  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.

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.

CI/CD
Direct link to 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
Direct link to Create an API token

  1. Run the following command locally:

    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
Direct link to 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.

mastra server deploy --yes

GitHub Actions
Direct link to GitHub Actions

The following workflow deploys on every push to main:

.github/workflows/deploy-mastra.yml
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
Direct link to GitLab CI

The following pipeline deploys on pushes to main:

.gitlab-ci.yml
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
Direct link to 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
Direct link to Verify the deploy

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

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

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

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

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

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

Override project config with environment variables
Direct link to 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:

VariableDescription
MASTRA_ORG_IDOverrides the organization ID from .mastra-project.json.
MASTRA_PROJECT_IDOverrides the project ID from .mastra-project.json.
On this page