A tool for managing Kubernetes port forwarding. Available as both a GUI desktop app and a TUI terminal app with feature parity.
| GUI (Desktop) | TUI (Terminal) |
![]() |
![]() |
- Visual port forwarding management
- Support for multiple Kubernetes contexts
- Real-time status monitoring
- Persistent configuration storage
- Context grouping with collapsible sections
- Persistent group collapse state and drag reordering
- Connection health verification and one-click reconnect
- SSH port forwarding support
- Local interface selection: 127.0.0.{x}
- Auto-suggest names based on service/context
- Search and filter configs
- Shared configuration between GUI and TUI
| GUI | TUI |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
- kubectl installed and configured
- At least one Kubernetes context configured
Built with Tauri (Rust + React). Cross-platform support for macOS, Windows, and Linux.
brew install --cask tonisives/tap/easy-kpfbrew install tonisives/tap/easykpfDownload the latest build from Releases, or build yourself!
pnpm install
make devpnpm tauri buildCreate the next patch release and start the GitHub Actions release workflow:
make releaseTo choose an explicit version instead:
make release VERSION=0.4.0Releases must be started from a clean main branch that matches origin/main.
Port forward configurations are stored in YAML files in the system config directory:
- macOS:
~/Library/Application Support/EasyKpf/ - Linux:
~/.config/EasyKpf/ - Windows:
%APPDATA%/EasyKpf/
port-forwards.yaml- Port forward definitionsapp-config.yaml- Application settings (kubectl path, kubeconfig path)
configs:
- name: "My Service"
context: "minikube"
namespace: "default"
service: "my-service"
ports: ["8080:80", "9090:9090"]Configuration files are automatically created with defaults on first run.
EasyKpf automatically replaces a failed forward with exponential backoff. A forward is considered recovered after the replacement process remains alive for the configured stability period. Explicitly stopping a forward cancels pending reconnect attempts.
Recovery can be shared by Kubernetes context or SSH host, then overridden for an individual forward. The lookup order is:
- The forward's own
recovery - Its entry under
recovery.kubernetes_contextsorrecovery.ssh_hosts - Built-in reconnect defaults
For example:
recovery:
kubernetes_contexts:
tgs:
reconnect:
enabled: true
initial_delay_ms: 1000
max_delay_ms: 30000
stable_after_seconds: 30
max_attempts: 0
hooks:
before_reconnect:
- type: command
command: /bin/launchctl
args:
- kickstart
- -k
- gui/501/com.example.kubernetes-tunnel
timeout_seconds: 15
cooldown_seconds: 30
ssh_hosts:
job-host:
reconnect:
enabled: true
hooks:
before_reconnect:
- type: ssh
ssh_host: bastion
command: sudo systemctl restart job-tunnel
args: []
configs:
- name: db gp
context: tgs
namespace: infra
service: postgres-gp-1-cluster-rw
ports: ["8101:5432"]
- name: job service
context: job-host
namespace: default
service: job-host
ports: ["8102:8080"]
forward_type: Ssh
- name: special job
context: job-host
namespace: default
service: job-host
ports: ["8103:8080"]
forward_type: Ssh
recovery:
reconnect:
enabled: true
hooks:
before_reconnect:
- type: ssh
ssh_host: bastion
command: sudo systemctl restart special-job-tunnel
args: []The built-in defaults retry indefinitely (max_attempts: 0), starting after
one second and backing off to 30 seconds. Local hooks are executed directly as
a command and argument list; EasyKpf does not evaluate them through a shell.
SSH hooks run the configured command on their forward's ssh_host in batch
mode. Cooldowns deduplicate identical hooks, which prevents several forwards
that share one upstream tunnel from restarting it repeatedly.
Local hook processes receive these environment variables:
EASY_KPF_EVENT:failure,before_reconnect, orrecoveredEASY_KPF_SERVICE: the configured forward nameEASY_KPF_ERROR: the error that initiated or most recently blocked recoveryEASY_KPF_ATTEMPT: the current reconnect attempt number
on_failure runs once when a managed forward fails. before_reconnect runs
before each reconnect attempt. on_recovered runs after the replacement
survives stable_after_seconds.
Each Kubernetes context and SSH host group has a Recovery action for its shared policy. Each forward's Settings dialog has another Recovery action for an exception. Additional lifecycle hooks can be added directly to YAML and are preserved when the UI saves a forward or shared policy.
A macOS recovery script for a launch agent can be as small as:
#!/bin/sh
exec /bin/launchctl kickstart -k "gui/$(id -u)/com.example.kubernetes-tunnel"- Frontend: React + TypeScript + Vite
- Backend: Rust + Tauri
- Kubernetes integration via kubectl






