Installation

System Requirements

Component	Minimum	Recommended
Python	3.11+	3.12+
Node.js	18+	20+
RAM	2 GB	4 GB
Disk	1 GB	5 GB

ChromaDB with sentence-transformers downloads embedding models on first run (~400 MB). Ensure you have adequate disk space and bandwidth.

Backend Setup

Clone the repository


git clone https://github.com/DoctaCloak/cortex-api.git
cd cortex-api

Create a virtual environment


python -m venv venv
source venv/bin/activate  # macOS/Linux
# or
venv\Scripts\activate     # Windows

Install dependencies


pip install -r requirements.txt

Configure environment variables

Create a .env file in the project root:

.env


# Required
ANTHROPIC_API_KEY=sk-ant-...
JWT_SECRET=your-secret-key-here

# Optional
CORS_ORIGINS=http://localhost:3000
DATABASE_URL=sqlite:///cortex.db
CHROMA_PERSIST_DIR=./chroma_data

Run the server


uvicorn main:app --reload --port 8000

The API will be available at http://localhost:8000. Visit http://localhost:8000/docs for the interactive Swagger UI.

Frontend Setup

Clone the repository


git clone https://github.com/DoctaCloak/cortex.git
cd cortex

Install dependencies


npm install

Configure environment variables

.env.local


NEXT_PUBLIC_API_URL=http://localhost:8000
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your-nextauth-secret

# GitHub OAuth (for authentication)
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

Run the development server


npm run dev

Visit http://localhost:3000 to see Cortex running.

Setting Up GitHub OAuth

Create a GitHub OAuth App

Go to GitHub Developer Settings
Click New OAuth App
Fill in the details:
- Application name: Cortex (Local)
- Homepage URL: http://localhost:3000
- Authorization callback URL: http://localhost:3000/api/auth/callback/github

Copy credentials

Copy the Client ID and generate a Client Secret. Add them to your frontend .env.local.

Docker Deployment

docker-compose.yml


version: '3.8'
services:
  backend:
    build: ./backend
    ports:
      - "8000:8000"
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - JWT_SECRET=${JWT_SECRET}
    volumes:
      - cortex-data:/app/data
 
  frontend:
    build: ./frontend
    ports:
      - "3000:3000"
    environment:
      - NEXT_PUBLIC_API_URL=http://backend:8000
    depends_on:
      - backend
 
volumes:
  cortex-data:


docker-compose up -d

Verify Installation

Run a quick health check:


# Backend
curl http://localhost:8000/health
 
# Expected response:
# {"status": "ok", "notes": 0, "links": 0}

Next Steps

Now that Cortex is running, create your first note →