Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/techjarves/Hermes-USB-Portable/llms.txt

Use this file to discover all available pages before exploring further.

The Hermes messaging gateway is a background process that receives incoming messages from external platforms — such as Telegram and WhatsApp — and routes them to the Hermes agent for processing. Responses are sent back through the same platform automatically. The gateway runs independently of the TUI chat interface, so you can keep it alive while closing and reopening the launcher at any time.

​
Starting the Gateway

1

Via the Launcher Menu

From the main menu, select [3] Start Gateway. The launcher starts the gateway as a background process, waits two seconds for it to initialize, then returns you to the menu with an updated status showing Running (PID …).
2

Via the CLI

You can start the gateway directly from the terminal using the launcher scripts or the hermes command.
:: Start gateway via launcher (background)
launch.bat gateway

:: Or using explicit hermes command forms
launch.bat hermes gateway
launch.bat hermes gateway run
launch.bat hermes gateway run --replace
hermes gateway run --replace stops any existing gateway instance before starting a fresh one. Use this when the status shows Stopped (stale lock) and a clean restart is needed.

​
Stopping the Gateway

When the gateway is running, the main menu option [3] changes to Stop Gateway [live]. Select it to send a stop signal and clean up the PID file.

​
Restarting the Gateway

Navigate to [4] Advanced Options → [4] Restart Gateway. The launcher runs hermes gateway restart and returns you to the main menu with a refreshed status.

​
Install as a System Service

You can register the gateway as an OS-level service so it starts automatically on boot without needing to open the launcher. 
# Install the gateway as a system service (auto-start on boot)
hermes gateway install

# Remove the system service
hermes gateway uninstall
When installed as a service, the gateway runs in the background even after you unplug the USB drive or move the folder. Run hermes gateway uninstall before transferring the drive to a different machine.

​
Checking Gateway Status

hermes gateway status
This command prints whether the gateway process is running, along with its PID and any relevant error messages.

​
Telegram Bot Setup

To receive and respond to Telegram messages, you need a Telegram Bot Token. Set it in data/.env: 
TELEGRAM_BOT_TOKEN=your-telegram-bot-token-here
Once the token is set, start the gateway and use the following commands in your Telegram chat with the bot:
Telegram CommandWhat it does
/startStart chatting with Hermes
/stopCancel the current task or agent turn
/sethomeSet this chat as your home channel for cron jobs and notifications
Any textHermes processes the message as a prompt and replies inline
You can obtain a Telegram Bot Token by messaging @BotFather on Telegram and following the bot creation flow.

​
Gateway Logs

All gateway activity is written to data/logs/gateway.log.

View via Launcher

Navigate to [4] Advanced Options → [2] View Logs. The launcher prints the last 20 lines of gateway.log inline.

View via CLI

hermes logs
Or tail the file directly:
tail -n 20 data/logs/gateway.log
The gateway PID is tracked in data/gateway.pid. If the gateway process exits unexpectedly without cleaning up this file, the launcher will show Stopped (stale lock) in yellow. Use [3] Start Gateway or hermes gateway run --replace to recover.

Build docs developers (and LLMs) love

Get started for freeTalk to us