keelOS

HomeWhy keelOSHow it worksAbout keelOSFAQFeature comparison

Features

kcell: Docker apps, each in a tiny VMNested virtualizationkeelRM: a BMC for machines without onePassthrough that survives a host restartSR-IOV: network cards and graphicsWindows 11 without workaroundsZFS underneathWeb, command line and APIRDP straight to the consoleMemory that is not wastedOld systems welcome

Market

MarketkeelNASkeelAuth

Performance

keelOS next to KVMCPUMemoryStorageNetworkGPU passthrough next to bare metal

Get started

QuickstartDownloadGuestsHardwareSource code and licences

Read

DocsArticles
中文日本語

Docs · 1.0

Creating your first virtual machine

This chapter walks through it from scratch: prepare an installation ISO, create a virtual machine, and open its screen to install the system. It assumes you have finished the first-time setup and have a storage pool.

1. Prepare an ISO

  1. Open Configuration → Storage and scroll down to ISO images.
  2. Use either method: - Upload ISO: pick an .iso (or .img) file on this computer and upload it. - Download from URL: paste an http or https download address and the host downloads it by itself. The download happens on the host, so you can leave the page.
  3. When it is done the ISO appears in the list, with its volume label shown below.

ISOs are kept in the storage pool and can be used by all virtual machines.

2. Make sure there is a network

A virtual machine's network card has to be attached to a network (a virtual switch). Open Configuration → Network and look:

  • If a network already exists (for example lan, attached to the management port), just use it.
  • If it says there are no networks yet, click to probe the physical ports and create one from "found on the ports", or make one by hand with New network and select the physical port to use. See Network.

You can create a virtual machine without a network too; it just has no network card for now.

3. Create the virtual machine

  1. Open Virtual machines and click New virtual machine.
  2. Pick a template: first a category, then the specific system (for example Windows 11, Debian, OpenWrt). A template holds the settings the system needs: firmware (UEFI or BIOS), the disk and network card models, whether a TPM is needed and so on, and it also says how much memory and disk it needs at least. If no template fits, choose Empty (UEFI, virtio).
  3. Name: the name of this virtual machine, used later in the list, the console and RDP (for example win11).
  4. CPU and memory: change them from the template's suggestion. Memory cannot be lower than the template's minimum.
  5. Disk: the template creates a new empty disk, whose size you can change; + disk adds another.
  6. ISO: click + ISO and pick the installation disc you prepared in step 1.
  7. Network card: choose which network it connects to. By default it is a virtual network card.
  8. Options: - start it now: power it on as soon as it is created. - wait for the console at the next start: the virtual machine is only powered on once the console is open, so you can see prompts that last just a few seconds, like "Press any key to boot from CD or DVD". Recommended when installing Windows. - Access password (optional): the password to use when connecting to this virtual machine's screen over RDP; if empty it is the admin password. See Console and remote desktop.
  9. Click Create.

At the bottom of the form you can see the configuration (JSON) that is handed to keel. Settings that are not on the form can be changed right there; you will not usually need to.

4. Open the screen and install the system

  1. Click the virtual machine in the list to open its detail page.
  2. Open the graphical console (VNC in the web page). You see the virtual machine's screen and install the system as if sitting at a real machine.
  3. When the installation is done, remove the ISO from the CD drive on the detail page so that the next start boots from the disk.

Besides the web console, you can connect straight to the virtual machine's screen with Windows' built-in "Remote Desktop Connection" (mstsc) or any other RDP client; you see it from the boot screen onward, and nothing needs to be installed in the virtual machine. See Console and remote desktop.

Things to know when installing Windows

  • Just pick a Windows template. The Windows 11 template comes with a virtual TPM 2.0 (TPM 2.0 (vTPM) is ticked by default) and Secure Boot, so the installer's hardware check passes directly, with no need to bypass it.
  • The templates use an NVMe disk and an e1000 network card, which Windows has built-in drivers for, so you do not need to load extra drivers during installation.
  • The display device is virtio-vga by default: the resolution can follow the size of the RDP client window, but you need to install virtio-win's viogpudo driver in Windows. The template has an optional CD drive called Drivers ISO (optional): upload virtio-win.iso too and choose it there, then install the driver from that drive after the system is installed. If you would rather not install a driver, set the display device to standard (bhyve framebuffer).
  • For old systems such as Windows XP, 2003 and 7, choose the matching template; they use SeaBIOS and the drivers built into the system. See Virtual machines.

Next steps

← Previous: First-time setupNext: Overview →