ports beta

A blue portal and an orange portal joined by beams of light, with the ports wordmark and the tagline REMOTE PORTS. LOCALLY.

A dev server, a database, or a dashboard starts on a remote machine and listens on 127.0.0.1:5432. To reach it you type ssh -L, guess the port, and start over when it moves. ports is a terminal UI that watches TCP listeners on your Linux SSH hosts and forwards the ones you want to 127.0.0.1 on your machine, automatically and as they appear.

The Ports tab listing listeners on two hosts. cloud-dev is connected with six listeners, including postgres on 5432 forwarded to local port 15432, a blocked SSH port, a failed forward, and two pending ports. pi is disconnected and shows a stale row from a snapshot.
Every listener on every host, with its process, owner, remote bind, local address, and state.

What it does

Screenshots

The detail view for port 5432, showing remote binds, scope, SSH destination, process, owner, command, local address, and recent events.
Details for one port, including why it was or wasn't forwarded.
The rule editor prefilled from postgres on cloud-dev, with host, process, and ports checked, action forward, and a preview saying it matches one row now.
The rule editor previews which rows a rule will match before you save it.
The Rules tab listing saved rules in order, with how many current rows each one decides.
Rules are checked top to bottom; the first match decides.
The Hosts tab listing cloud-dev and pi with state, listener and forward counts, autoconnect, process lookup mode, and poll interval.
Hosts, autoconnect, and poll intervals.
The command palette, a fuzzy list of actions with their shortcut keys.
Every action in a fuzzy command palette.
The Ports tab in the corridor theme, with blue keycaps and a dashed beam under the header.
The corridor theme with the dashed beam.

Install on Debian or Ubuntu

Available for 64-bit Intel and AMD PCs (amd64) through Alan NULL's APT repository. You also need the OpenSSH client and an SSH host you can log in to; the package installs openssh-client if it is missing.

  1. Add the APT repository

    Follow the repository's instructions to verify its signing key and enable it. You only need to do this once.

    Open repository setup instructions

  2. Install ports

    After setting up the repository, run these commands in a terminal:

    sudo apt update
sudo apt install ports

  3. Run it

    Run ports in a terminal, or find ports in your application menu. The first time, it lists the hosts in your ~/.ssh/config; pick one, or type any host you can reach with ssh.

Getting started

# open the TUI and connect your saved hosts
ports

# connect these hosts for this run only
ports tui cloud-dev build-box

# line-based text mode for one host
ports watch cloud-dev

In the Ports tab, select a row and press Enter to forward it, a to always forward it, or b to never forward it. Press o to open the forwarded port in your browser, / to filter, : for the command palette, and ? for help.

Process names come from the remote host and may be hidden when your SSH user can't see another user's processes. Turn on sudo process lookup for a host in the Hosts tab if it has passwordless sudo for ss and awk.

Settings, hosts, and rules live in ~/.config/ports/config.json. You can edit it while ports is running; changes apply within a second.

Keep ports up to date

Read the changelog for version history.

Updates arrive through the same APT repository. Use your system's software updater, or run:

sudo apt update
sudo apt install --only-upgrade ports

About the beta

This is the first public release. It hasn't been tested on many machines yet, and the config and rule formats may still change before 1.0.

Found a bug or have an idea? Send feedback and include the output of ports --version.