Deploying Mastra: Cloud vs Self-Hosted vs Vercel -- What the Docs Don't Tell You

Three deployment paths, three very different trade-offs. Here is a plain-English guide to which one fits your situation.

The Confusion

Mastra has three deployment paths: Mastra Cloud (managed), self-hosted (Docker or Node), and Vercel (serverless). The docs cover each separately but do not compare them, and the community regularly asks which one to use -- and why deploying to Vercel breaks things that work locally.

This article gives you the honest comparison, explains what breaks where, and tells you which path fits which situation.

Option 1: Mastra Cloud (Managed)

Mastra Cloud is the managed hosting service run by the Mastra team. You push your Mastra project and it handles infrastructure, scaling, persistence, and the Mastra Studio UI.

# Deploy to Mastra Cloud
npx mastra deploy --cloud
 
# Set up cloud credentials first:
npx mastra login

Mastra Cloud includes the Studio UI out of the box. If your team needs visibility into workflow runs, agent traces, and evals without setting up your own observability stack, Cloud is the fastest path.

Option 2: Self-Hosted (Docker / Node)

Self-hosting gives you full control. You run Mastra as a Node.js server (or in a Docker container) on any infrastructure: Railway, Render, Fly.io, EC2, your own VPS.

# Build your Mastra project for self-hosting
npx mastra build
 
# This outputs a .mastra/ directory with a standalone Node server
# Run it:
node .mastra/output/index.mjs
 
# Or with Docker (create your own Dockerfile):

FROM node:20-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY .mastra/ .mastra/
EXPOSE 3000
CMD ["node", ".mastra/output/index.mjs"]

Key things to configure for self-hosted production:

• Set a persistent storage adapter (LibSQL or PostgreSQL) -- without this, workflow state is lost on restart
• Set MASTRA_LOG_LEVEL=info in production (debug logging is very verbose)
• Expose the Mastra API on a specific port and put a reverse proxy (nginx, Caddy) in front
• The Studio UI is available at /studio in development but disabled in production builds by default -- enable with MASTRA_STUDIO=true if needed

The Studio UI in self-hosted mode is a development tool. Do not expose it publicly without authentication. In production, either disable it (default) or put it behind your auth layer.

Option 3: Vercel (Serverless)

Mastra can be embedded inside a Next.js app and deployed to Vercel. This is the most common path for teams that are already on Next.js. It is also where the most confusion and bugs come from.

How the integration works

In a Next.js + Mastra setup, your Mastra instance is initialised in a server-side module and your agents/workflows are exposed via Next.js API routes or Route Handlers. The Mastra Studio runs as a separate route group.

// src/mastra/index.ts -- your Mastra instance
import { Mastra } from '@mastra/core';
import { myAgent } from './agents/myAgent';
 
export const mastra = new Mastra({
  agents: { myAgent },
  // IMPORTANT: Vercel does not support LibSQL in serverless --
  // use a remote database (Turso, Neon, Supabase) instead:
  storage: new PostgresStore({ connectionString: process.env.DATABASE_URL }),
});
 
// src/app/api/agent/route.ts -- expose as API route
import { mastra } from '@/mastra';
export async function POST(req: Request) {
  const { message } = await req.json();
  const result = await mastra.getAgent('myAgent').generate(message);
  return Response.json({ result: result.text });
}

What breaks on Vercel

// next.config.ts -- increase function timeout for workflow routes
const nextConfig = {
  experimental: {
    serverActions: {
      bodySizeLimit: '2mb',
    },
  },
};
 
// In route handler for long-running workflows:
export const maxDuration = 60; // seconds (requires Vercel Pro)
export const dynamic = 'force-dynamic';

Decision Guide

Quick Reference

• Mastra Cloud: fastest to ship, managed infra, Studio included -- best for most teams
• Self-hosted: full control, needs persistent DB config, suits regulated or complex deployments
• Vercel: works for simple agents in Next.js, breaks for long-running or suspended workflows
• Always configure a remote storage backend on Vercel (Turso, Neon, Supabase)
• Studio UI is a dev tool -- do not expose without authentication in production