E2B Code Execution Agent
An advanced Mastra template that provides a coding agent capable of planning, writing, executing, and iterating on code in secure, isolated E2B sandboxes with comprehensive file management and development workflow capabilities.
Overview
This template demonstrates how to build an AI coding assistant that can work with real development environments. The agent can create sandboxes, manage files and directories, execute code in multiple languages, and monitor development workflows - all within secure, isolated E2B environments.
Features
- Secure Code Execution: Run Python, JavaScript, and TypeScript code in isolated E2B sandboxes
- Complete File Management: Create, read, write, delete files and directories with batch operations
- Multi-Language Support: Execute code in Python, JavaScript, and TypeScript environments
- Live Development Monitoring: Watch directory changes and monitor development workflows
- Command Execution: Run shell commands, install packages, and manage dependencies
- Memory System: Persistent conversation memory with semantic recall and working memory
- Development Workflows: Professional development patterns with build automation
Prerequisites
- Node.js 20 or higher
- E2B API key (sign up at e2b.dev)
- OpenAI API key
Setup
-
Clone and install dependencies:
git clone https://github.com/mastra-ai/template-coding-agent.git
cd template-coding-agent
pnpm install
-
Set up environment variables:
cp .env.example .env
# Edit .env and add your API keys
E2B_API_KEY="your-e2b-api-key-here"
OPENAI_API_KEY="your-openai-api-key-here"
-
Start the development server:
Architecture
Core Components
Coding Agent (src/mastra/agents/coding-agent.ts)
The main agent with comprehensive development capabilities:
- Sandbox Management: Creates and manages isolated execution environments
- Code Execution: Runs code with real-time output capture
- File Operations: Complete CRUD operations for files and directories
- Development Monitoring: Watches for changes and monitors workflows
- Memory Integration: Maintains conversation context and project history
E2B Tools (src/mastra/tools/e2b.ts)
Complete toolkit for sandbox interaction:
Sandbox Management:
createSandbox - Initialize new isolated environments
- Connection management with timeout handling
Code Execution:
runCode - Execute Python, JavaScript, TypeScript code
- Real-time output capture and error handling
- Environment variable and timeout configuration
File Operations:
writeFile - Create individual files
writeFiles - Batch create multiple files for project setup
readFile - Read file contents for analysis and validation
listFiles - Explore directory structures
deleteFile - Clean up files and directories
createDirectory - Set up project structures
File Information & Monitoring:
getFileInfo - Get detailed file metadata
checkFileExists - Validate file existence for conditional logic
getFileSize - Monitor file sizes and track changes
watchDirectory - Live monitoring of file system changes
Development Workflow:
runCommand - Execute shell commands, build scripts, package management
Memory System
The agent includes a configured memory system:
- Thread Management: Automatic conversation title generation
- Semantic Recall: Search through previous interactions
- Working Memory: Maintains context across interactions
- Vector Storage: Semantic search capabilities with
LibSQLVector
Configuration
Environment Variables
E2B_API_KEY=your_e2b_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
Customization
You can customize the agent behavior by modifying the instructions in src/mastra/agents/coding-agent.ts:
export const codingAgent = new Agent({
name: 'Coding Agent',
instructions: `
// Customize agent instructions here
// Focus on specific languages, frameworks, or development patterns
`,
model: 'openai/gpt-4.1',
// ... other configuration
});
Common Issues
"E2B_API_KEY is not set"
- Make sure you've set the environment variable
- Check that your API key is valid and has sufficient credits
- Verify your E2B account is properly configured
"Sandbox creation failed"
- Check your E2B API key and account status
- Ensure you haven't exceeded sandbox limits
- Verify network connectivity to E2B services
"Code execution timeout"
- Increase timeout values for long-running operations
- Break down complex operations into smaller steps
- Monitor resource usage and optimize code
"File operation errors"
- Validate file paths and permissions
- Check sandbox file system limits
- Ensure directories exist before file operations
"Agent stopping with tool-call reason"
- Increase
maxSteps in the agent configuration
Development
Project Structure
src/mastra/
agents/
coding-agent.ts # Main coding agent with development capabilities
tools/
e2b.ts # Complete E2B sandbox interaction toolkit
index.ts # Mastra configuration with storage and logging