Articles

keelOS: The public beta is here! From installing keelOS to your first Windows 10 VM

2026-10-11 · Wanpeng Qian

This guide is for the keelOS public beta released on 2026-10-11. keelOS ships a new version every week, so the screens and steps may have changed and this guide may lag behind; go by what your version shows.

The keelOS public beta has started. This guide starts from an empty machine, installs keelOS step by step, and then sets up the first Windows 10 virtual machine on it: installing Windows through kRDPclient, passing through the integrated GPU, and installing keelagent. It takes one to two hours, most of it waiting for Windows to install.

keelOS in two sentences: it is a virtualization system for the one server at home or in a small office, built on FreeBSD and bhyve, managed entirely from a web page. What sets it apart is that the host system can be upgraded and restarted while the virtual machines only pause for a few dozen seconds instead of shutting down, and passed-through GPUs and disks stay with them.

Recommended hardware

We recommend an 8th–10th gen Intel CPU with integrated graphics, two network ports and two disks; one port and one disk is the minimum.

You also need a USB stick of 2 GB or more as the installer. In the BIOS, turn on VT-x (Intel Virtualization Technology) and VT-d, and boot in UEFI mode.

Before you start: downloads and the boot stick

1. Download keelOS: get the latest keelos-<version>.iso (about 500 MB) from the GitHub releases page. The .sha256 file next to it lets you check the download.
2. Make the boot stick: the ISO is a hybrid image, so write it to the whole USB stick. On Windows use Rufus (choose "Write in DD Image mode" when asked) or balenaEtcher; on Linux and Mac use dd. Everything on the stick is erased.
3. Download the Windows 10 ISO from Microsoft's Windows 10 download page. Any language is fine; choose 64-bit. Keep it on your own computer for now: you will upload it from the web page later.

Installing keelOS

When you boot from the stick, keelOS first runs in memory and shows a blue installer menu. The installer needs no network; the network is set up by DHCP on the first boot after installing.

The menu entries:

• Upgrade: only shown when keelOS is already on a disk; you won't see it on a new machine.
• Fresh install: a new installation.
• Disk tools: shows what is on each disk and erases disks.
• Try only: run without writing anything.
• Quit: leave the installer.

Steps:

1. Erase disks first (if they have anything on them). A fresh install only goes onto empty disks. If a disk has an old system, an old keelOS or an old ZFS pool, open Disk tools, select the disk with Space, choose Erase, and type the disk's name to confirm. Be sure to erase any old keelOS boot partition, or the mainboard may boot from it. Choose Back to return to the menu.
2. Pick disks. In Fresh install, only empty disks you can install to are listed. Select one or more with Space. With two disks, select both: each disk gets an identical 2 GB boot partition at the start, either one can boot, and the rest of the space is left untouched. If there is no empty disk, it lists all disks and what is on them, and asks you to erase one in Disk tools first.
3. Confirm. Choose Install, then Yes in the final confirmation (the cursor starts on No, so a stray Enter does nothing). Copying usually takes a minute or two.
4. Restart. When it is done, remove the USB stick and restart.

After the restart, the console shows the host name and the web address above the login prompt, for example https://192.168.1.50/. If it gets no address within 30 seconds (no DHCP, or the switch port needs a VLAN), the console asks whether you want to set up the network by hand.

Opening the web page for the first time

On a computer on the same LAN, open the address shown on the console in a browser. The certificate is made by keelOS itself, so the browser warns that the site is not secure; choose to continue.

1. Set the admin password. The first time, the page asks you to set the admin password. It is also the host's root password. You log in to the web page with it from now on.
2. Make the storage pool. VM disks and ISOs live in the storage pool; you can't create a VM without one. Go to Configuration → Storage; at the top is "Make the pool zones". With two disks installed, select the space after the boot partition on both, and you get a mirror (the data survives if one disk dies). The confirmation lists what each disk will become.
3. Make a network. A VM's network card has to connect to a network. Go to Configuration → Network; Suggestions lists the host's ports, and you make a network from one of them (for example, named lan). With two ports, give the second one to the VMs, so web management and VM traffic are kept apart.

Getting kRDPclient

kRDPclient is keelOS's own RDP client for Windows. We suggest using it from the moment you install Windows: the picture is smoother than the web console, and it can hand USB sticks on your PC to the VM and share the clipboard and sound.

