Installation Guide
Install the kftray desktop app or kftui terminal interface on macOS, Linux, or Windows.
Install
There are several ways to install kftray. Pick the method that matches your platform and preference, then move on to the Quick Start.
Desktop Interface (kftray)
Install via Homebrew (recommended):
brew tap hcavarsan/kftray
brew install --cask kftrayOr download kftray_universal.dmg from the latest release. The universal binary works on both Intel and Apple Silicon.
Terminal Interface (kftui)
brew tap hcavarsan/kftray
brew install kftuiManual Binary Downloads
If the installer scripts don't work in your environment (corporate firewalls, restricted networks), download binaries directly from the latest release:
| Platform | Desktop | Terminal |
|---|---|---|
| macOS (Universal) | kftray_universal.dmg | kftui_macos_universal |
| Linux x86_64 | kftray_amd64.AppImage | kftui_amd64 |
| Linux ARM64 | kftray_aarch64.AppImage | kftui_arm64 |
| Windows x64 | kftray_x64-setup.exe | kftui_x86_64.exe |
| Windows ARM64 | kftray_arm64-setup.exe | — |
Linux Packages
Every release publishes kftray and kftui packages for Debian, Ubuntu, Fedora, and openSUSE through the openSUSE Build Service. Add the repository once, then install either package with your package manager; updates arrive with the regular system upgrade. The commands below install kftui; replace it with kftray for the desktop app.
Replace Debian_12 with Debian_13, Ubuntu_22.04, Ubuntu_24.04, or Ubuntu_26.04:
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.opensuse.org/repositories/home:/hencavarsan:/kftray/Debian_12/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kftray.gpg
echo "deb [signed-by=/etc/apt/keyrings/kftray.gpg] https://download.opensuse.org/repositories/home:/hencavarsan:/kftray/Debian_12/ /" | sudo tee /etc/apt/sources.list.d/kftray.list
sudo apt update
sudo apt install kftuiPackages are signed with the project key of home:hencavarsan:kftray; the .repo files reference it and the apt source pins it with signed-by. The kftray package ships the AppImage and depends on fuse3; kftui depends on libdbus-1.
Verifying the Installation
Launch kftray from your applications menu. You should see a system tray icon (a small Kubernetes logo). Click it to open the main configuration interface.
Configuration Storage
Both interfaces store data in ~/.kftray/:
| File | Purpose |
|---|---|
kftray.db | SQLite database with all configurations and state |
app.log | Application logs |
http_logs/ | HTTP traffic captures (when enabled) |
This directory is shared between both interfaces, so configurations created in one appear instantly in the other.