Serveur sur la plateforme Mastra

Le serveur de la plateforme Mastra est une cible de déploiement en production qui exécute votre application Mastra comme serveur d'API. Utilisez-le lorsque vous souhaitez que la plateforme compile, déploie, héberge et gère votre serveur Mastra.

Vous bénéficiez immédiatement d'un point de terminaison d'API stable, de la gestion des variables d'environnement, de la prise en charge des domaines personnalisés et d'un historique des déploiements.

remarque

mastra server deploy correspond à l'ancienne méthode de déploiement séparé. Les nouveaux projets doivent utiliser la commande unifiée mastra deploy, qui ajoute une validation préalable, les environnements et les bases de données gérées par la CLI.

remarque

Le déploiement du serveur provisionne automatiquement un stockage hébergé. Si vous remplacez le stockage par LibSQLStore avec une URL de fichier, utilisez plutôt une base de données hébergée à distance, car la plateforme Mastra emploie un système de fichiers éphémère.

Démarrage rapide

1. Suivez le guide de démarrage pour créer votre premier projet Mastra.

2. Installez globalement la CLI mastra :

   npm

   npm install -g mastra

   pnpm

   pnpm add -g mastra

   Yarn

   yarn global add mastra

   Bun

   bun add --global mastra

3. Déployez votre projet :

   mastra server deploy

   Si vous n'êtes pas encore authentifié, la CLI vous invite à vous connecter. Elle enregistre vos identifiants localement et les réutilise pour les commandes suivantes.

   La commande exécute mastra build, téléverse l'artefact, construit une image Docker puis la déploie. Lors du premier déploiement, la CLI crée un fichier .mastra-project.json qui relie votre projet local à la plateforme. Validez ce fichier dans Git afin que les déploiements suivants et la CI/CD ciblent le même projet.

   remarque

   Les variables d'environnement de .env, .env.local et .env.production sont incluses automatiquement. Lors du premier déploiement, elles initialisent le projet si aucune variable n'a encore été définie. Gérez ensuite les variables d'environnement depuis le tableau de bord web. Vérifiez et nettoyez ces fichiers avant le premier déploiement afin de ne pas téléverser de secrets personnels ou réservés au développement.

   Consultez la référence de la CLI pour la liste complète des options.

4. Vérifiez votre déploiement à l'URL affichée par la CLI. Ajoutez /api/agents pour confirmer qu'elle renvoie la liste JSON de vos Agents.

   attention

   Configurez l'authentification avant d'exposer publiquement vos points de terminaison.

Cycle de vie d'un déploiement

Un déploiement passe par les états queued → uploading → building → deploying → running, ou par failed, cancelled, crashed ou stopped. Un seul build peut s'exécuter à la fois pour un projet. Si plusieurs déploiements sont mis en file d'attente, seul le plus récent se poursuit et les autres sont annulés. Les builds qui durent plus de 15 minutes échouent automatiquement. Le premier déploiement provisionne l'infrastructure et initialise les variables d'environnement depuis votre fichier .env local. L'URL du serveur reste stable d'un déploiement à l'autre.

Comportement en cas d'inactivité

Le serveur de la plateforme Mastra peut mettre un service en veille après une période d'inactivité afin d'économiser des ressources. L'inactivité est mesurée d'après le trafic réseau sortant. Un service n'est considéré comme inactif qu'après environ dix minutes sans paquet sortant. Tout trafic sortant récurrent réinitialise ce délai et maintient le service actif.

Un serveur qui ne se met jamais en veille possède généralement une tâche d'arrière-plan ou une connexion persistante qui émet périodiquement du trafic. Vérifiez les causes courantes suivantes.

Connexions persistantes aux bases de données

Un client de base de données qui reste ouvert maintient la connexion active même lorsque le serveur est inactif. De nombreux pilotes exécutent également en arrière-plan un contrôle de santé qui interroge périodiquement la base de données ; cette activité est comptabilisée comme trafic sortant. Par exemple, un client MongoDB qui n'est jamais fermé conserve un socket de surveillance ouvert et envoie un signal environ toutes les dix secondes.

Les paramètres du pool de connexions qui ferment les connexions inactives ne suffisent pas, car la connexion de surveillance du pilote reste ouverte et continue d'émettre des requêtes. Pour permettre la mise en veille du serveur, fermez le client après une période d'inactivité et reconnectez-le lors de la requête suivante.

