How to Install Hermes Agent on Ubuntu

Hermes Agent is an open-source AI agent built by Nous Research. It runs on your own server. Hook it up to Telegram or Discord and it starts answering messages, browsing the web, running code, searching files, and handling scheduled jobs. The install is one curl command. The rest is a setup wizard.

1Before you start

You'll need:

• Ubuntu 20.04 or newer — 22.04 LTS and 24.04 LTS both work great. Older releases haven't been tested.
• Root or sudo access — the installer writes to system paths
• 4 GB RAM minimum (8 GB recommended if you plan to run local LLMs)
• ~2 GB free disk space for Hermes, Python packages, and browser tooling
• A working internet connection — the installer pulls from GitHub and installs packages via apt

2Install Hermes

Paste this into your terminal. If you're logged in as a non-root user with sudo, the installer will handle privilege escalation where needed.

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

That's the whole install command. Go grab a coffee — on a typical 2 vCPU / 4 GB VPS it takes around 3–5 minutes.

What gets installed

The script handles everything automatically. Here's what it sets up:

• Python 3.11 — installed via uv if you don't already have it. Fast and non-disruptive to any existing Python setup.
• Git — checked for and installed if missing
• Node.js 22 LTS — installed locally at ~/.hermes/node/, so it won't touch your system Node
• ripgrep — for fast file search in coding tasks
• ffmpeg — needed for voice message handling
• Playwright + Chromium — for browser automation tasks
• Hermes itself — cloned to /usr/local/lib/hermes-agent and registered as a systemd service

3The setup wizard

Once the install finishes, the setup wizard launches automatically. You can also get back to it at any time with:

hermes setup agent

You'll see three options:

• Quick Setup (Nous Portal) — logs in via OAuth. No API keys to manage. This is what most people should pick for a first install.
• Full Setup — you bring your own API keys and configure each LLM provider yourself (OpenAI, Anthropic, OpenRouter, and others).
• Blank Slate — starts with everything off. You opt in to each capability one at a time.

Terminal backend

Next, pick where Hermes should execute code:

Keep this on Local. The other options (Docker, SSH, Modal, Daytona) are for setups where you want code execution sandboxed or run on a separate machine. Most people don't need them.

4Connect a chat app

This is the part that makes Hermes actually useful. The wizard shows every supported messaging platform:

Use Space to toggle platforms on or off, then Enter to confirm. You can add more later. Telegram is the best starting point — it has the smoothest setup flow and works reliably from anywhere.

Setting up Telegram

After selecting Telegram, Hermes asks how you'd like to create your bot:

• Automatic (recommended) — scan a QR code in the Telegram app, confirm the connection, done. No tokens to copy-paste. Takes about 30 seconds.
• Manual — talk to @BotFather yourself, create a bot, paste the token. Useful if you're setting up on behalf of someone else or prefer to manage credentials manually.

The automatic method works for almost everyone. Pick it and follow the on-screen prompts.

5Verify it's running

Once setup completes, type hermes in your terminal:

If you see the HERMES-AGENT banner and a list of available tools and skills, you're done. Send a message to your Telegram bot — it should respond within a few seconds.

If nothing happens after sending a message, check the service status:

systemctl status hermes-gateway

6Day-to-day management

Hermes runs as a systemd service called hermes-gateway. The usual service commands all apply:

# Start / stop / restart
systemctl start hermes-gateway
systemctl stop hermes-gateway
systemctl restart hermes-gateway

# Follow logs live
journalctl -u hermes-gateway -f

# Update to the latest version
hermes update

# Add more chat apps or change your LLM provider
hermes setup agent

The agent starts on boot. Nothing extra to do after a server restart.

Your config lives at /root/.hermes/ (or /home/hermes/.hermes/ depending on the install). Two files matter: .env for API keys and tokens, and config.yaml for everything else. Change either one and restart the gateway to pick it up.