Skip to content

SAGE-OS Documentation

Self-Aware General Environment Operating System

Welcome to the comprehensive documentation for SAGE-OS, a revolutionary embedded operating system with integrated AI capabilities.

Documentation last updated: 2025-06-14

๐Ÿš€ Quick Navigation

- :material-rocket-launch:{ .lg .middle } **Getting Started** --- Get SAGE-OS running in minutes [:octicons-arrow-right-24: Quick Start](getting-started/quick-start.md) - :material-hammer-wrench:{ .lg .middle } **Build Guide** --- Complete build instructions for all platforms [:octicons-arrow-right-24: Build System](build-guide/build-system.md) - :material-sitemap:{ .lg .middle } **Architecture** --- System design and component overview [:octicons-arrow-right-24: Architecture](architecture/system-overview.md) - :material-api:{ .lg .middle } **API Reference** --- Complete API documentation [:octicons-arrow-right-24: API Docs](api/kernel.md)

โœจ Key Features

- **๐Ÿง  AI Integration** Built-in AI subsystem with GitHub Models API and local processing - **๐Ÿ—๏ธ Multi-Architecture** Support for i386, AArch64, RISC-V, and x86_64 architectures - **๐Ÿ–ฅ๏ธ Graphics Support** VGA graphics with text and graphics modes - **๐Ÿ”ง Modern Build System** CMake and Makefile-based build system with cross-compilation - **๐Ÿงช Comprehensive Testing** QEMU integration for all supported architectures - **๐Ÿ“š Auto-Generated Docs** AI-powered documentation generation and updates

๐ŸŽฏ Architecture Support Matrix

Architecture Build Status QEMU Support Hardware Support Notes
i386 โœ… Perfect โœ… Excellent โœ… Full Primary development target
AArch64 โœ… Perfect โœ… Excellent โœ… Full ARM 64-bit, Raspberry Pi 4/5
RISC-V โš ๏ธ Partial โœ… Good ๐Ÿ”„ Limited Needs kernel entry point fix
x86_64 ๐Ÿ”„ WIP โš ๏ธ Limited ๐Ÿ”„ Planned Requires multiboot2 support
ARM ๐Ÿ”„ Planned ๐Ÿ”„ Planned ๐Ÿ”„ Planned Future release target

๐Ÿ“Š Project Statistics

Metric Value
Documentation Pages 25+
Supported Architectures 4
Build Targets 10+
Test Configurations 15+
Last Updated 2025-06-14

๐Ÿš€ Quick Start

Get up and running with SAGE OS in minutes:

# Clone the repository
git clone https://github.com/AshishYesale7/SAGE-OS.git
cd SAGE-OS

# Build for your architecture
make build ARCH=x86_64

# Create bootable ISO
make iso ARCH=x86_64

# Run in emulator
make run ARCH=x86_64

๐Ÿ“– Detailed Installation Guide โ†’


๐Ÿ›๏ธ Architecture Overview

graph TB
    subgraph "User Space"
        A[Applications]
        B[System Services]
        C[Libraries]
    end

    subgraph "Kernel Space"
        D[System Call Interface]
        E[Process Manager]
        F[Memory Manager]
        G[File System]
        H[Device Drivers]
        I[Network Stack]
    end

    subgraph "Hardware"
        J[CPU]
        K[Memory]
        L[Storage]
        M[Network]
        N[Peripherals]
    end

    A --> D
    B --> D
    C --> D
    D --> E
    D --> F
    D --> G
    E --> H
    F --> H
    G --> H
    H --> J
    H --> K
    H --> L
    I --> M
    H --> N

๐Ÿ—๏ธ Detailed Architecture โ†’


๐Ÿ“ Project Structure

The SAGE OS project is organized into logical components:

SAGE-OS/
โ”œโ”€โ”€ ๐Ÿฅพ bootloader/          # Multi-stage bootloader
โ”‚   โ”œโ”€โ”€ stage1/            # Initial boot stage
โ”‚   โ”œโ”€โ”€ stage2/            # Extended bootloader
โ”‚   โ””โ”€โ”€ uefi/              # UEFI boot support
โ”œโ”€โ”€ ๐Ÿง  kernel/             # Kernel implementation
โ”‚   โ”œโ”€โ”€ arch/              # Architecture-specific code
โ”‚   โ”œโ”€โ”€ drivers/           # Device drivers
โ”‚   โ”œโ”€โ”€ fs/                # File systems
โ”‚   โ”œโ”€โ”€ mm/                # Memory management
โ”‚   โ””โ”€โ”€ proc/              # Process management
โ”œโ”€โ”€ ๐Ÿ‘ฅ userspace/          # User space components
โ”‚   โ”œโ”€โ”€ init/              # Init system
โ”‚   โ”œโ”€โ”€ shell/             # Command shell
โ”‚   โ””โ”€โ”€ utils/             # System utilities
โ”œโ”€โ”€ ๐Ÿ”ง tools/              # Development tools
โ”œโ”€โ”€ ๐Ÿ“š docs/               # Documentation
โ”œโ”€โ”€ ๐Ÿงช tests/              # Test suites
โ””โ”€โ”€ ๐Ÿ“ฆ scripts/            # Build scripts

