Hermes Agent VPS Complete Deployment Tutorial: Build Your 24/7 AI Assistant in 10 Minutes

What makes Hermes Agent different from your average chatbot is that it actually remembers stuff. It builds skills from your conversations, learns your preferences over time, and keeps context across different sessions. Once it’s running on a VPS, you can control it through Telegram even when you’re away from your computer.

The hardware requirements are pretty modest: Ubuntu 22.04 or Debian 12 will do. You can start with 1 core and 1GB RAM, but 2 cores with 2GB is much more comfortable. No GPU needed at all.

Installation Method 1: Official One-Click Script (Best for Beginners)

The easiest route by far — just one command and it handles almost everything:

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

The script installs Python, Node.js, ripgrep, ffmpeg, and the other dependencies it needs, clones the repo, sets up the virtual environment, creates a global hermes command, and then launches the setup wizard. Just follow the prompts and you’re good to go.

Installation Method 2: Manual Installation (If You Want to Understand Every Step)

First, update your system:

apt update && apt upgrade -y

Install uv — the package manager the team recommends (it’s noticeably faster than pip):

curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.cargo/env

Clone the repository — don’t forget the --recurse-submodules flag, or you’ll run into missing submodule errors later:

git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

Create a Python 3.11 virtual environment and install the dependencies:

uv venv venv --python 3.11
export VIRTUAL_ENV="$(pwd)/venv"
uv pip install -e ".[all]"

If you want browser tools or WhatsApp support, also run:

npm install

Set up the necessary folders and config files:

mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills,pairing,hooks,image_cache,audio_cache}
cp cli-config.yaml.example ~/.hermes/config.yaml
touch ~/.hermes/.env

Add your API key. I recommend using OpenRouter (one key gives you access to over 200 models):

echo 'OPENROUTER_API_KEY=sk-or-v1-your-key-here' >> ~/.hermes/.env

Make the hermes command available globally:

mkdir -p ~/.local/bin
ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Check if everything installed correctly:

hermes doctor

Initial Setup

Run the setup wizard:

hermes setup

It will walk you through choosing your LLM provider (OpenRouter, Anthropic, OpenAI, or a local endpoint), pasting your API key, and selecting a code execution backend (Docker is recommended for safety).

If you’ve used OpenClaw before, Hermes can detect it and offer to migrate your memories, skills, and keys with just a few clicks.

Basic Usage

To start the interactive CLI:

hermes

Some useful commands:

hermes               # Start the interactive CLI
hermes gateway       # Start the messaging gateway (Telegram, Discord, etc.)
hermes status        # Check current status
hermes logs          # View logs (with filtering options)
hermes doctor        # Run health check

Running It 24/7 in the Background

To keep it running after you close the terminal, the cleanest way is to use systemd:

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

Paste something like this (replace yourusername with your actual username):

[Unit]
Description=Hermes Agent Gateway
After=network.target

[Service]
Type=simple
User=yourusername
WorkingDirectory=/home/yourusername
ExecStart=/home/yourusername/.local/bin/hermes gateway
Restart=always
RestartSec=10
Environment=PATH=/home/yourusername/.local/bin:/usr/bin:/bin

[Install]
WantedBy=multi-user.target

Then enable and start it:

sudo systemctl daemon-reload
sudo systemctl enable hermes-gateway
sudo systemctl start hermes-gateway
sudo systemctl status hermes-gateway

If you see active (running), it’s working in the background and will automatically restart if the server reboots.

Connecting to Telegram

Open Telegram, search for @BotFather, send /newbot, follow the steps to create your bot and get the token.

Add the token to your environment file:

echo 'TELEGRAM_BOT_TOKEN=your-token-here' >> ~/.hermes/.env

Enable Telegram in the config file ~/.hermes/config.yaml:

gateway:
  telegram:
    enabled: true

Restart the gateway:

sudo systemctl restart hermes-gateway

Find your new bot in Telegram, send /start. If it replies, you’re all set. From then on, you can just chat with your agent from your phone and it will run commands on the VPS.

Common Issues & Troubleshooting

Python version error during install: uv should automatically download Python 3.11. You usually don’t need to install it manually — just make sure uv is correctly installed and in your PATH.

hermes doctor shows errors: Follow whatever it tells you. Most of the time it’s a missing dependency or an environment variable that wasn’t set properly.

Telegram messages aren’t coming through: Double-check the bot token and make sure there are no extra spaces or quotes in the ~/.hermes/.env file.

To see detailed logs:

journalctl -u hermes-gateway -f
# or
hermes logs --tail 100

Full documentation is available at hermes-agent.nousresearch.com/docs. If you run into trouble, the GitHub Issues page is pretty active and most common problems have already been answered there.