Getting Started

Quick Start

Copy page

Get Cortex running locally in just a few minutes using Docker Compose.

Prerequisites

Before you begin, make sure you have:

• Docker and Docker Compose installed
• Git for cloning the repository
• An OpenAI API key (or Anthropic/local LLM)

Installation

Step 1: Clone the Repository

Code
 
git clone https://github.com/mocaOS/cortex-app.git
cd cortex-app

Step 2: Configure Environment

The lowest-friction start is the recommended config that ships with the repo:

Code
 
cp .env.recommended .env

.env.recommended is the bench-validated starting point. Fill in the secrets block at the top and your LLM API key — that's it. Everything else (extraction budgets, concurrency, chunking) runs on production-tuned code defaults:

Code
 
# Secrets — generate strong values for production: openssl rand -base64 32
ADMIN_EMAIL=admin@email.com
ADMIN_PASSWORD=your-pass
ADMIN_API_KEY=custom-api-keyyy
SERVICE_PASSWORD_NEO4J=another-pass
SESSION_SECRET=secret
ENCRYPTION_KEY=

# Your LLM provider key
OPENAI_API_KEY=your-venice-api-key

Set ENCRYPTION_KEY for real deployments — it encrypts user-supplied secrets at rest (git connector tokens, secret-typed skill config). Left empty, those are stored in plaintext (Cortex logs a startup warning); setting a key later auto-encrypts existing secrets on the next boot. Generate one with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

LLM Configuration

Cortex speaks the OpenAI protocol everywhere, so any model from any OpenAI-compatible API works — Venice, OpenRouter, OpenAI, or self-hosted vLLM/Ollama. Five model slots (primary, extraction, relationship, vision, embeddings) are independently configurable, and every slot inherits the primary's API base + key unless overridden.

The recommended stack, pre-filled in .env.recommended:

• Primary agent — Gemma4 26B A4B (google-gemma-4-26b-a4b-it): fast MoE with a 256K window; drives Q&A, research, and chat.
• Knowledge-graph generation — Qwen3.6 27B (qwen3-6-27b): entity/relationship extraction and image analysis from a single endpoint.
• Embeddings — text-embedding-3-small (1536-dim; the code default).

Code
 
# Primary — agentic Q&A / research / chat
OPENAI_API_KEY=your-venice-api-key
OPENAI_API_BASE=https://api.venice.ai/api/v1
OPENAI_MODEL=google-gemma-4-26b-a4b-it
OPENAI_MAX_CONTEXT=256000

# Embeddings
EMBEDDING_MODEL=text-embedding-3-small

# Vision — image analysis during ingestion (must be set explicitly;
# leave empty to fall back to Docling's built-in captioning)
VISION_MODEL=qwen3-6-27b

# Knowledge-graph generation — drives relationship analysis via inheritance
GRAPH_EXTRACTION_MODEL=qwen3-6-27b

To point a tier at a different provider, uncomment its *_API_BASE / *_API_KEY pair in .env.recommended. You do not need to set context windows for the extraction or vision models — ingestion runs on its own fine-tuned budgets (16000/16000 by default, sized to provider decode speed rather than the model window). Only OPENAI_MAX_CONTEXT should match your primary model's window.

Running on OpenRouter or your own GPUs instead of Venice? The LLM Deployment Templates page has a tested stack per provider, including fallback model recommendations.

Or configure each tier independently:

Code
 
# ── Primary LLM (Q&A, research, chat) ───────────────────────────
# Recommended: Gemma4 26B A4B (google-gemma-4-26b-a4b-it) — blazing-fast MoE, ideal for retrieval
# (MiniMax M3 can give slightly better results but costs the system its snappiness — not a worthwhile tradeoff)
OPENAI_API_KEY=
OPENAI_API_BASE=https://api.example.com/v1
OPENAI_MODEL=

# ── Graph Extraction (entity discovery + community summarization) ─
# Recommended: Qwen3.6 27B — reasoning suppressed so it behaves like a fast instruct model (no overthinking)
ENABLE_GRAPH_EXTRACTION=                     # true = extract entities/relationships, false = skip
GRAPH_EXTRACTION_MODEL=                      # defaults to OPENAI_MODEL
GRAPH_EXTRACTION_API_BASE=                   # defaults to OPENAI_API_BASE
GRAPH_EXTRACTION_API_KEY=                    # defaults to OPENAI_API_KEY

# ── Relationship Model (relationship discovery) ─────────────────
# Recommended: Qwen3.6 27B — reasoning suppressed so it behaves like a fast instruct model (no overthinking)
# Used for per-chunk (Step 1) and cross-document (Step 2) relationship extraction
# Runs on a separate rate limit from entity extraction
RELATIONSHIP_EXTRACTION_MODEL=               # defaults to GRAPH_EXTRACTION_MODEL → OPENAI_MODEL
RELATIONSHIP_EXTRACTION_API_BASE=            # defaults to GRAPH_EXTRACTION_API_BASE
RELATIONSHIP_EXTRACTION_API_KEY=             # defaults to GRAPH_EXTRACTION_API_KEY

