portgate 0.1.dev1

A command-line utility to manage port mappings on your local router using UPnP/NAT-PMP

PortGate

A command-line utility to manage port mappings on your local router using UPnP/NAT-PMP. Easily open, close and list ports to expose local services (web servers, game servers, etc.) to the internet without Ngrok, Cloudflare, Serveo, etc.

Quick Start

Just run the following command to open a port on your router.

pip install portgate
portgate <local_port>

Features

• Open new port mappings with custom descriptions and TTL
• Remove existing port mappings
• List all active port mappings
• Refresh/renew specific port mappings
• Clear all port mappings created by PortGate
• Display router information and WAN IP

Installation

Use pip to install PortGate.

pip install portgate

Usage

Quick Mode (Recommended)

Just specify the local port you want to forward to the internet.

portgate <local_port>

Example:

sarp@IdeaPad:~$ portgate 8000
Port forwarding established!
External address: 95.65.xxx.xxx:1025
Internal address: localhost:8000
Press Ctrl+C to stop forwarding...
^C
Removing port mapping 1025 -> 8000...
Port mapping removed successfully.

Command Line Interface

portgate <command> <options>

Commands

Command	Description
add	Open a new port mapping
remove	Remove an existing port mapping
list	List all active port mappings
refresh	Refresh/renew a specific mapping
clear	Remove all mappings by PortGate
info	Show router & WAN IP info

Options for add

Option	Description	Default
-p, --port	Internal port to forward	Required
-e, --external	External port	Same as int.
-P, --protocol	Protocol: TCP, UDP, or BOTH	TCP
-d, --desc	Description for the mapping	"PortGate"
-t, --ttl	Lease duration in seconds (0 = infinite)	3600

Examples

# Map TCP port 8080 on WAN to port 8080 on local host, permanent
portgate add -p 8080 -P TCP -t 0

# Map external port 50000 to internal port 25565
portgate add -p 25565 -P TCP -e 50000

# Remove TCP port 8080 mapping
portgate remove -p 8080 -P TCP

# List current UPnP/NAT-PMP mappings
portgate list

# Display router info and public IP
portgate info

How It Works

PortGate uses the miniupnpc Python library to communicate with your router via UPnP/NAT-PMP protocols. This allows you to:

1. Run a service on a specific port locally (e.g., python3 -m http.server 55000)
2. Use PortGate to create a port mapping through your router
3. Access your service from the internet using your WAN IP and the mapped port

Requirements

• Python 3.8 or higher
• miniupnpc Python library
• Router with UPnP/NAT-PMP enabled