cortex-linux 0.1.0

AI-powered package manager for Debian/Ubuntu that understands natural language

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

Feature	Description
Natural Language	Describe what you need in plain English
Dry-Run Default	Preview all commands before execution
Sandboxed Execution	Commands run in Firejail isolation
Full Rollback	Undo any installation with cortex rollback
Role Management	AI-driven system personality detection and tailored recommendations
Docker Permission Fixer	Fix root-owned bind mount issues automatically
Audit Trail	Complete history in ~/.cortex/history.db
Hardware-Aware	Detects GPU, CPU, memory for optimized packages
Multi-LLM Support	Works with Claude, GPT-4, or local Ollama models

---

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

Command	Description
cortex install <query>	Install packages matching natural language query
cortex install <query> --dry-run	Preview installation plan (default)
cortex install <query> --execute	Execute the installation
cortex docker permissions	Fix file ownership for Docker bind mounts
cortex role detect	Automatically identifies the system's purpose
cortex role set <slug>	Manually declare a system role
cortex sandbox <cmd>	Test packages in Docker sandbox
cortex history	View all past installations
cortex rollback <id>	Undo a specific installation
cortex --version	Show version information
cortex --help	Display help message

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:

Protection	Implementation
Dry-run by default	No execution without --execute flag
Sandboxed execution	All commands run in Firejail containers
Command validation	Dangerous patterns blocked before execution
Audit logging	Every action recorded with timestamps
Rollback capability	Full undo support for all installations
No root by default	Sudo only when explicitly required

Security Policy

Found a vulnerability? Please report it responsibly:

• Email: [e-mail]
• See SECURITY.md for our disclosure policy

---

Troubleshooting

"No API key found"

Cortex auto-detects API keys from multiple locations. If none are found:

# 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

See Zero Config API Keys for details.

"command not found: cortex"

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

# Reinstall
pip install -e .

"Python version too old"

# 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

pip install fails

# 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:

Tier	Reward	Examples
Small	$25	Bug fixes, typos, minor features
Medium	$50-100	New features, significant improvements
Large	$150-200	Major features, security fixes

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: [e-mail]
• Twitter: @cortexlinux

Support

• Bug Reports: GitHub Issues
• Feature Requests: GitHub Discussions
• Security Issues: [e-mail]

---

License

Apache 2.0 - See LICENSE for details.

---

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