hermes - 💡(How to fix) Fix Docker backend: image arg clobbered with shell PATH export string, container fails with exit 125

Summary

On macOS, the Docker backend intermittently passes a literal shell export PATH=... string as the image argument to docker run, causing the container to fail with exit code 125. Once it starts happening it recurs on every gateway restart, multiple times per day.

Environment

• Host: macOS (Apple Silicon, M4)
• Docker Desktop, default backend
• Hermes installed from source at ~/.hermes/hermes-agent
• Updated 2026-05-25, bug present before and after update

Symptom

docker run -d is invoked with this in the image-name slot:

export PATH="/Applications/Docker.app/Contents/Resources/bin:$PATH"

…immediately before sleep infinity. Docker rejects it with exit 125.

Traceback

File "tools/terminal_tool.py", line 1834, in terminal_tool new_env = _create_environment(...) File "tools/terminal_tool.py", line 1142, in _create_environment return _DockerEnvironment(...) File "tools/environments/docker.py", line 519, in init result = subprocess.run(run_cmd, ..., check=True) subprocess.CalledProcessError: returned non-zero exit status 125

What I confirmed

• ~/.hermes/config.yaml has the correct docker_image: ubuntu:24.04
• docker_extra_args: [] (empty)
• TERMINAL_DOCKER_IMAGE is unset in both the user shell AND the running gateway process env (checked via ps eww)
• The bad string is the literal output of a PATH export, suggesting somewhere a shell-env-detection / find_docker-adjacent routine is capturing a line of shell stdout and feeding it into the image variable instead of the docker executable path

Repro

1. Run hermes gateway run --replace on macOS
2. Make any sandboxed terminal call
3. Fails ~daily, sometimes immediately after restart

Workaround

Restart the gateway: pkill -9 -f 'hermes.*gateway' nohup hermes gateway run --replace >/tmp/hermes-gw.log 2>&1 & disown Buys 2–24 hours, then recurs.

Suspected root cause

Something in the docker_image resolution path (likely an env-probe in find_docker() or its caller) is parsing shell stdout incorrectly on macOS when PATH augmentation lines are present. The captured string ends up as image rather than _docker_exe.