Skip to main content

🚀 Getting Started with Archon

Build Your AI's Knowledge Base - From zero to operational in under 10 minutes

Quick Start • What's Included • Next Steps • Documentation Guide

🎯What You'll Build

By the end of this guide, you'll have a fully operational Archon system with:

  • ✅ 14 MCP tools enabled and working
  • 🧠 RAG system for intelligent knowledge retrieval
  • 🌐 Archon UI Command Center for knowledge, projects, and tasks
  • 🔥 Real-time Logfire monitoring and debugging
  • 🌐 Modern UI for project and task management

🎯 What is Archon?​

Archon is a Model Context Protocol (MCP) server that creates a centralized knowledge base for your AI coding assistants. Connect Cursor, Windsurf, or Claude Desktop to give your AI agents access to:

  • Your documentation (crawled websites, uploaded PDFs/docs)
  • Smart search capabilities with advanced RAG strategies
  • Task management integrated with your knowledge base
  • Real-time updates as you add new content

⚡ Quick Start​

Prerequisites​

1. Clone & Setup​

git clone https://github.com/coleam00/archon.git
cd archon

# Create environment file
cp .env.example .env

2. Configure Environment​

Edit .env and add your credentials:

# Required
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=your-service-key-here

# Optional (but recommended for monitoring)
OPENAI_API_KEY=sk-proj-your-openai-key
# Unified Logging Configuration (Optional)
LOGFIRE_ENABLED=false              # true=Logfire logging, false=standard logging
LOGFIRE_TOKEN=your-logfire-token-here    # Only required when LOGFIRE_ENABLED=true

3. Set Up Database​

🗄️Database Setup

Create a new Supabase project, then follow these setup steps in order:

Step 1: Initial Setup - Enable RAG Crawl and Document Upload​

Run migration/1_initial_setup.sql - Creates vector database, settings, and core tables

Step 2: Install Projects Module​

Run migration/2_archon_projects.sql - Creates project and task management tables

Step 3: Enable MCP Client Management (Optional)​

Run migration/3_mcp_client_management.sql - Adds MCP client connection management features

🔄 Database Reset (Optional)​

Run migration/RESET_DB.sql - ⚠️ Completely resets database (deletes ALL data!)

🔍 How to run SQL scripts in Supabase
  1. Go to your Supabase Dashboard
  2. Select your project
  3. Navigate to SQL Editor in the left sidebar
  4. Click "New Query"
  5. Copy the contents of each migration file from your local files
  6. Paste and click "Run"
  7. Run each script in order: Step 1 → Step 2 → Step 3 (optional)

For database reset:

  1. Run RESET_DB.sql first to clean everything
  2. Then run migrations 1, 2, 3 in order to rebuild

4. Start Archon​

# Build and start all services
docker compose up --build -d

# View logs (optional)
docker compose logs -f
🔥Hot Module Reload

Archon includes Hot Module Reload (HMR) for both Python and React code. Changes to source files automatically reload without container rebuilds.

No rebuild needed for:

  • Python code changes (.py files)
  • React components (.tsx, .jsx)
  • CSS/Tailwind styles
  • Most configuration changes

Rebuild required for:

  • New dependencies (requirements.txt, package.json)
  • Dockerfile changes
  • Environment variables

5. Access & Configure​

ServiceURLPurpose
🌐 Web Interfacehttp://localhost:3737Main dashboard and controls
📚 Documentationhttp://localhost:3838Complete setup and usage guides
⚡ API Docshttp://localhost:8080/docsFastAPI documentation

