{"id":12066,"library":"ssh2","title":"SSH2 Client and Server for Node.js","description":"ssh2 is a pure JavaScript implementation of an SSH2 client and server for Node.js, enabling secure remote command execution, file transfers (SFTP), and interactive shell sessions. The current stable version is 1.17.0, with development actively maintained against recent OpenSSH versions (e.g., OpenSSH 8.7). This library is distinguished by its comprehensive support for both client and server roles, offering an extensive API for various channel types (exec, shell, direct-tcpip, X11, subsystems) and pluggable authentication methods, including password and public key. It provides fine-grained control over SSH connections, making it suitable for building custom SSH tooling, automating deployments, or implementing secure backend services. While it does not adhere to a strict release cadence, updates are released as features are added or bugs are fixed, ensuring ongoing compatibility and security.","status":"active","version":"1.17.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/mscdex/ssh2","tags":["javascript","ssh","ssh2","sftp","secure","shell","exec","remote","client"],"install":[{"cmd":"npm install ssh2","lang":"bash","label":"npm"},{"cmd":"yarn add ssh2","lang":"bash","label":"yarn"},{"cmd":"pnpm add ssh2","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used to help generate an optimal default cipher list. It's an optional package dependency that is automatically built and used if possible.","package":"cpu-features","optional":true}],"imports":[{"note":"Since v1.0.0, Client is a named export. Older versions might have had it as a default export or directly on the `require('ssh2')` object. Using named import/require is the modern and correct approach.","wrong":"const Client = require('ssh2');","symbol":"Client","correct":"import { Client } from 'ssh2';"},{"note":"Similar to Client, Server is a named export since v1.0.0. Ensure you destructure it from the module.","wrong":"const Server = require('ssh2');","symbol":"Server","correct":"import { Server } from 'ssh2';"},{"note":"Utility functions like `parseKey` are typically found in a separate `lib/utils` path and imported as a module. Direct named import from `ssh2` might not expose all utilities or could change.","wrong":"import { utils } from 'ssh2';","symbol":"utils","correct":"import * as utils from 'ssh2/lib/utils';"}],"quickstart":{"code":"const { readFileSync } = require('fs');\nconst { Client } = require('ssh2');\n\nconst conn = new Client();\nconn.on('ready', () => {\n  console.log('Client :: ready');\n  conn.exec('uptime', (err, stream) => {\n    if (err) throw err;\n    stream.on('close', (code, signal) => {\n      console.log(`Stream :: close :: code: ${code}, signal: ${signal}`);\n      conn.end();\n    }).on('data', (data) => {\n      console.log('STDOUT: ' + data);\n    }).stderr.on('data', (data) => {\n      console.error('STDERR: ' + data);\n    });\n  });\n}).on('error', (err) => {\n  console.error('Client Error:', err.message);\n}).connect({\n  host: process.env.SSH_HOST ?? '127.0.0.1',\n  port: parseInt(process.env.SSH_PORT ?? '22', 10),\n  username: process.env.SSH_USERNAME ?? 'user',\n  privateKey: readFileSync(process.env.SSH_PRIVATE_KEY_PATH ?? './id_rsa')\n});","lang":"javascript","description":"This example demonstrates how to establish an SSH client connection to a server and execute a remote command ('uptime'), logging its standard output and error."},"warnings":[{"fix":"Review the v1.0.0 breaking changes detailed in the GitHub issue #935 (linked in the README) and update import statements and method calls accordingly. Use named imports for `Client` and `Server`.","message":"Version 1.0.0 introduced significant breaking changes. Key classes like `Client` and `Server` became named exports instead of default exports or properties of the main module object. API method signatures, particularly for `Client.exec` and `Client.shell`, changed to pass the stream directly to the callback rather than returning it. `SFTPStream` and `Channel` are no longer directly exported.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Adjust `hostVerifier()` implementations to be idempotent and handle multiple calls per connection, including during rekey events.","message":"The `hostVerifier()` client option will now be called every time a handshake occurs, including during rekeying. Ensure your host verification logic handles this repeated invocation.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Ensure your Node.js environment meets the minimum version requirements. Upgrade Node.js to at least v12.0.0 for full key type compatibility.","message":"Node.js v10.16.0 or newer is required. For Ed25519 key support, Node.js v12.0.0 or newer is necessary.","severity":"gotcha","affected_versions":"<10.16.0 || <12.0.0 for Ed25519"},{"fix":"While not strictly required, resolving `cpu-features` installation issues (e.g., build toolchain problems) can improve performance. Check `cpu-features` documentation for its specific system requirements.","message":"The `cpu-features` package is an optional dependency used to optimize cipher list generation. If it fails to install or build, `ssh2` will still function but might use a less optimal default cipher list.","severity":"gotcha","affected_versions":">=0.x"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Verify the `username`, `password`, or `privateKey` used in the `connect` options. Ensure the `privateKey` path is correct and the key file is readable by the Node.js process. Check server logs for more details on authentication failures.","cause":"The SSH server rejected all attempted authentication methods (e.g., password, private key). This usually means incorrect credentials, an invalid private key, or the server not supporting the client's offered authentication methods.","error":"Error: All configured authentication methods failed"},{"fix":"Confirm the `host` and `port` are correct. Check if the SSH server process is running on the target machine. Verify network connectivity and firewall rules between the client and server.","cause":"The client could not establish a TCP connection to the specified host and port. This typically indicates the SSH server is not running, is not accessible from the client's network, or a firewall is blocking the connection.","error":"Error: connect ECONNREFUSED"},{"fix":"Ensure `privateKey` is correctly populated, either directly with a key string or by reading a valid key file using `readFileSync`. Double-check the path to the private key file.","cause":"The `privateKey` option was provided with an empty or undefined value, or the file path was incorrect leading to an empty buffer.","error":"Error: privateKey is required"}],"ecosystem":"npm"}