Installing Hermes Agent: The Complete Guide and the 6 Pitfalls That Cost You Half a Day

• How long does the installation really take?
• Pitfall #1: Why does the postinstall script stay stuck for 30 minutes?
• Should you use the interactive wizard or command-line configuration?
• Why does the dashboard build fail with npm run build?
• Why is hermes dashboard --host 0.0.0.0 refused?
• Why does the dashboard show "GATEWAY START STARTED" when nothing actually starts?
• Why is a service launched inside the sandbox invisible from the host?
• How much time should you plan for, concretely?

How long does the installation really take?¶

Tutorials claim five minutes. curl | bash, two or three questions, and you're done — at least, that's what the official documentation promises. We timed a real installation on August 1, 2026, on a Windows machine with WSL2 (Ubuntu 22.04), running Hermes Agent version 0.19.1 (build 2026.7.30). Result: 3 hours and 40 minutes, more than half of it lost to blockers that no documentation mentions.

It's not that Hermes Agent is badly designed. Once up and running, the software works very well — 67 skills and roughly seventy tools available natively is nothing to scoff at. The problem is the path between git clone and an agent that actually responds on Telegram. This guide documents that path as it really is, with the exact error messages copied straight from the terminal — not a cleaned-up version written after the fact.

If you're on Windows, know upfront that WSL2 isn't just one option among others — it's the only reliable path. We explain why in our dedicated guide to installing on Windows. And if you're just discovering Hermes Agent, our complete guide — what it is, how much it costs, what it can't do answers the questions we get asked most often before installation even comes up.

Pitfall #1: Why does the postinstall script stay stuck for 30 minutes?¶

First stop, barely two minutes after launching install.sh. The script runs through a series of post-installation tasks, and one of them is called unicode-animations. On paper, it's harmless: an animated ASCII banner that displays on startup, nothing more. In practice, when run in non-interactive mode (the default in a WSL2 terminal without a full TTY), this step never finishes. The cursor blinks, no error comes up, and nothing happens.

We let it run for 30 minutes before killing it. No timeout, no message, nothing. A Ctrl+C is enough to unblock the rest of the installation — the animation isn't a blocking dependency, just a poorly isolated script that fails to detect the absence of an interactive terminal.

What to do: if the installation seems frozen on a step that mentions animations, a banner, or a logo, don't wait. Interrupt with Ctrl+C and rerun the script — in our tests, interrupting this specific step never broke the rest of the installation.

Should you use the interactive wizard or command-line configuration?¶

Once the dependency installation is finished, install.sh automatically moves on to hermes setup, an interactive assistant: agent name, model provider, API key, preferred channel. Convenient if you're sitting at your screen and available to answer seven or eight questions in a row. Much less convenient if you're scripting the installation, running it in a pipeline, or simply want to configure things step by step without being stuck in front of the wizard.

The alternative exists but isn't documented anywhere visibly: hermes config set. This command lets you set each parameter individually, without going through the wizard:

Copierhermes config set model.provider openrouter
hermes config set model.name anthropic/claude-sonnet-4.5
hermes config set channels.telegram.enabled true

One detail that matters when choosing a model provider: on a free model (we tested poolside/laguna-s-2.1:free), the agent simply made up an installation it hadn't actually performed, and reported it as successful. No alert, no error message — just a false claim stated with confidence. This isn't an isolated bug: it's the kind of behavior you regularly see with free or very lightweight models, which are less reliable at following long instructions. For an agent meant to handle real tasks (emails, appointments, payments), that's not a minor detail.

Of the 32 available channels (Telegram, Microsoft Teams, Google Chat, IMAP/SMTP email…), Telegram remains by far the fastest to activate: QR code pairing, under two minutes, with no particular network configuration.

If you're coming from another agent — OpenClaw in particular — know that the hermes setup wizard offers automatic data migration from ~/.openclaw: we detail what actually transfers, and what doesn't, in our Hermes Agent vs. OpenClaw comparison.

The full configuration lives in two files: ~/.hermes/config.yaml for settings, and ~/.hermes/.env for secrets (API keys, tokens). One point that cost us twenty minutes: the container_persistent key, which controls the persistence of the Docker sandbox, has to be nested under the terminal: section — not placed at the root of the file:

