guideXOS Server Build and Testing

Recommended daily workflow

This is the main Server-branch workflow. It builds the UEFI bootloader, attempts the selected kernel build, stages the ESP directory, and launches QEMU when requested.

Current status: contributor workflow for source builds, architecture work, and QEMU validation alongside the public v0.2.1 AMD64 ISO.
Release note: source builds are useful for contributors but are no longer the only public path. Download the public ISO. Back to /Wiki/Server

Key scripts surfaced by the repo

• build.ps1 – full bootloader + kernel + ESP workflow
• build-uefi.ps1 – alias to the same UEFI-focused build flow
• run-qemu.bat / run-uefi.sh – OVMF/QEMU boot launchers
• scripts/qemu-secure-rng-args.ps1 / .bat – shared secure-entropy arguments used by QEMU launchers
• scripts/run-qemu-fs-test.ps1 / .sh – filesystem test launch flows
• sdk/build-samples.ps1 – stages Native ELF SDK sample apps for hosted runtime validation
• build-native-experimental.bat – hosted experimental Native ELF execution validation

Running guideXOS Server in QEMU

QEMU is the recommended first development and test environment for guideXOS Server. The current launch scripts give the guest reproducible virtual hardware, capture serial and debug output, use the known QEMU networking device, and make virtual devices such as storage and secure entropy controllable from the launch command.

The normal Windows path is powershell -ExecutionPolicy Bypass -File build.ps1 -RunQemu or, after the ESP is prepared, run-qemu.bat. The scripts boot the UEFI image with OVMF, expose the ESP as a FAT disk, attach an e1000 network device, send kernel output to -serial stdio, and include the shared secure-RNG arguments below. The PowerShell build path uses the pc machine; the batch launcher adds usb=off for the current PS/2 input path.

Secure entropy and HTTPS

The canonical QEMU secure-RNG configuration is:

The guest currently consumes the transitional PCI virtio-rng transport backed by QEMU's built-in host entropy. The kernel wires that device into the supported OS random path; it reports the random quality as Secure only when the device is ready.

Why this changes HTTPS behavior

Navigator's HTTPS/TLS stack needs cryptographically secure random data. Mbed TLS and PSA crypto receive that data through the guideXOS secure-random callback before TLS operations can safely proceed. If secure entropy is unavailable, crypto initialization and TLS fail closed; the implementation does not substitute timer ticks, timestamps, counters, deterministic pseudo-random values, or another weak fallback. Plain HTTP does not require this cryptographic entropy prerequisite.

A correctly configured QEMU VM can therefore obtain entropy through the supported virtio-rng path and may proceed with HTTPS when the other TLS prerequisites are also ready. The RNG is necessary but not sufficient: certificate trust-store, wall-clock, hostname-validation, and HTTPS-policy checks still apply.

The released bare-metal x86/AMD64 path has this transitional virtio-rng driver, but no general physical-hardware entropy/CSPRNG provider is established by the current Server source. Do not claim broad bare-metal HTTPS support for machines that do not provide a supported secure entropy path. Current bare-metal HTTPS policy can also remain fail-closed even after entropy is available until the validated trust-store and policy conditions are satisfied.

Troubleshooting HTTPS

HTTPS works in QEMU but not on bare metal

Compare the entropy device and OS path. QEMU should have both secure-RNG arguments above; physical hardware may not expose a device that the current Server driver can consume. Also compare the current trust-store, clock, hostname-validation, and HTTPS-policy diagnostics.

HTTPS fails in QEMU

Verify that the launch command includes both -object rng-builtin,id=rng0 and -device virtio-rng-pci,rng=rng0,disable-modern=on,max-bytes=1024,period=1000. Then inspect serial output for the actual current markers, including:

Failure diagnostics include [VIRTIO-RNG] Device present=no; no virtio-rng PCI device detected and [VIRTIO-RNG] Entropy device found but transport mode is unsupported. Navigator's diagnostics also expose the RNG quality/backend, virtio-rng status, RNG callback status, TLS backend status, and HTTPS-policy blocker.

HTTP works but HTTPS does not

Basic TCP/IP connectivity proves only that the network path is usable. It does not prove that the cryptographic entropy, Mbed TLS/PSA initialization, clock, certificate, hostname, and HTTPS-policy prerequisites required for TLS are ready.

What contributors should verify

See also

• Server Navigator Browser — current HTTP/TLS capability and policy boundary.
• Developing Apps with Developer Studio — create, build, run, and debug a Native GUI Application.
• Server Overview — release status and hosted/bare-metal context.