Project Logo

The Lupaxa SRE Toolbox
Part of The Lupaxa Project


lupaxa-port-forwarder

Listen on a local TCP port and forward each connection to a remote host and port.

Features

  • Listen on a local TCP port (loopback by default)
  • Forward each accepted client to a remote host and port
  • One process can run several LOCAL:HOST:REMOTE mappings
  • Relay bytes in both directions until either side closes
  • Half-close one side without dropping the reply on the other
  • --bind to choose the local listen address (0.0.0.0 to share on the LAN)
  • --allow to restrict source addresses and CIDR networks
  • --max-connections and --idle-timeout to cap sessions
  • --timeout to bound the remote connect
  • --verbose / --quiet for log volume
  • Library API (PortForwarder, PortForwarderGroup) and CLI (port-forwarder)
  • Fully typed, linted, formatted, and tested
  • No runtime dependencies beyond the standard library

Installation

From PyPI

pip install lupaxa-port-forwarder

From source (development mode)

pip install -e ".[dev]"

Requires Python 3.13+. No runtime dependencies.

Library quick start

from lupaxa.port_forwarder import PortForwarder

with PortForwarder(8080, "remote.example.com", 80) as forwarder:
    forwarder.start()

CLI quick start

port-forwarder --help
port-forwarder 8080 remote.example.com 80
port-forwarder 8080:remote.example.com:80 5432:db.internal:5432
port-forwarder 8080 remote.example.com 80 --bind 0.0.0.0 --allow 10.0.0.0/8
port-forwarder 8080 remote.example.com 80 --max-connections 8 --idle-timeout 60

You can also run the CLI as a module:

python -m lupaxa.port_forwarder --help
python -m lupaxa.port_forwarder --version

Documentation

Online documentation:

Documentation

Source repository:

GitHub

Serve docs locally

From a clone of the repository:

make mkdocs-serve

Then open the local URL printed by MkDocs in your browser.

Development

Clone the repository and install with Make:

make init                # first-time makefile-skills checkout
make python-install-dev  # editable install with [dev]
make python-check        # lint, type-check, and test
The Lupaxa Project Footer

Project links

Data verified by PyPI on Sep 10, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for lupaxa from gravatar.com lupaxa

Credits

Author: The Lupaxa Project

GitHub Statistics

Data verified by PyPI on Sep 10, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT License)

Requires

Python >=3.13

Provides Extra

dev test

Tags

cli networking port-forward proxy tcp

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

lupaxa_port_forwarder-0.1.0.tar.gz (11.0 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

lupaxa_port_forwarder-0.1.0-py3-none-any.whl (13.0 kB view details)

Uploaded Python 3

File details

Details for the file lupaxa_port_forwarder-0.1.0.tar.gz.

File metadata

  • Download URL: lupaxa_port_forwarder-0.1.0.tar.gz
  • Upload date:
  • Size: 11.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for lupaxa_port_forwarder-0.1.0.tar.gz
Algorithm Hash digest
SHA256 9d73aab70e3c3ba67a0297f6fc30332e92e26979ca31cdbd0d73a58f8a392881
MD5 13dbba6a9519b9aede874d53579284f6
BLAKE2b-256 478758c2e1b2eef3a6aee4b2a8e22ed14dc78aa1ca06c6ac87238600144758a7

See more details on using hashes here.

Provenance

The following attestation bundles were made for lupaxa_port_forwarder-0.1.0.tar.gz:

Publisher: generate-release.yml on lupaxa-sre-toolbox/port-forwarder

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file lupaxa_port_forwarder-0.1.0-py3-none-any.whl.

File metadata

File hashes

Hashes for lupaxa_port_forwarder-0.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 5a7a85697631d0756576a262ca6bfcdfc52e0aa37e435f8e26d9035c935ce487
MD5 94821cb2a0fd7bb798398d6b40ac0063
BLAKE2b-256 950d1bfeebf281d29611ad632345cec95cc0663abe987601048716ac8aff768b

See more details on using hashes here.

Provenance

The following attestation bundles were made for lupaxa_port_forwarder-0.1.0-py3-none-any.whl:

Publisher: generate-release.yml on lupaxa-sre-toolbox/port-forwarder

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page