Tunnel-SSH

Tunnel-SSH is a Node.js library for programmatically creating SSH tunnels, most commonly used to forward a remote database or internal service port to localhost during development. Built on top of the ssh2 client library, version 5 was rewritten to be more extendable, exposing the same low-level configuration options as the underlying SSH client and server rather than hiding them behind opinionated defaults.

Configuration is split into four independently-configurable parts — the tunnel server, the local TCP server, the SSH client, and SSH forwarding options — so callers can reach any binding behavior supported by ssh2 directly, including dynamic port mapping and custom bind addresses.

What You Get

• A single async function to create an SSH tunnel and forward a local TCP port to a remote destination
• Separately configurable tunnel server, TCP server, SSH client, and SSH forwarding options
• Support for dynamic port mapping and custom bind addresses (defaults to all interfaces)
• TypeScript type definitions shipped in the package
• Direct use of the ssh2 client under the hood, so any ssh2-supported auth method (password, private key, agent) is available

Common Use Cases

• Connecting a local development environment to a remote database that’s only reachable via an SSH bastion host
• Forwarding a remote internal service (e.g. an admin panel or metrics endpoint) to localhost for debugging
• Setting up ephemeral SSH tunnels inside CI pipelines or scripts that need temporary access to a private network

Under The Hood

Architecture The library is a thin orchestration layer (index.js, ~135 lines) around the ssh2 client: it opens an SSH connection, then creates a local TCP server whose incoming connections are piped into an SSH port-forward stream on the established connection. Configuration is deliberately split into four namespaces (tunnel server, TCP server, SSH client, SSH forwarding) that map directly onto the corresponding options of the local net server and the ssh2 client/forwarding APIs. Tech Stack Plain JavaScript with a single runtime dependency, ssh2, plus hand-written TypeScript declaration files under types/ for consumers using TS. No build step — the package ships index.js directly as both source and distributable. Code Quality The repository has no automated test suite; correctness relies on community-driven PRs and manual verification, which the README itself notes as the project’s long-running maintenance model (community-driven since its original creation as a teaching example). API Design The public surface is a single tunnel-creation call accepting four grouped option objects, mirroring ssh2’s own option shapes rather than inventing a new abstraction — this keeps the library’s ceiling as high as ssh2 itself at the cost of a slightly more verbose call site than a fully opinionated wrapper.