How to Set Up Hermes Agent on Ubuntu: A Step-by-Step Guide

Hermes Agent is an open-source AI agent that runs in your terminal and can work with almost any LLM provider. Here's how to get it running on a fresh Ubuntu machine — the exact steps I used to stand it up, verified end to end.

1Prerequisites

You need an Ubuntu system (20.04 or newer works fine) with:

Python 3.10+ (the installer manages its own environment, but a recent base helps)
curl (for the installer)
Roughly 2 GB of free disk for the agent and its Python environment
API access to at least one model provider — the easiest is a free/cheap OpenRouter key, or any provider key (Anthropic, OpenRouter, DeepSeek, local models later)

Check your base tools first:

python3 --version
curl --version

If curl is missing, sudo apt update && sudo apt install -y curl.

2Run the installer

Hermes ships a shell installer that sets up uv, an isolated Python venv, and the hermes launcher:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Let it finish — it installs everything under a dedicated environment rather than touching your system Python. When it's done, log out and back in (or source ~/.profile) so the hermes command is on your PATH.

3First run and setup

Launch the interactive chat:

hermes

On first run you'll be guided through setup — this is where you pick your model provider and default model. The quick manual path is:

hermes setup      # guided wizard: provider + default model
hermes model      # change default model anytime
hermes doctor     # health check: config, profiles, gateways

4Add an API key

Hermes reads keys from ~/.hermes/.env (secrets live here, never in config files). If the setup wizard didn't prompt you, add your key manually:

echo "OPENROUTER_API_KEY=sk-or-v1-..." >> ~/.hermes/.env
chmod 600 ~/.hermes/.env

Replace the value with your real key from the provider's console.

5Your first session

Now chat with the agent. Try something concrete:

hermes chat -q "What operating system am I running?"

You should get an answer that reflects the actual machine. From there the whole toolkit is available — /help lists in-session commands, hermes --help shows the CLI surface, and hermes doctor confirms health.

6Optional: profiles, skills, and messaging

Two things worth knowing early:

Profiles isolate separate agent instances: hermes profile create <name> makes an independent home under ~/.hermes/profiles/<name>/ with its own config, skills and sessions.
Skills are reusable procedures the agent saves and reuses. You can see what's loaded with hermes skills list and add more from the skill hub with hermes skills install <id>.

Troubleshooting

hermes: command not found after install — your PATH doesn't include the launcher yet; re-login or source ~/.profile.
No API key found for provider — the .env is empty or the key name is wrong for your provider; check grep OPENROUTER ~/.hermes/.env.
Health problems — run hermes doctor; it checks config, profiles, gateways and surfaces what to fix.

That's it. Fifteen minutes from a bare Ubuntu box to a working, provider-routed AI agent in your terminal.