Choosing a Host

Koios needs one Ubuntu Server machine to itself. That machine can be a virtual machine on a hypervisor you already run, or a physical computer. Both are fully supported, and the rest of the installation is identical once the operating system is on.

Which One?

Choose a virtual machine if	Choose a physical computer if
You already run Hyper-V, VMware, or Proxmox	There is no virtualization host at the site
You want snapshots and existing backup tooling	The machine sits on the plant floor, near the equipment
The site has a server room and IT staff	You want the smallest possible footprint
Several systems share one physical server	You need serial ports, GPIO pins, or other physical hardware

If you have the option, a virtual machine is usually easier to look after: snapshots make upgrades reversible, and you can move it to different hardware without reinstalling.

Virtual Machines

Hyper-V — recommended

Hyper-V is our recommendation if you have Windows Server, or Windows 10/11 Pro. It is already part of the operating system, there is no extra license to buy, and giving the virtual machine a real address on your network is a two-click operation rather than a networking exercise.

Creating the Virtual Machine is a click-by-click walkthrough.

VMware, Proxmox, and others

VMware ESXi / vSphere, Proxmox VE, and VirtualBox all run Koios without any Koios-specific configuration. Any hypervisor that can run a current Ubuntu Server release as a guest will work.

The settings to get right are the same everywhere:

Setting	Value	Why
Guest OS type	Ubuntu 64-bit	—
CPU	4 – 8 virtual processors	4 suits most sites. See System Requirements
Memory	8 – 32 GB, fixed	Do not use dynamic or ballooning memory — see below
Disk	50 – 500 GB	Thin provisioning is fine, so size generously
Network adapter	Bridged to the physical network	See below
Firmware	UEFI	Matches a modern Ubuntu install

Networking: bridged, not NAT

This is the setting that causes the most trouble, so it is worth being deliberate about.

Your hypervisor offers at least two kinds of network adapter. NAT puts the virtual machine behind a private router that the hypervisor runs. Bridged puts the virtual machine directly onto your physical network, with its own address, as though it were another computer plugged into the switch.

Use bridged networking

Koios has to open connections to your equipment, and people have to open connections to Koios. NAT allows neither. On Hyper-V a bridged adapter is called an External virtual switch; on VMware it is Bridged; on VirtualBox it is Bridged Adapter.

If your equipment sits on a separate network segment or VLAN from your office network, give the virtual machine a second adapter bridged onto that segment.

Do not use dynamic memory

Hyper-V calls it Dynamic Memory, VMware calls it ballooning, and both let the hypervisor reclaim memory from a running guest. Give Koios a fixed allocation instead. It holds recent data in memory to serve the live values and trends you see in the UI, so a hypervisor taking memory back mid-scan shows up as slow pages and gaps, and it is a difficult problem to trace back to its cause.

Snapshots

Take one before every Koios upgrade. It is the fastest way back if an upgrade does not go the way you expected, and it costs a few seconds.

Snapshot a stopped machine

Shut the virtual machine down before taking a snapshot you intend to roll back to. A snapshot of a running machine captures the databases mid-write, and restoring it can leave them inconsistent. See Backing Up Docker Volumes for backups you can take while Koios is running.

Physical Computers

Nothing about Koios needs a hypervisor. Install Ubuntu Server directly on the machine and skip to Installing Ubuntu — everything from that point on is the same.

What changes without a hypervisor:

	On a physical machine
Networking	Simpler. The machine is already on your network; there is no virtual switch to configure
Snapshots	Not available. Rely on scheduled backups instead, and take one before every upgrade
Recovery	A hardware failure means reinstalling on new hardware and restoring a backup. Keep backups somewhere other than this machine
Serial and GPIO	Directly available, with no pass-through to configure

Small-form-factor and industrial PCs

A fanless industrial PC or a mini PC is a good fit for a small site, and often a better one than a virtual machine: it sits in the panel next to the equipment it reads, it has no moving parts, and it is not competing for resources with anything else.

Look for 4 or more cores, 8 to 16 GB of memory, and a 256 GB SSD or larger. Prefer an SSD over an SD card or eMMC — Koios writes historical data continuously, and cheap flash storage wears out under that load. DIN-rail and panel-mount machines from the usual industrial vendors are well suited, as are the small business mini PCs from mainstream manufacturers.

Raspberry Pi and other ARM boards

Koios runs on 64-bit ARM, so a Raspberry Pi 4 or 5 is a genuine option for a small installation. Use a Pi 5 with 8 GB of memory or more where you can.

Boot it from an SSD, not the SD card. An SD card will not survive continuous historical writes, and that is the single most common cause of a Pi installation failing after a few months. Use a USB-attached or NVMe SSD.

Two more things to get right on ARM:

Install the 64-bit Ubuntu Server image, not Raspberry Pi OS and not a 32-bit image. Koios requires a 64-bit operating system.
Use the arm64 download. Koios is published for both amd64 (ordinary Intel and AMD machines) and arm64 (Raspberry Pi and other ARM boards). If you are downloading an archive rather than pulling from the internet, take the arm64 one — an amd64 archive will load but will not run, and the error it gives does not obviously point at the cause.

Expect a Pi to handle a modest tag count comfortably and to struggle with heavy AI inference. Sizing guidance is in System Requirements.

Serial and USB Devices

If Koios needs to read a serial device, the host has to reach it:

Physical machine: plug it in. Koios can be given access to the port without further configuration.
Virtual machine: configure USB or serial pass-through in your hypervisor so the guest can see the adapter. Not every hypervisor does this well, and it is a reason to prefer a physical machine when serial hardware is central to the installation.

What's Next

Using Hyper-V: Creating the Virtual Machine
Using another hypervisor, or a physical machine: Installing Ubuntu

System Requirements Creating the Virtual Machine