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

# Déploiement de Studio

Studio est une application monopage (SPA) fondée sur React qui s'exécute dans le navigateur et se connecte à un [serveur Mastra](https://mastra.zisheng.pro/fr/docs/deployment/mastra-server) en cours d'exécution.

Vous pouvez déployer Studio de deux manières principales :

- La plateforme Mastra fournit une instance Studio hébergée et vous permet d'en partager l'accès avec votre équipe au moyen d'un lien.
- Vous pouvez auto-héberger Studio sur votre propre infrastructure, soit avec votre serveur Mastra, soit séparément sous la forme d'une SPA autonome.

Cette page explique comment déployer Studio sur votre propre infrastructure. Les détails précis d'un déploiement pouvant varier considérablement selon vos besoins et votre configuration, nous présentons ici les principes généraux et les options disponibles.

## Démarrage rapide

La manière la plus simple d'exécuter Studio consiste à utiliser la commande [`mastra studio`](https://mastra.zisheng.pro/fr/reference/cli/mastra).

Alors que `mastra dev` exécute à la fois Studio et une API à des fins de développement, `mastra studio` sert une interface statique autonome qui se connecte à un serveur Mastra déjà actif. Vous pouvez ainsi déployer Studio indépendamment du serveur Mastra si vous le souhaitez.

Ouvrez un terminal et installez globalement la CLI `mastra` :

**npm**:

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

**pnpm**:

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

**Yarn**:

```bash
yarn global add mastra
```

**Bun**:

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

Exécutez la commande `mastra studio` :

```bash
mastra studio
```

Ouvrez [localhost:3000](http://localhost:3000) dans votre navigateur pour afficher l'interface de Studio. Par défaut, celle-ci tente de se connecter à un serveur Mastra exécuté sur `http://localhost:4111`. Si aucun serveur n'est trouvé à cette adresse, un formulaire vous permet de saisir l'URL de votre instance Mastra et le préfixe de l'API.

La commande utilise le module `http` intégré à Node et [`serve-handler`](https://www.npmjs.com/package/serve-handler) pour distribuer les fichiers statiques.

> **Remarque:** Si vous hébergez Studio sous un chemin secondaire (par exemple `/agents` derrière Nginx), définissez `MASTRA_STUDIO_BASE_PATH` avant de démarrer Studio :
>
> ```bash
> MASTRA_STUDIO_BASE_PATH=/agents mastra studio
> ```
>
> Cette variable met à jour l'URL de base HTML et le routage des ressources statiques afin que l'instance Studio autonome fonctionne correctement sous ce chemin secondaire.

## Plateforme Mastra

Pour utiliser Studio hébergé sur la plateforme Mastra, consultez [Studio sur la plateforme Mastra](https://mastra.zisheng.pro/fr/docs/mastra-platform/studio).

## Exécuter un serveur

L'exécution de `mastra studio` comme processus persistant ne diffère pas de celle de tout autre service Node.js. Les bonnes pratiques, outils et options habituels de déploiement s'appliquent également. Vous pouvez utiliser un gestionnaire de processus comme PM2, Docker ou des services cloud prenant en charge les applications Node.js. Comme pour tout service web, veillez à configurer correctement CORS et à surveiller les erreurs.

> **Attention:** Une fois connecté à votre serveur Mastra, Studio dispose d'un accès complet à vos Agents, Workflows et outils. Veillez à le sécuriser correctement en production, par exemple au moyen d'une authentification ou d'un VPN, afin d'empêcher tout accès non autorisé.
>
> Consultez la documentation sur l'[authentification](https://mastra.zisheng.pro/fr/docs/studio/auth) pour en savoir plus.

### Avec votre API

Vous pouvez également distribuer Studio avec votre [serveur Mastra](https://mastra.zisheng.pro/fr/docs/deployment/mastra-server). Vous ne disposez ainsi que d'un seul service à déployer et à gérer.

Pour cela, exécutez `mastra build` avec l'option `--studio` :

```bash
mastra build --studio
```

Cette commande crée un dossier `.mastra/output/studio` contenant les ressources compilées de Studio. En définissant la variable d'environnement `MASTRA_STUDIO_PATH`, le serveur Mastra peut également distribuer l'interface Studio.

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

## Utiliser un CDN

### Déploiement automatique

Certains [Providers cloud](https://mastra.zisheng.pro/fr/docs/deployment/cloud-providers) proposent de déployer Studio avec votre fonction serverless. Les Providers actuellement pris en charge sont :

- [`VercelDeployer`](https://mastra.zisheng.pro/fr/reference/deployer/vercel)

### Déploiement manuel

Vous ne pouvez pas déployer directement les ressources compilées de Studio sur un CDN, car l'interface dépend de certains paramètres d'exécution. Avec une configuration supplémentaire, vous pouvez transformer les ressources compilées en SPA autonome et la déployer sur n'importe quel service d'hébergement statique.

Suivez l'exemple ci-dessous pour créer une SPA avec Vite.

1. Créez un dossier et initialisez un nouveau projet Node.js :

   **npm**:

   ```bash
   mkdir studio-spa
   cd studio-spa
   npm init
   ```

   **pnpm**:

   ```bash
   mkdir studio-spa
   cd studio-spa
   pnpm init
   ```

   **Yarn**:

   ```bash
   mkdir studio-spa
   cd studio-spa
   yarn init
   ```

   **Bun**:

   ```bash
   mkdir studio-spa
   cd studio-spa
   bun init
   ```

2. Installez `vite` et `mastra` comme dépendances :

   **npm**:

   ```bash
   npm install vite mastra
   ```

   **pnpm**:

   ```bash
   pnpm add vite mastra
   ```

   **Yarn**:

   ```bash
   yarn add vite mastra
   ```

   **Bun**:

   ```bash
   bun add vite mastra
   ```

3. Ajoutez un script de build à votre fichier `package.json` :

   ```json
   {
     "scripts": {
       "build": "vite build"
     }
   }
   ```

4. Créez un fichier `index.html` de substitution :

   ```html
   <!doctype html>
   <html>
     <head></head>
     <body></body>
   </html>
   ```

5. Créez un fichier `vite.config.js`. Il copie les ressources compilées de Studio dans le dossier `dist` et remplace dans le HTML chaque valeur `%%PLACEHOLDER%%` par la valeur de la variable d'environnement correspondante.

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

6. Créez un fichier `.env` contenant les variables d'environnement nécessaires.

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

7. Exécutez le script de build pour générer les fichiers statiques dans le dossier `dist` :

   **npm**:

   ```bash
   npm run build
   ```

   **pnpm**:

   ```bash
   pnpm run build
   ```

   **Yarn**:

   ```bash
   yarn build
   ```

   **Bun**:

   ```bash
   bun run build
   ```

8. Faites pointer votre Provider d'hébergement vers le dossier `dist`, puis déployez l'application !