guideXOS Server Documentation

First Boot

The current repository recommends starting with the Windows → amd64 → UEFI → QEMU path. A typical first run starts from the build script rather than a prebuilt legacy ISO image:

• Build the UEFI bootloader project
• Build the kernel with the current toolchain
• Stage the ESP directory with boot artifacts
• Launch QEMU with OVMF firmware
• Observe serial and framebuffer output during bring-up

Using the Desktop

guideXOS still aims to present a visible desktop OS while the kernel matures. The current project story emphasizes:

• Framebuffer output: Graphics and UI work are still part of the project
• Console-first diagnostics: Serial and shell visibility matter during bring-up
• Layered app work: App registration and launch behavior should respect the app model
• Cross-target validation: Features should survive both host-side and bare-metal paths

What is GXAPP?

GXAPP is the canonical guideXOS Server package format. It is a native container with a magic header, one metadata entry, and one or more architecture-specific binaries.

File Structure

Metadata Example

The current implementation requires string metadata fields such as application name, version, required guideXOS version, and a binaries list:

Validation Rules

• Exactly one metadata entry is required
• At least one binary entry must be present
• Binary paths must match bin/<arch>/app.bin
• Duplicate architecture entries are rejected
• Trailing bytes after declared entries are rejected
• Current limits include 128 MiB package size and 64 entries

Installation Behavior

• Packages install under /system/apps
• Staging happens under /system/apps/.staging
• The package manager validates the current CPU has a matching binary
• Existing packages are not silently overwritten
• Compression, signatures, and repository downloads are not implemented yet

What Already Works

The current hardware report shows a substantial amount of platform support already in-tree:

• CPU targets: x86, amd64, arm, riscv64, loongarch64, ia64, sparc, sparc64, ppc64, and mips64 are present in-tree
• Boot paths: UEFI, BIOS/Multiboot, and OpenSBI depending on architecture
• Storage: ATA/IDE, AHCI, NVMe, and USB mass storage
• Filesystems: FAT32, exFAT, ext2/4, and UFS
• Networking: Ethernet, ARP, IPv4, ICMP, UDP, TCP, DHCP client, and DNS client
• Input and graphics: PS/2, USB HID, serial consoles, VGA text, EFI GOP, and framebuffer backends

Known Gaps

• ARM64 remains a high-priority missing architecture
• IPv6 is not implemented yet
• VirtIO block and VirtIO networking are not implemented
• Secure Boot, TPM-backed features, and kernel ASLR are missing
• GPU acceleration is not available

Common Bring-Up Focus

For contributors, the most stable path is still the amd64 UEFI QEMU flow:

Directory Structure

The repository is currently organized around the bootloader, kernel, docs, scripts, and staged ESP output:

File Operations

At runtime, the VFS layer already supports:

• Mount points
• Path normalization and resolution
• File handles for open files
• Directory listing, creation, and removal
• Package installation under /system/apps