Quick Start Guide

CortexOS is designed to spin up on your local hardware in less than a minute. You only need a modern operating system (Linux, macOS, or Windows WSL2), a shell environment, and CPU or GPU resources.

💡

Recommendation: For most users, running the curl installation script is the easiest way to download dependencies, set up local database files, and boot the application.

One-Command curl Install

Execute this command in your terminal. This downloads the installation bootstrapper, configures a virtual environment, checks for Ollama or local backends, and starts the services.

curl -fsSL https://cortexcloud.online/install.sh | bash

Once complete, the setup script launches the FastAPI server and React client, printing access endpoints to stdout.

Docker Deployment

For servers, continuous deployment pipelines, or environments requiring sandboxing, you can boot CortexOS using Docker and Docker Compose.

Step-by-Step Instructions

Clone the core repository and boot the Compose layout:

# 1. Clone the open source repository
git clone https://github.com/jonahthan433/CortexOS

# 2. Enter the project directory
cd CortexOS

# 3. Spin up the containers in detached mode
docker compose up -d

This command provisions three main isolated containers:

Frontend (React Client): Served on port 3000
Backend (FastAPI Server): Served on port 8000
SQLite Manager: An embedded local sqlite database instance

ℹ️

GPU Pass-Through: If you are planning to run local LLMs inside Docker on NVIDIA cards, ensure you have the nvidia-container-toolkit configured and set the GPU flags in your docker-compose.yml.

Local Development Setup

If you want to contribute to the open-source codebase, build custom modules, or inspect API routes, you can set up the full bare-metal development stack.

System Requirements

Python 3.10+
Node.js 18+ (and npm/yarn)
SQLite 3

Backend Setup

cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

Frontend Setup

cd frontend
npm install
npm run dev -- --port 3000

The frontend features hot-module reloading and links to backend operations via API proxies.

Core Module Guides

CortexOS is fully modular. It ships with 14 foundational modules representing complete capabilities. Turn them on or off in the dashboard settings panel depending on hardware resources.

💬 1. Chat Interface

Advanced chat with mid-thread model switching, streaming text, markdown parsing, and tree-like branching dialogs.

🤖 2. Autonomous Agents

Goal-oriented executors equipped with self-correction feedback, tool-access parameters, and persistent memory states.

📚 3. Agent Cookbook

A repository containing 50+ pre-configured templates for common workflows (reports, email parsing, triage, scrapers).

🔬 4. Deep Research

Multi-hop agents that crawl pages, query vector stores, synthesize sources, and output complete annotated research digests.

⚖️ 5. Model Comparison

Blind side-by-side prompt execution. Allows team members or scripts to grade model capabilities and compile leaderboard metrics.

📄 6. Documents & Copilot

Interactive writing environment with inline AI autocompletes, summaries, proofreading, and format conversion options.

🧠 7. Memory & Skills

A vector database mapping system. Gives agents private local recall storage and reusable script-like tools (skills).

📧 8. Email Integration

Full support for SMTP/IMAP protocols. Read, write, and send email messages locally. Enables building triage workflows.

✅ 9. Notes & Tasks

Kanban interface linked directly to agents, allowing automated prioritization and assignment of tasks.

📅 10. Calendar (CalDAV)

Sync support for standard CalDAV servers. Lets agents search schedules, coordinate meetings, and write appointments.

🔑 11. API Gateway

OpenAPI endpoint control center, API key issuer, and detailed request tracing logging dashboard.

⚡ 12. Scheduled Automations

Flexible background task runner. Trigger workflows using natural language expressions (e.g. "Every weekday at noon").

🎓 13. RL Training

Private reinforcement learning control dashboard. Run local finetunes and save target weights in GGUF formats.

🎨 14. Themes & Extras

Premium cyberpunk interfaces, customizable Jank Mode, performance visualizer charts, and audio text-to-speech tools.

Stack & Architecture

CortexOS utilizes a clean client-server architecture. On-premise reliability and modularity are the primary drivers of our design decisions.

Layer	Technology Used	Core Purpose
Frontend	React 18 + TS (Progressive Web App)	Interactive user dashboard, chat, files editor
Backend	FastAPI + Python 3.11	Async API layer, tool controllers, agent pipelines
Database	SQLite + Vector Extensions	Local data structures, history, user keys, vector memory
Sandboxing	Docker & Linux Namespaces	Secure sandboxed agent environment for file actions
Inference Backend	Ollama, vLLM, llama.cpp	Local LLM execution engines

Visual Themes

The system supports multiple premium visual modes out of the box, including our default deep dark theme, a sleek cyberpunk interface, and a playful Jank Mode inspired by early terminal aesthetics. Swap themes on the fly inside the Settings panel.

Connecting Backends

CortexOS can delegate model queries to any inference backend. Learn how to configure local integrations.

1. Local Ollama Integration

By default, CortexOS auto-detects Ollama if it is running on the host system. The application queries Ollama's port 11434 automatically.

If Ollama runs on a separate machine, update your environment configuration:

# edit backend/.env file
OLLAMA_HOST=http://192.168.1.100:11434

vLLM Cluster Connection

For teams requiring high-throughput, distributed execution, CortexOS supports Open-AI compatible backends, specifically vLLM.

Configure vLLM on your GPU server and point the client via the environment configurations:

# backend/.env
OPENAI_API_BASE=http://gpu-cluster-ip:8000/v1
OPENAI_API_KEY=token-key-if-applicable
DEFAULT_MODEL=meta-llama/Meta-Llama-3-70B-Instruct

CalDAV Calendar Sync

Connect your calendar so scheduling agents can inspect times and schedule meetings. The CalDAV integration supports Google Calendar, Nextcloud, and Apple iCloud.

Input credentials in your user Profile Settings panel:

Parameter	Description	Example
Server URL	The absolute path to your CalDAV collection	`https://nextcloud.corp.io/remote.php/dav/`
Username	Account identifier	`alex.reinholt`
App Password	Unique API app token (recommended over master password)	`xxxx-xxxx-xxxx-xxxx`

Deployment & Scaling

CortexOS and CortexCloud are built to scale alongside your organization. Select the appropriate configuration layout.

Solo Server: 1 CPU/GPU machine running Docker Compose. Simple, self-contained, low overhead.
Enterprise Cluster (CortexCloud Platform): Distributed backend nodes, vLLM pooling, high-availability Postgres clusters, centralized Redis locks.

Air-Gapped Configurations

Regulated sectors (healthcare, government, banking) require complete network isolation. CortexOS can run 100% offline.

Requirements Checklist

Pre-downloaded GGUF or Model Weights (stored locally under ~/.ollama/models or host directories).
Docker images exported to tar archives and transferred via safe physical media.
Configured offline RAG databases using local directory mappings.

⚠️

Note: When offline, external features like the OpenRouter fallback will be automatically disabled, and all queries will throw warnings if local backends are unavailable.