How-To Guide
Run Hermes Commands Remotely via SSH
Configure Hermes Agent to execute commands on a remote server while keeping the agent code local — perfect for sandboxing.
Quick answer
The SSH terminal backend keeps the Hermes agent on your machine while commands execute on a remote server, so the agent can't read its own .env or modify its own code. It's the most isolated backend: blast radius is the remote box, not your local secrets. Configure it with the target host's SSH access.
SSH backend is the most secure way to run Hermes — the agent code stays on your machine while commands execute on a remote server. The agent can't read its own .env file, can't modify its own code, and the remote server acts as a natural sandbox.
Managed cloud · API costs included · Skill library · Cancel anytime
Before you start:
- ☑Hermes Agent installed locally
- ☑SSH access to a remote server
- ☑SSH key authentication configured (recommended)
Steps
- 1
Set up SSH access
Ensure you can SSH to your server without a password prompt: ssh user@server
- 2
Configure the backend
In config.yaml, set terminal: backend: ssh
- 3
Add SSH connection details
Set ssh_host, ssh_user, ssh_port (default 22), and optionally ssh_key
- 4
Set the remote working directory
Set terminal: cwd: /home/user/projects (path on the remote server)
- 5
Test the connection
Run hermes and ask it to execute 'pwd' — should show the remote path
Pro Tips
- 💡Use SSH keys instead of passwords — add your public key to ~/.ssh/authorized_keys on the remote server
- 💡Configure passwordless sudo on the remote server for commands that need root access
- 💡The agent can't access local files in SSH mode — only files on the remote server
- 💡Great for using powerful remote hardware (GPU servers, beefy VPS) while running Hermes locally
Troubleshooting
❌ Connection times out
✅ Check that the remote server allows SSH connections. Verify firewall rules: sudo ufw allow 22
❌ Permission denied (publickey)
✅ Your SSH key isn't recognized. Either specify ssh_key path in config.yaml or add your public key to the server's authorized_keys file.
❌ Commands fail with 'command not found'
✅ The remote shell may not have the same PATH as interactive sessions. Use full paths (/usr/bin/python3) or source the profile in your commands.
❌ sudo commands fail
✅ Configure passwordless sudo on the remote: echo 'username ALL=(ALL) NOPASSWD: ALL' | sudo tee /etc/sudoers.d/username
FAQ
Why is the SSH backend considered the most secure?
The agent code and secrets stay local while commands run on a remote server. The agent can't read its own .env or alter its own code, so a bad command's blast radius is the remote box.
What do I need to configure it?
SSH access to the target server — host, user, and key. Hermes then routes executed commands over SSH instead of running them locally.
When is SSH backend the right choice?
When you want strong isolation between the agent and your local secrets, or when the real work lives on a remote server anyway.