Copierterminal:
  container_persistent: true

Placed at the wrong level, it's silently ignored. No syntax error, no warning: the container simply starts fresh from zero on every session.

Why does the dashboard build fail with npm run build?¶

The Hermes Agent web dashboard doesn't ship pre-built: you have to build it yourself with npm run build. Under Node.js 20 (the LTS version installed by default on most recent WSL2 images), the build fails with a stack of errors related to dependencies expecting a newer API — nothing exotic, just a version mismatch.

We reproduced the error, changed only the Node version, and reran it: immediate success under Node 22. No other change.

With nvm already installed, switching versions takes ten seconds:

Copiernvm install 22
nvm use 22
npm run build

Without nvm, expect more like fifteen minutes to cleanly install a recent Node version on Ubuntu, including the time to set up the NodeSource repository.

Why is hermes dashboard --host 0.0.0.0 refused?¶

Once the dashboard is built, the logical next step is to expose it on all network interfaces so you can access it from another machine: hermes dashboard --host 0.0.0.0. Result: the command is refused, and the service never starts.

The reason is actually good security news: Hermes Agent refuses to expose the dashboard on a public interface until authentication is configured. The dashboard gives access to the agent's configuration, its logs, and sometimes its secrets — exposing it without a password on 0.0.0.0 would be an open door to anyone who can reach the port.

The fix happens in ~/.hermes/config.yaml, under the dashboard: section:

Copierdashboard:
  basic_auth:
    username: your_username
    password: a_strong_password

Once this section is filled in, --host 0.0.0.0 is accepted normally. In practice, it's better to keep the dashboard on 127.0.0.1 anyway and go through an SSH tunnel if you need remote access — exposing it publicly, even password-protected, remains an extra attack surface.

Why does the dashboard show "GATEWAY START STARTED" when nothing actually starts?¶

This is the most confusing of the six pitfalls, and by far the one that costs the most time. The gateway is the component that connects the agent to external channels — Telegram, email. Running hermes gateway start without having installed the service beforehand returns this message, word for word:

CopierGateway service is not installed
Run: hermes gateway install

So far, nothing abnormal — the error is clear and says exactly what to do. The problem shows up if you go through the web dashboard instead of the terminal: the interface displays "GATEWAY START STARTED," as if everything were proceeding normally, and then nothing happens. No failure message, no switch to a visible error state. The status stays stuck on a label that suggests startup is in progress, indefinitely.

We lost 40 minutes on this single pitfall, checking ports, Docker logs, and network configuration — before rerunning the same command directly in the terminal and finally seeing the real error message the dashboard had been silently swallowing.

The correct sequence, in order, allows no exceptions:

Copierhermes gateway install
hermes gateway start

Why is a service launched inside the sandbox invisible from the host?¶

Hermes Agent runs its sandbox (where the agent can execute commands, scripts, and test servers) in a Docker container based on the nikolaik/python-nodejs:python3.11-nodejs20 image. As long as you stay within the "agent runs code, you get the result back as text" paradigm, everything is fine. Complications start as soon as you ask the agent to start a network service — a dev server, a test API.

The container gets an IP address internal to the Docker network, typically in the 172.18.x.x range. A service launched inside it does listen on that IP, but the ports aren't published to the host by default. Result: from your machine, curl 172.18.0.5:3000 or even curl localhost:3000 return nothing — the service is running, but it's unreachable from outside the container.

This isn't a bug: it's Docker's standard behavior without explicit port mapping. But it isn't documented anywhere in the context of Hermes Agent, and the symptom looks like a service that fails to start when it's actually running fine — just invisible.

How much time should you plan for, concretely?¶

Rounding generously: one hour for installing dependencies and cloning, one hour forty minutes for the six pitfalls above if you hit them without knowing them in advance, and the rest for fine-tuning the configuration (channels, priorities, initial tests). If you follow this guide already knowing the six pitfalls, expect more like 45 minutes to an hour end to end.

If your goal is a dedicated server rather than a local installation, the question of choosing a VPS and its real cost (hosting + model inference) deserves a separate calculation — we cover it in detail in our comparison of VPS offers for Hermes Agent.