🚀 BETA RELEASE - Universal port forwarding manager with intelligent health monitoring
ℹ️ LocalPort is in active development with new features being added regularly. While core functionality is stable and well-tested, some advanced features are still being developed. We welcome feedback and issue reports!
LocalPort is a modern Python CLI tool that simplifies port forwarding across different technologies (kubectl, SSH) while providing enterprise-grade features like automatic health monitoring, intelligent restart policies, and daemon-mode operation.
- 🔄 Universal: Works with kubectl, SSH, and more - one tool for all your port forwarding needs
- 🏥 Self-Healing: Automatic health monitoring with intelligent restart policies and exponential backoff
- ⚡ Hot Reload: Configuration changes applied instantly in daemon mode (powered by watchdog)
- 🎯 Production Ready: Daemon mode for background operation with comprehensive monitoring
- 🎨 Beautiful CLI: Rich terminal interface with clean output and progressive verbosity
- 🔧 Flexible: YAML configuration with environment variable support and validation
Note: LocalPort is now available on production PyPI! This is beta software with stable core functionality and active feature development.
⚠️ Python 3.11+ Required: LocalPort requires Python 3.11 or newer. If you don't have Python 3.11+, see Python Installation below.
# Install with pipx (recommended)
pipx install localport
# Install with optional dependencies for advanced health checks
pipx install "localport[kafka,postgres]"
# Alternative: Install with UV
uv tool install localportIf you don't have Python 3.11+, install it first:
macOS (using Homebrew):
brew install python@3.11
# or for latest version
brew install python@3.12Ubuntu/Debian:
sudo apt update
sudo apt install python3.11 python3.11-venv python3.11-pip
# or for newer version
sudo apt install python3.12 python3.12-venv python3.12-pipWindows:
- Download from python.org (3.11+ versions)
- Or use pyenv-win
Using pyenv (cross-platform):
pyenv install 3.11.0 # or 3.12.0, 3.13.0
pyenv global 3.11.0Verify installation:
python3.11 --version # Should show Python 3.11.x or newer# Install development versions from Test PyPI
pipx install --index-url https://test.pypi.org/simple/ --pip-args="--extra-index-url https://pypi.org/simple/" localport# Install latest from GitHub
pipx install git+https://github.com/dawsonlp/localport.git
# Install specific version/tag
pipx install git+https://github.com/dawsonlp/localport.git@v0.3.0
# Development: Install from source
git clone https://github.com/dawsonlp/localport.git
cd localport && ./scripts/setup-dev.sh- Create a configuration file (
localport.yaml):
version: "1.0"
services:
# Forward PostgreSQL from Kubernetes
- name: postgres
technology: kubectl
local_port: 5432
remote_port: 5432
connection:
resource_name: postgres
namespace: default
tags: [database]
# Forward Redis from Kubernetes (SSH tunnels planned for v0.4.0)
- name: redis
technology: kubectl
local_port: 6379
remote_port: 6379
connection:
resource_name: redis
namespace: default
tags: [cache]- Start your services:
# Start all services
localport start --all
# Start specific services
localport start postgres redis
# Start services by tag
localport start --tag database- Check status:
localport status- Use your forwarded services:
# Connect to PostgreSQL
psql -h localhost -p 5432 -U postgres
# Connect to Redis
redis-cli -h localhost -p 6379That's it! Your services are now accessible locally with automatic health monitoring and restart capabilities.
- Getting Started Guide - Step-by-step setup for new users
- Configuration Guide - Complete configuration reference
- CLI Reference - All commands and options
- CLI Reference - All commands and options
- Development Guide - Development setup and contribution guidelines
- Architecture Guide - Technical architecture overview
# Start services
localport start postgres redis # Specific services
localport start --tag database # By tag
localport start --all # All services
# Monitor services
localport status # Current status
localport status --watch # Live monitoring
# Stop services
localport stop postgres redis # Specific services
localport stop --all # All services# View all available service logs
localport logs --list
# View specific service logs
localport logs --service postgres
# Get log file path for external tools
localport logs --service postgres --path
# Filter logs with grep
localport logs --service postgres --grep "error"
# Show log directory locations
localport logs --location
# Use with external tools
tail -f $(localport logs --service postgres --path)# Start daemon for background operation
localport daemon start --auto-start
# Check daemon status
localport daemon status
# Reload configuration without restart
localport daemon reload
# Stop daemon
localport daemon stop# Validate configuration
localport config validate
# Export configuration
localport config export --format json
# Export specific services
localport config export --tag database --output backup.yamlversion: "1.0"
services:
- name: postgres
technology: kubectl
local_port: 5432
remote_port: 5432
connection:
resource_name: postgres
namespace: defaultversion: "1.0"
# Global defaults
defaults:
health_check:
type: tcp
interval: 30
timeout: 5.0
failure_threshold: 3
restart_policy:
enabled: true
max_attempts: 5
backoff_multiplier: 2.0
services:
- name: postgres
technology: kubectl
local_port: 5432
remote_port: 5432
connection:
resource_type: service
resource_name: postgres
namespace: default
context: ${KUBE_CONTEXT:minikube}
enabled: true
tags: [database, essential]
description: "PostgreSQL database"
health_check:
type: postgres
config:
database: postgres
user: postgres
password: ${POSTGRES_PASSWORD}
restart_policy:
max_attempts: 3
initial_delay: 2Supported Health Check Types:
- TCP: Basic connectivity testing
- HTTP/HTTPS: Web service health endpoints
- Kafka: Message broker connectivity (requires
kafka-python) - PostgreSQL: Database connectivity (requires
psycopg)
- name: service-name
technology: kubectl
connection:
resource_type: service # service, deployment, pod
resource_name: my-service
namespace: default
context: minikube # optional
⚠️ Note: SSH tunnel support is planned for v0.4.0 and not yet implemented. The configuration below shows the planned syntax.
- name: service-name
technology: ssh
connection:
host: remote-server.com
user: deploy
port: 22 # optional, default 22
key_file: ~/.ssh/id_rsa # optional
password: secret # optional (not recommended)When running in daemon mode, LocalPort automatically detects configuration changes and applies them without restarting services:
# Start daemon mode first
localport daemon start --auto-start
# Edit your localport.yaml file
vim localport.yaml
# Changes are automatically applied in daemon mode!
# Check what changed:
localport daemon status
localport statusNote: Hot reloading only works in daemon mode. For standalone commands, you'll need to restart services manually after configuration changes.
# Table format (default)
localport status
# JSON for scripting
localport status --output json
# Text for simple parsing
localport status --output textUse environment variable substitution for sensitive data:
connection:
host: ${DB_HOST:localhost}
user: ${DB_USER}
password: ${DB_PASSWORD}
key_file: ${SSH_KEY_FILE:~/.ssh/id_rsa}- Python 3.11+
- UV (for dependency management)
- Virtual environment support
# Clone the repository
git clone https://github.com/dawsonlp/localport.git
cd localport
# Setup development environment
./scripts/setup-dev.sh
# Activate virtual environment
source .venv/bin/activate
# Install in development mode
uv pip install -e .
# Run tests
uv run pytest- Fork the repository
- Create a feature branch
- Make your changes
- Add tests
- Run the test suite
- Submit a pull request
MIT License - see LICENSE file for details.
🎯 Beta Release 0.3.x - Stable core functionality with cluster health monitoring and daemon mode!
Current Progress:
- ✅ Core Infrastructure (100% complete)
- ✅ kubectl Port Forwarding (100% complete)
- ✅ Process Persistence (100% complete)
- ✅ ConnectionInfo Value Objects (100% complete)
- ✅ Health Monitoring Framework (100% complete)
- ✅ Configuration Management (100% complete)
- ✅ Daemon Mode (100% complete)
- ✅ Basic Testing Suite (100% complete)
- ✅ Hybrid Verbosity System (100% complete)
- 🚧 SSH Tunnels (planned for 0.4.0)
- 🚧 Advanced Health Checks (in progress)
- 🚧 Documentation (in progress)
Known Issues:
- PostgreSQL Health Check: Requires password configuration (see Configuration Guide)
- Kafka Health Check: May be too aggressive in failure detection
- SSH Tunnels: Not yet implemented
Recent Improvements:
- ✅ Daemon startup detection and verification
- ✅ Health check interface standardization
- ✅ Progressive verbosity system (-v, -vv, --debug)
- ✅ Clean CLI output by default
- ✅ v0.3.5 Architectural Enhancements: Complete kubectl adapter interface compliance with enhanced validation, type safety, and comprehensive testing (31 unit tests)
LocalPort is actively evolving with exciting features planned for future releases. Our development is driven by community needs and contributions.
- 🌐 Reverse Proxy Support: HTTP/HTTPS reverse proxies with load balancing
- 🔗 Advanced Routing: Multi-hop routing and service mesh capabilities
- 📊 Enhanced Logging: Ring buffer storage with real-time streaming
- 🤖 AI Integration: Natural language service management via MCP
- 🔒 Enterprise Security: mTLS, RBAC, and identity provider integration
- 🛠️ Developer Tools: IDE plugins and environment templates
Get Involved:
- 🗳️ Vote on features by reacting to GitHub issues
- 💬 Join discussions to share your use cases
- 🛠️ Contribute by implementing features you need
- 📝 Request features with detailed GitHub issues
📖 View Full Roadmap - Detailed feature descriptions, use cases, and contribution opportunities.
See CHANGELOG.md for detailed release notes and version history.
- Changelog - Detailed release notes and version history
- Development Guide - Development setup and contribution guidelines
- Architecture Guide - Technical architecture overview