Frequently Asked Questions
Common questions about ChatRAG features, setup, licensing, and usage.
Can't Find Your Answer?
General Questions
What is ChatRAG?
ChatRAG is a production-ready AI chatbot platform built with Next.js 16, React 19, and TypeScript. It features advanced RAG (Retrieval-Augmented Generation) with HNSW vector search, 100+ AI models via OpenRouter, multi-modal generation, WhatsApp integration, and MCP support.
What makes ChatRAG different from other chatbot platforms?
Key differentiators:
- HNSW Vector Search: 15-28x faster than traditional RAG
- Visual Config UI: No code changes needed for configuration
- White-Label Ready: Complete branding customization
- Multi-Channel: Web, WhatsApp, embed widget
- MCP Integration: Connect external tools (Zapier, custom servers)
- Reasoning Models: Support for o1, o3, Claude thinking, DeepSeek R1
Can I use ChatRAG for commercial projects?
Yes! ChatRAG has a commercial license that allows you to:
- Build unlimited chatbots for yourself or clients
- Full white-label customization
- Access to complete source code
- Cannot: Resell as boilerplate/template
Setup & Configuration
What are the minimum requirements to run ChatRAG?
Essential requirements:
- Node.js 18+ and npm
- Supabase account (free tier works)
- OpenAI API key (for embeddings)
- OpenRouter or direct AI provider API key
- LlamaCloud API key (for document processing)
How long does setup take?
With the Visual Config UI, you can have a working chatbot in 10-15 minutes:
- Clone repository: 2 minutes
- Install dependencies: 3 minutes
- Database setup (Supabase): 5 minutes
- Configure API keys: 5 minutes
- Test and verify: 5 minutes
Do I need to know how to code?
Basic familiarity with command line helps, but the Visual Config UI (npm run config) allows you to configure everything without editing code. You'll need basic dev skills to:
- Run npm commands
- Copy/paste environment variables
- Deploy to Vercel (point and click)
Can I run ChatRAG locally without deploying?
Yes! ChatRAG works perfectly for local development and testing. Just run npm run dev after setup. You only need deployment when you want to make it accessible to others online.
RAG & Documents
What file types can I upload?
ChatRAG supports: PDF, DOCX, TXT, HTML, RTF, and EPUB files through LlamaCloud parsing.
How does the RAG system work?
ChatRAG's RAG pipeline:
- Documents uploaded and parsed by LlamaCloud
- Content split into semantic chunks (2500 chars, 992 overlap)
- OpenAI generates 1536-dim embeddings for each chunk
- Stored with HNSW vector index in Supabase
- User queries matched via semantic search (<50ms)
- Relevant chunks injected into AI prompt
- AI generates response based on document context
Why is HNSW faster than traditional RAG?
HNSW (Hierarchical Navigable Small World) is a graph-based index that provides approximate nearest neighbor search with logarithmic complexity. This means 15-28x faster queries compared to IVFFlat indexes, especially at scale. Query times are typically <50ms even with large document sets.
Can users upload their own documents?
Yes! Set NEXT_PUBLIC_READ_ONLY_DOCUMENTS_ENABLED=false to allow user uploads. Row Level Security ensures users only see their own documents. For admin-only datasets, set it to true.
AI Models & Providers
How many AI models does ChatRAG support?
100+ models through OpenRouter, plus direct API support for OpenAI, Anthropic, and Google. Includes reasoning models (o1, o3, Claude thinking, DeepSeek R1, Gemini Thinking).
Which AI model should I use?
Recommended models by use case:
- General chat: GPT-4o-mini or Claude Sonnet 4.5
- RAG: Claude Sonnet 4.5 (best context understanding)
- WhatsApp: GPT-4o-mini or Gemini Flash (fast, concise)
- Complex reasoning: o1, o3, or Claude with extended thinking
- Cost optimization: Free tier models (Venice, Llama 4)
Can I add custom models?
Yes! Use the Config UI to add models, or manually configure them in 5 locations (.env.local, scripts/init-env.js, src/lib/env.ts, scripts/config-server.js, scripts/config-ui/index.html). The Config UI handles this automatically.
What are reasoning/thinking models?
Reasoning models (like OpenAI's o1/o3, Claude with extended thinking, DeepSeek R1) use additional computation to "think" before responding. They're excellent for complex problem-solving, math, code debugging, and multi-step tasks.
WhatsApp Integration
How does WhatsApp integration work?
ChatRAG uses Bailey's (open-source WhatsApp Web API) deployed on Fly.io or Koyeb. You scan a QR code to link your WhatsApp, and messages are routed between WhatsApp and ChatRAG via webhooks.
Do I need a business WhatsApp account?
No! You can use your personal WhatsApp account. Bailey's connects via WhatsApp Web, so any account works.
Which provider should I use - Fly.io or Koyeb?
Fly.io (recommended) for edge computing with global distribution, persistent volumes, and low latency.Koyeb is simpler with auto-scaling and GitHub integration. Both have free tiers.
Where is the Bailey's repository?
ChatRAG provides a ready-to-deploy Bailey's at github.com/areia-ai/chatrag specifically configured to work with ChatRAG.
MCP Integration
What is MCP?
Model Context Protocol (MCP) is an open standard for connecting AI applications with external tools and data sources. It allows ChatRAG to execute actions in services like Gmail, Google Calendar, Drive, and custom APIs.
What comes pre-configured with ChatRAG?
ChatRAG includes pre-configured Zapier MCP support with pattern detection for:
- Gmail (find emails, create drafts, send replies)
- Google Calendar (find events)
- Google Drive (upload files)
Can I add custom MCP servers?
Yes! Use the Config UI to add custom MCP servers with HTTP, SSE, or WebSocket transport. Supports Bearer tokens, API keys, and Basic auth.
Deployment & Hosting
Where can I deploy ChatRAG?
ChatRAG is optimized for Vercel (zero-config deployment), but also works on:
- Vercel (recommended)
- Self-hosting (Docker, PM2, VPS)
- Coolify
- Netlify, Railway, Render
- AWS (Amplify, EC2)
How much does hosting cost?
Vercel: Free tier supports hobby projects. Pro starts at $20/month.
Supabase: Free tier includes 500MB database + 1GB storage.
API costs vary based on usage (OpenAI, OpenRouter, etc.).
Can I self-host completely?
Yes! You can self-host both ChatRAG (Docker/VPS) and Supabase (open-source). You'll still need API keys for AI providers (OpenAI, OpenRouter) and LlamaCloud for document processing.
Customization & Branding
Can I white-label ChatRAG?
Yes! Complete branding customization via Config UI:
- Custom logos (header, AI avatar)
- App name and titles
- Welcome messages
- Colors and themes
- Custom domain
Can I modify the code?
Yes! You have full access to the source code. The license allows modifications for your own use and client projects. Just can't resell the codebase as a template/boilerplate.
Does ChatRAG support multiple languages?
Yes! Users can change the chatbot language in settings. Built-in support for 12+ languages including English, Spanish, French, German, Japanese, Chinese, Arabic, and more. Use Config UI translation tools to add new languages.
Support & Community
Where can I get help?
- Documentation: Complete guides and troubleshooting
- Discord Community: Real-time support and discussions
- GitHub Issues: Bug reports and feature requests
- Email Support: Direct assistance for purchasers
Do you offer updates?
Yes! ChatRAG receives regular updates with new features, bug fixes, and improvements. Updates are available through the repository.
Can I contribute to ChatRAG?
We welcome contributions! Fork the repository, make improvements, and submit pull requests. Check GitHub for contribution guidelines.
Ready to Get Started?
Follow the Quick Start guide to set up your ChatRAG instance in minutes:
- Clone repository and install dependencies
- Set up Supabase database
- Configure API keys via Config UI
- Start chatting with your AI assistant!