<!-- BusyBot node reference — https://busybot.net/tools/ssh/ -->

> Node: SSH (`ssh`) · Action (binary) · v1
> Category: Development · Credentials: SSH Credentials (`sshApi`)
> Updated: 2026-08-16

# SSH

> Execute commands and transfer files via SSH/SFTP

## Overview

The SSH tool connects to remote servers over the SSH protocol to execute shell commands, download files via SFTP, and upload files via SFTP. It supports both password and private key authentication. Commands return stdout, stderr, exit code, and signal. File downloads produce binary items stored in the binary store. File uploads read binary data from upstream items and send them to a remote path via SFTP. A single SSH connection is established per execution batch for efficiency.

**Category:** Development  
**Tool Name:** `ssh`  
**Version:** 1

**Appearance:** Icon: `lucide-Terminal` | Color: `#000000`

## Node Type

**Action (Binary)** — handles file/binary data operations

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool requires **SSH Credentials** credentials.
See the [Credentials Guide](https://busybot.net/credentials/ssh-api/) for setup instructions.

### Resources

| Resource | Value |
|----------|-------|
| Command | `command` |
| File | `file` |

### Operations

**Command**

| Operation | Value | Description |
|-----------|-------|-------------|
| Execute | `execute` | Execute a command on the remote server |

**File**

| Operation | Value | Description |
|-----------|-------|-------------|
| Download | `download` | Download a file from the remote server via SFTP |
| Upload | `upload` | Upload a file to the remote server via SFTP |

### Parameters

#### Command: Execute

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Command | `string` | Yes | — | The shell command to execute on the remote server. |
| Working Directory | `string` | No | — | Optional working directory for command execution. When set, the tool wraps the command as `sh -c 'cd <cwd> && <command>'`, which requires the remote server to have /bin/sh (true for OpenSSH-style servers). Leave empty for compatibility with restricted servers (e.g. Rebex demo) that whitelist specific commands and refuse `sh`. Supports ~/ for home directory. |
| Timeout (ms) | `number` | No | `60000` | Maximum time in milliseconds to wait for the command to complete before killing it. |
| Max Output Bytes | `number` | No | `5242880` | Maximum bytes of stdout/stderr to capture per stream. Output beyond this is truncated and a "truncated" flag is set. |
| Fail on Non-Zero Exit | `boolean` | No | `true` | If true, a non-zero exit code is treated as an error and routed accordingly. |

#### File: Download

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Path (`path`) | `string` | Yes | — | Full remote file path including file name. Supports ~/ for home directory. |
| Binary Property (`binaryPropertyName`) | `string` | Yes | `data` | Name of the output binary property to store the downloaded file. Names are case-sensitive — see the upstream node's Binary Data panel for the exact names to use. |
| Options | `collection` | No | `{}` | Additional options for file operations. |
| — File Name | `string` | No | — | Override the file name from the binary data or remote path. |

#### File: Upload

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Input Binary Field (`binaryPropertyName`) | `string` | Yes | `data` | Name of the input binary field containing the file to upload. Names are case-sensitive — see the upstream node's Binary Data panel for the exact names to use. |
| Target Directory (`path`) | `string` | Yes | — | Remote directory to upload the file to. The file name is taken from binary data. Supports ~/ for home directory. |
| Options | `collection` | No | `{}` | Additional options for file operations. |
| — File Name | `string` | No | — | Override the file name from the binary data or remote path. |

#### All Operations

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Max Concurrency | `number` | No | `1` | Maximum number of items to process concurrently. Keep low for SSH connections (default 1). |

This node's parameters are sent to the server literally. `{{ ... }}` expressions in Command, Path, Target Directory or Working Directory are **not** resolved against the item — they travel to the remote host as the text you typed. Build a dynamic command or path in an upstream node (for example Edit Fields) and select that field here instead.

## Output Data

One output item per input item — no operation fans out. What lands on the item differs sharply per operation:

| Operation | Output item |
|-----------|-------------|
| `command` / `execute` | The item JSON is **replaced** by the command result. Upstream fields do **not** pass through. Binary is forwarded unchanged. |
| `file` / `download` | The item JSON **passes through unchanged**; the downloaded file is added to the item's binary data under the Binary Property name, alongside any binary the item already carried. |
| `file` / `upload` | The item JSON is **replaced** by `{ "success": true }`. Upstream fields do **not** pass through. Binary is forwarded unchanged. |

A command result looks like this:

```json
{
  "stdout": "total 48\ndrwxr-xr-x 6 user user 4096 Jan 15 10:30 .",
  "stderr": "",
  "code": 0,
  "signal": null
}
```

- `code` is the process exit status and `signal` is the signal that killed it, or `null`.
- `truncated: true` is added when either stream hit Max Output Bytes and was cut short.
- With Fail on Non-Zero Exit on (the default), a non-zero `code` is turned into an item error. The error item still carries `stdout`, `stderr`, `code` and `signal`, so you can read the failing output on the Error branch. Turn the option off to treat a non-zero exit as an ordinary result and inspect `code` yourself.

On download, the file name is taken from the remote path unless you override it with the File Name option. On upload, the file name comes from the binary data's own file name unless File Name overrides it; if neither is available the item fails.

Reference the result downstream by expression, e.g. `{{ $json.stdout }}`.

## Usage Examples

- Run a shell command on a remote server and get the output
- Download a log file from a remote server via SFTP
- Upload a report to a remote server via SFTP
- Execute a deploy script on a production server
- Transfer backup files from a remote server

## Example Configuration

Run a command and capture its output:

```json
{
  "type": "ssh",
  "parameters": {
    "resource": "command",
    "operation": "execute",
    "command": "systemctl status nginx",
    "timeoutMs": 60000,
    "maxOutputBytes": 5242880,
    "failOnNonZeroExit": true
  }
}
```

Run a command from a working directory, tolerating a non-zero exit:

```json
{
  "type": "ssh",
  "parameters": {
    "resource": "command",
    "operation": "execute",
    "command": "ls -la",
    "cwd": "/var/log",
    "failOnNonZeroExit": false
  }
}
```

Download a log file into the item's binary data:

```json
{
  "type": "ssh",
  "parameters": {
    "resource": "file",
    "operation": "download",
    "path": "~/logs/application.log",
    "binaryPropertyName": "logFile"
  }
}
```

Upload a file from an upstream node, renaming it on the server:

```json
{
  "type": "ssh",
  "parameters": {
    "resource": "file",
    "operation": "upload",
    "path": "/etc/myapp/",
    "binaryPropertyName": "data",
    "options": {
      "fileName": "config.yml"
    }
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Execute commands and transfer files on remote servers via SSH/SFTP with password or private key authentication.