Mastra Studio Deployment Guide

Trust: ★★★☆☆ (0.90) · 0 validations · developer_reference

Published: 2026-05-13 · Source: crawler_authoritative

Tình huống

Guide for developers on deploying Mastra Studio, a React-based SPA that connects to a Mastra server, covering self-hosted deployment options and configurations.

Insight

Mastra Studio is a React-based Single Page Application (SPA) that runs in the browser and connects to a running Mastra server. Two primary deployment options exist: hosted Studio on the Mastra platform, or self-hosting on your own infrastructure. Self-hosting can run alongside the Mastra server or separately as a standalone SPA. The easiest way to run Studio locally is via the mastra studio CLI command, which serves a standalone static UI that connects to an already-running Mastra server using Node’s built-in http module and serve-handler package. By default, it attempts to connect to a Mastra server at http://localhost:4111. The command supports the MASTRA_STUDIO_BASE_PATH environment variable for hosting under subpaths (e.g., /agents behind Nginx). For production deployments alongside your API, use mastra build --studio to create a .mastra/output/studio folder, then set MASTRA_STUDIO_PATH=.mastra/output/studio and run node .mastra/output/index.mjs. For CDN deployment, Vercel offers automatic deployment via VercelDeployer. For manual CDN deployment, create a Vite-based SPA that copies Studio assets from node_modules/mastra/dist/studio and replaces “ values with environment variables including MASTRA_SERVER_HOST, MASTRA_SERVER_PORT, MASTRA_SERVER_PROTOCOL, MASTRA_API_PREFIX, MASTRA_CLOUD_API_ENDPOINT, and others. Studio can be installed globally via npm (npm install -g mastra), pnpm (pnpm add -g mastra), yarn (yarn global add mastra), or bun (bun add --global mastra). Running Studio as a long-running process follows standard Node.js deployment practices with PM2, Docker, or cloud services. CORS must be configured correctly, and security considerations include running behind authentication or VPN in production since Studio has full access to agents, workflows, and tools.

Hành động

To deploy Mastra Studio: 1) Install the mastra CLI globally using npm, pnpm, yarn, or bun. 2) Run mastra studio to start a local instance (defaults to localhost:3000, connecting to localhost:4111). 3) For subpath hosting, set MASTRA_STUDIO_BASE_PATH=/path mastra studio. 4) For deployment alongside your API, run mastra build --studio, set MASTRA_STUDIO_PATH=.mastra/output/studio, then run node .mastra/output/index.mjs. 5) For manual CDN deployment, create a Vite project, install vite and mastra, create a vite.config.js that copies Studio assets and replaces “ values with environment variables from a .env file, then run npm run build (or equivalent for your package manager) to generate the dist folder for deployment. Environment variables for Vite build include MASTRA_SERVER_HOST, MASTRA_SERVER_PORT, MASTRA_SERVER_PROTOCOL, MASTRA_API_PREFIX, MASTRA_HIDE_CLOUD_CTA, MASTRA_CLOUD_API_ENDPOINT, MASTRA_EXPERIMENTAL_FEATURES, MASTRA_TEMPLATES, MASTRA_TELEMETRY_DISABLED, MASTRA_REQUEST_CONTEXT_PRESETS, MASTRA_THEME_TOGGLE, MASTRA_EXPERIMENTAL_UI, and MASTRA_STUDIO_BASE_PATH. For production, ensure proper security (authentication, VPN) since Studio has full access to your Mastra instance.

Kết quả

Studio UI becomes accessible at the configured port (default localhost:3000), connects to the Mastra server at the specified URL and API prefix, and provides full access to agents, workflows, and tools via the web interface.

Điều kiện áp dụng

Studio deployment requires a running Mastra server to connect to. For subpath hosting behind reverse proxies like Nginx, set MASTRA_STUDIO_BASE_PATH environment variable.

Nội dung gốc (Original)

Studio deployment

Studio is a React-based Single Page Application (SPA) that runs in the browser and connects to a running Mastra server.

You can deploy Studio in two primary ways:

The Mastra platform provides a hosted Studio for you and allows you to share access with your team via link
Self-host Studio on your own infrastructure, either alongside your Mastra server or separately as a standalone SPA

On this page you’ll learn how to deploy Studio on your own infrastructure. As the finer details of deployment can vary widely based on your needs and setup, we’ll cover the general principles and options available to you.

Quickstart

The easiest way to run Studio is the mastra studio command.

Whereas mastra dev runs both Studio and an API for development purposes, the purpose of mastra studio is to serve a standalone, static UI that connects to an already-running Mastra server. This allows you to deploy Studio on its own, separate from the Mastra server, if desired.

Open a terminal and install the mastra CLI globally:

npm:

npm install -g mastra

pnpm:

pnpm add -g mastra

Yarn:

yarn global add mastra

Bun:

bun add --global mastra

Run the mastra studio command:

mastra studio

Open localhost:3000 in your browser to see the Studio UI. By default, it will attempt to connect to a Mastra server running at http://localhost:4111. If it doesn’t find one there, you’ll see a form where you can enter your Mastra instance URL and API prefix.

