Skip to content

Installation Guide

Jump to bottom
Mike Morgan edited this page Jan 11, 2026 · 1 revision

Installation Guide

Complete installation instructions for Cortex Linux across all supported platforms.

Table of Contents

  1. System Requirements
  2. VirtualBox Installation
  3. VMware Installation
  4. Bare Metal Installation
  5. Cloud Deployment
  6. Post-Installation Setup
  7. Troubleshooting

System Requirements

Minimum Requirements

  • CPU: x86_64 or ARM64 architecture, 2 cores minimum
  • RAM: 2GB (4GB recommended for optimal AI performance)
  • Storage: 10GB free disk space (20GB recommended)
  • Network: Optional (for package updates, not required for AI functionality)

Recommended Requirements

  • CPU: 4+ cores, modern architecture (Intel Skylake+, AMD Zen+, ARM Cortex-A78+)
  • RAM: 8GB+ for production workloads
  • Storage: 50GB+ SSD for better performance
  • Network: Broadband connection for initial setup

Supported Platforms

  • Virtualization: VirtualBox 6.0+, VMware Workstation/Player 15+, QEMU/KVM
  • Cloud: AWS EC2, DigitalOcean Droplets, Google Cloud Compute Engine, Azure VMs
  • Bare Metal: Standard x86_64 and ARM64 hardware
  • Containers: Docker (with limitations), Podman

VirtualBox Installation

Prerequisites

  1. Download and install VirtualBox (6.0 or later)
  2. Download Cortex Linux ISO from releases.cortexlinux.org

Step-by-Step Installation

1. Create Virtual Machine

# Using VirtualBox CLI
VBoxManage createvm --name "Cortex Linux" --ostype "Linux_64" --register
VBoxManage modifyvm "Cortex Linux" --memory 4096 --cpus 2
VBoxManage modifyvm "Cortex Linux" --graphicscontroller vboxsvga
VBoxManage modifyvm "Cortex Linux" --audio none
VBoxManage createhd --filename "CortexLinux.vdi" --size 20000
VBoxManage storagectl "Cortex Linux" --name "SATA Controller" --add sata
VBoxManage storageattach "Cortex Linux" --storagectl "SATA Controller" --port 0 --device 0 --type hdd --medium "CortexLinux.vdi"
VBoxManage storageattach "Cortex Linux" --storagectl "SATA Controller" --port 1 --device 0 --type dvddrive --medium cortex-linux-1.0.0.iso

Or use the VirtualBox GUI:

  1. Click "New" → Name: "Cortex Linux"
  2. Type: Linux, Version: Other Linux (64-bit)
  3. Memory: 4096 MB (or more)
  4. Create virtual hard disk: 20GB+ (VDI, dynamically allocated)
  5. Settings → Storage → Controller: IDE → Add optical drive → Select ISO

2. Boot from ISO

  1. Start the virtual machine
  2. Select "Install Cortex Linux" from the boot menu
  3. Follow the graphical installer

3. Installation Process

The installer will guide you through:

  • Language Selection: Choose your preferred language
  • Keyboard Layout: Select keyboard mapping
  • Disk Partitioning:
    • Automatic (recommended for beginners)
    • Manual (for advanced users)
  • User Account: Create root and user accounts
  • Network Configuration: Optional network setup
  • AI Engine Configuration: Initial Sapiens engine setup

4. Complete Installation

After installation completes:

# Reboot into installed system
sudo reboot

# Remove installation media
# In VirtualBox: Settings → Storage → Remove ISO

VMware Installation

Prerequisites

  • VMware Workstation Pro/Player 15+ or VMware Fusion 11+ (macOS)
  • Cortex Linux ISO image

Installation Steps

1. Create New Virtual Machine

# Using VMware CLI (vmrun)
vmware-vmx --new-sn=CortexLinux.vmx

