Agentic Web Code Agent

An AI-powered coding assistant that writes, executes, and previews code in isolated E2B sandboxes

Build anything with natural language - from web apps to Python scripts. Your AI pair programmer handles the environment setup, coding, and deployment.

---

A production-ready AI coding agent powered by Cedar-OS for the chat interface, Mastra for agent orchestration, and E2B for secure code execution in isolated sandboxes.

Perfect for developers at theagenticweb.dev who want to build AI coding assistants or integrate agentic code generation into their applications.

✨ Features

🎯 AI-Powered Code Generation

• Natural Language to Code - Describe what you want to build and watch the agent create it
• Multi-Language Support - Python, JavaScript, TypeScript, React, Next.js, Vue, Streamlit, Gradio
• Smart Template Selection - Automatically chooses the right environment for your project
• Complete Project Setup - Creates files, installs dependencies, and configures build tools

🔐 Secure Code Execution (E2B Sandboxes)

• Isolated Environments - Each project runs in its own secure E2B sandbox
• Multiple Templates - Pre-configured environments for different tech stacks
  • code-interpreter-v1 - Python data analysis and notebook-style execution
  • nextjs-developer - Next.js web applications with TypeScript and Tailwind
  • streamlit-developer - Python UI apps with live reload
  • gradio-developer - Python demo applications
  • vue-developer - Vue/Nuxt applications
• Sandbox Management - Create, list, reconnect, extend timeout, and terminate sandboxes
• Resource Control - Automatic timeout management and cleanup

💻 Development Workflow

• Complete File Management - Read, write, edit, delete files and directories
• Live Code Execution - Run Python, JavaScript, and TypeScript with real-time output
• Command Execution - Run shell commands, install packages, manage dependencies
• File Watching - Monitor file changes and track development workflows
• Build Automation - TypeScript compilation, package management, dev servers

🎨 Beautiful UI & Preview

• Code Preview - Syntax-highlighted code viewer with file navigation
• Live Web Preview - See your web apps running in real-time with iframe preview
• File Tree Explorer - Navigate project structure with hierarchical file viewer
• Dual View Modes - Switch between Code and Web views seamlessly
• Sandbox Status - Real-time sandbox information and expiration tracking

🔧 Core Platform Features

• 🤖 AI Chat Integration - Built-in chat workflows powered by OpenAI through Mastra agents
• ⚡ Real-time Streaming - Server-sent events (SSE) for streaming AI responses with progress updates
• 💬 Multi-Thread Conversations - Cedar-native thread management with persistence
• 🎯 Thread-Scoped Sandboxes - Each conversation has its own isolated development environment
• 🔄 State Persistence - File trees, code, and sandbox info persist across page refreshes
• ⚠️ Error Handling - Production-ready error boundaries and retry logic
• 🔐 Auth Ready - Auth0 for AI Agents integration (optional)

Quick Start

Prerequisites

• Node.js 18+ (20+ recommended)
• OpenAI API key - Get one here
• E2B API key - Sign up at e2b.dev for secure code execution sandboxes
• pnpm (recommended) or npm

Installation

1. Clone and install dependencies:

git clone <repository-url>
cd agentic-web-code-agent
pnpm install
cd src/backend && pnpm install && cd ../..

2. Set up environment variables:

Copy the template and add your API keys:

cp env.example .env

Required:

OPENAI_API_KEY=your-openai-api-key-here
E2B_API_KEY=your-e2b-api-key-here

Optional features:

# Authentication (see docs/authentication.md)
AUTH0_SECRET=generate-with-openssl
AUTH0_DOMAIN=your-domain.auth0.com
# ... more Auth0 vars

# Production chat history
NEXT_PUBLIC_SUPABASE_URL=your-supabase-url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

3. Start the development servers:

pnpm dev

This runs both:

• Frontend: http://localhost:3000
• Backend API: http://localhost:4111

4. Try it out!

Open http://localhost:3000 and start building with your AI coding assistant. Try:

• "Create a ping pong game using React and TypeScript" - Generates a complete game with canvas rendering
• "Build a lead capture landing page for a pizza restaurant" - Creates a Next.js landing page
• "Make a Python script that analyzes CSV data" - Sets up Python environment and creates data analysis code
• "Create a Streamlit dashboard with charts" - Builds an interactive Python web app
• "Build a todo app with Vue" - Scaffolds a Vue application with components

Project Architecture

Frontend (Next.js + Cedar-OS)

• Cedar Chat Interface: Beautiful, production-ready chat UI with streaming support
• Code Preview Panel: Syntax-highlighted code viewer with file navigation
• Web Preview Panel: Live iframe preview of running web applications
• File Tree Explorer: Hierarchical file browser with selection and navigation
• Thread-Scoped State: Each conversation maintains its own sandbox and files
• View Modes: Toggle between Code view and Web view for different workflows

