SAGE OS 🌱🧠

Self-Aware General Environment
An experimental, bare-metal operating system designed from scratch to learn, adapt, and evolve — starting on Raspberry Pi.

For detailed usage instructions, see USAGE_GUIDE.md

🔭 Vision

SAGE OS is not just another operating system. It is a living, evolving system designed to:

• Think autonomously
• Learn from usage patterns
• Optimize itself through artificial intelligence
• Rebuild and evolve its components as needed

This is an experiment at the intersection of kernel engineering, embedded systems, and machine intelligence — pushing the boundaries of what an operating system can become.

🚀 Features

• Multi-Architecture Support: Full support for i386, x86_64, aarch64, arm, and riscv64
• Custom Bootloaders: Architecture-specific boot code with multiboot support
• Bare-Metal Kernel: Written in C and assembly for maximum performance
• AI Subsystem: Integrated AI capabilities with the AI HAT+ accelerator
• Memory Management: Efficient memory allocation and management
• Shell Interface: Interactive command-line interface with VGA/UART output
• Hardware Abstraction: Support for Raspberry Pi 3, 4, 5, and x86 systems
• Device Drivers: UART, VGA, Serial, GPIO, I2C, SPI, and AI HAT+ drivers
• QEMU Emulation: Full testing support with safe tmux-based testing
• Docker Integration: Containerized builds and deployment
• Security Scanning: Comprehensive CVE vulnerability scanning
• Build System: Automated multi-architecture builds with macOS support

🧠 AI & Machine Learning Integration

SAGE OS includes embedded, resource-efficient AI components that can:

• Perform local inference using the AI HAT+ with up to 26 TOPS
• Support multiple model formats and precisions (FP32, FP16, INT8, INT4)
• Observe usage and optimize scheduling
• Trigger self-diagnostics and reconfiguration
• Dynamically adjust power consumption based on workload
• Monitor system health and performance
• Eventually, enable modular regeneration of subsystems

The AI HAT+ provides hardware acceleration for neural networks with:

• Up to 26 TOPS of neural processing power
• 4GB of dedicated memory for AI models
• Support for various model types (classification, detection, segmentation, generation)
• Power-efficient operation with multiple power modes
• Temperature monitoring and thermal management
• High-speed data transfer using SPI and control via I2C

🧰 Tech Stack

• Languages: ARM Assembly, C (kernel), Rust (core components), Python (tools & ML prototyping)
• Platform: Raspberry Pi 4B/5 (64-bit ARMv8/ARMv9)
• Toolchain: aarch64-linux-gnu-gcc, rustc, QEMU, CMake, TinyML (TFLM, uTensor)
• Build Environment: Cross-compilation (Linux, macOS)
• AI Acceleration: AI HAT+ with up to 26 TOPS neural processing

📦 Project Structure

📦 Folder Structure

• boot/ - Architecture-specific boot code
• kernel/ - Core kernel functionality
• drivers/ - Hardware drivers
• scripts/ - Utility scripts for building and testing

SAGE-OS/
├── boot/                  # Boot code
│   └── boot.S             # ARM64 boot assembly
├── kernel/                # Kernel components
│   ├── kernel.c           # Kernel main entry point
│   ├── memory.c           # Memory management
│   ├── shell.c            # Interactive shell
│   ├── stdio.c            # Standard I/O functions
│   └── ai/                # AI subsystem
│       └── ai_subsystem.c # AI subsystem implementation
├── drivers/               # Hardware drivers
│   ├── uart.c             # UART driver
│   ├── i2c.c              # I2C driver
│   ├── spi.c              # SPI driver
│   └── ai_hat/            # AI HAT+ driver
│       ├── ai_hat.c       # AI HAT+ implementation
│       └── ai_hat.h       # AI HAT+ interface
├── config.txt             # Raspberry Pi 3/4 configuration
├── config_rpi5.txt        # Raspberry Pi 5 configuration
├── linker.ld              # Linker script
├── Makefile               # Build system
└── run_qemu.sh            # QEMU runner script

🚀 Getting Started

🔧 Quick Setup (Automated)

# Clone repository
git clone //github.com/AshishYesale7/SAGE-OS.git
cd SAGE-OS
git checkout dev

# Install all dependencies automatically
chmod +x scripts/install-dependencies.sh
./scripts/install-dependencies.sh

# Build all architectures
./build.sh build-all

# Test with QEMU (safe method)
./build.sh  # Choose option 8 for QEMU testing

# Run comprehensive tests
chmod +x scripts/test-all-features.sh
./scripts/test-all-features.sh

📚 Documentation

