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

# 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`](https://mastra.zisheng.pro/fr/reference/workspace/platform-filesystem). 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`](https://mastra.zisheng.pro/fr/reference/workspace/platform-sandbox). 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](https://mastra.zisheng.pro/fr/docs/mastra-platform/environments) ; `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**:

```bash
npm install @mastra/platform-workspace
```

**pnpm**:

```bash
pnpm add @mastra/platform-workspace
```

**Yarn**:

```bash
yarn add @mastra/platform-workspace
```

**Bun**:

```bash
bun add @mastra/platform-workspace
```

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

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

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

```typescript
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](#environment-variables).

## 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` :

```typescript
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 :

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

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

Consultez la [référence de `PlatformSandbox`](https://mastra.zisheng.pro/fr/reference/workspace/platform-sandbox) 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é.

```bash
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`](https://mastra.zisheng.pro/fr/reference/workspace/local-filesystem) et [`LocalSandbox`](https://mastra.zisheng.pro/fr/reference/workspace/local-sandbox) 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`](https://mastra.zisheng.pro/fr/reference/workspace/platform-filesystem) : référence du provider de système de fichiers.
- [`PlatformSandbox`](https://mastra.zisheng.pro/fr/reference/workspace/platform-sandbox) : référence du provider de sandbox, y compris la récupération de checkpoints et le clonage.
- [Environnements](https://mastra.zisheng.pro/fr/docs/mastra-platform/environments) : comment les environnements limitent la portée des workspaces, variables et bases de données.