feat: Local database mode with PostgreSQL + PostgREST (no Supabase cloud required)

.env.example

@@ -1,6 +1,25 @@
 # Minimal startup configuration - only Supabase connection required
 # All other settings (API keys, model choices, RAG flags) are managed via the Settings page
 
+# =====================================================
+# LOCAL DATABASE MODE (optional)
+# Set LOCAL_DB=true to run PostgreSQL + PostgREST locally
+# instead of using Supabase cloud. All data stays on your machine.
+# =====================================================
+LOCAL_DB=false
+
+# Local database credentials (used when LOCAL_DB=true)
+LOCAL_DB_USER=archon
+LOCAL_DB_PASSWORD=archon_password
+LOCAL_DB_NAME=archon
+LOCAL_DB_PORT=5433
+POSTGREST_PORT=3001
+LOCAL_REST_PORT=3002
+
+# =====================================================
+# SUPABASE CLOUD MODE (default when LOCAL_DB=false)
+# =====================================================
+
 # Get your SUPABASE_URL from the Data API section of your Supabase project settings -
 # https://supabase.com/dashboard/project/<your project ID>/settings/api
 SUPABASE_URL=

Makefile

@@ -5,23 +5,37 @@ SHELL := /bin/bash
 # Docker compose command - prefer newer 'docker compose' plugin over standalone 'docker-compose'
 COMPOSE ?= $(shell docker compose version >/dev/null 2>&1 && echo "docker compose" || echo "docker-compose")
 
-.PHONY: help dev dev-docker stop test test-fe test-be lint lint-fe lint-be clean install check
+# Load .env if it exists
+ifneq (,$(wildcard .env))
+    include .env
+    export
+endif
+
+.PHONY: help dev dev-docker dev-local-db stop test test-fe test-be lint lint-fe lint-be clean install check
 
 help:
 	@echo "Archon Development Commands"
 	@echo "==========================="
-	@echo "  make dev        - Backend in Docker, frontend local (recommended)"
-	@echo "  make dev-docker - Everything in Docker"
-	@echo "  make stop       - Stop all services"
-	@echo "  make test       - Run all tests"
-	@echo "  make test-fe    - Run frontend tests only"
-	@echo "  make test-be    - Run backend tests only"
-	@echo "  make lint       - Run all linters"
-	@echo "  make lint-fe    - Run frontend linter only"
-	@echo "  make lint-be    - Run backend linter only"
-	@echo "  make clean      - Remove containers and volumes"
-	@echo "  make install    - Install dependencies"
-	@echo "  make check      - Check environment setup"
+	@echo "  make dev          - Backend in Docker, frontend local (recommended)"
+	@echo "  make dev-docker   - Everything in Docker"
+	@echo "  make dev-local-db - Full stack with local PostgreSQL + PostgREST"
+	@echo "  make stop         - Stop all services"
+	@echo "  make test         - Run all tests"
+	@echo "  make test-fe      - Run frontend tests only"
+	@echo "  make test-be      - Run backend tests only"
+	@echo "  make lint         - Run all linters"
+	@echo "  make lint-fe      - Run frontend linter only"
+	@echo "  make lint-be      - Run backend linter only"
+	@echo "  make clean        - Remove containers and volumes"
+	@echo "  make install      - Install dependencies"
+	@echo "  make check        - Check environment setup"
+	@echo ""
+	@echo "Local Database Commands"
+	@echo "======================="
+	@echo "  make local-db-up      - Start local database stack only"
+	@echo "  make local-db-down    - Stop local database stack"
+	@echo "  make local-db-reset   - Reset local database (deletes all data)"
+	@echo "  make local-db-logs    - View local database logs"
 
 # Install dependencies
 install:
@@ -62,12 +76,50 @@ dev-docker: check
 	@echo "Frontend: http://localhost:3737"
 	@echo "API: http://localhost:8181"
 
+# Full stack with local database
+dev-local-db: check
+	@echo "Starting Archon with local database..."
+	@$(COMPOSE) --profile full --profile local-db up -d --build
+	@echo "✓ All services running with local database"
+	@echo "Frontend: http://localhost:3737"
+	@echo "API: http://localhost:8181"
+	@echo "Database: localhost:$(LOCAL_DB_PORT:-5433)"
+	@echo "PostgREST: http://localhost:$(POSTGREST_PORT:-3001)"
+
 # Stop all services
 stop:
 	@echo "Stopping all services..."
