Kftray
kubectl port-forward manager and reverse tunnel (ngrok-like) for exposing local services publicly, with TLS termination, HTTP traffic inspection, UDP forwarding, multi-hop proxy routing through k8s clusters, stateful config via filesystem or git - GUI and TUI available
Install / Use
/learn @hcavarsan/KftrayREADME
About
kftray and kftui are Kubernetes port forwarding tools that actually work the way you'd expect them to. While kubectl port-forward is fine for quick tasks, it falls apart when pods restart or connections drop – and you're stuck manually reconnecting.
Both kftray (desktop app with tray integration) and kftui (terminal UI) share the same Rust backend and configuration files. They use the Kubernetes watch API to detect when pods come and go, automatically reconnecting your forwards without you having to babysit them. They handle TCP and UDP through a proxy relay in your cluster, support multiple forwards at once, and can even log HTTP traffic for debugging.
To download apps, you can check the download page on the kftray website.
Why Another Port Forwarding Tool?
There are plenty of Kubernetes tools out there, but port forwarding has always been weirdly neglected. The main issues with kubectl port-forward:
- Connections break when pods restart or get rescheduled
- No automatic reconnection – you have to manually restart everything
- Multiple forwards means multiple terminal windows
- No UDP support out of the box
- No way to debug HTTP traffic flowing through the tunnel
The tools monitor pod lifecycle events and automatically reconnect to healthy pods when things go sideways. You can manage dozens of forwards from a single interface, forward UDP traffic through a proxy relay, and inspect HTTP requests/responses when you need to debug.
check out our blog post at kftray.app/blog/posts/13-kftray-manage-all-k8s-port-forward.
<br> <div align="center"> <table> <tr> <td> <a href="https://youtu.be/3pIDGB6Tx_o"> <img src="https://img.youtube.com/vi/3pIDGB6Tx_o/maxresdefault.jpg" alt="Watch the video" width="800px"> </a> </td> <td> <a href="https://www.youtube.com/watch?v=Zvv9gIhLaSM"> <img src="https://img.youtube.com/vi/Zvv9gIhLaSM/maxresdefault.jpg" alt="Watch the video" width="800px"> </a> </td> </tr> </table> </div> <br>Features Matrix
<div align="center">| Feature | kftray (Desktop) | kftui (Terminal) | |---------|------------------|------------------| | Auto-reconnection – Reconnects when pods restart | ✅ | ✅ | | Multiple forwards – Start/stop many at once | ✅ | ✅ | | No kubectl needed – Direct K8s API integration | ✅ | ✅ | | TCP/UDP support – Via cluster proxy relay | ✅ | ✅ | | HTTP traffic logs – Inspect requests/responses | ✅ | ✅ | | Pod health tracking – Shows which pod you're connected to | ✅ | ✅ | | Network recovery – Auto-reconnects after sleep/disconnect | ✅ | ✅ | | GitHub sync – Share configs with your team | ✅ | ✅ | | Auto-import – Discover services via K8s annotations | ✅ | ✅ | | Custom kubeconfig – Use any kubeconfig path | ✅ | ✅ | | Port-forward timeouts – Auto-close after time limit | ✅ | ✅ | | Hosts file management – Auto-update /etc/hosts entries | ✅ | ✅ | | Auto SSL – Automatic SSL certificate generation for port forwards | ✅ | ✅ | | Expose local services – Reverse tunnel local apps to cluster/internet (like ngrok) | ✅ | ✅ | | System tray integration – Quick access from tray | ✅ | ❌ | | Request replay – Replay HTTP requests for debugging | ❌ | ✅ |
<sub>Notes: (1) Hosts file updates may require admin privileges and vary by OS. (2) HTTP logs/replay can expose sensitive data—opt-in and sanitize where needed.</sub>
</div>kftray - Desktop App
The desktop app runs in your system tray and provides a GUI for managing port forwards.
- Installation – Download and install
- Usage Guide – How to use kftray
- Building from Source – Build it yourself
kftui - Terminal UI
The terminal interface for those who prefer staying in the console.
- Installation – Install via Homebrew, Cargo, or download
- Usage Guide – Terminal shortcuts and features
- Building from Source – Build instructions
kftray-server - Proxy Relay
The proxy relay that runs in your cluster to handle TCP/UDP forwarding.
- Architecture Docs – How it all works
Configuration
Both tools share the same JSON configuration format. Here's a example:
[
{
"alias": "argocd",
"context": "kind-kftray-cluster",
"kubeconfig": "/Users/henrique/.kube/kind-config-kftray-cluster",
"local_port": 16080,
"namespace": "argocd",
"protocol": "tcp",
"remote_port": 8080,
"service": "argocd-server",
"workload_type": "service",
"http_logs_enabled": true
}
]
You can import configs from:
- Local JSON files
- GitHub repositories (public or private)
- Direct from your cluster using service annotations
- Command line (kftui supports
--jsonand--stdin)
Workload Types
kftray supports multiple workload types for different use cases:
<img src="https://raw.githubusercontent.com/hcavarsan/homebrew-kftray/main/img/workload_types.png" alt="Workload Types" />- service - Forward to a Kubernetes service (TCP/UDP)
- pod - Forward directly to pods using label selectors (TCP/UDP)
- proxy - Tunnel to external resources via the cluster (TCP/UDP)
- expose - Reverse tunnel your local services to the cluster or internet
Expose: Reverse Tunneling
The expose workload type lets you share your local development server with your team or expose it to the internet through your Kubernetes cluster. This is useful for:
- Testing webhooks locally with external services
- Sharing work-in-progress features with teammates
- Running local services that need to be accessible from the cluster
Example: Expose local service to the internet
{
"alias": "myapp.example.com",
"namespace": "production",
"local_port": 3000,
"local_address": "localhost",
"context": "my-k8s-cluster",
"workload_type": "expose",
"protocol": "tcp",
"domain_enabled": true,
"exposure_type": "public",
"cert_manager_enabled": true,
"cert_issuer": "letsencrypt-prod",
"cert_issuer_kind": "ClusterIssuer",
"ingress_class": "nginx"
}
Example: Expose to cluster internal network only
{
"alias": "internal-api",
"namespace": "development",
"local_port": 8080,
"local_address": "localhost",
"context": "my-k8s-cluster",
"workload_type": "expose",
"protocol": "tcp",
"domain_enabled": true,
"exposure_type": "internal"
}
For more examples, see the examples directory.
Under the hood
The tools use a shared Rust core that handles all the Kubernetes interaction. Here's the basic flow:
- Config Management – Load port forward configs from files/GitHub/K8s annotations
- Pod Discovery – Find target pods using label selectors or service definitions
- Connection Setup – Establish websocket connection to K8s API
- Traffic Relay – Forward traffic between local ports and pod ports
- Health Monitoring – Watch for pod changes and reconnect as needed
For UDP or when you need to reach external services, we deploy a small relay pod in your cluster that handles the actual forwarding.
Recent Updates
Check the releases page for the full changelog.
Security and SBOM
Releases are blocked if critical or high severity vulnerabilities are found. The CI scans frontend, backend, Docker image, and GitHub Actions using Grype before publishing. You can run the same scan locally with
