🚀 How to Install and Run Hermes Agent on Ubuntu VPS (5 Minute Quick-Start Guide)

This article describes how to install and run Hermes Agent on Ubuntu VPS.

Overview

Hermes Agent is an open-source AI agent framework from Nous Research that can run continuously on a VPS with persistent memory, tool access, and messaging integrations. This guide covers installation on Ubuntu 22.04/24.04 and basic configuration.

Prerequisites

Minimum Requirements

• Ubuntu 22.04 LTS or Ubuntu 24.04 LTS
• 2 GB RAM minimum (4 GB+ recommended)
• 20 GB SSD storage
• SSH access with sudo privileges
• Internet connectivity
• API key from OpenAI, Anthropic, OpenRouter, or another supported provider

Connect to Your VPS

ssh root@YOUR_SERVER_IP

Or if using a sudo user:

ssh username@YOUR_SERVER_IP

Compare Ubuntu VPS Plans

How to Install and Run Hermes Agent on Ubuntu VPS

To install and run Hermes Agent on Ubuntu VPS, follow the steps below:

1. Update Ubuntu

   Update all installed packages:

   sudo apt update && sudo apt upgrade -y
   

   Install required utilities:

   sudo apt install -y curl git ca-certificates
   

   Git is required because the installer clones the Hermes repository during installation.

   Verify:

   git --version
   curl --version
   

2. Install Hermes Agent

   The official installer automatically installs:

   • Python 3.11+
   • uv
   • Node.js
   • ripgrep
   • ffmpeg
   • Hermes CLI

   Run:

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

   The installer:

   1. Detects your operating system
   2. Installs dependencies
   3. Clones Hermes Agent
   4. Creates a Python virtual environment
   5. Installs the Hermes CLI
   6. Adds Hermes to your shell PATH automatically

3. Reload Your Shell

   After installation:

   source ~/.bashrc
   

   Or reconnect via SSH:

   exit
   ssh username@YOUR_SERVER_IP
   

   Verify installation:

   hermes --version
   

   Expected output:

   Hermes Agent x.x.x
   

4. Initial Setup

   Launch the setup wizard:

   hermes setup
   

   The wizard will ask for:

   • AI provider
   • API key
   • Model selection
   • Agent preferences

   Example providers:

   • OpenAI
   • Anthropic
   • OpenRouter
   • Nous Portal

5. Configure Your Model

   If using OpenAI:

   hermes model
   

   Choose:

   Provider: OpenAI
   Model: gpt-5
   API Key: sk-xxxxxxxx
   

   If using OpenRouter:

   Provider: OpenRouter
   Model: openai/gpt-5
   

   Save configuration when prompted.

6. Test Hermes

   Start an interactive session:

   hermes
   

   
   Try a test prompt:

   Create a bash script that displays disk usage.
   

   If Hermes responds, installation is successful.

7. Run Hermes Continuously

   For long-running deployments:

   Create a dedicated system user:

   sudo useradd -r -m -s /bin/bash hermes
   

   Locate the Hermes executable:

   which hermes
   

   Example output:

   /home/ubuntu/.local/bin/hermes
   

8. Create a Systemd Service

   Create service file:

   sudo nano /etc/systemd/system/hermes.service
   

   Insert:

   [Unit]
   Description=Hermes Agent
   After=network.target
   
   [Service]
   Type=simple
   User=ubuntu
   WorkingDirectory=/home/ubuntu
   ExecStart=/home/ubuntu/.local/bin/hermes
   Restart=always
   RestartSec=10
   
   [Install]
   WantedBy=multi-user.target
   

   Replace:

   • ubuntu with your username
   • Path with the actual Hermes path

   Save and exit.

   Reload systemd:

   sudo systemctl daemon-reload
   

   Enable startup:

   sudo systemctl enable hermes
   

   Start service:

   sudo systemctl start hermes
   

   Check status:

   sudo systemctl status hermes
   

9. View Logs

   Real-time logs:

   sudo journalctl -u hermes -f
   

   Recent logs:

   sudo journalctl -u hermes --since "1 hour ago"
   

10. Configure Firewall

    Install UFW:

    sudo apt install -y ufw
    

    Allow SSH:

    sudo ufw allow OpenSSH
    

    Enable firewall:

    sudo ufw enable
    

    Check status:

    sudo ufw status
    

11. Keep Hermes Updated

    Update Hermes:

    hermes update
    

    Or rerun the installer:

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

Troubleshooting

Hermes Command Not Found

Add local binaries to PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Verify Installation Path

which hermes

Check Service Errors

journalctl -xeu hermes.service

Verify Network Access

curl https://api.openai.com

Common Commands

hermes

Launch interactive mode.

hermes setup

Run configuration wizard.

hermes model

Configure AI provider and model.

hermes gateway setup

Configure messaging integrations.

hermes update

Update Hermes Agent.

hermes --help

Display all available commands.

Conclusion

You now know how to install and run Hermes Agent on Ubuntu VPS.

After completing these steps, Hermes Agent will be installed on Ubuntu, configured with your preferred AI provider, and running persistently through systemd. The agent will automatically start after reboots and can be extended with messaging platforms such as Telegram, Discord, and Slack for 24/7 operation.