Mastra with Edgenivo Sandbox

Give a Mastra agent a workspace that executes commands in Edgenivo Sandbox. The VercelSandbox adapter from @mastra/vercel runs commands in an isolated microVM, while your application runs the agent and calls models through AI Gateway.

Use VercelSandbox for this integration. Mastra also exports VercelServerlessSandbox, which uses Edgenivo Functions and has a different execution model.

Use a JavaScript or TypeScript project with Node.js 22.13 or later, a Edgenivo account, and the Edgenivo CLI. You'll also need an AI Gateway API key.

Install Mastra and its Edgenivo adapter:

pnpm i @mastra/core @mastra/vercel

yarn add @mastra/core @mastra/vercel

npm i @mastra/core @mastra/vercel

bun add @mastra/core @mastra/vercel

From your project directory, link the project to Edgenivo and pull its development environment:

vercel link
vercel env pull

This creates a .env.local file with a VERCEL_OIDC_TOKEN that authenticates the Sandbox SDK. Add your AI Gateway key to the same file:

AI_GATEWAY_API_KEY=your_ai_gateway_api_key_here

Sandbox authentication uses the deployment's OIDC token automatically when your application runs on Edgenivo. For an environment without OIDC, set VERCEL_TOKEN, VERCEL_TEAM_ID, and VERCEL_PROJECT_ID together, following the access token instructions.

Mastra's vercel/ model prefix routes requests through AI Gateway using AI_GATEWAY_API_KEY. The agent uses this key in your application process, so you don't need to pass it into the sandbox.

Create an entry file with the following code. The workspace gives the agent a command execution tool backed by Edgenivo Sandbox:

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: 300_000,
  }),
});
 
const agent = new Agent({
  id: 'sandbox-agent',
  name: 'Sandbox Agent',
  instructions:
    'Use the workspace command tool to run calculations in the sandbox. Report the command output.',
  model: 'vercel/openai/gpt-6.1-terra',
  workspace,
});
 
try {
  await workspace.init();
  const response = await agent.generate(
    'Use Node.js in the sandbox to calculate the sum of 1 through 100 and report the result.',
    { maxSteps: 5 },
  );
  console.log(response.text);
} finally {
  await workspace.destroy();
}

Run the TypeScript example with your environment variables loaded:

pnpm dlx tsx --env-file=.env.local index.mts

For JavaScript, run node --env-file=.env.local index.mjs. The agent runs a Node.js calculation in the sandbox and prints a response containing 5050. The wording can vary between runs.

The finally block calls workspace.destroy() after the response or an error to delete the sandbox and its snapshots. Keep the workspace alive while your application needs it, then destroy it when the session ends. Save any files you need before cleanup.

Use Chat SDK to let people interact with your Mastra agent on Edgenivo from Slack, Discord, or Microsoft Teams. Chat SDK handles platform messages and replies, while Edgenivo Sandbox isolates the commands your agent runs. Keep workspace creation and cleanup tied to your application's session lifecycle.

Mastra's channels integration accepts Chat SDK adapters through channels.adapters and registers their webhook routes. Point the platform's webhook URL to your deployed Mastra server. See Mastra's channels guide for adapter credentials, webhook configuration, and persistent storage.

• See Mastra's Edgenivo Sandbox integration for adapter options, exposed ports, and background processes.
• Read the Mastra workspace reference for workspace tools and lifecycle methods.
• Configure model access with Mastra and AI Gateway.