An SSH2 client module written in pure JavaScript for node.js
Switch branches/tags
Nothing to show
Pull request Compare This branch is 703 commits behind mscdex:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


An SSH2 client module written in pure JavaScript for node.js.

Development/testing is done against OpenSSH (6.0 currently).



npm install ssh2


  • Authenticate using keys, execute uptime on a server, and disconnect afterwards:
var Connection = require('ssh2');

var c = new Connection();
c.on('connect', function() {
  console.log('Connection :: connect');
c.on('ready', function() {
  console.log('Connection :: ready');
  c.exec('uptime', function(err, stream) {
    if (err)
      throw err;
    stream.on('data', function(data, extended) {
      console.log((extended === 'stderr' ? 'STDERR: ' : 'STDOUT: ')
                  + data);
    stream.on('end', function() {
      console.log('Stream :: EOF');
    stream.on('close', function() {
      console.log('Stream :: close');
    stream.on('exit', function(code, signal) {
      console.log('Stream :: exit :: code: ' + code + ', signal: ' + signal);
c.on('error', function(err) {
  console.log('Connection :: error :: ' + err);
c.on('end', function() {
  console.log('Connection :: end');
c.on('close', function(had_error) {
  console.log('Connection :: close');
  host: '',
  port: 22,
  username: 'frylock',
  privateKey: require('fs').readFileSync('/here/is/my/key'),
  publicKey: require('fs').readFileSync('/here/is/my/')

// example output:
// Connection :: connect
// Connection :: ready
// STDOUT:  17:41:15 up 22 days, 18:09,  1 user,  load average: 0.00, 0.01, 0.05
// Stream :: exit :: code: 0, signal: undefined
// Connection :: end
// Connection :: close


require('ssh2') returns a Connection object

Connection events

  • connect() - A connection to the server was successful.

  • ready() - Authentication was successful.

  • keyboard-interactive(< string >name, < string >instructions, < string >instructionsLang, < array >prompts, < function >finish) - The server is asking for replies to the given prompts for keyboard-interactive user authentication. name is generally what you'd use as a window title (for GUI apps). prompts is an array of { prompt: 'Password: ', echo: false } style objects (here echo indicates whether user input should be displayed on the screen). The answers for all prompts must be provided as an array of strings and passed to finish when you are ready to continue. Note: It's possible for the server to come back and ask more questions.

  • error(< Error >err) - An error occurred. A 'level' property indicates 'connection-socket' for socket-level errors and 'connection-ssh' for SSH disconnection messages. In the case of 'connection-ssh' messages, there may be a 'description' property that provides more detail.

  • end() - The socket was disconnected.

  • close(< boolean >hadError) - The socket was closed. hadError is set to true if this was due to error.

Connection methods

  • (constructor)() - Creates and returns a new Connection instance.

  • connect(< object >config) - (void) - Attempts a connection to a server using the information given in config:

    • user - < string > - Username for authentication. Default: (none)

    • password - < string > - Password for password-based user authentication. Default: (none)

    • host - < string > - Hostname or IP address of the server. Default: ("")

    • port - < integer > - Port number of the server. Default: 22

    • privateKey - < mixed > - Buffer or string that contains an unencrypted private key for key-based user authentication (OpenSSH format). Default: (none)

    • publicKey - < mixed > - Buffer or string that contains a public key for key-based user authentication (OpenSSH format). Default: (none)

    • tryKeyboard - < boolean > - Try keyboard-interactive user authentication if primary user authentication method fails. Default: (false)

  • exec(< string >command[, < object >environment], < function >callback]]) - (void) - Executes command on the server, with an optional environment set before execution. callback has 2 parameters: < Error >err, < ChannelStream >stream. For exec, the stream will also emit 'exit' when the process finishes. If the process finished normally, the process return value is passed to the 'exit' callback. If the process was interrupted by a signal, the following are passed to the 'exit' callback: < null >code, < string >signalName, < boolean >didCoreDump, < string >description.

  • shell([< object >window,] < function >callback]]) - (void) - Starts an interactive shell session on the server, with optional terminal window settings. Valid window properties include: rows (defaults to 24), cols (defaults to 80), height (in pixels, defaults to 480), width (in pixels, defaults to 640), and term (value to use for $TERM, defaults to 'vt100'). Rows and cols overrides width and height when rows and cols are non-zero. Pixel dimensions refer to the drawable area of the window. Zero dimension parameters are ignored. callback has 2 parameters: < Error >err, < ChannelStream >stream.

  • end() - (void) - Disconnects the connection.


This is a normal duplex Stream, with one change: for any special data events (e.g. data from stderr for exec/shell), a second (string) argument is passed in to the 'data' event callback containing the type. So far the only defined type is 'stderr'.