mirrors/hermes-agent
1
0
Fork 0
mirror of https://github.com/NousResearch/hermes-agent.git synced 2026-04-30 01:41:43 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 6

fix(gateway): inject PATH + VIRTUAL_ENV into launchd plist for macOS service (#3585)

Browse source 
Salvage of PR #2173 (hanai) and PR #3432 (timknip).

Injects PATH, VIRTUAL_ENV, and HERMES_HOME into the macOS launchd plist so gateway subprocesses find user-installed tools (node, ffmpeg, etc.). Matches systemd unit parity with venv/bin, node_modules/.bin, and resolved node dir in PATH. Includes 7 new tests and docs updates across 4 pages.

Co-Authored-By: Han <ihanai1991@gmail.com>
Co-Authored-By: timknip <timknip@users.noreply.github.com>
This commit is contained in:
Teknium 2026-03-28 14:23:26 -07:00 • committed by GitHub
parent 5cdc24c2e2
commit 6893c3befc
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 131 additions and 7 deletions
Download patch file Download diff file Expand all files Collapse all files

8
website/docs/guides/team-telegram-assistant.md
View file

@ -168,11 +168,15 @@ journalctl -u hermes-gateway -f
```bash
# macOS — manage the service
launchctl start ai.hermes.gateway
launchctl stop ai.hermes.gateway
hermes gateway start
hermes gateway stop
tail -f ~/.hermes/logs/gateway.log
```
:::tip macOS PATH
The launchd plist captures your shell PATH at install time so gateway subprocesses can find tools like Node.js and ffmpeg. If you install new tools later, re-run `hermes gateway install` to update the plist.
:::
### Verify It's Running
```bash

17
website/docs/reference/faq.md
View file

@ -357,6 +357,23 @@ lsof -i :8080
hermes config show
```
#### macOS: Node.js / ffmpeg / other tools not found by gateway
**Cause:** launchd services inherit a minimal PATH (`/usr/bin:/bin:/usr/sbin:/sbin`) that doesn't include Homebrew, nvm, cargo, or other user-installed tool directories. This commonly breaks the WhatsApp bridge (`node not found`) or voice transcription (`ffmpeg not found`).
**Solution:** The gateway captures your shell PATH when you run `hermes gateway install`. If you installed tools after setting up the gateway, re-run the install to capture the updated PATH:
```bash
hermes gateway install # Re-snapshots your current PATH
hermes gateway start # Detects the updated plist and reloads
```
You can verify the plist has the correct PATH:
```bash
/usr/libexec/PlistBuddy -c "Print :EnvironmentVariables:PATH" \
~/Library/LaunchAgents/ai.hermes.gateway.plist
```
---
### Performance Issues

23
website/docs/user-guide/messaging/index.md
View file

@ -289,12 +289,27 @@ If you run multiple Hermes installations on the same machine (with different `HE
### macOS (launchd)
```bash
hermes gateway install
launchctl start ai.hermes.gateway
launchctl stop ai.hermes.gateway
tail -f ~/.hermes/logs/gateway.log
hermes gateway install # Install as launchd agent
hermes gateway start # Start the service
hermes gateway stop # Stop the service
hermes gateway status # Check status
tail -f ~/.hermes/logs/gateway.log # View logs
```
The generated plist lives at `~/Library/LaunchAgents/ai.hermes.gateway.plist`. It includes three environment variables:
- **PATH** — your full shell PATH at install time, with the venv `bin/` and `node_modules/.bin` prepended. This ensures user-installed tools (Node.js, ffmpeg, etc.) are available to gateway subprocesses like the WhatsApp bridge.
- **VIRTUAL_ENV** — points to the Python virtualenv so tools can resolve packages correctly.
- **HERMES_HOME** — scopes the gateway to your Hermes installation.
:::tip PATH changes after install
launchd plists are static — if you install new tools (e.g. a new Node.js version via nvm, or ffmpeg via Homebrew) after setting up the gateway, run `hermes gateway install` again to capture the updated PATH. The gateway will detect the stale plist and reload automatically.
:::
:::info Multiple installations
Like the Linux systemd service, each `HERMES_HOME` directory gets its own launchd label. The default `~/.hermes` uses `ai.hermes.gateway`; other installations use `ai.hermes.gateway-<suffix>`.
:::
## Platform-Specific Toolsets
Each platform has its own toolset:

1
website/docs/user-guide/messaging/whatsapp.md
View file

@ -173,6 +173,7 @@ whatsapp:
| **Logged out unexpectedly** | WhatsApp unlinks devices after long inactivity. Keep the phone on and connected to the network, then re-pair with `hermes whatsapp` if needed. |
| **Bridge crashes or reconnect loops** | Restart the gateway, update Hermes, and re-pair if the session was invalidated by a WhatsApp protocol change. |
| **Bot stops working after WhatsApp update** | Update Hermes to get the latest bridge version, then re-pair. |
| **macOS: "Node.js not installed" but node works in terminal** | launchd services don't inherit your shell PATH. Run `hermes gateway install` to re-snapshot your current PATH into the plist, then `hermes gateway start`. See the [Gateway Service docs](./index.md#macos-launchd) for details. |
| **Messages not being received** | Verify `WHATSAPP_ALLOWED_USERS` includes the sender's number (with country code, no `+` or spaces). |
| **Bot replies to strangers with a pairing code** | Set `whatsapp.unauthorized_dm_behavior: ignore` in `~/.hermes/config.yaml` if you want unauthorized DMs to be silently ignored instead. |