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

# VercelSandbox

Exécute des commandes dans [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox), une microVM [Firecracker](https://firecracker-microvm.github.io/) éphémère exécutant Amazon Linux 2023. Fournit un système de fichiers persistant pendant la session, un accès `sudo`, des ports exposés et des processus en arrière-plan. Pour en savoir plus sur l’interface, consultez l’[interface WorkspaceSandbox](https://mastra.zisheng.pro/fr/reference/workspace/sandbox).

> **Remarque:** Cette solution est distincte de [`VercelServerlessSandbox`](https://mastra.zisheng.pro/fr/reference/workspace/vercel-serverless), qui exécute les commandes sous forme de **fonctions** serverless Vercel sans état. `VercelSandbox` exécute une microVM Linux complète avec un système de fichiers persistant et des processus de longue durée.

## Installation

**npm**:

```bash
npm install @mastra/vercel
```

**pnpm**:

```bash
pnpm add @mastra/vercel
```

**Yarn**:

```bash
yarn add @mastra/vercel
```

**Bun**:

```bash
bun add @mastra/vercel
```

## Authentification

Le SDK `@vercel/sandbox` utilise automatiquement un jeton OIDC Vercel lorsqu’aucun identifiant explicite n’est fourni. Si vous fournissez `token`, `teamId` ou `projectId`, fournissez les trois valeurs ensemble.

**OIDC (recommandé)**:

Pour le développement local, liez le projet et récupérez un jeton de développement :

```bash
vercel link
vercel env pull
```

Sur Vercel, l’authentification est gérée automatiquement ; aucune configuration n’est nécessaire.

**Jeton d’accès (.env)**:

Pour les environnements sans OIDC, fournissez les trois valeurs ensemble :

```bash
VERCEL_TOKEN=your-token
VERCEL_TEAM_ID=your-team-id
VERCEL_PROJECT_ID=your-project-id
```

**Constructeur**:

```typescript
new VercelSandbox({
  token: 'your-token',
  teamId: 'your-team-id',
  projectId: 'your-project-id',
})
```

## Utilisation

Ajoutez un `VercelSandbox` à un workspace et assignez-le à un agent :

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { VercelSandbox } from '@mastra/vercel'

const workspace = new Workspace({
  sandbox: new VercelSandbox({
    runtime: 'node24',
    timeout: 600_000,
  }),
})

const agent = new Agent({
  id: 'code-agent',
  name: 'Code Agent',
  instructions: 'You are a coding assistant working in this workspace.',
  model: 'anthropic/claude-sonnet-4-6',
  workspace,
})

const response = await agent.generate('Print "Hello, world!" and show the Node.js version.')

console.log(response.text)
```

### Ressources et ports exposés

Allouez des vCPU (2 048 Mo de mémoire par vCPU) et exposez des ports pour atteindre les services réseau exécutés dans la sandbox :

```typescript
const sandbox = new VercelSandbox({
  runtime: 'node24',
  resources: { vcpus: 4 },
  ports: [3000],
})

const workspace = new Workspace({ sandbox })
await sandbox.start()

// The public HTTPS domain for an exposed port is available via getInfo()
const { metadata } = sandbox.getInfo()
console.log(metadata?.domains) // { 3000: 'https://....vercel.run' }
```

### Sortie en streaming

Diffusez la sortie des commandes en temps réel via les rappels `onStdout` et `onStderr` :

```typescript
await sandbox.executeCommand('sh', ['-c', 'for i in 1 2 3; do echo "line $i"; sleep 1; done'], {
  onStdout: chunk => process.stdout.write(chunk),
  onStderr: chunk => process.stderr.write(chunk),
})
```

Les deux rappels sont facultatifs et peuvent être utilisés indépendamment.

## Paramètres du constructeur

**id** (`string`): Identifiant unique de cette instance de sandbox. (Default: `Généré automatiquement`)

**sandboxName** (`string`): Nom facultatif transmis à l’API Vercel. Généré automatiquement s’il est omis.

**token** (`string`): Jeton de l’API Vercel. Utilise à défaut la variable d’environnement VERCEL\_TOKEN. Omettez-le pour utiliser le jeton OIDC.

**teamId** (`string`): ID de l’équipe Vercel. Utilise à défaut la variable d’environnement VERCEL\_TEAM\_ID.

**projectId** (`string`): ID du projet Vercel. Utilise à défaut la variable d’environnement VERCEL\_PROJECT\_ID.

**runtime** (`'node24' | 'node22' | 'node26' | 'python3.13'`): Environnement d’exécution de la sandbox. (Default: `'node24'`)

**timeout** (`number`): Délai en millisecondes avant l’arrêt automatique de la sandbox. (Default: `300000 (5 minutes)`)

**resources** (`{ vcpus?: number }`): Allocation des ressources. Chaque vCPU dispose de 2 048 Mo de mémoire.

**ports** (`number[]`): Ports à exposer depuis la sandbox (jusqu’à 15). Les domaines HTTPS publics sont disponibles via getInfo().metadata.domains.

**env** (`Record<string, string>`): Variables d’environnement par défaut héritées par toutes les commandes. (Default: `{}`)

**metadata** (`Record<string, unknown>`): Métadonnées personnalisées exposées via getInfo(). (Default: `{}`)

**instructions** (`string | ((opts) => string)`): Remplace les instructions par défaut renvoyées par getInstructions(). Fournissez une chaîne pour les remplacer ou une fonction pour étendre les valeurs par défaut.

**onStart** (`SandboxLifecycleHook`): Hook de cycle de vie appelé lorsque la sandbox atteint l’état running.

**onStop** (`SandboxLifecycleHook`): Hook de cycle de vie appelé avant l’arrêt de la sandbox.

**onDestroy** (`SandboxLifecycleHook`): Hook de cycle de vie appelé avant la destruction de la sandbox.

## Propriétés

**id** (`string`): Identifiant de l’instance de sandbox.

**name** (`'VercelSandbox'`): Nom lisible par les humains.

**provider** (`'vercel-sandbox'`): Identifiant du type de fournisseur.

**status** (`ProviderStatus`): 'pending' | 'starting' | 'running' | 'stopping' | 'stopped' | 'destroying' | 'destroyed' | 'error'

**sandbox** (`Sandbox`): L’instance Sandbox sous-jacente de @vercel/sandbox. Déclenche SandboxNotReadyError si la sandbox n’a pas été démarrée.

**processes** (`VercelSandboxProcessManager`): Gestionnaire des processus en arrière-plan. Consultez la référence de SandboxProcessManager.

## Processus en arrière-plan

`VercelSandbox` inclut un gestionnaire permettant de lancer et de gérer des processus en arrière-plan. Chaque processus lancé s’exécute sous la forme d’une commande détachée dans la microVM, dont la sortie est diffusée dans les journaux de commandes.

```typescript
const sandbox = new VercelSandbox({ runtime: 'node24', ports: [3000] })
await sandbox.start()

const handle = await sandbox.processes.spawn('node server.js', {
  env: { PORT: '3000' },
  onStdout: data => console.log(data),
})

console.log(handle.stdout)
await handle.kill()
```

Consultez la [référence de `SandboxProcessManager`](https://mastra.zisheng.pro/fr/reference/workspace/process-manager) pour l’API complète.

> **Remarque:** Le SDK Vercel Sandbox n’expose pas de canal stdin pour les commandes en cours d’exécution ; `handle.sendStdin()` déclenche donc une erreur. Le montage du système de fichiers (FUSE) n’est pas non plus pris en charge par ce fournisseur.

## Limites

- Jusqu’à 32 vCPU, avec 2 048 Mo de mémoire par vCPU.
- Jusqu’à 15 ports exposés.
- Le système de fichiers est éphémère. Il persiste uniquement pendant la session et est perdu lorsque la sandbox s’arrête.
- La durée d’exécution maximale dépend de l’offre (45 minutes avec Hobby, jusqu’à 24 heures avec Pro et Enterprise) ; la valeur par défaut est de 5 minutes.

Consultez la [documentation Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) pour connaître les limites et les tarifs actuels.