Hermes Agent Install and Update Troubleshooting: macOS PATH, Docker, Gateway Restarts

If hermes update hangs, hermes disappears after install, Docker fails before any tool runs, or Telegram stops after a restart, treat it like an operations incident. Preserve state first, then isolate whether the failure is PATH, git/ssh, Python packaging, Docker/WSL, or a stale gateway process.

Why this page exists#

Recent Discord community data put install/update/docker/windows at 208 matched threads — one of the largest support clusters. Adjacent clusters included provider credits, dashboard/UI, and messaging platforms, which is exactly why install failures often surface as “Telegram is broken” or “the dashboard is weird.” The fix is to debug the stack in layers.

June 2026 update: v0.15.2 and current main fixes#

The latest Hermes GitHub work turns several common install/update problems into clearer recovery paths instead of mystery crashes. Check these before deleting state or rewriting config:

• Docker config migrations now run during container boot. Update the image and restart before hand-editing an older config.yaml.
• Unsupported arbitrary Docker users fail with clearer guidance. Avoid forcing docker run --user <random-uid> when the image cannot own the Hermes home tree.
• UID remap/chown handling was repaired. If mounted build trees or ~/.hermes became unwritable after an update, pull the latest image and inspect ownership before rebuilding from scratch.
• Python 3.14 is capped out for now. If install breaks on bleeding-edge Python, pin Hermes to a supported interpreter and rerun hermes doctor.
• Desktop managed clone updates are safer. The update flow no longer lets stash/restore clobber Desktop-managed source trees in the same way, but source installs should still check git status before and after hermes update.
• MCP discovery now expands ${ENV} in header auth probes. Header-auth MCP failures can be a missing container env var or an old Hermes version, not necessarily a broken MCP server.

For container-specific failures, use the dedicated Hermes Docker troubleshooting checklist. For a higher-level release summary, read what changed in Hermes Agent v0.15. For Desktop remote-backend setups, use the Hermes Desktop remote backend guide.

First: protect Hermes state#

Before reinstalling or deleting anything, remember that ~/.hermes can contain:

• config.yaml
• .env secrets
• sessions and memory
• skills and plugins
• cron jobs
• OAuth/provider auth
• the source checkout if installed from git

A safe pre-update backup pattern is:

cd ~/.hermes/hermes-agent
mkdir -p /tmp/hermes-update-backups
stamp=$(date +%Y%m%d-%H%M%S)
git status --short > /tmp/hermes-update-backups/status-$stamp.txt
git diff > /tmp/hermes-update-backups/working-tree-$stamp.diff
git diff --cached > /tmp/hermes-update-backups/index-$stamp.diff
git stash push -u -m "pre-update-$stamp"

Fix macOS reduced PATH problems#

On macOS, Hermes may be launched by a gateway, LaunchAgent, cron, or app wrapper with a reduced PATH. That can make child processes fail with git, ssh, bash, npm, or launchctl missing even when your interactive shell can find them.

Run quick checks:

which hermes
which git
which ssh
which bash
hermes --version

Then retry with a full PATH:

PATH="$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" hermes update

If the update command itself is still stuck, update the source checkout manually.

Manual source update fallback#

cd ~/.hermes/hermes-agent
/usr/bin/git fetch --tags origin
/usr/bin/git checkout main
/usr/bin/git pull --ff-only origin main
hermes config migrate
hermes doctor

If package metadata is stale after a source update, use the repo venv, which is commonly venv/:

cd ~/.hermes/hermes-agent
venv/bin/python -m ensurepip --upgrade
venv/bin/python -m pip install -e .
hermes --version
venv/bin/python - <<'PY'
import importlib.metadata
print(importlib.metadata.version('hermes-agent'))
PY

Docker and WSL are separate layers#

Do not confuse these three paths:

• Docker Compose runs Hermes as a long-lived service.
• The Docker terminal backend lets Hermes execute shell commands inside containers.
• WSL is the Linux environment Windows users may use to run Hermes.

If file or terminal tools fail with Docker startup errors such as exit 127, switch the terminal backend to local to isolate the problem:

hermes config set terminal.backend local
hermes doctor

Then return to Docker Compose setup or Docker terminal backend configuration after the local CLI works.

Gateway restart failures#

A stale gateway can survive code/config changes and keep old modules in memory. Symptoms include Telegram or Discord not replying, import/signature errors, or status files saying connected while real messages fail.

Use service-level restart checks:

hermes gateway status
hermes gateway restart
hermes gateway status

For macOS launchd, a harder restart may be needed:

/bin/launchctl kickstart -k gui/$(id -u)/ai.hermes.gateway
sleep 5
cat ~/.hermes/gateway_state.json

Then verify end-to-end with the actual channel, for example the Telegram setup guide, not only a green process state.

Provider and fallback failures can look like install failures#

Sometimes the binary is fine but the agent fails because a provider is exhausted, a model route changed, or an auxiliary task hit a rate limit. If hermes doctor passes but jobs fail during compression, session search, memory, or delegation, use the provider fallback guide and the provider cost guide.

Self-hosting vs managed path#

Self-hosting Hermes is powerful, but the full stack includes install, updates, Python packaging, provider keys, gateway services, Docker/WSL, dashboards, logs, and uptime. If you want the agent outcome without owning those layers, FlyHermes is the hosted alternative.

FAQ#

Why does hermes update hang on macOS?#

Common causes are reduced PATH, missing git or ssh in the subprocess environment, dependency installation, stale source checkout state, or gateway processes that need a full restart.

Should I delete ~/.hermes and reinstall?#

No, not as the first fix. Back up state and repair the checkout or venv first. ~/.hermes may contain memory, skills, cron jobs, sessions, and credentials.

Why does Telegram break after an update?#

The gateway may still be running old code against newer files, or it may have restarted with a reduced PATH or wrong profile. Restart the service process and verify the actual chat, not only the status file.

Gateway restart after updates#

After an update, do not trust an old long-running gateway process. Restart it with a full PATH, inspect current agent.log, and run the gateway troubleshooting checklist until a real Telegram or Discord message receives a reply. This catches stale module graphs, launchd PATH problems, and provider/config drift before users experience a silent bot.