hermes - 💡(How to fix) Fix install.sh: --no-venv flag is broken — uv sync always creates venv, shim never created [3 pull requests]

Bug

install.sh --no-venv --skip-setup fails to create the ~/.local/bin/hermes shim. which hermes returns nothing after a successful install.

Root Cause

Two issues:

1. setup_path() cannot find the binary

When --no-venv is passed, setup_path() (line ~1266) takes the else branch and runs which hermes. But uv sync --extra all --locked (called from install_deps) always creates a venv regardless of USE_VENV=false — the output even shows Creating virtual environment at: venv. The entry point lands at $INSTALL_DIR/venv/bin/hermes, but setup_path() never checks that path in the --no-venv branch.

Minimal fix: in the else branch, fall back to checking $INSTALL_DIR/venv/bin/hermes before giving up.

2. --no-venv is fundamentally broken on PEP 668 systems

Even if you skip uv sync and use uv pip install --system, modern distros (Ubuntu 24.04+) mark their Python as externally managed and refuse the install. Using --break-system-packages with the uv-managed Python 3.11 installs scripts into an obscure uv-internal path not on PATH.

More importantly, hermes update assumes it can re-run uv pip install or uv sync in the same environment. Without a venv, there is no consistent environment for updates to target.

Suggested Resolution

1. Short-term: Fix setup_path() to detect $INSTALL_DIR/venv/bin/hermes even when USE_VENV=false (since uv sync creates it anyway). This makes the current behavior work — users get a venv regardless of the flag, but at least the shim is created.

2. Long-term: Deprecate --no-venv. The flag has no practical effect — uv sync creates a venv unconditionally, and hermes update depends on it. Document this and emit a warning when the flag is passed.

Reproduction

curl -fsSL https://github.com/NousResearch/hermes-agent/raw/main/scripts/install.sh | bash -s -- --no-venv --skip-setup
which hermes        # returns nothing
ls ~/.hermes/hermes-agent/venv/bin/hermes  # exists (uv created it anyway)
ls ~/.local/bin/hermes                     # does not exist (shim not created)

Environment

• Ubuntu 26.04 x64
• uv 0.11.16
• Fresh install (no prior ~/.hermes)
• install.sh from main branch (2026-05-24)