Setup & Installation

This section guides you through setting up SynapseAI for local development. Choose your path based on your needs.

Setup Paths

🚀 Quick Start (30 minutes)

Best for: First-time users, demos, quick testing

Run everything with Docker Compose - no complex setup required.

What you get:

• ✅ Backend API running
• ✅ Frontend interface
• ✅ Redis for sessions
• ✅ MCP servers configured

Start Quick Start →

🔧 Full Development Setup (2 hours)

Best for: Active development, customization, debugging

Set up each component separately for full control and hot reload.

What you get:

• ✅ Backend with debugging enabled
• ✅ Frontend with hot reload
• ✅ MCP servers running locally
• ✅ Full IDE integration

Steps:

1. Prerequisites - Install required tools
2. Backend Setup - Install and configure the API
3. Frontend Setup - Set up the React app
4. MCP Servers - Configure external service clients

System Requirements

Minimum Requirements

• OS: macOS, Linux, or Windows with WSL2
• RAM: 8GB
• Disk: 10GB free space
• CPU: 2 cores

Recommended

• RAM: 16GB or more
• Disk: 20GB+ SSD
• CPU: 4+ cores

What Gets Installed?

Core Components

Backend:

• FastAPI application
• LangGraph AI agent
• Python dependencies (~500MB)

Frontend:

• React application
• Node.js dependencies (~300MB)

Infrastructure:

• Redis (via Docker)
• MCP servers (Commercetools, Voucherify)

External Services

You'll need API keys for:

• ✅ OpenAI, Cerebras, or Groq (for LLM)
• ✅ Commercetools (for e-commerce)
• ✅ Voucherify (for promotions)

Quick Decision Guide

Choose Quick Start if:

• ✅ You want to try SynapseAI quickly
• ✅ You're doing a demo or proof-of-concept
• ✅ You don't need to modify code yet

Choose Full Setup if:

• ✅ You're developing or customizing SynapseAI
• ✅ You need debugging and hot reload
• ✅ You want to understand each component
• ✅ You're preparing for production deployment

After Setup

Once your environment is running, you can:

1. Try the Chat Interface - Order products using natural language
2. Explore the Admin Panel - Manage campaigns and view analytics
3. Review Architecture - Understand how components interact
4. Customize Features - Extend the agent with new capabilities

Common Issues

Port Conflicts

If ports 8001, 3000, or 5173 are in use:

• Stop conflicting services
• Or modify port configuration in .env files

API Key Issues

Ensure all required API keys are set in .env:

# Check backend/.env
cat backend/.env | grep API_KEY

Docker Issues

• Ensure Docker is running: docker ps
• Check disk space: docker system df
• Clean up: docker system prune -a

Getting Help

Stuck? Check these resources:

• 📖 Troubleshooting Guide
• 💬 Slack: #synapseai-support
• 📧 Email: support@synapseai.com

Next Steps