# 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**:

   ```bash
   npm install -g mastra@latest
   ```

   **pnpm**:

   ```bash
   pnpm add -g mastra@latest
   ```

   **Yarn**:

   ```bash
   yarn global add mastra@latest
   ```

   **Bun**:

   ```bash
   bun add --global mastra@latest
   ```

2. Authenticate:

   ```bash
   mastra auth login
   ```

3. Verify your project builds locally:

   ```bash
   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](mailto:support@mastra.ai) 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**:

```bash
npm install @mastra/observability
```

**pnpm**:

```bash
pnpm add @mastra/observability
```

**Yarn**:

```bash
yarn add @mastra/observability
```

**Bun**:

```bash
bun add @mastra/observability
```

**Before (Mastra Cloud):**

```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):**

```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](https://mastra.ai/docs/studio/observability).
- `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](https://mastra.ai/docs/observability/overview) for the full configuration, including composite storage with DuckDB for metrics.

## Deploy Studio

Deploy your hosted Studio instance:

```bash
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](https://mastra.ai/docs/studio/deployment) for details.

## Deploy Server (optional)

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

```bash
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](https://mastra.ai/guides/deployment/mastra-platform) 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](https://projects.mastra.ai). 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:

   ```bash
   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:

```yaml
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:

```yaml
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](https://mastra.ai/docs/studio/observability). Delete your old Mastra Cloud project once everything is confirmed working.

## Related

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