remarque

La fermeture du client ajoute un court délai de reconnexion à la première requête après le réveil du serveur. Si votre charge ne peut pas tolérer ce délai, maintenez la connexion ouverte et ne comptez pas sur la mise en veille automatique.

Tâches planifiées et minuteurs

Un setInterval, un job cron ou une boucle d'interrogation qui effectue des appels réseau maintient le serveur actif. Si vous avez besoin de tâches planifiées, exécutez-les comme service distinct ou utilisez un planificateur externe qui réveille le serveur au moyen d'une requête.

Pings externes et contrôles de maintien en vie

Un moniteur de disponibilité, un contrôle de santé ou un ping de maintien en vie qui appelle périodiquement le serveur réinitialise le délai d'inactivité. Supprimez ces contrôles ou augmentez leur intervalle au-delà de la période d'inactivité si vous souhaitez que le serveur se mette en veille.

Exporters d'observabilité

Un exporter qui diffuse des traces, des journaux ou des métriques vers un point de terminaison distant génère du trafic sortant. Vérifiez qu'il regroupe les données et cesse de les envoyer lorsque le serveur est inactif, au lieu de les vider à intervalle fixe.

Flux persistants

Un flux SSE ouvert, un WebSocket ou toute autre connexion persistante maintient le trafic ouvert jusqu'à sa fermeture. Une réponse en streaming qui reste abonnée en arrière-plan garde la connexion active. Vérifiez que les flux se ferment lorsque le client se déconnecte et qu'aucun flux ne reste ouvert lorsque le serveur est autrement inactif.

Intégrations de chat

Certaines intégrations de chat maintiennent une connexion persistante et envoient régulièrement un signal, ce qui garde le serveur actif. Par exemple, une application Slack en Socket Mode ouvre un WebSocket et émet un ping environ toutes les trente secondes, tandis qu'un bot Discord maintient le WebSocket de sa passerelle ouvert avec un signal périodique. Le socket ouvert comme le signal empêchent la mise en veille.

Si vous souhaitez que le serveur se mette en veille, recevez les événements par webhooks HTTP plutôt que par connexion persistante lorsque l'intégration le permet. Les applications Slack peuvent par exemple utiliser l'Events API avec une URL de requête à la place de Socket Mode. Si votre application nécessite une connexion persistante, maintenez le service actif grâce au module complémentaire Persistent Server décrit ci-dessous.

Inspecter les connexions actives

Pour déterminer ce qui maintient le serveur actif, inspectez les handles actifs du processus pendant les périodes d'inactivité. Un handle qui subsiste après la fin de toutes les requêtes est une piste à examiner. Les sockets ouverts signalent une connexion persistante à fermer, tandis que les minuteurs actifs indiquent un setInterval ou un setTimeout qui se reprogramme lui-même.

Ajoutez la fonction d'assistance suivante à votre application, puis observez le journal après l'arrêt du trafic. Tout élément encore répertorié lorsque le serveur est inactif le maintient éveillé :

src/mastra/diagnose-idle.ts

export function logActiveHandles() {
  // process._getActiveHandles is undocumented but useful for diagnosis.
  const handles = (process as any)._getActiveHandles() as Array<any>

  const summary = handles.map(handle => {
    const type = handle?.constructor?.name ?? typeof handle
    if (type === 'Socket') {
      return `Socket -> ${handle.remoteAddress}:${handle.remotePort}`
    }
    return type
  })

  console.log(`[idle] ${handles.length} active handles:`, summary)
}

// Log every 30 seconds so you can see what persists while the server is idle.
setInterval(logActiveHandles, 30_000).unref()

Appelez unref() sur l'intervalle de diagnostic afin que la fonction d'assistance ne maintienne pas elle-même le serveur actif.

Maintenir un service actif

Certaines applications ont réellement besoin des connexions ou tâches décrites ci-dessus, par exemple une connexion persistante à une base de données pour réduire la latence de la première requête, un planificateur en arrière-plan ou un flux de longue durée. Si votre application en dépend, ne forcez pas la mise en veille du service. Utilisez plutôt le module complémentaire Persistent Server pour maintenir le service actif en permanence.

