GUI
Visual port-forward management with system tray integration, HTTP logging, and GitHub sync.
The kftray desktop interface provides visual management of Kubernetes port forwards through a system tray application.
System tray integration
The system tray icon provides quick access without opening the full interface.
macOS:
Menu bar icon → Click for quick menu
Right-click → Start All, Stop All, Open Main WindowWindows:
System tray → Click for quick menu
Right-click → Start All, Stop All, Open Main WindowLinux:
AppIndicator → Click for quick menu
Right-click → Start All, Stop All, Open Main WindowLinux AppIndicator requirement
GNOME requires the AppIndicator extension installed and enabled. KDE, XFCE, and other desktop environments typically include AppIndicator support by default.
Status indicators on the tray icon show whether any forwards are active. The icon changes color based on overall state, making it easy to see at a glance if your forwards are running.
Main window
The main window displays all configurations in a list format with status toggles for each forward.
Configuration management
Click the + button or press Ctrl/Cmd + N to create a new configuration.
Required fields:
{
"service": "api-gateway",
"namespace": "development",
"local_port": 8080,
"remote_port": 80,
"protocol": "tcp",
"alias": "gateway"
}Optional fields:
- Custom kubeconfig path
- Specific context
- Workload type (service, pod, deployment)
- Domain alias for local access
The configuration dialog validates inputs and prevents saving invalid configurations.
Click the edit icon next to any configuration to modify it.
Changes take effect immediately for stopped forwards. Active forwards need to be restarted to use new settings.
Common edits:
- Change local port to avoid conflicts
- Update alias for clarity
- Switch to different namespace
- Modify protocol (TCP/UDP)
Click the duplicate icon next to any configuration to create a copy. This is useful when you need a similar forward with a different local port or namespace.
Individual delete: Click the delete icon next to a configuration. Confirmation prompt prevents accidental deletion.
Bulk delete:
- Select multiple configurations with checkboxes
- Click bulk delete button
- Confirm deletion
Active forwards are stopped before deletion.
Port forward management
Start individual forwards: Toggle the switch next to any configuration. Status changes from red (stopped) to yellow (connecting) to green (active).
Start all forwards: Click "Start All" button or use the system tray menu. Useful for establishing complete development environments.
Stop forwards: Toggle switches, "Stop All" button, or tray menu options. Only the interface that started a forward can stop it — this prevents conflicts when multiple interfaces access the same configuration.
Status indicators:
| Color | Meaning |
|---|---|
| Green | Active connection established |
| Red | Stopped |
| Yellow | Connecting or reconnecting |
| Error icon | Failed to start or lost connection |
Connection failures show error details in a tooltip. Click the error icon for troubleshooting information.
HTTP logging
HTTP logging captures request and response details for debugging. See HTTP Logging for complete documentation.
Enable logging:
Right-click a configuration.
Select "Enable HTTP Logging".
Toggle switch appears next to configuration.
View logs: Click the log viewer icon next to configurations with logging enabled. Logs open in your system's default text editor.
Log location:
~/.kftray/http_logs/Each configuration creates a separate log file with format:
config-<id>-port-<local_port>.logDisk usage
HTTP logging can generate large files for high-traffic services. Monitor disk usage and clean up logs regularly through the bulk cleanup option in the main menu.
Log viewer
Right-click the system tray icon and select "View Logs" to open the built-in log viewer window. The viewer shows application logs in real time with auto-refresh and supports:
- Filtering by log level or module
- Full-text search across log entries
- Browsing older log files
- Exporting logs or generating a diagnostic report for sharing
Log retention is configurable — you can set how many files to keep and for how long. Old logs are cleaned up automatically on startup.
Server resources
Click "Server Resources" in the main menu to see an overview of all Kubernetes resources kftray has deployed in your clusters (proxy pods, services, ingress objects for expose workloads). This helps you audit what kftray is running and clean up leftover resources if needed.
GitHub sync
GitHub sync coordinates configuration sharing across teams. See GitHub Sync for complete documentation.
Setup:
Open Settings → GitHub Sync.
Enter repository URL (e.g., https://github.com/team/kftray-configs).
Add Personal Access Token with repo scope.
Set sync interval (default: 5 minutes).
Enable auto-sync toggle.
Manual sync: Click "Sync Now" button to trigger immediate synchronization, bypassing the interval timer.
Conflict resolution: Repository configurations take precedence over local changes. Back up local configurations before enabling sync if you have custom settings.
Auto import
Auto import discovers services in Kubernetes clusters and creates configuration suggestions. See Auto Import for annotation details.
Workflow:
Click "Auto Import" in main menu.
Select kubeconfig and context.
Choose target namespace (or scan all).
Review discovered services with kftray.app/enabled annotation.
Select services to import.
Click "Import Selected".
Imported configurations merge with existing ones. Running auto import multiple times won't create duplicates.
Settings
Keyboard shortcuts
| Shortcut | Action |
|---|---|
Ctrl/Cmd + N | New configuration |
Ctrl/Cmd + F | Search configurations |
Ctrl/Cmd + A | Select all |
Ctrl/Cmd + , | Open settings |
Space | Toggle selected forward |
Delete | Delete selected configurations |
Esc | Close dialogs |