System Requirements

Before installing Koios, verify that your host machine meets the following hardware and software requirements.

Single Container Architecture

Koios runs all services inside a single Docker container — including the configuration database, time-series database, in-memory cache, web proxy, and the application services. The requirements below account for this all-in-one deployment.

Hardware

Resource	Minimum	Recommended
CPU	2 cores	4+ cores
RAM	4 GB	8+ GB
Disk	20 GB free	50+ GB free

Disk usage grows over time with historical time-series data. Plan storage based on the number of tags, scan rates, and data retention settings.

Operating System

OS	Version
Ubuntu Server	20.04 LTS, 22.04 LTS, or 24.04 LTS

Ubuntu Server (minimal install) is recommended. A desktop environment is not required — Koios is managed entirely through its web interface.

Software

Dependency	Version
Docker Engine	20.10 or later

Docker is the only software dependency. See Installing Docker Engine for setup instructions.

Network

Requirement	Detail
Docker Hub access	Required to pull the Koios image (unless using an offline bundle)
Ports 443 and 80	Must be available on the host for HTTPS and HTTP access
Device network access	The host must be able to reach industrial devices (OPC-UA, Modbus, etc.) on their respective ports

Virtual Machines

If you're running Koios in a VM, use bridged networking so the container can reach devices on the local network. See Virtual Machine for details.

Time Synchronization (NTP)

The host must keep accurate time via NTP (Network Time Protocol). Koios timestamps every device read, model prediction, event, and historical sample using the host clock — so a drifting clock corrupts all of it.

Risk	Impact
Drift on the host	Time-series data is written with the wrong timestamp. Trends, model history, and event timelines no longer line up with reality.
Drift between host and browser	The UI compares its own clock against the server clock. A few seconds of drift triggers a warning on the System Overview page; large drift makes "live" values appear stale or future-dated.
Drift between Koios and external systems	Comparing Koios timestamps to PLC, SCADA, or third-party historians becomes unreliable when each side runs on its own clock.

Ubuntu enables systemd-timesyncd automatically on a clean install. Verify it's running and synchronized:

timedatectl status

The output should show System clock synchronized: yes and NTP service: active. If it's not, enable it:

sudo timedatectl set-ntp true

For air-gapped sites, point the host at an internal NTP server by editing /etc/systemd/timesyncd.conf:

[Time]
NTP=ntp.internal.example.com
FallbackNTP=ntp.ubuntu.com

Then restart the service:

sudo systemctl restart systemd-timesyncd

Don't fix drift by jumping the clock

Once Koios is collecting data, never set the host clock backward by more than a few seconds. Historical writes use timestamps as primary keys, so jumping the clock backward can create overlapping samples or appear to "lose" recent data. Let NTP slew the clock gradually, or stop Koios before making a large adjustment.

What's Next

Virtual Machine — guidance for running Koios inside a VM
Installing Ubuntu — set up the host operating system
Installing Docker Engine — install the Docker runtime

Getting Started Virtual Machine