Skip to main content

SSH

Connect SSH credentials so workflows can run commands on Linux and Windows servers — VMs, bare metal, or anything outside Kubernetes. SSH is listed under Servers in the integrations catalog.

When Do You Need This?​

This integration is optional. Connect SSH when an automation needs to reach a host directly:

  • integrations.ssh — run a command on a remote server and capture its output.
  • script.run with executor_type: ssh — run a Bash, Python, JavaScript or PowerShell script on the host.
note

This is not what the Kubernetes Execute Bash runbook action uses — that runs inside the cluster in an ephemeral container or dedicated pod, and needs no SSH integration.

Prerequisites​

  • A user on the target hosts that NudgeBee can authenticate as, with only the privileges the automations need. Key-based authentication is strongly preferred over passwords.
  • For Proxy Agent mode, a Proxy Agent (Forager) with network access to the hosts.

Step 1: Open the Configuration Form​

Navigate to Admin > Integrations > Servers and select SSH, then click Add SSH Account.

The SSH tile in the Servers tab of the integrations catalog

  • Name of Ssh * (Required) — How this credential is identified when selecting an integration in a task, e.g. billing-vms.
  • Select Account * (Required) — The NudgeBee account this belongs to.

Step 2: Choose a Connection Mode​

K8s​

The agent connects from inside a cluster using a Kubernetes Secret.

  • Kubernetes secret containing SSH_KEY, SSH_HOST, SSH_USER keys * (Required)
KeyValue
SSH_HOSTHostname or IP of the target server
SSH_USERUsername to log in as
SSH_KEYPrivate key in PEM format
kubectl create secret generic nudgebee-ssh \
  --namespace nudgebee-agent \
  --from-literal=SSH_HOST=10.0.1.20 \
  --from-literal=SSH_USER=nudgebee \
  --from-file=SSH_KEY=./id_ed25519

The SSH configuration form in K8s connection mode, showing the Kubernetes secret field

Proxy Agent​

Forager opens the SSH connection. Credentials are configured here; which hosts may be reached is configured on the agent, not in this form — either a fixed host on the datasource, or allowed_hosts for dynamic mode, where NudgeBee supplies the target host at request time. See SSH datasource notes.

  • Credential Source — Cloud Push (default), AWS Sm, Gcp Sm, Azure Kv or Local. See credential sources.
  • Username — Default login user. Optional; a task may override it per command with user_name.
  • Private Key — The private key in PEM format. Preferred over a password.
  • Password — Used only when not authenticating with a key.
  • Passphrase — Required if the private key is encrypted.

The SSH form in Proxy Agent mode, showing the credential source, username, private key, password and passphrase fields

Step 3: Test and Save​

Click Test Connection, then Save.

Security Notes​

  • Give the SSH user the narrowest account that still lets the automations work, and prefer a dedicated key per integration so it can be revoked without affecting anyone else.
  • In dynamic mode, allowed_hosts is the boundary on what NudgeBee can reach. Keep it to the CIDR ranges or hostnames the automations actually need.
  • Forager verifies the server host key when the datasource sets known_hosts or host_key. Configure one of them for anything reachable outside a trusted network — see SSH datasource notes.

Verify the Integration​

  1. Click Test Connection on the form — it should succeed before you save.
  2. In a workflow, run an integrations.ssh task with a harmless command such as hostname or uptime, and confirm the output is what you expect.

Troubleshooting​

SymptomLikely CauseFix
permission denied (publickey)The public key is not in the user's authorized_keysAdd the matching public key on the target host.
Key is rejected but works elsewhereKey supplied in the wrong formatThe private key must be PEM. Convert with ssh-keygen -p -m PEM -f <keyfile>.
Authentication fails on an encrypted keyMissing passphraseSet Passphrase, or use an unencrypted key dedicated to NudgeBee.
Host key verification failedknown_hosts or host_key does not match the serverUpdate the agent's configured host key. Do not disable verification.
Connection refused for one host but not othersThe host is outside allowed_hostsAdd its address or CIDR range to the datasource's allowed_hosts.
Commands run as the wrong userThe task overrode the defaultCheck user_name on the task; it takes precedence over Username.