Hermes Agent SSH means pointing the agent's terminal at a remote server: you run hermes config set terminal.backend ssh, put the host and user in your Hermes env file, and every shell command the agent runs from then on executes on that server instead of your laptop.
📺 Watch: Hermes Agent Just Made Multi-Device AI Agents INSANE!
🔥 Get the Agent OS as a free bonus: AI Profit Boardroom members get the full Agent OS zip, prompt libraries, daily tutorials and weekly live coaching calls. → Get inside
This guide covers the exact settings, how the connection works under the hood, what the persistent shell does and doesn't keep, how SSH compares with the Docker, Modal and local backends, and the separate Desktop feature that also uses SSH. Every setting here comes from the official Hermes configuration docs.
Julian Goldie shares his full agent setups, step-by-step trainings and weekly coaching calls inside the AI Profit Boardroom. If you want to talk through your own server plan first, book a free AI strategy session.
What the SSH backend changes
Hermes ships six built-in terminal backends: local, docker, ssh, modal, daytona and vercel_sandbox. Plugins add more, such as Singularity and Sprites.
The backend decides one thing: where the agent's shell commands actually run. With local, they run on the machine Hermes is installed on. With ssh, Hermes stays where it is, but the commands travel to a remote machine you manage.
The Hermes tools page labels the SSH backend "recommended for security", because the agent can't modify its own code. Its files live on one machine and its commands land on another.
One thing the SSH backend is not: a sandbox or a container. It is a real server, and whatever the agent runs there changes that server.
How to set up Hermes Agent SSH, step by step
- Pick the server. Any machine you can already reach with an SSH key works. Note the hostname, the user and the port.
- Switch the backend. Run hermes config set terminal.backend ssh. In config.yaml the same setting reads terminal, then backend: ssh.
- Add the two required variables to ~/.hermes/.env: TERMINAL_SSH_HOST (the docs use my-server.example.com) and TERMINAL_SSH_USER (the docs use ubuntu).
- Add the optional ones if you need them. TERMINAL_SSH_PORT defaults to 22. TERMINAL_SSH_KEY is the path to your private key, for example ~/.ssh/id_rsa, and falls back to your system default key.
- Start a new session and ask the agent to run hostname. The answer should be the server's name, not your laptop's.
Keep the split clear: the backend choice lives in config.yaml, and the host, user, port and key live in the .env file.
Authentication is key-based. Hermes connects with BatchMode=yes, which means no password prompt, so make sure your key already logs you in without typing anything.
📺 Watch: How to Run Hermes Agent in the Cloud for FREE
How the connection works under the hood
Hermes doesn't open a fresh login for every command. It uses SSH ControlMaster to reuse one connection, with a 5-minute idle keepalive.
At startup it connects with BatchMode=yes and StrictHostKeyChecking=accept-new. The second setting means a host you have never connected to is accepted and remembered the first time.
Right after connecting, Hermes captures the remote login shell's environment once and saves it as a snapshot. From then on, each command runs as a fresh ssh … bash -c that sources the snapshot, moves into the tracked working directory and runs your command.
That design is why the agent sees the same PATH and login exports on every call, even though each call is a new process.
Persistent shell: what carries over between commands
The setting terminal.persistent_shell is on by default. With it on, two things survive from one command to the next: the working directory and exported variables, such as export FOO=bar.
Three things do not survive: plain shell variables, functions and aliases you define mid-session. If a later step needs a value, export it.
To turn the feature off, run hermes config set terminal.persistent_shell false.
For SSH, the order of precedence is TERMINAL_SSH_PERSISTENT first, then terminal.persistent_shell (env name TERMINAL_PERSISTENT_SHELL). The local backend has its own switch, TERMINAL_LOCAL_PERSISTENT. Docker, Modal, Daytona, Vercel Sandbox and plugin backends ignore both.
📺 Watch: How to Run Hermes Agent OS on a VPS
SSH vs Docker, Modal and local
This table follows the backend security comparison in the Hermes security docs and the checkpoint rules in the checkpoints docs:
| Backend | Where commands run | Dangerous-command check | Checkpoints and /rollback | Persistent shell setting |
|---|---|---|---|---|
| local | Your own machine, no isolation | Yes | Yes | TERMINAL_LOCAL_PERSISTENT |
| ssh | A remote machine you manage | Yes | Yes | TERMINAL_SSH_PERSISTENT |
| docker | One long-lived container per Hermes process, via docker exec | Skipped, the container is the boundary | No | Ignored |
| modal | A cloud sandbox VM with set CPU, memory and disk | Skipped | No | Ignored |
The short version: SSH keeps the safety check and the rollback that local gives you, but moves the work off your machine. Docker and Modal give you a container wall instead, and trade away checkpoints for it.
For maximum isolation, the security docs suggest running the gateway itself on a separate machine or VM.
Planning which backend fits your setup? Book a free AI strategy session and bring your server list.
Skill variables, sudo and the ! shortcut
Skill variables. Variables a skill declares in required_environment_variables, or that you list under terminal.env_passthrough, travel with OpenSSH SendEnv. The values never appear in the command text.
The catch: the server's /etc/ssh/sshd_config needs a matching AcceptEnv line for those names. Without it, the server silently drops them and the remote shell sees them as unset. Hermes provider keys, such as OPENAI_API_KEY, are never forwarded, even if you list them.
Sudo. SUDO_PASSWORD is sent to whichever backend runs the command. On SSH, set it to the remote host's sudo password, not your laptop's.
The ! shortcut. Commands you type with a leading ! in the CLI always run on the machine where Hermes runs, never on the SSH server. So !hostname shows your machine, while the agent's terminal tool shows the server. Path completion in the composer does follow the SSH backend.
Desktop SSH connections are a separate feature
Hermes Desktop can also reach a server over SSH, but it does a different job. The terminal backend sends commands to a server. A Desktop SSH connection drives a whole Hermes install that lives on that server.
To add one, open Settings, Gateways, Add connection, pick the SSH kind and fill the SSH host field as user@host:22. User and port are optional. Your SSH key is used, and the app opens the tunnel, starts the remote dashboard and adopts a token over it.
A Desktop-owned SSH backend stops on its own after dashboard.ssh_isolated_idle_grace_s, which defaults to 900 seconds with no client connected and no turn running.
The v0.23.0 release (5 November 2026) keeps every registered gateway connected, so switching to an SSH gateway is instant. Terminal tabs run on the host they were opened on, with "New terminal on…" for any SSH gateway, and Desktop can now connect to Windows SSH hosts.
After you update Hermes, reconnect Desktop for any SSH backend. Restarting gateways alone doesn't refresh those processes.
For the full picture of running several machines side by side, read the Hermes multi-gateway connections guide.
My verdict on the SSH backend
Use SSH when you want the agent working on a real server, with the dangerous-command check and rollback still in place. It is the right call for a VPS that hosts your sites, a home lab box or a build server.
Use Docker or Modal when you want a throwaway wall around the work and don't need checkpoints. Stay on local only for trusted, hands-on development.
This is the kind of setup Julian walks members through inside the AI Profit Boardroom, and his Agent OS guide shows how the agent, tools and machines fit together. To compare models before you give one a server, check the scores on Goldie Bench. For a one-to-one plan, book a free AI strategy session.
FAQ
How do I get Hermes to run its commands on a remote server?
Run hermes config set terminal.backend ssh, then add TERMINAL_SSH_HOST and TERMINAL_SSH_USER to ~/.hermes/.env and start a new session.
Which key does the SSH backend log in with?
The private key at TERMINAL_SSH_KEY. If you leave it unset, Hermes uses your system default key. The port is 22 unless you set TERMINAL_SSH_PORT.
Will the agent remember my working folder and variables?
With terminal.persistent_shell on, which is the default, the working directory and exported variables carry over. Plain variables, functions and aliases don't.
What separates SSH from the Docker and Modal backends?
SSH runs on a machine you manage and keeps the dangerous-command check and rollback. Docker uses one persistent local container and Modal uses a cloud sandbox, and both skip that check because the container is the boundary.
Can Hermes Desktop open a remote install over SSH?
Yes. Under Settings, Gateways, add an SSH connection in user@host:22 form, and the app opens the tunnel and starts the remote dashboard.
Why are my skill's variables missing on the server?
The server's sshd_config needs an AcceptEnv line for those variable names. Without it, the server drops them without a warning.
Set the backend, add your host and key, run hostname to confirm, and you have a working Hermes Agent SSH setup.
