VercelSandbox
Exécute des commandes dans Vercel Sandbox, une microVM Firecracker é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.
Cette solution est distincte de VercelServerlessSandbox, 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.
InstallationLien direct vers Installation
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/vercel
pnpm add @mastra/vercel
yarn add @mastra/vercel
bun add @mastra/vercel
AuthentificationLien direct vers 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é)
- Jeton d’accès (.env)
- Constructeur
Pour le développement local, liez le projet et récupérez un jeton de développement :
vercel link
vercel env pull
Sur Vercel, l’authentification est gérée automatiquement ; aucune configuration n’est nécessaire.
Pour les environnements sans OIDC, fournissez les trois valeurs ensemble :
VERCEL_TOKEN=your-token
VERCEL_TEAM_ID=your-team-id
VERCEL_PROJECT_ID=your-project-id
new VercelSandbox({
token: 'your-token',
teamId: 'your-team-id',
projectId: 'your-project-id',
})
UtilisationLien direct vers Utilisation
Ajoutez un VercelSandbox à un workspace et assignez-le à un agent :
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ésLien direct vers 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 :
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 streamingLien direct vers Sortie en streaming
Diffusez la sortie des commandes en temps réel via les rappels onStdout et onStderr :
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 constructeurLien direct vers Paramètres du constructeur
id?:
sandboxName?:
token?:
teamId?:
projectId?:
runtime?:
timeout?:
resources?:
ports?:
env?:
metadata?:
instructions?:
onStart?:
running.onStop?:
onDestroy?:
PropriétésLien direct vers Propriétés
id:
name:
provider:
status:
sandbox:
processes:
Processus en arrière-planLien direct vers 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.
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 pour l’API complète.
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.
LimitesLien direct vers 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 pour connaître les limites et les tarifs actuels.