Cortex Linux

Cortex is an AI layer for Linux Debian/Ubuntu
Instead of memorizing commands, googling errors, and copy-pasting from Stack Overflow — describe what you need.

Quick Start • Features • Usage • Architecture • Contributing • Community

What is Cortex?

Cortex is an AI layer for Linux Debian/Ubuntu
Instead of memorizing commands, googling errors, and copy-pasting from Stack Overflow — describe what you need.

# Instead of googling "what's the package name for PDF editing on Ubuntu?"
cortex install "something to edit PDFs"

# Instead of remembering exact package names
cortex install "a lightweight code editor with syntax highlighting"

# Natural language just works
cortex install "tools for video compression"

Features

Quick Start

Prerequisites

• OS: Ubuntu 22.04+ / Debian 12+
• Python: 3.10 or higher
• API Key: Anthropic or OpenAI (optional - use Ollama for free local inference)

Installation

# 1. Clone the repository
git clone https://github.com/cortexlinux/cortex.git
cd cortex

# 2. Create virtual environment
python3 -m venv venv
source venv/bin/activate

# 3. Install Cortex
# Using pyproject.toml (recommended)
pip install -e .

# Or install with dev dependencies
pip install -e ".[dev]"

# 4. Configure AI Provider (choose one):

## Option A: Ollama (FREE - Local LLM, no API key needed)
python scripts/setup_ollama.py

## Option B: Claude (Cloud API - Best quality)
echo 'ANTHROPIC_API_KEY=your-key-here' > .env

## Option C: OpenAI (Cloud API - Alternative)
echo 'OPENAI_API_KEY=your-key-here' > .env

# 5. Verify installation
cortex --version

💡 Zero-Config: If you already have API keys from Claude CLI (~/.config/anthropic/) or OpenAI CLI (~/.config/openai/), Cortex will auto-detect them! Environment variables work immediately without prompting. See Zero Config API Keys.

First Run

# Preview what would be installed (safe, no changes made)
cortex install nginx --dry-run

# Actually install
cortex install nginx --execute

Usage

Basic Commands

# Install with natural language
cortex install "web server for static sites" --dry-run
cortex install "image editing software like photoshop" --execute

# View installation history
cortex history

# Rollback an installation
cortex rollback <installation-id>

Role Management

# Auto-detect your system role using AI analysis of local context and patterns
cortex role detect

# Manually set your system role to receive specific AI recommendations
cortex role set <slug>

Command Reference

Configuration

Cortex stores configuration in ~/.cortex/:

~/.cortex/
├── config.yaml      # User preferences
├── history.db       # Installation history (SQLite)
└── audit.log        # Detailed audit trail

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         User Input                              │
│                    "install video editor"                       │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                        CLI Interface                            │
│                         (cli.py)                                │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      LLM Router                                 │
│              Claude / GPT-4 / Ollama                            │
│                                                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │  Anthropic  │  │   OpenAI    │  │   Ollama    │              │
│  │   Claude    │  │    GPT-4    │  │   Local     │              │
│  └─────────────┘  └─────────────┘  └─────────────┘              │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Coordinator                                 │
│            (Plan Generation & Validation)                       │
└─────────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│    Hardware     │ │    Package      │ │    Sandbox      │
│    Detection    │ │    Manager      │ │    Executor     │
│                 │ │  (apt/yum/dnf)  │ │   (Firejail)    │
└─────────────────┘ └─────────────────┘ └─────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                   Installation History                          │
│                 (SQLite + Audit Logging)                        │
└─────────────────────────────────────────────────────────────────┘

Project Structure

cortex/
├── cortex/                 # Main package
│   ├── cli.py              # Command-line interface
│   ├── coordinator.py      # Installation orchestration
│   ├── llm_router.py       # Multi-LLM routing
│   ├── packages.py         # Package manager wrapper
│   ├── hardware_detection.py
│   ├── installation_history.py
│   └── utils/              # Utility modules
├── tests/                  # Test suite
├── docs/                   # Documentation
├── examples/               # Example scripts
└── scripts/                # Utility scripts

Safety & Security

Cortex is designed with security as a priority:

Security Policy

Found a vulnerability? Please report it responsibly:

• Email: security@cortexlinux.com
• See SECURITY.md for our disclosure policy

Troubleshooting

# Option 1: Set environment variables (used immediately, no save needed)
export ANTHROPIC_API_KEY=sk-ant-your-key
cortex install nginx --dry-run

# Option 2: Save directly to Cortex config
echo 'ANTHROPIC_API_KEY=sk-ant-your-key' > ~/.cortex/.env

# Option 3: Use Ollama (free, local, no key needed)
export CORTEX_PROVIDER=ollama
python scripts/setup_ollama.py

# Option 4: If you have Claude CLI installed, Cortex will find it automatically
# Just run: cortex install nginx --dry-run

# Ensure virtual environment is activated
source venv/bin/activate

# Reinstall
pip install -e .

# Check version
python3 --version

# Install Python 3.11 on Ubuntu/Debian
sudo apt update
sudo apt install python3.11 python3.11-venv

# Create venv with specific version
python3.11 -m venv venv

# Update pip
pip install --upgrade pip

# Install build dependencies
sudo apt install python3-dev build-essential

# Retry installation
pip install -e .

Project Status

Alpha Release - Cortex is under active development. APIs may change.

Completed

• Natural language to package resolution
• Claude and OpenAI integration
• Installation history and rollback
• User preferences (YAML-backed)
• Hardware detection (GPU/CPU/Memory)
• Firejail sandboxing
• Dry-run preview mode
• Docker bind-mount permission fixer
• Automatic Role Discovery (AI-driven system context sensing)

In Progress

• Conflict resolution UI
• Multi-step orchestration
• Ollama local model support
• MCP server integration
• Snap/Flatpak support

Planned

• Fedora/RHEL support
• Arch Linux support
• Web UI dashboard
• VS Code extension

See ROADMAP.md for the full development roadmap.

Contributing

We welcome contributions of all kinds!

Ways to Contribute

• Code: Python, Linux kernel optimizations
• Documentation: Guides, tutorials, API docs
• Testing: Bug reports, test coverage
• Design: UI/UX improvements

Bounty Program

We offer bounties for merged PRs:

See issues labeled bounty for available tasks.

Getting Started

# Fork and clone
git clone https://github.com/YOUR_USERNAME/cortex.git
cd cortex

# Setup development environment
python3 -m venv venv
source venv/bin/activate
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Run tests
pytest tests/ -v

See CONTRIBUTING.md for detailed guidelines.

Community

• Discord: discord.gg/uCqHvxjU83
• Discussions: GitHub Discussions
• Email: mike@cortexlinux.com
• Twitter: @cortexlinux

Support

• Bug Reports: GitHub Issues
• Feature Requests: GitHub Discussions
• Security Issues: security@cortexlinux.com

License

Apache 2.0 - See LICENSE for details.

_{Built with love by the Cortex team and contributors worldwide.}