AeThex-OS/docs/AETHEX_LINUX.md

AeThex Linux - Bootable OS Distribution

What Is AeThex Linux?

AeThex Linux is a custom Linux distribution that boots directly into the AeThex-OS desktop environment. Instead of accessing your CloudOS through a browser, it becomes the primary operating system interface.

Three Deployment Modes

Mode	Description	Use Case
Web	Browser-based, hosted on Railway	Public access, multi-tenant SaaS
Desktop	Tauri app (Windows/Mac/Linux)	Single-user, native app
Linux Distro	Bootable OS replacing Windows/Mac	Full system replacement, kiosks, custom hardware

Architecture

┌─────────────────────────────────────────┐
│         AeThex Linux Boot Flow          │
└─────────────────────────────────────────┘

Hardware Power On
    ↓
BIOS/UEFI Firmware
    ↓
GRUB Bootloader (AeThex branded)
    ↓
Linux Kernel 6.x (Ubuntu 24.04 LTS base)
    ↓
Systemd Init System
    ↓
├─ Network Manager
├─ Audio (PulseAudio/PipeWire)
├─ Display Server (Wayland/X11)
└─ AeThex Session Manager
    ↓
┌──────────────────────────────────────┐
│   AeThex Desktop Environment (DE)     │
├──────────────────────────────────────┤
│  Window Manager    [Your React UI]   │
│  File Manager      [Already built]   │
│  Terminal          [Already built]   │
│  Settings          [Already built]   │
│  Projects App      [Already built]   │
│  Messaging         [Already built]   │
│  Marketplace       [Already built]   │
└──────────────────────────────────────┘
    ↓
Hardware Access (Full system control)

Technical Stack

Base System

• Distribution Base: Ubuntu 24.04 LTS (Noble Numbat)
• Kernel: Linux 6.8+
• Init System: systemd
• Display Server: Wayland (primary) / X11 (fallback)
• Package Manager: apt + snap (optional)

Desktop Layer

• Shell: Tauri + React (your existing codebase)
• Window Manager: Custom (your drag/drop windows)
• Compositor: Mutter or custom Wayland compositor
• File Manager: Your existing File Manager component
• Terminal: Your existing Terminal component

System Services

/etc/systemd/system/
├── aethex-desktop.service      # Main DE launcher
├── aethex-kernel.service       # OS Kernel (entitlements)
├── aethex-network.service      # Network/sync
└── aethex-updater.service      # Auto-updates

Build Process

Phase 1: Base System Setup

1. Create Build Environment

# Install build tools
sudo apt install debootstrap arch-install-scripts squashfs-tools xorriso grub-pc-bin grub-efi-amd64-bin

# Create workspace
mkdir -p ~/aethex-linux-build
cd ~/aethex-linux-build

2. Bootstrap Ubuntu Base

# Create minimal Ubuntu system
sudo debootstrap --arch=amd64 noble chroot http://archive.ubuntu.com/ubuntu/

# Chroot into system
sudo chroot chroot /bin/bash

3. Install Core Packages

# Inside chroot
apt update
apt install -y \
  linux-image-generic \
  grub-efi-amd64 \
  systemd \
  network-manager \
  pulseaudio \
  wayland-protocols \
  xwayland \
  mesa-utils \
  firmware-linux

Phase 2: AeThex Desktop Integration

4. Build Tauri Desktop App

# From your AeThex-OS repo
cd /workspaces/AeThex-OS
npm run tauri:build

# Copy binary to build system
sudo cp src-tauri/target/release/aethex-os \
  ~/aethex-linux-build/chroot/usr/bin/aethex-desktop

# Make executable
sudo chmod +x ~/aethex-linux-build/chroot/usr/bin/aethex-desktop

5. Create Desktop Session

# Create session file
sudo tee ~/aethex-linux-build/chroot/usr/share/xsessions/aethex.desktop << 'EOF'
[Desktop Entry]
Name=AeThex OS
Comment=AeThex Desktop Environment
Exec=/usr/bin/aethex-desktop
Type=Application
DesktopNames=AeThex
X-Ubuntu-Gettext-Domain=aethex-session
EOF

6. Configure Auto-Start

# Create systemd service
sudo tee ~/aethex-linux-build/chroot/etc/systemd/system/aethex-desktop.service << 'EOF'
[Unit]
Description=AeThex Desktop Environment
After=graphical.target
Requires=graphical.target

[Service]
Type=simple
User=aethex
Environment=DISPLAY=:0
Environment=WAYLAND_DISPLAY=wayland-0
ExecStart=/usr/bin/aethex-desktop
Restart=on-failure
RestartSec=5

[Install]
WantedBy=graphical.target
EOF

# Enable service
sudo systemctl enable aethex-desktop.service

Phase 3: System Configuration

7. Create Default User

# Inside chroot
useradd -m -s /bin/bash aethex
echo "aethex:aethex" | chpasswd
usermod -aG sudo,audio,video,plugdev aethex

8. Configure Auto-Login

# Install display manager
apt install -y lightdm

# Configure auto-login
sudo tee /etc/lightdm/lightdm.conf << 'EOF'
[Seat:*]
autologin-user=aethex
autologin-user-timeout=0
user-session=aethex
EOF

