# 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](https://mastra.ai/docs) to create your first Mastra project.

2. Install the `mastra` CLI globally:

   **npm**:

   ```bash
   npm install -g mastra
   ```

   **pnpm**:

   ```bash
   pnpm add -g mastra
   ```

   **Yarn**:

   ```bash
   yarn global add mastra
   ```

   **Bun**:

   ```bash
   bun add --global mastra
   ```

3. Deploy Studio with a single command:

   ```bash
   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](https://mastra.ai/reference/cli/mastra) 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`:

```bash
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](https://mastra.ai/docs/mastra-platform/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:

```bash
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](https://mastra.ai/docs/studio/deployment).

## Related

- [`mastra studio deploy`](https://mastra.ai/reference/cli/mastra)