ssh-auto-forward 0.0.1__py3-none-any.whl

ssh_auto_forward/__init__.py

@@ -0,0 +1,5 @@
+"""SSH Auto Port Forwarder - Automatically forward ports from remote SSH servers."""
+
+from ssh_auto_forward.__version__ import __version__
+
+__all__ = ["__version__"]

ssh_auto_forward/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

ssh_auto_forward/cli.py

@@ -0,0 +1,653 @@
+"""CLI entry point for ssh-auto-forward."""
+
+import argparse
+import configparser
+import logging
+import os
+import re
+import socket
+import sys
+import threading
+import time
+from collections import defaultdict
+from pathlib import Path
+from typing import Dict, List, Optional, Set, Tuple
+
+import paramiko
+from paramiko import SSHClient
+
+from ssh_auto_forward.__version__ import __version__
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(message)s",
+    datefmt="%H:%M:%S",
+)
+logger = logging.getLogger("ssh-auto-forward")
+
+# Ports to skip by default (well-known ports < 1000)
+DEFAULT_SKIP_PORTS = set(range(0, 1000))
+
+
+class SSHTunnel:
+    """Represents a single SSH tunnel (forwarded port)."""
+
+    def __init__(self, ssh_client: SSHClient, remote_host: str, remote_port: int, local_port: int):
+        self.ssh_client = ssh_client
+        self.remote_host = remote_host
+        self.remote_port = remote_port
+        self.local_port = local_port
+        self.transport = ssh_client.get_transport()
+        self.server_socket = None
+        self.forward_thread = None
+        self.active = False
+
+    def start(self):
+        """Start the port forwarding in a background thread."""
+        try:
+            # Create a local server socket
+            self.server_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            self.server_socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            self.server_socket.bind(("127.0.0.1", self.local_port))
+            self.server_socket.listen(5)
+            self.server_socket.settimeout(1.0)  # Non-blocking accept
+
+            self.active = True
+            self.forward_thread = threading.Thread(
+                target=self._forward_loop,
+                daemon=True,
+                name=f"Tunnel-{self.local_port}->{self.remote_port}"
+            )
+            self.forward_thread.start()
+            logger.debug(f"✓ Tunnel active: localhost:{self.local_port} -> {self.remote_host}:{self.remote_port}")
+            return True
+        except Exception as e:
+            logger.error(f"Failed to start tunnel for port {self.remote_port}: {e}")
+            if self.server_socket:
+                self.server_socket.close()
+                self.server_socket = None
+            return False
+
+    def _forward_loop(self):
+        """Main loop that accepts connections and forwards them."""
+        while self.active:
+            try:
+                client_sock, addr = self.server_socket.accept()
+                threading.Thread(
+                    target=self._handler,
+                    args=(client_sock,),
+                    daemon=True,
+                ).start()
+            except socket.timeout:
+                continue
+            except Exception as e:
+                if self.active:
+                    logger.debug(f"Error accepting connection: {e}")
+
+    def _handler(self, client_sock):
+        """Handle a single forwarded connection."""
+        chan = None
+        try:
+            # Open a direct-tcpip channel through SSH
+            chan = self.transport.open_channel(
+                "direct-tcpip",
+                (self.remote_host, self.remote_port),
+                ("127.0.0.1", 0),
+            )
+            # Pipe data between client socket and SSH channel
+            self._pipe(client_sock, chan)
+        except Exception as e:
+            logger.debug(f"Connection error: {e}")
+        finally:
+            try:
+                client_sock.close()
+            except Exception:
+                pass
+            try:
+                if chan:
+                    chan.close()
+            except Exception:
+                pass
+
+    def _pipe(self, sock, chan):
+        """Pipe data between socket and SSH channel."""
+        try:
+            while self.active:
+                # Check if either end is closed
+                if chan.closed or chan.eof_received:
+                    break
+
+                # Use select to wait for data on either end
+                import select
+                r, w, x = select.select([sock, chan], [], [], 1.0)
+                if sock in r:
+                    data = sock.recv(4096)
+                    if not data:
+                        break
+                    chan.send(data)
+                if chan in r:
+                    data = chan.recv(4096)
+                    if not data:
+                        break
+                    sock.send(data)
+        except Exception:
+            pass
+        finally:
+            try:
+                sock.close()
+            except Exception:
+                pass
+            try:
+                chan.close()
+            except Exception:
+                pass
+
+    def stop(self):
+        """Stop the tunnel."""
+        self.active = False
+        try:
+            if self.server_socket:
+                self.server_socket.close()
+        except Exception as e:
+            logger.debug(f"Error closing server socket: {e}")
+        logger.info(f"✗ Tunnel stopped: localhost:{self.local_port} -> {self.remote_host}:{self.remote_port}")
+
+
+class SSHAutoForwarder:
+    """Main class that manages SSH connection and auto port forwarding."""
+
+    def __init__(
+        self,
+        host_alias: str,
+        ssh_config_path: Optional[str] = None,
+        skip_ports: Optional[Set[int]] = None,
+        port_range: Tuple[int, int] = (3000, 10000),
+        scan_interval: int = 5,
+    ):
+        self.host_alias = host_alias
+        self.ssh_config_path = ssh_config_path or self._find_ssh_config()
+        self.skip_ports = skip_ports or DEFAULT_SKIP_PORTS
+        self.port_range = port_range
+        self.scan_interval = scan_interval
+
+        self.ssh_client = None
+        self.tunnels: Dict[int, SSHTunnel] = {}  # remote_port -> tunnel
+        self.local_port_map: Dict[int, int] = {}  # remote_port -> local_port
+        self.failed_ports: Set[int] = set()  # Ports that failed to forward
+        self.running = False
+        self.next_alt_port = port_range[0]
+
+        # Get connection details
+        self.config = self._load_ssh_config(host_alias)
+
+    def _find_ssh_config(self) -> str:
+        """Find the SSH config file."""
+        home = Path.home()
+        for path in [".ssh/config", ".ssh/config.d/*"]:
+            full_path = home / path
+            if full_path.exists():
+                return str(full_path)
+        return os.path.expanduser("~/.ssh/config")
+
+    def _load_ssh_config(self, host_alias: str) -> dict:
+        """Load configuration for a host from SSH config."""
+        config = {
+            "hostname": host_alias,
+            "user": os.getenv("USER") or os.getenv("USERNAME"),
+            "port": 22,
+            "identityfile": None,
+        }
+
+        if not os.path.exists(self.ssh_config_path):
+            logger.warning(f"SSH config not found at {self.ssh_config_path}, using defaults")
+            return config
+
+        # Parse SSH config (simple parser)
+        current_host = None
+        host_pattern = None
+
+        with open(self.ssh_config_path, "r") as f:
+            for line in f:
+                line = line.strip()
+                if not line or line.startswith("#"):
+                    continue
+
+                # Handle multi-line values (rare)
+                parts = line.split(maxsplit=1)
+                if len(parts) < 2:
+                    continue
+
+                key, value = parts[0].lower(), parts[1]
+
+                if key == "host":
+                    if current_host is not None and self._host_matches(current_host, host_alias):
+                        break
+                    # Convert SSH glob pattern to regex
+                    host_pattern = value.replace(".", r"\.").replace("*", ".*").replace("?", ".")
+                    current_host = value
+                elif current_host and re.match(host_pattern, host_alias):
+                    if key == "hostname":
+                        config["hostname"] = value
+                    elif key == "user":
+                        config["user"] = value
+                    elif key == "port":
+                        config["port"] = int(value)
+                    elif key == "identityfile":
+                        # Remove quotes if present
+                        config["identityfile"] = value.strip('"').strip("'")
+
+        logger.info(f"Loaded config for '{host_alias}': {config['user']}@{config['hostname']}:{config['port']}")
+        return config
+
+    def _host_matches(self, pattern: str, host: str) -> bool:
+        """Check if a host pattern matches the target host."""
+        regex = pattern.replace(".", r"\.").replace("*", ".*").replace("?", ".")
+        return re.match(regex, host) is not None
+
+    def _load_keys(self, key_path: str) -> list:
+        """Load a private key file, trying different key formats."""
+        keys = []
+        key_types = [
+            paramiko.RSAKey,
+            paramiko.ECDSAKey,
+            paramiko.Ed25519Key,
+        ]
+
+        for key_type in key_types:
+            try:
+                key = key_type.from_private_key_file(key_path)
+                keys.append(key)
+                logger.debug(f"Loaded key type: {key_type.__name__}")
+                break
+            except Exception:
+                pass
+
+        return keys
+
+    def _get_agent_keys(self) -> list:
+        """Get keys from SSH agent."""
+        keys = []
+        try:
+            agent = paramiko.AgentRequestHandler()
+            keys = agent.get_keys()
+            logger.debug(f"Found {len(keys)} key(s) in SSH agent")
+        except Exception as e:
+            logger.debug(f"SSH agent not available: {e}")
+        return keys
+
+    def _find_identity_keys(self) -> list:
+        """Find identity keys from SSH config or default locations."""
+        keys = []
+
+        # Try identityfile from SSH config first
+        if self.config.get("identityfile"):
+            key_path = os.path.expanduser(self.config["identityfile"])
+            if os.path.exists(key_path):
+                keys.extend(self._load_keys(key_path))
+
+        # Try default key locations if no keys found yet
+        if not keys:
+            default_keys = [
+                "~/.ssh/id_rsa",
+                "~/.ssh/id_ed25519",
+                "~/.ssh/id_ecdsa",
+                "~/.ssh/id_ecdsa2",
+                "~/.ssh/id_dsa",
+            ]
+            for key_path in default_keys:
+                expanded = os.path.expanduser(key_path)
+                if os.path.exists(expanded):
+                    loaded = self._load_keys(expanded)
+                    if loaded:
+                        keys.extend(loaded)
+                        logger.debug(f"Loaded key from {key_path}")
+                        break
+
+        return keys
+
+    def connect(self) -> bool:
+        """Establish SSH connection to the remote host."""
+        self.ssh_client = SSHClient()
+        self.ssh_client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
+
+        try:
+            logger.info(f"Connecting to {self.config['hostname']}...")
+
+            # Prepare connection parameters
+            connect_kwargs = {
+                "hostname": self.config['hostname'],
+                "port": self.config['port'],
+                "username": self.config['user'],
+                "timeout": 10,
+                "allow_agent": False,  # We'll handle agent manually
+            }
+
+            # Method 1: Try SSH agent keys first
+            agent_keys = self._get_agent_keys()
+            if agent_keys:
+                logger.info(f"Trying SSH agent authentication ({len(agent_keys)} key(s))...")
+                connect_kwargs["pkey"] = agent_keys[0]
+
+            # Method 2: Try identity file keys
+            if not agent_keys:
+                identity_keys = self._find_identity_keys()
+                if identity_keys:
+                    logger.info("Trying identity file authentication...")
+                    connect_kwargs["pkey"] = identity_keys[0]
+                else:
+                    # No keys found, let SSH client try with allow_agent=True
+                    logger.info("Trying with default authentication...")
+                    connect_kwargs["allow_agent"] = True
+
+            self.ssh_client.connect(**connect_kwargs)
+            logger.info("✓ Connected!")
+            return True
+
+        except paramiko.AuthenticationException:
+            logger.error("Authentication failed. Check your SSH keys or credentials.")
+            logger.info("Hint: Ensure your SSH key is loaded in ssh-agent or your SSH config is correct.")
+            return False
+        except Exception as e:
+            logger.error(f"Connection failed: {e}")
+            return False
+
+    def get_remote_listening_ports(self) -> Dict[int, str]:
+        """Get the list of listening ports on the remote server with process names."""
+        try:
+            # Try to get port + process name
+            commands = [
+                "ss -tlnp 2>/dev/null | awk 'NR>1 {print $4, $7}'",
+                "netstat -tlnp 2>/dev/null | awk 'NR>1 && /LISTEN/ {print $4, $7}'",
+            ]
+
+            for cmd in commands:
+                stdin, stdout, stderr = self.ssh_client.exec_command(cmd)
+                output = stdout.read().decode().strip()
+                error = stderr.read().decode().strip()
+
+                if error and "permission denied" in error.lower():
+                    continue  # Try next command
+
+                ports = {}
+                for line in output.split("\n"):
+                    line = line.strip()
+                    if not line:
+                        continue
+                    parts = line.split()
+                    if len(parts) >= 2:
+                        # Extract port from address (e.g., "0.0.0.0:2999")
+                        addr = parts[0]
+                        if ":" in addr:
+                            port_str = addr.split(":")[-1]
+                            if port_str.isdigit():
+                                port = int(port_str)
+                                # Extract process name (e.g., "users:(("mdtohtml-watch",pid=518168,fd=4))")
+                                proc_info = parts[1]
+                                # Try to extract process name from various formats
+                                proc_name = "unknown"
+                                if 'users:(("' in proc_info:
+                                    proc_name = proc_info.split('users:(("')[1].split('"')[0]
+                                elif 'users:(("' in proc_info:
+                                    proc_name = proc_info.split('users:(("')[1].split('"')[0]
+                                elif "/" in proc_info:
+                                    proc_name = proc_info.split("/")[-1].split(",")[0]
+                                ports[port] = proc_name
+
+                if ports:
+                    return ports
+
+            # Fallback: just get ports without process names
+            commands_fallback = [
+                "ss -tln 2>/dev/null | awk 'NR>1 {print $4}' | cut -d: -f2 | sort -u",
+            ]
+
+            for cmd in commands_fallback:
+                stdin, stdout, stderr = self.ssh_client.exec_command(cmd)
+                output = stdout.read().decode().strip()
+
+                ports = {}
+                for line in output.split("\n"):
+                    line = line.strip()
+                    if line and line.isdigit():
+                        ports[int(line)] = ""
+                if ports:
+                    return ports
+
+            return {}
+
+        except Exception as e:
+            logger.debug(f"Error getting remote ports: {e}")
+            return {}
+
+    def is_local_port_available(self, port: int) -> bool:
+        """Check if a local port is available."""
+        # Check if already used for SSH forwarding
+        if port in self.local_port_map.values():
+            return False
+
+        # Check if port can be bound by a socket
+        try:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                s.bind(("127.0.0.1", port))
+                return True
+        except OSError:
+            return False
+
+    def find_available_local_port(self, preferred_port: int) -> Optional[int]:
+        """Find an available local port, preferring the preferred port."""
+        # Try the preferred port first
+        if self.is_local_port_available(preferred_port):
+            return preferred_port
+
+        # Increment until we find a free port
+        for offset in range(1, 1000):
+            alt_port = preferred_port + offset
+            if alt_port > 65535:
+                break  # Port number too high
+            if self.is_local_port_available(alt_port):
+                return alt_port
+
+        # If still no luck, try from port 3000 upwards
+        for port in range(3000, 65535):
+            if self.is_local_port_available(port):
+                return port
+
+        return None
+
+    def forward_port(self, remote_port: int, process_name: str = "") -> bool:
+        """Create a tunnel for a remote port."""
+        if remote_port in self.tunnels:
+            return True  # Already forwarded
+
+        if remote_port in self.skip_ports:
+            logger.debug(f"Skipping port {remote_port} (in skip list)")
+            return False
+
+        # Skip remote ports that match our local forwarding ports - they're likely our own tunnels
+        # But allow the port if it's the same as the remote port (direct forwarding)
+        used_local_ports = set(self.local_port_map.values())
+        if remote_port in used_local_ports and remote_port not in self.tunnels:
+            logger.debug(f"Skipping port {remote_port} (already used as a local forwarding port)")
+            return False
+
+        # Skip ports that previously failed (to avoid spamming errors)
+        if remote_port in self.failed_ports:
+            return False
+
+        local_port = self.find_available_local_port(remote_port)
+        if local_port is None:
+            logger.warning(f"⚠ No available local port for remote port {remote_port}")
+            self.failed_ports.add(remote_port)
+            return False
+
+        tunnel = SSHTunnel(
+            ssh_client=self.ssh_client,
+            remote_host="localhost",
+            remote_port=remote_port,
+            local_port=local_port,
+        )
+
+        if tunnel.start():
+            self.tunnels[remote_port] = tunnel
+            self.local_port_map[remote_port] = local_port
+
+            proc_suffix = f" ({process_name})" if process_name else ""
+            if local_port != remote_port:
+                logger.info(f"✓ Forwarding remote port {remote_port} -> local port {local_port}{proc_suffix}")
+            else:
+                logger.info(f"✓ Forwarding port {remote_port}{proc_suffix}")
+            return True
+        else:
+            # Track failed ports to avoid retrying
+            self.failed_ports.add(remote_port)
+            return False
+
+    def stop_forwarding_port(self, remote_port: int):
+        """Stop forwarding a specific port."""
+        if remote_port in self.tunnels:
+            self.tunnels[remote_port].stop()
+            del self.tunnels[remote_port]
+            del self.local_port_map[remote_port]
+            # Remove from failed ports so we can retry if the port comes back
+            self.failed_ports.discard(remote_port)
+
+    def scan_and_forward(self):
+        """Scan for new ports and set up forwarding."""
+        remote_ports = self.get_remote_listening_ports()
+
+        if not remote_ports:
+            return
+
+        logger.debug(f"Found {len(remote_ports)} listening port(s) on remote")
+
+        # Forward new ports
+        for port, proc_name in remote_ports.items():
+            self.forward_port(port, proc_name)
+
+        # Stop forwarding closed ports
+        current_remote_ports = set(self.tunnels.keys())
+        closed_ports = current_remote_ports - set(remote_ports.keys())
+        for port in closed_ports:
+            logger.info(f"✗ Remote port {port} is no longer listening, stopping tunnel")
+            self.stop_forwarding_port(port)
+
+        # Update terminal title with status
+        self._update_terminal_title()
+
+    def _update_terminal_title(self):
+        """Update terminal title with current status."""
+        try:
+            port_count = len(self.tunnels)
+            title = f"ssh-auto-forward: {self.host_alias} ({port_count} tunnels active)"
+            # ANSI escape code to set terminal title
+            print(f"\033]0;{title}\007", end="", flush=True)
+        except Exception:
+            pass
+
+    def run(self):
+        """Main loop - connect and continuously scan for ports."""
+        if not self.connect():
+            logger.error("Failed to connect. Exiting.")
+            return
+
+        self.running = True
+
+        try:
+            logger.info("Starting port detection loop...")
+
+            # Initial scan
+            self.scan_and_forward()
+
+            # Continuous scanning
+            while self.running:
+                time.sleep(self.scan_interval)
+                self.scan_and_forward()
+
+        except KeyboardInterrupt:
+            logger.info("\nReceived interrupt signal, shutting down...")
+        finally:
+            self.shutdown()
+
+    def shutdown(self):
+        """Clean up all tunnels and close connection."""
+        self.running = False
+
+        logger.info("Stopping all tunnels...")
+        for remote_port in list(self.tunnels.keys()):
+            self.stop_forwarding_port(remote_port)
+
+        if self.ssh_client:
+            self.ssh_client.close()
+            logger.info("✓ Disconnected")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Automatically forward ports from a remote SSH server to your local machine",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  ssh-auto-forward myserver              # Forward ports from host defined in SSH config
+  ssh-auto-forward myserver -v           # Enable verbose logging
+  ssh-auto-forward myserver -p 4000:9000 # Use local port range 4000-9000
+  ssh-auto-forward myserver -s 22,80,443 # Skip specific ports
+        """,
+    )
+    parser.add_argument("host", help="Host alias from SSH config or hostname")
+    parser.add_argument("-v", "--verbose", action="store_true", help="Enable verbose logging")
+    parser.add_argument("-i", "--interval", type=int, default=5, help="Scan interval in seconds (default: 5)")
+    parser.add_argument(
+        "-p",
+        "--port-range",
+        default="3000:10000",
+        metavar="MIN:MAX",
+        help="Local port range to use (default: 3000:10000)",
+    )
+    parser.add_argument(
+        "-s",
+        "--skip",
+        default="",
+        metavar="PORTS",
+        help="Comma-separated list of ports to skip (default: all ports < 1000)",
+    )
+    parser.add_argument("-c", "--config", help="Path to SSH config file")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    args = parser.parse_args()
+
+    if args.verbose:
+        logging.getLogger("ssh-auto-forward").setLevel(logging.DEBUG)
+        paramiko.common.logging.basicConfig(level=paramiko.common.logging.DEBUG)
+
+    # Parse port range
+    try:
+        port_min, port_max = map(int, args.port_range.split(":"))
+        port_range = (port_min, port_max)
+    except ValueError:
+        logger.error("Invalid port range. Use format MIN:MAX (e.g., 3000:10000)")
+        sys.exit(1)
+
+    # Parse skip ports
+    skip_ports = DEFAULT_SKIP_PORTS.copy()
+    if args.skip:
+        try:
+            extra_skip = {int(p.strip()) for p in args.skip.split(",")}
+            skip_ports.update(extra_skip)
+        except ValueError:
+            logger.error("Invalid skip ports. Use comma-separated integers (e.g., 22,80,443)")
+            sys.exit(1)
+
+    forwarder = SSHAutoForwarder(
+        host_alias=args.host,
+        ssh_config_path=args.config,
+        skip_ports=skip_ports,
+        port_range=port_range,
+        scan_interval=args.interval,
+    )
+
+    forwarder.run()
+
+
+if __name__ == "__main__":
+    main()

ssh_auto_forward-0.0.1.dist-info/METADATA

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: ssh-auto-forward
+Version: 0.0.1
+Summary: Auto-forward SSH ports
+Author: alexe
+License: WTFPL
+Keywords: port-forwarding,remote-development,ssh,tunnel
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: paramiko>=3.4.0
+Description-Content-Type: text/markdown
+
+# SSH Auto Port Forwarder
+
+Automatically detect and forward ports from a remote SSH server to your local machine. Similar to VS Code's port forwarding feature, but fully automatic.
+
+## Features
+
+- Automatically discovers listening ports on the remote server
+- Shows process names for each forwarded port
+- Forwards ports to your local machine via SSH tunneling
+- Handles port conflicts by finding alternative local ports
+- Auto-detects new ports and starts forwarding
+- Auto-detects closed ports and stops forwarding
+- Terminal title shows tunnel count
+- Runs in the background with status updates
+- Reads connection details from your SSH config
+- Skips well-known ports (< 1000) by default
+
+## Installation
+
+### With uv (recommended):
+
+```bash
+uvx ssh-auto-forward hetzner
+```
+
+### Install locally:
+
+```bash
+cd portforwards
+uv sync
+```
+
+This installs the `ssh-auto-forward` command.
+
+### Local development:
+
+```bash
+make run ARGS=hetzner
+make run ARGS="hetzner -v"
+```
+
+## Usage
+
+### Basic usage - uses host from your SSH config:
+
+```bash
+ssh-auto-forward hetzner
+```
+
+### Options:
+
+```
+-v, --verbose           Enable verbose logging
+-i, --interval SECS     Scan interval in seconds (default: 5)
+-p, --port-range MIN:MAX Local port range for remapping (default: 3000:10000)
+-s, --skip PORTS        Comma-separated ports to skip (default: all ports < 1000)
+-c, --config PATH       Path to SSH config file
+--version               Show version and exit
+```
+
+### Examples:
+
+```bash
+# Scan every 3 seconds
+ssh-auto-forward hetzner -i 3
+
+# Use specific port range
+ssh-auto-forward hetzner -p 4000:9000
+
+# Skip specific ports
+ssh-auto-forward hetzner -s 22,80,443
+
+# Verbose mode
+ssh-auto-forward hetzner -v
+```
+
+## How it works
+
+1. Connects to your remote server using your SSH config
+2. Runs `ss -tlnp` on the remote to find listening ports
+3. Creates SSH tunnels for each discovered port
+4. Continuously monitors for new/closed ports
+5. Handles port conflicts on your local machine
+
+## Status messages
+
+```
+✓ Connected!
+✓ Forwarding port 2999 (python3)
+✓ Forwarding port 7681 (ttyd)
+✓ Forwarding remote port 19840 -> local port 3000 (node)
+✗ Remote port 2999 is no longer listening, stopping tunnel
+```
+
+The terminal title also updates to show: `ssh-auto-forward: hetzner (18 tunnels active)`
+
+## Testing
+
+Start a test server on your remote machine:
+
+```bash
+ssh hetzner "python3 -m http.server 9999 --bind 127.0.0.1 &"
+```
+
+Then run `ssh-auto-forward hetzner` and you should see:
+
+```
+✓ Forwarding remote port 9999 -> local port 3003 (python3)
+```
+
+Access it locally:
+
+```bash
+curl http://localhost:3003/
+```
+
+## Stopping
+
+Press `Ctrl+C` to stop the forwarder and close all tunnels.
+
+## Requirements
+
+- Python 3.10+
+- paramiko
+- Remote server must have `ss` or `netstat` command available
+
+## Tests
+
+### Unit tests (run locally, no SSH required):
+
+```bash
+make test
+# or
+uv run pytest tests/ -v
+```
+
+### Integration tests (require SSH access):
+
+```bash
+SSH_AUTO_FORWARD_TEST_HOST=hetzner uv run pytest tests_integration/ -v
+```
+
+The integration tests:
+- Test that remote ports are forwarded to the same local port when available
+- Test that ports increment by 1 when the local port is busy
+- Test auto-detection of new ports
+- Test auto-cleanup when remote ports close

ssh_auto_forward-0.0.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+ssh_auto_forward/__init__.py,sha256=6R1wUse_b0k-zeWxZOixpeqjc_vrZjdkQ730b3LqsF0,166
+ssh_auto_forward/__version__.py,sha256=sXLh7g3KC4QCFxcZGBTpG2scR7hmmBsMjq6LqRptkRg,22
+ssh_auto_forward/cli.py,sha256=dtUaBqyYaKH5b1Jl7Qnop2ZSUG3VsfR6XmmBXA3l_Lg,24046
+ssh_auto_forward-0.0.1.dist-info/METADATA,sha256=jw0B7WlgrhGZn5tnRFTqvaAoJfWpCmEzqphfLLlzq80,3892
+ssh_auto_forward-0.0.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+ssh_auto_forward-0.0.1.dist-info/entry_points.txt,sha256=2DQMDbkXDrmoBg03lQq3vMJ5O1W2ZrxapDgKztQQUOQ,63
+ssh_auto_forward-0.0.1.dist-info/RECORD,,

ssh_auto_forward-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ssh_auto_forward-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ssh-auto-forward = ssh_auto_forward.cli:main