Before you start: do you actually want to self-host?
Self-hosting Hermes Agent is the right choice if you want full control over your data, you're comfortable with Linux server administration, you have specific compliance or privacy requirements, or you want to modify the agent's core behavior. The MIT license means you can do anything with it.
Skip this guide if your hourly rate is above $50, you want to be running within the next 30 minutes, or you'd rather spend your time on the work the agent will do rather than configuring the environment it runs in. Hermes OS deploys a fully configured Hermes instance — Docker, systemd, Telegram gateway, web UI — in one click, without any of the steps below. If that sounds better, skip to the end.
What you will need before starting: a VPS running Ubuntu 24.04 LTS (fresh install preferred), root SSH access, a domain name pointed at the server (optional but strongly recommended for the web UI), an API key from at least one LLM provider (OpenRouter recommended — gives access to 300+ models including Claude and GPT-5 with a single key), and a Telegram account for the messaging gateway.
Server requirements
Minimum: 2 vCPU, 4GB RAM, 20GB SSD. This runs Hermes with Docker-sandboxed execution. Hetzner CX22 at €3.99/month meets this spec exactly — it is the community's recommended budget option. DigitalOcean's Basic Droplet at 4GB RAM is $24/month for the same spec. Hostinger KVM 2 at ~$10-20/month with 8GB RAM is a solid mid-tier option if you run several tools on the same server.
Recommended: 4 vCPU, 8GB RAM, 40GB SSD. The additional RAM matters for running local models via Ollama alongside the agent, or for heavy parallel task workloads. 4GB is the hard floor — below this, you will hit OOM errors on complex tasks.
Operating system: Ubuntu 24.04 LTS. The official install script is written for this. Debian 12 works with minor adjustments. Do not use anything else unless you are confident rewriting the installer.
Phase 1: server preparation
SSH into your VPS as root. Run the initial system update:
apt update && apt upgrade -y
Create a dedicated non-root user for Hermes. Running the agent as root is a security risk:
adduser hermes --disabled-password --gecos ""
usermod -aG sudo hermes
echo 'hermes ALL=(ALL) NOPASSWD:ALL' > /etc/sudoers.d/hermes
chmod 440 /etc/sudoers.d/hermes
Copy your SSH keys to the new user so you can login directly:
mkdir -p /home/hermes/.ssh
cp ~/.ssh/authorized_keys /home/hermes/.ssh/
chown -R hermes:hermes /home/hermes/.ssh
chmod 700 /home/hermes/.ssh && chmod 600 /home/hermes/.ssh/authorized_keys
Switch to the hermes user and stay there for the rest of the setup:
su - hermes
Set up the firewall before you expose anything. This blocks all inbound traffic except SSH:
sudo apt-get install -y ufw
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow ssh
sudo ufw --force enable
sudo ufw status verbose
Phase 2: Docker installation
Hermes uses Docker for sandboxed terminal execution. Install from the official Docker repository (not the Ubuntu package, which is often outdated):
sudo apt-get install -y ca-certificates curl gnupg
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list
sudo apt-get update && sudo apt-get install -y docker-ce docker-ce-cli containerd.io
Add the hermes user to the docker group so it can run containers without sudo:
sudo usermod -aG docker hermes && newgrp docker
Verify the installation:
docker run --rm hello-world
You should see 'Hello from Docker!'. If you see a permission error, log out and back in to pick up the group membership change — newgrp docker fixes this for the current session but the persistent change requires a re-login.
Phase 3: Hermes Agent installation
The official one-line installer handles Python dependencies, the CLI binary, and the initial directory structure:
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
After it completes, reload your shell to pick up the hermes command:
source ~/.bashrc
Verify the installation and run the built-in health check:
hermes --version
hermes doctor
hermes doctor checks Docker availability, Python version, required dependencies, and write access to config directories. Fix anything it flags before continuing — common issues are Docker not being in the PATH, missing Python packages, or permissions on ~/.hermes/.
Run the interactive setup wizard:
hermes setup
This will prompt you for your LLM provider preference and generate the initial config files. It creates ~/.hermes/.env, ~/.hermes/config.yaml, ~/.hermes/MEMORY.md, and ~/.hermes/USER.md. These are the core files — do not delete them.
Phase 4: LLM provider configuration
Hermes supports 400+ models. OpenRouter is the recommended starting point — one API key gives you access to Anthropic, OpenAI, Mistral, Llama, and 60+ other providers without managing multiple accounts. Get a key at openrouter.ai.
Set permissions on the env file first (keeps your keys out of group-readable files):
chmod 600 ~/.hermes/.env
Add your API key:
echo 'OPENROUTER_API_KEY=sk-or-v1-your-key-here' >> ~/.hermes/.env
Set your default model — Claude Sonnet is the recommended starting point for general tasks:
hermes config set model.provider openrouter
hermes config set model.default anthropic/claude-sonnet-4
Test that it works:
hermes -m 'What is 2+2?'
If you get a response, the LLM connection is working. If you get an API error, check the key is correct and has credits.
Configure Docker as the terminal backend. This runs all of the agent's shell commands in an isolated container rather than directly on your server:
hermes config set terminal.backend docker
hermes config get terminal
Test sandboxed execution:
hermes -m 'Run ls -la in a sandboxed environment and show me the output'
Phase 5: Telegram gateway setup
The Telegram gateway is how you interact with Hermes from your phone or desktop. You will need a Telegram bot token and your Telegram user ID.
Create a bot: open Telegram, message @BotFather, send /newbot, follow the prompts to name your bot, and copy the token it gives you.
Get your user ID: message @userinfobot and it will reply with your numeric user ID.
Add both to your env file:
echo 'TELEGRAM_BOT_TOKEN=your-bot-token-here' >> ~/.hermes/.env
echo 'TELEGRAM_ALLOWED_USERS=your-numeric-user-id' >> ~/.hermes/.env
The TELEGRAM_ALLOWED_USERS whitelist is important — without it, anyone who finds your bot can send it commands. If you want to add another user later, separate IDs with commas.
Test the gateway manually:
hermes gateway
Send a message to your bot in Telegram. You should see the message arrive in the terminal and a response sent back. Press Ctrl+C once you have confirmed it works.
Phase 6: run as a persistent service
The gateway running in a terminal session will stop when your SSH connection closes. Install it as a systemd user service to run permanently and restart automatically on reboot:
hermes gateway install
systemctl --user enable hermes-gateway
systemctl --user start hermes-gateway
systemctl --user status hermes-gateway
Verify it is running:
journalctl --user -u hermes-gateway -f
You should see log output showing Telegram connection established. Send another test message from Telegram — if you get a response, the persistent service is working.
Test that it survives a reboot:
sudo reboot
SSH back in after 30 seconds and check the service status:
systemctl --user status hermes-gateway
If the service fails to start after reboot, the most common cause is XDG_RUNTIME_DIR not being set for loginctl sessions. Fix:
loginctl enable-linger hermes
This allows the user service to run without an active login session.
Common errors and fixes
'Permission denied' running Docker after adding to the group: log out and back in, or run newgrp docker. The group membership is picked up on next login.
'hermes: command not found' after installation: run source ~/.bashrc or open a new terminal. The installer adds the PATH entry but it only applies in new shell sessions.
hermes doctor shows missing dependencies: run hermes update to pull the latest install and re-run dependencies. If specific Python packages are missing, run pip install -r ~/.hermes/requirements.txt.
Telegram bot not responding: check the token is correct (no extra spaces), verify TELEGRAM_ALLOWED_USERS contains your exact numeric user ID, and check journalctl --user -u hermes-gateway -f for error messages.
Out of memory during tasks: 4GB RAM is the minimum — if you are below this, complex tasks will fail. The fix is upgrading the server. Check current usage with free -h.
API errors after it was working: your API key may have run out of credits, especially on OpenRouter's free tier. Check your provider dashboard.
Updates and maintenance
Hermes Agent is under active development — 17,500+ GitHub stars and frequent commits. Updates occasionally introduce breaking changes in config format or dependencies. The official update command:
hermes update
After a major update, run hermes doctor and hermes config check to verify nothing broke.
For community skills from the Skills Hub:
hermes skills list
hermes skills install skill-name
hermes skills update
For the log files:
tail -f ~/.hermes/logs/*.log
This is the maintenance overhead you are signing up for. Expect to spend 30-60 minutes per month on updates, monitoring, and the occasional breaking change. Factor this into the self-hosting math.
The honest self-hosting calculation
Server cost: Hetzner CX22 at €3.99/month (~$4.30). LLM API costs: $5-50/month depending on task volume. Your time: initial setup 2-4 hours, ongoing maintenance 30-60 minutes per month. At $50/hour, the setup alone costs $100-200 in time. That's enough to cover 2-4 months of a managed service.
Self-hosting wins if you're comfortable with Linux, you expect to keep the agent running for a year or more, and you care about complete data control. It loses if you hit setup issues, if maintenance distracts you from the actual work, or if updates break your configuration at inconvenient times.
Hermes OS is the managed alternative. One-click deploy, we handle the Docker configuration, systemd service, SSL, reverse proxy, and updates. The Telegram gateway, web interface, and persistent memory work out of the box. If you want Hermes running in 30 minutes rather than 4 hours, that is what Hermes OS is for.