Or via GUI:

  1. File → New Virtual Machine
  2. Typical configuration
  3. Install from disc image file → Select Cortex Linux ISO
  4. Linux → Other Linux 5.x kernel 64-bit
  5. Name: "Cortex Linux"
  6. Disk size: 20GB+ (split into multiple files recommended)
  7. Customize hardware:
    • Memory: 4096 MB+
    • Processors: 2+
    • Network: NAT or Bridged

2. Install Operating System

  1. Power on the virtual machine
  2. Boot from ISO
  3. Follow installation wizard (same as VirtualBox)
  4. Complete installation and reboot

3. Install VMware Tools (Optional)

# After installation
sudo apt update
sudo apt install open-vm-tools
sudo systemctl enable open-vm-tools
sudo systemctl start open-vm-tools

Bare Metal Installation

Creating Bootable Media

USB Drive (Linux/macOS)

# Identify USB device
lsblk  # or diskutil list on macOS

# Unmount USB drive
sudo umount /dev/sdX  # Replace X with your device

# Write ISO to USB
sudo dd if=cortex-linux-1.0.0.iso of=/dev/sdX bs=4M status=progress oflag=sync

# On macOS
sudo dd if=cortex-linux-1.0.0.iso of=/dev/rdiskX bs=1m

USB Drive (Windows)

  1. Download Rufus or Balena Etcher
  2. Select Cortex Linux ISO
  3. Select USB drive
  4. Click "Start" or "Flash"

BIOS/UEFI Configuration

  1. Enter BIOS/UEFI: Press F2, F10, F12, or Del during boot (varies by manufacturer)
  2. Disable Secure Boot: Required for Cortex Linux installation
  3. Set Boot Priority: USB drive first, then hard disk
  4. Enable UEFI Mode: Recommended for modern systems
  5. Save and Exit

Installation Process

  1. Boot from USB: Select USB drive from boot menu
  2. Select Installation Mode:
    • Graphical installer (recommended)
    • Text-based installer (for headless systems)
  3. Partitioning Options:
    • Automatic: Use entire disk (erases all data)
    • Manual: Custom partition layout
      • /boot (EFI): 512MB (UEFI) or 256MB (BIOS)
      • /: 20GB+ (root filesystem)
      • /home: Optional (user data)
      • swap: 2-4GB (or equal to RAM for hibernation)
  4. Complete Installation: Follow prompts, reboot when finished

Post-Installation Hardware Configuration

# Check hardware detection
sudo lshw -short

# Install proprietary drivers (if needed)
sudo apt update
sudo apt install linux-firmware

# Configure graphics (if needed)
sudo apt install nvidia-driver  # For NVIDIA GPUs
# or
sudo apt install mesa-vulkan-drivers  # For AMD/Intel GPUs

Cloud Deployment

AWS EC2

Launch Instance

# Using AWS CLI
aws ec2 run-instances \
  --image-id ami-xxxxx \
  --instance-type t3.medium \
  --key-name your-key-pair \
  --security-group-ids sg-xxxxx \
  --subnet-id subnet-xxxxx \
  --user-data file://cortex-init.sh

Or via AWS Console:

  1. EC2 Dashboard → Launch Instance
  2. AMI: Select Cortex Linux AMI (or upload custom)
  3. Instance Type: t3.medium or larger (2 vCPU, 4GB RAM minimum)
  4. Key Pair: Select or create SSH key pair
  5. Network: Configure VPC, subnet, security groups
  6. Storage: 20GB+ gp3 SSD
  7. Launch Instance

Security Group Configuration

Required ports:

  • 22: SSH (TCP)
  • 8080: Cortex AI HTTP API (TCP, optional, restrict source IP)
  • 80/443: Web services (TCP, if applicable)
# Configure security group
aws ec2 authorize-security-group-ingress \
  --group-id sg-xxxxx \
  --protocol tcp \
  --port 22 \
  --cidr 0.0.0.0/0  # Restrict to your IP in production

Connect and Verify

