Migrate from Mastra Cloud to Mastra platform

The Mastra platform replaces Mastra Cloud with separate Studio and Server products, CLI-driven deploys, and a new observability system. This guide walks you through each step.

What changed

Area	Mastra Cloud	Mastra platform
Products	Single project	Separate Studio and Server
Deploys	Auto-deploy on push	CLI-driven (mastra studio deploy, mastra server deploy)
Project creation	GitHub import	CLI creates projects on first deploy
Storage	Managed LibSQL (Cloud Store) or bring your own	Bring your own hosted database
Observability	Logger-based	Observability class with exporters
Env vars	Set during project setup	Seeded from .env on first deploy, managed in dashboard after
URLs	Single URL	Separate Studio and Server URLs

Before you start

1. Install or update the CLI:

   npm

   npm install -g mastra@latest

   pnpm

   pnpm add -g mastra@latest

   Yarn

   yarn global add mastra@latest

   Bun

   bun add --global mastra@latest

2. Authenticate:

   mastra auth login

3. Verify your project builds locally:

   mastra build

Replace Mastra Cloud Store with a hosted database

Mastra Cloud provided a managed LibSQL database. The Mastra platform does not host a database for you, so you need to point your storage at an externally hosted instance.

If you were already using a hosted database ("bring your own"), no changes are needed. Make sure the connection string is set as an environment variable in the dashboard rather than hardcoded.

If you were using file:./mastra.db with Cloud Store, please contact support for a migration path to export and import your data.

Update observability configuration

Mastra Cloud used logger-based tracing. The Mastra platform uses the Observability class with explicit exporters.

Install the observability package:

npm

npm install @mastra/observability

pnpm

pnpm add @mastra/observability

Yarn

yarn add @mastra/observability

Bun

bun add @mastra/observability

Before (Mastra Cloud):

src/mastra/index.ts

import { Mastra } from '@mastra/core/mastra'
import { PinoLogger } from '@mastra/loggers'

export const mastra = new Mastra({
  logger: new PinoLogger({ name: 'my-app', level: 'info' }),
  // traces appear in Cloud dashboard automatically
})

After (Mastra platform):

src/mastra/index.ts

import { Mastra } from '@mastra/core/mastra'
import {
  Observability,
  DefaultExporter,
  CloudExporter,
  SensitiveDataFilter,
} from '@mastra/observability'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-app',
        exporters: [new DefaultExporter(), new CloudExporter()],
        spanOutputProcessors: [new SensitiveDataFilter()],
      },
    },
  }),
})

• DefaultExporter persists traces to your storage backend for Studio.
• CloudExporter sends traces to the Mastra platform when MASTRA_CLOUD_ACCESS_TOKEN is set.
• SensitiveDataFilter redacts passwords, tokens, and keys from span data before export.

See the observability overview for the full configuration, including composite storage with DuckDB for metrics.

Deploy Studio

Deploy your hosted Studio instance:

mastra studio deploy

The CLI builds your project, uploads the artifact, and deploys it. On first deploy, a .mastra-project.json file is created to link your local project to the platform. Commit this file to your repository.

See Studio deployment for details.

Deploy Server (optional)

If you need a production API endpoint, deploy a Server:

mastra server deploy

This creates a separate deployment with a stable API URL, environment variable management, and custom domain support. See the Server deployment guide for the full walkthrough.

note

Environment variables from .env, .env.local, and .env.production are included automatically on first deploy. 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.

Set up CI (optional)

Mastra Cloud auto-deployed on push. The Mastra platform uses CLI-driven deploys, which you can run from any CI provider.

Prerequisites

1. Create an API token:

   mastra auth tokens create ci-deploy

2. Store the token as a GitHub Actions secret (e.g. MASTRA_API_TOKEN).

3. Commit .mastra-project.json to your repo (generated on your first manual deploy).

When MASTRA_API_TOKEN is set, the CLI runs in headless mode and skips all interactive prompts.

Deploy Server on push to main

Server deploy accepts org and project from .mastra-project.json, so no extra env vars are needed beyond the token:

.github/workflows/deploy-server.yml

name: Deploy to Mastra Server

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - uses: pnpm/action-setup@v4
        with:
          version: 10
      - run: pnpm install
      - run: pnpm mastra server deploy --yes --config .mastra-project.json
        env:
          MASTRA_API_TOKEN: ${{ secrets.MASTRA_API_TOKEN }}

Deploy Studio on push to main

Studio deploy requires MASTRA_ORG_ID and MASTRA_PROJECT_ID as env vars in headless mode, even when --config is provided:

.github/workflows/deploy-studio.yml

name: Deploy to Mastra Studio

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - uses: pnpm/action-setup@v4
        with:
          version: 10
      - run: pnpm install
      - run: pnpm mastra studio deploy --yes --config .mastra-project.json
        env:
          MASTRA_API_TOKEN: ${{ secrets.MASTRA_API_TOKEN }}
          MASTRA_ORG_ID: ${{ secrets.MASTRA_ORG_ID }}
          MASTRA_PROJECT_ID: ${{ secrets.MASTRA_PROJECT_ID }}

Decommission old Cloud project

Update any clients pointing to your old Mastra Cloud URL to the new Server or Studio URL. Verify traces appear in the new platform by checking the Studio observability dashboard. Delete your old Mastra Cloud project once everything is confirmed working.

Related

• Observability overview
• Studio deployment
• Server deployment
• CLI reference
• Mastra platform overview