Install Hermes Agent on a Hostinger VPS

Install Hermes Agent on a Hostinger VPS

Hermes Agent is designed to run permanently on a server — that's its primary use case for most users. A VPS (Virtual Private Server) gives you full control, 24/7 availability, and predictable performance for your AI agent. Hostinger offers affordable VPS plans perfectly suited for this purpose, with plans starting at just a few euros per month that provide more than enough resources.

This guide walks you through every step, from VPS creation to a fully functional Hermes Agent with the gateway running on Telegram or Discord.

Why a VPS for Hermes Agent?

Hermes Agent works locally on your machine, but deploying it on a VPS offers decisive advantages:

• 24/7 availability: the gateway runs continuously, your Telegram/Discord bots respond even when your PC is off
• Network stability: dedicated server connection, no WiFi drops or sleep mode interruptions
• Isolation: the agent runs in a separate environment from your personal machine
• Reliable cron jobs: scheduled tasks execute on time without depending on your local session
• Multi-user access: multiple people can interact with the agent through messaging platforms

Choosing and Configuring the VPS

Recommended Hardware

Hermes Agent is lightweight — it only calls APIs and executes shell commands. Real-world requirements are modest:

• RAM: 1 GB minimum, 2 GB recommended (context compression and local STT consume more)
• CPU: 1 vCPU is plenty
• Disk: 20 GB SSD minimum, 40 GB recommended (logs, sessions, image cache)
• Bandwidth: standard, Hermes consumes almost no bandwidth

A KVM 1 VPS plan at Hostinger (1 vCPU, 4 GB RAM, 50 GB NVMe) is more than enough for Hermes and leaves room for running other services alongside it.

Creating the VPS

1. Go to Hostinger and choose a VPS plan
2. Select a datacenter close to your geographic area to minimize latency
3. Choose Ubuntu 22.04 LTS or Ubuntu 24.04 LTS as the operating system — the distribution best supported by Hermes
4. Configure your root password or SSH key
5. Enable the firewall — you don't need to open any inbound ports for Hermes, everything works through outgoing connections (Telegram/Discord polling or webhooks)

Initial Connection

ssh root@YOUR_VPS_IP

First action after connecting — update the system:

apt update && apt upgrade -y

Installing Hermes Agent

System Prerequisites

Hermes needs Git and Python. The installer handles the rest:

apt install -y git

The installer uses uv as the Python package manager — it's fast, requires no sudo, and manages Python versions automatically. If uv isn't present, the installer downloads and installs it for you.

Automatic Installation (Recommended)

The simplest method:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

The installer automatically handles:

1. Checking and installing uv
2. Installing Python 3.11 via uv if needed
3. Cloning the repository to ~/.hermes/hermes-agent/
4. Creating the Python virtual environment
5. Installing all dependencies
6. Launching the interactive setup (hermes setup)

For non-interactive mode (scripting, curl pipe), add --skip-setup to configure manually later:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s -- --skip-setup

Manual Installation

If you prefer to control each step:

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

# Clone Hermes
git clone https://github.com/NousResearch/hermes-agent.git ~/.hermes/hermes-agent
cd ~/.hermes/hermes-agent

# Create environment and install dependencies
uv venv --python 3.11
source .venv/bin/activate
uv pip install -e ".[all]"

# Run setup
hermes setup

Verify Installation

After installation, verify everything works:

hermes doctor

This command checks configuration, dependencies, and detected API keys. Resolve any reported issues before continuing.

hermes --version
hermes config check

Initial Configuration

Setting Up the LLM Model

Hermes requires at least one LLM provider configured. The interactive setup guides you through this, but you can also do it manually:

hermes model

Or directly in the configuration file:

hermes config edit

Minimal configuration example in ~/.hermes/config.yaml:

model:
  default: "anthropic/claude-sonnet-4"
  provider: openrouter

And in ~/.hermes/.env:

OPENROUTER_API_KEY=your_api_key_here

For OAuth providers (Nous Portal, OpenAI Codex), use hermes login instead.

Gateway Configuration

The gateway is the component that connects Hermes to messaging platforms. For a VPS, this is the primary operating mode.

hermes gateway setup

The wizard asks you to choose platforms to enable and enter the corresponding tokens:

• Telegram: create a bot via @BotFather, get the token
• Discord: create a bot on the Discord Developer Portal, enable Message Content Intent
• Slack: create a Slack app with chat:write and message.channels permissions

Install Gateway as a systemd Service

To have the gateway restart automatically after a reboot and survive SSH disconnections:

hermes gateway install

This command creates a systemd service that automatically manages:

• Startup at VPS boot
• Restart on crash
• Centralized logs via journalctl

Management commands:

hermes gateway status     # Check state
hermes gateway restart    # Restart
hermes gateway start      # Start
hermes gateway stop       # Stop
hermes gateway uninstall  # Remove service

Verify the Gateway Works

hermes gateway status

You should see the status of each configured platform. Send a message to your Telegram or Discord bot to test.

VPS Security

Firewall (UFW)

Hermes needs no inbound ports — everything works through outgoing connections (Telegram long polling, Discord webhooks). A strict firewall is the best approach:

apt install -y ufw
ufw default deny incoming
ufw default allow outgoing
ufw allow ssh          # Allow SSH (port 22)
ufw enable

If you use a custom SSH port, replace ssh with the port number.

SSH Authentication

Disable password authentication and use SSH keys only:

# On your local machine (not the VPS)
ssh-copy-id root@YOUR_VPS_IP

