How-To Guide
Secure Your Hermes Agent Server — Best Practices
Harden your Hermes Agent deployment with firewall rules, SSH keys, approval workflows, and best practices.
Quick answer
Secure a Hermes server because the agent has shell access, your API keys, and your conversation memory. The essentials: keep the Web UI/dashboard port private (not public), harden SSH, lock down the gateway's secure context, and enable Tirith approvals for dangerous actions. Five minutes of hardening blocks the common attack vectors.
An exposed Hermes agent is a serious security risk — it has shell access, your API keys, and memory of your conversations. Five minutes of hardening prevents the most common attack vectors.
Managed cloud · API costs included · Skill library · Cancel anytime
Before you start:
- ☑Hermes Agent deployed on a VPS or server
- ☑SSH access to the server
- ☑Basic familiarity with ufw and SSH config
Steps
- 1
Use SSH keys only
Disable password auth in /etc/ssh/sshd_config and use SSH key pairs
- 2
Configure firewall
Use ufw to allow only SSH (22) and any webhook ports Hermes needs
- 3
Enable Tirith approvals
Set tirith: enabled: true so dangerous commands require your approval
- 4
Restrict allowed contacts
Whitelist specific user IDs in each channel config to prevent unauthorized access
- 5
Keep Hermes updated
Run hermes update regularly to get security patches
- 6
Use environment variables
Store API keys in .env files instead of config.yaml — never commit secrets to git
Pro Tips
- 💡The single most impactful step: set 'allowed_user_ids' for every connected channel. Without this, anyone who discovers your bot can interact with your agent.
- 💡Store API keys in a .env file and reference them in config.yaml — never commit config.yaml to git if it contains secrets
- 💡Enable Tirith approvals for shell commands — this gives you a human-in-the-loop safety net for dangerous operations
- 💡Treat the Hermes Web UI like an admin dashboard: never expose it publicly without authentication, HTTPS, and narrow firewall access
Troubleshooting
❌ Unknown users are messaging the Hermes Telegram bot
✅ Add 'telegram: allowedUserIds: [YOUR_USER_ID]' to config.yaml immediately. Get your user ID from @userinfobot on Telegram. Restart Hermes to apply.
❌ API keys showing up in logs
✅ Set 'logging: redactSecrets: true' in config.yaml. Also ensure your log files are not world-readable: 'chmod 600 ~/.hermes/logs/*.log'.
❌ Firewall blocking legitimate webhook traffic
✅ If using strict firewall rules, allow Telegram's IP ranges or switch to polling mode which needs no inbound connections.
FAQ
What's the biggest Hermes security risk?
Exposing the dashboard/Web UI or gateway to the public internet. The agent has shell access and your keys, so keep admin ports private — reachable only over localhost, your own network, or a managed host.
How do I limit what the agent can do?
Enable Tirith approvals so dangerous actions — file deletion, shell execution, side-effecting calls — require explicit confirmation. Combine with an SSH or Docker terminal backend to sandbox command execution.
Should I run Hermes as root?
No. Run it as a non-privileged user, restrict file permissions on ~/.hermes (it holds your .env and keys), and harden SSH on the host.