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

# DaytonaSandbox

Exécute des commandes dans des Sandboxes cloud [Daytona](https://www.daytona.io) isolées. Prend en charge plusieurs environnements d'exécution, la configuration des ressources, les volumes, les snapshots, la sortie en streaming, la reconnexion aux Sandboxes, le montage de systèmes de fichiers (S3, GCS) et l'isolation réseau. Pour plus de détails sur l'interface, consultez [l'interface WorkspaceSandbox](https://mastra.zisheng.pro/fr/reference/workspace/sandbox).

## Installation

**npm**:

```bash
npm install @mastra/daytona
```

**pnpm**:

```bash
pnpm add @mastra/daytona
```

**Yarn**:

```bash
yarn add @mastra/daytona
```

**Bun**:

```bash
bun add @mastra/daytona
```

Définissez votre clé d'API Daytona de l'une des trois manières suivantes.

**Export du shell**:

```bash
export DAYTONA_API_KEY=your-api-key
```

**Fichier .env**:

```bash
DAYTONA_API_KEY=your-api-key
```

**Constructeur**:

```typescript
new DaytonaSandbox({ apiKey: 'your-api-key' })
```

## Utilisation

Ajoutez une `DaytonaSandbox` à un Workspace et attribuez-la à un Agent :

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { DaytonaSandbox } from '@mastra/daytona'

const workspace = new Workspace({
  sandbox: new DaytonaSandbox({
    language: 'typescript',
    timeout: 120_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 current working directory.',
)

console.log(response.text)
// I'll run both commands simultaneously!
//
// Here are the results:
//
// 1. **Hello, world!** — Successfully printed the message.
// 2. **Current Working Directory** — `/home/daytona`
//
// Both commands ran in parallel and completed successfully!
```

### Avec un snapshot

Utilisez un snapshot préconstruit pour éviter le temps de configuration de l'environnement :

```typescript
const workspace = new Workspace({
  sandbox: new DaytonaSandbox({
    snapshot: 'my-snapshot-id',
    timeout: 60_000,
  }),
})
```

### Image personnalisée avec des ressources

Utilisez une image Docker personnalisée avec une allocation de ressources précise :

```typescript
const workspace = new Workspace({
  sandbox: new DaytonaSandbox({
    image: 'node:20-slim',
    resources: { cpu: 2, memory: 4, disk: 6 },
    language: 'typescript',
  }),
})
```

### Sandbox éphémère

Pour les tâches ponctuelles, la Sandbox est supprimée dès son arrêt :

```typescript
const workspace = new Workspace({
  sandbox: new DaytonaSandbox({
    ephemeral: true,
    language: 'python',
  }),
})
```

### Sortie en streaming

Diffusez la sortie des commandes en temps réel au moyen des callbacks `onStdout` et `onStderr` :

```typescript
await sandbox.executeCommand('bash', ['-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 callbacks sont facultatifs et peuvent être utilisés séparément.

### Reconnexion

Reconnectez-vous à une Sandbox existante en fournissant le même `id`. La Sandbox reprend avec ses fichiers et son état intacts :

```typescript
const sandbox = new DaytonaSandbox({ id: 'my-persistent-sandbox' })

// First session
await sandbox._start()
await sandbox.executeCommand('sh', ['-c', 'echo "session 1" > /tmp/state.txt'])
await sandbox._stop()

// Later — reconnects to the same sandbox
const sandbox2 = new DaytonaSandbox({ id: 'my-persistent-sandbox' })
await sandbox2._start()
const result = await sandbox2.executeCommand('cat', ['/tmp/state.txt'])
console.log(result.stdout) // "session 1"
```

Si la Sandbox est arrêtée ou archivée, elle redémarre automatiquement. Si elle est définitivement inactive (détruite ou en erreur), une nouvelle Sandbox est créée à la place.

### Montage de systèmes de fichiers

Montez des buckets S3 ou GCS comme répertoires locaux dans la Sandbox.

#### Via la configuration des montages du Workspace

La méthode la plus simple : les systèmes de fichiers sont montés automatiquement au démarrage de la Sandbox :

```typescript
import { Workspace } from '@mastra/core/workspace'
import { DaytonaSandbox } from '@mastra/daytona'
import { GCSFilesystem } from '@mastra/gcs'
import { S3Filesystem } from '@mastra/s3'

const workspace = new Workspace({
  mounts: {
    '/s3-data': new S3Filesystem({
      bucket: process.env.S3_BUCKET!,
      region: 'auto',
      accessKeyId: process.env.S3_ACCESS_KEY_ID,
      secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
      endpoint: process.env.S3_ENDPOINT, // e.g. https://<account-id>.r2.cloudflarestorage.com
    }),
    '/gcs-data': new GCSFilesystem({
      bucket: process.env.GCS_BUCKET!,
      projectId: 'my-project-id',
      credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY!),
    }),
  },
  sandbox: new DaytonaSandbox({ language: 'python' }),
})
```

Au démarrage du Workspace, les systèmes de fichiers sont automatiquement montés aux chemins indiqués. Le code exécuté dans la Sandbox peut alors accéder aux fichiers de `/s3-data` et `/gcs-data` comme s'il s'agissait de répertoires locaux.

#### Via `sandbox.mount()`

Effectuez un montage manuel à tout moment après le démarrage de la Sandbox :

#### S3

```typescript
import { S3Filesystem } from '@mastra/s3'

await sandbox.mount(
  new S3Filesystem({
    bucket: process.env.S3_BUCKET!,
    region: 'us-east-1',
    accessKeyId: process.env.S3_ACCESS_KEY_ID,
    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
  }),
  '/data',
)
```

#### Compatible S3 (Cloudflare R2, MinIO)

```typescript
import { S3Filesystem } from '@mastra/s3'

await sandbox.mount(
  new S3Filesystem({
    bucket: process.env.S3_BUCKET!,
    region: 'auto',
    accessKeyId: process.env.S3_ACCESS_KEY_ID,
    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
    endpoint: process.env.S3_ENDPOINT, // e.g. https://<account-id>.r2.cloudflarestorage.com
  }),
  '/data',
)
```

#### GCS

```typescript
import { GCSFilesystem } from '@mastra/gcs'

await sandbox.mount(
  new GCSFilesystem({
    bucket: process.env.GCS_BUCKET!,
    projectId: 'my-project-id',
    credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY!),
  }),
  '/data',
)
```

### Isolation réseau

Limitez l'accès réseau sortant :

```typescript
const workspace = new Workspace({
  sandbox: new DaytonaSandbox({
    networkBlockAll: true,
    networkAllowList: '10.0.0.0/8,192.168.0.0/16',
  }),
})
```

Utilisez `domainAllowList` pour les services dont les adresses IP changent, tels que les registres de packages et les API hébergées :

```typescript
const workspace = new Workspace({
  sandbox: new DaytonaSandbox({
    networkBlockAll: true,
    domainAllowList: 'registry.npmjs.org,*.githubusercontent.com',
  }),
})
```

Les deux listes d'autorisation sont appliquées lors de la création de la Sandbox et conservées par `clone()`. Pour modifier la politique après le démarrage de la Sandbox, utilisez la Sandbox Daytona sous-jacente :

```typescript
await sandbox.instance.updateNetworkSettings({
  domainAllowList: 'api.example.com',
})
```

## Paramètres du constructeur

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

**apiKey** (`string`): Clé d'API Daytona pour l'authentification. Utilise la variable d'environnement DAYTONA\_API\_KEY comme valeur de repli.

**apiUrl** (`string`): Endpoint de l'API Daytona. Utilise la variable d'environnement DAYTONA\_API\_URL comme valeur de repli.

**target** (`string`): Région du runner. Utilise la variable d'environnement DAYTONA\_TARGET comme valeur de repli.

**timeout** (`number`): Délai d'expiration par défaut de l'exécution, en millisecondes. (Default: `300000 (5 minutes)`)

**language** (`'typescript' | 'javascript' | 'python'`): Langage d'exécution de la Sandbox. (Default: `'typescript'`)

**snapshot** (`string`): Identifiant du snapshot préconstruit à partir duquel créer la Sandbox. Prioritaire sur l'image.

**image** (`string`): Image Docker destinée à la création de la Sandbox. Lorsqu'elle est définie, déclenche une création fondée sur l'image. Peut être associée à des ressources. Ignorée lorsqu'un snapshot est défini.

**resources** (`{ cpu?: number; memory?: number; disk?: number }`): Allocation de ressources de la Sandbox (cœurs de CPU, mémoire en Gio, disque en Gio). Utilisée uniquement lorsqu'une image est définie.

**env** (`Record<string, string>`): Variables d'environnement à définir dans la Sandbox. (Default: `{}`)

**labels** (`Record<string, string>`): Labels de métadonnées personnalisés. (Default: `{}`)

**name** (`string`): Nom d'affichage de la Sandbox. (Default: `Identifiant de la Sandbox`)

**user** (`string`): Utilisateur du système d’exploitation sous lequel exécuter les commandes. (Default: `'daytona'`)

**public** (`boolean`): Rend publiques les prévisualisations des ports. (Default: `false`)

**ephemeral** (`boolean`): Supprime la Sandbox dès son arrêt. (Default: `false`)

**autoStopInterval** (`number`): Intervalle d'arrêt automatique en minutes. Définissez 0 pour le désactiver. (Default: `15`)

**autoArchiveInterval** (`number`): Intervalle d'archivage automatique en minutes. Définissez 0 pour obtenir l'intervalle maximal (7 jours). (Default: `7 jours`)

**autoDeleteInterval** (`number`): Intervalle de suppression automatique en minutes. Les valeurs négatives la désactivent. Définissez 0 pour supprimer la Sandbox lors de son arrêt. (Default: `désactivé`)

**volumes** (`Array<{ volumeId: string; mountPath: string }>`): Volumes Daytona à attacher lors de la création de la Sandbox.

**networkBlockAll** (`boolean`): Bloque tout accès réseau sortant depuis la Sandbox. (Default: `false`)

**networkAllowList** (`string`): Liste d'adresses CIDR autorisées, séparées par des virgules, lorsque l'accès réseau est limité.

**domainAllowList** (`string`): Liste de domaines autorisés, séparés par des virgules, lorsque l'accès réseau est limité. Prend en charge les caractères génériques, par exemple \*.githubusercontent.com. Utilisez cette option à la place de networkAllowList pour les services dont les adresses IP changent.

## Propriétés

**id** (`string`): Identifiant de l'instance de Sandbox.

**name** (`string`): Nom du Provider ('DaytonaSandbox').

**provider** (`string`): Identifiant du Provider ('daytona').

**status** (`ProviderStatus`): 'pending' | 'initializing' | 'ready' | 'stopped' | 'destroyed' | 'error'

**instance** (`Sandbox`): Instance de Sandbox Daytona sous-jacente. Lève SandboxNotReadyError si la Sandbox n'a pas été démarrée.

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

## Processus en arrière-plan

`DaytonaSandbox` comprend un gestionnaire de processus intégré permettant de lancer et de gérer des processus en arrière-plan. Ceux-ci s'exécutent dans la Sandbox cloud Daytona au moyen d'une exécution de commandes fondée sur les sessions.

```typescript
const sandbox = new DaytonaSandbox({ language: 'typescript' })
await sandbox.start()

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

// Interact with the process
console.log(handle.stdout)
await handle.sendStdin('input\n')
await handle.kill()
```

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

## Montage du stockage cloud

Les Sandboxes Daytona peuvent monter des buckets S3 ou GCS, rendant le stockage cloud accessible comme des répertoires locaux dans la Sandbox. Cette fonctionnalité permet notamment de :

- Traiter de grands jeux de données stockés dans des buckets cloud
- Écrire les fichiers de sortie directement dans le stockage cloud
- Partager des données entre les sessions de Sandbox

Pour consulter des exemples d'utilisation, reportez-vous au [montage de systèmes de fichiers](#filesystem-mounting).

Les Sandboxes Daytona utilisent FUSE (Filesystem in Userspace) pour monter le stockage cloud :

- **S3/R2** : monté via [s3fs-fuse](https://github.com/s3fs-fuse/s3fs-fuse)
- **GCS** : monté via [gcsfuse](https://github.com/GoogleCloudPlatform/gcsfuse)

Les Tools FUSE nécessaires sont installés automatiquement lors du montage s'ils ne figurent pas déjà dans l'image de la Sandbox.

### Variables d'environnement S3

| Variable               | Description                                  |
| ---------------------- | -------------------------------------------- |
| `S3_BUCKET`            | Nom du bucket                                |
| `S3_REGION`            | Région AWS ou `auto` pour R2/MinIO           |
| `S3_ACCESS_KEY_ID`     | Identifiant de la clé d'accès                |
| `S3_SECRET_ACCESS_KEY` | Clé d'accès secrète                          |
| `S3_ENDPOINT`          | URL de l'endpoint (compatible S3 uniquement) |

### Variables d'environnement GCS

| Variable                  | Description                                                         |
| ------------------------- | ------------------------------------------------------------------- |
| `GCS_BUCKET`              | Nom du bucket                                                       |
| `GCS_SERVICE_ACCOUNT_KEY` | Clé JSON du compte de service (chaîne JSON complète, pas un chemin) |

### Réduction de la latence du démarrage à froid avec un snapshot

Par défaut, `s3fs` et `gcsfuse` sont installés via `apt` lors du premier montage, ce qui allonge le démarrage. Pour éviter ce délai, préinstallez-les dans un snapshot Daytona et transmettez le nom de celui-ci au moyen de l'option `snapshot`.

**Option 1 : build déclaratif de l'image**

```typescript
import { Daytona, Image } from '@daytonaio/sdk'

const template = Image.base('daytonaio/sandbox')
  .runCommands('sudo apt-get update -qq')
  .runCommands('sudo apt-get install -y s3fs')
  // gcsfuse requires the Google Cloud apt repository
  .runCommands(
    'sudo mkdir -p /etc/apt/keyrings && ' +
      'curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg -o /tmp/gcsfuse-key.gpg && ' +
      'sudo gpg --batch --yes --dearmor -o /etc/apt/keyrings/gcsfuse.gpg /tmp/gcsfuse-key.gpg && ' +
      // Use gcsfuse-jammy for Ubuntu, gcsfuse-bookworm for Debian
      'echo "deb [signed-by=/etc/apt/keyrings/gcsfuse.gpg] https://packages.cloud.google.com/apt gcsfuse-jammy main" | sudo tee /etc/apt/sources.list.d/gcsfuse.list',
  )
  .runCommands('sudo apt-get update -qq && sudo apt-get install -y gcsfuse')

const daytona = new Daytona()

await daytona.snapshot.create(
  {
    name: 'cloud-fs-mounting',
    image: template,
  },
  { onLogs: console.log },
)
```

**Option 2 : Dockerfile :** utilisez [`Image.fromDockerfile()`](https://www.daytona.io/docs/typescript-sdk/image#fromdockerfile)

```dockerfile
FROM daytonaio/sandbox
RUN sudo apt-get update -qq
RUN sudo apt-get install -y s3fs
# Use gcsfuse-jammy for Ubuntu, gcsfuse-bookworm for Debian
RUN sudo mkdir -p /etc/apt/keyrings && curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg -o /tmp/gcsfuse-key.gpg && sudo gpg --batch --yes --dearmor -o /etc/apt/keyrings/gcsfuse.gpg /tmp/gcsfuse-key.gpg && echo "deb [signed-by=/etc/apt/keyrings/gcsfuse.gpg] https://packages.cloud.google.com/apt gcsfuse-jammy main" | sudo tee /etc/apt/sources.list.d/gcsfuse.list
RUN sudo apt-get update -qq && sudo apt-get install -y gcsfuse
```

```typescript
import { Daytona, Image } from '@daytonaio/sdk'

const daytona = new Daytona()

await daytona.snapshot.create(
  {
    name: 'cloud-fs-mounting',
    image: Image.fromDockerfile('./Dockerfile'),
  },
  { onLogs: console.log },
)
```

Utilisez ensuite le nom du snapshot dans la configuration de votre Sandbox :

```typescript
const workspace = new Workspace({
  mounts: {
    '/s3-data': new S3Filesystem({/* ... */}),
    '/gcs-data': new GCSFilesystem({/* ... */}),
  },
  sandbox: new DaytonaSandbox({ snapshot: 'cloud-fs-mounting' }),
})
```

## Accès direct au SDK

Accédez à l'instance Daytona `Sandbox` sous-jacente pour les opérations sur le système de fichiers, git et les autres opérations non exposées par l'interface `WorkspaceSandbox` :

```typescript
const daytonaSandbox = sandbox.instance

// Upload a file
await daytonaSandbox.fs.uploadFile(Buffer.from('hello'), '/tmp/hello.txt')

// Run git operations
await daytonaSandbox.git.clone('https://github.com/org/repo', '/workspace/repo')
```

Le getter `instance` lève `SandboxNotReadyError` si la Sandbox n'a pas encore été démarrée.

## Modes de création de la Sandbox

`DaytonaSandbox` sélectionne un mode de création selon les options fournies :

| Options                        | Mode de création                                                |
| ------------------------------ | --------------------------------------------------------------- |
| `snapshot` défini              | Fondé sur un snapshot (le snapshot est prioritaire sur l'image) |
| `image` défini (sans snapshot) | Fondé sur une image (éventuellement avec `resources`)           |
| Aucun des deux                 | Fondé par défaut sur un snapshot                                |

Les ressources sont appliquées uniquement lorsque `image` est défini. Transmettre `resources` sans `image` reste sans effet.

## Voir aussi

- [Référence de SandboxProcessManager](https://mastra.zisheng.pro/fr/reference/workspace/process-manager)
- [Interface WorkspaceSandbox](https://mastra.zisheng.pro/fr/reference/workspace/sandbox)
- [Référence de LocalSandbox](https://mastra.zisheng.pro/fr/reference/workspace/local-sandbox)
- [Référence de S3Filesystem](https://mastra.zisheng.pro/fr/reference/workspace/s3-filesystem)
- [Référence de GCSFilesystem](https://mastra.zisheng.pro/fr/reference/workspace/gcs-filesystem)
- [Présentation de Workspace](https://mastra.zisheng.pro/fr/docs/workspace/overview)