Getting Started

Quick Start

Copy page

There are two ways in, and they end at the same place — a stack on http://localhost:3000 with the API on :8000:

• One command — npx @mocaos/cortex runs prebuilt, version-pinned images. Nothing to clone, nothing to build. Use this unless you have a reason not to.
• Build from source — clone the repo and docker compose up. For development, for tracking main, or when you want to modify the code.

Install in one command

Code
 
npx @mocaos/cortex

That is the entire installation. There is no install subcommand — npx already means "fetch and run".

Prerequisites

• Docker with the Compose v2 plugin — check with docker compose version. On Linux, apt install docker.io does not include it; use Docker's official packages or Docker Desktop.
• curl and tar on the host.
• ~20 GB free disk, ~8 GB RAM, linux/amd64 or linux/arm64. Images pull ~1.6 GB in total.
• An OpenAI-compatible API key — OpenAI, OpenRouter, Venice, Groq, a local Ollama, anything that speaks /v1/chat/completions. Embeddings need /v1/embeddings, but not necessarily from the same provider: Groq has no embedding endpoint at all, so the installer lets you point embeddings somewhere else.
• npx brings its own Node. If one is already on your PATH it must be 20.12 or newer.

What it does

It stops at the first thing that would waste your time:

1. Checks your environment — Docker daemon, Compose v2, architecture, disk, RAM, and the ports it is about to bind.
2. Validates your credentials with two live calls — a real chat completion and a real embedding call. Nothing is written to disk and no image is pulled until both succeed, so a wrong key costs you seconds instead of a 1.6 GB download. The embedding dimension is measured here rather than assumed, because it gets baked into the Neo4j vector index on first use.
3. Asks how you want it set up — localhost or a public domain (with automatic HTTPS via Caddy), your provider and models, your admin identity, and secrets, which are generated for you unless you would rather set them.
4. Pulls, starts, and verifies — writes .env at mode 0600, fetches that release's Compose files, pulls the pinned images, and waits for every service to report healthy before printing your login.

Then it prints your URLs and credentials, and you can go straight to First Steps.

The stack it brings up is Cortex, Neo4j, a nightly backup sidecar, and optionally Cortex Chat — plus Caddy in domain mode. Cortex and Chat share one identity when chat is installed, so the admin email and password log you into both.

Managing the instance

The same command owns the instance afterwards, so you rarely touch Compose directly:

Code
 
npx @mocaos/cortex status     # service state, health, URLs
npx @mocaos/cortex doctor     # one pasteable diagnostic block
npx @mocaos/cortex logs       # follow logs
npx @mocaos/cortex backup     # verified backup now
npx @mocaos/cortex update     # move to the latest tested stack

start, stop, restart, config, restore and uninstall round it out. Your data lives in Docker volumes, so stop and uninstall never touch it — removing volumes takes a confirmation and a typed phrase.

If npx itself won't run

Two failures happen before the installer starts, and neither message points at its cause:

• could not determine executable to run — you typed npx install @mocaos/cortex. There is no install subcommand; that asks npm to run a package literally named install. Drop the word.
• ENOVERSIONS — No versions available — the package is public and fine; npm is hiding it from you. An .npmrc with min-release-age set filters out every version published inside that window, so a release that is hours old has none left. Keep the setting — it is real protection against supply-chain attacks — and override it for the one command:

Code
 
npx --min-release-age=0 @mocaos/cortex

Unattended installs

--yes runs the identical sequence, including both credential probes, from environment variables instead of prompts:

Code
 
CORTEX_ADMIN_EMAIL=you@example.com \
CORTEX_OPENAI_API_KEY=sk-... \
CORTEX_OPENAI_API_BASE=https://api.venice.ai/api/v1 \
CORTEX_OPENAI_MODEL=qwen3-6-35b-a3b \
CORTEX_EMBEDDING_MODEL=text-embedding-3-small \
CORTEX_EMBEDDING_DIMENSION=1536 \
npx @mocaos/cortex --yes

CORTEX_OPENAI_API_BASE is optional and defaults to OpenAI's endpoint. Secrets are generated unless you supply them (CORTEX_ADMIN_PASSWORD, CORTEX_NEO4J_PASSWORD, CORTEX_ADMIN_API_KEY, CORTEX_SESSION_SECRET, CORTEX_CHAT_ENCRYPTION_KEY). Embeddings follow the chat provider unless you set CORTEX_EMBEDDING_API_BASE and CORTEX_EMBEDDING_API_KEY — both or neither, since a base URL on its own would send one vendor's key to another vendor's endpoint. Add CORTEX_MODE=domain with CORTEX_APP_DOMAIN, CORTEX_CHAT_DOMAIN and CORTEX_ACME_EMAIL for a public deployment.

The deployment guide covers domain mode, the manual equivalent of every step above, and the backup and restore runbook.

Build from source

Use this path for development, for tracking main, or when you want to run modified code. It compiles the frontend and a torch-bearing backend locally, which takes a while on a small machine. You will also need Git on top of the prerequisites above.

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

The installer asks for the same choices and writes them into .env for you — this section is what it is choosing between, and where to look for the knobs it doesn't ask about.

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 — Qwen3.6 35B A3B (qwen3-6-35b-a3b): 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=qwen3-6-35b-a3b
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: Qwen3.6 35B A3B (qwen3-6-35b-a3b) — 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"
}

A degraded instance — Neo4j unreachable, or the schema not yet confirmed — answers 503 with "status": "degraded", so key your own checks off the status code. Don't read version as the release you are running: it was a hardcoded 1.0.0 through v1.0.1 and only reports the real release after that. docker compose images (or npx @mocaos/cortex status) tells you what is actually running.

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

From a source checkout. On an installer-managed instance use the verbs instead — npx @mocaos/cortex start / stop / restart / logs — since they run Compose in the right directory with the right file set.

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

On an installer-managed instance, start with npx @mocaos/cortex doctor — it prints one pasteable block covering the environment checks plus service state and health.

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 - The installer in depth, public domains with HTTPS, the manual release stack, backups and restore
• API Reference - Full API documentation