Running guideXOS in VirtualBox

A beginner-friendly setup guide for guideXOS Server and guideXOS C# / UEFI.

Start with the important setting

Both guideXOS Server and guideXOS C# are actively tested in virtual machines. VirtualBox works well when its guest type and firmware settings match the ISO. You do not need to know anything about QEMU or the guideXOS development environment to follow this page.

Use “Other (64-bit)”, not “Other”.

Choosing Other without the (64-bit) version can prevent guideXOS Server from booting. EFI / UEFI and I/O APIC should also be enabled before you start the VM.

Download the ISO you want to test from the downloads page before creating the VM.

Before you create the VM

  1. Install and open Oracle VM VirtualBox.
  2. Download the guideXOS ISO you want to try.
  3. Make sure virtualization is enabled on the host computer if VirtualBox asks for it.
  4. Keep the VM stopped while changing firmware, motherboard, storage, or display settings.

guideXOS Server

These settings are a conservative starting point for the released guideXOS Server ISO. Start with the defaults shown here, then adjust only if you have a specific reason.

1. Create the virtual machine

  1. In VirtualBox Manager, click New.
  2. Give the VM a name such as guideXOS Server.
  3. Set Type to Other.
  4. Set Version to Other (64-bit).
  5. Continue with the guided VM creation screens. A virtual hard disk is optional for the first boot.

2. Configure the VM before starting it

VirtualBox area Starting value Why it matters
System > Motherboard > Base Memory 2–4 GB Enough memory for a first desktop and application test.
System > Processor 1–2 CPUs Start small; add CPUs only when you need to test a different workload.
System > Motherboard > Extended Features Enable EFI / UEFI
Enable I/O APIC		 These firmware and interrupt-controller settings are part of the known-good baseline.
System > Motherboard > Chipset Leave the conservative/default value No project-specific chipset change is required for the first boot attempt.
Display > Screen 1 monitor, about 128 MB video memory, 3D acceleration off Provides a simple framebuffer configuration while troubleshooting.
Storage Attach the guideXOS Server ISO to the virtual optical drive The optical drive must be enabled and available at boot.
Network NAT Default/NAT networking is sufficient for the initial boot.

3. Attach the ISO and boot

  1. Open Settings > Storage and select the virtual optical drive.
  2. Choose the downloaded guideXOS Server ISO.
  3. In Settings > System > Boot Order, make sure the optical drive is enabled and available.
  4. Click Start.
What a successful boot looks like

The VM should boot from the ISO and reach the guideXOS Server startup or desktop environment. The first boot is only a boot test; it does not require a writable data disk.

Writable storage for saving files

guideXOS Server can boot without a writable data disk. However, applications such as Notepad need writable filesystem storage in order to save files. If there is no writable storage, the operating system may still start normally; saving a file is the operation that needs the disk.

The development and QEMU environment commonly provides a FAT32 disk automatically, which can make this requirement easy to miss when testing outside that environment. This does not mean that Notepad itself is broken.

Current release limitation

The current released version cannot yet reliably initialize and format a completely blank disk through Disk Manager; this is a current storage-management limitation. The project is separately improving guideXOS Server so it can detect raw disks and guide users through initialization.

guideXOS C# / UEFI

guideXOS C# / UEFI is a UEFI operating system. EFI / UEFI must be enabled for this edition; a VM configured for legacy BIOS can show a black screen or fail to find a bootable operating system. I/O APIC should also be enabled.

1. Create the virtual machine

  1. In VirtualBox Manager, click New.
  2. Give the VM a name such as guideXOS C# UEFI.
  3. Set Type to Other.
  4. Set Version to Other (64-bit).

2. Configure the VM before starting it

VirtualBox area Starting value Important note
System > Motherboard > Base Memory 2–4 GB A practical starting range for the UEFI desktop.
System > Processor 1–2 CPUs Use a small, conservative CPU count for the first boot.
System > Motherboard > Extended Features Enable EFI / UEFI
Enable I/O APIC		 EFI is required because this is the UEFI edition; I/O APIC is part of the known-good baseline.
System > Motherboard > Chipset Leave the conservative/default value No project-specific chipset change is required for the first boot attempt.
Display > Screen 1 monitor, about 128 MB video memory, 3D acceleration off Keep the initial graphics setup simple.
Storage Mount the guideXOS C# / UEFI ISO as optical media Use the UEFI ISO, not a different guideXOS edition.

3. Attach the ISO and boot

  1. Open Settings > Storage and mount the downloaded guideXOS C# / UEFI ISO in the optical drive.
  2. Confirm that the optical drive is enabled and available in the boot order.
  3. Confirm one last time that Enable EFI and Enable I/O APIC are checked.
  4. Click Start.
What to expect

With the UEFI settings applied, the VM should proceed from the mounted ISO instead of stopping at a black screen. If it does not, use the checks below before replacing the ISO.

Troubleshooting

“No bootable operating system” or VirtualBox asks for another ISO

Check each of these before downloading the ISO again:

  • The VM is Other (64-bit), not Other.
  • EFI / UEFI is enabled.
  • I/O APIC is enabled.
  • The correct guideXOS ISO is attached to the virtual optical drive.
  • The optical drive is enabled and available in the boot order.

Black screen

A black screen does not immediately mean that the ISO is corrupt. First check:

  • EFI / UEFI is enabled.
  • I/O APIC is enabled.
  • The guest type is Other (64-bit).
  • 3D acceleration is disabled.
  • The VM has adequate video memory, approximately 128 MB if available.
  • The correct ISO is attached and the VM is actually booting from the optical drive.

The project does not currently specify a single verified VirtualBox graphics-controller setting as required. Leave the controller at the VirtualBox default initially. If the checks above are correct and the screen is still black, trying another controller offered by your VirtualBox version can be a diagnostic experiment; change one setting at a time and do not treat that experiment as a project requirement.

Recommended baseline, not a permanent restriction

The memory, CPU count, video memory, one-display setup, NAT networking, chipset defaults, and disabled 3D acceleration on this page are recommended starting values. The settings that should be treated as required for this guide are Other (64-bit), the correct ISO, and enabled EFI / UEFI and I/O APIC.