中文日本語

Quickstart

Four steps from download to the first VM.

1Download

Download the keelOS ISO.

Download the ISO

Get keelos-VERSION.iso from the releases on GitHub (public beta since 2026-10-11). The same file works on a USB stick, as a CD, and as a server's virtual media.

The version is the commit and the build time (UTC), e.g. keelos-196d733-20261001T104152Z.iso: a later time is a newer version.

Check the hardware

64-bit Intel CPU with VT-x enabled in the firmware (VT-d too for passthrough). AMD support is early (guests run, no passthrough yet): see the FAQ.

A disk of 4 GiB or more with 512-byte sectors for keelOS (4Kn disks cannot boot). The rest of that disk and any other disks can hold VMs.

8 GB of memory runs a few VMs. One wired network port.

Machines and parts we have tested: Hardware.

2Boot stick

Write the ISO to a USB stick of 1 GB or more and boot from it.

On Windows

Use Rufus: pick the stick and the ISO, press Start, and choose DD image mode when asked (not ISO mode). Or use balenaEtcher, which asks nothing. The stick is erased.

On macOS or Linux

Use balenaEtcher or dd. Check the device name first; the wrong one erases another disk.

dd if=keelos-VERSION.iso of=/dev/sdX bs=4M   # Linux, sdX is the stick
dd if=keelos-VERSION.iso of=/dev/rdiskN bs=4m # macOS, N from diskutil list
Servers: the BMC's virtual media

A server with IPMI, iDRAC, iLO or a Supermicro BMC needs no stick: mount the ISO as virtual media in the BMC's web page and boot from it once.

Firmware settings

UEFI boot with CSM / Legacy off (the image has no legacy BIOS boot code). Secure Boot off. VT-x and VT-d on.

Press the boot menu key at power-on (F12 on many Lenovo machines, F11 on Supermicro) and pick the stick.

3Install

On the console choose install, pick one disk and a network port, wait a minute or two, remove the stick and reboot.

A normal install

keelOS starts in memory and asks whether to install or try; Enter installs.

  1) install
  2) quit: write nothing
Choice [1]:

The wizard lists every disk with what is on it (partitions, file systems, ZFS pools), so a disk with Windows or an old pool is easy to spot. keelOS takes a small part at the front of the chosen disk; a disk that holds data must be confirmed by typing its name. Then pick the network port (the one with a link is the default), DHCP or a fixed address.

Already installed

The menu then has three entries: upgrade (writes the new version to the other slot; settings, pools and VMs stay), fresh install (erases one disk and starts over) and quit. The install image has no "try only" mode: without an install there is no storage pool and VMs cannot start.

A disk that holds data

The wizard shows what is on it and erases it only after you type its name. An empty answer goes back to pick another disk.

Disk to install to [ada2]: ada0
  ada0 holds GPT: ms-basic-data 1 GiB (msdosfs "WINDOWS").
  Everything on ada0 will be erased.
  Type ada0 to erase it (empty: pick another disk): ada0

4Set up

Open the address shown on the console in a browser and set the admin password. The rest is clicks in the web page.

Open the web page, set the password

The console shows the address above the login prompt, for example https://192.168.1.10/. The certificate is the host's own, so the browser asks you to confirm once.

The first page is Set the admin password (8 characters or more); it is root's password too. Whoever opens the page first sets it, so do it right after the install. Forgot it? Run keel admin reset on the host's console.

Make the storage pool

Configuration → Storage → Make the pool zones. Tick the rest of the boot disk and/or other disks: one disk is a single disk, two a mirror, three or more raidz, four or more raidz2.

Optional: a copy of the boot partition on a second disk, so the host still boots when the first one fails.

Set up the network

Configuration → Network → Physical ports → Probe. keelOS listens on each port for subnets, VLANs, routers and DHCP servers; create the suggested networks under Found on the ports. VMs connect to networks, not to ports.

Create the first VM

Configuration → Storage → ISO images → Upload ISO: an installer for the guest system (or give a URL and let the host download it).

Virtual machines → New virtual machine: pick a template (Windows 11, Linux, FreeBSD…), fill in name, CPUs, memory, disk, ISO and network, tick start it now and press Create. Install the system in Screen (VNC) in the browser, or connect any RDP client to the VM's screen.

Next

  • Restart the host once (shutdown -r now on the host) and watch the VMs pause and carry on. That is what keelOS is for.
  • Upgrades: System → Upgrade with a new keelOS ISO. The new version goes into the boot partition's other slot and the host restarts into it while the VMs only pause. If the new version does not come up, the next boot returns to the old one. Settings are kept.
  • Give a disk controller or an NVMe drive to a NAS VM, or SR-IOV VFs to a router: see passthrough and SR-IOV.