# SSH into instance
ssh -i your-key.pem ec2-user@your-instance-ip

# Verify Cortex installation
cortex-ai --version
systemctl status cortex-ai

DigitalOcean Droplet

Create Droplet

# Using doctl CLI
doctl compute droplet create cortex-linux \
  --image cortex-linux-1-0-0 \
  --size s-2vcpu-4gb \
  --region nyc1 \
  --ssh-keys your-ssh-key-id

Or via DigitalOcean Console:

  1. Create → Droplets
  2. Image: Cortex Linux (or upload custom image)
  3. Plan: Basic, $24/month (4GB RAM, 2 vCPU) or larger
  4. Datacenter: Select region
  5. Authentication: SSH keys or password
  6. Create Droplet

Post-Creation Setup

# SSH into droplet
ssh root@your-droplet-ip

# Update system
apt update && apt upgrade -y

# Verify AI engine
cortex-ai test

Google Cloud Platform

Create VM Instance

# Using gcloud CLI
gcloud compute instances create cortex-linux \
  --image-family=cortex-linux \
  --image-project=cortex-linux-cloud \
  --machine-type=n1-standard-2 \
  --zone=us-central1-a \
  --boot-disk-size=20GB

Or via GCP Console:

  1. Compute Engine → VM Instances → Create
  2. Name: cortex-linux
  3. Machine Type: n1-standard-2 (2 vCPU, 7.5GB RAM) or larger
  4. Boot Disk: Cortex Linux image, 20GB+
  5. Firewall: Allow HTTP/HTTPS traffic (if needed)
  6. Create

Configure Firewall

# Allow SSH
gcloud compute firewall-rules create allow-ssh \
  --allow tcp:22 \
  --source-ranges 0.0.0.0/0 \
  --description "Allow SSH"

# Allow Cortex API (restrict source in production)
gcloud compute firewall-rules create allow-cortex-api \
  --allow tcp:8080 \
  --source-ranges 0.0.0.0/0 \
  --description "Allow Cortex AI API"

Azure Virtual Machines

# Using Azure CLI
az vm create \
  --resource-group cortex-rg \
  --name cortex-linux \
  --image CortexLinux:cortex-linux:1.0.0:latest \
  --size Standard_B2s \
  --admin-username azureuser \
  --generate-ssh-keys

Post-Installation Setup

Initial System Configuration

# Update system packages
sudo apt update
sudo apt upgrade -y

# Set timezone
sudo timedatectl set-timezone America/New_York

# Configure hostname
sudo hostnamectl set-hostname cortex-linux

# Verify AI engine status
sudo systemctl status cortex-ai

Configure Cortex AI Service

# Check service status
systemctl status cortex-ai

# Enable on boot
sudo systemctl enable cortex-ai

# Start service
sudo systemctl start cortex-ai

# View logs
journalctl -u cortex-ai -f

Configure HTTP API (Optional)

Edit /etc/cortex-ai/config.yaml:

server:
  host: 0.0.0.0
  port: 8080
  enable_cors: true
  
security:
  api_key_required: false  # Set to true for production
  allowed_ips: []  # Restrict access if needed
  
ai:
  model_path: /usr/lib/cortex-ai/models/sapiens-0.27b
  max_memory_mb: 512
  num_threads: 4

Restart service:

sudo systemctl restart cortex-ai

Test Installation

# Test CLI
cortex-ai reason "What is 2+2?"

# Test HTTP API
curl -X POST http://localhost:8080/reason \
  -H "Content-Type: application/json" \
  -d '{"query": "Test query"}'

# Check system resources
cortex-ai status

Network Configuration

# Configure static IP (if needed)
sudo nano /etc/netplan/01-netcfg.yaml

# Example configuration
network:
  version: 2
  ethernets:
    eth0:
      dhcp4: false
      addresses:
        - 192.168.1.100/24
      gateway4: 192.168.1.1
      nameservers:
        addresses:
          - 8.8.8.8
          - 8.8.4.4