Lorsque le module complémentaire Persistent Server est activé, le service reste actif même en l'absence de trafic. Les connexions persistantes, les tâches planifiées et les flux ouverts continuent donc de fonctionner sans être interrompus par la mise en veille.

CI/CD

Automatisez les déploiements depuis GitHub Actions, GitLab CI ou tout autre Provider de CI. Après votre premier déploiement interactif, la CI/CD a besoin de deux éléments : un jeton d'API et le fichier .mastra-project.json validé dans votre dépôt.

astuce

Si votre code se trouve sur GitHub, l'intégration GitHub permet de déployer à chaque push sans écrire de fichier de Workflow. Utilisez le flux CI/CD fondé sur la CLI ci-dessous si vous avez besoin de GitLab, d'un autre Provider de CI ou d'étapes de build personnalisées avant le déploiement.

Créer un jeton d'API

1. Exécutez localement la commande suivante :

   mastra auth tokens create ci-deploy

   La CLI n'affiche le jeton qu'une fois. Copiez-le immédiatement, car il ne pourra pas être récupéré ultérieurement.

2. Ajoutez le jeton comme secret dans votre Provider de CI. Dans GitHub Actions, ouvrez Settings → Secrets and variables → Actions puis créez un secret nommé MASTRA_API_TOKEN.

3. Vérifiez que votre fichier .mastra-project.json est validé dans le dépôt. La CLI y lit organizationId et projectId afin de cibler le bon projet pendant les déploiements de CI.

L'option --yes

Transmettez --yes (ou -y) pour ignorer toutes les demandes de confirmation. Sans cette option, la CLI attend une saisie interactive et votre job de CI reste bloqué.

mastra server deploy --yes

GitHub Actions

Le Workflow suivant déploie l'application à chaque push vers main :

.github/workflows/deploy-mastra.yml

name: Deploy to Mastra platform

on:
  push:
    branches: [main]
    paths: ['src/mastra/**']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'
      - name: Install dependencies
        run: npm install
      - name: Deploy to Mastra platform
        run: npx mastra server deploy --yes
        env:
          MASTRA_API_TOKEN: ${{ secrets.MASTRA_API_TOKEN }}

Adaptez le filtre paths et working-directory si votre projet Mastra se trouve dans un sous-répertoire, par exemple dans un monorepo.

remarque

Pour les déploiements de Studio, remplacez mastra server deploy par mastra studio deploy. Les options et les variables d'environnement restent identiques.

GitLab CI

Le pipeline suivant effectue un déploiement à chaque push vers main :

.gitlab-ci.yml

deploy:
  image: node:22
  stage: deploy
  only:
    - main
  before_script:
    - npm install
  script:
    - npx mastra server deploy --yes

Ajoutez MASTRA_API_TOKEN comme variable de CI/CD dans Settings → CI/CD → Variables.

Autres Providers de CI

Tout système de CI capable d'exécuter Node.js et des commandes shell fonctionne avec Mastra :

1. Installez les dépendances.
2. Définissez MASTRA_API_TOKEN comme variable d'environnement.
3. Exécutez mastra server deploy --yes (ou mastra studio deploy --yes).

Vérifier le déploiement

Une fois le Workflow terminé, vérifiez le déploiement en appelant le point de terminaison de santé :

curl -f https://<your-project>.server.mastra.cloud/health

Vous pouvez également vérifier le point de terminaison des Agents, qui renvoie leur liste au format JSON :

curl -f https://<your-project>.server.mastra.cloud/api/agents

L'exemple suivant ajoute une étape de vérification à un Workflow GitHub Actions :

- name: Verify deployment
  run: |
    sleep 30
    curl -f https://<your-project>.server.mastra.cloud/health

Remplacer la configuration du projet avec des variables d'environnement

Par défaut, la CLI lit organizationId et projectId dans .mastra-project.json. Pour remplacer ces valeurs, par exemple afin de déployer vers un autre projet depuis le même dépôt, définissez les variables d'environnement suivantes :

Variable	Description
MASTRA_ORG_ID	Remplace l'identifiant de l'organisation lu dans .mastra-project.json.
MASTRA_PROJECT_ID	Remplace l'identifiant du projet lu dans .mastra-project.json.

Voir aussi

• mastra server deploy
• mastra server pause
• mastra server restart
• mastra studio deploy
• mastra auth tokens