Back
gh

coleam00/Archon: Beta release of Archon OS - the knowledge and task management backbone for AI coding assistants.

Beta release of Archon OS - the knowledge and task management backbone for AI coding assistants. - coleam00/Archon

by coleam00 github.com 2,239 words
View original

Archon Main Graphic

coleam00%2FArchon | Trendshift

Power up your AI coding assistants with your own custom knowledge base and task management as an MCP server

Quick Start • Upgrading • What’s Included • Architecture • Troubleshooting

🎯 What is Archon?

Archon is currently in beta! Expect things to not work 100%, and please feel free to share any feedback and contribute with fixes/new features! Thank you to everyone for all the excitement we have for Archon already, as well as the bug reports, PRs, and discussions. It’s a lot for our small team to get through but we’re committed to addressing everything and making Archon into the best tool it possibly can be!

Archon is the command center for AI coding assistants. For you, it’s a sleek interface to manage knowledge, context, and tasks for your projects. For the AI coding assistant(s), it’s a Model Context Protocol (MCP) server to collaborate on and leverage the same knowledge, context, and tasks. Connect Claude Code, Kiro, Cursor, Windsurf, etc. to give your AI agents access to:

This new vision for Archon replaces the old one (the agenteer). Archon used to be the AI agent that builds other agents, and now you can use Archon to do that and more.

It doesn’t matter what you’re building or if it’s a new/existing codebase - Archon’s knowledge and task management capabilities will improve the output of any AI driven coding.

🔗 Important Links

Quick Start

Archon Setup Tutorial
📺 Click to watch the setup tutorial on YouTube
-> Example AI coding workflow in the video <-

Prerequisites

Setup Instructions

  1. Clone Repository: 
    git clone -b stable https://github.com/coleam00/archon.git
    cd archon
    Note: The stable branch is recommended for using Archon. If you want to contribute or try the latest features, use the main branch with git clone https://github.com/coleam00/archon.git
  2. Environment Configuration: 
    cp .env.example .env
# Edit .env and add your Supabase credentials:
# SUPABASE_URL=https://your-project.supabase.co
# SUPABASE_SERVICE_KEY=your-service-key-here
    IMPORTANT NOTES:
    • For cloud Supabase: They recently introduced a new type of service role key but use the legacy one (the longer one).
      • For local Supabase: Set SUPABASE_URL to http://host.docker.internal:8000 (unless you have an IP address set up). To get SUPABASE_SERVICE_KEY run supabase status -o env.
  3. Database Setup: In your Supabase project SQL Editor, copy, paste, and execute the contents of migration/complete_setup.sql
  4. Start Services (choose one): Full Docker Mode (Recommended for Normal Archon Usage) 
    docker compose up --build -d
    This starts all core microservices in Docker:
    • Server: Core API and business logic (Port: 8181)
      • MCP Server: Protocol interface for AI clients (Port: 8051)
      • UI: Web interface (Port: 3737) Ports are configurable in your.env as well!
  5. Configure API Keys:
    • Open http://localhost:3737
      • You’ll automatically be brought through an onboarding flow to set your API key (OpenAI is default)

⚡ Quick Test

Once everything is running:

  1. Test Web Crawling: Go to http://localhost:3737 → Knowledge Base → “Crawl Website” → Enter a doc URL (such as https://ai.pydantic.dev/llms.txt)
  2. Test Document Upload: Knowledge Base → Upload a PDF
  3. Test Projects: Projects → Create a new project and add tasks
  4. Integrate with your AI coding assistant: MCP Dashboard → Copy connection config for your AI coding assistant

Installing Make

🛠️ Make installation (OPTIONAL - For Dev Workflows)

Windows

# Option 1: Using Chocolatey
choco install make

# Option 2: Using Scoop
scoop install make

# Option 3: Using WSL2
wsl --install
# Then in WSL: sudo apt-get install make

macOS

# Make comes pre-installed on macOS
# If needed: brew install make

Linux

# Debian/Ubuntu
sudo apt-get install make

# RHEL/CentOS/Fedora
sudo yum install make

🚀 Quick Command Reference for Make

CommandDescription
make devStart hybrid dev (backend in Docker, frontend local) ⭐
make dev-dockerEverything in Docker
make stopStop all services
make testRun all tests
make lintRun linters
make installInstall dependencies
make checkCheck environment setup
make cleanRemove containers and volumes (with confirmation)

🔄 Database Reset (Start Fresh if Needed)

If you need to completely reset your database and start fresh:

⚠️ Reset Database - This will delete ALL data for Archon!

  1. Run Reset Script: In your Supabase SQL Editor, run the contents of migration/RESET_DB.sql ⚠️ WARNING: This will delete all Archon specific tables and data! Nothing else will be touched in your DB though.
  2. Rebuild Database: After reset, run migration/complete_setup.sql to create all the tables again.
  3. Restart Services: 
    docker compose --profile full up -d
  4. Reconfigure:
    • Select your LLM/embedding provider and set the API key again
      • Re-upload any documents or re-crawl websites

The reset script safely removes all tables, functions, triggers, and policies with proper dependency handling.

📚 Documentation

Core Services

ServiceContainer NameDefault URLPurpose
Web Interfacearchon-uihttp://localhost:3737Main dashboard and controls
API Servicearchon-serverhttp://localhost:8181Web crawling, document processing
MCP Serverarchon-mcphttp://localhost:8051Model Context Protocol interface
Agents Servicearchon-agentshttp://localhost:8052AI/ML operations, reranking
Agent Work Orders (optional)archon-agent-work-ordershttp://localhost:8053Workflow execution with Claude Code CLI

