How to Configure n8n SSH Sandbox

Published
Length
3 min read

Luis Felipe Dias

All posts

To set up an n8n ssh sandbox, pair restricted Linux accounts with OpenSSH certificates. Then route your workflow commands through that locked-down host user. Engineering teams often attach remote shell execution to workflow nodes or AI Agent nodes. In n8n, an AI Agent node links a chat model with one or more tools. The agent then decides which tools to call to finish its task. When teams give that workflow a broad SSH key, any mistake affects the whole server. A bad prompt or broken workflow ste

SSH Access Management + AI Sandbox Environments: the complete guide

Architecture patterns, implementation strategies, and security best practices. Delivered to your inbox.

Free white paper. No spam. Unsubscribe anytime.

To set up an n8n ssh sandbox, pair restricted Linux accounts with OpenSSH certificates. Then route your workflow commands through that locked-down host user. Engineering teams often attach remote shell execution to workflow nodes or AI Agent nodes. In n8n, an AI Agent node links a chat model with one or more tools. The agent then decides which tools to call to finish its task. When teams give that workflow a broad SSH key, any mistake affects the whole server. A bad prompt or broken workflow step can delete files or read private keys.

How an n8n ssh sandbox works in OpenSSH

A basic n8n ssh sandbox starts on the target Linux host. First, admins create a dedicated local user with very few file permissions. They place this user in a locked directory or a clean container on the host. This limits which folders and system binaries the workflow can read or run.

Next, teams replace static private keys with OpenSSH certificates. Certificate support for users and hosts arrived in OpenSSH 5.4. An OpenSSH certificate holds a public key, identity data, principals, and signed options. A Certification Authority key signs the certificate to make it valid. OpenSSH uses a much simpler format than X.509 certificates. Admins sign user keys to limit which host accounts the n8n workflow can enter. They also attach options to the certificate that restrict port forwarding or force one command.

Inside n8n, builders wire the remote command workflow to the AI Agent node. Starting in n8n 1.82.0, all AI Agent nodes run as a Tools Agent. You must attach at least one tool sub-node to the agent. Teams often use a Call n8n Workflow Tool or Custom Code Tool to trigger SSH. The agent picks the tool, passes the arguments, and waits for the host output.

What the native sandbox solves and what it misses

Host-level user rules and OpenSSH certificates solve the login problem well. They check who can log in and which host account they enter. A forced command on a certificate also blocks random shell calls when only one script runs.

Still, this static setup struggles when an agent needs to run varied commands. If you allow a general shell for fixing, the host cannot judge each command in flight. Once the session starts, the OS only checks basic file permissions. It does not require human approval when an agent tries to restart a core service. Also, stdout from a shell tool can return raw emails, phone numbers, or card numbers. Native SSH passes that raw text straight back into the workflow state and model history. Host logs also miss which workflow run or agent prompt triggered a specific shell command.

SSH Access Management + AI Sandbox Environments: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Adding command checks and output controls to workflows

To close this gap, teams move controls from the static login step to the command level. Every command from an n8n workflow should pass through an inspection step before it runs. Read-only checks like viewing disk space or reading safe log lines can run right away. Risky actions like editing files or stopping services should pause and ask a human first.

Teams also need to clean command output before it reaches the n8n AI Agent node. Rewriting matched fields like emails, phone numbers, and national IDs keeps secrets out of chat logs. Tying each shell command to a specific workflow identity also makes audits clear and fast.

Add command and file guardrails to SSH access

Host firewalls and certificate principals control who opens an SSH session. Yet an allowed user or agent can still run a bad one-shot command or pull sensitive files over sftp. In practice, hoop.dev provides an open-source SSH server with guardrails on the host that uses OpenSSH certificates.

Using hoop.dev SSH controls, guardrails check one-shot commands, env variable names, and sftp or scp paths before they run. Port forwards default to deny unless the target is listed. Because interactive shells have no statement boundary and carry no guardrails, teams can turn them off so every command is checked and logged. Check out the MIT-licensed project on GitHub.

Frequently asked questions

How does an n8n AI Agent run SSH commands?

An n8n AI Agent connects a chat model to one or more tool sub-nodes. Teams use a Call n8n Workflow Tool to invoke a sub-workflow that runs the SSH node.

Why are static SSH keys risky in n8n workflows?

Static keys often grant full shell permissions and never expire on their own. If a workflow leaks the key or runs a bad command, the whole host is exposed.

Can OpenSSH certificates restrict what n8n does on a host?

Yes, OpenSSH certificates can restrict logins to specific principals and set options like forced commands. Still, they cannot inspect dynamic arguments or rewrite sensitive text in command output.

Save the open-source gateway.

hoop is MIT-licensed infrastructure for controlling how AI agents reach production data. Star hoophq/hoop so you can inspect it, deploy it, or share it when your team starts governing agent access.