Initial Configuration:

  1. Open the Web Interface (http://localhost:3737)
  2. Go to Settings and add your OpenAI API key
  3. Start the MCP server from the MCP Dashboard
  4. Get connection details for your AI client
🎉You're Ready!

Your Archon system is now running with 14 MCP tools available. Your AI agents can now access your knowledge base!

🛠️ What's Included​

When you run docker compose up -d, you get:

Microservices Architecture​

  • Frontend (Port 3737): React dashboard for managing knowledge and tasks
  • API Service (Port 8080): FastAPI server with Socket.IO for real-time features
  • MCP Service (Port 8051): Model Context Protocol server for AI clients
  • Agents Service (Port 8052): AI processing service for document analysis
  • Documentation (Port 3838): Complete Docusaurus documentation site

Key Features​

  • Smart Web Crawling: Automatically detects sitemaps, text files, or webpages
  • Document Processing: Upload PDFs, Word docs, markdown, and text files
  • AI Integration: Connect any MCP-compatible client (Cursor, Windsurf, etc.)
  • Real-time Updates: Socket.IO-based live progress tracking
  • Task Management: Organize projects and tasks with AI agent integration

Architecture Overview​

⚡ Quick Test​

Once everything is running:

  1. Test Document Upload: Go to http://localhost:3737 → Documents → Upload a PDF
  2. Test Web Crawling: Knowledge Base → "Crawl Website" → Enter a docs URL
  3. Test AI Integration: MCP Dashboard → Copy connection config for your AI client

🔌 Connecting to Cursor IDE​

To connect Cursor to your Archon MCP server, add this configuration:

File: ~/.cursor/mcp.json

{
  "mcpServers": {
    "archon": {
      "command": "docker",
      "args": [
        "exec", 
        "-i",
        "-e", "TRANSPORT=stdio",
        "-e", "HOST=localhost", 
        "-e", "PORT=8051",
        "archon-mcp",
        "python", "src/mcp_server.py"
      ]
    }
  }
}

🎯 Next Steps​

Immediate Actions​

  1. 📚 Build Your Knowledge Base - Start crawling and uploading content
  2. 🔌 Connect Your AI Client - Set up Cursor, Windsurf, or Claude Desktop
  3. 📊 Monitor Performance - Set up Logfire for real-time debugging

Building Your Knowledge Base​

Crawl Documentation Sites:

  1. Go to Knowledge Base in the web interface
  2. Click "Crawl Website"
  3. Enter a documentation URL (e.g., https://docs.python.org)
  4. Monitor progress in real-time

Pro Tips:

  • Start with well-structured documentation sites
  • Use sitemap URLs when available (e.g., sitemap.xml)
  • Monitor crawl progress via Socket.IO updates

Advanced Setup​

For production deployments and advanced features:

📖 Documentation Guide​

This documentation is organized for different use cases:

🚀 Getting Started (You Are Here)​

QuickStart guide to get Archon running in minutes

🔌 MCP Integration​

MCP Overview - Connect Cursor, Windsurf, Claude Desktop, and other MCP clients

🧠 RAG & Search​

RAG Strategies - Configure intelligent search and retrieval for optimal AI responses

📊 Configuration & Monitoring​

Configuration Guide - Setup, monitoring, and Logfire integration

🚀 Production Deployment​

Deployment Guide - Scale Archon for team and production use

🛠️ Development​

API Reference - REST API endpoints and development guides Testing Guide - Development setup and testing procedures

🔧 Troubleshooting​

🐳 Container Issues
# Check Docker status
docker --version
docker compose version

# Rebuild containers
docker compose down
docker compose up --build -d

# Check container logs
docker compose logs archon-server
docker compose logs archon-mcp
docker compose logs archon-agents
🔌 Connection Issues
# Verify environment variables
docker compose exec archon-server env | grep -E "(SUPABASE|OPENAI)"

# Check MCP server health
curl http://localhost:8051/sse

# Check API health
curl http://localhost:8080/health

# Check Agents service health
curl http://localhost:8052/health
🧠 Empty RAG Results
# Check available sources
curl http://localhost:8080/api/sources

# Test basic query
curl -X POST http://localhost:8080/api/rag/query \
  -H "Content-Type: application/json" \
  -d '{"query": "test", "match_count": 1}'

💬 Getting Help​

Supercharging AI IDE's with knowledge and tasks
Transform your AI coding experience with Archon