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
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"
| 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 |
| 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 |
- OS: Ubuntu 22.04+ / Debian 12+
- Python: 3.10 or higher
- API Key: Anthropic or OpenAI (optional - use Ollama for free local inference)
# 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
pip install -e .
# 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.
# Preview what would be installed (safe, no changes made)
cortex install nginx --dry-run
# Actually install
cortex install nginx --execute# 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>| 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 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 |
Cortex stores configuration in ~/.cortex/:
~/.cortex/
├── config.yaml # User preferences
├── history.db # Installation history (SQLite)
└── audit.log # Detailed audit trail
┌─────────────────────────────────────────────────────────────────┐
│ 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) │
└─────────────────────────────────────────────────────────────────┘
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
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 |
Found a vulnerability? Please report it responsibly:
- Email: security@cortexlinux.com
- See SECURITY.md for our disclosure policy
"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-runSee 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 venvpip install fails
# Update pip
pip install --upgrade pip
# Install build dependencies
sudo apt install python3-dev build-essential
# Retry installation
pip install -e .Alpha Release - Cortex is under active development. APIs may change.
- 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
- Conflict resolution UI
- Multi-step orchestration
- Ollama local model support
- MCP server integration
- Snap/Flatpak support
- Fedora/RHEL support
- Arch Linux support
- Web UI dashboard
- VS Code extension
See ROADMAP.md for the full development roadmap.
We welcome contributions of all kinds!
- Code: Python, Linux kernel optimizations
- Documentation: Guides, tutorials, API docs
- Testing: Bug reports, test coverage
- Design: UI/UX improvements
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.
# 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/ -vSee CONTRIBUTING.md for detailed guidelines.
- Discord: discord.gg/uCqHvxjU83
- Discussions: GitHub Discussions
- Email: mike@cortexlinux.com
- Twitter: @cortexlinux
- Bug Reports: GitHub Issues
- Feature Requests: GitHub Discussions
- Security Issues: security@cortexlinux.com
Apache 2.0 - See LICENSE for details.
Built with love by the Cortex team and contributors worldwide.
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
