---
title: "Mastra integration"
description: "Build a Mastra coding agent on E2B. The @mastra/e2b package connects a Mastra workspace to a sandbox, so agent commands run in isolation."
url: "https://e2b.dev/integrations/mastra"
---

# Mastra

> Connect a Mastra workspace to an E2B sandbox. With @mastra/e2b, the commands your Mastra agent runs execute in an isolated cloud sandbox instead of on your machine.

Agent frameworks & SDKs · [All integrations](https://e2b.dev/integrations.md)

## About this integration

- **Maintained by:** Mastra
- **How it works:** Mastra workspace sandbox
- **Package:** @mastra/e2b
- **Language:** TypeScript
- **Upstream:** [mastra-ai/mastra · ★ 30k](https://github.com/mastra-ai/mastra)
- **Docs:** [docs.e2b.dev/agents/mastra](https://docs.e2b.dev/agents/mastra)

## Get started

Paste the prompt into your coding agent, or follow the steps yourself.

### Paste this into your coding agent

```text
Add E2B sandboxes to this Mastra project.

1. Install @mastra/core and @mastra/e2b using the project's package manager.
2. The sandbox needs the E2B_API_KEY environment variable. If it isn't set, ask me for my API key from https://console.e2b.dev/?tab=keys. Never hardcode it.
3. Follow the Mastra guide at https://docs.e2b.dev/agents/mastra. Give my agent a Workspace with an E2BSandbox, call workspace.init() before it runs, and workspace.destroy() in a finally block.
4. Run one task and show me the output that came from the sandbox.
```

## Or set it up yourself

### 1. Install Mastra and the E2B provider

```bash
npm init -y && npm pkg set type=module
npm install @mastra/core @mastra/e2b zod
npm install --save-dev tsx typescript @types/node
```

### 2. Set your API keys

```bash
export E2B_API_KEY="e2b_***"
export OPENAI_API_KEY="sk-***"
```

### 3. Give the agent a sandbox workspace

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { E2BSandbox } from '@mastra/e2b'

const workspace = new Workspace({
  sandbox: new E2BSandbox({
    id: `mastra-coding-agent-${Date.now()}`,
    timeout: 600_000,
  }),
})

const agent = new Agent({
  id: 'coding-agent',
  name: 'Coding Agent',
  model: 'openai/gpt-5.4-mini',
  instructions: 'You are a software engineer working in an isolated E2B sandbox.',
  workspace,
})
```

### 4. Run the agent

```typescript
const task = process.argv.slice(2).join(' ') || 'Create a small Express API with a health endpoint and test it'

try {
  await workspace.init()

  const stream = await agent.stream(task, { maxSteps: 30 })

  for await (const chunk of stream.textStream) {
    process.stdout.write(chunk)
  }
} finally {
  await workspace.destroy()
}
```

## What runs in the sandbox

Your Mastra agent runs locally; the commands it chooses run in an isolated sandbox.

- **Commands:** execute_command calls from the agent, routed by @mastra/e2b to E2B command execution.
- **Files:** A sandbox-only workspace has no read_file or write_file tools, so the agent works on files through the shell.
- **Lifetime:** workspace.init() creates or reconnects the sandbox and workspace.destroy() kills it. timeout is in milliseconds.
- **Template:** Pass a template ID or name to E2BSandbox to preinstall runtimes and dependencies.

## More agent frameworks

Other frameworks that run their tools on E2B.

- [Vercel AI SDK](https://e2b.dev/integrations/vercel-ai-sdk.md): Give Vercel AI SDK agents sandbox tools with @e2b/ai-sdk-sandbox. Experimental for AI SDK 7.
- [Flue](https://e2b.dev/integrations/flue.md): Add E2B to a Flue project with one command and run its sandbox agents on it.
- [OpenAI Agents SDK](https://e2b.dev/integrations/openai-agents-sdk.md): Use the built-in E2B sandbox client in the OpenAI Agents SDK to give agents a real machine.

## Links

- [Get API key](https://console.e2b.dev/?tab=keys)
- [Read the docs](https://docs.e2b.dev/agents/mastra)
- [E2B documentation](https://docs.e2b.dev)
