> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# 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](https://mastra.ai/docs/mastra-platform/github) for the repository-linked flow.

> **Note:** `mastra studio deploy` is the earlier split deploy path. New projects should use the unified [`mastra deploy`](https://mastra.ai/docs/mastra-platform/deploy) command, which adds preflight validation, environments, and CLI-managed databases.

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

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

To run the same codebase across `production` and `staging`, use the unified [`mastra deploy --env`](https://mastra.ai/docs/mastra-platform/deploy) command instead. [Environments](https://mastra.ai/docs/mastra-platform/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:

```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)