Backend (Mastra + E2B)

• Coding Agent: Advanced AI agent specialized in software development workflows
• E2B Sandbox Tools: Complete toolkit for managing isolated code execution environments
  • Sandbox lifecycle (create, list, reconnect, terminate)
  • File operations (read, write, delete, directory management)
  • Code execution (Python, JavaScript, TypeScript)
  • Command execution (npm, pip, shell commands)
• Frontend Tools: Cedar-native tools for UI synchronization
  • File tree updates
  • Code preview
  • Sandbox status
  • Live preview URLs
• Template System: Pre-configured environments for different tech stacks

Development

Running the Project

# Start both frontend and backend
pnpm dev

# Run frontend only
pnpm dev:next

# Run backend only
pnpm dev:mastra

📖 Documentation

Comprehensive guides in the /docs folder:

• Getting Started - Detailed setup and installation
• Architecture Overview - Understanding the system design
• Chat History - Persist conversations with localStorage/Supabase
• Tools System - Create custom tools for your agents
• Authentication - Secure your app with Auth0 for AI Agents
• Error Handling - Production-ready error patterns
• Deployment - Deploy to Vercel, Netlify, or self-host

🎯 What's Included

agentic-web-code-agent/
├── docs/                        # 📚 Complete documentation
├── src/
│   ├── app/                    # Next.js app (frontend)
│   │   ├── api/               # API routes (sandbox read-file)
│   │   └── page.tsx           # Main application page
│   ├── backend/                # Mastra backend
│   │   └── src/mastra/
│   │       ├── agents/         # Coding agent with E2B instructions
│   │       └── tools/          # E2B sandbox tools and templates
│   ├── components/             # React components
│   │   ├── CodePreview.tsx    # Code viewer with syntax highlighting
│   │   ├── FileViewer.tsx     # File tree explorer
│   │   ├── WebPreview.tsx     # Live web app preview
│   │   ├── ConversationSidebar.tsx  # Thread management
│   │   └── ErrorBoundary.tsx  # Error handling
│   ├── types/                  # TypeScript definitions
│   │   └── coding.ts          # File, sandbox, and view types
│   └── cedar/                  # Cedar-OS components
└── env.example                 # Environment variables template

🚀 Next Steps

1. Try different templates - Experiment with Next.js, Streamlit, Vue, and Python environments
2. Customize the agent - Modify src/backend/src/mastra/agents/coding-agent.ts instructions
3. Add new E2B templates - Extend src/backend/src/mastra/tools/e2b-templates.ts
4. Create custom tools - Add your own tools to enhance the coding workflow
5. Set up authentication - Secure your app: docs/authentication.md
6. Deploy - Ship to production: docs/deployment.md

🔧 Technology Stack

• Frontend: Next.js 15, React 19, TypeScript, Tailwind CSS
• UI Components: Cedar-OS, Radix UI, Lucide Icons
• Backend: Mastra, OpenAI SDK (GPT-4.1)
• Code Execution: E2B Sandboxes (isolated cloud environments)
• State Management: Cedar-OS state registration with thread-scoped persistence
• Auth: Auth0 for AI Agents (optional)
• Storage: localStorage for thread persistence

🎓 How It Works

1. User Request: Describe what you want to build in natural language
2. Agent Planning: The coding agent analyzes requirements and selects the appropriate template
3. Sandbox Creation: E2B creates an isolated environment with the selected tech stack
4. Code Generation: Agent writes files, installs dependencies, and sets up the project
5. Execution: Code runs in the sandbox and generates a live preview URL
6. UI Sync: Frontend tools update the file tree and display the preview
7. Iteration: Continue refining with natural language requests

🔑 Key Concepts

Thread-Scoped Sandboxes

Each conversation thread maintains its own:

• Active sandbox instance
• File tree state
• Code preview
• Live preview URL

Switch between threads to work on multiple projects simultaneously.

Frontend Tools (Cedar Pattern)

The agent uses special frontend tools to sync backend state with the UI:

• update-file-tree - Displays files in the explorer
• show-file-content - Shows code in the preview panel
• update-sandbox-info - Sets sandbox status and preview URL
• update-sandbox-list - Lists all available sandboxes

E2B Templates

Pre-configured environments that scaffold projects:

• Install required dependencies
• Create initial files
• Configure build tools
• Set default ports

🤝 Contributing

Contributions welcome! Please read our contributing guidelines before submitting PRs.

📄 License

MIT License - see LICENSE file for details.

🔗 Resources

• Cedar-OS Documentation - Chat UI framework
• Mastra Documentation - Agent orchestration
• E2B Documentation - Code execution sandboxes
• The Agentic Web - Learn agentic patterns
• Next.js Documentation - Frontend framework

---

Built for developers who want to ship agentic web apps fast. 🚀