[Bug]: gateway install --system ExecStart skips project venv

[hugobiais]

Summary

hermes gateway install --system generates a unit file whose ExecStart points at the base uv-managed Python interpreter instead of the project's venv Python. Because all Hermes runtime dependencies (PyYAML, etc.) are installed into the venv's site-packages, the service crash-loops on startup with ModuleNotFoundError: No module named 'yaml'.

Environment

• Ubuntu 24.04
• Hermes Agent v0.8.0 (2026.4.8)
• Installed via the standard installer (uv-managed Python + project venv at /root/.hermes/hermes-agent/venv)
• Running as root on a VPS (--run-as-user root)

Repro

1. Fresh install Hermes on Ubuntu 24.04 as root.
2. hermes gateway install --system --run-as-user root
3. hermes gateway start --system
4. journalctl -u hermes-gateway -f

Observed:

python3.11[...]: ModuleNotFoundError: No module named 'yaml'
systemd[1]: hermes-gateway.service: Main process exited, code=exited, status=1/FAILURE

Root cause

The generated unit file at /etc/systemd/system/hermes-gateway.service contains:

ExecStart=/root/.local/share/uv/python/cpython-3.11.15-linux-x86_64-gnu/bin/python3.11 -m hermes_cli.main gateway run --replace
Environment="VIRTUAL_ENV=/root/.hermes/hermes-agent/venv"
Environment="PATH=/root/.hermes/hermes-agent/venv/bin:..."

The unit correctly sets VIRTUAL_ENV and puts venv/bin on PATH, but ExecStart bypasses both by hard-coding an absolute path to the base uv interpreter. Invoking the base Python directly does not pick up the venv's site-packages, so none of the installed Hermes dependencies are importable.

For comparison, /root/.local/bin/hermes has the correct shebang:

#!/root/.hermes/hermes-agent/venv/bin/python3

…which is why running hermes manually works fine.

generate_systemd_unit() in hermes_cli/gateway.py appears to resolve the interpreter from sys.executable or similar at install time, which on a uv-managed install resolves to the base interpreter rather than the venv wrapper.

Workaround

Systemd drop-in override that replaces ExecStart with the venv Python:

mkdir -p /etc/systemd/system/hermes-gateway.service.d
cat > /etc/systemd/system/hermes-gateway.service.d/override.conf <<'OVERRIDE'
[Service]
ExecStart=
ExecStart=/root/.hermes/hermes-agent/venv/bin/python3 -m hermes_cli.main gateway run --replace
OVERRIDE
systemctl daemon-reload
systemctl reset-failed hermes-gateway.service
hermes gateway start --system

After this, the service starts cleanly and systemctl status shows the correct interpreter in Main PID.

Suggested fix

In generate_systemd_unit(), prefer $VIRTUAL_ENV/bin/python (or equivalently the shebang target of the installed hermes entrypoint) over sys.executable when generating ExecStart. Something like:

venv = os.environ.get("VIRTUAL_ENV")
python_exe = f"{venv}/bin/python" if venv and Path(f"{venv}/bin/python").exists() else sys.executable

This also makes the behavior consistent with the Environment="VIRTUAL_ENV=..." line the generator already emits.

[hugobiais]

Opened #7985 with a fix and tests. The root cause is in get_python_path(): it only checks for venv/bin/python, which is absent on uv-managed venvs that only ship python3 / pythonX.Y symlinks, causing it to fall through to sys.executable (the base interpreter). The PR makes it try python, then python3, then pythonX.Y before giving up on the venv.

[DestMountain]

I can reproduce the same underlying issue in a migration scenario from OpenClaw to Hermes.

Summary

I deployed OpenClaw on a Tencent Cloud VM, then switched the installation to Hermes and chose to inherit the existing OpenClaw setup during hermes init.

After migration, hermes doctor looked healthy and reported that PyYAML was installed, but the systemd-managed gateway crash-looped on startup with:

ModuleNotFoundError: No module named 'yaml'

In my case, the root cause was the same as described here: the generated hermes-gateway.service used the uv/base Python in ExecStart instead of the project venv Python, so the service did not load the Hermes venv site-packages.

Environment

• Tencent Cloud VM
• Hermes Agent v0.8.0 (2026.4.8)
• Migrated from OpenClaw to Hermes
• Chose to inherit OpenClaw during hermes init
• Running gateway as a systemd service
• Project venv located at /root/.hermes/hermes-agent/venv

Repro

1. Deploy OpenClaw on a Tencent Cloud VM.
2. Switch the installation to Hermes.
3. During hermes init, choose to inherit the existing OpenClaw setup.
4. Start the gateway with systemd:
   • hermes gateway start
   • or hermes gateway start --system
5. Check status/logs:
   • systemctl status hermes-gateway
   • journalctl -u hermes-gateway -n 200 -l --no-pager

Observed:

ModuleNotFoundError: No module named 'yaml'
hermes-gateway.service: Main process exited, code=exited, status=1/FAILURE
Start request repeated too quickly

Root cause

The generated unit used an ExecStart like:

/root/.local/share/uv/python/cpython-3.11.15-linux-x86_64-gnu/bin/python3.11 -m hermes_cli.main gateway run --replace

while the actual Hermes runtime environment was under:

/root/.hermes/hermes-agent/venv

So even though the unit exported VIRTUAL_ENV and included venv/bin in PATH, ExecStart still bypassed the venv by hard-coding the base interpreter.

This was especially confusing because hermes doctor reported PyYAML as installed, which was true for the Hermes environment, but not for the interpreter used by systemd.

Workaround

I fixed it with a systemd drop-in override:

sudo mkdir -p /etc/systemd/system/hermes-gateway.service.d

sudo tee /etc/systemd/system/hermes-gateway.service.d/override.conf >/dev/null <<'EOF'
[Service]
ExecStart=
ExecStart=/root/.hermes/hermes-agent/venv/bin/python -m hermes_cli.main gateway run --replace
EOF

sudo systemctl daemon-reload
sudo systemctl reset-failed hermes-gateway
sudo systemctl restart hermes-gateway

After that:

• systemctl cat hermes-gateway showed the drop-in override

• systemctl status hermes-gateway showed:

  Main PID: ... /root/.hermes/hermes-agent/venv/bin/python -m hermes_cli.main gateway run --replace

• the service stayed active (running)

Suggested fix

It would be good if gateway/systemd unit generation always preferred the Hermes project venv Python for ExecStart, especially in migration or inherited-install scenarios such as OpenClaw -> Hermes.

This would avoid cases where:

• hermes doctor looks correct
• but systemd still uses a different interpreter and crash-loops on missing modules

[Tranquil-Flow]

This appears to be already fixed on main. The _remap_path_for_user() function in hermes_cli/gateway.py (lines 780-786) now uses .expanduser() for lexical tilde expansion only, preserving the venv python symlink instead of following it to the base interpreter via .resolve().

[alt-glitch]

Duplicate of #9201 — same root cause: generate_systemd_unit() uses sys.executable (uv base interpreter) instead of venv Python for ExecStart. Fix PR at #9230.

[teknium1]

Closing as duplicate of #9201.

Triage notes (high confidence):
Maintainer alt-glitch explicitly marked as duplicate of #9201 (same root cause: generate_systemd_unit uses sys.executable/uv base interpreter instead of venv Python). Open fix PR #9230 tracks resolution. #9201 confirmed OPEN.

Please follow #9201 for updates. If this isn't actually a duplicate, comment and we'll reopen.

(Bulk-closed during a CLI issue triage sweep.)