-	@$(COMPOSE) --profile backend --profile frontend --profile full down
+	@$(COMPOSE) --profile backend --profile frontend --profile full --profile local-db down
 	@echo "✓ Services stopped"
 
+# Local database commands
+local-db-up:
+	@echo "Starting local database stack..."
+	@$(COMPOSE) --profile local-db up -d
+	@echo "✓ Local database running"
+	@echo "PostgreSQL: localhost:$(LOCAL_DB_PORT:-5433)"
+	@echo "PostgREST: http://localhost:$(POSTGREST_PORT:-3001)"
+
+local-db-down:
+	@echo "Stopping local database..."
+	@$(COMPOSE) --profile local-db down
+	@echo "✓ Local database stopped"
+
+local-db-reset:
+	@echo "⚠️  This will remove the local database volume and recreate it"
+	@read -p "Are you sure? All data will be lost! (y/N) " -n 1 -r; \
+	echo; \
+	if [[ $$REPLY =~ ^[Yy]$$ ]]; then \
+		$(COMPOSE) --profile local-db down -v; \
+		$(COMPOSE) --profile local-db up -d; \
+		echo "✓ Local database reset and recreated"; \
+	else \
+		echo "Cancelled"; \
+	fi
+
+local-db-logs:
+	@$(COMPOSE) --profile local-db logs -f
+
 # Run all tests
 test: test-fe test-be
 

README.md

