Infrastructure10 min

SSHKeySetupforn8n

Generate an SSH private key and add it to n8n for remote server access. Covers key generation, server configuration, and credential setup for homelab monitoring workflows.

n8n's SSH node uses private key authentication to run commands on remote servers. This guide gets you from zero to a working SSH credential in n8n -- about 10 minutes total.

Generate the Key Pair

On your local machine (or wherever you run n8n), generate an Ed25519 key pair:

ssh-keygen -t ed25519 -C "n8n-automation" -f ~/.ssh/n8n_key

When prompted for a passphrase, leave it empty (press Enter twice). n8n's SSH node doesn't support passphrase-protected keys.

This creates two files:

  • ~/.ssh/n8n_key -- your private key (stays with n8n, never share this)
  • ~/.ssh/n8n_key.pub -- your public key (goes on the target server)

If your system doesn't support Ed25519 (older OpenSSH), use RSA instead:

ssh-keygen -t rsa -b 4096 -C "n8n-automation" -f ~/.ssh/n8n_key

Add the Public Key to Your Server

Copy the public key to the server you want n8n to monitor:

ssh-copy-id -i ~/.ssh/n8n_key.pub your_user@your_server_ip

If ssh-copy-id isn't available, do it manually:

cat ~/.ssh/n8n_key.pub | ssh your_user@your_server_ip "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"

Docker Access

If your n8n workflow runs Docker commands (like the Homelab Health Dashboard), the SSH user needs Docker access. Either:

Option A -- Add user to docker group (recommended):

sudo usermod -aG docker your_user

Log out and back in for the change to take effect.

Option B -- Use root (simpler but less secure): Use root as the SSH user. Not recommended for production, but fine for a personal homelab.

Test the Connection

Before configuring n8n, verify the key works:

ssh -i ~/.ssh/n8n_key your_user@your_server_ip "hostname && docker ps --format '{{.Names}}'"

You should see the server's hostname and a list of running containers, with no password prompt.

Get the Private Key Content

n8n needs the contents of the private key file, not the file path. Print it:

cat ~/.ssh/n8n_key

The output looks like this:

-----BEGIN OPENSSH PRIVATE KEY-----
b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAA...
[several lines of base64]
...
-----END OPENSSH PRIVATE KEY-----

Copy everything including the BEGIN and END lines. You'll paste this into n8n next.

Add the Credential in n8n

  1. In n8n, go to Credentials (left sidebar)
  2. Click Add Credential
  3. Search for SSH and select SSH Private Key
  4. Fill in the fields:
    • Host: Your server's IP or hostname (e.g., 192.168.1.100)
    • Port: 22 (default)
    • Username: The SSH user from the previous step
    • Private Key: Paste the full key content
    • Passphrase: Leave empty (we created the key without one)
  5. Click Test Connection to verify
  6. Click Save

Every SSH node in your workflows can now use this credential.

If you're importing a workflow template that uses SSH, the template will prompt you to connect this credential when you first open it.

n8n Running in Docker?

If n8n runs inside a Docker container (the most common self-hosted setup), it can't access ~/.ssh/ on the host. That's exactly why n8n stores the private key in its credential system rather than reading from a file path.

The credential you just created works regardless of whether n8n runs on bare metal, in Docker, or in Kubernetes. The key content is stored in n8n's encrypted credential database.

Troubleshooting

"Authentication failed" error -- Verify: (1) you pasted the private key, not the public key (it should say OPENSSH PRIVATE KEY), (2) the username matches, (3) the public key is in the server's ~/.ssh/authorized_keys.

"Connection timed out" -- The server isn't reachable from wherever n8n runs. If n8n is in Docker, make sure the server IP is accessible from the Docker network (not localhost).

"Permission denied (publickey)" -- The server has PubkeyAuthentication disabled. Check /etc/ssh/sshd_config on the server:

grep PubkeyAuthentication /etc/ssh/sshd_config

If it says no, change it to yes and restart SSH: sudo systemctl restart sshd.

"docker: permission denied" -- The SSH user isn't in the Docker group. Run sudo usermod -aG docker your_user on the server, then log out and back in.

Key format issues -- If you get format errors, make sure you copied the entire key including the header/footer lines. Some terminals truncate long clipboard contents. Try copying from a text editor instead.

This guide covers SSH setup for the Homelab Health Dashboard and any n8n workflow that connects to remote servers via SSH.

Resources

Used In

← Back to Guides