Installing umbrelOS in a virtual machine

umbrelOS runs in a virtual machine using any virtualization software that supports EFI boot, such as Proxmox, VirtualBox, VMware, or KVM. See Running umbrelOS on your own hardware for what to expect.

Minimum VM requirements

• Computer: A 64-bit Intel or AMD computer. Macs with Apple silicon can't run umbrelOS in a virtual machine, including in UTM, VirtualBox, or VMware Fusion, because there is no ARM version of the installer.
• RAM: 4 GB (8 GB+ recommended)
• Storage: 32 GB virtual hard drive (more depending on your use case)

Hyper-V doesn't work with the umbrelOS installer yet. The installer starts but can't find its own files, and stops with "Timed out waiting for device". Use another virtual machine app, or contact us for a workaround.

Install umbrelOS

1. Download the latest umbrelOS USB installer ISO.
2. Create a new VM and allocate at least 4 GB of RAM and a 32 GB virtual hard drive.
3. Attach the ISO to the VM's virtual CD-ROM drive.
4. Important: Set the VM to boot in EFI mode, not legacy BIOS, and turn Secure Boot off. The installer won't start with legacy BIOS or with Secure Boot on.
5. Set the VM's network to bridged mode so it gets its own IP address on your local network.
6. Boot the VM. The installer will show a drive selection screen. Select your virtual hard drive and confirm.
7. Once installation is complete, shut down the VM.
8. Remove the installer ISO from the VM's virtual drives. If you leave it attached, the VM starts the installer again.

Boot and access

1. Boot the VM.
2. Wait about 5 minutes for the first boot to complete, then open http://umbrel.local in your browser.

See Connecting to your Umbrel if you need help accessing it.

Settings for your virtual machine app

• VirtualBox. Choose Linux and a 64-bit version such as Debian (64-bit) as the type, and tick Enable EFI before the first boot. If you see "This kernel requires an x86-64 CPU, but only detected an i686 CPU", the VM's type is set to a 32-bit system: change it to a 64-bit one. For the network, choose Bridged Adapter.
• Proxmox. Choose OVMF (UEFI) as the BIOS, not SeaBIOS, and untick Pre-Enroll keys when adding the EFI disk so Secure Boot stays off. Add the virtual hard drive as SATA.
• VMware. Choose UEFI as the firmware type, leave Secure Boot unticked, and use Bridged networking.
• KVM and virt-manager. Choose a UEFI firmware without Secure Boot, and add the virtual hard drive as SATA.

If something goes wrong

• The installer doesn't start. Check that the VM uses EFI, Secure Boot is off, and the installer ISO is attached to its CD drive. Messages like "No bootable medium found", "Access denied", or "rejected by Secure Boot" point to one of these settings.
• The VM says there's nothing to boot after installing. The VM was switched from EFI to legacy BIOS, or was installed without EFI. Turn EFI on and start it again. If it was installed without EFI, reinstall with EFI on.
• The installer starts again after installing. Shut down the VM and remove the installer ISO from its CD drive.
• You see a text login prompt. That's normal, and it means umbrelOS is running. You don't need to log in there: open http://umbrel.local in your browser instead.
• http://umbrel.local doesn't open. Make sure the VM's network is set to bridged mode, not NAT. With NAT, the VM isn't visible to other devices on your network. If it still doesn't open, use the VM's IP address instead. To find it, log in at the text prompt with the username umbrel and the password umbrel (this works until you create your account), then run ip -br -4 addr.

Notes

• Extra virtual drives. Storage Manager only lists SATA and NVMe drives. If you add more virtual drives to try FailSafe, add them as SATA, not VirtIO or SCSI.
• A VM is the quickest way to try umbrelOS, but running it directly on a device gives you better performance and access to all of its hardware.