---
title: "System Requirements"
description: "Hardware and software prerequisites for running Koios"
source_url: https://ai-ops.com/docs/installation/system-requirements
---

# System Requirements

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

> [!NOTE] 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](https://ai-ops.com/docs/installation/installing-docker.md) 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 |

> [!TIP] 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](https://ai-ops.com/docs/installation/virtual-machine.md) 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:

```bash
timedatectl status
```

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

```bash
sudo timedatectl set-ntp true
```

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

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

Then restart the service:

```bash
sudo systemctl restart systemd-timesyncd
```

> [!WARNING] Don
> 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](https://ai-ops.com/docs/installation/virtual-machine.md) — guidance for running Koios inside a VM
- [Installing Ubuntu](https://ai-ops.com/docs/installation/installing-ubuntu.md) — set up the host operating system
- [Installing Docker Engine](https://ai-ops.com/docs/installation/installing-docker.md) — install the Docker runtime