---
title: Mastra with Vercel Sandbox
product: vercel
url: /docs/sandbox/ecosystem/mastra
canonical_url: "https://vercel.com/docs/sandbox/ecosystem/mastra"
last_updated: 2018-10-20
type: how-to
prerequisites:
  - /docs/sandbox/ecosystem
  - /docs/sandbox
related:
  - /docs/sandbox
  - /docs/ai-gateway
  - /docs/accounts
  - /docs/cli
  - /docs/ai-gateway/authentication-and-byok/authentication
summary: Give a Mastra agent an isolated workspace for running commands with the Vercel Sandbox adapter and AI Gateway.
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---

# Mastra with Vercel Sandbox

Give a [Mastra](https://mastra.ai) agent a workspace that executes commands in [Vercel Sandbox](/docs/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](/docs/ai-gateway).

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

## Prerequisites

Use a JavaScript or TypeScript project with Node.js 22.13 or later, a [Vercel account](/docs/accounts), and the [Vercel CLI](/docs/cli). You'll also need an [AI Gateway API key](/docs/ai-gateway/authentication-and-byok/authentication).

## Install the packages

Install Mastra and its Vercel adapter:

**pnpm**

```bash
pnpm i @mastra/core @mastra/vercel
```

**yarn**

```bash
yarn add @mastra/core @mastra/vercel
```

**npm**

```bash
npm i @mastra/core @mastra/vercel
```

**bun**

```bash
bun add @mastra/core @mastra/vercel
```

## Configure authentication

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

```bash filename="terminal"
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:

```bash filename=".env.local"
AI_GATEWAY_API_KEY=your_ai_gateway_api_key_here
```

Sandbox authentication uses the deployment's OIDC token automatically when your application runs on Vercel. For an environment without OIDC, set `VERCEL_TOKEN`, `VERCEL_TEAM_ID`, and `VERCEL_PROJECT_ID` together, following the [access token instructions](/docs/sandbox/concepts/authentication#access-tokens).

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.

## Run an agent with a sandbox workspace

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

**index.mts**

```ts filename="index.mts" framework=all
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();
}
```

**index.mjs**

```js filename="index.mjs" framework=all
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:

```bash filename="terminal"
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.

## Clean up the workspace

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.

## Connect your agent on Vercel to chat platforms

Use [Chat SDK](/docs/chat-sdk) to let people interact with your Mastra agent on Vercel from Slack, Discord, or Microsoft Teams. Chat SDK handles platform messages and replies, while Vercel 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](https://mastra.ai/docs/channels) for adapter credentials, webhook configuration, and persistent storage.

## Next steps

- See [Mastra's Vercel Sandbox integration](https://mastra.ai/integrations/sandboxes/vercel#vercel-sandbox) for adapter options, exposed ports, and background processes.
- Read the [Mastra workspace reference](https://mastra.ai/reference/workspace/workspace-class) for workspace tools and lifecycle methods.
- Configure model access with [Mastra and AI Gateway](/docs/ai-gateway/ecosystem/framework-integrations/mastra).


---

[View full sitemap](/docs/sitemap)


If you encounter incorrect information, can’t find what you need, need a capability Vercel doesn’t currently offer, or have any other feedback to report, please do it by following the instructions at https://vercel.com/feedback.md.