sshpushpull 0.1.0a3

Dead simple, jargon-free Python tool to make a local TCP port available on a remote host or make a remote TCP port available locally, with auto-reconnect.

This is a Python reimplementation of push-pull-port that uses paramiko instead of shelling out to autossh, making it cross-platform and self-contained.

Motivation

Modern work is mobile. Whether you're at home, in a cafe, or on the move with 4G, you need secure, on-demand access to your devices and services - without wrestling with complex forwarding rules or VPNs.

sshpushpull lets you instantly "push" or "pull" any TCP port via SSH with human-friendly commands.

• Expose your device's SSH, VNC, or web apps at a moment's notice.
• Stop and start tunnels with a single command.
• Failures show up immediately - no silent, sneaky background errors.
• Auto-reconnects after transient network drops with exponential backoff.

It's the Unix philosophy, everywhere: portable, composable, and under your control.

Prerequisites

• Python 2 or Python 3
• paramiko (installed automatically via pip install sshpushpull)
• SSH access to the remote host
• For unattended tunnels, set up SSH key-based authentication so you're not prompted for a password on every reconnect.

Note: When using push, to make the pushed port accessible from other hosts, ensure the remote SSH server has GatewayPorts clientspecified set in /etc/ssh/sshd_config.

Installation

pip install sshpushpull

Usage

sshpushpull provides two subcommands:

• push — Make a local TCP port available on a remote host (equivalent to ssh -R)
• pull — Make a remote TCP port available locally (equivalent to ssh -L)

Both commands run in the foreground and auto-reconnect after transient network failures with exponential backoff (up to 10 seconds).

Push: Expose a local port on a remote host

sshpushpull push \
    --local-port <local_port> \
    --remote-port <remote_port> \
    --username <user> \
    --host <host> \
    [--port <ssh_port>] \
    [--password <pwd> | --rsa-key <path> | --ed25519-key <path>] \
    [--localhost-only]

Examples:

# Make local port 3000 available on dev.example.com:3001 using password auth
sshpushpull push --local-port 3000 --remote-port 3001 --username dev --host dev.example.com --password secret

# Using an Ed25519 key
sshpushpull push --local-port 3000 --remote-port 3001 --username dev --host dev.example.com --ed25519-key ~/.ssh/id_ed25519

# If SSH is running on port 2222
sshpushpull push --local-port 3000 --remote-port 3001 --username dev --host dev.example.com --port 2222 --rsa-key ~/.ssh/id_rsa

# Push multiple ports at once
sshpushpull push \
    --host dev.example.com \
    --username dev \
    --ed25519-key ~/.ssh/id_ed25519 \
    --local-port 3000 --remote-port 3001 \
    --local-port 4000 --remote-port 4001 \
    --local-port 8080 --remote-port 9090

# Only allow access from the remote host's own localhost
sshpushpull push --local-port 3000 --remote-port 3001 --username dev --host dev.example.com --ed25519-key ~/.ssh/id_ed25519 --localhost-only

Pull: Access a remote port locally

sshpushpull pull \
    --remote-port <remote_port> \
    --local-port <local_port> \
    --username <user> \
    --host <host> \
    [--port <ssh_port>] \
    [--password <pwd> | --rsa-key <path> | --ed25519-key <path>]

Examples:

# Access remote port 3306 (database) through local port 3307
sshpushpull pull --remote-port 3306 --local-port 3307 --username admin --host db.internal --password secret

# Using an Ed25519 key
sshpushpull pull --remote-port 3306 --local-port 3307 --username admin --host db.internal --ed25519-key ~/.ssh/id_ed25519

# Pull multiple ports at once
sshpushpull pull \
    --host db.internal \
    --username admin \
    --password secret \
    --local-port 3307 --remote-port 3306 \
    --local-port 5433 --remote-port 5432

# If SSH is running on port 2222
sshpushpull pull --remote-port 3306 --local-port 3307 --username admin --host db.internal --port 2222 --rsa-key ~/.ssh/id_rsa

Multiple Ports

Both push and pull support forwarding multiple ports over a single SSH connection. Simply repeat --local-port and --remote-port in matched pairs:

# Push: expose three local services on the remote host
sshpushpull push \
    --host dev.example.com \
    --username dev \
    --ed25519-key ~/.ssh/id_ed25519 \
    --local-port 3000 --remote-port 3001 \
    --local-port 4000 --remote-port 4001 \
    --local-port 8080 --remote-port 9090

# Pull: access remote database and cache locally
sshpushpull pull \
    --host db.internal \
    --username admin \
    --password secret \
    --local-port 3307 --remote-port 3306 \
    --local-port 6380 --remote-port 6379

Ports are paired by position: the first --local-port with the first --remote-port, the second with the second, and so on. All mappings share a single SSH connection and reconnect together.

Foreground Operation: Visibility Over Stealth

We intentionally run all tunnels in the foreground. This ensures:

• Immediate Error Visibility: Any connection issues, authentication failures, or port conflicts are clearly printed to your terminal, so you can respond and debug without guessing.
• No Silent Failures: By avoiding background daemons, you won't miss subtle (or catastrophic) tunnel dropouts that go unnoticed.
• Stopping the tunnel: Simply press Ctrl-C to stop the tunnel. You can also close the terminal window/tab to end it.

Tip: If you ever want to run the tunnel in the background, you can use a terminal multiplexer like tmux to keep tunnels running while detached.

Auto-Reconnect

Both push and pull automatically reconnect after transient network failures. The reconnect strategy uses exponential backoff:

1. First retry: 1 second
2. Second retry: 2 seconds
3. Third retry: 4 seconds
4. ...up to a maximum of 10 seconds

After a successful reconnection, the backoff resets to 1 second.

Why We Use Push/Pull Instead of Forward/Reverse

The Problem with Traditional Terms

The standard SSH port forwarding terms (local forwarding vs remote forwarding) are notoriously confusing because:

1. Perspective Dependence
   The "remote" and "local" labels depend on which machine initiates the SSH connection, not the actual service exposure direction users care about.

2. Cognitive Mismatch
   When developers want to:

   • Expose a local service remotely, they must remember this is called "remote forwarding" (-R)
   • Access a remote service locally, this is called "local forwarding" (-L)

3. Implementation-First Naming
   The terms describe SSH's technical implementation rather than user intent.

Our Push/Pull Metaphor

We intentionally avoid forward/reverse terminology in favor of intuitive action verbs:

Key Advantages

1. Intent-Oriented

   • push: "I want to make this local port available there"
   • pull: "I want to access that remote port here"

2. Directionally Clear
   Eliminates ambiguity about "whose local/remote" we're referring to.

3. Cloud-Native Alignment
   Matches modern service mesh concepts (ingress/egress) better than SSH's 1990s perspective.

Contributing

Contributions are welcome! Please submit pull requests or open issues on the GitHub repository.

License

This project is licensed under the MIT License.