@@ -60,7 +60,7 @@ This new vision for Archon replaces the old one (the agenteer). Archon used to b
 
 - [Docker Desktop](https://www.docker.com/products/docker-desktop/)
 - [Node.js 18+](https://nodejs.org/) (for hybrid development mode)
-- [Supabase](https://supabase.com/) account (free tier or local Supabase both work)
+- [Supabase](https://supabase.com/) account (free tier or local Supabase both work) **OR use local database mode**
 - [OpenAI API key](https://platform.openai.com/api-keys) (Gemini and Ollama are supported too!)
 - (OPTIONAL) [Make](https://www.gnu.org/software/make/) (see [Installing Make](#installing-make) below)
 
@@ -77,16 +77,34 @@ This new vision for Archon replaces the old one (the agenteer). Archon used to b
    **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**:
 
-   ```bash
-   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
-   ```
+    ```bash
+    cp .env.example .env
+    ```
+
+    **Option A — Supabase Cloud (Default)**:
+    ```bash
+    # Edit .env and add your Supabase credentials:
+    SUPABASE_URL=https://your-project.supabase.co
+    SUPABASE_SERVICE_KEY=your-service-key-here
+    ```
+
+    **Option B — Local Database (No Cloud)**:
+    ```bash
+    # Edit .env and set:
+    LOCAL_DB=true
+    # Leave SUPABASE_URL and SUPABASE_SERVICE_KEY empty
+    ```
+
+    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).
+    - For local database mode: no Supabase credentials needed — just set `LOCAL_DB=true`.
+
+3. **Database Setup**:
 
-   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).
+    **Supabase Cloud**: In your [Supabase project](https://supabase.com/dashboard) SQL Editor, copy, paste, and execute the contents of `migration/complete_setup.sql`
+
+    **Local Database**: The database is automatically initialized when you start the services — no manual SQL execution needed.
 
 3. **Database Setup**: In your [Supabase project](https://supabase.com/dashboard) SQL Editor, copy, paste, and execute the contents of `migration/complete_setup.sql`
 
@@ -105,6 +123,25 @@ This new vision for Archon replaces the old one (the agenteer). Archon used to b
 
    Ports are configurable in your .env as well!
 
+   **Local Database Mode (No Supabase Account Required)**
+
+   If you want to keep all data on your machine with no cloud dependencies:
+
+   ```bash
+   # Option 1: Using Make (recommended)
+   make dev-local-db
+
+   # Option 2: Using Docker Compose directly
+   docker compose --profile full --profile local-db up -d
+   ```
+
+   This starts the full Archon stack **plus** a local PostgreSQL + PostgREST database:
+   - **Database**: PostgreSQL 16 with pgvector (Port: 5433)
+   - **PostgREST**: REST API compatible with supabase-py (Port: 3001)
+   - **All data stays on your machine** – no Supabase account needed
+
+   No additional configuration required – just set `LOCAL_DB=true` in your `.env` and everything works automatically.
+
 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)
@@ -160,16 +197,20 @@ sudo yum install make
 <summary><strong>🚀 Quick Command Reference for Make</strong></summary>
 <br/>
 
-| Command           | Description                                             |
-| ----------------- | ------------------------------------------------------- |
-| `make dev`        | Start hybrid dev (backend in Docker, frontend local) ⭐ |
-| `make dev-docker` | Everything in Docker                                    |
-| `make stop`       | Stop all services                                       |
-| `make test`       | Run all tests                                           |
-| `make lint`       | Run linters                                             |
-| `make install`    | Install dependencies                                    |
-| `make check`      | Check environment setup                                 |
-| `make clean`      | Remove containers and volumes (with confirmation)       |
+| Command              | Description                                             |
+| -------------------- | ------------------------------------------------------- |
+| `make dev`           | Start hybrid dev (backend in Docker, frontend local) ⭐ |
+| `make dev-docker`    | Everything in Docker                                    |
+| `make dev-local-db`  | Full stack with local PostgreSQL + PostgREST 🆕         |
+| `make stop`          | Stop all services                                       |
+| `make test`          | Run all tests                                           |
+| `make lint`          | Run linters                                             |
+| `make install`       | Install dependencies                                    |
+| `make check`         | Check environment setup                                 |
+| `make clean`         | Remove containers and volumes (with confirmation)       |
+| `make local-db-up`   | Start local database stack only                         |
+| `make local-db-down` | Stop local database stack                               |
+| `make local-db-reset`| Reset local database (deletes all data)                 |
 
 </details>
 
@@ -204,12 +245,20 @@ The reset script safely removes all tables, functions, triggers, and policies wi
 
 ### Core Services
 
-| Service            | Container Name | Default URL           | Purpose                           |
-| ------------------ | -------------- | --------------------- | --------------------------------- |
-| **Web Interface**  | archon-ui      | http://localhost:3737 | Main dashboard and controls       |
-| **API Service**    | archon-server  | http://localhost:8181 | Web crawling, document processing |
-| **MCP Server**     | archon-mcp     | http://localhost:8051 | Model Context Protocol interface  |
-| **Agents Service** | archon-agents  | http://localhost:8052 | AI/ML operations, reranking       |  
+| Service            | Container Name        | Default URL           | Purpose                           |
+| ------------------ | --------------------- | --------------------- | --------------------------------- |
+| **Web Interface**  | archon-ui             | http://localhost:3737 | Main dashboard and controls       |
+| **API Service**    | archon-server         | http://localhost:8181 | Web crawling, document processing |
+| **MCP Server**     | archon-mcp            | http://localhost:8051 | Model Context Protocol interface  |
+| **Agents Service** | archon-agents         | http://localhost:8052 | AI/ML operations, reranking       |
+
+### Local Database Services (opt-in)
+
+| Service            | Container Name        | Default URL           | Purpose                           |
+| ------------------ | --------------------- | --------------------- | --------------------------------- |
+| **PostgreSQL**     | archon-db             | localhost:5433        | Database with pgvector extension  |
+| **PostgREST**      | archon-postgrest      | http://localhost:3001 | REST API for PostgreSQL           |
+| **Nginx Proxy**    | archon-postgrest-proxy| http://localhost:3002 | Supabase URL compatibility layer  |
 
 ## Upgrading
 
@@ -285,12 +334,27 @@ Archon uses true microservices architecture with clear separation of concerns:
                          ┌─────────────────┐               │
                          │    Database     │               │
                          │                 │               │
-                         │    Supabase     │◄──────────────┘
-                         │    PostgreSQL   │
-                         │    PGVector     │
+                         │  Supabase Cloud │◄──────────────┘
+                         │  or Local DB    │
+                         │  PostgreSQL     │
+                         │  + PostgREST    │
                          └─────────────────┘
 ```
 
+### Local Database Architecture
+
+When running with `LOCAL_DB=true`, Archon uses a local PostgreSQL stack instead of Supabase Cloud:
+
+```
+┌──────────────┐    ┌──────────────┐    ┌──────────────┐
+│  PostgreSQL  │───►│  PostgREST   │───►│  Nginx Proxy │
+│  16 + pgvec  │    │  (REST API)  │    │  /rest/v1/   │
+│  Port 5433   │    │  Port 3001   │    │  Port 3002   │
+└──────────────┘    └──────────────┘    └──────────────┘
+```
+
+The Nginx proxy maps `/rest/v1/` paths to PostgREST's root paths, making it fully compatible with the `supabase-py` client. **No code changes needed** – Archon's Python services work identically in both modes.
+
 ### Service Responsibilities
 
 | Service        | Location             | Purpose                      | Key Features                                                       |