• Developer Guide - Comprehensive setup and usage guide
• Quick Reference - Essential commands and troubleshooting
• Architecture Guide - System architecture details

🏗️ Supported Architectures

Architecture	Status	QEMU Support	Real Hardware
i386	✅ Working	✅ Full	✅ PC/VM
x86_64	✅ Working	✅ Full	✅ PC/VM
aarch64	✅ Working	✅ Full	✅ RPi 4/5
arm	✅ Working	✅ Full	✅ RPi 3/4
riscv64	✅ Working	✅ Full	⚠️ Limited

🎯 Quick Commands

# Build specific architecture
./build.sh build i386
./build.sh build x86_64

# Create ISO images
./build.sh  # Choose option 7

# Docker builds
make docker-build-all

# Security scanning
./scan-vulnerabilities.sh --format html --arch i386

# Safe QEMU testing (recommended)
tmux new-session -d -s qemu-test
tmux send-keys -t qemu-test "./build.sh" Enter
# Choose option 8, then your architecture
# To exit: tmux kill-session -t qemu-test

🔍 What's New in This Version

• ✅ Fixed QEMU Emulation: All architectures now boot successfully
• ✅ Enhanced Build System: Automated dependency installation
• ✅ Docker Integration: Containerized builds and deployment
• ✅ Security Scanning: CVE vulnerability scanning with multiple output formats
• ✅ Safe Testing: tmux-based QEMU testing to prevent terminal lockups
• ✅ Comprehensive Documentation: Developer guides and quick references
• ✅ Multi-Platform Support: Linux, macOS, and Windows (WSL2) compatibility

Shell Commands

Once booted, SAGE OS provides a shell with the following commands:

• help - Display available commands
• echo [text] - Echo text to the console
• clear - Clear the screen
• meminfo - Display memory information
• reboot - Reboot the system
• version - Display OS version information
• ai info - Display AI subsystem information (if enabled)
• ai temp - Show AI HAT+ temperature (if available)
• ai power - Show AI HAT+ power consumption (if available)
• ai models - List loaded AI models (if any)

🧑‍💻 Contributing

SAGE OS is open to contributions from developers, researchers, and hardware hackers.

• 📜 License (BSD 3-Clause)
• ⚖️ Commercial Use Terms
• 🧠 AI Safety & Ethics Manifesto
• 🛠️ How to Contribute

By contributing, you agree to the above terms.

🔍 Current Development Status

✅ Completed Features

• Multi-Architecture Support: i386, x86_64, aarch64, arm, riscv64
• Custom Bootloaders: Architecture-specific boot code with multiboot support
• Kernel Core: Memory management, process handling, and shell interface
• Device Drivers: UART, VGA, Serial, GPIO drivers
• QEMU Emulation: Full testing support for all architectures
• Build System: Automated builds with dependency management
• Docker Integration: Containerized builds and deployment
• Security Scanning: CVE vulnerability scanning with multiple formats
• Documentation: Comprehensive developer guides and references
• AI HAT+ Support: Neural processing acceleration for Raspberry Pi
• Cross-Platform: Linux, macOS, Windows (WSL2) support

🚧 In Progress

• Enhanced File System: Minimal file system implementation
• Network Stack: Basic networking capabilities
• Process Scheduling: Advanced multi-tasking support
• Power Management: Dynamic power optimization

🔮 Future Plans

• Self-Tuning Scheduler: AI-driven task optimization
• Evolutionary Updates: Self-modifying system capabilities
• Full AI Pipeline: Complete model loading and inference
• Distributed Computing: Multi-node cluster support

📝 License

SAGE OS is dual-licensed under the BSD 3-Clause License and a Commercial License.

You may use this project under the terms of the BSD 3-Clause License as stated in the LICENSE file.
Alternatively, commercial use with extended rights is available — contact the author for commercial licensing.

See the LICENSE file for details.

🎨 Graphics Mode (macOS Optimized)

Quick Start for macOS

# Build and run i386 graphics (recommended for macOS)
./build-i386-graphics.sh
./run-i386-graphics.sh cocoa

# Or use unified launcher
./sage-os-launcher.sh

Build Options

• ./build-i386-graphics.sh - Dedicated i386 graphics builder
• ./build-graphics-smart.sh - Smart architecture detection
• make graphics-i386 - Makefile target

Run Options

• ./run-i386-graphics.sh cocoa - Native macOS window
• ./run-i386-graphics.sh vnc - VNC mode
• ./quick-graphics-macos.sh - Interactive menu

Verification

./verify-build-system.sh  # Comprehensive verification
./test-i386-build.sh      # Quick build test