# 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](https://mastra.ai/reference/storage/libsql) and a file URL, switch to a remotely hosted database because Mastra platform uses an ephemeral filesystem.

## Quickstart

1. Follow the [get started guide](https://mastra.ai/docs) to create your first Mastra project.

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

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

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](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

- [`mastra server deploy`](https://mastra.ai/reference/cli/mastra)
- [`mastra server pause`](https://mastra.ai/reference/cli/mastra)
- [`mastra server restart`](https://mastra.ai/reference/cli/mastra)
- [`mastra studio deploy`](https://mastra.ai/reference/cli/mastra)
- [`mastra auth tokens`](https://mastra.ai/reference/cli/mastra)