Upgrading

To upgrade Archon to the latest version:

  1. Pull latest changes: 
    git pull
  2. Rebuild and restart containers: 
    docker compose up -d --build
    This rebuilds containers with the latest code and restarts all services.
  3. Check for database migrations:
    • Open the Archon settings in your browser: http://localhost:3737/settings
      • Navigate to the Database Migrations section
      • If there are pending migrations, the UI will display them with clear instructions
      • Click on each migration to view and copy the SQL
      • Run the SQL scripts in your Supabase SQL editor in the order shown

What’s Included

🧠 Knowledge Management

🤖 AI Integration

📋 Project & Task Management

🔄 Real-time Collaboration

Architecture

Microservices Structure

Archon uses true microservices architecture with clear separation of concerns:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend UI   │    │  Server (API)   │    │   MCP Server    │    │ Agents Service  │
│                 │    │                 │    │                 │    │                 │
│  React + Vite   │◄──►│    FastAPI +    │◄──►│    Lightweight  │◄──►│   PydanticAI    │
│  Port 3737      │    │    SocketIO     │    │    HTTP Wrapper │    │   Port 8052     │
│                 │    │    Port 8181    │    │    Port 8051    │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘    └─────────────────┘
         │                        │                        │                        │
         └────────────────────────┼────────────────────────┼────────────────────────┘
                                  │                        │
                         ┌─────────────────┐               │
                         │    Database     │               │
                         │                 │               │
                         │    Supabase     │◄──────────────┘
                         │    PostgreSQL   │
                         │    PGVector     │
                         └─────────────────┘

Service Responsibilities

ServiceLocationPurposeKey Features
Frontendarchon-ui-main/Web interface and dashboardReact, TypeScript, TailwindCSS, Socket.IO client
Serverpython/src/server/Core business logic and APIsFastAPI, service layer, Socket.IO broadcasts, all ML/AI operations
MCP Serverpython/src/mcp/MCP protocol interfaceLightweight HTTP wrapper, MCP tools, session management
Agentspython/src/agents/PydanticAI agent hostingDocument and RAG agents, streaming responses
Agent Work Orders (optional)python/src/agent_work_orders/Workflow execution engineClaude Code CLI automation, repository management, SSE updates

Communication Patterns

Key Architectural Benefits

🔧 Configuring Custom Ports & Hostname

By default, Archon services run on the following ports:

Changing Ports

To use custom ports, add these variables to your .env file:

# Service Ports Configuration
ARCHON_UI_PORT=3737
ARCHON_SERVER_PORT=8181
ARCHON_MCP_PORT=8051
ARCHON_AGENTS_PORT=8052
AGENT_WORK_ORDERS_PORT=8053

Example: Running on different ports:

ARCHON_SERVER_PORT=8282
ARCHON_MCP_PORT=8151

Configuring Hostname

By default, Archon uses localhost as the hostname. You can configure a custom hostname or IP address by setting the HOST variable in your .env file:

# Hostname Configuration
HOST=localhost  # Default

# Examples of custom hostnames:
HOST=192.168.1.100     # Use specific IP address
HOST=archon.local      # Use custom domain
HOST=myserver.com      # Use public domain

This is useful when:

After changing hostname or ports:

  1. Restart Docker containers: docker compose down && docker compose --profile full up -d
  2. Access the UI at: http://${HOST}:${ARCHON_UI_PORT}
  3. Update your AI client configuration with the new hostname and MCP port

🔧 Development

Quick Start

# Install dependencies
make install

# Start development (recommended)
make dev        # Backend in Docker, frontend local with hot reload

# Alternative: Everything in Docker
make dev-docker # All services in Docker

# Stop everything (local FE needs to be stopped manually)
make stop

Development Modes

Best for active development with instant frontend updates:

Full Docker Mode - make dev-docker

For all services in Docker environment:

Testing & Code Quality

# Run tests
make test       # Run all tests
make test-fe    # Run frontend tests
make test-be    # Run backend tests

# Run linters
make lint       # Lint all code
make lint-fe    # Lint frontend code
make lint-be    # Lint backend code

# Check environment
make check      # Verify environment setup

# Clean up
make clean      # Remove containers and volumes (asks for confirmation)

Viewing Logs

# View logs using Docker Compose directly
docker compose logs -f              # All services
docker compose logs -f archon-server # API server
docker compose logs -f archon-mcp    # MCP server
docker compose logs -f archon-ui     # Frontend

Note: The backend services are configured with --reload flag in their uvicorn commands and have source code mounted as volumes for automatic hot reloading when you make changes.

Troubleshooting

Common Issues and Solutions

Port Conflicts

If you see “Port already in use” errors:

# Check what's using a port (e.g., 3737)
lsof -i :3737

# Stop all containers and local services
make stop

# Change the port in .env

Docker Permission Issues (Linux)

If you encounter permission errors with Docker:

# Add your user to the docker group
sudo usermod -aG docker $USER

# Log out and back in, or run
newgrp docker

Windows-Specific Issues

Frontend Can’t Connect to Backend

Docker Compose Hangs

If docker compose commands hang:

# Reset Docker Compose
docker compose down --remove-orphans
docker system prune -f

# Restart Docker Desktop (if applicable)

Hot Reload Not Working

📈 Progress

Star History Chart

📄 License

Archon Community License (ACL) v1.2 - see LICENSE file for details.

TL;DR: Archon is free, open, and hackable. Run it, fork it, share it - just don’t sell it as-a-service without permission.