Workspaces

Un workspace est un ensemble de ressources d’exécution que la plateforme Mastra provisionne et remet à vos agents lors du déploiement. Chaque environnement reçoit son propre workspace afin que production et staging restent isolés.

Chaque workspace expose deux capacités :

• Un bucket pour le stockage du système de fichiers, encapsulé par PlatformFilesystem. Le bucket est un stockage durable limité à l’environnement, que les agents lisent et dans lequel ils écrivent au fil des exécutions.
• Un pool de sandboxes à la demande pour l’exécution de commandes, encapsulé par PlatformSandbox. Chaque instance PlatformSandbox provisionne son propre sandbox distant avec start() et le détruit avec destroy(). Les agents lancent généralement plusieurs sandboxes par session, les utilisent pour une tâche, puis les abandonnent.

Les workspaces sont limités à un seul environnement ; production et staging ne partagent donc ni buckets ni pools de sandboxes. La plateforme gère le provisionnement, l’authentification et le nettoyage des ressources inactives.

Quand les workspaces sont provisionnés

Les nouveaux projets ont les workspaces activés par défaut. Lorsque vous créez un environnement, la plateforme provisionne automatiquement un bucket. L’image de base du sandbox est préchauffée en arrière-plan afin que le premier appel à PlatformSandbox démarre rapidement.

Les projets existants qui n’ont pas activé cette fonctionnalité affichent une action Enable workspaces dans l’onglet Workspaces. L’activation provisionne un bucket pour chaque environnement du projet.

Si le provisionnement échoue pour un environnement, par exemple lorsque le fournisseur de sandbox est très sollicité, l’onglet Workspaces affiche l’échec et propose une nouvelle tentative. L’environnement est tout de même créé. Seul le workspace reste indisponible jusqu’à votre nouvelle tentative.

Utiliser le workspace dans votre code

Installez le package provider :

npm

npm install @mastra/platform-workspace

pnpm

pnpm add @mastra/platform-workspace

Yarn

yarn add @mastra/platform-workspace

Bun

bun add @mastra/platform-workspace

Composez les providers dans un workspace et enregistrez-le auprès de Mastra :

src/mastra/workspace.ts

import { Workspace } from '@mastra/core/workspace'
import { PlatformFilesystem, PlatformSandbox } from '@mastra/platform-workspace'

export const workspace = new Workspace({
  filesystem: new PlatformFilesystem(),
  sandbox: new PlatformSandbox(),
})

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { workspace } from './workspace'

export const mastra = new Mastra({
  workspace,
})

PlatformFilesystem et PlatformSandbox lisent leur configuration depuis les variables d’environnement ; vous ne transmettez donc aucune option sur la plateforme. Celle-ci les injecte lors du déploiement. Consultez Variables d’environnement.

Un bucket, de nombreux sandboxes

PlatformFilesystem et PlatformSandbox ont des cycles de vie différents, ce qui importe lors de la conception des agents.

PlatformFilesystem est un handle de longue durée vers le bucket de l’environnement. Toutes les requêtes, tous les agents et tous les sandboxes de l’environnement lisent et écrivent dans le même stockage d’objets. Tout ce qu’un agent écrit est visible à la requête suivante, sauf suppression explicite.

PlatformSandbox est un client pour provisionner des sandboxes éphémères. Chaque instance PlatformSandbox possède un sandbox distant :

• start() provisionne un nouveau sandbox, ou s’y rattache lorsque vous avez transmis sandboxId.
• executeCommand() y exécute des commandes.
• destroy() détruit le sandbox. stop() est un alias.

Le sandbox transmis à Workspace fournit les tools qu’un agent utilise dans sa propre requête. Lorsque votre agent a besoin d’un autre environnement isolé, par exemple un workspace par tâche, un tenant par utilisateur ou un job d’arrière-plan qui ne doit pas toucher l’état shell de l’appelant, construisez un autre PlatformSandbox :

src/mastra/tools/run-in-fresh-sandbox.ts

import { PlatformSandbox } from '@mastra/platform-workspace'

export async function runInFreshSandbox(command: string) {
  const sandbox = new PlatformSandbox()
  await sandbox.start()
  try {
    return await sandbox.executeCommand(command)
  } finally {
    await sandbox.destroy()
  }
}

Vous pouvez aussi cloner un sandbox configuré comme modèle pour une flotte, afin que les clones héritent des identifiants, de l’environnement, de l’isolation réseau et des valeurs par défaut sans les répéter :

const template = new PlatformSandbox({ networkIsolation: 'PRIVATE' })

const perProjectSandbox = template.clone({ id: `project-${projectId}` })
await perProjectSandbox.start()

Consultez la référence de PlatformSandbox pour le cycle de vie complet, la récupération de checkpoints, le rattachement et les options de clonage.

Variables d’environnement

Chaque déploiement exécuté sur un environnement de plateforme avec un workspace reçoit automatiquement ces variables :

Variable	Contenu
MASTRA_PLATFORM_ACCESS_TOKEN	JSON Web Token (JWT) émis par la plateforme et utilisé par les providers de workspace pour s’authentifier. Le token est limité à l’organisation et au projet du déploiement.
MASTRA_PROJECT_ID	Projet auquel appartient le déploiement.
MASTRA_ENVIRONMENT_ID	Environnement auquel appartient le déploiement. Sélectionne le pool de sandboxes utilisé par la plateforme.
MASTRA_PLATFORM_BUCKET_NAME	Nom du bucket attaché à l’environnement. Sélectionne le bucket lu et écrit par PlatformFilesystem.

Ces noms sont réservés. Si votre projet définit explicitement l’un d’eux, les valeurs gérées par la plateforme sont prioritaires.

Développement local

Réutilisez les mêmes providers localement en plaçant les quatre variables dans votre fichier .env. Obtenez les valeurs du projet, de l’environnement et du bucket depuis l’onglet Workspaces de votre projet. Pour MASTRA_PLATFORM_ACCESS_TOKEN, créez un token d’API sk_ dans la page des paramètres de votre organisation, sous API Tokens. Les déploiements de plateforme utilisent plutôt un JWT injecté.

.env

MASTRA_PLATFORM_ACCESS_TOKEN=sk_your-api-token
MASTRA_PROJECT_ID=your-project-id
MASTRA_ENVIRONMENT_ID=your-environment-id
MASTRA_PLATFORM_BUCKET_NAME=your-bucket-name

PlatformFilesystem et PlatformSandbox se comportent de la même façon localement et sur la plateforme : ils se connectent au même bucket et au même pool de sandboxes pour cet environnement. Utilisez les variables d’un environnement staging ou preview pour les exécutions locales si vous souhaitez isoler les données de production.

Pour une boucle entièrement hors ligne qui ne touche jamais la plateforme, remplacez les providers par LocalFilesystem et LocalSandbox dans un build local.

Inspecter le workspace

L’onglet Workspaces de votre projet de plateforme affiche, pour chaque environnement :

• L’état du bucket et son contenu, avec des actions d’envoi, de téléchargement et de suppression.
• Les sessions de sandbox récentes avec leur commande, leur code de sortie et leur durée.
• Les échecs de provisionnement avec une action Retry.

Voir aussi

• PlatformFilesystem : référence du provider de système de fichiers.
• PlatformSandbox : référence du provider de sandbox, y compris la récupération de checkpoints et le clonage.
• Environnements : comment les environnements limitent la portée des workspaces, variables et bases de données.