SSH and SFTP client library for React Native

SSH and SFTP client library for React Native on iOS and Android.

Installation

npm install @speedshield/react-native-ssh-sftp

iOS

No Podfile edits are needed. The iOS side is backed by Citadel, a pure-Swift SSH/SFTP library, vendored as a precompiled XCFramework and wired up through RNSSHClient.podspec, which CocoaPods and Expo's autolinking resolve automatically like any other autolinked native dependency.

Just run pod install in your ./ios directory after installing the package, same as you would for any other native module:

cd ios
pod install
cd -

[!TIP] Adding a postinstall script to your package.json file to run pod install after npm install is a good idea. The pod-install package is a good way to do this.

{
  "scripts": {
    "postinstall": "npx pod-install"
  }
}

[!NOTE] This library requires iOS 18.0 or later, needed for the Swift concurrency APIs (SE-0417) that the Citadel-based connection handling relies on. tvOS is not supported.

Android

No additional steps are needed for Android.

Linking

This library autolinks via the Expo Modules API, so manual linking is not required in either setup:

• Expo-managed apps pick it up automatically.
• Bare React Native apps (RN >= 0.74) need the expo package installed as an optional dependency purely for its autolinking infrastructure - see Installing Expo modules in an existing React Native project. You don't need any other part of the Expo SDK.

Usage

All functions that run asynchronously where we have to wait for a result returns Promises that can reject if an error occurred.

[!NOTE] On the old NMSSH-based iOS implementation, the Simulator only worked with the x86_64 (Intel/Rosetta) Simulator, not the native arm64 Simulator on Apple Silicon Macs - NMSSH didn't ship a universal Simulator slice, so you'd need to explicitly select or force an x86_64 Simulator target (see this issue for background). The Citadel-based rewrite's XCFramework does ship a genuine universal Simulator slice (arm64 + x86_64, verified in its Info.plist), so this specific limitation shouldn't apply anymore - but that's link-level evidence, not a full functional test, so a physical device is still the safer choice until someone confirms a real SSH connection end-to-end on the Simulator.

Create a client using password authentication

import SSHClient from '@speedshield/react-native-ssh-sftp';

SSHClient.connectWithPassword(
  "10.0.0.10",
  22,
  "user",
  "password"
).then(client => {/*...*/});

Create a client using public key authentication

import SSHClient from '@speedshield/react-native-ssh-sftp';

SSHClient.connectWithKey(
  "10.0.0.10",
  22,
  "user",
  privateKey="-----BEGIN RSA...",
  passphrase
).then(client => {/*...*/});

Public key authentication is also supported

{privateKey: '-----BEGIN RSA......'}
{privateKey: '-----BEGIN RSA......', publicKey: 'ssh-rsa AAAAB3NzaC1yc2EA......'}
{privateKey: '-----BEGIN RSA......', publicKey: 'ssh-rsa AAAAB3NzaC1yc2EA......', passphrase: 'Password'}

Close client

client.disconnect();

Execute SSH command

const command = 'ls -l';
client.execute(command)
  .then(output => console.warn(output));

Shell

Start shell

• Supported ptyType: vanilla, vt100, vt102, vt220, ansi, xterm

const ptyType = 'vanilla';
client.startShell(ptyType)
  .then(() => {/*...*/});

Read from shell

client.on('Shell', (event) => {
  if (event)
    console.warn(event);
});

Write to shell

const str = 'ls -l\n';
client.writeToShell(str)
  .then(() => {/*...*/});

Close shell

client.closeShell();

SFTP

Connect SFTP

client.connectSFTP()
  .then(() => {/*...*/});

List directory

const path = '.';
client.sftpLs(path)
  .then(response => console.warn(response));

Create directory

client.sftpMkdir('dirName')
  .then(() => {/*...*/});

Rename file or directory

client.sftpRename('oldName', 'newName')
  .then(() => {/*...*/});

Remove directory

client.sftpRmdir('dirName')
  .then(() => {/*...*/});

Remove file

client.sftpRm('fileName')
  .then(() => {/*...*/});

Download file

client.sftpDownload('[path-to-remote-file]', '[path-to-local-directory]')
  .then(downloadedFilePath => {
    console.warn(downloadedFilePath);
  });

// Download progress (setup before call)
client.on('DownloadProgress', (event) => {
  console.warn(event);
});

// Cancel download
client.sftpCancelDownload();

Upload file

client.sftpUpload('[path-to-local-file]', '[path-to-remote-directory]')
  .then(() => {/*...*/});

// Upload progress (setup before call)
client.on('UploadProgress', (event) => {
  console.warn(event);
});

// Cancel upload
client.sftpCancelUpload();

Close SFTP

client.disconnectSFTP();

Example app

You can find a very simple example app for the usage of this library here (predates the Expo Modules/Citadel rewrite, so treat it as a usage reference rather than a setup reference).

longphung/rnssh-test-app is a minimal manual test harness kept up to date against this library's current architecture, including the file: sibling-directory setup this repo's own native code needs for local development.

Credits

This package wraps the following libraries, which provide the actual SSH/SFTP functionality:

• Citadel (MIT license) for iOS, by Orlandos - a pure-Swift SSH/SFTP library built on Apple's swift-nio-ssh (Apache License 2.0)
• JSch for Android (from Matthias Wiedemann fork)

This package is a fork of Emmanuel Natividad's react-native-ssh-sftp package. The fork chain from there is as follows:

1. Gabriel Paul "Cley Faye" Risterucci
2. Bishoy Mikhael
3. Qian Sha