Installing Hermes Agent on Linux (the Real Walkthrough)

Tested with: Debian 13 (trixie), Hermes Agent v0.15.2 (build 2026.5.29.2), Python 3.13.5, installed via pip into a virtualenv, tested 2026-06-02.

Hermes Agent is the agent runtime from Nous Research, the one whose tagline is "the agent that grows with you". I wanted to see how clean the install actually is on a bare Linux box, so I did it on a fresh Debian server with nothing but Python. This is the real walkthrough: the one gotcha that stopped me cold, the actual version and command surface, and an honest note about where the install ends and your accounts begin.

One thing up front: getting the CLI installed and getting it talking to a model are two different steps. The install is genuinely quick. Pointing it at a model needs a provider login, which means an account. This post covers the install completely and tells you exactly what the auth step expects.

The gotcha that stopped me first: python3-venv

Hermes installs cleanly with pip, and the right way to pip-install a CLI tool is into its own virtualenv. On Debian that failed immediately:

$ python3 -m venv hermes-venv
The virtual environment was not created successfully because ensurepip is not
available.  On Debian/Ubuntu systems, you need to install the python3-venv
package using the following command.

    apt install python3.13-venv

Debian ships Python without the venv bootstrap by default. The fix is one line, and it is the only step here that needs root:

sudo apt-get install -y python3-venv

This bit me on a minimal image; a desktop or fuller server image may already have it. Either way, if you see the ensurepip is not available message, that is what it means.

Install Hermes with pip

With venv working, the install is three commands:

python3 -m venv hermes-venv
hermes-venv/bin/pip install --upgrade pip
hermes-venv/bin/pip install hermes-agent

Confirm what landed. This matters because the SDK and CLI move fast and you want to know your exact version:

$ hermes-venv/bin/hermes --version
Hermes Agent v0.15.2 (2026.5.29.2)
Project: .../hermes-venv/lib/python3.13/site-packages
Python: 3.13.5

That is the CLI installed. (If you prefer, Nous also ships a one-line curl installer and a pip-plus-postinstall path; I used the plain pip route because it is the easiest to reason about and to tear down.)

Bootstrap the non-Python dependencies

The pip package is the Python core. Hermes also uses Node, a browser, ripgrep, and ffmpeg for some of its tools, and it bundles a command to fetch those for you rather than making you hunt them down:

hermes postinstall

Its own help describes it as "bootstrap non-Python deps for pip installs (node, browser, ripgrep, ffmpeg)". Run it if you want the browser-automation and media tools; skip it if this box is headless and you only need text and file tools. Nothing else in the core install needs it.

What you actually installed: the command surface

Run hermes --help and the breadth tells you what this thing is. It is not a chat wrapper; it is a full agent platform. The real commands, grouped:

• Core: chat (interactive session), model (pick model + provider), setup (interactive wizard), run.
• Providers and auth: login, logout, auth, fallback, portal (Nous Portal + Tool Gateway), proxy (a local OpenAI-compatible proxy).
• Messaging: gateway, whatsapp, slack, send, webhook.
• Agent features: memory, skills, tools, cron (scheduled jobs), hooks, mcp (yes, Hermes can be an MCP client), computer-use, kanban.
• Operations: status, doctor, update, backup, checkpoints, sessions, logs.

Two flags worth noting from the usage line: --tui launches a terminal UI instead of the plain CLI, and --continue [SESSION] resumes a previous session, which is the feature behind the "grows with you" tagline. The persistent memory lives under the Hermes data directory and is searched automatically, so do not delete it when you tinker.

The presence of an mcp command is the interesting one if you have been following along with the MCP posts: Hermes can consume MCP servers, so the server you build can be wired straight into it.

Where the install ends and your account begins

Here is the honest boundary. Everything above gets you a working binary. To actually run a turn, Hermes needs a model, and a model needs auth. The two paths:

hermes login           # authenticate with an inference provider
hermes setup --portal  # one OAuth covering a model + the Tool Gateway tools

The Nous Portal route is the smoothest: a single OAuth grants a model plus the four Tool Gateway tools (web search, image generation, text-to-speech, browser). The provider login route lets you bring your own key for Anthropic, OpenAI, OpenRouter, and others. Either way, that step is tied to your account, so this is where a generic walkthrough stops and your setup takes over. Once a provider is configured, hermes chat drops you into a session and hermes status confirms every component is healthy.

When something seems off

Two commands earn their keep. hermes doctor checks the binary, config, provider, and data directory and tells you what is wrong. hermes status shows the state of all components. Run doctor first and ask questions second. And if the CLI is not found after install, the usual cause is that your venv is not active or its bin/ is not on PATH, which a quick source hermes-venv/bin/activate fixes.

Takeaways

• On Debian, install python3-venv first or the venv step fails with an ensurepip error. It is the one root step in the core install.
• The install itself is three pip commands; I landed Hermes v0.15.2 on Python 3.13.5.
• Run hermes postinstall only if you want the Node, browser, ripgrep, and ffmpeg tools; headless text-and-file setups can skip it.
• The command surface is large (gateway, cron, memory, skills, mcp, computer-use). This is an agent platform, not a chat CLI, and it can act as an MCP client.
• Running a turn needs a provider login (hermes login or hermes setup --portal), which is tied to your account. That is the one part a walkthrough cannot do for you.