1. On your own Windows computer, open the keelOS web page, go to Companion apps, and click "Download with this host" next to kRDPclient. You get a zip of about 10 MB.
2. Unzip it and run krdpclient.exe. This host is already added (the zip carries a token made for you and the host's certificate), so it opens with the host's VMs listed.
3. Double-click a VM to connect to its console.

The token in the zip carries your rights on this host: don't pass it on. kRDPclient imports it on its first start and deletes the file. It appears under System → Tokens as "kRDPclient · your name · date"; revoke it there and that client stops working.

Other RDP clients (such as Windows' own Remote Desktop) can connect too: the address is host-address:3389, the user name is the VM's name, and the password is the admin password; each VM's page shows these. They just don't have USB, sound and the other extras.

Creating the Windows 10 VM

Go to Virtual machines, click "New virtual machine", and choose Windows → Desktop → Windows 10. The wizard has six steps:

1. Architecture: choose "64-bit (x64)". The other two are 32-bit and "64-bit, BIOS"; the latter is for importing a Windows that was installed in BIOS mode on an old PC or on ESXi.
2. System: the system comes from an ISO. Click "Upload from this computer" and choose the Windows 10 ISO you downloaded; it is selected when the upload finishes. You don't need a drivers ISO: Windows has drivers for the default NVMe disk and e1000 network card.
3. Resources: 4 vCPUs, 8 GB memory and a 64 GB disk by default; adjust to your machine.
4. Network: connect NIC 1 to the network you just made (lan).
5. Options: leave TPM 2.0 and Display at their defaults.
6. Confirm: check the settings, untick "start it now", and click Create. Don't power it on yet: connect kRDPclient first.

Once created, you land on the VM's page. First double-click the VM in kRDPclient (refresh if the list hasn't updated) to connect to its console; then go back to the web page and click Start. You watch it boot in kRDPclient from the very first frame, as if you were sitting in front of a PC whose power button you just pressed. Without a Windows PC, you can use Screen (VNC) → in this page on the VM's page instead, then click Start. When you see "Press any key", press a key at once to enter Windows Setup:

1. Choose the language → Install now.
2. For the product key you can choose "I don't have a product key" and activate later; pick an edition (Pro, Home).
3. Choose "Custom: Install Windows only"; the 64 GB disk is in the list. Select it and click Next.
4. Wait while it copies files and restarts a few times, until it reaches the initial setup (region, keyboard, account). The network card already works, so you can sign in with a Microsoft account or make a local account.

When you reach the desktop, you're done. Run Windows Update once first.

Passing through the iGPU

Once the iGPU belongs to Windows, Windows gets hardware acceleration, and a monitor on the host's HDMI port shows the Windows desktop.

1. Shut down first. Shut Windows down normally.
2. Keep the iGPU for passthrough. Go to Configuration → PCI passthrough, find the Intel graphics (for example vgapci0 · UHD Graphics 630), click "Keep for passthrough" and tick "Now". If the page says it can't do that now, restart the host once; it keeps the iGPU from then on, at every boot.
3. Add it to the VM. On the Windows VM's page → Edit → PCI devices, choose the iGPU in the drop-down, click Add, and save. One iGPU can be given to several VMs, but only the one started first can use it at a time.
4. Start. Click Start. The boot screen (the Windows logo) now only shows in the keelOS console; the monitor stays dark.
5. Install the Intel graphics driver. In Windows, Device Manager shows a new display adapter under "Display adapters". Let Windows Update install the driver, or download it from Intel. Once the driver is installed, the monitor on HDMI comes on.

From then on, the boot logo still only appears in the keelOS console at every start, and the monitor comes on once the Intel driver loads; this is normal. To see Windows remotely, use kRDPclient: what it shows is the picture the iGPU produces.

Installing keelagent

keelagent runs in a Windows VM that has a GPU and uses that GPU to encode the Windows screen as video for keelOS. kRDPclient gets a sharper picture and the host's CPU does less work. It is experimental for now.

1. Turn on the agent channel. On the VM's page → Edit, tick "Channel for a guest encoding agent" and save.
2. Cold start. Shut down in Windows, then click Start on the web page. The setting only takes effect after a power off and on; a restart inside Windows doesn't count.
3. Download. In Windows, open the keelOS web page in a browser, log in, go to Companion apps, and download keelagent.exe. You can also download it on another computer and copy it in.
4. Install. Double-click keelagent.exe and click Install in its window. It installs itself and the driver it needs as a Windows service, which starts automatically at every boot.

FAQ

• After installing, the mainboard still boots the old system or the old keelOS: another disk still has an old boot partition. Boot from the USB stick again and erase that disk with Disk tools, or move "keelOS gpt/keelboot…" to the front of the boot order in the BIOS.
• Something went wrong in the installer: log in as root at the console login prompt (no password). The install log is /var/log/keel-install.log; please attach it when you report the problem.
• The web page won't open: check that your computer and the host are on the same subnet and that the address starts with https://. The address on the console is the one the host has right now.
• Missed "Press any key": the VM stops at a screen like "no bootable device". Force it off on the web page and start it again, and this time watch kRDPclient and press a key in time.
• With the iGPU passed through, the monitor is dark at boot: this is normal. The monitor only comes on once Windows' Intel driver loads; watch the boot in kRDPclient.

Feedback

If you run into a problem during the beta, please open an issue on GitHub Issues with your keelOS version (bottom right of the web page), your hardware model and the step where it went wrong. Screenshots or logs help a lot.

← Articles · Why keelOS