Installation Guide

This guide shows how to install the KOSI command line interface.

Tags:

5 minute read

In this quickstart you will learn about:

KOSI system requirements
how to install KOSI
how to use the official KubeOps Website to download KOSI
how to install required software

KOSI seamlessly integrates with other package management software such as Helm and Podman. To ensure compatibility across different containerized environments, KOSI requires the installation of this software.

After the installation, KOSI is available as command line interface.

Note We recommend to install KOSI onto the admin machine of a cluster.

Prerequisites

To get the most out of this guide, the following requirements should be met:

basic understanding of Linux environments, bash / shell
sudo privileges (root) to install packages

Step 1 - System Requirements

Make sure you have prepared the listed requirements before installing KOSI.

KOSI is designed to work with the latest versions of the following operating systems:

OS	Diskspace
Red Hat Enterprise Linux 9.6 and newer	500 MB
Ubuntu 24.04 and newer	500 MB

Important

By default Red Hat Enterprise Linux restricts package management such as installing or updating. Before installing any software, you may need to register and subscribe with the Red Hat Customer Portal.

To register and subscribe, run the command subscription-manager register.

Step 2 - Include Package Repo

To easily install the kosi package you should add the kubeops package repo to your operating system’s package manager.

wget https://packagerepo.kubeops.net/pgp-key.public
cat pgp-key.public | sudo gpg --dearmor -o /usr/share/keyrings/kubeops.gpg
echo 'deb [arch=amd64 signed-by=/usr/share/keyrings/kubeops.gpg] https://packagerepo.kubeops.net/deb stable main' | sudo tee /etc/apt/sources.list.d/kubeops.list
sudo apt update

sudo dnf config-manager --add-repo https://packagerepo.kubeops.net/rpm/kubeops.repo

Step 3 - Install KOSI

There are two ways to install kosi.

a) quick via the package repo of your operating system’s package manager.

sudo apt update
sudo apt install -y kosi=2.14*

sudo dnf install -y --disableexcludes=kubeops-repo kosi-2.14.0.0-0

b) manual download the kosi package from the official KubeOps Website and install it.

Downloading KOSI

Login into your KubeOps account. If you don‘t have an account, you can create one by following the instructions for Create a KOSI account (with SSO).

Download your desired version of the KOSI package file (.rpm or .deb) from the official download page.

# download kosi deb manually and install with
sudo dpkg --install kosi_2.14.0.0-1_amd64.deb

# download kosi rpm manually and install with
sudo rpm --install -v kosi-2.14.0.0-0.x86_64.rpm

Step 4 - Set the KUBEOPSROOT env var

Set KUBEOPSROOT and XDG_RUNTIME_DIR in ~/.bashrc

⚠ Warning This file entry has to be adapted to your values before usage.

# file ~/.bashrc
# Append these values to the end of your ~/.bashrc file
export KUBEOPSROOT=/home/<yourUser>/kubeops
export XDG_RUNTIME_DIR=$KUBEOPSROOT

Source .bashrc to apply the values

source ~/.bashrc
echo $KUBEOPSROOT
echo $XDG_RUNTIME_DIR

As a result you should see your KUBEOPSROOT-path two times.

Step 5 - Adjust KOSI Configuration

This creates a kubeops directory in your home directory and transfers all necessary files, e.g., the kosi-config and the plugins, to it.

mkdir ~/kubeops
cd ~/kubeops
cp -R /var/kubeops/kosi/ .
cp -R /var/kubeops/plugins/ .

The config.yaml is in your KUBEOPSROOT-path (typically in ~/kubeops/kosi)

Set hub in your kosi config to hub: https://dispatcher.kubeops.net/v4/dispatcher/

⚠ Warning This file entry has to be adapted to your values before usage.

Set the “plugins”-entry in your kosi config to plugins: /home/<yourUser>/kubeops/plugins, where is changed to your username

⚠ Warning This file has to be adapted to your values before usage.

# file $KUBEOPSROOT/kosi/config.yaml
apiversion: kubernative/sina/config/v2

spec:
  hub: https://dispatcher.kubeops.net/v4/dispatcher/ # <-- set hub url
  plugins: <your kubeopsroot>/kubeops/plugins/ # <-- set the path to your plugin folder (~ for home or $KUBEOPSROOT don't work, it has to be the full path)
  workspace: /tmp/kosi/process/
  logging: info
  housekeeping: false
  proxy: false

Step 6 - Install KOSI enterprise plugins

kosi install --hub kosi-enterprise kosi/enterprise-plugins:2.0.0

Step 7 - Install Podman

To ensure compatibility across different containerized environments, KOSI requires the installation of Podman (latest version).

Install Podman using the inbuilt package manager.

sudo apt update
sudo apt install -y podman

sudo dnf install -y podman

Step 8 - Install Helm

Many KOSI packages use helm. Therefore, it is recommended to install helm.

Install Helm using the KubeOps package repo.

sudo apt update
sudo apt install -y helm

sudo dnf install -y helm

Verify your Installation

To verify the installation of KOSI on your system, use the command kosi version.

kosi version

The output displays the KOSI version along with relevant information. It confirms the successful installation of KOSI.

2026-01-23 16:09:55 Info:      KOSI version: 2.14.0.0
2026-01-23 16:09:55 Info:      Latest KOSI-package-apiversion: kubernative/kubeops/sina/user/v4
2026-01-23 16:09:55 Info:      Latest KOSI-lanugage-version is: 1.0.0
2026-01-23 16:09:55 Info:      This work is licensed under Creative Commons Attribution - NoDerivatives 4.0 International License(see https://creativecommons.org/licenses/by-nd/4.0/legalcode for more details).
2026-01-23 16:09:55 Info:      © KubeOps GmbH, Hinter Stöck 17, 72406 Bisingen - Germany, 2025

Check if you can log in with the command kosi login.

kosi login -u <yourUser>

The output confirms that you are successfully loged in.

2026-01-23 16:11:40 Info:      KOSI version: 2.14.0.0
2026-01-23 16:11:47 Info:      Login Succeeded to Hub.
2026-01-23 16:11:48 Info:      The login to registry was successful. You are now logged in as kubeops and can use the public and private registry.