SSH
Runs commands, scripts, and file uploads on a remote server over SSH/SCP. An agent can execute shell commands (with optional sudo), upload text content as a file, or run a multi-line bash script — all against a single configured host.
Add to an agent node's tools array with _node_type: "tool-ssh". See Connector Reference — How connectors are used.
Authentication
| Field | Required | Description |
|---|---|---|
host | Yes | SSH connection target in user@hostname or user@hostname:port form. Passed directly to the ssh/scp CLI. |
private_key | No | PEM-encoded private key content. Written to a temporary file (mode 0600) and passed via ssh -i for the duration of each call; if omitted, the worker's default SSH credentials/agent are used. |
{
"name": "ssh",
"_node_type": "tool-ssh",
"host": "deploy@web1.example.com",
"private_key": "{{ secret.SSH_DEPLOY_KEY }}"
}
Tools
ssh_exec
Execute a shell command on a remote server via SSH. Returns combined stdout+stderr.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
command | string | Yes | Shell command to execute on the remote server |
sudo | boolean | No | Prefix with sudo |
Returns: The combined stdout+stderr of the remote command. If the SSH invocation itself errors (non-zero exit), returns exit error: <err>\noutput: <output> instead of failing the tool call.
ssh_upload
Upload text content as a file to the remote server via SCP.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
content | string | Yes | Text content to write |
remote_path | string | Yes | Full remote path e.g. /tmp/deploy.sh |
Returns: "uploaded to <remote_path>" on success. Returns an error if scp fails.
ssh_run_script
Upload and execute a multi-line bash script on the remote server.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
script | string | Yes | Multi-line bash script to run remotely |
Returns: The combined stdout+stderr of the script, executed via bash <<'__EOF__' ... __EOF__ over SSH. If the SSH invocation errors, returns script error: <err>\n<output> instead of failing the tool call.