hcavarsan/kftray

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

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.

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 mise run sbom:scan.

SBOMs are generated with Syft in CycloneDX format for each artifact. Links below point to the latest release:

• kftray (desktop): SBOM · Vuln Report
• kftui (CLI): SBOM · Vuln Report
• kftray-server (Docker): SBOM · Vuln Report
• VEX Document (vulnerability exploitability assessments)

Attestation Verification

All release artifacts are signed with Cosign and verified with gh attestation verify. Verify them using the GitHub CLI:

gh attestation verify oci://ghcr.io/hcavarsan/kftray-server:latest --owner hcavarsan
gh attestation verify kftui_linux_amd64.tar.gz --owner hcavarsan
gh attestation verify kftray_<version>_amd64.AppImage --owner hcavarsan

Cosign SBOM Verification

SBOMs and VEX documents are signed with Cosign using the v3 bundle format:

curl -LO https://github.com/hcavarsan/kftray/releases/latest/download/sbom-kftray.cdx.json
curl -LO https://github.com/hcavarsan/kftray/releases/latest/download/sbom-kftray.cdx.json.bundle.json

cosign verify-blob \
  --bundle sbom-kftray.cdx.json.bundle.json \
  --certificate-identity-regexp "https://github.com/hcavarsan/kftray" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  sbom-kftray.cdx.json

SLSA Compliance

KFtray builds meet SLSA Level 2 requirements:

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 💻

Fili