hermes-skills-devops/hermes-troubleshooting/references/s6-gateway-restart.md

Gateway Restart in s6 Container

Problem

hermes gateway restart refuses to run from inside the gateway process (prevents restart loops):

✗ Refusing to restart the gateway from inside the gateway process.
This command was blocked to prevent restart loops.
Use `hermes gateway restart` from a shell outside the running gateway.

Solution: Kill + S6 Auto-Restart

The gateway runs under s6 supervision in a Docker container. s6 auto-restarts services on exit.

Step 1: Find the gateway PID

ps aux | grep "hermes.*gateway\|gateway.*hermes" | grep -v grep
# Look for: hermes gateway run --replace

Step 2: Send SIGHUP (graceful) or SIGKILL (force)

kill -HUP <pid>    # Graceful — s6 will restart it
# or
kill -9 <pid>      # Force — use if HUP hangs

Step 3: Verify restart

sleep 3
ps aux | grep "hermes.*gateway" | grep -v grep
# Should show a NEW PID (s6 restarted it)

Step 4: Check logs for clean startup

tail -20 /opt/data/logs/gateway.log
# Look for: "Starting Hermes Gateway...", platform connections

When to Use This

• After updating config.yaml or .env for the default profile
• After hermes -p <profile> config set ... changes that need gateway reload
• When gateway is in a bad state (OOM, stuck, 401 loop)
• When running from inside the gateway process (TUI session, cron job, etc.)

Important Notes

• Do NOT use nohup or & — s6 manages the lifecycle
• PID will change — s6 spawns a new process; don't track the old PID
• Config reload is automatic — gateway reads config.yaml on startup
• Platform reconnection — Feishu, Weixin, etc. reconnect within ~5 seconds