# Apply changes
sudo netplan apply

Firewall Configuration

# Install UFW (if not present)
sudo apt install ufw

# Allow SSH
sudo ufw allow 22/tcp

# Allow Cortex API (if exposing)
sudo ufw allow 8080/tcp

# Enable firewall
sudo ufw enable

# Check status
sudo ufw status

Troubleshooting

Installation Issues

Boot Failure

Symptoms: System fails to boot from installation media

Solutions:

# Verify ISO integrity
sha256sum cortex-linux-1.0.0.iso
# Compare with published checksum

# Try different boot mode
# UEFI vs Legacy BIOS
# Disable Secure Boot

# Check USB drive
# Use different USB port
# Try different USB drive

Installation Hangs

Symptoms: Installer freezes during installation

Solutions:

# Check system resources
# Ensure sufficient RAM (4GB+)
# Verify disk space (20GB+)

# Try text-based installer
# Boot with: cortex text

# Check for hardware compatibility
# Review kernel logs: dmesg | tail -100

Partitioning Errors

Symptoms: Cannot create or format partitions

Solutions:

# Check disk for errors
sudo badblocks -v /dev/sda

# Verify partition table
sudo fdisk -l /dev/sda

# Use manual partitioning
# Create partitions manually in installer

# For dual-boot systems
# Ensure sufficient unallocated space
# Verify boot mode (UEFI/BIOS) matches existing OS

Post-Installation Issues

AI Service Not Starting

Symptoms: systemctl status cortex-ai shows failed state

Solutions:

# Check service logs
journalctl -u cortex-ai -n 50

# Verify model files
ls -lh /usr/lib/cortex-ai/models/

# Check permissions
sudo chown -R cortex-ai:cortex-ai /usr/lib/cortex-ai/

# Verify system resources
free -h
df -h

# Reinstall AI engine
sudo apt remove cortex-ai
sudo apt install cortex-ai

HTTP API Not Responding

Symptoms: API endpoints return connection refused

Solutions:

# Check if service is running
systemctl status cortex-ai

# Verify port is listening
sudo netstat -tlnp | grep 8080
# or
sudo ss -tlnp | grep 8080

# Check firewall
sudo ufw status
sudo ufw allow 8080/tcp

# Verify configuration
cat /etc/cortex-ai/config.yaml

# Test locally
curl http://localhost:8080/health

Performance Issues

Symptoms: Slow AI responses, high CPU usage

Solutions:

# Check system resources
htop
# or
top

# Verify CPU affinity
taskset -p $(pgrep cortex-ai)

# Adjust thread count in config
# /etc/cortex-ai/config.yaml
# ai.num_threads: 2  # Reduce if CPU-bound

# Check memory usage
free -h
# Increase swap if needed
sudo swapon --show

Cloud-Specific Issues

AWS: Instance Not Accessible

# Check security groups
aws ec2 describe-security-groups --group-ids sg-xxxxx

# Verify key pair
ssh -i your-key.pem -v ec2-user@instance-ip

# Check instance status
aws ec2 describe-instance-status --instance-ids i-xxxxx

DigitalOcean: Droplet Not Booting

# Check droplet status
doctl compute droplet get droplet-id

# Access console via web interface
# DigitalOcean → Droplets → Your Droplet → Access → Launch Console

# Verify image
doctl compute image list

Getting Help

If you encounter issues not covered here:

  1. Check Logs: journalctl -xe for system-wide issues
  2. Review Documentation: FAQ, Technical Specifications
  3. Community Support: GitHub Issues
  4. Search Existing Issues: Check if your problem has been reported

Next Steps

After successful installation:

  1. Configure AI Integration: AI Integration Guide
  2. Explore Use Cases: Use Cases and Tutorials
  3. Review Security: Security and Compliance
  4. Read Developer Docs: Developer Documentation

Last updated: 2024

Clone this wiki locally