9. Brand Bootloader

# Custom GRUB theme
mkdir -p /boot/grub/themes/aethex
# (Add custom logo, colors, fonts)

# Edit /etc/default/grub
GRUB_DISTRIBUTOR="AeThex Linux"
GRUB_CMDLINE_LINUX_DEFAULT="quiet splash"
GRUB_TIMEOUT=3
GRUB_THEME="/boot/grub/themes/aethex/theme.txt"

Phase 4: ISO Creation

10. Generate ISO

# Install Cubic (for advanced ISO building)
sudo apt-add-repository ppa:cubic-wizard/release
sudo apt update
sudo apt install cubic

# Or manual method:
cd ~/aethex-linux-build
sudo mksquashfs chroot filesystem.squashfs -comp xz
sudo mkisofs -r -V "AeThex Linux 1.0" \
  -cache-inodes -J -l \
  -b isolinux/isolinux.bin \
  -c isolinux/boot.cat \
  -no-emul-boot -boot-load-size 4 \
  -boot-info-table \
  -o AeThex-Linux-1.0-amd64.iso \
  iso/

Distribution Files

AeThex-Linux-1.0/
├── aethex-linux-1.0-amd64.iso       # Bootable ISO (2-4 GB)
├── aethex-linux-1.0-amd64.iso.sha256  # Checksum
├── INSTALL.md                       # Installation guide
└── LICENSE                          # GPL v3 + Commercial dual-license

Installation Methods

Method 1: USB Boot (Live System)

# Create bootable USB
sudo dd if=AeThex-Linux-1.0-amd64.iso of=/dev/sdX bs=4M status=progress

Method 2: Virtual Machine

# VirtualBox
VBoxManage createvm --name "AeThex Linux" --ostype Ubuntu_64 --register
VBoxManage modifyvm "AeThex Linux" --memory 4096 --vram 128
VBoxManage storagectl "AeThex Linux" --name "SATA" --add sata
VBoxManage storageattach "AeThex Linux" --storagectl "SATA" --port 0 --device 0 --type dvddrive --medium AeThex-Linux-1.0-amd64.iso

Method 3: Dual Boot (Alongside Windows)

1. Create partition (GParted or Windows Disk Manager)
2. Boot from USB
3. Run installer (Ubiquity/Calamares)
4. GRUB automatically detects Windows

Method 4: Full Installation (Replace OS)

• Boot from USB
• Select "Erase disk and install AeThex Linux"
• Complete installation wizard

Features Unique to AeThex Linux

System-Level Integration

// Full hardware access (not available in web/desktop modes)
- Direct GPU access for 3D acceleration
- Raw disk I/O for file operations
- Kernel module loading for custom drivers
- System service management (systemctl)
- Network configuration (NetworkManager API)

Offline-First

// Works completely offline
- Local database (SQLite instead of Supabase)
- Local authentication (PAM integration)
- Cached assets and apps
- Sync when network available

Performance

Metric              | Web    | Desktop | Linux
--------------------|--------|---------|-------
Boot Time           | N/A    | 3-5s    | 10-15s
Memory Usage        | 200MB  | 150MB   | 300MB (full OS)
Disk Space          | 0      | 100MB   | 2-4GB (full system)
Startup App Launch  | 1-2s   | <1s     | <500ms

Customization Options

Minimal Edition (Kiosk Mode)

• 800MB ISO
• No package manager
• Read-only root filesystem
• Purpose-built for single-use devices

Developer Edition

• Pre-installed: Node.js, Python, Rust, Docker
• VS Code (or VSCodium)
• Git, build tools
• Full package manager

Enterprise Edition

• Active Directory integration
• Centralized management (Ansible/Puppet)
• Pre-configured VPN
• Compliance tools (SELinux)

Maintenance & Updates

Update Channels

# Stable (quarterly)
sudo apt update && sudo apt upgrade

# Rolling (weekly)
sudo add-apt-repository ppa:aethex/rolling

# Nightly (for developers)
sudo add-apt-repository ppa:aethex/nightly

Auto-Update Service

// /usr/bin/aethex-updater
- Check for updates daily
- Download in background
- Prompt user for installation
- Rollback on failure

Security Model

Sandboxing

• Snap/Flatpak for untrusted apps
• AppArmor profiles for system services
• SELinux (optional, enterprise)

Authentication

• PAM integration for system login
• Biometric support (fingerprint/face)
• Hardware keys (YubiKey, FIDO2)
• Dual-mode: local + cloud sync

Build Scripts

Ready to generate build automation scripts? I can create:

1. script/build-linux-iso.sh - Full automated ISO builder
2. script/test-in-vm.sh - Automated VM testing
3. docs/LINUX_BUILD_GUIDE.md - Step-by-step instructions
4. configs/branding/ - GRUB theme, plymouth splash, wallpapers

Next Steps

Choose your path:

Path A: Proof of Concept (1 day)

• Basic Ubuntu + Tauri app
• Manual boot to desktop
• VM testing only

Path B: Distributable ISO (1 week)

• Automated build scripts
• Branded installer
• Basic hardware support

Path C: Full Distribution (1-3 months)

• Custom repositories
• Update infrastructure
• Hardware certification
• Community/documentation

Which path interests you?