---
title: "Running Multiple Instances"
description: "Run several Koios containers on one host with explicit port mapping"
source_url: https://ai-ops.com/docs/installation/running-multiple-instances
---

# Running Multiple Instances

You can run more than one Koios container on a single host, for example to separate lines, sites, or test environments on shared hardware. Each instance keeps its own database, history, certificates, and license in its own set of named volumes, so the instances stay fully isolated.

The one thing that has to change from a single-instance install is networking. The recommended `--network host` flag binds the container directly to host ports 443 and 80, so a second instance started the same way would fail to bind. To run several instances side by side, give each one **explicit port mappings** and its **own volume set**.

## Map Each Instance to a Unique Port

Replace `--network host` with `-p` mappings and pick a distinct host port for each instance's HTTPS port (443). Give every instance its own container name and its own seven volumes:

```bash
# Instance A, reachable at https://<host>:8443
docker run -d --name koios-a \
  -p 8443:443 \
  --mount source=koios_a_postgres,target=/var/lib/postgresql/16/main \
  --mount source=koios_a_influxdb,target=/root/.influxdbv2 \
  --mount source=koios_a_media,target=/var/www/koios/media \
  --mount source=koios_a_logs,target=/var/www/koios/logs \
  --mount source=koios_a_certs,target=/var/www/koios/certs \
  --mount source=koios_a_license,target=/var/www/koios/license \
  --mount source=koios_a_secrets,target=/var/www/koios/secrets \
  aiopinc/koios:latest

# Instance B, reachable at https://<host>:8444
docker run -d --name koios-b \
  -p 8444:443 \
  --mount source=koios_b_postgres,target=/var/lib/postgresql/16/main \
  --mount source=koios_b_influxdb,target=/root/.influxdbv2 \
  --mount source=koios_b_media,target=/var/www/koios/media \
  --mount source=koios_b_logs,target=/var/www/koios/logs \
  --mount source=koios_b_certs,target=/var/www/koios/certs \
  --mount source=koios_b_license,target=/var/www/koios/license \
  --mount source=koios_b_secrets,target=/var/www/koios/secrets \
  aiopinc/koios:latest
```

Each instance is then reached at `https://<host>:<port>`, for example `https://<host>:8443` and `https://<host>:8444`. Log in to each one separately; every instance has its own `admin` account and its own license.

A few rules keep the instances isolated:

- **A unique host port per instance.** Only one container can own a given host port. Map the container's 443 to a different host port for each instance. You rarely need to map 80, since you connect to each instance by its HTTPS port directly.
- **A unique volume set per instance.** Each container needs its own seven volumes (`koios_a_*`, `koios_b_*`, and so on). Never share a volume between instances, as doing so will corrupt data.
- **A unique container name.** Use `--name koios-a`, `koios-b`, and so on, so Docker can tell them apart.

> [!WARNING] Device connectivity without host networking
> `--network host` lets a container reach industrial devices directly on the host network. Without it, a container only sees the ports you map. If an instance polls devices over OPC-UA, Modbus, or EtherNet/IP, make sure its container can route to them, for example by mapping the relevant device ports or attaching the container to a Docker network that can reach the plant network.

## Run Each Instance as a Service

Most deployments run each instance as its own systemd service so it starts on boot and restarts on failure. Give every instance its own unit file, named for the instance (for example `docker.koios-a.service`).

Create the unit for the first instance:

```bash
sudo nano /etc/systemd/system/docker.koios-a.service
```

Paste a unit that carries the same explicit port and volume set from above:

```ini
[Unit]
Description=Koios (instance A)
After=docker.service
Requires=docker.service

[Service]
Restart=always
RestartSec=5
ExecStartPre=-/usr/bin/docker rm -f koios-a
ExecStart=/usr/bin/docker run --rm --name koios-a \
  -p 8443:443 \
  --mount source=koios_a_postgres,target=/var/lib/postgresql/16/main \
  --mount source=koios_a_influxdb,target=/root/.influxdbv2 \
  --mount source=koios_a_media,target=/var/www/koios/media \
  --mount source=koios_a_logs,target=/var/www/koios/logs \
  --mount source=koios_a_certs,target=/var/www/koios/certs \
  --mount source=koios_a_license,target=/var/www/koios/license \
  --mount source=koios_a_secrets,target=/var/www/koios/secrets \
  aiopinc/koios:latest
ExecStop=/usr/bin/docker stop koios-a

[Install]
WantedBy=default.target
```

Enable and start it:

```bash
sudo systemctl daemon-reload
sudo systemctl enable docker.koios-a.service
sudo systemctl start docker.koios-a.service
```

Then repeat for each additional instance, changing four things in every copy: the **unit file name** (`docker.koios-b.service`), the **container name** (`koios-b`), the **host port** (`-p 8444:443`), and the **volume set** (`koios_b_*`). Keeping these four distinct is what lets the instances coexist on one host.

Check any instance with `systemctl status docker.koios-a.service`, and follow its logs with `docker logs -f koios-a`. See [Running Koios as a Service](https://ai-ops.com/docs/installation/running-as-a-service.md) for the single-instance walkthrough, firewall notes, and version pinning.

## Manage the Fleet from One Place

Once several instances are running, the [Koios Admin Console](https://ai-ops.com/docs/admin-console/introduction.md) gives you a single view of their health, service state, and licenses. Connect each instance by its `host:port` from the console's [Instances page](https://ai-ops.com/docs/admin-console/managing-instances.md) and monitor them all without signing into each one.