Introduction
Manage Kubernetes port forwards from the desktop or terminal, with automatic reconnection and shared configs.
kftray is a cross-platform tool for managing Kubernetes port forwards. It adds automatic reconnection, UDP support, HTTP traffic logs and team configuration sharing.
kftray is the desktop app with tray integration, and kftui is the terminal UI. Both share the same Rust backend and configuration files. They use the Kubernetes watch API to see pods come and go, and they reconnect your forwards without you watching them.
For a tour of the desktop app and the terminal interface, watch the overview video. The overview blog post covers the background.
Why We Built This
We built kftray to handle recurring problems with kubectl port-forward during Kubernetes development:
Use Cases
Local microservices development
Forward your database, API gateway and backend services to localhost with one click or command.
Production debugging
Forward specific services for a while to investigate an issue, without setting up VPN tunnels.
Team onboarding
Share port-forward configs as JSON files or through GitHub repositories for new developers to import.
UDP services
Reach DNS, DHCP and other UDP-based services that kubectl port-forward can't.
Webhooks and demos
Expose a local server to the cluster or the internet with the expose workload, like a reverse tunnel.
MCP server
Let external clients manage port forwards through kftray with the MCP server.
Features
| Feature | Desktop (kftray) | Terminal (kftui) |
|---|---|---|
| Auto-reconnection when pods restart | Yes | Yes |
| Multiple forwards, started and stopped together | Yes | Yes |
Direct Kubernetes API access, no kubectl needed | Yes | Yes |
| TCP and UDP through a cluster proxy relay | Yes | Yes |
| HTTP traffic logs | Yes | Yes |
| Pod health tracking (shows which pod you're connected to) | Yes | Yes |
| Network recovery after sleep or disconnect | Yes | Yes |
| GitHub sync | Yes | Yes |
| Auto import from Kubernetes annotations | Yes | Yes |
| Custom kubeconfig path | Yes | Yes |
| Forward timeouts that close a forward after a time limit | Yes | Yes |
Hosts file management (updates /etc/hosts entries) | Yes | Yes |
| Automatic SSL certificates for forwards | Yes | Yes |
| Expose local services (reverse tunnel, like ngrok) | Yes | Yes |
| System tray integration | Yes | No |
| Request replay for HTTP logs | No | Yes |
Hosts file updates may need administrator privileges and vary by operating system. HTTP logs and replay can expose sensitive data, so turn them on only when you need them and sanitize what you share.
Two Interfaces, One Configuration
kftray comes in two versions that share the same configuration database:
Desktop (kftray) | Terminal (kftui) | |
|---|---|---|
| Best for | Visual management and system tray access | Keyboard-driven workflows, SSH and low resource use |
| Memory | ~100 MB | ~30 MB |
| Exclusive features | System tray integration | Request replay, SSH compatibility, tmux support, non-interactive mode |
| Shared features | HTTP traffic logging, GitHub sync, auto import, auto-reconnection, TCP/UDP, expose (reverse tunneling) | |
| Platform | macOS, Linux, Windows | macOS, Linux, Windows |
Both apps read configs.db in the same configuration directory (~/.kftray by default), so you can switch interfaces without copying configs. Set up a port forward in kftray and you see it in kftui. Save something in kftui and it shows up in kftray. See the Desktop Interface and Terminal Interface pages for instructions.
Usage at a Glance
You define port forwards as JSON configurations:
{
"alias": "gateway",
"context": "dev-cluster",
"namespace": "development",
"workload_type": "service",
"service": "api-gateway",
"protocol": "tcp",
"local_port": 8080,
"remote_port": 80
}Start the forward in either interface. kftray manages the connection and reconnects when pods restart. You can load configs from:
- Local JSON files
- GitHub repositories, public or private
- Kubernetes service annotations
- The command line (
kftui --jsonand--stdin)
For the full walkthrough, see the Quick Start.