Before you start: do you actually want to self-host?
Self-hosting makes sense 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. The rest of this guide is for the self-hosters.
What you 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 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 and is the community's budget option. DigitalOcean's Basic Droplet at 4GB RAM is $24/month for the same spec. Hostinger KVM 2 at around $10-20/month with 8GB RAM is a solid mid-tier choice if you run several tools on the same server.
Recommended: 4 vCPU, 8GB RAM, 40GB SSD. The extra RAM matters for running local models via Ollama alongside the agent, or for heavy parallel task workloads. 4GB is the hard floor — below it, you 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. Nothing else unless you're 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 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:
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 exposing 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:
sudo usermod -aG docker hermes && newgrp docker
Verify:
docker run --rm hello-world
You should see 'Hello from Docker!'. If you see a permission error, log out and back in — newgrp docker fixes it for the current session but the persistent change needs 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:
source ~/.bashrc
Verify the installation and run the 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 PATH, missing Python packages, or permissions on ~/.hermes/.
Run the interactive setup wizard:
hermes setup
This prompts for your LLM provider preference and generates the initial config files: ~/.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 access to Anthropic, OpenAI, Mistral, Llama, and 60+ other providers. Get a key at openrouter.ai.
Set permissions on the env file first:
chmod 600 ~/.hermes/.env
echo 'OPENROUTER_API_KEY=sk-or-v1-your-key-here' >> ~/.hermes/.env
Set your default model:
hermes config set model.provider openrouter
hermes config set model.default anthropic/claude-sonnet-4
Test it:
hermes -m 'What is 2+2?'
If you get a response, the LLM connection is working.
Configure Docker as the terminal backend:
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
Create a bot: open Telegram, message @BotFather, send /newbot, follow the prompts, and copy the token. Get your user ID from @userinfobot.
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
TELEGRAM_ALLOWED_USERS is your security allowlist. Without it, anyone who finds your bot can send it commands. Test the gateway:
hermes gateway
Send a message to your bot in Telegram. You should see it arrive in the terminal and a response sent back. Press Ctrl+C once confirmed.
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:
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
Test that it survives a reboot:
sudo reboot
SSH back in after 30 seconds and check:
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:
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. Group membership is only picked up on new login.
'hermes: command not found' after installation: run source ~/.bashrc. The installer adds the PATH entry but it only applies in new shell sessions.
hermes doctor flags missing dependencies: run hermes update then re-check. If specific Python packages are still missing: pip install -r ~/.hermes/requirements.txt.
Telegram bot not responding: check the token (no extra spaces), verify TELEGRAM_ALLOWED_USERS contains your exact numeric user ID, and check journalctl --user -u hermes-gateway -f for the specific error.
Out of memory during tasks: 4GB RAM is the minimum — if you are below this, complex tasks will fail. Check current usage with free -h and upgrade the server if needed.
API errors after it was working: your API key may have exhausted credits, especially on OpenRouter's free tier. Check your provider dashboard.
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. Initial setup: 2-4 hours of your time. Ongoing maintenance: 30-60 minutes per month. At $50/hour, the setup alone costs $100-200 in time — enough to cover 2-4 months of a managed service.
Self-hosting wins if you are comfortable with Linux, expect to keep the agent running for a year or more, and care about complete data control. It loses if setup issues frustrate you, if maintenance distracts from the actual work, or if updates break your configuration at inconvenient times. Hermes OS is the one-click alternative — the same Hermes Agent, with the Docker configuration, systemd service, SSL, and updates handled. If you want it running in 30 minutes rather than 4 hours, that is what it is for.