Studio on Mastra platform

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

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, compiles src/mastra/ into .mastra/output, packages the output as an artifact ZIP, uploads it, 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

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, such as .env.staging and .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> 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