PlatformSandbox
Client permettant de provisionner des Sandboxes dans un environnement Mastra Platform. Chaque instance de PlatformSandbox possède une Sandbox distante : start() la provisionne, executeCommand() y exécute des commandes et destroy() la détruit. Construisez des instances supplémentaires pour posséder d'autres Sandboxes distantes. Utilisez clone() pour les dériver d'un template configuré (consultez Clonage).
Les Sandboxes démarrent depuis un checkpoint de recette préconstruit dans lequel Python 3, Node 22, TypeScript, tsx et les Tools de build courants sont déjà installés. Transmettez un id stable pour activer la récupération par checkpoint, afin qu'une nouvelle Sandbox démarre depuis le système de fichiers de la précédente.
Providers associés : RailwaySandbox pour les Sandboxes Railway auto-hébergées, LocalSandbox pour les Sandboxes locales.
Pour plus de détails sur l'interface, consultez l'interface WorkspaceSandbox.
InstallationLien direct vers Installation
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/platform-workspace
pnpm add @mastra/platform-workspace
yarn add @mastra/platform-workspace
bun add @mastra/platform-workspace
Configurez les identifiants de la plateforme. Le token d'accès, l'identifiant du projet et celui de l'environnement utilisent par défaut des variables d'environnement ; un déploiement Mastra Platform peut donc n'utiliser aucune option du constructeur.
- Fichier .env
- Constructeur
MASTRA_PLATFORM_ACCESS_TOKEN=your-platform-access-token
MASTRA_PROJECT_ID=your-project-id
MASTRA_ENVIRONMENT_ID=your-environment-id
new PlatformSandbox({
accessToken: 'your-platform-access-token',
projectId: 'your-project-id',
environmentId: 'your-environment-id',
})
Dans un déploiement Mastra Platform, MASTRA_PLATFORM_ACCESS_TOKEN, MASTRA_PROJECT_ID et MASTRA_ENVIRONMENT_ID sont injectés automatiquement ; le constructeur peut donc être appelé sans options. Pour le développement local, MASTRA_PLATFORM_ACCESS_TOKEN peut contenir un token d'API sk_ provenant de la section Tokens d'API de la page des paramètres de votre organisation.
UtilisationLien direct vers Utilisation
Ajoutez une PlatformSandbox à un Workspace et attribuez-la à un Agent :
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { PlatformSandbox } from '@mastra/platform-workspace'
const workspace = new Workspace({
sandbox: new PlatformSandbox({
// accessToken, projectId, environmentId all fall back to env vars
idleTimeoutMinutes: 30,
}),
})
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)
Réseau privéLien direct vers Réseau privé
Définissez networkIsolation sur PRIVATE pour rejoindre le réseau privé de l'environnement et accéder aux autres services exécutés dans le même environnement Mastra Platform :
const workspace = new Workspace({
sandbox: new PlatformSandbox({
networkIsolation: 'PRIVATE',
}),
})
Le mode ISOLATED par défaut autorise uniquement l'accès sortant à Internet, sans connectivité au réseau privé.
Reconnexion à une Sandbox en cours d'exécutionLien direct vers Reconnexion à une Sandbox en cours d'exécution
Transmettez un sandboxId existant pour vous reconnecter à une Sandbox active au lieu d'en créer une nouvelle :
const sandbox = new PlatformSandbox({
sandboxId: 'sbx_abc123',
})
await sandbox.start()
const result = await sandbox.executeCommand('cat', ['/workspace/state.json'])
Lorsque sandboxId est défini, environmentId n'est pas obligatoire, car la Sandbox existe déjà.
Récupération par checkpointLien direct vers Récupération par checkpoint
La valeur id du constructeur (explicite ou générée automatiquement) est envoyée à la plateforme lors de POST /sandbox comme clé de récupération indicative :
- Si la plateforme reconnaît le
idd'une session précédente, la nouvelle Sandbox démarre depuis le checkpoint le plus récent du système de fichiers de cette ancienne Sandbox, plutôt que depuis la recette de base. - Si le
idn'est pas reconnu, la plateforme démarre une nouvelle Sandbox depuis la recette de base. Les identifiants générés automatiquement ne correspondent jamais ; omettreiddésactive donc la récupération par checkpoint.
Transmettez un id stable afin de préserver le système de fichiers d'une Sandbox entre les sessions ou pendant un cycle destroy()/start() :
const sandbox = new PlatformSandbox({
id: `project-${projectId}`,
})
await sandbox.start() // Boots from the most recent checkpoint for this id, or fresh if unknown
La récupération par checkpoint est moins précise que la reconnexion au moyen de sandboxId. La reconnexion (via sandboxId) rejoint exactement la Sandbox active et ses processus en cours. La récupération par checkpoint construit une toute nouvelle Sandbox et restaure son système de fichiers depuis le dernier checkpoint capturé par la plateforme pour la Sandbox précédente portant ce id. Les processus en cours et les écritures effectuées après le dernier checkpoint ne sont pas restaurés.
Chaque id correspond à un système de fichiers indépendant. La réutilisation du même id pour des Sandboxes sans rapport amène la plateforme à les démarrer depuis le checkpoint les unes des autres.
Clonage pour une flotte de SandboxesLien direct vers Clonage pour une flotte de Sandboxes
clone() renvoie une PlatformSandbox sœur indépendante qui hérite des identifiants et des valeurs par défaut (token d'accès, projet, environnement, isolation réseau, délai d'expiration, instructions, env et délai d'inactivité), avec des remplacements propres à l'instance. La Sandbox renvoyée n'est pas démarrée et se provisionne lors de son propre appel à start() ; clone() n'effectue donc aucune E/S :
const template = new PlatformSandbox({
networkIsolation: 'PRIVATE',
idleTimeoutMinutes: 30,
})
const perProject = template.clone({ id: `project-${projectId}` })
await perProject.start()
Combinez clone() à un id stable pour chaque clone afin d'activer indépendamment la récupération par checkpoint sur chacun d'eux.
Exécution de commandesLien direct vers Exécution de commandes
executeCommand exécute une commande dans la Sandbox distante et renvoie sa sortie. Transmettez args afin que les arguments soient correctement échappés pour le shell :
const result = await sandbox.executeCommand('python', ['analyze.py'], {
timeout: 30_000,
cwd: '/workspace',
env: { INPUT: 'repo' },
})
console.log(result.stdout)
console.log(result.exitCode)
L'argument command est une chaîne shell concaténée telle quelle dans le shell distant. Cela permet d'utiliser des pipes, des redirections et des enchaînements (ls -la | grep foo), mais les entrées non fiables doivent être transmises au moyen de args (échappées en toute sécurité) ou échappées pour le shell par l'appelant. Les valeurs command non fiables permettent l'exécution de commandes shell arbitraires dans la Sandbox.
Paramètres du constructeurLien direct vers Paramètres du constructeur
accessToken?:
projectId?:
environmentId?:
sandboxId?:
idleTimeoutMinutes?:
networkIsolation?:
env?:
timeout?:
instructions?:
id?:
fetch?:
PropriétésLien direct vers Propriétés
id:
name:
provider:
status:
processes:
MéthodesLien direct vers Méthodes
start:
destroy:
stop:
executeCommand:
clone:
getInfo:
getInstructions:
ErreursLien direct vers Erreurs
Les échecs de l'API Platform lèvent PlatformApiError. Les réponses structurées { error: { message, type } } sont analysées dans .code (type lisible par une machine) et .proxyMessage (chaîne lisible par les utilisateurs) ; le corps brut de la réponse reste disponible dans .body :
import { PlatformApiError } from '@mastra/platform-workspace'
try {
await sandbox.executeCommand('cat', ['/missing.txt'])
} catch (err) {
if (err instanceof PlatformApiError) {
if (err.code === 'not_found') {
// handle missing resource
} else if (err.code === 'authentication_error') {
// refresh token
}
console.error(err.status, err.code, err.proxyMessage)
}
}
code et proxyMessage valent undefined lorsque le corps de la réponse n'est pas au format JSON, par exemple pour une réponse HTML 502 provenant d'un répartiteur de charge.
executeCommand s'exécute sur le plan de données direct-exec (un WebSocket vers le tcp-proxy Railway) et peut également lever deux erreurs de Sandbox typées en cas d'échec irrécupérable :
import { SandboxDestroyedError, SandboxExecTransportError } from '@mastra/platform-workspace'
try {
await sandbox.executeCommand('pytest')
} catch (err) {
if (err instanceof SandboxDestroyedError) {
// /exec-lease returned 410; the sandbox has been destroyed.
// The cached sandbox id and lease have already been cleared,
// so reusing the instance will reprovision on the next call.
} else if (err instanceof SandboxExecTransportError) {
// Both the initial WebSocket attempt and the built-in retry
// closed without an exit frame against a live sandbox.
console.error(err.closeCode, err.closeReason, err.wsEndpoint)
}
}
SandboxExecTransportError contient des champs de diagnostic (opened, closeCode, closeReason, wsEndpoint, ainsi que sandboxId, command et attempts) afin que les opérateurs puissent distinguer un plan de données Railway défaillant d'une commande ayant échoué.