Studio on Mastra platform

Studio on Mastra platform is a hosted visual workspace for testing agents and running workflows, plus inspecting traces. Use it when you want to share Studio with your team without hosting the Studio UI yourself.

You can deploy Studio from the CLI as shown below, or link a GitHub repository for push-to-deploy. See the GitHub integration for the repository-linked flow.

note

mastra studio deploy is the earlier split deploy path. New projects should use the unified mastra deploy command, which adds preflight validation, environments, and CLI-managed databases.

Quickstart

1. Follow the get started guide to create your first Mastra project.

2. 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

3. Deploy Studio with a single command:

   mastra studio deploy

   On a successful deploy, the CLI outputs the URL of your deployed Studio instance.

On your first deploy, the CLI prompts you to create a new project or select an existing one. It then creates a .mastra-project.json file in your project directory. This file links your local project to a platform project. It contains the projectId, projectName, and organizationId. Commit this file to your repository so CI/CD knows which project to deploy to.

How deploy works

The mastra studio deploy command builds your project and compiles src/mastra/ into .mastra/output. It packages that output as an artifact ZIP, then uploads and deploys it to a cloud sandbox.

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 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.

See the mastra studio deploy CLI reference for the full list of flags and CI/CD usage.

Environment files

A local env file is optional. When a .env or .env.* file is present in the project directory, the deploy bundles its environment variables.

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

To run the same codebase across production and staging, use the unified mastra deploy --env command instead. Environments replace the earlier pattern of one project per environment.

Create a new project non-interactively

mastra studio deploy can create a project on first run. If --project <name> doesn't 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.

Self-host Studio

To deploy Studio on your own infrastructure, see Studio deployment.

Related

• mastra studio deploy