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.
QuickstartDirect link to Quickstart
Follow the get started guide to create your first Mastra project.
Install the
mastraCLI globally:- npm
- pnpm
- Yarn
- Bun
npm install -g mastrapnpm add -g mastrayarn global add mastrabun add --global mastraDeploy Studio with a single command:
mastra deployOn 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 worksDirect link to How deploy works
The mastra 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 deploy CLI reference for the full list of flags and CI/CD usage.
AuthenticationDirect link to Authentication
By default, every Studio deploy on Mastra platform is protected by platform auth. Members of your platform organization sign in with their platform account, and no one else can access the deployed Studio. You don't need to configure anything to get this behavior.
Platform auth applies to the Studio UI only. Your server's API routes are governed by your own server.auth configuration, or remain open if you haven't set one.
Roles and permissionsDirect link to Roles and permissions
Platform auth maps your organization roles to Studio permissions:
| Platform role | Studio permissions |
|---|---|
admin | Full access (*) |
member | Read and execute |
viewer | Read-only |
To customize this mapping, set roleMapping on studio.rbac in your Mastra configuration. When present, your mapping replaces the platform defaults. See Role-based access control for the permission format.
Bring your own authDirect link to Bring your own auth
To use your own auth provider for the deployed Studio instead of platform auth, set an environment variable on the project:
MASTRA_PLATFORM_STUDIO_AUTH=disabled
Add it to the env file you deploy with, or store it on the project through the dashboard, then redeploy. With platform auth disabled, the deploy leaves your auth and RBAC configuration untouched. Your own provider drives the Studio login flow, exactly like a self-hosted deploy. studio.auth protects the Studio UI, while server.auth protects your API routes. Studio requests fall back to server.auth when studio.auth isn't set.
Disabling platform auth turns off platform account logins. If you disable it without configuring your own auth provider, the deployed Studio and all API routes are publicly accessible.
If you keep platform auth enabled and also configure your own studio.auth, both providers validate tokens, but the login screen only offers the platform sign-in flow. To sign in through your own provider, disable platform auth.
Environment filesDirect link to 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 deploy --env-file .env.production --yes
To run the same codebase across production and staging, use mastra deploy --env. See Environments for the full model.
Create a new project non-interactivelyDirect link to Create a new project non-interactively
On its first run, mastra deploy can create a project. When --project <name> doesn't match an existing project, the CLI treats the value as a new project name and creates it after confirmation. Add --yes to make this flow fully scriptable:
mastra 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 StudioDirect link to Self-host Studio
To deploy Studio on your own infrastructure, see Studio deployment.