Skip to content

Getting started

Requirements

  • Python 3.13 or newer
  • No runtime dependencies beyond the standard library

Install

pip install lupaxa-port-forwarder
port-forwarder --help

Library import:

from lupaxa.port_forwarder import PortForwarder

forwarder = PortForwarder(8080, "remote.example.com", 80)

Module entry point:

python -m lupaxa.port_forwarder --version

From source (development)

make init
make python-install-dev
port-forwarder --version

First run

Pass the local listen port, the remote host, and the remote port:

port-forwarder 8080 remote.example.com 80

Or pass one or more LOCAL:HOST:REMOTE mappings:

port-forwarder 8080:remote.example.com:80 5432:db.internal:5432

The process stays in the foreground and logs each accepted client. Stop it with Ctrl+C or SIGTERM. Use --quiet to hide accept lines, or --timeout to bound the remote connect.

By default the listener binds 127.0.0.1. Use --bind 0.0.0.0 when other hosts must connect to the local port, and --allow to restrict who may. --max-connections and --idle-timeout cap concurrent sessions and quiet ones.

Makefile helpers

make init                 # clone makefile-skills into .makefiles/
make python-install-dev   # editable install with [dev]
make python-check         # lint + type + test
make mkdocs-serve         # local docs site