How to install Hermes Agent on Ubuntu

Hermes Agent is an open-source AI assistant that runs directly on your server. It can write code, manage files, run commands, browse the web, and more. In this guide, I will walk you through installing it on a fresh Ubuntu VPS.

What you need

• a Linux VPS running Ubuntu 20.04 or newer

• SSH access with sudo privileges

• about 15 minutes

Step 1: Connect to your VPS

If you haven't already, connect via SSH:

ssh root@your-server-ip

Replace your-server-ip with the actual IP of your VPS.

Step 2: Update your system

Always start with a clean slate:

sudo apt update && sudo apt upgrade -y

Step 3: Install Python and pip

Hermes needs Python 3.10 or newer. Ubuntu 22.04+ comes with it by default, but let us make sure everything is in place:

python3 --version

# If you need Python 3.11 specifically
sudo apt install python3.11 python3.11-venv python3-pip -y

Step 4: Install uv (fast Python package manager)

Hermes uses uv under the hood. Install it with a single command:

curl -LsSf https://astral.sh/uv/install.sh | sh

After the install completes, reload your shell:

source ~/.bashrc

Check that it worked:

uv --version

Step 5: Install Hermes Agent

Now for the main event. Create a directory for Hermes and install it:

mkdir -p ~/hermes && cd ~/hermes

# Download and run the installer
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | sh

The installer will set up a virtual environment and download all dependencies. This might take a minute or two depending on your server.

Step 6: Configure your API key

Hermes needs access to an LLM provider. The easiest way is to set up an OpenRouter API key:

export OPENROUTER_API_KEY="your-api-key-here"

To make this permanent, add it to your shell config:

echo 'export OPENROUTER_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

You can get a free API key from openrouter.ai/keys.

Step 7: Test that it works

Run a quick test to verify everything is set up correctly:

# Check the Hermes version
hermes --version

# Start an interactive session
hermes

If everything went well, you should see Hermes starting up and ready for your commands.

Running Hermes as a service (optional)

If you want Hermes to keep running in the background, set it up as a systemd service:

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

Paste this:

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

[Service]
Type=simple
User=root
WorkingDirectory=/root/hermes
ExecStart=/root/hermes/.venv/bin/hermes
Restart=always
Environment=OPENROUTER_API_KEY=your-api-key-here

[Install]
WantedBy=multi-user.target

Then enable and start it:

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

Common issues

"Command not found: hermes"

The installer adds Hermes to your PATH, but you might need to reload your shell:

source ~/.bashrc
# Or log out and back in

"uv: command not found"

Make sure ~/.local/bin is in your PATH:

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

Where to go from here

• Read the official Hermes documentation

• Check out the GitHub repo

• Join the community on Discord or GitHub Discussions