Initial commit: Alpine Zero-OS initramfs build system with cleaned Docker configuration

2025-08-15 22:11:44 +02:00
commit 9b14d94bbe
34 changed files with 12864 additions and 0 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -0,0 +1,51 @@
+# Build artifacts
+output/
+cache/
+
+# Git submodules directory (managed separately)
+components/
+
+# Docker artifacts
+.dockerignore
+
+# Build logs and temporary files
+*.log
+*.tmp
+.buildlog
+
+# OS-specific files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Editor/IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Kernel build artifacts
+*.ko
+*.o
+*.mod.c
+.tmp_versions/
+modules.order
+Module.symvers
+
+# Alpine/Linux temporary files
+.alpine-*
+initramfs-*
+
+# Backup files
+*.bak
+*.backup
+*.orig
+
+# Test artifacts
+test-output/
+test-cache/
--- a/README.md
+++ b/README.md
@@ -0,0 +1,67 @@
+# Alpine-based Zero-OS Initramfs
+
+Modern Alpine Linux based approach to building Zero-OS initramfs, replacing the complex build-from-source system with Alpine packages.
+
+## Architecture Overview
+
+This system uses:
+- **Alpine Linux LTS** as base system (latest packages, no building from source)
+- **Alpine kernel** with embedded essential storage/ethernet modules  
+- **GitHub components**: zinit, core-x, seektime, rfs (only custom builds needed)
+- **Same init flow**: tmpfs copy approach for compatibility
+- **Alpine packages**: All standard tools (busybox, openssh, btrfs-progs, etc.)
+
+## Directory Structure
+
+```
+alpine-initramfs/
+├── build/                     # Build orchestration
+│   ├── Dockerfile.alpine      # Alpine build environment
+│   ├── docker-compose.yml     # Build orchestration
+│   └── build-initramfs.sh     # Main build script
+├── configs/                   # Configuration files
+│   ├── packages.txt           # Alpine packages to install
+│   ├── kernel-modules.txt     # Essential modules to embed
+│   ├── init                   # Custom init script (Alpine → zinit)
+│   └── zinit/                 # Zinit service configs (from ../config/etc/zinit/)
+├── scripts/                   # Build helper scripts
+│   ├── fetch-github.sh        # Download zinit, core-x, seektime, rfs
+│   ├── install-packages.sh    # Install Alpine packages to initramfs
+│   ├── setup-initramfs.sh     # Create initramfs structure
+│   └── build-kernel.sh        # Build kernel with embedded initramfs
+├── output/                    # Build artifacts
+│   ├── initramfs.cpio.xz      # Generated initramfs
+│   ├── vmlinuz.efi            # Final bootable kernel
+│   └── modules/               # Kernel modules
+└── docs/                      # Documentation
+    ├── PACKAGES.md            # Package mapping (old build → Alpine)
+    ├── MODULES.md             # Kernel modules reference
+    └── BUILD.md               # Build process guide
+```
+
+## Build Flow
+
+1. **Alpine Environment**: Setup Alpine LTS build container
+2. **Package Installation**: Install all required Alpine packages
+3. **GitHub Components**: Fetch zinit, core-x, seektime, rfs from releases
+4. **Initramfs Assembly**: Create filesystem structure with same tmpfs approach
+5. **Kernel Build**: Compile Alpine kernel with embedded essential modules
+6. **Output**: Generate bootable vmlinuz.efi with embedded initramfs
+
+## Quick Start
+
+```bash
+cd alpine-initramfs/build
+docker compose build
+docker compose run --rm builder
+# Output: ../output/vmlinuz.efi
+```
+
+## Key Advantages
+
+- ✅ **No source compilation** - Use Alpine's maintained packages
+- ✅ **Latest versions** - Always current with Alpine package updates  
+- ✅ **Faster builds** - Minutes vs hours
+- ✅ **Smaller footprint** - Alpine's minimal design
+- ✅ **Same functionality** - Identical init flow and service management
+- ✅ **Better maintenance** - Package updates handled by Alpine team
--- a/build.sh
+++ b/build.sh
@@ -0,0 +1,182 @@
+#!/bin/bash
+# Host build script for Alpine Zero-OS Initramfs
+
+set -e
+
+# Colors for output
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+# Function to print colored output
+print_info() {
+    echo -e "${BLUE}[INFO]${NC} $1"
+}
+
+print_success() {
+    echo -e "${GREEN}[SUCCESS]${NC} $1"
+}
+
+print_warning() {
+    echo -e "${YELLOW}[WARNING]${NC} $1"
+}
+
+print_error() {
+    echo -e "${RED}[ERROR]${NC} $1"
+}
+
+# Default values
+BUILDMODE="${BUILDMODE:-debug}"
+SERVICE="builder"
+CLEAN_BUILD=false
+DEV_MODE=false
+MINIMAL_MODE=false
+
+# Help function
+show_help() {
+    echo "Usage: $0 [OPTIONS]"
+    echo ""
+    echo "Options:"
+    echo "  -r, --release      Build in release mode (default: debug)"
+    echo "  -m, --minimal      Build minimal embedded initramfs (~50MB vs 700MB)"
+    echo "  -c, --clean        Clean build without cache volumes"
+    echo "  -d, --dev          Start development container with shell"
+    echo "  -t, --test         Run test build without cache"
+    echo "  -h, --help         Show this help message"
+    echo ""
+    echo "Examples:"
+    echo "  $0                 # Build in debug mode with cache"
+    echo "  $0 --release       # Build in release mode"
+    echo "  $0 --minimal       # Build minimal embedded initramfs"
+    echo "  $0 --clean         # Clean build without cache"
+    echo "  $0 --dev           # Start development shell"
+    echo ""
+    echo "Environment variables:"
+    echo "  BUILDMODE=release  # Override build mode"
+    echo "  TARGETARCH=amd64   # Target architecture"
+    echo ""
+}
+
+# Parse command line arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        -r|--release)
+            BUILDMODE="release"
+            shift
+            ;;
+        -m|--minimal)
+            MINIMAL_MODE=true
+            shift
+            ;;
+        -c|--clean)
+            CLEAN_BUILD=true
+            shift
+            ;;
+        -d|--dev)
+            DEV_MODE=true
+            SERVICE="shell"
+            shift
+            ;;
+        -t|--test)
+            SERVICE="test"
+            shift
+            ;;
+        -h|--help)
+            show_help
+            exit 0
+            ;;
+        *)
+            print_error "Unknown option: $1"
+            show_help
+            exit 1
+            ;;
+    esac
+done
+
+print_info "Alpine Zero-OS Initramfs Builder"
+print_info "Build mode: $BUILDMODE"
+if [ "$MINIMAL_MODE" = true ]; then
+    print_info "Initramfs type: MINIMAL (~50MB embedded cpio)"
+else
+    print_info "Initramfs type: FULL (~700MB with all packages)"
+fi
+print_info "Service: $SERVICE"
+if [ "$CLEAN_BUILD" = true ]; then
+    print_info "Clean build: removing cache and artifacts"
+fi
+
+# Change to build directory
+cd "$(dirname "$0")/build"
+
+# Handle clean build
+if [ "$CLEAN_BUILD" = true ]; then
+    print_info "Cleaning build artifacts and cache..."
+    
+    # Remove output artifacts
+    rm -rf ../output/*
+    print_info "  Removed output artifacts"
+    
+    # Remove cache directories
+    rm -rf ../cache/*
+    print_info "  Removed cache directories"
+    
+    # Remove Docker volumes
+    print_info "  Removing Docker cache volumes..."
+    docker volume rm alpine-initramfs_github-cache alpine-initramfs_kernel-cache 2>/dev/null || true
+    print_info "  Docker cache volumes removed"
+    
+    print_success "Clean completed successfully"
+    exit 0
+fi
+
+# Create necessary directories
+mkdir -p ../output ../cache/github ../cache/packages
+
+# Export environment variables for docker-compose
+export BUILDMODE
+export MINIMAL_MODE
+export TARGETARCH="${TARGETARCH:-amd64}"
+
+if [ "$DEV_MODE" = true ]; then
+    print_info "Starting development container..."
+    docker compose run --rm $SERVICE
+else
+    print_info "Starting build process..."
+    
+    # Build the Docker image first
+    print_info "Building Docker image..."
+    docker compose build $SERVICE
+    
+    # Run the build
+    print_info "Running Alpine initramfs build..."
+    docker compose run --rm $SERVICE
+    
+    # Check if build was successful
+    if [ -f "../output/vmlinuz.efi" ]; then
+        print_success "Build completed successfully!"
+        print_info "Build artifacts:"
+        ls -la ../output/
+        
+        # Show size information
+        size=$(stat -c%s "../output/vmlinuz.efi" 2>/dev/null || stat -f%z "../output/vmlinuz.efi" 2>/dev/null || echo "unknown")
+        print_info "Kernel size: $size bytes"
+        
+        if [ -f "../output/initramfs.cpio.xz" ]; then
+            initramfs_size=$(stat -c%s "../output/initramfs.cpio.xz" 2>/dev/null || stat -f%z "../output/initramfs.cpio.xz" 2>/dev/null || echo "unknown")
+            print_info "Initramfs size: $initramfs_size bytes"
+        fi
+        
+        print_success "Alpine Zero-OS kernel ready: output/vmlinuz.efi"
+        print_info ""
+        print_info "To test with QEMU:"
+        print_info "  qemu-system-x86_64 -kernel output/vmlinuz.efi -m 2048 -enable-kvm -cpu host \\"
+        print_info "    -net nic,model=e1000 -net bridge,br=vm0 -nographic -serial null \\"
+        print_info "    -serial mon:stdio -append console=ttyS1,115200n8"
+        
+    else
+        print_error "Build failed - no kernel image found in output/"
+        exit 1
+    fi
+fi
--- a/build/Dockerfile.alpine
+++ b/build/Dockerfile.alpine
@@ -0,0 +1,71 @@
+# Alpine-based Zero-OS Initramfs Builder
+FROM alpine:3.22
+
+# Set build arguments
+ARG TARGETARCH=amd64
+ARG BUILDMODE=debug
+ARG MINIMAL_MODE=false
+
+# Set environment variables
+ENV BUILDMODE=${BUILDMODE}
+ENV TARGETARCH=${TARGETARCH}
+ENV MINIMAL_MODE=${MINIMAL_MODE}
+ENV PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+
+# Install build dependencies
+RUN apk add --no-cache \
+    # Build tools
+    build-base \
+    linux-headers \
+    cmake \
+    git \
+    wget \
+    curl \
+    cpio \
+    xz \
+    gzip \
+    bc \
+    perl \
+    python3 \
+    # Kernel build dependencies
+    linux-lts-dev \
+    linux-lts \
+    elfutils-dev \
+    openssl-dev \
+    flex \
+    bison \
+    # Archive tools
+    tar \
+    bzip2 \
+    unzip \
+    # Text processing
+    sed \
+    grep \
+    findutils \
+    # JSON processing for GitHub API
+    jq
+
+# Create directories
+RUN mkdir -p /build/initramfs /build/kernel /build/output /build/github /build/configs/zinit /mnt/zinit
+
+# Set working directory
+WORKDIR /build
+
+# Copy build scripts and configs
+COPY scripts/ /build/scripts/
+COPY configs/ /build/configs/
+
+# Make scripts executable
+RUN chmod +x /build/scripts/*.sh
+
+# Create build configuration
+RUN echo "BUILDMODE=${BUILDMODE}" > /build/build.conf && \
+    echo "TARGETARCH=${TARGETARCH}" >> /build/build.conf && \
+    echo "MINIMAL_MODE=${MINIMAL_MODE}" >> /build/build.conf && \
+    echo "INITRAMFS_ROOT=/build/initramfs" >> /build/build.conf && \
+    echo "KERNEL_DIR=/build/kernel" >> /build/build.conf && \
+    echo "OUTPUT_DIR=/build/output" >> /build/build.conf && \
+    echo "CONFIG_DIR=/build/configs" >> /build/build.conf
+
+# Default command
+CMD ["/build/scripts/build-initramfs.sh"]
--- a/build/Dockerfile.cached
+++ b/build/Dockerfile.cached
@@ -0,0 +1,102 @@
+# Multi-stage Alpine Zero-OS Builder with Smart Caching
+# Stage 1: Base build environment (cached until Alpine version changes)
+FROM alpine:3.22 AS base-builder
+
+# Install build dependencies (expensive, cache this layer)
+RUN apk add --no-cache \
+    # Build tools
+    build-base \
+    linux-headers \
+    cmake \
+    git \
+    wget \
+    curl \
+    cpio \
+    xz \
+    gzip \
+    bc \
+    perl \
+    python3 \
+    # Kernel build dependencies
+    linux-lts-dev \
+    linux-lts \
+    elfutils-dev \
+    openssl-dev \
+    flex \
+    bison \
+    # Archive tools
+    tar \
+    bzip2 \
+    unzip \
+    # Text processing
+    sed \
+    grep \
+    findutils \
+    jq \
+    # Go and Rust for source compilation
+    go \
+    rust \
+    cargo
+
+# Create standard directories
+RUN mkdir -p /build/initramfs /build/kernel /build/output /build/github /build/configs/zinit /mnt/zinit /build/source /build/cache
+
+WORKDIR /build
+
+# Stage 2: Zero-OS components (cached until source repos change)
+FROM base-builder AS components-builder
+
+# Copy component compilation script
+COPY scripts/compile-components.sh /build/scripts/
+RUN chmod +x /build/scripts/compile-components.sh
+
+# Create a marker file to track component compilation
+RUN echo "$(date)" > /build/components-build-time
+
+# This stage will be cached unless we explicitly rebuild components
+
+# Stage 3: Kernel builder (cached until kernel version/config changes)  
+FROM components-builder AS kernel-builder
+
+# Copy kernel configuration and version
+COPY configs/kernel-version /build/configs/
+COPY configs/kernel-config-generic /build/configs/
+COPY scripts/build-kernel.sh /build/scripts/
+RUN chmod +x /build/scripts/build-kernel.sh
+
+# Create kernel build marker
+RUN echo "Kernel: $(cat /build/configs/kernel-version)" > /build/kernel-build-marker
+
+# This stage caches kernel source download and basic setup
+
+# Stage 4: Final builder (lightweight layer for initramfs assembly)
+FROM kernel-builder AS final-builder
+
+# Copy all scripts and configs
+COPY scripts/ /build/scripts/
+COPY configs/ /build/configs/
+
+# Make all scripts executable
+RUN chmod +x /build/scripts/*.sh
+
+# Set build arguments
+ARG TARGETARCH=amd64
+ARG BUILDMODE=debug
+ARG MINIMAL_MODE=false
+
+# Set environment variables
+ENV BUILDMODE=${BUILDMODE}
+ENV TARGETARCH=${TARGETARCH}
+ENV MINIMAL_MODE=${MINIMAL_MODE}
+
+# Create build configuration
+RUN echo "BUILDMODE=${BUILDMODE}" > /build/build.conf && \
+    echo "TARGETARCH=${TARGETARCH}" >> /build/build.conf && \
+    echo "MINIMAL_MODE=${MINIMAL_MODE}" >> /build/build.conf && \
+    echo "INITRAMFS_ROOT=/build/initramfs" >> /build/build.conf && \
+    echo "KERNEL_DIR=/build/kernel" >> /build/build.conf && \
+    echo "OUTPUT_DIR=/build/output" >> /build/build.conf && \
+    echo "CONFIG_DIR=/build/configs" >> /build/build.conf
+
+# Default command
+CMD ["/build/scripts/build-initramfs.sh"]
--- a/build/docker-compose.yml
+++ b/build/docker-compose.yml
@@ -0,0 +1,126 @@
+services:
+  # Cached builder using multi-stage Dockerfile
+  builder:
+    build:
+      context: ..
+      dockerfile: build/Dockerfile.cached
+      target: final-builder
+      args:
+        BUILDMODE: "${BUILDMODE:-debug}"
+        TARGETARCH: "${TARGETARCH:-amd64}"
+        MINIMAL_MODE: "${MINIMAL_MODE:-false}"
+    image: zero-os-alpine-builder:cached-${BUILDMODE:-debug}
+    container_name: zero-os-alpine-builder-cached
+    privileged: true
+    volumes:
+      # Mount source configs and scripts (read-only for cache efficiency)
+      - ../configs:/build/configs:ro
+      - ../scripts:/build/scripts:ro
+      # Mount output directory
+      - ../output:/build/output
+      # Persistent cache directories for maximum caching
+      - build-cache:/build/cache
+      - source-cache:/build/source
+      - kernel-cache:/build/kernel
+      # Mount existing zinit config from main project
+      - ../configs/zinit:/mnt/zinit:ro
+    environment:
+      - BUILDMODE=${BUILDMODE:-debug}
+      - TARGETARCH=${TARGETARCH:-amd64}
+      - MINIMAL_MODE=${MINIMAL_MODE:-false}
+    working_dir: /build
+    command: ["/build/scripts/build-smart.sh"]
+  
+  # Legacy builder for comparison/fallback
+  builder-legacy:
+    build:
+      context: ..
+      dockerfile: build/Dockerfile.alpine
+      args:
+        BUILDMODE: "${BUILDMODE:-debug}"
+        TARGETARCH: "${TARGETARCH:-amd64}"
+        MINIMAL_MODE: "${MINIMAL_MODE:-false}"
+    image: zero-os-alpine-builder:legacy
+    container_name: zero-os-alpine-builder-legacy
+    privileged: true
+    volumes:
+      - ../configs:/build/configs:ro
+      - ../scripts:/build/scripts:ro
+      - ../output:/build/output
+      - github-cache:/build/github
+      - kernel-cache-legacy:/build/kernel
+      - ../configs/zinit:/mnt/zinit:ro
+    environment:
+      - BUILDMODE=${BUILDMODE:-debug}
+      - TARGETARCH=${TARGETARCH:-amd64}
+      - MINIMAL_MODE=${MINIMAL_MODE:-false}
+    working_dir: /build
+    command: ["/build/scripts/build-initramfs.sh"]
+
+  # Quick shell access for debugging (uses cached builder)
+  shell:
+    extends: builder
+    container_name: zero-os-alpine-shell
+    command: /bin/sh
+    stdin_open: true
+    tty: true
+
+  # Development shell with full caches
+  dev-shell:
+    extends: builder
+    container_name: zero-os-alpine-dev-shell
+    command: /bin/sh
+    stdin_open: true
+    tty: true
+    volumes:
+      - ../configs:/build/configs
+      - ../scripts:/build/scripts
+      - ../output:/build/output
+      - build-cache:/build/cache
+      - source-cache:/build/source
+      - kernel-cache:/build/kernel
+      - ../configs/zinit:/mnt/zinit:ro
+
+  # Test build with minimal caching (for testing clean builds)
+  test:
+    extends: builder
+    container_name: zero-os-alpine-test
+    volumes:
+      - ../configs:/build/configs:ro
+      - ../scripts:/build/scripts:ro
+      - ../output:/build/output
+      - ../configs/zinit:/mnt/zinit:ro
+    environment:
+      - BUILDMODE=debug
+      - TARGETARCH=amd64
+      - MINIMAL_MODE=${MINIMAL_MODE:-false}
+
+  # Cache management service
+  cache-info:
+    extends: builder
+    container_name: zero-os-alpine-cache-info
+    command: |
+      sh -c "
+        echo 'Build Cache Information:'
+        echo 'Cache directory: /build/cache'
+        ls -la /build/cache/ 2>/dev/null || echo 'No cache markers found'
+        echo ''
+        echo 'Source cache: /build/source'
+        ls -la /build/source/ 2>/dev/null || echo 'No source cache found'
+        echo ''
+        echo 'Kernel cache: /build/kernel'
+        ls -la /build/kernel/ 2>/dev/null || echo 'No kernel cache found'
+        echo ''
+        echo 'Cache sizes:'
+        du -sh /build/cache /build/source /build/kernel 2>/dev/null || true
+      "
+
+volumes:
+  # New cached volumes
+  build-cache:
+  source-cache:
+  kernel-cache:
+  
+  # Legacy volumes (for fallback)
+  github-cache:
+  kernel-cache-legacy:
--- a/configs/init
+++ b/configs/init
@@ -0,0 +1,103 @@
+#!/bin/sh
+# Alpine-based Zero-OS Init Script
+# Maintains identical flow to original busybox version
+
+echo ""
+echo "============================================"
+echo "==       ZERO-OS ALPINE INITRAMFS        =="
+echo "============================================"
+
+echo "[+] creating ram filesystem"
+mount -t proc proc /proc
+mount -t sysfs sysfs /sys
+mount -t tmpfs tmpfs /mnt/root -o size=1536M
+mount -t devtmpfs devtmpfs /dev
+
+echo "[+] building ram filesystem"
+target="/mnt/root"
+
+# Copy Alpine filesystem to tmpfs (same as original)
+echo "  copying /bin..."
+cp -ar /bin $target
+echo "  copying /etc..."
+cp -ar /etc $target
+echo "  copying /lib..."
+cp -ar /lib* $target
+echo "  copying /usr..."
+cp -ar /usr $target
+echo "  copying /root..."
+cp -ar /root $target
+echo "  copying /sbin..."
+cp -ar /sbin $target
+echo "  copying /tmp..."
+cp -ar /tmp $target
+echo "  copying /var..."
+cp -ar /var $target
+echo "  copying /run..."
+cp -ar /run $target
+
+# Create essential directories
+mkdir -p $target/dev
+mkdir -p $target/sys
+mkdir -p $target/proc
+mkdir -p $target/mnt
+
+# Mount filesystems in tmpfs
+mount -t proc proc $target/proc
+mount -t sysfs sysfs $target/sys
+mount -t devtmpfs devtmpfs $target/dev
+
+# Mount devpts for terminals
+mkdir -p $target/dev/pts
+mount -t devpts devpts $target/dev/pts
+
+echo "[+] setting environment"
+export PATH
+
+echo "[+] probing drivers"
+# Use Alpine's udev instead of busybox udevadm
+if [ -x /sbin/udevd ]; then
+    echo "  starting udevd..."
+    udevd --daemon
+    
+    echo "  triggering device discovery..."
+    udevadm trigger --action=add --type=subsystems
+    udevadm trigger --action=add --type=devices
+    udevadm settle
+    
+    echo "  stopping udevd..."
+    kill $(pidof udevd) || true
+else
+    echo "  warning: udevd not found, skipping hardware detection"
+fi
+
+echo "[+] loading essential drivers"
+# Load core drivers for storage and network
+modprobe btrfs 2>/dev/null || true
+modprobe fuse 2>/dev/null || true
+modprobe overlay 2>/dev/null || true
+
+# Load storage drivers
+modprobe ahci 2>/dev/null || true
+modprobe nvme 2>/dev/null || true
+modprobe virtio_blk 2>/dev/null || true
+modprobe virtio_scsi 2>/dev/null || true
+
+# Load network drivers  
+modprobe virtio_net 2>/dev/null || true
+modprobe e1000 2>/dev/null || true
+modprobe e1000e 2>/dev/null || true
+
+# Unmount init filesystems
+umount /proc 2>/dev/null || true
+umount /sys 2>/dev/null || true
+
+echo "[+] checking for debug files"
+if [ -e /init-debug ]; then
+    echo "  executing debug script..."
+    sh /init-debug
+fi
+
+echo "[+] switching root"
+echo "  exec switch_root /mnt/root /sbin/zinit init"
+exec switch_root /mnt/root /sbin/zinit init
--- a/configs/kernel-config-generic
+++ b/configs/kernel-config-generic
--- a/configs/kernel-version
+++ b/configs/kernel-version
@@ -0,0 +1 @@
+6.12.41
--- a/configs/packages-alpine.txt
+++ b/configs/packages-alpine.txt
@@ -0,0 +1,86 @@
+# ALPINE RUNTIME PACKAGES FOR ZERO-OS
+# Standard Alpine Linux + Zero-OS runtime dependencies
+# Purpose: Complete Alpine system with Zero-OS binaries (mountable)
+
+# Core Alpine system (standard installation)
+alpine-baselayout
+busybox
+busybox-suid
+musl
+apk-tools
+
+# System utilities (standard Alpine)
+util-linux
+findutils
+grep
+sed
+coreutils
+
+# Crypto and certificates
+openssl
+ca-certificates
+
+# Filesystem tools
+e2fsprogs
+btrfs-progs
+xfsprogs
+parted
+dosfstools
+
+# Network tools (for Zero-OS operation)
+iproute2
+openssh
+openssh-server
+curl
+wget
+dhcpcd
+dnsmasq
+nftables
+iptables
+netcat-openbsd
+ethtool
+wireguard-tools
+
+# Storage and hardware
+smartmontools
+dmidecode
+hdparm
+nvme-cli
+
+# Compression and archives
+zlib
+zstd
+xz
+gzip
+tar
+
+# System services
+redis
+haveged
+
+# Filesystem support
+fuse
+fuse3
+
+# Hardware detection and drivers
+eudev
+kmod
+pciutils
+usbutils
+
+# Container and virtualization support
+# runc (if available in Alpine)
+
+# Essential libraries for Zero-OS binaries
+libaio
+keyutils
+
+# Text processing (for Zero-OS operation)
+jq
+
+# Runtime dependencies for Zero-OS components
+# (will be determined based on compiled binaries)
+
+# NO development tools (gcc, make, go, rust, etc.)
+# NO debugging tools (gdb, strace, etc.) 
+# Those stay in build environment only
--- a/configs/packages-boot.txt
+++ b/configs/packages-boot.txt
@@ -0,0 +1,27 @@
+# MINIMAL BOOT PACKAGES FOR EMBEDDED INITRAMFS
+# Target: ~10-20MB embedded in kernel
+# Purpose: Boot, establish network, mount runtime Alpine system
+
+# Absolute minimum Alpine base
+alpine-baselayout
+busybox
+musl
+
+# Hardware detection and drivers
+eudev
+kmod
+
+# Network connectivity (essential for mounting runtime system)
+iproute2
+dhcpcd
+ethtool
+
+# Mount utilities for runtime system
+util-linux
+
+# Essential libraries only
+zlib
+
+# NO debugging, NO development tools, NO SSH server
+# NO extra packages - keep this list minimal!
+# Runtime tools will be available in mounted Alpine system
--- a/configs/packages-minimal.txt
+++ b/configs/packages-minimal.txt
@@ -0,0 +1,29 @@
+# MINIMAL Alpine packages for Zero-OS embedded initramfs
+# Target: ~50MB total (not 700MB!)
+
+# Core system (essential only)
+alpine-baselayout
+busybox
+musl
+
+# Module loading & hardware detection
+eudev
+kmod
+
+# Essential networking (for Zero-OS connectivity)
+iproute2
+ethtool
+
+# Filesystem support (minimal)
+btrfs-progs
+dosfstools
+
+# Essential libraries only
+zlib
+
+# Network utilities (minimal)
+dhcpcd
+
+# NO debugging tools, NO development tools, NO SSH, NO curl/wget
+# NO python, NO redis, NO massive linux-firmware package
+# These will be loaded from RFS after network connectivity
--- a/configs/packages.txt
+++ b/configs/packages.txt
@@ -0,0 +1,92 @@
+# Core Alpine packages for Zero-OS initramfs
+# Based on package mapping from current build-from-source system
+
+# Base system
+alpine-baselayout
+busybox
+busybox-suid
+musl
+apk-tools
+
+# System utilities
+util-linux
+findutils
+grep
+sed
+
+# Crypto and certificates
+openssl
+ca-certificates
+
+# Filesystem tools
+e2fsprogs
+btrfs-progs
+xfsprogs
+parted
+dosfstools
+
+# Network tools
+iproute2
+openssh
+openssh-server
+curl
+wget
+dhcpcd
+dnsmasq
+nftables
+iptables
+netcat-openbsd
+ethtool
+wireguard-tools
+
+# Storage and hardware
+smartmontools
+dmidecode
+hdparm
+nvme-cli
+
+# Compression and archives
+zlib
+zstd
+xz
+gzip
+tar
+
+# Development and system
+redis
+haveged
+tcpdump
+strace
+
+# Filesystem support
+fuse
+fuse3
+
+# Virtualization filesystem support (for local development)
+# VirtioFS userspace tools
+virtiofsd
+
+# Hardware detection and drivers
+eudev
+kmod
+pciutils
+usbutils
+
+# Linux firmware
+linux-firmware
+
+# Container and virtualization
+# runc (may be in testing, skip for now)
+
+# Additional libraries
+libaio
+keyutils
+
+# Debugging tools (for debug builds)
+gdb
+strace
+lsof
+htop
+
+# Text processing
+jq
--- a/configs/zinit/zinit.yaml
+++ b/configs/zinit/zinit.yaml
@@ -0,0 +1,30 @@
+# Zero-OS Zinit Configuration
+exec:
+  # Core Zero-OS Services
+  rfs:
+    exec: /usr/bin/rfs
+    after:
+      - mycelium
+  
+  seektime:
+    exec: /usr/bin/seektime
+    
+  core-x:
+    exec: /usr/bin/core-x
+    after:
+      - rfs
+      - mycelium
+      
+  mycelium:
+    exec: /usr/bin/mycelium
+    
+  # System Services
+  sshd:
+    exec: /usr/sbin/sshd -D
+    after:
+      - mycelium
+      
+  # Network configuration
+  networking:
+    exec: /bin/sh -c "ip link set lo up"
+    oneshot: true
--- a/docs/BUILD.md
+++ b/docs/BUILD.md
@@ -0,0 +1,423 @@
+# Alpine Zero-OS Build Process
+
+Complete build system documentation for the Alpine-based Zero-OS initramfs.
+
+## Build Environment - Dockerfile.alpine
+
+```dockerfile
+# Alpine-based Zero-OS Initramfs Builder
+FROM alpine:3.22
+
+# Set build arguments
+ARG TARGETARCH=amd64
+ARG BUILDMODE=debug
+
+# Set environment variables
+ENV BUILDMODE=${BUILDMODE}
+ENV TARGETARCH=${TARGETARCH}
+
+# Install build dependencies
+RUN apk add --no-cache \
+    # Build tools
+    build-base \
+    linux-headers \
+    cmake \
+    git \
+    wget \
+    curl \
+    cpio \
+    xz \
+    gzip \
+    bc \
+    perl \
+    python3 \
+    # Kernel build dependencies
+    linux-lts-dev \
+    linux-lts \
+    elfutils-dev \
+    openssl-dev \
+    # Archive tools
+    tar \
+    bzip2 \
+    # Text processing
+    sed \
+    grep \
+    findutils
+
+# Create directories
+RUN mkdir -p /build/initramfs /build/kernel /build/output /build/github
+
+# Set working directory
+WORKDIR /build
+
+# Copy build scripts
+COPY scripts/ /build/scripts/
+COPY configs/ /build/configs/
+
+# Make scripts executable
+RUN chmod +x /build/scripts/*.sh
+
+# Default command
+CMD ["/build/scripts/build-initramfs.sh"]
+```
+
+## Docker Compose Configuration
+
+```yaml
+services:
+  builder:
+    build:
+      context: ..
+      dockerfile: build/Dockerfile.alpine
+      args:
+        BUILDMODE: "${BUILDMODE:-debug}"
+        TARGETARCH: "${TARGETARCH:-amd64}"
+    image: zero-os-alpine-builder:latest
+    container_name: zero-os-alpine-builder
+    privileged: true
+    volumes:
+      # Mount source configs and scripts
+      - ../configs:/build/configs:ro
+      - ../scripts:/build/scripts:ro
+      # Mount output directory
+      - ../output:/build/output
+      # Cache directories for faster builds
+      - github-cache:/build/github
+      - kernel-cache:/build/kernel
+    environment:
+      - BUILDMODE=${BUILDMODE:-debug}
+      - TARGETARCH=${TARGETARCH:-amd64}
+    working_dir: /build
+
+  # Quick shell access for debugging
+  shell:
+    extends: builder
+    command: /bin/sh
+    stdin_open: true
+    tty: true
+
+volumes:
+  github-cache:
+  kernel-cache:
+```
+
+## Build Scripts
+
+### Main Build Script - build-initramfs.sh
+
+```bash
+#!/bin/sh
+set -e
+
+echo "====================================="
+echo "=   Alpine Zero-OS Initramfs Build  ="
+echo "====================================="
+echo ""
+
+# Source configuration
+. /build/configs/build.conf
+
+echo "[+] Build mode: $BUILDMODE"
+echo "[+] Target arch: $TARGETARCH"
+echo ""
+
+# Phase 1: Install Alpine packages to initramfs
+echo "[+] Installing Alpine packages..."
+/build/scripts/install-packages.sh
+
+# Phase 2: Fetch GitHub components
+echo "[+] Fetching GitHub components..."
+/build/scripts/fetch-github.sh
+
+# Phase 3: Setup initramfs structure
+echo "[+] Setting up initramfs structure..."
+/build/scripts/setup-initramfs.sh
+
+# Phase 4: Build kernel with embedded initramfs
+echo "[+] Building kernel..."
+/build/scripts/build-kernel.sh
+
+echo ""
+echo "[+] Build completed successfully!"
+echo "[+] Output: /build/output/vmlinuz.efi"
+```
+
+### Package Installation Script - install-packages.sh
+
+```bash
+#!/bin/sh
+set -e
+
+INITRAMFS_ROOT="/build/initramfs"
+PACKAGES_FILE="/build/configs/packages.txt"
+
+echo "[+] Creating initramfs root directory..."
+mkdir -p "$INITRAMFS_ROOT"
+
+echo "[+] Installing Alpine base system..."
+apk add --root "$INITRAMFS_ROOT" --update-cache --initdb alpine-base
+
+echo "[+] Installing Zero-OS packages..."
+while read -r package; do
+    # Skip comments and empty lines
+    case "$package" in
+        \#*|"") continue ;;
+    esac
+    
+    echo "  Installing: $package"
+    apk add --root "$INITRAMFS_ROOT" --no-cache "$package"
+done < "$PACKAGES_FILE"
+
+echo "[+] Setting up initramfs filesystem structure..."
+# Create essential directories
+mkdir -p "$INITRAMFS_ROOT"/{dev,proc,sys,mnt,tmp,var/run,var/log}
+
+# Create device nodes (minimal set)
+mknod "$INITRAMFS_ROOT/dev/console" c 5 1
+mknod "$INITRAMFS_ROOT/dev/null" c 1 3
+mknod "$INITRAMFS_ROOT/dev/zero" c 1 5
+
+# Set proper permissions
+chmod 666 "$INITRAMFS_ROOT/dev/null" "$INITRAMFS_ROOT/dev/zero"
+chmod 600 "$INITRAMFS_ROOT/dev/console"
+
+echo "[+] Alpine packages installed successfully"
+```
+
+### GitHub Components Fetcher - fetch-github.sh
+
+```bash
+#!/bin/sh
+set -e
+
+GITHUB_DIR="/build/github"
+INITRAMFS_ROOT="/build/initramfs"
+
+echo "[+] Fetching GitHub components..."
+
+# Create cache directory
+mkdir -p "$GITHUB_DIR"
+
+# Function to download latest release
+download_github_release() {
+    local repo="$1"
+    local binary="$2"
+    local install_path="$3"
+    
+    echo "  Fetching: $repo"
+    
+    # Get latest release URL
+    local api_url="https://api.github.com/repos/$repo/releases/latest"
+    local download_url=$(wget -qO- "$api_url" | grep "browser_download_url.*linux.*amd64" | cut -d '"' -f 4 | head -1)
+    
+    if [ -z "$download_url" ]; then
+        echo "    Warning: No linux amd64 release found for $repo"
+        return 1
+    fi
+    
+    # Download and install
+    local filename=$(basename "$download_url")
+    wget -O "$GITHUB_DIR/$filename" "$download_url"
+    
+    # Extract if needed and install
+    case "$filename" in
+        *.tar.gz|*.tgz)
+            tar -xzf "$GITHUB_DIR/$filename" -C "$GITHUB_DIR"
+            cp "$GITHUB_DIR/$binary" "$INITRAMFS_ROOT$install_path"
+            ;;
+        *.zip)
+            unzip -q "$GITHUB_DIR/$filename" -d "$GITHUB_DIR"
+            cp "$GITHUB_DIR/$binary" "$INITRAMFS_ROOT$install_path"
+            ;;
+        *)
+            # Assume it's a binary
+            cp "$GITHUB_DIR/$filename" "$INITRAMFS_ROOT$install_path/$binary"
+            ;;
+    esac
+    
+    chmod +x "$INITRAMFS_ROOT$install_path/$binary"
+    echo "    Installed: $install_path/$binary"
+}
+
+# Fetch required components
+download_github_release "threefoldtech/zinit" "zinit" "/sbin"
+download_github_release "threefoldtech/core-x" "core-x" "/usr/bin"
+download_github_release "threefoldtech/seektime" "seektime" "/usr/bin"
+download_github_release "threefoldtech/rfs" "rfs" "/usr/bin"
+
+echo "[+] GitHub components fetched successfully"
+```
+
+### Initramfs Setup Script - setup-initramfs.sh
+
+```bash
+#!/bin/sh
+set -e
+
+INITRAMFS_ROOT="/build/initramfs"
+CONFIG_DIR="/build/configs"
+
+echo "[+] Setting up initramfs structure..."
+
+# Copy init script
+echo "  Installing init script..."
+cp "$CONFIG_DIR/init" "$INITRAMFS_ROOT/init"
+chmod +x "$INITRAMFS_ROOT/init"
+
+# Copy zinit configuration
+echo "  Installing zinit configuration..."
+mkdir -p "$INITRAMFS_ROOT/etc/zinit"
+cp -r "$CONFIG_DIR/zinit/"* "$INITRAMFS_ROOT/etc/zinit/"
+
+# Copy other configurations
+echo "  Installing system configuration..."
+# Copy any additional configs needed
+
+# Set up symlinks (similar to current system)
+cd "$INITRAMFS_ROOT"
+ln -sf usr/lib lib || true
+ln -sf usr/lib lib64 || true
+
+# Create initramfs archive
+echo "[+] Creating initramfs archive..."
+cd "$INITRAMFS_ROOT"
+find . | cpio -H newc -o | xz --check=crc32 --x86 --lzma2=dict=1MiB > /build/output/initramfs.cpio.xz
+
+echo "[+] Initramfs created: /build/output/initramfs.cpio.xz"
+```
+
+### Kernel Build Script - build-kernel.sh
+
+```bash
+#!/bin/sh
+set -e
+
+KERNEL_DIR="/build/kernel"
+OUTPUT_DIR="/build/output"
+CONFIG_DIR="/build/configs"
+
+echo "[+] Building kernel with embedded initramfs..."
+
+# Setup kernel source
+echo "  Preparing kernel source..."
+mkdir -p "$KERNEL_DIR"
+cd "$KERNEL_DIR"
+
+# Use Alpine's kernel source
+cp -r /usr/src/linux-* ./linux || {
+    echo "  Downloading kernel source..."
+    # Fallback: download kernel source if not available
+    KERNEL_VERSION=$(uname -r | sed 's/-.*$//')
+    wget -O- "https://cdn.kernel.org/pub/linux/kernel/v6.x/linux-${KERNEL_VERSION}.tar.xz" | tar -xJ
+    mv "linux-${KERNEL_VERSION}" linux
+}
+
+cd linux
+
+# Copy kernel configuration
+echo "  Configuring kernel..."
+cp "$CONFIG_DIR/kernel-config" .config
+
+# Set initramfs path
+echo "  Setting initramfs path..."
+sed -i "s|^CONFIG_INITRAMFS_SOURCE=.*|CONFIG_INITRAMFS_SOURCE=\"$OUTPUT_DIR/initramfs.cpio.xz\"|" .config
+
+# Build kernel
+echo "  Compiling kernel..."
+make -j$(nproc) bzImage
+
+# Copy output
+echo "  Installing kernel..."
+cp arch/x86/boot/bzImage "$OUTPUT_DIR/vmlinuz.efi"
+
+echo "[+] Kernel build completed: $OUTPUT_DIR/vmlinuz.efi"
+```
+
+## Configuration Files
+
+### packages.txt
+```
+# Core Alpine packages for Zero-OS initramfs
+busybox
+busybox-suid
+alpine-base
+openssl
+ca-certificates
+util-linux
+util-linux-misc
+e2fsprogs
+btrfs-progs
+parted
+dnsmasq
+nftables
+iproute2
+openssh
+curl
+restic
+wireguard-tools
+zlib
+fuse
+unionfs-fuse
+smartmontools
+dmidecode
+netcat-openbsd
+redis
+haveged
+ethtool
+dhcpcd
+tcpdump
+xfsprogs
+bcache-tools
+keyutils
+zstd
+libaio
+eudev
+kmod
+linux-firmware
+```
+
+### build.conf
+```bash
+# Build configuration
+BUILDMODE="${BUILDMODE:-debug}"
+TARGETARCH="${TARGETARCH:-amd64}"
+
+# GitHub repositories
+ZINIT_REPO="threefoldtech/zinit"
+COREX_REPO="threefoldtech/core-x"
+SEEKTIME_REPO="threefoldtech/seektime"
+RFS_REPO="threefoldtech/rfs"
+
+# Paths
+INITRAMFS_ROOT="/build/initramfs"
+KERNEL_DIR="/build/kernel"
+OUTPUT_DIR="/build/output"
+CONFIG_DIR="/build/configs"
+```
+
+## Usage
+
+```bash
+# Build with defaults (debug mode)
+cd alpine-initramfs/build
+docker compose build
+docker compose run --rm builder
+
+# Build release version
+BUILDMODE=release docker compose run --rm builder
+
+# Interactive shell for debugging
+docker compose run --rm shell
+
+# Output
+ls ../output/
+# vmlinuz.efi - bootable kernel with embedded initramfs
+# initramfs.cpio.xz - standalone initramfs archive
+```
+
+This build system provides:
+- ✅ **Fast builds** (~5 minutes vs 60+ minutes)
+- ✅ **Latest packages** from Alpine repositories
+- ✅ **Minimal complexity** - only 4 GitHub components to fetch
+- ✅ **Same functionality** - identical init flow and services
+- ✅ **Better maintenance** - Alpine handles package updates
--- a/docs/GITHUB.md
+++ b/docs/GITHUB.md
@@ -0,0 +1,411 @@
+# GitHub Components Integration
+
+Documentation for fetching and integrating the four custom components from GitHub repositories.
+
+## Required GitHub Components
+
+| Component | Repository | Purpose | Install Path |
+|-----------|------------|---------|--------------|
+| zinit | `threefoldtech/zinit` | Init system (PID 1) | `/sbin/zinit` |
+| core-x | `threefoldtech/core-x` | Container remote control | `/usr/bin/core-x` |
+| seektime | `threefoldtech/seektime` | Disk type detection | `/usr/bin/seektime` |
+| rfs | `threefoldtech/rfs` | Rust version of 0-fs | `/usr/bin/rfs` |
+
+## GitHub Release Fetcher Script
+
+### scripts/fetch-github.sh
+
+```bash
+#!/bin/sh
+set -e
+
+GITHUB_DIR="/build/github"
+INITRAMFS_ROOT="/build/initramfs"
+CACHE_TIMEOUT=3600  # 1 hour cache
+
+echo "[+] Fetching GitHub components..."
+
+# Create cache directory
+mkdir -p "$GITHUB_DIR"
+
+# Function to get latest release info
+get_latest_release() {
+    local repo="$1"
+    local cache_file="$GITHUB_DIR/${repo//\//_}_release.json"
+    
+    # Check cache first
+    if [ -f "$cache_file" ] && [ $(($(date +%s) - $(stat -c %Y "$cache_file"))) -lt $CACHE_TIMEOUT ]; then
+        cat "$cache_file"
+        return
+    fi
+    
+    # Fetch latest release info
+    local api_url="https://api.github.com/repos/$repo/releases/latest"
+    echo "    Fetching release info for $repo..." >&2
+    
+    if command -v curl >/dev/null; then
+        curl -s "$api_url" | tee "$cache_file"
+    else
+        wget -qO- "$api_url" | tee "$cache_file"
+    fi
+}
+
+# Function to extract download URL from release JSON
+get_download_url() {
+    local release_json="$1"
+    local pattern="$2"
+    
+    echo "$release_json" | grep -o '"browser_download_url": *"[^"]*"' | \
+        grep "$pattern" | head -1 | cut -d '"' -f 4
+}
+
+# Function to download and install binary
+install_github_binary() {
+    local repo="$1"
+    local binary_name="$2"
+    local install_path="$3"
+    local download_pattern="$4"
+    
+    echo "  Installing: $repo -> $install_path/$binary_name"
+    
+    # Get release information
+    local release_json=$(get_latest_release "$repo")
+    if [ -z "$release_json" ]; then
+        echo "    Error: Failed to get release info for $repo" >&2
+        return 1
+    fi
+    
+    # Extract version for logging
+    local version=$(echo "$release_json" | grep '"tag_name"' | cut -d '"' -f 4)
+    echo "    Version: $version"
+    
+    # Get download URL
+    local download_url=$(get_download_url "$release_json" "$download_pattern")
+    if [ -z "$download_url" ]; then
+        echo "    Error: No matching release found for pattern: $download_pattern" >&2
+        return 1
+    fi
+    
+    echo "    Downloading: $(basename "$download_url")"
+    local filename=$(basename "$download_url")
+    local download_path="$GITHUB_DIR/$filename"
+    
+    # Download if not cached
+    if [ ! -f "$download_path" ]; then
+        if command -v curl >/dev/null; then
+            curl -L -o "$download_path" "$download_url"
+        else
+            wget -O "$download_path" "$download_url"
+        fi
+    else
+        echo "    Using cached file"
+    fi
+    
+    # Create install directory
+    mkdir -p "$INITRAMFS_ROOT$install_path"
+    
+    # Extract and install based on file type
+    case "$filename" in
+        *.tar.gz|*.tgz)
+            echo "    Extracting tar.gz..."
+            tar -xzf "$download_path" -C "$GITHUB_DIR"
+            # Find the binary in extracted files
+            local extracted_binary=$(find "$GITHUB_DIR" -name "$binary_name" -type f | head -1)
+            if [ -n "$extracted_binary" ]; then
+                cp "$extracted_binary" "$INITRAMFS_ROOT$install_path/$binary_name"
+            else
+                echo "    Error: Binary '$binary_name' not found in archive" >&2
+                return 1
+            fi
+            ;;
+        *.zip)
+            echo "    Extracting zip..."
+            unzip -q "$download_path" -d "$GITHUB_DIR"
+            local extracted_binary=$(find "$GITHUB_DIR" -name "$binary_name" -type f | head -1)
+            if [ -n "$extracted_binary" ]; then
+                cp "$extracted_binary" "$INITRAMFS_ROOT$install_path/$binary_name"
+            else
+                echo "    Error: Binary '$binary_name' not found in archive" >&2
+                return 1
+            fi
+            ;;
+        *)
+            # Assume it's a direct binary
+            echo "    Installing direct binary..."
+            cp "$download_path" "$INITRAMFS_ROOT$install_path/$binary_name"
+            ;;
+    esac
+    
+    # Make executable
+    chmod +x "$INITRAMFS_ROOT$install_path/$binary_name"
+    
+    # Verify installation
+    if [ -x "$INITRAMFS_ROOT$install_path/$binary_name" ]; then
+        echo "    Success: $install_path/$binary_name installed"
+    else
+        echo "    Error: Failed to install $binary_name" >&2
+        return 1
+    fi
+}
+
+# Install each component
+echo ""
+
+# Zinit - Init system
+install_github_binary "threefoldtech/zinit" "zinit" "/sbin" "linux.*amd64"
+
+# Core-X - Container control
+install_github_binary "threefoldtech/core-x" "core-x" "/usr/bin" "linux.*amd64"
+
+# Seektime - Disk detection
+install_github_binary "threefoldtech/seektime" "seektime" "/usr/bin" "linux.*amd64"
+
+# RFS - Rust filesystem
+install_github_binary "threefoldtech/rfs" "rfs" "/usr/bin" "linux.*amd64"
+
+echo ""
+echo "[+] GitHub components installed successfully"
+
+# Optional: Show installed binaries info
+echo ""
+echo "[+] Installed components:"
+for binary in "/sbin/zinit" "/usr/bin/core-x" "/usr/bin/seektime" "/usr/bin/rfs"; do
+    if [ -x "$INITRAMFS_ROOT$binary" ]; then
+        size=$(stat -c%s "$INITRAMFS_ROOT$binary" 2>/dev/null || echo "unknown")
+        echo "  $binary (${size} bytes)"
+    else
+        echo "  $binary (MISSING)"
+    fi
+done
+```
+
+## Alternative: Pinned Versions
+
+For production builds, you may want to pin specific versions:
+
+### scripts/fetch-github-pinned.sh
+
+```bash
+#!/bin/sh
+set -e
+
+GITHUB_DIR="/build/github"
+INITRAMFS_ROOT="/build/initramfs"
+
+# Pinned versions for reproducible builds
+ZINIT_VERSION="v0.2.11"
+COREX_VERSION="v2.1.0"
+SEEKTIME_VERSION="v0.1"
+RFS_VERSION="v1.1.1"
+
+echo "[+] Fetching pinned GitHub components..."
+
+# Function to download specific version
+download_pinned_release() {
+    local repo="$1"
+    local version="$2"
+    local binary_name="$3"
+    local install_path="$4"
+    local asset_pattern="$5"
+    
+    echo "  Installing: $repo@$version"
+    
+    # Construct release URL
+    local release_url="https://api.github.com/repos/$repo/releases/tags/$version"
+    
+    # Get release info
+    local release_json
+    if command -v curl >/dev/null; then
+        release_json=$(curl -s "$release_url")
+    else
+        release_json=$(wget -qO- "$release_url")
+    fi
+    
+    # Extract download URL
+    local download_url=$(echo "$release_json" | grep -o '"browser_download_url": *"[^"]*"' | \
+        grep "$asset_pattern" | head -1 | cut -d '"' -f 4)
+    
+    if [ -z "$download_url" ]; then
+        echo "    Error: No asset matching '$asset_pattern' found" >&2
+        return 1
+    fi
+    
+    # Download and install
+    local filename=$(basename "$download_url")
+    local download_path="$GITHUB_DIR/$filename"
+    
+    echo "    Downloading: $filename"
+    if command -v curl >/dev/null; then
+        curl -L -o "$download_path" "$download_url"
+    else
+        wget -O "$download_path" "$download_url"
+    fi
+    
+    # Install based on file type
+    mkdir -p "$INITRAMFS_ROOT$install_path"
+    
+    case "$filename" in
+        *.tar.gz|*.tgz)
+            tar -xzf "$download_path" -C "$GITHUB_DIR"
+            cp "$GITHUB_DIR/$binary_name" "$INITRAMFS_ROOT$install_path/$binary_name"
+            ;;
+        *)
+            cp "$download_path" "$INITRAMFS_ROOT$install_path/$binary_name"
+            ;;
+    esac
+    
+    chmod +x "$INITRAMFS_ROOT$install_path/$binary_name"
+    echo "    Success: $install_path/$binary_name"
+}
+
+# Install pinned versions
+download_pinned_release "threefoldtech/zinit" "$ZINIT_VERSION" "zinit" "/sbin" "linux.*amd64"
+download_pinned_release "threefoldtech/core-x" "$COREX_VERSION" "core-x" "/usr/bin" "linux.*amd64"
+download_pinned_release "threefoldtech/seektime" "$SEEKTIME_VERSION" "seektime" "/usr/bin" "linux.*amd64"
+download_pinned_release "threefoldtech/rfs" "$RFS_VERSION" "rfs" "/usr/bin" "linux.*amd64"
+
+echo "[+] Pinned GitHub components installed"
+```
+
+## Build Integration
+
+### Integration with main build script:
+
+```bash
+# In build-initramfs.sh
+echo "[+] Installing Alpine packages..."
+/build/scripts/install-packages.sh
+
+echo "[+] Fetching GitHub components..."
+if [ "$BUILDMODE" = "production" ]; then
+    # Use pinned versions for production
+    /build/scripts/fetch-github-pinned.sh
+else
+    # Use latest versions for development
+    /build/scripts/fetch-github.sh
+fi
+
+echo "[+] Setting up initramfs structure..."
+/build/scripts/setup-initramfs.sh
+```
+
+## Caching Strategy
+
+### Docker Volume Caching:
+```yaml
+# In docker-compose.yml
+volumes:
+  github-cache:
+    driver: local
+    driver_opts:
+      type: none
+      o: bind
+      device: ./cache/github
+
+services:
+  builder:
+    volumes:
+      - github-cache:/build/github
+```
+
+### Local Caching:
+```bash
+# Cache structure
+alpine-initramfs/cache/
+├── github/
+│   ├── zinit-v0.2.11-linux-amd64.tar.gz
+│   ├── core-x-v2.1.0-linux-amd64.tar.gz
+│   ├── seektime-v0.1-linux-amd64.tar.gz
+│   ├── rfs-v1.1.1-linux-amd64.tar.gz
+│   └── *.json (release info cache)
+```
+
+## Error Handling
+
+### Robust Download with Retries:
+```bash
+# Enhanced download function with retries
+download_with_retry() {
+    local url="$1"
+    local output="$2"
+    local max_attempts=3
+    local attempt=1
+    
+    while [ $attempt -le $max_attempts ]; do
+        echo "    Attempt $attempt/$max_attempts..."
+        
+        if command -v curl >/dev/null; then
+            if curl -L --fail -o "$output" "$url"; then
+                return 0
+            fi
+        else
+            if wget -O "$output" "$url"; then
+                return 0
+            fi
+        fi
+        
+        attempt=$((attempt + 1))
+        if [ $attempt -le $max_attempts ]; then
+            echo "    Retrying in 5 seconds..."
+            sleep 5
+        fi
+    done
+    
+    echo "    Error: Failed to download after $max_attempts attempts" >&2
+    return 1
+}
+```
+
+## Verification
+
+### Component Verification:
+```bash
+# Verify all components are installed and working
+verify_components() {
+    local errors=0
+    
+    echo "[+] Verifying GitHub components..."
+    
+    # Check zinit
+    if [ -x "$INITRAMFS_ROOT/sbin/zinit" ]; then
+        echo "  ✓ zinit installed"
+    else
+        echo "  ✗ zinit missing"
+        errors=$((errors + 1))
+    fi
+    
+    # Check core-x
+    if [ -x "$INITRAMFS_ROOT/usr/bin/core-x" ]; then
+        echo "  ✓ core-x installed"
+    else
+        echo "  ✗ core-x missing"
+        errors=$((errors + 1))
+    fi
+    
+    # Check seektime
+    if [ -x "$INITRAMFS_ROOT/usr/bin/seektime" ]; then
+        echo "  ✓ seektime installed"
+    else
+        echo "  ✗ seektime missing"
+        errors=$((errors + 1))
+    fi
+    
+    # Check rfs
+    if [ -x "$INITRAMFS_ROOT/usr/bin/rfs" ]; then
+        echo "  ✓ rfs installed"
+    else
+        echo "  ✗ rfs missing"
+        errors=$((errors + 1))
+    fi
+    
+    if [ $errors -eq 0 ]; then
+        echo "  All components verified successfully"
+        return 0
+    else
+        echo "  $errors components missing"
+        return 1
+    fi
+}
+```
+
+This system ensures reliable fetching and integration of the four custom GitHub components while maintaining caching and error resilience.
--- a/docs/INIT.md
+++ b/docs/INIT.md
@@ -0,0 +1,299 @@
+# Alpine Zero-OS Init Script Design
+
+Design documentation for the Alpine-based init script that maintains the exact same tmpfs approach as the current system.
+
+## Current Init Flow Analysis
+
+The existing init script (`config/init/init`) does:
+1. Mount basic filesystems (proc, sysfs, devtmpfs)
+2. Create 1536M tmpfs at `/mnt/root`
+3. Copy entire filesystem to tmpfs
+4. Mount filesystems in tmpfs
+5. Hardware detection with udev
+6. Load essential drivers
+7. Debug file injection (if available)
+8. `switch_root` to tmpfs and exec zinit
+
+## Alpine Init Script - configs/init
+
+```bash
+#!/bin/sh
+# Alpine-based Zero-OS Init Script
+# Maintains identical flow to original busybox version
+
+echo ""
+echo "============================================"
+echo "==       ZERO-OS ALPINE INITRAMFS        =="
+echo "============================================"
+
+echo "[+] creating ram filesystem"
+mount -t proc proc /proc
+mount -t sysfs sysfs /sys
+mount -t tmpfs tmpfs /mnt/root -o size=1536M
+mount -t devtmpfs devtmpfs /dev
+
+echo "[+] building ram filesystem"
+target="/mnt/root"
+
+# Copy Alpine filesystem to tmpfs (same as original)
+echo "  copying /bin..."
+cp -ar /bin $target
+echo "  copying /etc..."
+cp -ar /etc $target
+echo "  copying /lib..."
+cp -ar /lib* $target
+echo "  copying /usr..."
+cp -ar /usr $target
+echo "  copying /root..."
+cp -ar /root $target
+echo "  copying /sbin..."
+cp -ar /sbin $target
+echo "  copying /tmp..."
+cp -ar /tmp $target
+echo "  copying /var..."
+cp -ar /var $target
+echo "  copying /run..."
+cp -ar /run $target
+
+# Create essential directories
+mkdir -p $target/dev
+mkdir -p $target/sys
+mkdir -p $target/proc
+mkdir -p $target/mnt
+
+# Mount filesystems in tmpfs
+mount -t proc proc $target/proc
+mount -t sysfs sysfs $target/sys
+mount -t devtmpfs devtmpfs $target/dev
+
+# Mount devpts for terminals
+mkdir -p $target/dev/pts
+mount -t devpts devpts $target/dev/pts
+
+echo "[+] setting environment"
+export PATH
+
+echo "[+] probing drivers"
+# Use Alpine's udev instead of busybox udevadm
+if [ -x /sbin/udevd ]; then
+    echo "  starting udevd..."
+    udevd --daemon
+    
+    echo "  triggering device discovery..."
+    udevadm trigger --action=add --type=subsystems
+    udevadm trigger --action=add --type=devices
+    udevadm settle
+    
+    echo "  stopping udevd..."
+    kill $(pidof udevd) || true
+else
+    echo "  warning: udevd not found, skipping hardware detection"
+fi
+
+echo "[+] loading essential drivers"
+# Load core drivers for storage and network
+modprobe btrfs 2>/dev/null || true
+modprobe fuse 2>/dev/null || true
+modprobe overlay 2>/dev/null || true
+
+# Load storage drivers
+modprobe ahci 2>/dev/null || true
+modprobe nvme 2>/dev/null || true
+modprobe virtio_blk 2>/dev/null || true
+modprobe virtio_scsi 2>/dev/null || true
+
+# Load network drivers  
+modprobe virtio_net 2>/dev/null || true
+modprobe e1000 2>/dev/null || true
+modprobe e1000e 2>/dev/null || true
+
+# Unmount init filesystems
+umount /proc 2>/dev/null || true
+umount /sys 2>/dev/null || true
+
+echo "[+] checking for debug files"
+if [ -e /init-debug ]; then
+    echo "  executing debug script..."
+    sh /init-debug
+fi
+
+echo "[+] switching root"
+echo "  exec switch_root /mnt/root /sbin/zinit init"
+exec switch_root /mnt/root /sbin/zinit init
+```
+
+## Debug Script - configs/init-debug
+
+For debug mode compatibility:
+
+```bash
+#!/bin/sh
+# Debug file injection script (Alpine version)
+# Maintains compatibility with existing debug workflow
+
+echo "[+] debug mode enabled"
+
+# Check for debug device (same as original)
+if [ -b /dev/sda1 ]; then
+    echo "  debug device found: /dev/sda1"
+    
+    # Create temporary mount point
+    mkdir -p /mnt/debug
+    
+    # Try to mount as vfat (same as original)
+    if mount -t vfat -o ro /dev/sda1 /mnt/debug 2>/dev/null; then
+        echo "  mounted debug device"
+        
+        # Check for debug marker file
+        if [ -f /mnt/debug/.zero-os-debug ]; then
+            echo "  debug marker found, copying files..."
+            
+            # Copy all files from debug device to tmpfs root
+            target="/mnt/root"
+            if [ -d "$target" ]; then
+                cp -rv /mnt/debug/* "$target/" 2>/dev/null || true
+                echo "  debug files copied to tmpfs"
+            else
+                echo "  warning: tmpfs root not ready yet"
+            fi
+        else
+            echo "  no debug marker (.zero-os-debug) found"
+        fi
+        
+        # Unmount debug device
+        umount /mnt/debug 2>/dev/null || true
+    else
+        echo "  failed to mount debug device"
+    fi
+    
+    # Cleanup
+    rmdir /mnt/debug 2>/dev/null || true
+else
+    echo "  no debug device found"
+fi
+
+echo "[+] debug initialization complete"
+```
+
+## Key Differences from Original
+
+### Advantages of Alpine Version:
+1. **Better error handling**: Uses `|| true` to prevent failures
+2. **More verbose output**: Better logging for debugging
+3. **Alpine tools**: Uses Alpine's optimized udev/modprobe
+4. **Modular approach**: Separates debug script for clarity
+5. **Robust driver loading**: Loads more essential drivers upfront
+
+### Maintained Compatibility:
+1. **Identical filesystem structure**: Same tmpfs copy approach
+2. **Same mount points**: Preserves all original mount points
+3. **Same debug workflow**: Compatible with existing debug injection
+4. **Same zinit execution**: Identical handoff to zinit
+5. **Same memory usage**: 1536M tmpfs size preserved
+
+## Hardware Detection Improvements
+
+### Enhanced Driver Loading:
+```bash
+# Storage drivers (embedded in initramfs)
+modprobe ahci          # SATA controllers
+modprobe nvme          # NVMe SSDs
+modprobe virtio_blk    # Virtual block devices
+modprobe virtio_scsi   # Virtual SCSI
+modprobe usb_storage   # USB storage
+
+# Network drivers (embedded in initramfs)  
+modprobe virtio_net    # Virtual network
+modprobe e1000         # Intel Gigabit
+modprobe e1000e        # Intel Gigabit Enhanced
+modprobe r8169         # Realtek
+modprobe tg3           # Broadcom
+
+# Filesystem drivers
+modprobe btrfs         # Primary filesystem
+modprobe overlay       # Container filesystems
+modprobe fuse          # FUSE filesystems
+```
+
+### Advanced Hardware Detection:
+```bash
+# Optional: More sophisticated hardware detection
+if [ -x /usr/bin/lspci ]; then
+    echo "[+] detecting hardware..."
+    
+    # Load drivers based on detected hardware
+    for device in $(lspci -n | awk '{print $3}'); do
+        case "$device" in
+            "8086:*") # Intel devices
+                modprobe e1000e 2>/dev/null || true
+                ;;
+            "10ec:*") # Realtek devices  
+                modprobe r8169 2>/dev/null || true
+                ;;
+            "14e4:*") # Broadcom devices
+                modprobe tg3 2>/dev/null || true
+                ;;
+        esac
+    done
+fi
+```
+
+## Error Handling and Logging
+
+### Robust Error Handling:
+```bash
+# Function for safe command execution
+safe_exec() {
+    local cmd="$1"
+    local desc="$2"
+    
+    echo "  $desc..."
+    if $cmd; then
+        echo "    success"
+    else
+        echo "    warning: $desc failed (continuing)"
+    fi
+}
+
+# Usage examples:
+safe_exec "modprobe btrfs" "loading btrfs driver"
+safe_exec "udevadm settle" "waiting for device settlement"
+```
+
+### Enhanced Logging:
+```bash
+# Optional: Detailed logging for debug builds
+if [ "$BUILDMODE" = "debug" ]; then
+    # Log to both console and file
+    exec 1> >(tee -a /mnt/root/var/log/init.log)
+    exec 2> >(tee -a /mnt/root/var/log/init.log >&2)
+    
+    echo "[DEBUG] Init script started at $(date)"
+    echo "[DEBUG] Available memory: $(free -m)"
+    echo "[DEBUG] Detected hardware: $(lspci -nn)"
+fi
+```
+
+## Integration with Zinit
+
+### Zinit Configuration Preservation:
+- All existing zinit YAML configs copied unchanged
+- Service dependencies maintained  
+- Init scripts preserved in `/etc/zinit/init/`
+- Same service execution flow
+
+### Zinit Execution Environment:
+```bash
+# Ensure clean environment for zinit
+export PATH="/sbin:/bin:/usr/sbin:/usr/bin"
+export HOME="/root"
+export TERM="linux"
+
+# Clear any init-specific variables
+unset target
+
+# Execute zinit with same arguments
+exec switch_root /mnt/root /sbin/zinit init
+```
+
+This design maintains 100% compatibility with the existing system while leveraging Alpine's more robust and modern tooling.
--- a/docs/MINIMAL-DESIGN.md
+++ b/docs/MINIMAL-DESIGN.md
@@ -0,0 +1,111 @@
+# Minimal Embedded Initramfs Design
+
+## 🎯 **Requirements: Ultra-Minimal Embedded CPIO**
+
+- **Size Target**: 50-100MB (not 700MB!)
+- **Network drivers** + essential firmware only
+- **eudev** for module loading
+- **btrfs** and **vfat** filesystem support
+- **Embedded in kernel** for fastest boot
+
+## 📦 **Minimal Package List**
+
+### Core System (Essential Only)
+```
+alpine-baselayout     # Basic filesystem structure
+busybox              # Essential utilities
+musl                 # C library
+```
+
+### Module Loading & Hardware Detection
+```
+eudev                # Hardware detection and module loading
+kmod                 # Module management
+```
+
+### Filesystem Support (Minimal)
+```
+btrfs-progs          # btrfs filesystem support  
+dosfstools           # vfat filesystem support
+```
+
+### Network Essentials (Minimal)
+```
+# NO full linux-firmware (600MB!)
+# Only essential network drivers via selective firmware
+```
+
+## 🗂️ **Firmware Strategy: Selective Loading**
+
+Instead of 600MB linux-firmware package:
+
+### Essential Network Firmware Only
+```
+intel/          # Intel ethernet (e1000e, ixgbe, i40e)
+realtek/        # Realtek ethernet (r8169)  
+broadcom/       # Broadcom ethernet (bnx2, tg3)
+```
+
+### Load via Kernel Modules (Not Initramfs)
+- WiFi firmware (loaded later from RFS)
+- GPU firmware (not needed for initramfs)
+- Sound firmware (not needed)
+
+## 🎯 **Size Optimization Strategy**
+
+### What to EXCLUDE from Initramfs
+- ❌ **SSH tools** (700KB) - load from RFS
+- ❌ **Debugging tools** (gdb, strace, etc. - 50MB)
+- ❌ **Development tools** (python, etc. - 50MB) 
+- ❌ **Full linux-firmware** (600MB) - selective only
+- ❌ **Compression tools** (load from RFS)
+- ❌ **Network utilities** (curl, wget, etc.)
+
+### What to INCLUDE in Initramfs
+- ✅ **Core Alpine base** (~10MB)
+- ✅ **eudev + kmod** (~5MB)
+- ✅ **Essential network drivers** (~20MB firmware)
+- ✅ **btrfs-progs + dosfstools** (~10MB)
+- ✅ **GitHub components** (zinit, etc. ~5MB)
+
+**Target: ~50MB total**
+
+## 🔧 **Implementation Changes Needed**
+
+### 1. Create Minimal Package List
+Replace `packages.txt` with ultra-minimal version
+
+### 2. Selective Firmware Installation
+Custom script to install only essential network firmware:
+- `/lib/firmware/intel/`
+- `/lib/firmware/realtek/` 
+- `/lib/firmware/broadcom/`
+
+### 3. Build Process Changes
+- Skip massive firmware installation
+- Strip unnecessary files aggressively
+- Optimize cpio compression
+
+### 4. Two-Stage Loading
+1. **Initramfs**: Minimal (network + filesystems)
+2. **RFS**: Full tooling loaded after network
+
+## 📊 **Expected Size Breakdown**
+
+| Component | Size | Notes |
+|-----------|------|-------|
+| Alpine base | ~10MB | Core system |
+| eudev + kmod | ~5MB | Module loading |
+| Filesystems | ~10MB | btrfs + vfat |
+| Network firmware | ~20MB | Essential only |
+| GitHub tools | ~5MB | zinit, core-x, etc |
+| **Total** | **~50MB** | **10x smaller!** |
+
+## 🚀 **Benefits of Minimal Approach**
+
+- **Fast boot**: 50MB vs 700MB embedded
+- **Memory efficient**: Less RAM usage
+- **Network focused**: Only what's needed for connectivity
+- **Scalable**: Load additional tools from RFS after network
+
+This aligns with the original Zero-OS philosophy: minimal initramfs + network-loaded tools.
--- a/docs/MODULES.md
+++ b/docs/MODULES.md
@@ -0,0 +1,255 @@
+# Kernel Modules for Alpine Zero-OS Initramfs
+
+Essential kernel modules to embed in initramfs for hardware detection and basic functionality.
+
+## 🔧 Storage Controllers (Built-in to Initramfs)
+
+### SATA/AHCI Controllers
+```
+# Standard SATA/AHCI support
+ahci
+libahci
+sata_via
+sata_sis
+sata_uli
+sata_promise
+sata_qstor
+sata_vsc
+sata_svw
+sata_nv
+sata_mv
+ata_piix
+ata_generic
+pata_acpi
+```
+
+### NVMe Storage
+```
+# NVMe SSD support  
+nvme
+nvme-core
+nvme-fabrics
+nvme-fc
+nvme-rdma
+nvme-tcp
+```
+
+### SCSI Support
+```
+# SCSI layer
+scsi_mod
+sd_mod
+sr_mod
+sg
+scsi_transport_sas
+scsi_transport_spi
+scsi_transport_fc
+```
+
+### Virtual Storage (Cloud/VM)
+```
+# Virtualization storage
+virtio_blk
+virtio_scsi
+vmw_balloon
+vmw_vmci
+vmware_balloon
+xen-blkfront
+```
+
+### USB Storage
+```
+# USB mass storage
+usb-storage
+uas
+usb_common
+usbcore
+ehci-hcd
+ohci-hcd
+uhci-hcd
+xhci-hcd
+```
+
+## 🌐 Network Controllers (Built-in to Initramfs)
+
+### Intel Ethernet
+```
+# Intel network adapters
+e1000
+e1000e
+igb
+igbvf
+ixgbe
+ixgbevf
+i40e
+i40evf
+ice
+iavf
+```
+
+### Realtek Ethernet  
+```
+# Realtek adapters
+r8169
+8139too
+8139cp
+```
+
+### Broadcom Ethernet
+```
+# Broadcom adapters
+tg3
+bnx2
+bnx2x
+```
+
+### AMD/ATI Ethernet
+```
+# AMD network adapters
+pcnet32
+```
+
+### Virtual Network (Cloud/VM)
+```
+# Virtualization networking
+virtio_net
+vmxnet3
+xen-netfront
+```
+
+### Standard Network Support
+```
+# Core networking
+netconsole
+```
+
+## 💾 Filesystem Support (Built-in)
+
+### Essential Filesystems
+```
+# Core filesystems for Zero-OS
+ext4
+btrfs
+xfs
+vfat
+ntfs
+fuse
+overlay
+tmpfs
+proc
+sysfs
+devtmpfs
+```
+
+### Special Filesystems
+```
+# Container/special use
+unionfs
+aufs
+squashfs
+```
+
+## 🔌 Hardware Detection & Management
+
+### PCI/Hardware Detection
+```
+# Hardware enumeration
+pci_hotplug
+acpiphp
+pciehp
+shpchp
+```
+
+### Device Management
+```
+# Device handling
+usbhid
+hid-generic
+i2c-core
+```
+
+## ⚙️ Kernel Configuration
+
+For Alpine kernel build, these modules should be:
+
+### Built-in (=y)
+- Core filesystem support (ext4, btrfs, tmpfs, proc, sysfs)
+- Basic PCI/ACPI support
+- Essential SATA (ahci, ata_piix)
+- Basic virtio support for cloud environments
+
+### Modules (=m) - Included in Initramfs
+- Extended storage controllers
+- Network adapters
+- USB support
+- Advanced filesystem support
+
+### Example Kernel Config Additions
+```bash
+# Storage - built-in
+CONFIG_ATA=y
+CONFIG_SATA_AHCI=y
+CONFIG_ATA_PIIX=y
+CONFIG_NVME_CORE=y
+CONFIG_NVME=y
+
+# Storage - modules (in initramfs)
+CONFIG_SATA_VIA=m
+CONFIG_SATA_SIS=m
+CONFIG_SATA_PROMISE=m
+# ... (rest as modules)
+
+# Network - built-in
+CONFIG_NETDEVICES=y
+CONFIG_ETHERNET=y
+
+# Network - modules (in initramfs)  
+CONFIG_E1000=m
+CONFIG_E1000E=m
+CONFIG_IGB=m
+CONFIG_IXGBE=m
+CONFIG_R8169=m
+CONFIG_TG3=m
+# ... (rest as modules)
+
+# Filesystems - built-in
+CONFIG_EXT4_FS=y
+CONFIG_BTRFS_FS=y
+CONFIG_TMPFS=y
+CONFIG_PROC_FS=y
+CONFIG_SYSFS=y
+
+# Filesystems - modules (in initramfs)
+CONFIG_XFS_FS=m
+CONFIG_VFAT_FS=m
+CONFIG_NTFS_FS=m
+CONFIG_FUSE_FS=m
+CONFIG_OVERLAY_FS=m
+```
+
+## 📡 Remote Module Loading Strategy
+
+Modules **NOT** included in initramfs (loaded via RFS):
+- Wireless drivers (wifi, bluetooth)
+- Specialized storage controllers (rare/legacy hardware)
+- Graphics drivers
+- Audio drivers
+- Specialized network adapters (10GbE, InfiniBand, etc.)
+- Hardware-specific drivers (sensors, etc.)
+
+These will be:
+1. Stored in remote RFS repositories
+2. Downloaded on-demand based on hardware detection
+3. Loaded dynamically after basic system initialization
+
+## 🔧 Module Loading Order
+
+1. **Phase 1 (Early Init)**: Built-in modules for basic hardware
+2. **Phase 2 (Hardware Detection)**: Load initramfs modules based on detected hardware
+3. **Phase 3 (Remote Loading)**: Fetch additional modules via RFS as needed
+
+This approach ensures:
+- ✅ Fast boot with essential hardware support
+- ✅ Minimal initramfs size
+- ✅ Support for wide hardware variety via remote loading
+- ✅ Always up-to-date drivers via RFS
--- a/docs/OVERVIEW.md
+++ b/docs/OVERVIEW.md
@@ -0,0 +1,289 @@
+# Alpine Zero-OS Initramfs - Complete Architecture Overview
+
+Comprehensive documentation for the Alpine Linux-based Zero-OS initramfs system that replaces the complex build-from-source approach.
+
+## 🎯 Project Goals
+
+Transform Zero-OS initramfs from:
+- ❌ **60+ packages built from source** → ✅ **Alpine packages + 4 GitHub releases**
+- ❌ **Complex build dependencies** → ✅ **Simple Docker build**
+- ❌ **60+ minute builds** → ✅ **5-minute builds**
+- ❌ **Manual security updates** → ✅ **Alpine security updates**
+- ❌ **Ubuntu 18.04 locked** → ✅ **Alpine 3.22 current**
+
+## 🏗️ Architecture Summary
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Alpine Zero-OS Stack                     │
+├─────────────────────────────────────────────────────────────┤
+│ Applications:   zinit (PID1) │ core-x │ seektime │ rfs     │ ← GitHub
+├─────────────────────────────────────────────────────────────┤
+│ System Tools:   openssh │ curl │ redis │ btrfs-progs │... │ ← Alpine
+├─────────────────────────────────────────────────────────────┤
+│ Core System:    busybox │ util-linux │ openssl │ eudev    │ ← Alpine
+├─────────────────────────────────────────────────────────────┤
+│ Base System:    musl libc │ Alpine Linux │ apk             │ ← Alpine
+├─────────────────────────────────────────────────────────────┤
+│ Kernel:         Alpine LTS Kernel + Essential Modules      │ ← Alpine
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 📦 Component Mapping
+
+### Direct Alpine Replacements (40+ packages)
+| Component | Current Version | Alpine Package | Status |
+|-----------|----------------|----------------|---------|
+| busybox | 1.31.0 | `busybox` | ✅ Direct replacement |
+| openssl | 1.1.1d | `openssl` | ✅ Latest version |
+| util-linux | 2.34 | `util-linux` | ✅ Latest version |
+| e2fsprogs | 1.45.2 | `e2fsprogs` | ✅ Latest version |
+| btrfs-progs | 4.20.2 | `btrfs-progs` | ✅ Latest version |
+| openssh | 8.0p1 | `openssh` | ✅ Latest version |
+| redis | 7.2.1 | `redis` | ✅ Latest version |
+| ... | ... | ... | ✅ See PACKAGES.md |
+
+### GitHub Components (4 only)
+| Component | Repository | Purpose |
+|-----------|------------|---------|
+| zinit | `threefoldtech/zinit` | Init system (PID 1) |
+| core-x | `threefoldtech/core-x` | Container control |
+| seektime | `threefoldtech/seektime` | Disk detection |
+| rfs | `threefoldtech/rfs` | Rust filesystem |
+
+## 🔄 Boot Flow (Unchanged)
+
+```
+1. Kernel Boot
+   ├── Load Alpine initramfs
+   └── Execute /init (Alpine sh)
+
+2. Init Phase (/init script)
+   ├── Mount proc, sysfs, devtmpfs
+   ├── Create 1536M tmpfs at /mnt/root
+   ├── Copy Alpine filesystem to tmpfs
+   ├── Hardware detection (udev)
+   ├── Load essential drivers
+   ├── Debug file injection (if enabled)
+   └── switch_root /mnt/root /sbin/zinit init
+
+3. Zinit Phase (PID 1)
+   ├── Read /etc/zinit/*.yaml configs
+   ├── Start system services
+   ├── Manage containers
+   └── Runtime operation
+```
+
+**Key Point**: Boot flow remains 100% identical to current system.
+
+## 🛠️ Build Process
+
+### Current vs Alpine Build
+
+| Phase | Current Approach | Alpine Approach | Time Savings |
+|-------|------------------|-----------------|--------------|
+| **Setup** | Install Ubuntu 18.04 deps | Alpine Docker image | 90% faster |
+| **Downloads** | 60+ source archives | 4 GitHub releases | 95% less data |
+| **Compilation** | Build each package | Install Alpine packages | 99% faster |
+| **Integration** | Complex scripts | Simple filesystem copy | 80% faster |
+| **Kernel** | Custom build | Alpine kernel + modules | 50% faster |
+| **Total** | 60+ minutes | ~5 minutes | **92% faster** |
+
+### Build Commands
+
+```bash
+# Simple build process
+cd alpine-initramfs/build
+docker compose build
+docker compose run --rm builder
+
+# Output: ../output/vmlinuz.efi
+```
+
+## 📂 Directory Structure
+
+```
+alpine-initramfs/
+├── build/                     # Build orchestration
+│   ├── Dockerfile.alpine      # Alpine build environment
+│   ├── docker-compose.yml     # Build orchestration
+│   └── build-initramfs.sh     # Main build script
+├── configs/                   # Configuration files
+│   ├── packages.txt           # Alpine packages list
+│   ├── kernel-modules.txt     # Essential modules
+│   ├── init                   # Init script (Alpine→zinit)
+│   ├── init-debug            # Debug injection script
+│   └── zinit/                 # Zinit configs (from ../config/etc/zinit/)
+├── scripts/                   # Build helper scripts
+│   ├── fetch-github.sh        # Download GitHub components
+│   ├── install-packages.sh    # Install Alpine packages
+│   ├── setup-initramfs.sh     # Create initramfs structure
+│   └── build-kernel.sh        # Build kernel + initramfs
+├── docs/                      # Documentation
+│   ├── OVERVIEW.md            # This file - complete architecture
+│   ├── PACKAGES.md            # Package mapping reference
+│   ├── MODULES.md             # Kernel modules reference
+│   ├── BUILD.md               # Build process guide
+│   ├── INIT.md                # Init script design
+│   └── GITHUB.md              # GitHub integration
+├── cache/                     # Build caches (Docker volumes)
+│   ├── github/                # GitHub releases cache
+│   └── packages/              # Alpine packages cache
+└── output/                    # Build artifacts
+    ├── vmlinuz.efi            # Final bootable kernel
+    ├── initramfs.cpio.xz      # Standalone initramfs
+    └── build.log              # Build log
+```
+
+## 🔧 Key Technical Details
+
+### Hardware Support Strategy
+
+**Built-in Modules (Essential)**:
+- Storage: SATA (ahci), NVMe (nvme), Virtual (virtio_blk)
+- Network: Intel (e1000e), Realtek (r8169), Virtual (virtio_net)
+- Filesystems: btrfs, ext4, tmpfs, overlay, fuse
+
+**Initramfs Modules (Common)**:
+- Extended storage controllers
+- Additional network adapters
+- USB support
+- Specialized filesystems
+
+**Remote Modules (RFS)**:
+- Wireless drivers
+- Specialized hardware
+- Graphics/audio drivers
+- Legacy hardware support
+
+### Memory Usage
+
+| Component | Current | Alpine | Change |
+|-----------|---------|--------|--------|
+| **Initramfs Size** | ~200MB | ~150MB | -25% smaller |
+| **Runtime RAM** | 1536MB tmpfs | 1536MB tmpfs | Unchanged |
+| **Boot Memory** | ~300MB | ~250MB | -17% less |
+
+### Security Benefits
+
+| Aspect | Current | Alpine | Improvement |
+|--------|---------|--------|-------------|
+| **Base System** | Ubuntu 18.04 | Alpine 3.22 | Current LTS |
+| **Security Updates** | Manual | Alpine team | Automated |
+| **Attack Surface** | Large build chain | Minimal packages | Reduced |
+| **Vulnerability Response** | Slow | Fast | Days vs months |
+
+## 🚀 Migration Benefits
+
+### For Developers
+- ✅ **Faster builds**: 5 minutes vs 60+ minutes
+- ✅ **Simpler debugging**: Standard Alpine tools
+- ✅ **Better caching**: Docker layer caching
+- ✅ **Modern toolchain**: Latest versions
+- ✅ **Easier updates**: `docker compose build`
+
+### For Operations
+- ✅ **Automated security**: Alpine security updates
+- ✅ **Reduced complexity**: No build chain maintenance
+- ✅ **Better reliability**: Fewer moving parts
+- ✅ **Standard tools**: Alpine ecosystem
+- ✅ **Container native**: Docker-based workflow
+
+### For Users
+- ✅ **Same functionality**: Identical boot/runtime behavior
+- ✅ **Better hardware support**: Latest drivers
+- ✅ **Faster boot**: Optimized initramfs
+- ✅ **More reliable**: Alpine stability
+- ✅ **Current security**: Latest patches
+
+## 📋 Implementation Plan
+
+### Phase 1: Setup (Complete)
+- [x] Architecture design
+- [x] Package mapping
+- [x] Build system design
+- [x] Documentation
+
+### Phase 2: Implementation (Next)
+- [ ] Create actual build files (Dockerfile, scripts, configs)
+- [ ] Test basic Alpine package installation
+- [ ] Verify GitHub component fetching
+- [ ] Test initramfs generation
+
+### Phase 3: Integration (Following)
+- [ ] Kernel build integration
+- [ ] Boot testing with QEMU
+- [ ] Hardware compatibility testing
+- [ ] Performance benchmarking
+
+### Phase 4: Validation (Final)
+- [ ] Full system testing
+- [ ] Migration testing from current system
+- [ ] Documentation finalization
+- [ ] Deployment readiness
+
+## 🎛️ Configuration
+
+### Build Modes
+
+**Debug Mode** (default):
+- Latest GitHub releases
+- Debug symbols preserved
+- Verbose logging
+- Debug file injection enabled
+
+**Production Mode**:
+- Pinned component versions
+- Optimized binaries
+- Minimal logging
+- Security hardened
+
+### Customization Options
+
+```bash
+# Environment variables
+BUILDMODE=release          # debug|release
+TARGETARCH=amd64          # amd64|arm64
+KERNEL_VERSION=lts        # lts|edge|specific
+ALPINE_VERSION=3.22       # Alpine version
+
+# Build options
+INCLUDE_MODULES=minimal   # minimal|standard|full
+CACHE_DOWNLOADS=true      # Enable download caching
+VERIFY_CHECKSUMS=true     # Verify component integrity
+```
+
+## 📚 Documentation Index
+
+| Document | Purpose | Audience |
+|----------|---------|----------|
+| **OVERVIEW.md** | Complete architecture | All stakeholders |
+| **PACKAGES.md** | Package mapping reference | Developers |
+| **MODULES.md** | Kernel modules reference | System engineers |
+| **BUILD.md** | Build process guide | Developers |
+| **INIT.md** | Init script design | System engineers |
+| **GITHUB.md** | GitHub integration | Developers |
+
+## 🎯 Success Metrics
+
+| Metric | Current | Target | Status |
+|--------|---------|--------|--------|
+| **Build Time** | 60+ min | <5 min | 🎯 Designed |
+| **Build Complexity** | High | Low | 🎯 Designed |
+| **Update Frequency** | Quarterly | Monthly | 🎯 Planned |
+| **Security Response** | Weeks | Days | 🎯 Planned |
+| **Developer Onboarding** | Hours | Minutes | 🎯 Designed |
+
+## 🏁 Conclusion
+
+The Alpine-based approach represents a fundamental architectural improvement:
+
+- **Simplicity**: Replace complex build chain with package management
+- **Modernity**: Current tools and security practices
+- **Efficiency**: Massive reduction in build time and complexity
+- **Reliability**: Proven Alpine Linux ecosystem
+- **Maintainability**: Automated updates and minimal custom code
+
+This design maintains 100% compatibility with existing Zero-OS functionality while providing a modern, efficient, and maintainable foundation for future development.
+
+**Next Step**: Switch to code mode to implement the actual build files and scripts based on this architecture.
--- a/docs/PACKAGES.md
+++ b/docs/PACKAGES.md
@@ -0,0 +1,104 @@
+# Package Mapping: Build-from-Source → Alpine
+
+This document maps the current build-from-source components to their Alpine Linux package equivalents.
+
+## ✅ Direct Alpine Package Replacements
+
+| Current Build | Version | Alpine Package | Notes |
+|---------------|---------|----------------|-------|
+| busybox | 1.31.0 | `busybox` | Core system utilities |
+| openssl | 1.1.1d | `openssl` | Crypto library |
+| ca-certificates | 20190110 | `ca-certificates` | SSL certificates |
+| util-linux | 2.34 | `util-linux` | System utilities (lsblk, etc.) |
+| e2fsprogs | 1.45.2 | `e2fsprogs` | ext2/3/4 filesystem tools |
+| btrfs-progs | 4.20.2 | `btrfs-progs` | Btrfs filesystem tools |
+| parted | 3.2 | `parted` | Partition management |
+| dnsmasq | 2.80 | `dnsmasq` | DHCP/DNS server |
+| nftables | 0.9.1 | `nftables` | Firewall/routing |
+| iproute2 | 5.4.0 | `iproute2` | Network namespace support |
+| openssh | 8.0p1 | `openssh` | SSH client/server |
+| curl | 7.65.1 | `curl` | HTTP client library |
+| restic | 0.9.2 | `restic` | Backup tool |
+| wireguard-tools | 1.0.20200102 | `wireguard-tools` | VPN userland tools |
+| zlib | 1.2.11 | `zlib` | Compression library |
+| fuse | 2.9.7 | `fuse` | Filesystem in userspace |
+| unionfs-fuse | 2.0 | `unionfs-fuse` | Union filesystem |
+| smartmontools | 7.0 | `smartmontools` | S.M.A.R.T monitoring |
+| dmidecode | 3.2 | `dmidecode` | Hardware info |
+| netcat | 110 | `netcat-openbsd` | Network utility |
+| redis | 7.2.1 | `redis` | Key-value store |
+| haveged | 1.9.4 | `haveged` | Entropy daemon |
+| ethtool | 5.1 | `ethtool` | Ethernet tool |
+| dhcpcd | 7.2.2 | `dhcpcd` | DHCP client |
+| tcpdump | 4.9.2 | `tcpdump` | Network packet analyzer |
+| xfsprogs | 5.4.0 | `xfsprogs` | XFS filesystem tools |
+| bcache-tools | master | `bcache-tools` | Bcache utilities |
+| keyutils | 1.6.3 | `keyutils` | Kernel key management |
+| zstd | 1.5.6 | `zstd` | Compression tool |
+| libaio | 0.3.113 | `libaio` | Async I/O library |
+
+## 🔧 Hardware & Kernel Support
+
+| Current Build | Alpine Package | Purpose |
+|---------------|----------------|---------|
+| eudev | `eudev` | Device manager |
+| kmod | `kmod` | Kernel module tools |
+| linux-firmware | `linux-firmware` | Hardware firmware |
+
+## 🐹 GitHub Components (Custom Builds)
+
+These components are fetched from GitHub releases instead of building from source:
+
+| Component | Repository | Purpose |
+|-----------|------------|---------|
+| zinit | `github.com/threefoldtech/zinit` | Init system (PID 1) |
+| core-x | `github.com/threefoldtech/core-x` | Container remote control |
+| seektime | `github.com/threefoldtech/seektime` | Disk type detection |
+| rfs | `github.com/threefoldtech/rfs` | Rust version of 0-fs |
+
+## 📦 Additional Alpine Packages Needed
+
+These packages are required for the Alpine environment but weren't in the original build:
+
+| Package | Purpose |
+|---------|---------|
+| `alpine-base` | Base Alpine system |
+| `musl` | C library |
+| `alpine-keys` | Package signing keys |
+| `apk-tools` | Package manager |
+| `busybox-suid` | SUID busybox utilities |
+| `util-linux-misc` | Additional util-linux tools |
+
+## 🏗️ Build Dependencies (Build Container Only)
+
+These are only needed in the build container, not in the final initramfs:
+
+| Package | Purpose |
+|---------|---------|
+| `build-base` | Compilation tools |
+| `linux-headers` | Kernel headers |
+| `cmake` | Build system |
+| `git` | Source control |
+| `wget` | Download tool |
+| `cpio` | Archive tool |
+| `xz` | Compression |
+
+## 🚫 Removed Components
+
+These are no longer needed with the Alpine approach:
+
+| Removed | Reason |
+|---------|--------|
+| libvirt + qemu | Too heavy for initramfs, not core functionality |
+| Various build toolchains | Using Alpine packages instead |
+| Custom musl builds | Alpine already uses musl |
+
+## 📊 Size Comparison
+
+| Metric | Current Build | Alpine Approach |
+|--------|---------------|-----------------|
+| Build time | 60+ minutes | ~5 minutes |
+| Source packages | 50+ | 4 (GitHub only) |
+| Dependencies | Complex web | Package manager handled |
+| Updates | Manual version bumps | Alpine package updates |
+| Security patches | Manual backports | Alpine security team |
--- a/docs/VERSIONS.md
+++ b/docs/VERSIONS.md
@@ -0,0 +1,170 @@
+# Latest Versions Update - Alpine 3.22
+
+Updated version mapping to use the latest and greatest Alpine Linux 3.22 and current package versions.
+
+## 🚀 Alpine Version Update
+
+### Current State (August 2025)
+- **Alpine Linux**: 3.22 (latest stable)
+- **Kernel**: Linux 6.12.42 LTS
+- **OpenSSL**: 3.3.x (current stable)
+- **All packages**: Latest stable versions from Alpine 3.22
+
+## 📦 Updated Package Versions
+
+### Core System Components
+| Component | Old Reference | Alpine 3.22 Version | Security Status |
+|-----------|---------------|---------------------|-----------------|
+| **Alpine Base** | 3.19 | **3.22** | ✅ Current stable |
+| **OpenSSL** | 1.1.1d (EOL) | **3.3.x** | ✅ Current, secure |
+| **Linux Kernel** | 6.8.8 | **6.12.42 LTS** | ✅ Latest LTS |
+| **busybox** | 1.31.0 | **1.37.x** | ✅ Current |
+| **util-linux** | 2.34 | **2.40.x** | ✅ Current |
+| **e2fsprogs** | 1.45.2 | **1.47.x** | ✅ Current |
+| **btrfs-progs** | 4.20.2 | **6.10.x** | ✅ Current |
+| **openssh** | 8.0p1 | **9.8.x** | ✅ Current |
+| **redis** | 7.2.1 | **7.4.x** | ✅ Current |
+
+### Network & Security Tools
+| Component | Old Reference | Alpine 3.22 Version | Notes |
+|-----------|---------------|---------------------|-------|
+| **curl** | 7.65.1 | **8.9.x** | ✅ HTTP/3 support |
+| **nftables** | 0.9.1 | **1.1.x** | ✅ Latest features |
+| **wireguard** | 1.0.20200102 | **1.0.x** | ✅ Current stable |
+| **dnsmasq** | 2.80 | **2.90.x** | ✅ Current |
+
+### Container & Virtualization
+| Component | Old Reference | Alpine 3.22 Version | Notes |
+|-----------|---------------|---------------------|-------|
+| **runc** | Not included | **1.2.x** | ✅ OCI runtime |
+| **containerd** deps | Various | **Current** | ✅ Latest stable |
+
+## 🔧 Updated Docker Configuration
+
+### Dockerfile Changes
+```dockerfile
+# Updated to latest Alpine
+FROM alpine:3.22
+
+# Latest package versions automatically included
+RUN apk add --no-cache \
+    linux-lts-dev \     # 6.12.42 LTS kernel
+    openssl-dev \       # OpenSSL 3.3.x
+    # ... all packages get latest versions
+```
+
+### Version Benefits
+- **Security**: All packages receive latest security patches
+- **Features**: Access to latest functionality
+- **Performance**: Optimizations from years of development
+- **Compatibility**: Better hardware support
+
+## 📋 Updated Architecture Decisions
+
+### 1. Always Use Latest Stable
+```yaml
+Strategy: Latest Stable Packages
+Rationale: 
+  - Security patches automatically included
+  - Better hardware support
+  - Performance improvements
+  - Feature completeness
+Risk Mitigation:
+  - Alpine 3.22 is well-tested stable release
+  - Package versions are curated by Alpine team
+```
+
+### 2. Automatic Updates via Alpine
+```yaml
+Update Strategy: Alpine Package Manager
+Benefits:
+  - Consistent, tested combinations
+  - Security team maintenance
+  - Minimal compatibility issues
+  - Automated dependency resolution
+```
+
+### 3. Version Pinning for Production
+```yaml
+Development: Use :latest tags (Alpine 3.22)
+Production: Pin specific Alpine 3.22.x point releases
+CI/CD: Regular automated updates with testing
+```
+
+## 🚨 Security Improvements
+
+### Eliminated EOL Software
+- ❌ **OpenSSL 1.1.1d** (End of Life September 2023)
+- ✅ **OpenSSL 3.3.x** (Active development, LTS until 2026)
+
+### Current Security Status
+- ✅ **All packages**: Active maintenance
+- ✅ **Alpine 3.22**: Regular security updates
+- ✅ **Kernel 6.12.42**: Long-term support branch
+- ✅ **No EOL components**: Everything actively maintained
+
+## 📊 Version Comparison Impact
+
+### Build Time Impact
+| Metric | Old Versions | Alpine 3.22 | Improvement |
+|--------|-------------|--------------|-------------|
+| **Security patches** | Manual | Automatic | 100% automated |
+| **Feature updates** | Complex | Simple | Package manager |
+| **Compatibility** | Unknown | Tested | Alpine integration |
+| **Maintenance** | High effort | Minimal | Alpine team handled |
+
+### Runtime Improvements
+- **Better hardware support**: Latest drivers and firmware
+- **Performance**: Years of optimizations
+- **Security**: No EOL vulnerabilities
+- **Features**: Latest tool capabilities
+
+## 🎯 Implementation Updates
+
+### Updated Dockerfile
+```dockerfile
+FROM alpine:3.22  # Was: alpine:3.19
+
+# All packages automatically get latest versions:
+# - OpenSSL 3.3.x (was: 1.1.1d EOL)
+# - Linux 6.12.42 LTS (was: 6.8.8)
+# - All tools: current stable versions
+```
+
+### Package Selection Strategy
+```yaml
+Approach: Trust Alpine Curation
+- Use Alpine 3.22 stable packages
+- No version pinning in package list
+- Let Alpine team handle version compatibility
+- Pin only the Alpine base version (3.22)
+```
+
+### Update Process
+```bash
+# Automatic latest versions
+apk add --no-cache package-name  # Gets latest stable
+
+# No need for version specifications:
+# apk add openssl=1.1.1d  # Old, manual approach
+# apk add openssl         # New, automatic latest
+```
+
+## ✅ Migration Benefits
+
+### Security
+- **No EOL software**: Everything actively maintained
+- **Patch automation**: Alpine security team handles updates
+- **CVE response**: Faster than manual maintenance
+
+### Operational
+- **Simplified maintenance**: No version tracking needed
+- **Better support**: Active community and documentation
+- **Hardware compatibility**: Latest drivers and firmware
+
+### Development
+- **Faster builds**: Optimized packages
+- **Better debugging**: Current tooling
+- **Documentation**: Up-to-date guides and examples
+
+This update ensures Zero-OS uses current, secure, and performant software components while maintaining the same functionality and boot behavior.
--- a/scripts/build-boot.sh
+++ b/scripts/build-boot.sh
@@ -0,0 +1,179 @@
+#!/bin/sh
+set -e
+
+BOOT_ROOT="/build/boot"
+OUTPUT_DIR="/build/output"
+CONFIG_DIR="/build/configs"
+
+echo "[+] Building minimal boot initramfs..."
+echo "    Target: ~10-20MB embedded in kernel"
+echo "    Purpose: Boot + network + mount Alpine runtime"
+
+# Clean and create boot root
+rm -rf "$BOOT_ROOT"
+mkdir -p "$BOOT_ROOT"
+
+echo "[+] Installing minimal boot packages..."
+
+# Set up APK for boot root
+mkdir -p "$BOOT_ROOT/etc/apk"
+cp /etc/apk/repositories "$BOOT_ROOT/etc/apk/"
+
+# Copy APK keys
+if [ -d /etc/apk/keys ]; then
+    mkdir -p "$BOOT_ROOT/etc/apk/keys"
+    cp /etc/apk/keys/* "$BOOT_ROOT/etc/apk/keys/"
+fi
+
+# Create APK database
+mkdir -p "$BOOT_ROOT/lib/apk/db"
+mkdir -p "$BOOT_ROOT/var/cache/apk"
+
+# Install absolute minimal packages
+echo "  Installing boot packages from packages-boot.txt..."
+apk --root "$BOOT_ROOT" --clean-protected --update-cache --initdb add alpine-baselayout busybox apk-tools musl
+
+# Install additional boot packages
+while read -r package; do
+    # Skip comments and empty lines
+    case "$package" in
+        \#*|"") continue ;;
+    esac
+    
+    echo "    Installing: $package"
+    if apk --root "$BOOT_ROOT" add --no-cache "$package"; then
+        echo "      Success: $package"
+    else
+        echo "      Warning: Failed to install $package"
+    fi
+done < "$CONFIG_DIR/packages-boot.txt"
+
+echo "[+] Installing minimal ethernet drivers..."
+# Install essential ethernet firmware and drivers using our minimal script
+INITRAMFS_ROOT="$BOOT_ROOT" /build/scripts/install-firmware-minimal.sh
+
+echo "[+] Setting up boot filesystem structure..."
+
+# Create essential directories
+mkdir -p "$BOOT_ROOT"/{dev,proc,sys,mnt,tmp,var/run,var/log}
+mkdir -p "$BOOT_ROOT"/{root,home,opt}
+mkdir -p "$BOOT_ROOT"/mnt/{alpine,debug}
+
+# Create device nodes
+echo "  Creating device nodes..."
+[ ! -e "$BOOT_ROOT/dev/console" ] && mknod "$BOOT_ROOT/dev/console" c 5 1
+[ ! -e "$BOOT_ROOT/dev/null" ] && mknod "$BOOT_ROOT/dev/null" c 1 3
+[ ! -e "$BOOT_ROOT/dev/zero" ] && mknod "$BOOT_ROOT/dev/zero" c 1 5
+
+# Set proper permissions
+chmod 666 "$BOOT_ROOT/dev/null" "$BOOT_ROOT/dev/zero"
+chmod 600 "$BOOT_ROOT/dev/console"
+
+echo "[+] Creating boot init script..."
+# Create minimal init script for mounting Alpine runtime
+cat > "$BOOT_ROOT/init" << 'EOF'
+#!/bin/sh
+# Minimal boot init - establish network and mount Alpine runtime
+
+echo "[BOOT] Zero-OS minimal boot starting..."
+
+# Mount essential filesystems
+mount -t proc proc /proc
+mount -t sysfs sysfs /sys
+mount -t devtmpfs devtmpfs /dev
+
+# Load essential modules
+echo "[BOOT] Loading ethernet drivers..."
+modprobe -a e1000 e1000e igb ixgbe r8169 8139too bnx2 tg3 2>/dev/null || true
+
+# Start eudev for hardware detection
+echo "[BOOT] Starting hardware detection..."
+/sbin/udevd --daemon
+udevadm trigger
+udevadm settle
+
+# Network configuration
+echo "[BOOT] Configuring network..."
+for iface in $(ls /sys/class/net/ | grep -v lo); do
+    echo "  Bringing up interface: $iface"
+    ip link set "$iface" up
+    # Try DHCP with timeout
+    timeout 30 dhcpcd "$iface" && break
+done
+
+# Mount Alpine runtime system
+echo "[BOOT] Mounting Alpine runtime system..."
+
+# Check for VirtioFS mount (development)
+if [ -d /sys/fs/virtio_fs ]; then
+    echo "  Attempting VirtioFS mount..."
+    mount -t virtiofs alpine-root /mnt/alpine && ALPINE_MOUNTED=true
+fi
+
+# If VirtioFS failed, try network mount (production)
+if [ "$ALPINE_MOUNTED" != "true" ]; then
+    echo "  VirtioFS not available, attempting network mount..."
+    # Add network mounting logic here (NFS, HTTP, etc.)
+    echo "  Network mount not implemented yet"
+fi
+
+# Switch to Alpine runtime if mounted
+if [ "$ALPINE_MOUNTED" = "true" ]; then
+    echo "[BOOT] Switching to Alpine runtime system..."
+    
+    # Move boot mounts to Alpine
+    mount --move /proc /mnt/alpine/proc
+    mount --move /sys /mnt/alpine/sys
+    mount --move /dev /mnt/alpine/dev
+    
+    # Switch root to Alpine
+    exec switch_root /mnt/alpine /sbin/zinit
+else
+    echo "[BOOT] Failed to mount Alpine runtime - dropping to shell"
+    exec /bin/sh
+fi
+EOF
+
+chmod +x "$BOOT_ROOT/init"
+
+echo "[+] Setting up symlinks..."
+cd "$BOOT_ROOT"
+
+# Standard symlinks
+ln -sf usr/lib lib || true
+ln -sf usr/lib lib64 || true
+
+# Fixed run symlink (not circular)
+mkdir -p run
+cd var
+ln -sf ../run run || true
+cd ..
+
+echo "[+] Cleaning up boot initramfs..."
+# Remove unnecessary files
+rm -rf var/cache/apk/*
+rm -rf usr/share/doc usr/share/man usr/share/info 2>/dev/null || true
+
+# Aggressive cleanup for embedded
+find . -name "*.a" -delete 2>/dev/null || true
+find . -name "*.la" -delete 2>/dev/null || true
+
+echo "[+] Creating boot initramfs archive..."
+cd "$BOOT_ROOT"
+
+# Create cpio archive
+find . | cpio -H newc -o > "$OUTPUT_DIR/boot-initramfs.cpio"
+
+if [ -f "$OUTPUT_DIR/boot-initramfs.cpio" ]; then
+    size=$(stat -c%s "$OUTPUT_DIR/boot-initramfs.cpio")
+    size_mb=$((size / 1024 / 1024))
+    echo "[+] Boot initramfs created: $OUTPUT_DIR/boot-initramfs.cpio (${size_mb}MB)"
+else
+    echo "[-] Error: Failed to create boot initramfs"
+    exit 1
+fi
+
+echo "[+] Minimal boot initramfs build complete"
+echo "    Size: ${size_mb}MB (target: ~10-20MB)"
+echo "    Contains: Boot + network + minimal drivers"
+echo "    Purpose: Mount and switch to Alpine runtime"
--- a/scripts/build-initramfs.sh
+++ b/scripts/build-initramfs.sh
@@ -0,0 +1,74 @@
+#!/bin/sh
+set -e
+
+echo "====================================="
+echo "=   Alpine Zero-OS Initramfs Build  ="
+echo "====================================="
+echo ""
+
+# DIAGNOSTIC: Check critical dependencies before starting
+echo "[DEBUG] Checking critical dependencies..."
+echo "[DEBUG] Current directory: $(pwd)"
+echo "[DEBUG] Available disk space: $(df -h /build | tail -1)"
+echo "[DEBUG] Available memory: $(free -h)"
+echo "[DEBUG] Network connectivity: $(ping -c 1 8.8.8.8 >/dev/null 2>&1 && echo 'OK' || echo 'FAILED')"
+echo "[DEBUG] GitHub API access: $(curl -s https://api.github.com/repos/threefoldtech/zinit/releases/latest >/dev/null 2>&1 && echo 'OK' || echo 'FAILED')"
+echo "[DEBUG] Zinit config mount check: $(ls -la /mnt/zinit 2>/dev/null | wc -l) files"
+echo "[DEBUG] APK repositories: $(apk update >/dev/null 2>&1 && echo 'OK' || echo 'FAILED')"
+echo ""
+
+# Source configuration
+if [ -f /build/build.conf ]; then
+    . /build/build.conf
+else
+    echo "Error: build.conf not found"
+    exit 1
+fi
+
+echo "[+] Build mode: $BUILDMODE"
+echo "[+] Target arch: $TARGETARCH"
+echo "[+] Output directory: $OUTPUT_DIR"
+echo ""
+
+# Ensure output directory exists
+mkdir -p "$OUTPUT_DIR"
+
+# Phase 1: Install Alpine packages to initramfs
+echo "[+] Installing Alpine packages..."
+/build/scripts/install-packages.sh
+
+# Phase 2: Compile Zero-OS components from source (replaces problematic fetch-github)
+echo "[+] Compiling Zero-OS components..."
+if [ -f /build/scripts/build-smart.sh ]; then
+    # Use smart build if available (with caching)
+    /build/scripts/build-smart.sh
+    exit $?
+else
+    # Fallback to direct component compilation
+    /build/scripts/compile-components.sh
+fi
+
+# Phase 3: Setup initramfs structure
+echo "[+] Setting up initramfs structure..."
+/build/scripts/setup-initramfs.sh
+
+# Phase 4: Build kernel with embedded initramfs
+echo "[+] Building kernel..."
+/build/scripts/build-kernel.sh
+
+echo ""
+echo "[+] Build completed successfully!"
+echo "[+] Output files:"
+ls -la "$OUTPUT_DIR/"
+
+# Verify output
+if [ -f "$OUTPUT_DIR/vmlinuz.efi" ]; then
+    size=$(stat -c%s "$OUTPUT_DIR/vmlinuz.efi")
+    echo "[+] Kernel size: $size bytes"
+else
+    echo "[-] Error: vmlinuz.efi not found!"
+    exit 1
+fi
+
+echo ""
+echo "[+] Alpine Zero-OS initramfs build complete!"
--- a/scripts/build-kernel.sh
+++ b/scripts/build-kernel.sh
@@ -0,0 +1,259 @@
+#!/bin/sh
+set -e
+
+KERNEL_DIR="/build/kernel"
+OUTPUT_DIR="/build/output"
+CONFIG_DIR="/build/configs"
+
+# Parse command line arguments
+KERNEL_ONLY=false
+EMBED_ONLY=false
+
+while [ $# -gt 0 ]; do
+    case $1 in
+        --kernel-only)
+            KERNEL_ONLY=true
+            shift
+            ;;
+        --embed-only)
+            EMBED_ONLY=true
+            shift
+            ;;
+        *)
+            echo "Unknown option: $1"
+            exit 1
+            ;;
+    esac
+done
+
+echo "[+] Building custom Zero-OS kernel..."
+echo "    Mode: $([ "$KERNEL_ONLY" = "true" ] && echo "kernel-only" || [ "$EMBED_ONLY" = "true" ] && echo "embed-only" || echo "full-build")"
+
+# DIAGNOSTIC: Check prerequisites
+echo "[DEBUG] Checking kernel build prerequisites..."
+echo "[DEBUG] Initramfs file exists: $([ -f "$OUTPUT_DIR/initramfs.cpio.xz" ] && echo 'YES' || echo 'NO')"
+echo "[DEBUG] Kernel config exists: $([ -f "$CONFIG_DIR/kernel-config-generic" ] && echo 'YES' || echo 'NO')"
+
+# Only check for initramfs if we're doing embedding
+if [ "$KERNEL_ONLY" != "true" ] && [ ! -f "$OUTPUT_DIR/initramfs.cpio.xz" ]; then
+    echo "[DEBUG] ERROR: Initramfs not found - kernel build will fail"
+    exit 1
+fi
+
+if [ ! -f "$CONFIG_DIR/kernel-config-generic" ]; then
+    echo "[DEBUG] ERROR: Kernel config not found - kernel build will fail" 
+    exit 1
+fi
+
+echo "[DEBUG] Initramfs size: $(stat -c%s "$OUTPUT_DIR/initramfs.cpio.xz") bytes"
+
+# Read kernel version from config
+if [ -f "$CONFIG_DIR/kernel-version" ]; then
+    KERNEL_VERSION=$(cat "$CONFIG_DIR/kernel-version" | tr -d '\n')
+    echo "  Using kernel version from config: $KERNEL_VERSION"
+else
+    echo "  Error: kernel-version config file not found" >&2
+    exit 1
+fi
+
+KERNEL_MAJOR=$(echo $KERNEL_VERSION | cut -d. -f1)
+KERNEL_URL="https://cdn.kernel.org/pub/linux/kernel/v${KERNEL_MAJOR}.x/linux-${KERNEL_VERSION}.tar.xz"
+
+echo "  Kernel version: $KERNEL_VERSION"
+echo "  Download URL: $KERNEL_URL"
+
+# Create kernel build directory
+echo "  Setting up kernel build environment..."
+mkdir -p "$KERNEL_DIR"
+cd "$KERNEL_DIR"
+
+# Install kernel build dependencies
+echo "  Installing kernel build dependencies..."
+apk add --no-cache build-base bc bison flex openssl-dev elfutils-dev \
+    perl linux-headers cpio xz wget
+
+# Download kernel source if not already present
+if [ ! -f "linux-${KERNEL_VERSION}.tar.xz" ]; then
+    echo "  Downloading Linux kernel ${KERNEL_VERSION}..."
+    wget -q --show-progress "$KERNEL_URL"
+fi
+
+# Extract kernel source if not already extracted
+if [ ! -d "linux-${KERNEL_VERSION}" ]; then
+    echo "  Extracting kernel source..."
+    tar -xf "linux-${KERNEL_VERSION}.tar.xz"
+fi
+
+cd "linux-${KERNEL_VERSION}"
+
+# Copy kernel config
+echo "  Setting up kernel configuration..."
+cp "$CONFIG_DIR/kernel-config-generic" .config
+
+# Handle different build modes
+if [ "$KERNEL_ONLY" = "true" ]; then
+    echo "  Building kernel only (no initramfs embedding)..."
+    
+    # Disable initramfs in config for kernel-only build
+    sed -i 's/CONFIG_INITRAMFS_SOURCE="..\/..\/root"/CONFIG_INITRAMFS_SOURCE=""/' .config
+    
+    # Update config and build kernel
+    make olddefconfig
+    make -j$(nproc) bzImage
+    make -j$(nproc) modules
+    
+    echo "  Kernel built successfully (cached for later embedding)"
+    exit 0
+    
+elif [ "$EMBED_ONLY" = "true" ]; then
+    echo "  Embedding initramfs into existing kernel..."
+    
+    # The kernel config expects initramfs at "../../root" relative to kernel build directory
+    echo "    Extracting initramfs for embedding..."
+    mkdir -p ../../root
+    cd ../../root
+    rm -rf ./*
+    xz -dc "$OUTPUT_DIR/initramfs.cpio.xz" | cpio -id
+    cd "$KERNEL_DIR/linux-${KERNEL_VERSION}"
+    
+    # Restore initramfs path in config
+    sed -i 's/CONFIG_INITRAMFS_SOURCE=""/CONFIG_INITRAMFS_SOURCE="..\/..\/root"/' .config
+    
+    # Rebuild with embedded initramfs
+    make olddefconfig
+    make -j$(nproc) bzImage
+    
+    # Copy final kernel
+    echo "    Copying embedded kernel..."
+    cp arch/x86/boot/bzImage "$OUTPUT_DIR/vmlinuz.efi"
+    
+    kernel_size=$(stat -c%s "$OUTPUT_DIR/vmlinuz.efi")
+    echo "  Embedded kernel created: $(echo "$kernel_size / 1024 / 1024" | bc)MB"
+    exit 0
+    
+else
+    # Full build mode (original behavior)
+    echo "  Full build: kernel + embedded initramfs..."
+    
+    # The kernel config expects initramfs at "../../root" relative to kernel build directory
+    echo "  Setting up initramfs for kernel embedding..."
+    mkdir -p ../../root
+    cd ../../root
+    
+    # Extract our initramfs to the location expected by kernel config
+    echo "  Extracting initramfs to expected location..."
+    # Remove any existing contents first
+    rm -rf ./*
+    # Extract the initramfs cpio archive
+    xz -dc "$OUTPUT_DIR/initramfs.cpio.xz" | cpio -id
+    
+    echo "  Initramfs extracted to: $(pwd)"
+    echo "  Initramfs contents:"
+    find . -maxdepth 2 -type f -o -type d | head -20
+    
+    # Return to kernel source directory
+    cd "$KERNEL_DIR/linux-${KERNEL_VERSION}"
+    
+    # Verify kernel config is properly set up
+    echo "  Verifying kernel configuration..."
+    if grep -q 'CONFIG_INITRAMFS_SOURCE="../../root"' .config; then
+        echo "    ✓ Initramfs source path configured correctly"
+    else
+        echo "    ✗ Warning: Initramfs source path not found in config"
+    fi
+    
+    if grep -q 'CONFIG_INITRAMFS_COMPRESSION_XZ=y' .config; then
+        echo "    ✓ XZ compression enabled"
+    else
+        echo "    ✗ Warning: XZ compression not enabled"
+    fi
+    
+    # Update config to handle any new options
+    echo "  Updating kernel configuration..."
+    make olddefconfig
+    
+    # Build the kernel
+    echo "  Building kernel with embedded initramfs..."
+    echo "    This may take several minutes..."
+    make -j$(nproc) bzImage
+fi
+
+# Verify kernel was built
+if [ ! -f "arch/x86/boot/bzImage" ]; then
+    echo "    Error: Kernel build failed - bzImage not found" >&2
+    exit 1
+fi
+
+# Copy built kernel to output location
+echo "  Installing built kernel..."
+cp arch/x86/boot/bzImage "$OUTPUT_DIR/vmlinuz.efi"
+
+# Get kernel size info
+kernel_size=$(stat -c%s "$OUTPUT_DIR/vmlinuz.efi")
+initramfs_size=$(stat -c%s "$OUTPUT_DIR/initramfs.cpio.xz")
+
+echo "[DEBUG] Built kernel size: $kernel_size bytes"
+echo "[DEBUG] Original initramfs size: $initramfs_size bytes"
+
+# Create version info file
+echo "  Creating version information..."
+cat > "$OUTPUT_DIR/version.txt" << EOF
+Zero-OS Custom Kernel (Linux $KERNEL_VERSION)
+Built: $(date)
+Source: $KERNEL_URL
+Config: kernel-config-generic
+Initramfs: Embedded during compilation
+Final size: $kernel_size bytes
+Original initramfs: $initramfs_size bytes
+
+Boot Options:
+  Method: Custom kernel with embedded initramfs
+  Usage: Boot vmlinuz.efi directly
+  GRUB: linux vmlinuz.efi
+  No separate initramfs needed
+
+Build Environment:
+  Alpine Linux $(cat /etc/alpine-release 2>/dev/null || echo 'unknown')
+  GCC: $(gcc --version | head -1)
+  Make: $(make --version | head -1)
+EOF
+
+# Build kernel modules
+echo "  Building kernel modules..."
+make -j$(nproc) modules
+
+# Install modules to output directory
+echo "  Installing kernel modules..."
+mkdir -p "$OUTPUT_DIR/modules"
+make INSTALL_MOD_PATH="$OUTPUT_DIR/modules" modules_install
+
+# Find the installed module directory
+MODULE_DIR=$(find "$OUTPUT_DIR/modules/lib/modules" -maxdepth 1 -type d -name "*" | head -1)
+if [ -n "$MODULE_DIR" ]; then
+    echo "    Modules installed to: $MODULE_DIR"
+    echo "Modules: $MODULE_DIR" >> "$OUTPUT_DIR/version.txt"
+else
+    echo "    Warning: No modules installed"
+fi
+
+# Clean up intermediate files
+echo "  Cleaning up build artifacts..."
+cd "$KERNEL_DIR"
+rm -rf "linux-${KERNEL_VERSION}"
+rm -f "linux-${KERNEL_VERSION}.tar.xz"
+
+echo "[+] Custom kernel build completed successfully"
+echo "    Kernel: $OUTPUT_DIR/vmlinuz.efi ($(du -h $OUTPUT_DIR/vmlinuz.efi | cut -f1))"
+echo "    Version: Linux $KERNEL_VERSION Zero-OS"
+if [ -d "$OUTPUT_DIR/modules" ]; then
+    echo "    Modules: $OUTPUT_DIR/modules/ ($(du -sh $OUTPUT_DIR/modules | cut -f1))"
+fi
+echo "    Method: Custom compilation with embedded initramfs"
+
+# Final verification
+if [ ! -f "$OUTPUT_DIR/vmlinuz.efi" ] || [ "$(stat -c%s "$OUTPUT_DIR/vmlinuz.efi")" -eq 0 ]; then
+    echo "    Error: Final kernel verification failed" >&2
+    exit 1
+fi
+
+echo "    ✓ Kernel ready for deployment"
--- a/scripts/build-smart.sh
+++ b/scripts/build-smart.sh
@@ -0,0 +1,106 @@
+#!/bin/sh
+set -e
+
+CACHE_DIR="/build/cache"
+KERNEL_VERSION=$(cat /build/configs/kernel-version)
+
+echo "[+] Smart build with Docker layer caching..."
+
+# Function to check if we need to rebuild a stage
+needs_rebuild() {
+    local stage="$1"
+    local trigger_files="$2"
+    local cache_marker="$CACHE_DIR/${stage}-marker"
+    
+    # If cache marker doesn't exist, rebuild
+    if [ ! -f "$cache_marker" ]; then
+        echo "    $stage: No cache marker found, rebuild needed"
+        return 0
+    fi
+    
+    # Check if any trigger files are newer than cache marker
+    for file in $trigger_files; do
+        if [ -f "$file" ] && [ "$file" -nt "$cache_marker" ]; then
+            echo "    $stage: $file changed, rebuild needed"
+            return 0
+        fi
+    done
+    
+    echo "    $stage: Cache valid, skipping"
+    return 1
+}
+
+# Function to mark stage as completed
+mark_completed() {
+    local stage="$1"
+    mkdir -p "$CACHE_DIR"
+    touch "$CACHE_DIR/${stage}-marker"
+}
+
+echo "  Checking cache status..."
+
+# Check each build stage
+REBUILD_COMPONENTS=false
+REBUILD_KERNEL=false
+REBUILD_INITRAMFS=false
+
+# Components need rebuild if:
+# - Component source repos have updates (we'll assume weekly refresh)
+# - compile-components.sh script changed
+if needs_rebuild "components" "/build/scripts/compile-components.sh"; then
+    REBUILD_COMPONENTS=true
+fi
+
+# Kernel needs rebuild if:
+# - Kernel version changed
+# - Kernel config changed
+# - build-kernel.sh script changed
+if needs_rebuild "kernel" "/build/configs/kernel-version /build/configs/kernel-config-generic /build/scripts/build-kernel.sh"; then
+    REBUILD_KERNEL=true
+fi
+
+# Initramfs always rebuilds (it's fast and contains user scripts)
+REBUILD_INITRAMFS=true
+
+echo ""
+echo "  Build plan:"
+echo "    Components: $([ "$REBUILD_COMPONENTS" = "true" ] && echo "REBUILD" || echo "CACHED")"
+echo "    Kernel: $([ "$REBUILD_KERNEL" = "true" ] && echo "REBUILD" || echo "CACHED")"
+echo "    Initramfs: REBUILD (always)"
+echo ""
+
+# Phase 1: Components (if needed)
+if [ "$REBUILD_COMPONENTS" = "true" ]; then
+    echo "[+] Building Zero-OS components from source..."
+    /build/scripts/compile-components.sh
+    mark_completed "components"
+else
+    echo "[+] Using cached Zero-OS components"
+fi
+
+# Phase 2: Kernel (if needed)
+if [ "$REBUILD_KERNEL" = "true" ]; then
+    echo "[+] Building kernel ${KERNEL_VERSION}..."
+    # Only download and build kernel, not embed initramfs yet
+    /build/scripts/build-kernel.sh --kernel-only
+    mark_completed "kernel"
+else
+    echo "[+] Using cached kernel ${KERNEL_VERSION}"
+fi
+
+# Phase 3: Initramfs (always - fast)
+echo "[+] Installing Alpine packages..."
+/build/scripts/install-packages.sh
+
+echo "[+] Setting up initramfs structure..."
+/build/scripts/setup-initramfs.sh
+
+# Phase 4: Final kernel assembly (embed initramfs)
+echo "[+] Embedding initramfs into kernel..."
+/build/scripts/build-kernel.sh --embed-only
+
+echo ""
+echo "[+] Smart build completed!"
+echo "    Components: $([ "$REBUILD_COMPONENTS" = "true" ] && echo "rebuilt" || echo "cached")"
+echo "    Kernel: $([ "$REBUILD_KERNEL" = "true" ] && echo "rebuilt" || echo "cached")"
+echo "    Total time saved by caching: significant!"
--- a/scripts/compile-components.sh
+++ b/scripts/compile-components.sh
@@ -0,0 +1,196 @@
+#!/bin/sh
+set -e
+
+ALPINE_ROOT="/build/alpine"
+COMPONENTS_DIR="/build/components"
+CACHE_DIR="/build/cache/source"
+
+echo "[+] Compiling Zero-OS components from git submodules..."
+
+# Create build directories
+mkdir -p "$CACHE_DIR"
+
+# Check if submodules are available
+if [ ! -d "$COMPONENTS_DIR" ]; then
+    echo "Error: Components directory not found. Run setup-submodules.sh first."
+    exit 1
+fi
+
+# Function to prepare component for building
+prepare_component() {
+    local component_name="$1"
+    local component_dir="$COMPONENTS_DIR/$component_name"
+    
+    if [ ! -d "$component_dir" ]; then
+        echo "    Warning: $component_name submodule not found at $component_dir"
+        return 1
+    fi
+    
+    echo "    Preparing $component_name..."
+    cd "$component_dir"
+    
+    # Update submodule if needed
+    if [ -d ".git" ]; then
+        git pull origin main 2>/dev/null || git pull origin master 2>/dev/null || echo "    Using existing checkout"
+    fi
+    
+    return 0
+}
+
+# Function to build Rust project from submodule
+build_rust_component() {
+    local component_name="$1"
+    local binary_name="$2"
+    local install_path="$3"
+    
+    echo "  Building Rust component: $component_name"
+    
+    if ! prepare_component "$component_name"; then
+        echo "    Skipping $component_name (not available)"
+        return 1
+    fi
+    
+    # Build the project
+    echo "    Compiling with cargo..."
+    if command -v cargo >/dev/null; then
+        cargo build --release
+        
+        # Install binary to Alpine root
+        mkdir -p "$ALPINE_ROOT$install_path"
+        cp "target/release/$binary_name" "$ALPINE_ROOT$install_path/"
+        chmod +x "$ALPINE_ROOT$install_path/$binary_name"
+        
+        echo "    Success: $install_path/$binary_name installed to Alpine root"
+        return 0
+    else
+        echo "    Error: cargo not found - installing Rust..."
+        apk add --no-cache rust cargo
+        cargo build --release
+        
+        mkdir -p "$ALPINE_ROOT$install_path"
+        cp "target/release/$binary_name" "$ALPINE_ROOT$install_path/"
+        chmod +x "$ALPINE_ROOT$install_path/$binary_name"
+        
+        echo "    Success: $install_path/$binary_name installed to Alpine root"
+        return 0
+    fi
+}
+
+# Function to build Go project from submodule
+build_go_component() {
+    local component_name="$1"
+    local binary_name="$2"
+    local install_path="$3"
+    local build_cmd="$4"
+    
+    echo "  Building Go component: $component_name"
+    
+    if ! prepare_component "$component_name"; then
+        echo "    Skipping $component_name (not available)"
+        return 1
+    fi
+    
+    # Build the project
+    echo "    Compiling with go..."
+    if command -v go >/dev/null; then
+        if [ -n "$build_cmd" ]; then
+            eval "$build_cmd"
+        else
+            go build -o "$binary_name"
+        fi
+        
+        # Install binary to Alpine root
+        mkdir -p "$ALPINE_ROOT$install_path"
+        cp "$binary_name" "$ALPINE_ROOT$install_path/"
+        chmod +x "$ALPINE_ROOT$install_path/$binary_name"
+        
+        echo "    Success: $install_path/$binary_name installed to Alpine root"
+        return 0
+    else
+        echo "    Error: go not found - installing Go..."
+        apk add --no-cache go
+        if [ -n "$build_cmd" ]; then
+            eval "$build_cmd"
+        else
+            go build -o "$binary_name"
+        fi
+        
+        mkdir -p "$ALPINE_ROOT$install_path"
+        cp "$binary_name" "$ALPINE_ROOT$install_path/"
+        chmod +x "$ALPINE_ROOT$install_path/$binary_name"
+        
+        echo "    Success: $install_path/$binary_name installed to Alpine root"
+        return 0
+    fi
+}
+
+# Install build dependencies if needed
+echo "  Checking build dependencies..."
+if ! command -v git >/dev/null; then
+    echo "    Installing git..."
+    apk add --no-cache git
+fi
+
+echo ""
+
+# Ensure Alpine root directory exists
+if [ ! -d "$ALPINE_ROOT" ]; then
+    echo "Error: Alpine root not found at $ALPINE_ROOT"
+    echo "Make sure Alpine system is built first"
+    exit 1
+fi
+
+# Build each Zero-OS component from submodules
+echo "Building Zero-OS components from submodules:"
+
+# 1. Zinit - Init system (Go)
+if build_go_component "zinit" "zinit" "/sbin" "go build -o zinit"; then
+    echo "    Zinit built successfully"
+else
+    echo "    Warning: Failed to build zinit"
+fi
+
+# 2. RFS - Rust filesystem (Rust)
+if build_rust_component "rfs" "rfs" "/usr/bin"; then
+    echo "    RFS built successfully"
+else
+    echo "    Warning: Failed to build rfs"
+fi
+
+# 3. Seektime - Disk detection (Go)
+if build_go_component "seektime" "seektime" "/usr/bin" "go build -o seektime"; then
+    echo "    Seektime built successfully"
+else
+    echo "    Warning: Failed to build seektime"
+fi
+
+# 4. Core-X - Container control (Go)
+if build_go_component "core-x" "core-x" "/usr/bin" "go build -o core-x"; then
+    echo "    Core-X built successfully"
+else
+    echo "    Warning: Failed to build core-x"
+fi
+
+# 5. Mycelium - Networking layer (Rust)
+if build_rust_component "mycelium" "mycelium" "/usr/bin"; then
+    echo "    Mycelium built successfully"
+else
+    echo "    Warning: Failed to build mycelium"
+fi
+
+echo ""
+echo "[+] Zero-OS component compilation completed"
+
+# Show installed binaries info
+echo ""
+echo "[+] Compiled Zero-OS components in Alpine root:"
+for binary in "/sbin/zinit" "/usr/bin/rfs" "/usr/bin/seektime" "/usr/bin/core-x" "/usr/bin/mycelium"; do
+    if [ -x "$ALPINE_ROOT$binary" ]; then
+        size=$(stat -c%s "$ALPINE_ROOT$binary" 2>/dev/null || echo "unknown")
+        echo "  $binary (${size} bytes)"
+    else
+        echo "  $binary (NOT BUILT)"
+    fi
+done
+
+echo "[+] Zero-OS binaries installed to Alpine root filesystem"
--- a/scripts/fetch-github.sh
+++ b/scripts/fetch-github.sh
@@ -0,0 +1,215 @@
+#!/bin/sh
+set -e
+
+GITHUB_DIR="/build/github"
+INITRAMFS_ROOT="/build/initramfs"
+CACHE_TIMEOUT=3600  # 1 hour cache
+
+echo "[+] Fetching GitHub components..."
+
+# DIAGNOSTIC: Check GitHub connectivity and cache
+echo "[DEBUG] Checking GitHub connectivity..."
+echo "[DEBUG] Cache directory: $GITHUB_DIR"
+echo "[DEBUG] Existing cache files: $(ls -la $GITHUB_DIR 2>/dev/null | wc -l)"
+echo "[DEBUG] GitHub API rate limit check..."
+github_status=$(curl -s -I https://api.github.com/repos/threefoldtech/zinit/releases/latest | head -1 | awk '{print $2}')
+echo "[DEBUG] GitHub API response code: $github_status"
+if [ "$github_status" != "200" ]; then
+    echo "[DEBUG] WARNING: GitHub API may be inaccessible - code: $github_status"
+fi
+echo "[DEBUG] Available tools: curl=$(command -v curl >/dev/null && echo 'YES' || echo 'NO'), wget=$(command -v wget >/dev/null && echo 'YES' || echo 'NO')"
+
+# Create cache directory
+mkdir -p "$GITHUB_DIR"
+
+# Function to get latest release info
+get_latest_release() {
+    local repo="$1"
+    local cache_file="$GITHUB_DIR/${repo//\//_}_release.json"
+    
+    # Check cache first
+    if [ -f "$cache_file" ] && [ $(($(date +%s) - $(stat -c %Y "$cache_file"))) -lt $CACHE_TIMEOUT ]; then
+        cat "$cache_file"
+        return
+    fi
+    
+    # Fetch latest release info
+    local api_url="https://api.github.com/repos/$repo/releases/latest"
+    echo "    Fetching release info for $repo..." >&2
+    
+    if command -v curl >/dev/null; then
+        curl -s "$api_url" | tee "$cache_file"
+    else
+        wget -qO- "$api_url" | tee "$cache_file"
+    fi
+}
+
+# Function to extract download URL from release JSON
+get_download_url() {
+    local release_json="$1"
+    local pattern="$2"
+    
+    echo "$release_json" | grep -o '"browser_download_url": *"[^"]*"' | \
+        grep "$pattern" | head -1 | cut -d '"' -f 4
+}
+
+# Function to download with retry
+download_with_retry() {
+    local url="$1"
+    local output="$2"
+    local max_attempts=3
+    local attempt=1
+    
+    while [ $attempt -le $max_attempts ]; do
+        echo "    Attempt $attempt/$max_attempts..."
+        
+        if command -v curl >/dev/null; then
+            if curl -L --fail -o "$output" "$url"; then
+                return 0
+            fi
+        else
+            if wget -O "$output" "$url"; then
+                return 0
+            fi
+        fi
+        
+        attempt=$((attempt + 1))
+        if [ $attempt -le $max_attempts ]; then
+            echo "    Retrying in 5 seconds..."
+            sleep 5
+        fi
+    done
+    
+    echo "    Error: Failed to download after $max_attempts attempts" >&2
+    return 1
+}
+
+# Function to download and install binary
+install_github_binary() {
+    local repo="$1"
+    local binary_name="$2"
+    local install_path="$3"
+    local download_pattern="$4"
+    
+    echo "  Installing: $repo -> $install_path/$binary_name"
+    
+    # Get release information
+    local release_json=$(get_latest_release "$repo")
+    if [ -z "$release_json" ]; then
+        echo "    Error: Failed to get release info for $repo" >&2
+        echo "[DEBUG] GitHub API call failed for $repo - check network/rate limits"
+        return 1
+    fi
+    
+    # Check if this is a "Not Found" response
+    if echo "$release_json" | grep -q '"message": *"Not Found"'; then
+        echo "    Error: Repository $repo not found or has no releases" >&2
+        echo "[DEBUG] Repository $repo does not exist or has no releases"
+        return 1
+    fi
+    
+    echo "[DEBUG] Successfully fetched release info for $repo"
+    
+    # Extract version for logging
+    local version=$(echo "$release_json" | grep '"tag_name"' | cut -d '"' -f 4)
+    echo "    Version: $version"
+    
+    # Get download URL
+    local download_url=$(get_download_url "$release_json" "$download_pattern")
+    if [ -z "$download_url" ]; then
+        echo "    Error: No matching release found for pattern: $download_pattern" >&2
+        return 1
+    fi
+    
+    echo "    Downloading: $(basename "$download_url")"
+    local filename=$(basename "$download_url")
+    local download_path="$GITHUB_DIR/$filename"
+    
+    # Download if not cached
+    if [ ! -f "$download_path" ]; then
+        download_with_retry "$download_url" "$download_path"
+    else
+        echo "    Using cached file"
+    fi
+    
+    # Create install directory
+    mkdir -p "$INITRAMFS_ROOT$install_path"
+    
+    # Extract and install based on file type
+    case "$filename" in
+        *.tar.gz|*.tgz)
+            echo "    Extracting tar.gz..."
+            tar -xzf "$download_path" -C "$GITHUB_DIR"
+            # Find the binary in extracted files
+            local extracted_binary=$(find "$GITHUB_DIR" -name "$binary_name" -type f -executable | head -1)
+            if [ -n "$extracted_binary" ]; then
+                cp "$extracted_binary" "$INITRAMFS_ROOT$install_path/$binary_name"
+            else
+                echo "    Error: Binary '$binary_name' not found in archive" >&2
+                return 1
+            fi
+            ;;
+        *.zip)
+            echo "    Extracting zip..."
+            unzip -q "$download_path" -d "$GITHUB_DIR"
+            local extracted_binary=$(find "$GITHUB_DIR" -name "$binary_name" -type f -executable | head -1)
+            if [ -n "$extracted_binary" ]; then
+                cp "$extracted_binary" "$INITRAMFS_ROOT$install_path/$binary_name"
+            else
+                echo "    Error: Binary '$binary_name' not found in archive" >&2
+                return 1
+            fi
+            ;;
+        *)
+            # Assume it's a direct binary
+            echo "    Installing direct binary..."
+            cp "$download_path" "$INITRAMFS_ROOT$install_path/$binary_name"
+            ;;
+    esac
+    
+    # Make executable
+    chmod +x "$INITRAMFS_ROOT$install_path/$binary_name"
+    
+    # Verify installation
+    if [ -x "$INITRAMFS_ROOT$install_path/$binary_name" ]; then
+        echo "    Success: $install_path/$binary_name installed"
+    else
+        echo "    Error: Failed to install $binary_name" >&2
+        return 1
+    fi
+}
+
+# Install each component
+echo ""
+
+# Zinit - Init system
+install_github_binary "threefoldtech/zinit" "zinit" "/sbin" "linux-x86_64"
+
+# Core-X - Container control (skip if repo doesn't exist)
+echo "  Checking: threefoldtech/core-x"
+if install_github_binary "threefoldtech/core-x" "core-x" "/usr/bin" "linux.*amd64"; then
+    echo "    Core-X installed successfully"
+else
+    echo "    Warning: Core-X repository not found or no releases available - continuing without it"
+fi
+
+# Seektime - Disk detection
+install_github_binary "threefoldtech/seektime" "seektime" "/usr/bin" "linux-amd64"
+
+# RFS - Rust filesystem (direct binary, no architecture in name)
+install_github_binary "threefoldtech/rfs" "rfs" "/usr/bin" "rfs"
+
+echo ""
+echo "[+] GitHub components installed successfully"
+
+# Show installed binaries info
+echo ""
+echo "[+] Installed components:"
+for binary in "/sbin/zinit" "/usr/bin/core-x" "/usr/bin/seektime" "/usr/bin/rfs"; do
+    if [ -x "$INITRAMFS_ROOT$binary" ]; then
+        size=$(stat -c%s "$INITRAMFS_ROOT$binary" 2>/dev/null || echo "unknown")
+        echo "  $binary (${size} bytes)"
+    else
+        echo "  $binary (MISSING)"
+    fi
+done
--- a/scripts/install-firmware-minimal.sh
+++ b/scripts/install-firmware-minimal.sh
@@ -0,0 +1,115 @@
+#!/bin/sh
+set -e
+
+INITRAMFS_ROOT="/build/initramfs"
+FIRMWARE_DIR="$INITRAMFS_ROOT/lib/firmware"
+
+echo "[+] Installing minimal network firmware (not full 600MB package)..."
+
+# Create firmware directory
+mkdir -p "$FIRMWARE_DIR"
+
+# Install full linux-firmware temporarily to extract essentials
+echo "  Downloading linux-firmware package..."
+cd /tmp
+apk fetch linux-firmware
+tar -xf linux-firmware-*.apk
+
+# Extract only essential network firmware
+echo "  Extracting essential network drivers..."
+
+# Intel Ethernet (most common)
+if [ -d lib/firmware/intel ]; then
+    mkdir -p "$FIRMWARE_DIR/intel"
+    # e1000e, ixgbe, i40e, ice drivers
+    cp -r lib/firmware/intel/*e1000* "$FIRMWARE_DIR/intel/" 2>/dev/null || true
+    cp -r lib/firmware/intel/*ixgbe* "$FIRMWARE_DIR/intel/" 2>/dev/null || true
+    cp -r lib/firmware/intel/*i40e* "$FIRMWARE_DIR/intel/" 2>/dev/null || true
+    cp -r lib/firmware/intel/*ice* "$FIRMWARE_DIR/intel/" 2>/dev/null || true
+    echo "    Intel ethernet firmware: $(du -sh $FIRMWARE_DIR/intel 2>/dev/null | cut -f1)"
+fi
+
+# Realtek Ethernet
+if [ -d lib/firmware/rtl_nic ]; then
+    mkdir -p "$FIRMWARE_DIR/rtl_nic"
+    # r8169 driver
+    cp -r lib/firmware/rtl_nic/* "$FIRMWARE_DIR/rtl_nic/" 2>/dev/null || true
+    echo "    Realtek ethernet firmware: $(du -sh $FIRMWARE_DIR/rtl_nic 2>/dev/null | cut -f1)"
+fi
+
+# Broadcom Ethernet  
+if [ -d lib/firmware/bnx2 ]; then
+    mkdir -p "$FIRMWARE_DIR/bnx2"
+    cp -r lib/firmware/bnx2/* "$FIRMWARE_DIR/bnx2/" 2>/dev/null || true
+fi
+if [ -d lib/firmware/tigon ]; then
+    mkdir -p "$FIRMWARE_DIR/tigon"
+    cp -r lib/firmware/tigon/* "$FIRMWARE_DIR/tigon/" 2>/dev/null || true
+fi
+
+# Essential system firmware
+if [ -d lib/firmware/regulatory.db ]; then
+    cp lib/firmware/regulatory.db* "$FIRMWARE_DIR/" 2>/dev/null || true
+fi
+
+# Cleanup temporary files
+cd /build
+rm -rf /tmp/lib /tmp/linux-firmware-*
+
+# Show firmware size
+if [ -d "$FIRMWARE_DIR" ]; then
+    total_size=$(du -sh "$FIRMWARE_DIR" 2>/dev/null | cut -f1)
+    echo "[+] Essential firmware installed: $total_size (vs 600MB full package)"
+else
+    echo "[-] Warning: No firmware installed"
+fi
+
+# Install essential ethernet kernel modules
+echo "  Installing essential ethernet kernel modules..."
+KERNEL_VERSION=$(cat /build/configs/kernel-version)
+MODULES_DIR="$INITRAMFS_ROOT/lib/modules/${KERNEL_VERSION}-Zero-OS"
+mkdir -p "$MODULES_DIR/kernel/drivers/net/ethernet"
+
+# Copy essential ethernet driver modules from the built kernel
+KERNEL_BUILD_DIR="/build/kernel/linux-${KERNEL_VERSION}"
+if [ -d "$KERNEL_BUILD_DIR" ]; then
+    echo "    Copying ethernet drivers from kernel build..."
+    
+    # Intel drivers (e1000, e1000e, igb, ixgbe, i40e, ice)
+    find "$KERNEL_BUILD_DIR" -name "e1000.ko" -exec cp {} "$MODULES_DIR/kernel/drivers/net/ethernet/" \; 2>/dev/null || true
+    find "$KERNEL_BUILD_DIR" -name "e1000e.ko" -exec cp {} "$MODULES_DIR/kernel/drivers/net/ethernet/" \; 2>/dev/null || true
+    find "$KERNEL_BUILD_DIR" -name "igb.ko" -exec cp {} "$MODULES_DIR/kernel/drivers/net/ethernet/" \; 2>/dev/null || true
+    find "$KERNEL_BUILD_DIR" -name "ixgbe.ko" -exec cp {} "$MODULES_DIR/kernel/drivers/net/ethernet/" \; 2>/dev/null || true
+    find "$KERNEL_BUILD_DIR" -name "i40e.ko" -exec cp {} "$MODULES_DIR/kernel/drivers/net/ethernet/" \; 2>/dev/null || true
+    find "$KERNEL_BUILD_DIR" -name "ice.ko" -exec cp {} "$MODULES_DIR/kernel/drivers/net/ethernet/" \; 2>/dev/null || true
+    
+    # Realtek drivers (r8169, 8139too)
+    find "$KERNEL_BUILD_DIR" -name "r8169.ko" -exec cp {} "$MODULES_DIR/kernel/drivers/net/ethernet/" \; 2>/dev/null || true
+    find "$KERNEL_BUILD_DIR" -name "8139too.ko" -exec cp {} "$MODULES_DIR/kernel/drivers/net/ethernet/" \; 2>/dev/null || true
+    
+    # Broadcom drivers (bnx2, tg3, b44)
+    find "$KERNEL_BUILD_DIR" -name "bnx2.ko" -exec cp {} "$MODULES_DIR/kernel/drivers/net/ethernet/" \; 2>/dev/null || true
+    find "$KERNEL_BUILD_DIR" -name "tg3.ko" -exec cp {} "$MODULES_DIR/kernel/drivers/net/ethernet/" \; 2>/dev/null || true
+    find "$KERNEL_BUILD_DIR" -name "b44.ko" -exec cp {} "$MODULES_DIR/kernel/drivers/net/ethernet/" \; 2>/dev/null || true
+    
+    # Common dependencies (mii, mdio)
+    find "$KERNEL_BUILD_DIR" -name "mii.ko" -exec cp {} "$MODULES_DIR/kernel/drivers/net/" \; 2>/dev/null || true
+    find "$KERNEL_BUILD_DIR" -name "mdio.ko" -exec cp {} "$MODULES_DIR/kernel/drivers/net/" \; 2>/dev/null || true
+    
+    # Create modules.dep for module loading
+    if command -v depmod >/dev/null 2>&1; then
+        depmod -b "$INITRAMFS_ROOT" "${KERNEL_VERSION}-Zero-OS" 2>/dev/null || true
+    fi
+    
+    module_count=$(find "$MODULES_DIR" -name "*.ko" | wc -l)
+    echo "    Installed $module_count ethernet driver modules"
+else
+    echo "    Warning: Kernel build directory not found, modules may not be available"
+fi
+
+# Create essential kernel module directories that eudev expects
+mkdir -p "$INITRAMFS_ROOT/lib/modules"
+mkdir -p "$INITRAMFS_ROOT/sys/module"
+mkdir -p "$INITRAMFS_ROOT/dev"
+
+echo "[+] Minimal firmware and driver installation complete"
--- a/scripts/install-packages.sh
+++ b/scripts/install-packages.sh
@@ -0,0 +1,200 @@
+#!/bin/sh
+set -e
+
+INITRAMFS_ROOT="/build/initramfs"
+
+# Determine which package list to use
+if [ "$1" = "minimal" ] || [ "$MINIMAL_MODE" = "true" ] || [ -f "/build/configs/packages-minimal.txt" -a ! -f "/build/configs/packages.txt" ]; then
+    PACKAGES_FILE="/build/configs/packages-minimal.txt"
+    MINIMAL_MODE=true
+    echo "[+] Creating MINIMAL initramfs root directory (embedded cpio)..."
+else
+    PACKAGES_FILE="/build/configs/packages.txt"
+    MINIMAL_MODE=false
+    echo "[+] Creating FULL initramfs root directory..."
+fi
+rm -rf "$INITRAMFS_ROOT"
+mkdir -p "$INITRAMFS_ROOT"
+
+echo "[+] Setting up Alpine repositories..."
+echo "[DEBUG] Checking APK setup..."
+echo "[DEBUG] Host repositories: $(cat /etc/apk/repositories | grep -v '^#' | wc -l) active repos"
+echo "[DEBUG] Host APK keys: $(ls -la /etc/apk/keys 2>/dev/null | wc -l) keys"
+echo "[DEBUG] Network connectivity to Alpine repos..."
+apk_test=$(apk update --quiet 2>&1 && echo 'OK' || echo 'FAILED')
+echo "[DEBUG] APK repository access: $apk_test"
+
+# Create the repository configuration and copy APK keys
+mkdir -p "$INITRAMFS_ROOT/etc/apk"
+cp /etc/apk/repositories "$INITRAMFS_ROOT/etc/apk/"
+
+# Copy APK keys to avoid UNTRUSTED signature warnings
+if [ -d /etc/apk/keys ]; then
+    mkdir -p "$INITRAMFS_ROOT/etc/apk/keys"
+    cp /etc/apk/keys/* "$INITRAMFS_ROOT/etc/apk/keys/"
+fi
+
+echo "[+] Installing Alpine base system..."
+# Create APK database directory and initialize
+mkdir -p "$INITRAMFS_ROOT/lib/apk/db"
+mkdir -p "$INITRAMFS_ROOT/var/cache/apk"
+
+# Initialize the database first with --clean-protected for new root
+apk --root "$INITRAMFS_ROOT" --clean-protected --update-cache --initdb add alpine-baselayout busybox apk-tools musl
+
+echo "[+] Installing Zero-OS packages..."
+while read -r package; do
+    # Skip comments and empty lines
+    case "$package" in
+        \#*|"") continue ;;
+    esac
+    
+    echo "  Installing: $package"
+    if apk --root "$INITRAMFS_ROOT" add --no-cache "$package"; then
+        echo "[DEBUG] Successfully installed: $package"
+    else
+        echo "    Warning: Failed to install $package (continuing)"
+        echo "[DEBUG] Package installation failed: $package - check if package exists in repos"
+    fi
+done < "$PACKAGES_FILE"
+
+# For minimal mode, install selective firmware instead of full linux-firmware package
+if [ "$MINIMAL_MODE" = "true" ]; then
+    echo "[+] Installing minimal firmware (essential network drivers only)..."
+    /build/scripts/install-firmware-minimal.sh
+else
+    echo "[+] Full mode: linux-firmware package already installed"
+fi
+
+echo "[+] Setting up initramfs filesystem structure..."
+
+# Create essential directories
+mkdir -p "$INITRAMFS_ROOT"/{dev,proc,sys,mnt,tmp,var/run,var/log,var/lock}
+mkdir -p "$INITRAMFS_ROOT"/{root,home,opt}
+mkdir -p "$INITRAMFS_ROOT"/mnt/root
+mkdir -p "$INITRAMFS_ROOT"/var/cache/containers
+
+# Create device nodes (minimal set) - check if they exist first
+echo "  Creating device nodes..."
+[ ! -e "$INITRAMFS_ROOT/dev/console" ] && mknod "$INITRAMFS_ROOT/dev/console" c 5 1
+[ ! -e "$INITRAMFS_ROOT/dev/null" ] && mknod "$INITRAMFS_ROOT/dev/null" c 1 3
+[ ! -e "$INITRAMFS_ROOT/dev/zero" ] && mknod "$INITRAMFS_ROOT/dev/zero" c 1 5
+[ ! -e "$INITRAMFS_ROOT/dev/random" ] && mknod "$INITRAMFS_ROOT/dev/random" c 1 8
+[ ! -e "$INITRAMFS_ROOT/dev/urandom" ] && mknod "$INITRAMFS_ROOT/dev/urandom" c 1 9
+
+# Set proper permissions
+chmod 666 "$INITRAMFS_ROOT/dev/null" "$INITRAMFS_ROOT/dev/zero"
+chmod 600 "$INITRAMFS_ROOT/dev/console"
+chmod 644 "$INITRAMFS_ROOT/dev/random" "$INITRAMFS_ROOT/dev/urandom"
+
+# Create symlinks (similar to current system)
+echo "  Creating symlinks..."
+cd "$INITRAMFS_ROOT"
+ln -sf usr/lib lib || true
+ln -sf usr/lib lib64 || true
+ln -sf var/run run || true
+
+# Ensure minimal login logs
+touch "$INITRAMFS_ROOT"/var/log/lastlog
+touch "$INITRAMFS_ROOT"/var/log/wtmp
+
+# Legacy mtab symlink
+cd "$INITRAMFS_ROOT/etc"
+ln -sf /proc/mounts mtab || true
+
+echo "[+] Cleaning up unnecessary files..."
+cd "$INITRAMFS_ROOT"
+
+# Remove package cache and docs
+rm -rf var/cache/apk/*
+rm -rf usr/share/doc
+rm -rf usr/share/man
+rm -rf usr/share/info
+rm -rf usr/share/locale
+rm -rf usr/include
+rm -rf usr/lib/pkgconfig
+
+# Remove development files
+rm -rf lib/*.a usr/lib/*.a
+rm -rf lib/*.la usr/lib/*.la
+
+# Aggressive cleanup for minimal mode
+if [ "$MINIMAL_MODE" = "true" ]; then
+    echo "  Applying aggressive size optimizations for embedded cpio..."
+    
+    # Remove ALL documentation and help files
+    rm -rf usr/share/doc usr/share/man usr/share/info
+    rm -rf usr/share/help usr/share/gtk-doc usr/share/licenses
+    rm -rf usr/share/LICENSES usr/share/COPYING*
+    
+    # Remove ALL locale and internationalization
+    rm -rf usr/share/locale usr/share/i18n
+    rm -rf usr/lib/locale usr/lib/gconv
+    
+    # Remove timezone data (embedded systems often use UTC)
+    rm -rf usr/share/zoneinfo/* 2>/dev/null || true
+    
+    # Remove terminfo except bare essentials (vt100, linux, xterm)
+    rm -rf usr/share/terminfo/[b-df-km-uw-z]* 2>/dev/null || true
+    rm -rf usr/share/terminfo/[A-Z]* 2>/dev/null || true
+    rm -rf usr/share/terminfo/1 usr/share/terminfo/2 usr/share/terminfo/3 2>/dev/null || true
+    
+    # Remove graphics/desktop files (embedded has no GUI)
+    rm -rf usr/share/pixmaps usr/share/icons usr/share/applications
+    rm -rf usr/share/mime usr/share/desktop-directories
+    
+    # Remove development headers and static libraries
+    rm -rf usr/include usr/lib/pkgconfig usr/share/pkgconfig
+    rm -rf lib/*.a usr/lib/*.a lib/*.la usr/lib/*.la
+    
+    # Remove Python cache and compiled modules
+    rm -rf usr/lib/python*/site-packages/__pycache__
+    rm -rf usr/lib/python*/__pycache__ usr/lib/python*/test
+    rm -rf usr/lib/python*/tkinter usr/lib/python*/turtle*
+    find usr/lib/python* -name "*.pyc" -delete 2>/dev/null || true
+    find usr/lib/python* -name "*.pyo" -delete 2>/dev/null || true
+    
+    # Remove unnecessary logs, cache, and temporary files
+    rm -rf var/log/* var/cache/* tmp/* var/tmp/*
+    rm -rf var/lib/apk/db/installed var/lib/apk/db/lock
+    rm -rf etc/apk/cache/* 2>/dev/null || true
+    
+    # Remove unneeded kernel modules (we only need firmware)
+    rm -rf lib/modules/* 2>/dev/null || true
+    
+    # Strip binaries aggressively to reduce size
+    echo "    Stripping binaries..."
+    find . -type f -perm -111 -exec strip --strip-unneeded {} \; 2>/dev/null || true
+    find . -name "*.so*" -exec strip --strip-unneeded {} \; 2>/dev/null || true
+    
+    # Remove backup files and editor artifacts
+    find . -name "*~" -delete 2>/dev/null || true
+    find . -name "*.orig" -delete 2>/dev/null || true
+    find . -name "*.rej" -delete 2>/dev/null || true
+    
+    # Show final firmware size
+    echo "    Minimal firmware size: $(du -sh lib/firmware 2>/dev/null | cut -f1 || echo 'N/A')"
+    echo "    Total size after aggressive cleanup: $(du -sh . | cut -f1)"
+fi
+
+echo "[+] Setting up Alpine-specific configurations..."
+
+# Ensure terminfo is available (needed for various tools)
+if [ -d /usr/share/terminfo ]; then
+    cp -r /usr/share/terminfo "$INITRAMFS_ROOT/usr/share/" || true
+fi
+
+# Copy timezone data
+if [ -d /usr/share/zoneinfo ]; then
+    mkdir -p "$INITRAMFS_ROOT/usr/share"
+    cp -r /usr/share/zoneinfo "$INITRAMFS_ROOT/usr/share/" || true
+fi
+
+echo "[+] Alpine packages installed successfully"
+echo "    Initramfs root: $INITRAMFS_ROOT"
+
+# Show size
+if command -v du >/dev/null; then
+    size=$(du -sh "$INITRAMFS_ROOT" | cut -f1)
+    echo "    Size: $size"
+fi
--- a/scripts/setup-initramfs.sh
+++ b/scripts/setup-initramfs.sh
@@ -0,0 +1,172 @@
+#!/bin/sh
+set -e
+
+INITRAMFS_ROOT="/build/initramfs"
+CONFIG_DIR="/build/configs"
+OUTPUT_DIR="/build/output"
+
+echo "[+] Setting up initramfs structure..."
+
+# Copy init script
+echo "  Installing init script..."
+cp "$CONFIG_DIR/init" "$INITRAMFS_ROOT/init"
+chmod +x "$INITRAMFS_ROOT/init"
+
+# Copy zinit configuration (mounted from existing config)
+echo "  Installing zinit configuration..."
+echo "[DEBUG] Checking zinit config sources..."
+echo "[DEBUG] /mnt/zinit exists: $([ -d "/mnt/zinit" ] && echo 'YES' || echo 'NO')"
+echo "[DEBUG] /mnt/zinit contents: $(ls -la /mnt/zinit 2>/dev/null | wc -l) files"
+echo "[DEBUG] $CONFIG_DIR/zinit exists: $([ -d "$CONFIG_DIR/zinit" ] && echo 'YES' || echo 'NO')"
+echo "[DEBUG] $CONFIG_DIR/zinit contents: $(ls -la $CONFIG_DIR/zinit 2>/dev/null | wc -l) files"
+
+mkdir -p "$INITRAMFS_ROOT/etc/zinit"
+if [ -d "/mnt/zinit" ]; then
+    cp -r "/mnt/zinit/"* "$INITRAMFS_ROOT/etc/zinit/"
+    echo "    Copied zinit configs from /mnt/zinit"
+    echo "[DEBUG] Copied $(ls -la $INITRAMFS_ROOT/etc/zinit 2>/dev/null | wc -l) zinit config files"
+elif [ -d "$CONFIG_DIR/zinit" ]; then
+    cp -r "$CONFIG_DIR/zinit/"* "$INITRAMFS_ROOT/etc/zinit/"
+    echo "    Copied zinit configs from $CONFIG_DIR/zinit"
+    echo "[DEBUG] Copied $(ls -la $INITRAMFS_ROOT/etc/zinit 2>/dev/null | wc -l) zinit config files"
+else
+    echo "    Warning: zinit config directory not found"
+    echo "[DEBUG] ERROR: No zinit config source available - this will likely cause runtime failures"
+fi
+
+# Create debug script for compatibility
+echo "  Creating debug script..."
+cat > "$INITRAMFS_ROOT/init-debug" << 'EOF'
+#!/bin/sh
+# Debug file injection script (Alpine version)
+echo "[+] debug mode enabled"
+
+# Check for debug device (same as original)
+if [ -b /dev/sda1 ]; then
+    echo "  debug device found: /dev/sda1"
+    
+    # Create temporary mount point
+    mkdir -p /mnt/debug
+    
+    # Try to mount as vfat (same as original)
+    if mount -t vfat -o ro /dev/sda1 /mnt/debug 2>/dev/null; then
+        echo "  mounted debug device"
+        
+        # Check for debug marker file
+        if [ -f /mnt/debug/.zero-os-debug ]; then
+            echo "  debug marker found, copying files..."
+            
+            # Copy all files from debug device to tmpfs root
+            target="/mnt/root"
+            if [ -d "$target" ]; then
+                cp -rv /mnt/debug/* "$target/" 2>/dev/null || true
+                echo "  debug files copied to tmpfs"
+            else
+                echo "  warning: tmpfs root not ready yet"
+            fi
+        else
+            echo "  no debug marker (.zero-os-debug) found"
+        fi
+        
+        # Unmount debug device
+        umount /mnt/debug 2>/dev/null || true
+    else
+        echo "  failed to mount debug device"
+    fi
+    
+    # Cleanup
+    rmdir /mnt/debug 2>/dev/null || true
+else
+    echo "  no debug device found"
+fi
+
+echo "[+] debug initialization complete"
+EOF
+
+chmod +x "$INITRAMFS_ROOT/init-debug"
+
+# Copy other system configurations
+echo "  Setting up system configuration..."
+
+# Ensure proper hostname
+echo "zero-os" > "$INITRAMFS_ROOT/etc/hostname"
+
+# Basic hosts file
+cat > "$INITRAMFS_ROOT/etc/hosts" << EOF
+127.0.0.1	localhost zero-os
+::1		localhost zero-os
+EOF
+
+# Minimal passwd file (compatible with existing)
+if [ ! -f "$INITRAMFS_ROOT/etc/passwd" ]; then
+    cat > "$INITRAMFS_ROOT/etc/passwd" << EOF
+root:x:0:0:root:/root:/bin/sh
+EOF
+fi
+
+# Minimal group file
+if [ ! -f "$INITRAMFS_ROOT/etc/group" ]; then
+    cat > "$INITRAMFS_ROOT/etc/group" << EOF
+root:x:0:
+EOF
+fi
+
+# Set up profile for environment
+cat > "$INITRAMFS_ROOT/etc/profile" << EOF
+export PATH=/sbin:/bin:/usr/sbin:/usr/bin
+export HOME=/root
+export TERM=linux
+EOF
+
+# Ensure SSH directory exists
+mkdir -p "$INITRAMFS_ROOT/etc/ssh"
+mkdir -p "$INITRAMFS_ROOT/root/.ssh"
+
+# Set proper permissions
+chmod 700 "$INITRAMFS_ROOT/root"
+chmod 700 "$INITRAMFS_ROOT/root/.ssh" 2>/dev/null || true
+
+# Create necessary run directories
+mkdir -p "$INITRAMFS_ROOT/run"
+mkdir -p "$INITRAMFS_ROOT/var"
+
+# Ensure terminfo is available for better terminal support
+if [ -d "$INITRAMFS_ROOT/usr/share/terminfo" ]; then
+    echo "  terminfo available"
+else
+    echo "  warning: terminfo not found"
+fi
+
+# Set up symlinks (similar to current system)
+echo "  Setting up symlinks..."
+cd "$INITRAMFS_ROOT"
+
+# Ensure lib symlinks
+ln -sf usr/lib lib || true
+ln -sf usr/lib lib64 || true
+
+# Ensure var/run symlink (standard Linux practice: /var/run -> /run)
+cd "$INITRAMFS_ROOT/var"
+rm -rf run
+ln -sf ../run run || true
+cd "$INITRAMFS_ROOT"
+
+# Create initramfs archive
+echo "[+] Creating initramfs archive..."
+cd "$INITRAMFS_ROOT"
+
+# Create the cpio archive
+find . | cpio -H newc -o | xz --check=crc32 --x86 --lzma2=dict=1MiB > "$OUTPUT_DIR/initramfs.cpio.xz"
+
+if [ -f "$OUTPUT_DIR/initramfs.cpio.xz" ]; then
+    size=$(stat -c%s "$OUTPUT_DIR/initramfs.cpio.xz")
+    echo "[+] Initramfs created: $OUTPUT_DIR/initramfs.cpio.xz ($size bytes)"
+else
+    echo "[-] Error: Failed to create initramfs archive"
+    exit 1
+fi
+
+# Also create uncompressed version for debugging
+find . | cpio -H newc -o > "$OUTPUT_DIR/initramfs.cpio"
+
+echo "[+] Initramfs setup completed successfully"
--- a/scripts/setup-permissions.sh
+++ b/scripts/setup-permissions.sh
@@ -0,0 +1,7 @@
+#!/bin/sh
+# Ensure all scripts are executable
+
+chmod +x /build/scripts/*.sh
+
+echo "Script permissions updated:"
+ls -la /build/scripts/*.sh | grep -E '\.(sh)$'
--- a/scripts/setup-submodules.sh
+++ b/scripts/setup-submodules.sh
@@ -0,0 +1,62 @@
+#!/bin/sh
+set -e
+
+echo "[+] Setting up Zero-OS component submodules..."
+
+# Check if we're in git repository
+if [ ! -d ".git" ]; then
+    echo "Error: Not in a git repository. Please run 'git init' first."
+    exit 1
+fi
+
+# Create components directory
+mkdir -p components
+
+# Add Zero-OS components as git submodules
+echo "  Adding zinit (init system)..."
+if [ ! -d "components/zinit" ]; then
+    git submodule add https://github.com/threefoldtech/zinit.git components/zinit
+else
+    echo "    zinit submodule already exists"
+fi
+
+echo "  Adding seektime (disk detection)..."
+if [ ! -d "components/seektime" ]; then
+    git submodule add https://github.com/threefoldtech/seektime.git components/seektime
+else
+    echo "    seektime submodule already exists"
+fi
+
+echo "  Adding core-x (container control)..."
+if [ ! -d "components/core-x" ]; then
+    git submodule add https://github.com/threefoldtech/core-x.git components/core-x
+else
+    echo "    core-x submodule already exists"
+fi
+
+echo "  Adding mycelium (networking layer)..."
+if [ ! -d "components/mycelium" ]; then
+    git submodule add https://github.com/threefoldtech/mycelium.git components/mycelium
+else
+    echo "    mycelium submodule already exists"
+fi
+
+echo "  Adding rfs (rust filesystem)..."
+if [ ! -d "components/rfs" ]; then
+    git submodule add https://github.com/threefoldtech/rfs.git components/rfs
+else
+    echo "    rfs submodule already exists"
+fi
+
+# Initialize and update submodules
+echo "  Initializing submodules..."
+git submodule init
+git submodule update
+
+echo "[+] Zero-OS component submodules setup complete"
+echo ""
+echo "Submodules added:"
+ls -la components/
+echo ""
+echo "To update submodules later, run:"
+echo "  git submodule update --remote"
--- a/test-initramfs.sh
+++ b/test-initramfs.sh
@@ -0,0 +1,73 @@
+#!/bin/bash
+set -e
+
+echo "[+] Quick initramfs rebuild test..."
+
+# Run just the initramfs setup in the existing container
+docker run --rm \
+    -v "$(pwd)/scripts:/build/scripts" \
+    -v "$(pwd)/configs:/build/configs" \
+    -v "$(pwd)/output:/build/output" \
+    -v "$(pwd)/configs/zinit:/mnt/zinit" \
+    zero-os-alpine-builder:latest \
+    /bin/sh -c "
+        echo '[+] Setting up build environment...'
+        source /build/build.conf
+        
+        # Only run the Alpine package installation and initramfs setup
+        echo '[+] Installing packages...'
+        /build/scripts/install-packages.sh
+        
+        echo '[+] Setting up initramfs...'
+        /build/scripts/setup-initramfs.sh
+        
+        echo '[+] Quick initramfs rebuild complete!'
+        ls -la /build/output/initramfs.*
+    "
+
+echo "[+] Testing initramfs structure..."
+echo "Checking for symlink loops in the initramfs..."
+
+# Extract and examine the initramfs structure
+cd output
+if [ -f "initramfs.cpio" ]; then
+    mkdir -p test-extract
+    cd test-extract
+    cpio -idmv < ../initramfs.cpio >/dev/null 2>&1
+    
+    echo "=== Checking /run and /var/run structure ==="
+    if [ -L "run" ]; then
+        echo "/run is a symlink to: $(readlink run)"
+    elif [ -d "run" ]; then
+        echo "/run is a directory"
+    else
+        echo "/run does not exist"
+    fi
+    
+    if [ -L "var/run" ]; then
+        echo "/var/run is a symlink to: $(readlink var/run)"
+    elif [ -d "var/run" ]; then
+        echo "/var/run is a directory"
+    else
+        echo "/var/run does not exist"
+    fi
+    
+    # Check for circular symlinks
+    echo "=== Checking for symlink loops ==="
+    if [ -L "run" ] && [ -L "var/run" ]; then
+        run_target=$(readlink run)
+        var_run_target=$(readlink var/run)
+        echo "Symlinks: /run -> $run_target, /var/run -> $var_run_target"
+        
+        if [[ "$run_target" == *"var/run"* ]] && [[ "$var_run_target" == *"run"* ]]; then
+            echo "❌ CIRCULAR SYMLINK DETECTED!"
+        else
+            echo "✅ No circular symlinks detected"
+        fi
+    fi
+    
+    cd ..
+    rm -rf test-extract
+fi
+
+echo "[+] Quick test complete!"