Studio のデプロイ

Studio はブラウザーで動作し、実行中の Mastra サーバーに接続する React ベースのシングルページアプリケーション（SPA）です。

Studio の主なデプロイ方法は2つあります。

Mastra platform のホステッド Studio を使用し、リンクでチームにアクセスを共有する
Mastra サーバーと同じ場所、または独立した SPA として別の場所に Studio をセルフホストする

このページでは、Studio を独自のインフラストラクチャにデプロイする方法を説明します。デプロイの詳細は要件や構成によって大きく異なるため、ここでは一般的な原則と利用可能な選択肢を取り上げます。

クイックスタート
クイックスタートへの直接リンク

Studio を実行する最も簡単な方法は、mastra studio コマンドです。

mastra dev は開発用の Studio と API の両方を実行します。一方、mastra studio は、すでに実行中の Mastra サーバーに接続する独立した静的 UI を提供します。必要に応じて Studio を Mastra サーバーとは別にデプロイできます。

ターミナルを開き、mastra CLI をグローバルにインストールします。

npm
pnpm
Yarn
Bun

npm install -g mastra

pnpm add -g mastra

yarn global add mastra

bun add --global mastra

mastra studio コマンドを実行します。

mastra studio

ブラウザーで localhost:3000 を開くと Studio UI が表示されます。デフォルトでは、http://localhost:4111 で実行中の Mastra サーバーへの接続を試みます。見つからない場合は、Mastra インスタンスの URL と API プレフィックスを入力するフォームが表示されます。

このコマンドは Node の組み込み http モジュールと serve-handler を使用して静的ファイルを配信します。

注記

Studio をサブパス（Nginx の背後にある /agents など）でホストする場合は、Studio を起動する前に MASTRA_STUDIO_BASE_PATH を設定します。

MASTRA_STUDIO_BASE_PATH=/agents mastra studio

これにより HTML のベース URL と静的アセットのルーティングが更新され、独立した Studio がそのサブパスで正しく動作します。

Mastra platform
Mastra platformへの直接リンク

Mastra platform のホステッド Studio については、Mastra platform の Studio を参照してください。

mastra studio を長時間実行するプロセスとして運用する方法は、他の Node.js サービスと変わりません。デプロイに関する一般的なベストプラクティス、ツール、選択肢をそのまま適用できます。PM2 などのプロセスマネージャー、Docker、Node.js アプリケーションに対応するクラウドサービスを利用できます。他の Web サービスと同様に、CORS を正しく設定し、エラーを監視してください。

警告

Studio を Mastra サーバーに接続すると、Agent、Workflow、Tool に対するフルアクセスが与えられます。不正アクセスを防ぐため、本番環境では認証や VPN などを使用して適切に保護してください。

詳しくは認証ドキュメントを参照してください。

API と同じ場所で実行する
API と同じ場所で実行するへの直接リンク

また、Mastra サーバーと同じ場所で Studio を配信することもできます。この方法なら、デプロイして管理するサービスは1つだけです。

これを行うには、--studio フラグを指定して mastra build を実行します。

mastra build --studio

ビルドされた Studio アセットを含む .mastra/output/studio フォルダーが作成されます。MASTRA_STUDIO_PATH 環境変数を定義すると、Mastra サーバーから Studio UI も配信できます。

MASTRA_STUDIO_PATH=.mastra/output/studio node .mastra/output/index.mjs

CDN を使用する
CDN を使用するへの直接リンク

自動
自動への直接リンク

一部のクラウド Provider には、サーバーレス関数とともに Studio をデプロイするオプションがあります。現在対応している Provider は次のとおりです。

VercelDeployer

手動
手動への直接リンク

Studio UI は一部のランタイム設定に依存するため、ビルド済みの Studio アセットを CDN に直接デプロイすることはできません。少し設定を追加すれば、ビルド済みアセットから独立した SPA を作成し、任意の静的ホスティングサービスにデプロイできます。

次の例に従って、Vite を使用した SPA を作成します。

新しいフォルダーを作成し、Node.js プロジェクトを初期化します。

npm
pnpm
Yarn
Bun

mkdir studio-spa
cd studio-spa
npm init

mkdir studio-spa
cd studio-spa
pnpm init

mkdir studio-spa
cd studio-spa
yarn init

mkdir studio-spa
cd studio-spa
bun init

vite と mastra を依存関係としてインストールします。

npm
pnpm
Yarn
Bun

npm install vite mastra

pnpm add vite mastra

yarn add vite mastra

bun add vite mastra

package.json にビルドスクリプトを追加します。
package.json
```
{
  "scripts": {
    "build": "vite build"
  }
}
```
プレースホルダーとなる index.html ファイルを作成します。
index.html
```
<!doctype html>
<html>
  <head></head>
  <body></body>
</html>
```

vite.config.js ファイルを作成します。このファイルは、ビルド済みの Studio アセットを dist フォルダーにコピーし、HTML 内の %%PLACEHOLDER%% 値を環境変数の値に置き換えます。

vite.config.js
import { defineConfig, loadEnv } from 'vite'
import { readFileSync, cpSync, writeFileSync } from 'node:fs'
import { resolve, join } from 'node:path'

const studioDir = resolve(import.meta.dirname, 'node_modules/mastra/dist/studio')

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), 'MASTRA_')

  return {
    plugins: [
      {
        name: 'mastra-studio',
        closeBundle() {
          const outDir = resolve(import.meta.dirname, 'dist')
          cpSync(studioDir, outDir, { recursive: true })

          const indexPath = join(outDir, 'index.html')
          const html = readFileSync(indexPath, 'utf-8')
          writeFileSync(
            indexPath,
            html.replaceAll(/%%(\w+)%%/g, (_, key) => env[key] ?? ''),
          )
        },
      },
    ],
    build: {
      emptyOutDir: true,
    },
  }
})

必要な環境変数を指定した .env ファイルを作成します。

.env
MASTRA_SERVER_HOST=localhost
MASTRA_SERVER_PORT=4111
MASTRA_SERVER_PROTOCOL=http
MASTRA_API_PREFIX=/api
MASTRA_HIDE_CLOUD_CTA=false
MASTRA_CLOUD_API_ENDPOINT=
MASTRA_EXPERIMENTAL_FEATURES=false
MASTRA_TEMPLATES=false
MASTRA_TELEMETRY_DISABLED=true
MASTRA_REQUEST_CONTEXT_PRESETS=
MASTRA_THEME_TOGGLE=false
MASTRA_EXPERIMENTAL_UI=false
MASTRA_STUDIO_BASE_PATH=

ビルドスクリプトを実行し、dist フォルダーに静的ファイルを生成します。
- npm
- pnpm
- Yarn
- Bun
npm run build
pnpm run build
yarn build
bun run build
ホスティング Provider のデプロイ対象を dist フォルダーに設定します。

クイックスタートクイックスタートへの直接リンク

Mastra platformMastra platformへの直接リンク

サーバーを実行するサーバーを実行するへの直接リンク

API と同じ場所で実行するAPI と同じ場所で実行するへの直接リンク

CDN を使用するCDN を使用するへの直接リンク

自動自動への直接リンク

手動手動への直接リンク