Skip to content

Installation

This guide covers installing Cortex Linux on physical hardware, virtual machines, and cloud platforms.

Installation Methods

flowchart TD
    A[Choose Installation Method] --> B{Hardware Type}
    B -->|Physical| C[ISO Installation]
    B -->|Virtual| D[VM Image]
    B -->|Cloud| E[Cloud Image]
    B -->|Container| F[Docker Image]

    C --> G[Boot from USB]
    D --> H[Import OVA/QCOW2]
    E --> I[Launch Instance]
    F --> J[docker run]

ISO Installation

Download

Download the latest stable ISO from the official releases page:

# Download ISO
curl -LO https://releases.cortexlinux.com/stable/cortex-2024.1.iso

# Download checksum
curl -LO https://releases.cortexlinux.com/stable/cortex-2024.1.iso.sha256

# Verify integrity
sha256sum -c cortex-2024.1.iso.sha256

Create Bootable USB

# Identify your USB device
lsblk

# Write ISO to USB (replace /dev/sdX with your device)
sudo dd if=cortex-2024.1.iso of=/dev/sdX bs=4M status=progress oflag=sync

# Sync and safely eject
sync
sudo eject /dev/sdX

# List disks to identify USB
diskutil list

# Unmount the USB disk
diskutil unmountDisk /dev/diskN

# Write ISO
sudo dd if=cortex-2024.1.iso of=/dev/rdiskN bs=4m

# Eject
diskutil eject /dev/diskN

Use Rufus or balenaEtcher:

  1. Download and run Rufus
  2. Select the Cortex ISO
  3. Select your USB drive
  4. Click "Start"

Boot and Install

  1. Boot from USB: Insert the USB drive and boot your system. Access BIOS/UEFI (usually F2, F12, or DEL) and select USB as boot device.

  2. Select Installation Mode:

    • Guided Install: Recommended for most users
    • Expert Install: Full control over partitioning
    • Server Install: Minimal installation without GUI

  3. Configure Disk: 

    ┌─────────────────────────────────────────┐
│ Disk Configuration                       │
├─────────────────────────────────────────┤
│ ○ Use entire disk (recommended)         │
│ ○ Use entire disk with LVM              │
│ ○ Use entire disk with ZFS              │
│ ○ Manual partitioning                   │
└─────────────────────────────────────────┘

  4. Set Up User Account:

    • Username and password
    • SSH key import (optional)
    • Enable root account (optional, not recommended)

  5. Select Components: 

    [x] Cortex CLI (required)
[x] Cortex Ops
[ ] Cortex LLM (requires GPU)
[x] Cortex Security
[ ] Cortex Stacks (Kubernetes)
[ ] Cortex Observe (monitoring)

  6. Complete Installation: The installer will partition disks, install packages, and configure the bootloader. This typically takes 5-15 minutes.

Virtual Machine Installation

VMware / VirtualBox

Download the OVA image:

curl -LO https://releases.cortexlinux.com/stable/cortex-2024.1.ova

Import into your hypervisor:

File → Open → Select cortex-2024.1.ova

Recommended settings:

Setting Value
CPUs 4+
Memory 8192 MB
Disk 64 GB (thin provisioned)
Network Bridged or NAT 
File → Import Appliance → Select cortex-2024.1.ova

QEMU / KVM

Download the QCOW2 image:

curl -LO https://releases.cortexlinux.com/stable/cortex-2024.1.qcow2

Create and start VM:

# Create VM with virt-install
virt-install \
  --name cortex \
  --memory 8192 \
  --vcpus 4 \
  --disk path=cortex-2024.1.qcow2,format=qcow2 \
  --import \
  --os-variant ubuntu22.04 \
  --network bridge=virbr0

# Or start directly with QEMU
qemu-system-x86_64 \
  -enable-kvm \
  -m 8G \
  -smp 4 \
  -drive file=cortex-2024.1.qcow2,format=qcow2 \
  -net nic -net user,hostfwd=tcp::2222-:22

Cloud Installation

Amazon Web Services (AWS)

# Find the latest Cortex AMI
aws ec2 describe-images \
  --owners 123456789012 \
  --filters "Name=name,Values=cortex-*" \
  --query 'Images | sort_by(@, &CreationDate) | [-1]'

# Launch instance
aws ec2 run-instances \
  --image-id ami-0123456789abcdef0 \
  --instance-type t3.xlarge \
  --key-name your-key \
  --security-group-ids sg-0123456789abcdef0 \
  --subnet-id subnet-0123456789abcdef0

# For GPU workloads
aws ec2 run-instances \
  --image-id ami-0123456789abcdef0 \
  --instance-type p3.2xlarge \
  --key-name your-key

Google Cloud Platform (GCP)

# Create instance
gcloud compute instances create cortex-vm \
  --image-family=cortex-stable \
  --image-project=cortexlinux \
  --machine-type=n2-standard-4 \
  --boot-disk-size=100GB \
  --zone=us-central1-a

# For GPU workloads
gcloud compute instances create cortex-gpu \
  --image-family=cortex-stable \
  --image-project=cortexlinux \
  --machine-type=n1-standard-8 \
  --accelerator=type=nvidia-tesla-t4,count=1 \
  --maintenance-policy=TERMINATE \
  --zone=us-central1-a

Microsoft Azure

# Create resource group
az group create --name cortex-rg --location eastus

# Create VM
az vm create \
  --resource-group cortex-rg \
  --name cortex-vm \
  --image cortexlinux:cortex:stable:latest \
  --size Standard_D4s_v3 \
  --admin-username cortex \
  --generate-ssh-keys

# For GPU workloads
az vm create \
  --resource-group cortex-rg \
  --name cortex-gpu \
  --image cortexlinux:cortex:stable:latest \
  --size Standard_NC6s_v3 \
  --admin-username cortex \
  --generate-ssh-keys

Container Installation

Docker

# Pull the latest image
docker pull cortexlinux/cortex:latest

# Run interactive shell
docker run -it cortexlinux/cortex

# Run with GPU support (NVIDIA)
docker run --gpus all -it cortexlinux/cortex

# Run with persistent storage
docker run -it \
  -v cortex-data:/var/lib/cortex \
  -v cortex-config:/etc/cortex \
  cortexlinux/cortex

Podman

# Pull and run
podman pull docker.io/cortexlinux/cortex:latest
podman run -it cortexlinux/cortex

Post-Installation

After installation, verify your system:

# Check Cortex version
cortex --version

# Run system diagnostics
cortex-ops doctor

# View system status
cortex status

Continue to Quick Start to begin using Cortex Linux.

Troubleshooting Installation

Boot Issues

UEFI Secure Boot

Cortex Linux supports Secure Boot, but you may need to enroll the Cortex signing key in your UEFI firmware.

# Check if booted in UEFI mode
[ -d /sys/firmware/efi ] && echo "UEFI" || echo "BIOS"

# Enroll MOK key (if prompted)
mokutil --import /var/lib/shim-signed/mok/MOK.der

GPU Not Detected

# Check for NVIDIA GPU
lspci | grep -i nvidia

# Install NVIDIA drivers
sudo apt install nvidia-driver-535

# Verify installation
nvidia-smi

Network Issues

# Check network interfaces
ip link show

# Restart networking
sudo systemctl restart NetworkManager

# Check DNS resolution
dig cortexlinux.com