hermes - 💡(How to fix) Fix [Bug]: Hermes Signal setup wizard fails to create/persist signal-cli daemon service

Summary

After completing the Signal setup through the Hermes native messaging options wizard (hermes setup → Signal), the gateway dashboard consistently reports signal-cli as errored. The wizard appears to register/link the account but does not configure or persist the required signal-cli daemon --http background service.

Environment

• OS: macOS 26.5 (Apple Silicon)
• Hermes version: v0.14.0
• signal-cli: 0.14.4.1 via Homebrew (/opt/homebrew/bin/signal-cli)
• Hermes install method: user installer (~/.hermes/hermes-agent)
• Gateway runtime: launchd (ai.hermes.gateway)

Steps to reproduce

1. Run hermes setup and select Signal from the messaging options wizard.
2. Follow prompts to link device, provide phone number, and confirm account.
3. Wizard completes with no errors.
4. Start gateway (hermes gateway start or let launchd auto-start).
5. Dashboard shows Signal as errored.

Expected behavior

After wizard completion, the gateway should be able to connect to signal-cli on the configured HTTP port without manual intervention.

Actual behavior

gateway.log shows repeated connection failures:

ERROR gateway.platforms.signal: Signal: cannot reach signal-cli at http://127.0.0.1:8080: All connection attempts failed

Root cause: nothing is listening on port 8080. The wizard registered the account but never created a persistent daemon process.

Manual workaround

Create a launchd plist to run the daemon persistently:

cat > ~/Library/LaunchAgents/com.asamk.signal-cli.daemon.plist <<'PLIST'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.asamk.signal-cli.daemon</string>
    <key>ProgramArguments</key>
    <array>
        <string>/opt/homebrew/bin/signal-cli</string>
        <string>daemon</string>
        <string>--http</string>
        <string>127.0.0.1:8080</string>
        <string>--no-receive-stdout</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/sean/Library/Logs/signal-cli-daemon.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/sean/Library/Logs/signal-cli-daemon.log</string>
    <key>WorkingDirectory</key>
    <string>/Users/sean</string>
    <key>EnvironmentVariables</key>
    <dict>
        <key>HOME</key>
        <string>/Users/sean</string>
    </dict>
</dict>
</plist>
PLIST

launchctl load ~/Library/LaunchAgents/com.asamk.signal-cli.daemon.plist
launchctl start com.asamk.signal-cli.daemon

Then restart the Hermes gateway. Signal connects successfully:

INFO gateway.platforms.signal: Signal: connected to http://127.0.0.1:8080
INFO gateway.run: ✓ signal connected
INFO gateway.platforms.signal: Signal SSE: connected

Suggested fix

The Signal setup wizard should:

1. Detect whether signal-cli is installed (Homebrew or otherwise).
2. Create the appropriate persistent daemon service for the platform:
   • macOS: launchd plist in ~/Library/LaunchAgents/
   • Linux: systemd user service
3. Start the service immediately and verify port connectivity.
4. Store the daemon URL in config.yaml or .env so the gateway knows where to connect.

Related issues

• #31674 (Signal gateway setup pitfalls)
• #13827 (config-backed adapters blocked by env-only checks)

Reported by @porkmagus