Hermes Agent
How to stop or restart Hermes Agent: the gateway commands
Updated 22 November 2026
Hermes Agent’s messaging side runs as a process called the gateway, and that is the thing you stop, start and restart. This page gives the commands first, then how they differ between a foreground run, an installed service, several profiles, Docker and Windows, and what to check when it will not stay stopped.
Facts come from the Hermes Agent 0.23.3 documentation (the CLI reference, the multi-profile gateways, Docker and updating pages, the FAQ, the slash-command reference and the Windows pages), read on 22 November 2026.
The commands
These are the subcommands of hermes gateway for everyday control, as the CLI reference describes them:
| Command | What it does |
|---|---|
hermes gateway run | Runs the gateway in the current terminal. The docs recommend it for WSL, Docker and Termux. In the official Docker image, s6 manages the gateway process. |
hermes gateway start | Starts the installed systemd or launchd background service. |
hermes gateway stop | Stops the service (or the foreground process). |
hermes gateway restart | Restarts the gateway. For a gateway you ran by hand with no service or supervisor, the replacement runs in the current terminal by default. Add --detach to start it in the background. |
hermes gateway status | Shows service status. |
hermes gateway list | Lists all profiles and whether each profile’s gateway is running, with the PID where available. |
hermes gateway install | Installs the gateway as a systemd (Linux) or launchd (macOS) background service. |
So the short answers: run hermes profile to check which profile is active. On the default profile, hermes gateway stop stops the gateway and hermes gateway restart restarts it; if that gateway serves several profiles, all of them are affected. On a named profile served by the shared gateway, the same commands park or reconnect just that profile. On Linux or macOS, use hermes gateway start to bring an installed service back up. If you ran the gateway in a terminal, use hermes gateway run to bring it back in the foreground. The next section covers the difference. Removing the service altogether is a different job, covered on uninstalling Hermes Agent.
Foreground run or installed service
First check whether you started the gateway in a terminal, installed a service, or let a Hermes client start it in the background. The commands above behave according to which one you used.
- Foreground.
hermes gateway runkeeps the gateway in your terminal. It needs no service manager, which is why the docs recommend it where systemd is unreliable. - Service. After
hermes gateway install, the gateway is managed by systemd on Linux or launchd on macOS, andstart,stop,restartandstatustalk to that service. On Linux,sudo hermes gateway install --systeminstalls a boot-time system service instead of a user service, and the docs suggest it for a VPS or headless host. A user service on a server needssudo loginctl enable-linger $USERto keep running after you log out. For that system service, usesudo hermes gateway start --systemto start it andsudo hermes gateway status --systemto check it. Restarting it requires root. Choose one service type for the gateway, because installing both the user and system units can make it unclear which one you are controlling. - Started by a Hermes client. Opening the workspace with
hermes webappstarts the gateway if it is not running.
When the gateway is in the middle of chat turns, cron jobs or background delegations, stop and restart list that work and ask y/N before interrupting it. Add --yes (or -y) to skip the question; with no terminal to ask on, such as a script or cron, the command refuses unless you pass it. On Linux, the docs say to prefer hermes gateway restart over a raw systemctl restart when in-flight turns matter, because it asks the gateway to drain first and waits up to its time limit for the replacement.
Restart the gateway after editing the tool-progress setting in config.yaml or changing which skills appear in Telegram’s command menu; Telegram rebuilds that menu when the gateway starts. Updating is a separate job: after a successful update, hermes update tries to restart the gateways that were running for the Hermes home being updated. If it lacks permission to restart a Linux system service, it prints the manual restart command. The update page covers it.
Two more things you can do from inside a chat. /restart is a messaging-only command that gracefully restarts the gateway after draining active runs, then sends a confirmation to the requesting chat once its connection is ready. If the gateway still cannot deliver that confirmation after 30 minutes, it discards it. To interrupt the running agent from a messaging chat, send /stop. This also kills running background processes and leaves the gateway online.
Several profiles
Each profile has its own bot tokens, sessions and memory (see Hermes Agent profiles). When gateway.multiplex_profiles is unset, the default gateway checks at startup whether it can serve the profiles together, and saves true in the default profile’s configuration if it can. If a blocker such as a duplicate bot credential prevents that, the gateway serves only the default profile and reports the reason in hermes gateway status. An explicit true skips this check. The parking commands below apply to a named profile served by the shared gateway, so what a command affects depends on which profile you name.
hermes gateway stopon the default profile takes every served profile offline.hermes -p coder gateway stopparks just that profile and the others keep running. It writes agateway.parkedmarker in the profile’s home, which persists across host restarts. Parking preserves the profile, its sessions and its scheduled jobs. The host skips that profile’s future scheduled runs while it is parked, and work already dispatched by the scheduler continues.hermes -p coder gateway startremoves the marker and serves the profile again, andhermes -p coder gateway restartreconnects it with its current configuration.- With separate per-profile gateways,
--allapplies the command across profiles. With a shared gateway, the--allcommands target the host gateway. In particular,start --allandrestart --allleave separately running gateways alone.
With a live shared gateway, hermes -p coder gateway run can attach to the host, and hermes -p coder gateway start can bring a parked profile back online. If the host is down, start it from the default profile when prompted. Trying to install a separate gateway for a named profile in this setup is refused with exit code 78. The docs describe a per-profile gateway as a temporary gateway.standalone: true setting that they do not recommend for new setups. The dashboard and Desktop Stop and Start buttons do the same parking, and their Restart asks before restarting the shared gateway because every bot on the device reconnects.
Docker
When the official image runs its normal entrypoint as PID 1, s6 supervises the gateway. If the platform supplies its own PID 1, the image can run without s6 and its per-profile services are unavailable. Under s6, if the gateway process crashes, it is restarted within a couple of seconds without losing the container, and the docs say docker stop still shuts everything down cleanly. The examples use a container named hermes and a profile named coder. For a profile on the shared gateway, stop parks it, start brings it back and restart reconnects it. A profile with gateway.standalone: true uses its own s6 service; if you created that profile on the host, run the start example first to register its missing service, provided its profile directory contains SOUL.md.
docker exec hermes hermes -p coder gateway stop
docker exec hermes hermes -p coder gateway start
docker exec hermes hermes -p coder gateway restart
docker exec hermes hermes -p coder gateway statusFor a profile running its own s6 service, Hermes routes start, stop and restart to s6. Only a gateway you explicitly stopped with hermes gateway stop stays down across a container restart; a restart, image upgrade or unexpected exit leaves the recorded state as running, so it starts again on the next boot.
To opt out of supervision, pass --no-supervise to gateway run or set HERMES_GATEWAY_NO_SUPERVISE=1. The gateway then runs as the container’s main process with no auto-restart, and the container exits when it does. The docs call that useful for CI smoke tests and say the supervised default is better for production. For a headless container, follow the output with docker logs -f hermes; in an interactive container, supervised output goes to /run/uncaught-logs/current by default. For the full container setup see Hermes Agent in Docker.
Windows and WSL
Windows native. hermes gateway install registers a task that runs at login with standard user permissions. Registration asks for UAC confirmation once. If policy blocks task registration, Hermes uses the Startup folder. In PowerShell, use hermes gateway status, hermes gateway start, hermes gateway stop or hermes gateway restart. The Windows page says stop waits for the gateway to drain (capped at 30 seconds) and only then force-kills it if it is still alive, and that restart does the same drain-first stop and then a fresh start. status shows a merged view of the task, the Startup folder and the running process. A plain start without a terminal does not touch the login auto-start setting.
WSL. The docs say WSL’s systemd support is unreliable, so start may fail or the service may not survive WSL restarts. They advise hermes gateway run instead. For a foreground launch, choose one of the following commands. The first runs the gateway in the current terminal, the second runs it in tmux so you can close the terminal, and the third runs it in the background with nohup.
hermes gateway run
tmux new -s hermes 'hermes gateway run'
nohup hermes gateway run > ~/.hermes/logs/gateway.log 2>&1 &With tmux, reattach later with tmux attach -t hermes. If you do want systemd on WSL, the quickstart enables it with systemd=true under [boot] in /etc/wsl.conf, then wsl --shutdown from PowerShell. Reopen the WSL terminal and run ps -p 1 -o comm=. It should print systemd. Then run hermes gateway setup inside WSL; the wizard can install a user service so the gateway starts when WSL starts.
When it will not stop or keeps coming back
Check what happened immediately before the gateway came back. Work down this list, using what the docs say about each.
- A supervisor owns it. The installed Linux and macOS services and Docker’s s6 supervisor can relaunch a gateway after its process dies. Use
hermes gateway stopfor a planned stop. With--no-supervise, s6 does not relaunch the gateway; the container exits with it, and Docker can start the container again if its restart policy says so. On Windows, the registered task starts the gateway at login, and a gateway killed after launch stays down until it is started again. Opening the workspace withhermes webappcan also start a stopped gateway. - It starts at login or boot. On Windows, a registered task or Startup-folder entry launches the gateway at login, and
hermes gateway uninstallremoves it. On Linux, a system service from--systemcomes back at boot. - An update restarted it. After a successful update, Hermes tries to restart the running gateways of that home so they pick up the new code.
- A custom kill hook. The docs warn against adding a systemd drop-in such as
ExecStopPost=/bin/kill -9 $MAINPID: it fires on every stop, kills the fresh instance, and starts an infinite restart loop (on Telegram, a flood of restart messages). For a user service, open the override withsystemctl --user edit hermes-gateway, delete theExecStopPost=/bin/kill -9 $MAINPIDline, save, and runsystemctl --user daemon-reload. For a system service, usesudo systemctl edit hermes-gatewayto delete the same line and save. - A requested restart leaves the gateway stopped. If you launched the gateway with
hermes gateway runand the--external-supervisoroption, a restart exits with status 75. Configure the wrapper’s process manager to relaunch it after that exit. For systemd the docs say to useRestart=on-failureorRestart=alwayswithout 75 inRestartPreventExitStatus; without that policy a requested restart leaves the gateway stopped. A named profile that attaches to the host gateway under a service supervisor also exits 75 and is retried. - It is waiting for work to finish. While a graceful restart waits for active work to finish,
hermes gateway statuslists that work. Finish or stop a listed task to let the restart proceed. If the command finishes waiting while work is still active, the gateway keeps serving and restarts when it becomes idle; a supervisor starts it again, and if you started it by hand, runhermes gateway runagain after it exits. The restart interrupts work that Hermes identifies as wedged. For a manual stop or restart,--yesgives permission up front to interrupt active work. On Linux or macOS, choosehermes update --forcewhen starting an update if you intend to interrupt work across the gateways it owns; it cannot shorten an update already waiting. On Windows, the update still waits for work to finish.
To confirm it is really stopped:
hermes gateway status
hermes gateway liststatus is the check for one gateway, list shows every profile. To read the last 100 lines of the active profile’s gateway log, run hermes logs gateway -n 100. If it will not start again, the FAQ’s “Gateway won’t start” entry names missing dependencies, port conflicts and misconfigured tokens, and suggests hermes config show to check the configuration.
Stopping and restarting on ReadyHermes
ReadyHermes runs your Hermes Agent gateway on our servers, always on, connected to the chat apps you choose. There is no gateway service for you to manage and no terminal that has to stay open. In the workspace, Bot tools has a Power tab with start, stop and restart; a restart takes about a minute. Connecting a chat app or changing the model key also restarts the assistant for you, again about a minute.
We do not document which hermes commands work inside a ReadyHermes assistant, so use the Power tab rather than the commands on this page. Plans start from US$3.99 a month (Lite) or US$6.99 (Pro), with US$1 of AI included every month. If you would rather run it yourself, the page on self-hosting vs managed hosting covers the trade-off.
Questions
How do I stop Hermes Agent?
Run hermes profile to check the active profile. On the default profile, hermes gateway stop stops the service or foreground gateway, taking every profile it serves offline; on a named profile served by the shared gateway, it parks only that profile. If the gateway is running chat turns, cron jobs or background delegations, Hermes lists them and asks y/N first; add --yes to skip the question. To interrupt the running agent from a messaging chat, send /stop. This also kills running background processes and leaves the gateway online.
How do I restart the Hermes gateway?
Run hermes gateway restart. On Linux, use it when active turns matter because it asks the gateway to finish running work and waits up to its time limit for the replacement; if work is still running, the restart stays pending. From a messaging chat, send /restart. The gateway sends the restart confirmation when the chat connection is ready; if it still cannot deliver that confirmation after 30 minutes, it discards it.
How do I check whether the gateway is running?
Run hermes gateway status for the service, or hermes gateway list to see every profile and whether its gateway is running, with the PID where available. Run hermes logs gateway -n 100 to read the last 100 lines of the active profile's gateway log.
Why does the gateway start again after I stop it?
A service manager can relaunch a killed process. On Windows, the registered task starts the gateway at login. Opening the workspace with hermes webapp can start a stopped gateway, and a successful update tries to restart gateways that were running for the home being updated. A custom kill hook on a systemd unit can also cause a restart loop. Use hermes gateway stop for a planned stop.
How do I stop and restart Hermes on ReadyHermes?
Use the Power tab under Bot tools in the workspace, which has start, stop and restart. A restart takes about a minute. There is no gateway service for you to manage, and we do not document which hermes commands work inside a ReadyHermes assistant.