Hermes Update Command Hangs: How to Fix Update and Install Failures

If hermes update hangs, crashes, or leaves the gateway in a weird state, do not keep rerunning random install commands. Treat it like an agent operations incident: preserve your local state, verify which Hermes binary is running, fix the shell environment, update the source checkout safely, and restart the gateway only after the package metadata and config migration are clean.

Why this happens#

Recent community support threads show update failures clustering around a few repeat causes:

• A long Hermes update command hangs (round 2) thread showed that update failures are rarely just one command; they involve git state, dependency installs, and long-running gateway processes.
• no menu in choosing models in telegram. update failed connected update problems to a broken messaging gateway experience.
• restart loop showed why update work should end with a clean process restart, not a half-reloaded gateway.
• Custom docker_image not being read and YouTube Content Tool docker show how Docker terminal settings can make an otherwise good install look broken.
• Discord Attribute Error: 'DiscordAdapter' object has no attribute 'message_len_fn' is the classic symptom of code/config/process skew after an update.

The commercial takeaway is simple: self-hosting Hermes is powerful because you control the code and environment, but it also means you own git, Python, launchd/systemd, Docker, model credentials, and gateway restarts. If that maintenance is not the job you want, FlyHermes is the practical hosted alternative.

1. Preserve state before trying another update#

Before rerunning the updater, save your current state. This protects local edits, custom skills, and any uncommitted source checkout work.

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"

If git status shows source changes you care about, do not overwrite them. Either keep the stash reference, make a branch, or copy the diff somewhere safe. For first-time installs, start with how to install Hermes Agent and only come back here if the update path fails.

2. Check whether Hermes is running from the checkout you are updating#

A surprising number of update bugs come from editing one checkout while the shell runs a different binary. Verify both the command and the package metadata.

which hermes
head -1 $(which hermes)
cd ~/.hermes/hermes-agent
hermes --version
venv/bin/python - <<'PY'
import importlib.metadata
print(importlib.metadata.version('hermes-agent'))
PY

If hermes --version changed but package metadata did not, reinstall from the repo venv instead of using system Python:

cd ~/.hermes/hermes-agent
venv/bin/python -m ensurepip --upgrade
venv/bin/python -m pip install -e .

3. Fix reduced PATH on macOS and launchd contexts#

On macOS, Hermes may be launched from Telegram, a gateway service, launchd, or another reduced environment. In that context, child processes may not find git, ssh, bash, node, or npm even though your interactive shell can.

Use an explicit PATH for update and gateway commands:

export PATH="$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH"
which git
which ssh
which python3
hermes update

If the built-in updater still fails because it cannot find git or ssh, do the source update manually:

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

This same PATH issue can affect the dashboard; if the web UI says npm is unavailable, use the Hermes dashboard setup path and rebuild frontend assets with a full PATH.

4. Restart the gateway after code changes#

A gateway process can keep old Python modules in memory after files on disk have changed. That is why Discord or Telegram errors after an update often look unrelated to the updater. If you see import errors, missing adapter attributes, restart loops, or Gateway is shutting down, do a real process restart.

hermes gateway stop || true
hermes gateway start
hermes gateway status
tail -120 ~/.hermes/logs/agent.log | egrep -i 'gateway|telegram|discord|error|exception|connected'

For always-on deployments, pair this with the Hermes VPS hosting guide, background monitoring and webhooks, and Hermes Agent cron jobs so the agent has a reliable lifecycle instead of an invisible zombie process.

5. Check Docker and terminal backend drift#

If updates appear to succeed but tools fail immediately, the problem may be the terminal backend rather than the code checkout. Community threads around custom Docker images and Docker-based tools show this pattern often.

hermes config | grep -i 'terminal' -A 8
hermes doctor
hermes setup terminal

Choose local when Docker is not installed or is broken. Choose Docker only when you actually want sandboxed terminal execution and have verified the image, volumes, and daemon. Use the Hermes Docker install guide and security hardening guide when sandboxing is part of the requirement.

6. Verify the update with a smoke test#

Do not call the update fixed just because the command exited. Run a short smoke test through the same interface that was broken.

hermes doctor
hermes chat -q "Reply with the active Hermes version and no extra text."
hermes tools list | head -40
hermes gateway status

If Telegram or Discord was the broken surface, send one test message there too. A CLI smoke test does not prove a messaging gateway is healthy. For channel-specific setup, use the Telegram setup guide, Discord setup guide, and Hermes profiles guide so bot credentials and skills stay scoped.

Self-hosting vs hosted: the honest decision#

Use self-hosted Hermes when you want source control, custom tools, local files, Docker sandboxes, MCP servers, and full control over your agent runtime. Use FlyHermes when the value is having an agent available without personally maintaining the VPS, Docker daemon, launchd service, gateway logs, and update path.

A good rule: if debugging git, ssh, venv, launchd, gateway state, and Docker images sounds like normal infrastructure work, self-host. If it sounds like a distraction from getting agent work done, take the hosted route.

FAQ#

Why does hermes update hang?#

Usually because the process is waiting on git, dependency installation, an unavailable binary in PATH, a locked checkout, or a stale gateway process. Preserve state, rerun with a full PATH, then update manually if needed.

Should I delete ~/.hermes and reinstall?#

No, not as a first step. That directory contains config, sessions, skills, memory, and credentials. Back up state first, then repair the source checkout or venv.

Why did Telegram or Discord break after updating?#

The gateway may still be running old in-memory code against newer files on disk, or the update changed a platform adapter while the service was not fully restarted. Stop and start the gateway, then check agent.log.

Is Docker required for Hermes updates?#

No. Docker is one terminal backend option. If Docker is broken, switch the terminal backend to local while you repair the install.

What is the fastest path if I do not want to maintain updates?#

Use FlyHermes for a hosted Hermes experience, or keep local Hermes but avoid always-on gateways until you are comfortable with the update and restart workflow.