kportal logo

Kubernetes Port-Forward
Manager

Terminal interface for managing multiple Kubernetes port-forwards with auto-reconnect, hot-reload, health monitoring, and mDNS hostnames.

Get Started View on GitHub
Version License Go Report
kportal terminal interface

Features

Everything you need for production-grade port-forwarding

Interactive TUI

Beautiful terminal interface with real-time updates and keyboard navigation

Live Management

Add, edit, delete, and toggle port-forwards without restarting

Auto-Reconnect

Exponential backoff retry with infinite retries on connection failures

Hot-Reload

Configuration changes applied automatically without restart

Health Monitoring

Multiple check methods with stale connection detection

mDNS Hostnames

Access forwards via .local hostnames without /etc/hosts

Multi-Context

Manage forwards across multiple clusters and namespaces

Pod Restart Handling

Automatic reconnection when pods restart or reschedule

Port Conflict Detection

Validates port availability with process ID information

HTTP Traffic Logging

Real-time HTTP logging with filters (Non-2xx, Errors, Search)

Connection Benchmarking

Built-in HTTP benchmarking with latency percentiles

Headless Mode

Background operation for scripting and automation

Installation

Get started in seconds

Homebrew

macOS & Linux

brew install lukaszraczylo/brew-taps/kportal

Quick Install

All platforms

curl -fsSL https://raw.githubusercontent.com/lukaszraczylo/kportal/main/install.sh | bash

Manual Download

Linux, macOS, Windows (amd64 & arm64)

Download from GitHub Releases

Usage

Simple commands, powerful results

Interactive Mode

kportal

Launch the interactive TUI with real-time status updates and keyboard controls.

Verbose Mode

kportal -v

Run with detailed logging for debugging and automation.

Validate Config

kportal --check

Validate configuration without starting any forwards.

Custom Config

kportal -c /path/to/config.yaml

Use a custom configuration file instead of .kportal.yaml

Headless Mode

kportal -headless -v &

Run without TUI for scripting and background operation.

Keyboard Shortcuts

↑↓ Navigate
Space Toggle forward
a Add forward
e Edit forward
d Delete forward
j/k Vim navigation
b Benchmark
l HTTP logs

Status Indicators

● Active
○ Starting
◐ Reconnecting
✗ Error
○ Disabled

Configuration

Simple YAML configuration with powerful options

Basic Configuration 
contexts:
  - name: production
    namespaces:
      - name: backend
        forwards:
          - resource: service/postgres
            protocol: tcp
            port: 5432
            localPort: 5432
            alias: prod-db

          - resource: pod/nginx
            protocol: tcp
            port: 80
            localPort: 8080
With mDNS & Health Checks 
mdns:
  enabled: true

healthCheck:
  interval: "3s"
  method: "data-transfer"
  maxConnectionAge: "25m"

contexts:
  - name: production
    namespaces:
      - name: default
        forwards:
          - resource: service/postgres
            port: 5432
            localPort: 5432
            alias: db  # db.local

Resource Types

  • service/name Service
  • pod/name Pod by name
  • pod/prefix Pod by prefix
  • deployment/name Deployment

Label Selectors

  • resource: pod
  • selector: app=nginx
  • Dynamically resolves to running pods matching labels

Forward Options

  • resource - Target resource
  • port - Remote port
  • localPort - Local port
  • alias - Display name & mDNS
  • selector - Label selector

Advanced Features

Production-ready capabilities

Health Checks

Advanced health monitoring prevents stale connections during long operations like database dumps.

tcp-dialFast connection test
data-transferVerifies tunnel functionality
maxConnectionAgeReconnect before k8s timeout
maxIdleTimeDetect idle connections

mDNS Hostnames

Access forwards via .local hostnames without editing /etc/hosts.

alias: prod-db → prod-db.local
service/redis → redis.local

Works on macOS (Bonjour) and Linux (avahi-daemon)

Hot Reload

Configuration changes are applied automatically without restarting.

  • • File watcher detects changes in ~100ms
  • • New forwards start automatically
  • • Removed forwards stop gracefully
  • • Existing forwards continue uninterrupted

Retry Strategy

Exponential backoff with infinite retries ensures reliability.

1s → 2s → 4s → 8s → 10s max

HTTP Traffic Logging

Press l to view real-time HTTP traffic for debugging.

Columns: Time, Method, Status, Latency, Path
f Filter mode / Search c Clear
Filters: All, Non-2xx, Errors (4xx/5xx)

Connection Benchmarking

Press b to benchmark a connection with configurable parameters.

ConcurrencyParallel workers
RequestsTotal request count
LatencyP50/P95/P99 percentiles
ThroughputRequests per second