Aller au contenu principal

ModalSandbox

Exécute des commandes dans des sandboxes cloud Modal isolées. Fournit des environnements sécurisés et éphémères reposant sur l'infrastructure de Modal. Pour plus de détails sur l'interface, consultez l'interface WorkspaceSandbox.

Installation
Lien direct vers Installation

npm install @mastra/modal

Utilisation
Lien direct vers Utilisation

Ajoutez une ModalSandbox à un Workspace et attribuez-la à un agent :

import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { ModalSandbox } from '@mastra/modal'

const workspace = new Workspace({
  sandbox: new ModalSandbox({
    id: 'dev-sandbox',
    baseImage: 'ubuntu:22.04',
    timeoutMs: 60_000,
  }),
})

const agent = new Agent({
  id: 'dev-agent',
  model: 'anthropic/claude-opus-4-7',
  workspace,
})

Authentification
Lien direct vers Authentification

Définissez les identifiants Modal à l'aide de variables d'environnement ou des options du constructeur :

MODAL_TOKEN_ID=ak-...
MODAL_TOKEN_SECRET=as-...

Ou transmettez-les directement :

const sandbox = new ModalSandbox({
  tokenId: process.env.MODAL_TOKEN_ID,
  tokenSecret: process.env.MODAL_TOKEN_SECRET,
})

Obtenez vos identifiants depuis le tableau de bord Modal.

Paramètres du constructeur
Lien direct vers Paramètres du constructeur

id?:

string
= Généré automatiquement
Identifiant ou nom unique de cette sandbox. Utilisé comme nom de sandbox Modal afin de pouvoir s'y reconnecter lors des appels ultérieurs à start().

appName?:

string
= 'mastra'
Nom de l'application Modal à associer aux sandboxes.

baseImage?:

string
= 'ubuntu:22.04'
Image Docker à utiliser pour la sandbox.

timeoutMs?:

number
= 300000 (5 minutes)
Durée de vie maximale en temps réel, en millisecondes. La sandbox est arrêtée lorsque ce délai expire, quelle que soit son activité. Le maximum autorisé par Modal est de 24 heures (86_400_000).

env?:

Record<string, string>
Variables d'environnement intégrées à la sandbox lors de sa création.

workdir?:

string
Répertoire de travail par défaut dans la sandbox.

tokenId?:

string
Identifiant du jeton Modal. Utilise la variable d'environnement MODAL_TOKEN_ID à défaut.

tokenSecret?:

string
Secret du jeton Modal. Utilise la variable d'environnement MODAL_TOKEN_SECRET à défaut.

instructions?:

string | function
Instructions personnalisées renvoyées par getInstructions(). Transmettez une chaîne pour remplacer entièrement les instructions par défaut, ou une fonction pour les étendre.

onStart?:

function
Hook de cycle de vie appelé une fois que la sandbox atteint l'état d'exécution.

onStop?:

function
Hook de cycle de vie appelé avant l'arrêt de la sandbox.

onDestroy?:

function
Hook de cycle de vie appelé avant la destruction de la sandbox.

Propriétés
Lien direct vers Propriétés

id:

string
Identifiant de l'instance de sandbox.

name:

string
Nom du Provider ('ModalSandbox')

provider:

string
Identifiant du Provider ('modal')

status:

ProviderStatus
'pending' | 'starting' | 'running' | 'stopping' | 'stopped' | 'destroying' | 'destroyed' | 'error'

modal:

Sandbox
Instance Modal Sandbox sous-jacente. Lève SandboxNotReadyError si la sandbox n'a pas été démarrée.

processes:

ModalProcessManager
Gestionnaire de processus d'arrière-plan. Consultez la référence de SandboxProcessManager.

Cycle de vie de la sandbox
Lien direct vers Cycle de vie de la sandbox

  • _start() : tente de se reconnecter à une sandbox en cours d'exécution. Si aucune n'est trouvée, crée une sandbox à partir du snapshot le plus récent (s'il en existe un provenant d'un précédent appel à _stop()), ou à partir de baseImage.
  • _stop() : crée un snapshot du système de fichiers, puis arrête la sandbox. Le snapshot est conservé en mémoire dans la même instance pour les prochains démarrages.
  • _destroy() : arrête la sandbox et supprime tout snapshot.
const sandbox = new ModalSandbox({
  id: 'dev-sandbox',
  baseImage: 'ubuntu:22.04',
  timeoutMs: 300_000,
})

await sandbox._start()
await sandbox.processes.spawn('npm install')
await sandbox._stop()
await sandbox._start()

Processus d'arrière-plan
Lien direct vers Processus d'arrière-plan

ModalSandbox comprend un gestionnaire de processus intégré permettant de lancer et de gérer des processus d'arrière-plan. Chaque appel à spawn() crée un nouveau ContainerProcess par l'intermédiaire de l'API Sandbox.exec() du SDK Modal.

const sandbox = new ModalSandbox({ id: 'dev-sandbox' })
await sandbox._start()

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

// Wait for the process to complete
const result = await handle.wait()
console.log(result.exitCode)

// Kill the process
await handle.kill()
remarque

sendStdin() n'est pas pris en charge. Le SDK JS de Modal n'expose pas stdin sur Sandbox.exec().

Consultez la référence de SandboxProcessManager pour découvrir l'API complète.

On this page