๐Ÿ“‚ Complete File Reference โ†’


๐Ÿ› ๏ธ Development Workflow

sequenceDiagram
    participant Dev as Developer
    participant Git as Git Repository
    participant CI as GitHub Actions
    participant Test as Test Suite
    participant Deploy as Deployment

    Dev->>Git: Push changes
    Git->>CI: Trigger workflow
    CI->>Test: Run tests
    Test->>CI: Test results
    CI->>Deploy: Build artifacts
    Deploy->>Dev: Feedback

Development Process

  1. ๐Ÿ”€ Fork & Clone: Start with your own fork
  2. ๐ŸŒฟ Branch: Create feature branches
  3. ๐Ÿ’ป Develop: Write code following our standards
  4. ๐Ÿงช Test: Run comprehensive test suites
  5. ๐Ÿ“ Document: Update documentation
  6. ๐Ÿ” Review: Submit pull requests
  7. ๐Ÿš€ Deploy: Automated deployment

๐Ÿ‘จโ€๐Ÿ’ป Contributing Guide โ†’


๐Ÿ”’ Security & Compliance

SAGE OS takes security seriously with multiple layers of protection:

Security Features

Feature Description Status
๐Ÿ›ก๏ธ Memory Safety Rust-based memory management โœ… Active
๐Ÿ” Secure Boot Hardware-backed verification โœ… Active
๐Ÿ” CVE Scanning Automated vulnerability detection โœ… Active
๐Ÿšซ ASLR Address Space Layout Randomization โœ… Active
๐Ÿ”’ DEP/NX Data Execution Prevention โœ… Active
๐Ÿ›ก๏ธ Stack Protection Stack canaries and guards โœ… Active

Vulnerability Management

We use automated tools to continuously monitor for security vulnerabilities:

  • CVE Binary Tool: Scans all binaries for known vulnerabilities
  • Dependency Scanning: Monitors third-party dependencies
  • Static Analysis: Code analysis for security issues
  • Penetration Testing: Regular security assessments

๐Ÿ”’ Security Documentation โ†’


๐Ÿ“Š Platform Support

Architecture Status Bootloader Kernel Userspace Testing
x86_64 โœ… Stable โœ… GRUB/UEFI โœ… Full โœ… Complete โœ… CI/CD
ARM64 โœ… Stable โœ… U-Boot โœ… Full โœ… Complete โœ… CI/CD
RISC-V ๐Ÿšง Beta โœ… OpenSBI โœ… Core ๐Ÿšง Partial โœ… CI/CD

๐Ÿ—๏ธ Multi-Architecture Guide โ†’


๐Ÿ“š Documentation Sections

- :material-rocket-launch: **Getting Started** --- Quick setup and installation guides [:octicons-arrow-right-24: Installation](getting-started/installation.md) [:octicons-arrow-right-24: Building](getting-started/building.md) [:octicons-arrow-right-24: First Boot](getting-started/first-boot.md) - :material-cog: **Architecture** --- Deep dive into system design [:octicons-arrow-right-24: Overview](architecture/overview.md) [:octicons-arrow-right-24: Kernel](architecture/kernel.md) [:octicons-arrow-right-24: Memory](architecture/memory.md) - :material-code-braces: **Development** --- Developer resources and guides [:octicons-arrow-right-24: Contributing](development/contributing.md) [:octicons-arrow-right-24: Testing](development/testing.md) [:octicons-arrow-right-24: Debugging](development/debugging.md) - :material-shield-check: **Security** --- Security features and best practices [:octicons-arrow-right-24: Overview](security/overview.md) [:octicons-arrow-right-24: CVE Scanning](security/cve-scanning.md) [:octicons-arrow-right-24: Best Practices](security/best-practices.md)

๐Ÿค Community & Support

Get Involved

Contributing

We welcome contributions of all kinds:

  • ๐Ÿ› Bug reports and fixes
  • โœจ New features and enhancements
  • ๐Ÿ“š Documentation improvements
  • ๐Ÿงช Test coverage expansion
  • ๐ŸŽจ UI/UX improvements

๐Ÿค How to Contribute โ†’


๐Ÿ“„ License

SAGE OS is dual-licensed to provide flexibility for different use cases:

  • ๐Ÿ†“ Open Source: BSD 3-Clause License for open source projects
  • ๐Ÿ’ผ Commercial: Commercial license for proprietary applications

๐Ÿ“„ License Details โ†’


Built with โค๏ธ by the SAGE OS Team

Copyright ยฉ 2025 Ashish Vasant Yesale