Website | Downloads | Blog

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.

Features Matrix

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	❌	✅

_{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.}

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 --json and --stdin)

Workload Types

kftray supports multiple workload types for different use cases:

• 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:

1. Config Management – Load port forward configs from files/GitHub/K8s annotations
2. Pod Discovery – Find target pods using label selectors or service definitions
3. Connection Setup – Establish websocket connection to K8s API
4. Traffic Relay – Forward traffic between local ports and pod ports
5. 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.

Development

Want to contribute or build from source? We use mise to manage the development environment.

Quick start:

# Install mise
curl https://mise.run | sh

# Clone and setup
git clone https://github.com/hcavarsan/kftray.git
cd kftray
mise install        # Install all tools
mise run setup      # Setup dependencies
mise run dev        # Start development

Available commands:

• mise run dev - Start development mode
• mise run build - Build production app
• mise run format - Format code
• mise run lint - Lint with auto-fix
• mise run test:back - Run tests

See DEVELOPMENT.md for the complete development guide.

Contributing

We're always looking for contributions. Whether it's bug fixes, new features, or just ideas, we'd love to hear from you.

• Pull Requests – Fork, code, and submit
• Issues – Report bugs or request features
• Discussions – Share ideas and feedback

Check out CONTRIBUTING.md for guidelines

License

kftray is available under the GPL 3.0 License.

Star History

Contributors

Thanks goes to these wonderful people (emoji key):

Henrique Cavarsan 💻

Filipe Andujar 💻

Ikko Eltociear Ashimine 💻

Honsun Zhu 💻

Peter Hansson 💻

FabijanZulj 💻

This project follows the all-contributors specification. Contributions of any kind welcome!