# On the VPS
sed -i 's/#PasswordAuthentication yes/PasswordAuthentication no/' /etc/ssh/sshd_config
systemctl restart sshd

Automatic Updates

Enable automatic security updates:

apt install -y unattended-upgrades
dpkg-reconfigure -plow unattended-upgrades

Backups

Hermes' critical data is in ~/.hermes/:

• config.yaml — configuration
• .env — API keys
• sessions/ — conversation history
• auth.json — OAuth tokens
• skills/ — custom skills

Set up regular backups:

# Manual backup
tar czf hermes-backup-$(date +%Y%m%d).tar.gz ~/.hermes/

# Via cron (daily backup)
echo "0 3 * * * tar czf /root/hermes-backup-$(date +\%Y\%m\%d).tar.gz ~/.hermes/" | crontab -

Advanced VPS Configuration

Enable Context Compression

On a VPS with 1 GB RAM, automatic compression is essential for managing long conversations without saturating memory:

compression:
  enabled: true
  threshold: 0.50
  target_ratio: 0.20

Hermes compresses context when it reaches 50% of the model's context window, bringing it down to 20%.

Local STT (Speech-to-Text)

To transcribe voice messages for free without external APIs:

source ~/.hermes/hermes-agent/.venv/bin/activate
pip install faster-whisper

Configuration:

stt:
  enabled: true
  provider: local
  local:
    model: base    # tiny, base, small, medium, large-v3

The base model uses ~150 MB of RAM. On a 1 GB VPS, stick with tiny or base.

Useful Production Plugins

A few plugins particularly useful on a VPS:

• disk-cleanup: automatically cleans temporary files created by Hermes, preventing the VPS from filling up
• langfuse: cost and performance observability (requires a Langfuse account)
• Memory provider: for persistent cross-session memory

Activation:

plugins:
  enabled:
    - disk-cleanup
    - observability/langfuse

Profiles for Multi-User

If multiple people use your Hermes instance through different messaging platforms, profiles isolate configuration, sessions, and memory:

hermes profile create telegram-bot
hermes profile create discord-bot
hermes profile use telegram-bot

Docker Installation (Alternative)

If you prefer containerization to isolate Hermes from the rest of the VPS:

# Create a docker-compose.yml
mkdir -p /opt/hermes && cd /opt/hermes

docker-compose.yml file:

version: "3.8"
services:
  hermes:
    image: nikolaik/python-nodejs:python3.11-nodejs20
    container_name: hermes-agent
    restart: unless-stopped
    working_dir: /root/.hermes/hermes-agent
    volumes:
      - hermes-data:/root/.hermes
    environment:
      - HERMES_HOME=/root/.hermes
    command: >
      bash -c "
        apt-get update && apt-get install -y git curl &&
        curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s -- --skip-setup &&
        hermes gateway run
      "

volumes:
  hermes-data:

docker compose up -d
docker compose logs -f hermes

Docker's advantage: total isolation, reproducibility, and easy rollback. The downside: slight overhead (~200 MB extra RAM) and more complex setup for hardware access (audio, GPIO).

For most users, native installation (uv + systemd) is simpler and more performant. Docker is relevant if you run other containerized services on the same VPS.

TLS Configuration with nginx

If you expose web endpoints (API Server, webhooks), an nginx reverse proxy with Let's Encrypt is recommended:

apt install -y nginx certbot python3-certbot-nginx

Minimal configuration in /etc/nginx/sites-available/hermes:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:9119;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

ln -s /etc/nginx/sites-available/hermes /etc/nginx/sites-enabled/
certbot --nginx -d your-domain.com

Monitoring and Maintenance

Monitoring Logs

# Gateway logs in real time
hermes logs --follow --level info

# Errors only
hermes logs --level error

# Via systemd (if installed as service)
journalctl -u hermes-gateway -f

Health Check

hermes doctor --fix    # Diagnose and auto-fix common issues
hermes status --all    # Full status of all components

Updating Hermes

hermes update

This command pulls the latest version and installs updated dependencies. Remember to restart the gateway after:

hermes gateway restart

Monitor VPS Resources

# RAM/CPU usage
htop

# Disk space
df -h

# Hermes space usage
du -sh ~/.hermes/

Troubleshooting Common Issues

Gateway won't start

1. Check logs: hermes logs --level error
2. Verify systemd service: hermes gateway status
3. If the service has failed: systemctl --user reset-failed hermes-gateway then hermes gateway restart

Bot not responding on Telegram

1. Verify the token is correct in .env: TELEGRAM_BOT_TOKEN
2. Check connection: hermes gateway status should show Telegram as connected
3. Restart the gateway: hermes gateway restart

Memory errors (OOM)

If the VPS runs out of RAM (1 GB):

1. Disable local STT (switch to groq or openai)
2. Reduce the STT model to tiny
3. Enable context compression with a lower threshold (0.40)
4. Disable non-essential plugins

VPS inaccessible after reboot

1. Check on the Hostinger dashboard that the VPS is running
2. Use the VNC console from the dashboard if SSH doesn't respond
3. Verify the firewall allows SSH

Conclusion

Deploying Hermes Agent on a Hostinger VPS is a straightforward process that transforms your AI agent into an always-available service. In under 15 minutes, from VPS creation to the first message on Telegram, you have an autonomous agent with gateway, cron jobs, plugins, and monitoring. The systemd configuration ensures service permanence, while backups and automatic updates secure your data. With a VPS starting at just a few euros per month, you get a 24/7 AI assistant available on all your messaging platforms.