Koncierge UI is a cross-platform application designed to simplify the management of Kubernetes port forwards. It offers an intuitive interface for viewing pods, services, and managing port forwarding sessions across multiple clusters and namespaces.
Key Features:
Multi-Cluster Support: Manage port forwards across different Kubernetes clusters and contexts with ease.
Resource Browser: Access comprehensive views of pods and services, complete with filtering options by namespace, status, type, and name.
Secret Management: Link Kubernetes secrets to port forwards for secure credential handling, featuring auto-copy functionality and secret resolution.
User-Friendly Experience: Toggle between dark/light themes, enjoy multi-language support, and benefit from detailed connection logging and persistent preferences.
Cross-Platform Availability: Available on Windows, macOS, iOS (experimental), and Android (experimental), with a command-line interface for scriptable automation.
Audience & Benefit:
Ideal for Kubernetes users, DevOps engineers, and cloud developers seeking to streamline port-forwarding management. Koncierge UI reduces complexity and potential errors associated with manual kubectl commands, enabling efficient resource monitoring and secure secret handling across environments.
Koncierge UI can be installed via winget, ensuring a seamless setup process on supported platforms.
README
Koncierge UI
A modern, cross-platform Kubernetes port-forwarding manager
Koncierge UI is a cross-platform Kubernetes port-forwarding manager available both as a desktop application (built with .NET MAUI and Blazor) and a command-line interface. It provides an intuitive way to manage multiple port-forwards across different clusters, namespaces, and services without needing to remember complex kubectl commands.
Features
🔗 Port Forwarding Management
Easy port-forward creation - Forward ports from pods and services with just a few clicks
Template system - Save frequently used port-forward configurations as reusable templates
Auto port assignment - Use random ports (port 0) for automatic assignment of available local ports
Multi-cluster support - Manage port-forwards across multiple Kubernetes clusters and contexts
🔍 Resource Browser
Pod browser - View and filter pods by namespace, status, and name
Service browser - Browse services with filtering by namespace and type
Multi-select filters - Filter resources using multiple namespaces or statuses simultaneously
Real-time status - See pod status with color-coded indicators
🔐 Secret Management
Linked secrets - Associate Kubernetes secrets with port-forwards
Auto-copy credentials - Quickly copy secret values to clipboard
Secret resolution - Automatically resolve and display secret values for running forwards
🎨 User Experience
Dark/Light themes - Automatic theme detection with manual override
Multi-language support - Internationalization ready (English and more)
Connection logging - Detailed logs for each port-forward connection
Persistent preferences - Remember your selected cluster, theme, and language
💻 Cross-Platform
Windows - Native Windows 10/11 support
macOS - MacCatalyst support for Intel and Apple Silicon
iOS - iPad support (experimental)
Android - Tablet support (experimental)
⌨️ Command-Line Interface
Interactive mode - Full menu-driven interface in the terminal
Scriptable commands - Individual commands for automation and scripting
Shared configuration - Uses the same templates and preferences as the GUI
Watch mode - Monitor forwards with live log updates
Rich output - Tables, colors, and status indicators
Installation
Prerequisites
.NET 9 SDK (for building from source)
A valid kubeconfig file with cluster access
Windows - WinGet (Recommended)
# Install the desktop application (with desktop shortcut)
winget install DavideMaggi.KonciergeUI
# Install the CLI tool
winget install DavideMaggi.Koncierge
Windows - Chocolatey
# Install the desktop application
choco install konciergeui
# Install the CLI tool
choco install koncierge
Windows - Manual Installation
Download the latest release from the Releases page:
Desktop Application:
Installer (KonciergeUI-setup-X.Y.Z.exe): Recommended, creates desktop shortcut and adds konciergeui to PATH
Portable (KonciergeUi-win-X.Y.Z.zip): Extract and run KonciergeUI.exe
CLI Tool:
Installer (Koncierge-cli-setup-X.Y.Z.exe): Adds koncierge command to PATH
Portable (Koncierge-cli-win-X.Y.Z.zip): Extract and run Koncierge.exe
macOS / Linux
Build from source (see below) or download platform-specific releases when available.
Build from Source
# Clone the repository
git clone https://github.com/davidemaggi/koncierge-ui.git
cd koncierge-ui
# Restore dependencies
dotnet restore
# Build the solution
dotnet build
# Run the application (Windows)
dotnet run --project KonciergeUi.Client -f net9.0-windows10.0.19041.0
# Run the application (macOS)
dotnet run --project KonciergeUi.Client -f net9.0-maccatalyst
Getting Started
1. Add Your Kubeconfig
On first launch, click "Add Kubeconfig" to import your Kubernetes configuration file. Koncierge UI will automatically discover all clusters and contexts defined in the file.
2. Select a Cluster
Use the cluster dropdown to select which Kubernetes cluster you want to work with.
3. Browse Resources
Navigate through the Pods or Services tabs to view available resources. Use the filters to narrow down by:
Namespace (multi-select)
Status (for pods)
Type (for services)
Free text search
4. Create a Port Forward
Click the "Forward" button on any port to create a new port-forward. Configure:
Local port (or use 0 for automatic assignment)
Protocol hint (HTTP, TCP, gRPC)
Optional linked secrets
5. Save as Template (Optional)
Once you have configured your forwards, click "Create Template" to save the configuration for future use.
Usage
Managing Templates
Templates allow you to save and quickly start multiple port-forwards at once.
Create forwards from pods/services
Click "Create Template"
Give it a name and description
Start the template with one click from the Templates page
Viewing Active Forwards
Navigate to the Active Forwards page to see all running port-forwards. From here you can:
View connection logs
Copy linked secret values
Stop individual forwards or entire templates
Filtering Resources
All resource tables support advanced filtering:
Multi-select namespaces - Select multiple namespaces to view
Multi-select statuses - Filter by multiple pod statuses
Text search - Search by name across all visible resources
Clearable filters - Use the X button to reset filters
Koncierge UI also includes a powerful command-line interface for users who prefer terminal-based workflows or need to integrate with scripts and automation.
Installation
# Via WinGet (recommended)
winget install DavideMaggi.Koncierge
# After installation, the 'koncierge' command is available globally
koncierge --help
Running the CLI (from source)
# Run directly with dotnet
dotnet run --project KonciergeUI.Cli
# Or build and run the executable
dotnet build KonciergeUI.Cli
./KonciergeUI.Cli/bin/Debug/net9.0/Koncierge
Interactive Mode
Start the full interactive menu with all features:
koncierge interactive
# or
koncierge i
The interactive mode provides a guided menu for:
🔄 Switching clusters
📋 Listing pods and services
🔐 Viewing secrets and ConfigMaps
▶️ Creating quick port forwards
📁 Managing templates
📊 Viewing active forwards
CLI Commands
Cluster Management
# List all available clusters
koncierge cluster list
# Select a cluster interactively or by name
koncierge cluster select
koncierge cluster select my-cluster
Resource Listing
# List pods (with optional namespace and cluster filters)
koncierge pods list
koncierge pods list -n kube-system -c my-cluster
# List services
koncierge services list
koncierge services list -n default
# List secrets and ConfigMaps
koncierge secrets list -n default
koncierge secrets list --show-values
Port Forwarding
# Create a quick port forward interactively
koncierge forward create
# Create with options
koncierge forward create -n default -t service -r my-service -p 8080 -l 8080
# List active forwards
koncierge forward list
# Stop a forward
koncierge forward stop
koncierge forward stop --all
Template Management
# List saved templates
koncierge template list
# Run a template
koncierge template run
koncierge template run "My Template" -c my-cluster
# Run with watch mode (shows logs and status updates)
koncierge template run "My Template" --watch
# Stop a running template
koncierge template stop
koncierge template stop --all
# Create a new template interactively
koncierge template create
CLI Features
Shared configuration - CLI uses the same templates and preferences as the GUI application
Interactive prompts - When options are not provided, the CLI prompts for input with smart defaults
Rich terminal output - Tables, colors, and status indicators using Spectre.Console
Watch mode - Monitor running forwards with live log updates
Secret resolution - View resolved secrets and ConfigMaps for running forwards
Example Workflow
# 1. List and select a cluster
koncierge cluster list
koncierge cluster select production
# 2. Browse resources
koncierge pods list -n backend
koncierge services list -n backend
# 3. Run a saved template with logging
koncierge template run "Backend Dev" --watch
# 4. Or create a quick forward
koncierge forward create -t service -r api-gateway -p 8080
# 5. View active forwards
koncierge forward list
# 6. Stop when done
koncierge forward stop --all
FAQ
General
Q: What Kubernetes versions are supported?
A: Koncierge UI uses the official Kubernetes C# client and supports any cluster version compatible with the client library (typically 1.20+).
Q: Can I use multiple kubeconfig files?
A: Yes! You can add multiple kubeconfig files, and Koncierge UI will aggregate all clusters and contexts.
Q: Where are my settings stored?
A: Settings are stored in a JSON file in your platform's application data folder.
Port Forwarding
Q: What does "Random" port mean?
A: When you set the local port to 0, the system automatically assigns an available port. The actual port number is displayed once the forward starts.
Q: Why can't I start a template?
A: The "Start Template" button is disabled if any of the configured ports are already in use by another running forward. Check the tooltip for details on which ports conflict.
Q: How does service port forwarding work?
A: When forwarding a service, Koncierge UI resolves the actual pod behind the service and uses the correct targetPort (container port), not the service port.
Q: Why did my forward fail with "connection refused"?
A: This usually means the application inside the pod is not listening on the specified port. Verify the pod is running and the port is correct.
Troubleshooting
Q: Emoji render as "??" in the CLI on Windows
A: This is usually a console/font limitation. Use Windows Terminal or PowerShell 7, and pick a font with emoji support (for example, Segoe UI Emoji or Cascadia Code PL). If you run from cmd.exe, verify the code page is UTF-8 with chcp 65001.
Q: Resources are not loading after changing clusters
A: Make sure you have proper RBAC permissions on the target cluster. Check the connection logs for detailed error messages.
Q: Theme doesn't apply correctly on startup
A: The theme is resolved after the first render. This is normal behavior to support system theme detection.
Q: Filters persist after changing clusters
A: This was a known issue and has been fixed. Filters now reset automatically when you change clusters.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
