installing kftray

getting kftray running depends on whether someone prefers a desktop interface or terminal interface. both work with the same configuration, so the choice comes down to workflow preference.

understanding the options

kftray (desktop) makes sense for visual configuration management and features like http traffic logging. kftui (terminal) works better for minimal resource usage, server environments, or when staying in command-line workflows.

both interfaces access the same configuration database, so someone can switch between them or use both depending on the situation.

desktop interface installation

macOS setup

the homebrew approach handles dependencies automatically:

brew tap hcavarsan/kftray
brew install --cask kftray

for manual installation, download the universal binary that works on both Intel and Apple Silicon macs. the dmg file includes the application bundle and handles system permissions.

linux desktop setup

homebrew works across most linux distributions:

brew tap hcavarsan/kftray
brew install kftray-linux

on GNOME-based distributions, the system tray requires AppIndicator support. install the AppIndicator extension for the system tray icon to appear properly.

for non-GNOME environments (KDE, XFCE, i3), the AppImage format typically works without additional setup.

windows desktop setup

windows users can download the installer for their architecture. the x64 installer covers most systems, while ARM64 specifically targets newer Windows ARM devices.

the installer handles PATH configuration and creates Start Menu entries automatically.

terminal interface installation

unix-like systems (linux, macOS, WSL)

the installer script handles platform detection and downloads the appropriate binary:

bash <(curl -s https://raw.githubusercontent.com/hcavarsan/kftray/main/hacks/kftui_installer.sh)

alternatively with wget:

bash <(wget -qO- https://raw.githubusercontent.com/hcavarsan/kftray/main/hacks/kftui_installer.sh)

this script installs to /usr/local/bin/kftui and requires sudo permissions for system-wide installation.

windows terminal setup

powershell installation handles the windows-specific setup:

Invoke-Expression ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/hcavarsan/kftray/main/hacks/kftui_installer.ps1'))

the installer adds the binary to PATH and creates the necessary directories.

manual installation approach

when automatic installers don't work (corporate networks, security policies), direct binary downloads provide an alternative.

desktop interface binaries

download the appropriate file for the target platform:

• macOS: kftray_universal.dmg works on all mac hardware
• Windows x64: kftray_x64-setup.exe for standard Windows systems
• Windows ARM: kftray_arm64-setup.exe for ARM Windows devices
• Linux x64: kftray_amd64.AppImage for most linux distributions
• Linux ARM: kftray_aarch64.AppImage for ARM-based linux systems

terminal interface binaries

similar platform-specific binaries are available:

• macOS: kftui_macos_universal
• Linux x64: kftui_amd64
• Linux ARM: kftui_arm64
• Windows x86: kftui_x86.exe
• Windows x64: kftui_x86_64.exe

all binaries are available from the latest GitHub release.

verifying the installation

desktop interface verification

launch kftray from the applications menu. the system tray should show the kftray icon (a small kubernetes logo). clicking the icon opens the main configuration interface.

if the tray icon doesn't appear on linux, check that AppIndicator support is installed and enabled.

terminal interface verification

run kftui from any terminal to launch the text interface. the application displays a configuration list (initially empty) with keyboard shortcuts at the bottom.

kftui

press Ctrl+C to exit the application.

common installation issues

permission problems

on macOS, the system may prevent unsigned applications from running. go to System Preferences > Security & Privacy and allow the kftray application to run.

on linux, AppImage files need execute permissions:

chmod +x kftray_amd64.AppImage

missing dependencies

the terminal interface is statically linked and doesn't require additional dependencies on most systems. the desktop interface may need system tray support, which varies by linux distribution.

network restrictions

corporate networks may block the installer scripts. in these cases, download the binary manually and place it in the appropriate location (/usr/local/bin for unix systems, or any directory in PATH).

configuration storage

both interfaces create configuration files in the user's home directory under .kftray/. this includes the configuration database, logs, and any cached data.

the configuration database is shared between both interfaces, so switching between desktop and terminal modes preserves all settings.

next steps

with either interface installed, the next step is creating port-forward configurations. the quick start guide walks through the basic workflow for both interfaces.