Studio Deployment

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

Published: 2026-05-10 · Source: crawler_authoritative

Tình huống

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

Insight

Studio is a React-based Single Page Application (SPA) that connects to a running Mastra server. Two deployment options exist: hosted Studio on the Mastra platform or self-hosted on own infrastructure. The mastra studio command serves a standalone static UI using Node’s built-in http module and serve-handler package. By default, it connects to a Mastra server at http://localhost:4111. If no server is found there, a form allows entering a custom Mastra instance URL and API prefix. For subpath hosting (e.g., /agents behind Nginx), set MASTRA_STUDIO_BASE_PATH environment variable before starting Studio. Platform deployment uses mastra studio deploy which builds the project (compiling src/mastra/ into .mastra/output), packages it as a ZIP artifact, uploads it, and deploys to a cloud sandbox. The deploy transitions through queued → uploading → starting → running states. If a sandbox is already running, it hot-updates in place. The .mastra-project.json file is written automatically. An env file is required for deployment - the CLI errors with ‘No env file found for deploy’ if missing. Use --env-file flag for non-interactive selection. mastra build --studio creates Studio assets in .mastra/output/studio folder, and setting MASTRA_STUDIO_PATH environment variable allows the Mastra server to serve the Studio UI. Manual CDN deployment requires a Vite configuration that copies built Studio assets from node_modules/mastra/dist/studio to dist, replacing “ values with environment variables.

Hành động

To install the Mastra CLI globally: run npm install -g mastra, pnpm add -g mastra, yarn global add mastra, or bun add --global mastra. Run mastra studio to start Studio locally at localhost:3000. For subpath hosting, run MASTRA_STUDIO_BASE_PATH=/agents mastra studio. For Mastra platform deployment: run mastra studio deploy. Ensure a .env file exists in the project directory before deploying. To select a specific env file non-interactively: mastra studio deploy --env-file .env.production --yes. To create a new project non-interactively: mastra studio deploy --project "my-new-project" --yes. To serve Studio alongside the Mastra server: run mastra build --studio, then start with MASTRA_STUDIO_PATH=.mastra/output/studio node .mastra/output/index.mjs. For manual CDN deployment with Vite: create a project, install vite and mastra dependencies, add a build script, create a vite.config.js that copies Studio assets and replaces “ values, create a .env file with required environment variables (MASTRA_SERVER_HOST, MASTRA_SERVER_PORT, MASTRA_SERVER_PROTOCOL, MASTRA_API_PREFIX, etc.), and run the build. Security warning: Studio has full access to agents, workflows, and tools - secure it with authentication, VPN, or other measures in production.

Kết quả

Studio runs as a standalone static UI at localhost:3000 by default, connecting to the Mastra server. Platform deployments transition through queued → uploading → starting → running states, with hot-updates for existing sandboxes. The instance URL is assigned per project slug and remains stable across deploys. Built Vite projects generate static files in the dist folder for CDN deployment.

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

The Mastra platform allows you to deploy your Studio to the cloud. Run a single CLI command, and the platform handles provisioning, deployment, and hosting.

Run the following command:

mastra studio deploy

Note: See the CLI reference for the full list of flags and CI/CD usage.

This builds your project (compiling src/mastra/ into .mastra/output), packages it as an artifact ZIP, uploads it, and deploys it to a cloud sandbox.

If this is your first deploy, the CLI will prompt you to create a new project or select an existing one. The .mastra-project.json file is written automatically.

A deploy transitions through queued → uploading → starting → running (or failed if something goes wrong). If a sandbox is already running for your project, the platform hot-updates it in place with no downtime. Otherwise it creates a fresh sandbox. Your instance URL is assigned per project slug and remains stable across deploys.

Env file requirement

The deploy bundles environment variables from a .env or .env.* file in the project directory. If no env file is present, the deploy errors with No env file found for deploy. after the build step. Add at least an empty .env file before running the command.

When multiple env files are present, the CLI prompts you to pick one. To select non-interactively, pass --env-file:

mastra studio deploy --env-file .env.production --yes

This is also how you target multiple environments from a single codebase: maintain one env file per environment (for example .env.staging, .env.production) and pass the right one to each deploy. Each environment still requires its own Mastra platform project — see Configuration for the multi-environment pattern.

Create a new project non-interactively

mastra studio deploy can create a project on first run. If --project <name> does not match an existing project, the CLI uses the value as the new project name and creates it after confirmation. Combined with --yes, this is fully scriptable:

mastra studio deploy --project "my-new-project" --yes

Use this from CI or AI coding agents instead of mastra studio projects create, which is interactive only.

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

Studio Deployment

Studio Deployment

Tình huống

Insight

Hành động

Kết quả

Nội dung gốc (Original)

Studio deployment

Quickstart

Mastra platform

Env file requirement

Create a new project non-interactively

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