The command uses Node’s built-in http module and serve-handler to serve the static files.

Note: If you’re hosting Studio under a subpath (for example /agents behind Nginx), set MASTRA_STUDIO_BASE_PATH before starting Studio:
MASTRA_STUDIO_BASE_PATH=/agents mastra studio
This updates the HTML base URL and static asset routing so the standalone Studio works correctly under that subpath.

Mastra platform

For hosted Studio on Mastra platform, see Studio on Mastra platform.

Running a server

Running mastra studio as a long-running process is no different from running any other Node.js service. All the best practices, tools, and options for deployment apply here as well. You can use process managers like PM2, use Docker, or cloud services that support Node.js applications. You’ll need to ensure CORS is configured correctly and errors are monitored, as with any web service.

Warning: Once Studio is connected to your Mastra server, it has full access to your agents, workflows, and tools. Be sure to secure it properly in production (e.g. behind authentication, VPN, etc.) to prevent unauthorized access.

Visit the Authentication docs to learn more.

Alongside your API

Alternatively, you can serve Studio alongside your Mastra server. This way you only have one service to deploy and manage.

To do this, run mastra build with the --studio flag:

mastra build --studio

It’ll create a .mastra/output/studio folder with the built Studio assets. By defining the MASTRA_STUDIO_PATH environment variable, the Mastra server can serve the Studio UI, too.

MASTRA_STUDIO_PATH=.mastra/output/studio node .mastra/output/index.mjs

Using a CDN

Automatic

Some of the Cloud providers offer an option to deploy Studio alongside your serverless function. Currently, the supported providers are:

VercelDeployer

Manual

You can’t directly deploy the built Studio assets to a CDN, as the UI relies on some dynamic configuration. With a bit of extra setup, you can create a standalone SPA out of the built assets and deploy it to any static hosting service.

Follow the example below to create a SPA using Vite.

Create a new folder and initialize a new Node.js project:

npm:

mkdir studio-spa
cd studio-spa
npm init

pnpm:

mkdir studio-spa
cd studio-spa
pnpm init

Yarn:

mkdir studio-spa
cd studio-spa
yarn init

Bun:

mkdir studio-spa
cd studio-spa
bun init

Install vite and mastra as dependencies:

npm:

npm install vite mastra

pnpm:

pnpm add vite mastra

Yarn:

yarn add vite mastra

Bun:

bun add vite mastra

Add a build script to your package.json:

{
  "scripts": {
    "build": "vite build"
  }
}

Create a placeholder index.html file:

<!doctype html>
<html>
  <head></head>
  <body></body>
</html>

Create a vite.config.js file. It copies the built Studio assets to the dist folder and replaces any “ values in the HTML with environment variable values.

import { defineConfig, loadEnv } from 'vite'
import { readFileSync, cpSync, writeFileSync } from 'node:fs'
import { resolve, join } from 'node:path'
 
const studioDir = resolve(import.meta.dirname, 'node_modules/mastra/dist/studio')
 
export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), 'MASTRA_')
 
  return {
    plugins: [
      {
        name: 'mastra-studio',
        closeBundle() {
          const outDir = resolve(import.meta.dirname, 'dist')
          cpSync(studioDir, outDir, { recursive: true })
 
          const indexPath = join(outDir, 'index.html')
          const html = readFileSync(indexPath, 'utf-8')
          writeFileSync(
            indexPath,
            html.replaceAll(//g, (_, key) => env[key] ?? ''),
          )
        },
      },
    ],
    build: {
      emptyOutDir: true,
    },
  }
})

Create a .env file with the necessary environment variables.

MASTRA_SERVER_HOST=localhost
MASTRA_SERVER_PORT=4111
MASTRA_SERVER_PROTOCOL=http
MASTRA_API_PREFIX=/api
MASTRA_HIDE_CLOUD_CTA=false
MASTRA_CLOUD_API_ENDPOINT=
MASTRA_EXPERIMENTAL_FEATURES=false
MASTRA_TEMPLATES=false
MASTRA_TELEMETRY_DISABLED=true
MASTRA_REQUEST_CONTEXT_PRESETS=
MASTRA_THEME_TOGGLE=false
MASTRA_EXPERIMENTAL_UI=false
MASTRA_STUDIO_BASE_PATH=

Run the build script to generate the static files in the dist folder:

npm:
```
npm run build
```
pnpm:
```
pnpm run build
```
Yarn:
```
yarn build
```
Bun:
```
bun run build
```
Point your hosting provider to the dist folder and deploy!

Liên kết

Nền tảng: Dev Framework · Mastra
Nguồn: https://mastra.ai/docs/studio/deployment

Xem thêm:

KakaFlow KB

Nội dung

Mastra Studio Deployment Guide

Mastra Studio Deployment Guide

Tình huống

Insight

Hành động

Kết quả

Điều kiện áp dụng

Nội dung gốc (Original)

Studio deployment

Quickstart

Mastra platform

Running a server

Alongside your API

Using a CDN

Automatic

Manual

Liên kết

Sơ đồ

Mục lục

Liên kết ngược