# Context budgets — the extraction budgets ship production-tuned defaults
# (GRAPH_EXTRACTION_MAX_CONTEXT=16000, EXTRACTION_MAX_OUTPUT_TOKENS=16000);
# only set them to deviate. OPENAI_MAX_CONTEXT cascades to the remaining
# sub-tiers via the fallback chain (0 = inherit).
# GRAPH_EXTRACTION_MAX_CONTEXT=16000         # batch-size / graph-density dial, NOT the model window
# EXTRACTION_MAX_OUTPUT_TOKENS=16000         # generous ceiling matched to the context
# RELATIONSHIP_MAX_CONTEXT=0                 # leave 0 = inherit — see Configuration for when widening is safe

# ── Vision (image analysis during document ingestion) ────────────
VISION_MODEL=
VISION_MODEL_API_BASE=                       # defaults to OPENAI_API_BASE
VISION_MODEL_API_KEY=                        # defaults to OPENAI_API_KEY

# ── Embeddings ───────────────────────────────────────────────────
EMBEDDING_MODEL=
EMBEDDING_DIMENSION=
EMBEDDING_SEND_DIMENSIONS=true               # set false for models with fixed output dim
EMBEDDING_API_BASE=                          # defaults to OPENAI_API_BASE
EMBEDDING_API_KEY=                           # defaults to OPENAI_API_KEY

Performance Tuning

Controls how much work runs in parallel:

Code
 
BATCH_PROCESSING_CONCURRENCY=2               # documents processed in parallel (2 beats 3: concurrent
                                             # docs share the provider's decode rate and multiply timeouts)
CONCURRENT_EXTRACTIONS=3                     # entity extraction thread pool size
CONCURRENT_RELATIONS=3                       # per-chunk relationship extractions per document
VISION_MAX_CONCURRENT=2                      # concurrent vision API calls (system-wide; ~20 provider slots/key bind first)
PARALLEL_RELATIONSHIP_BATCHES=5              # relationship analysis batches in parallel (1 = sequential)

BATCH_PROCESSING_CONCURRENCY controls how many documents go through the pipeline simultaneously. Within each document, CONCURRENT_EXTRACTIONS sizes the entity extraction thread pool and CONCURRENT_RELATIONS controls per-chunk relationship extraction concurrency. VISION_MAX_CONCURRENT independently caps the background image analysis pipeline across all documents. PARALLEL_RELATIONSHIP_BATCHES is the most impactful lever for speeding up cross-document relationship analysis — increase it to run multiple LLM calls concurrently.

See the Configuration Reference for all 50+ environment variables.

Step 3: Start Services

Code
 
docker compose up -d

This starts all services:

Service	URL	Description
Frontend	http://localhost:3000	Next.js web interface
Backend API	http://localhost:8000	FastAPI REST API
Neo4j Browser	http://localhost:7474	Database admin UI
Neo4j Bolt	bolt://localhost:7687	Database connection

Step 4: Verify Installation

Check that all containers are running:

Code
 
docker compose ps

Test the API health endpoint:

Code
 
curl http://localhost:8000/health

Expected response:

Code
 
{
  "status": "healthy",
  "neo4j_connected": true,
  "version": "1.0.0"
}

Step 5: Access the Web Interface

Open http://localhost:3000 in your browser and log in with your admin credentials.

First Steps

1. Upload Your First Document

1. Navigate to the Documents page
2. Click the Upload button to open the upload modal
3. Drag and drop a PDF, TXT, MD, or DOCX file
4. Click Start Processing to begin — you'll be taken back to the Documents page where you can watch progress in real-time

2. Explore Your Knowledge Base

1. Go to the Explore section
2. Use the Knowledge Graph tab to visualize entities and relationships
3. Use the Deep Research tab for multi-step reasoning over your documents
4. Use the Chat tab to ask questions and get AI-generated answers with source citations

Common Commands

Code
 
# Start all services
docker compose up -d

# Stop all services
docker compose down

# View logs
docker compose logs -f

# View logs for specific service
docker compose logs -f backend

# Restart a service
docker compose restart backend

# Rebuild after code changes
docker compose up -d --build

Troubleshooting

Container won't start

Check if ports are already in use:

Code
 
lsof -i :3000  # Frontend
lsof -i :8000  # Backend
lsof -i :7687  # Neo4j

Neo4j connection failed

Wait 30-60 seconds for Neo4j to fully initialize, then restart the backend:

Code
 
docker compose restart backend

OpenAI API errors

Verify your API key is valid:

Code
 
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Next Steps

• Configuration Reference - All 50+ environment variables
• Document Upload Guide - Supported formats and options
• Deployment Guide - Production deployment with Coolify
• API Reference - Full API documentation