Skip to content

Connect to Hermes

Jump to bottom
JdaieLin edited this page Jun 14, 2026 · 1 revision

Whisplay Chatbot supports IM mode. After setting LLM_SERVER to whisplay-im, you can use the chatbot as an IM client connected to Hermes Agent.

Whisplay IM acts as a messaging platform for Hermes Gateway. You can speak to the Whisplay device, let the chatbot forward the message to Hermes, and display/play the Hermes response back on the device.

Configure Whisplay AI Chatbot to use IM mode

.env file settings:

LLM_SERVER=whisplay-im

## Whisplay IM bridge (use Hermes as IM backend)
# WHISPLAY_IM_BRIDGE_HOST=127.0.0.1
# WHISPLAY_IM_BRIDGE_PORT=18888
# WHISPLAY_IM_INBOX_PATH=/whisplay-im/inbox
# WHISPLAY_IM_POLL_PATH=/whisplay-im/poll
# WHISPLAY_IM_SEND_PATH=/whisplay-im/send
# WHISPLAY_IM_STATUS_PATH=/whisplay-im/status
# WHISPLAY_IM_APPROVAL_PATH=/whisplay-im/approval
# WHISPLAY_IM_TOKEN=define_by_yourself_and_configure_in_hermes
# WHISPLAY_IM_TIMEOUT_MS=30000

Normally, you only need to set LLM_SERVER=whisplay-im. If you set WHISPLAY_IM_TOKEN, configure the same token in the Hermes plugin configuration.

Restart the chatbot after editing .env:

sudo systemctl restart chatbot.service

In the chatbot log, you should see the Whisplay IM bridge listening:

Current LLM Server: whisplay-im
[WhisplayIM] Bridge server listening on 18888/whisplay-im/inbox

Install Hermes Agent

On the Raspberry Pi, install Hermes Agent with the official installer:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh -o /tmp/hermes-install.sh
bash /tmp/hermes-install.sh

If the installer cannot finish because GitHub or PyPI is slow on the Raspberry Pi, you can still use the installer-created environment under ~/.hermes/ and install the Python package manually:

~/.hermes/bin/uv venv ~/.hermes/venv --python 3.11
~/.hermes/bin/uv pip install --python ~/.hermes/venv/bin/python -i https://pypi.tuna.tsinghua.edu.cn/simple hermes-agent
mkdir -p ~/.local/bin
ln -sf ~/.hermes/venv/bin/hermes ~/.local/bin/hermes
ln -sf ~/.hermes/venv/bin/hermes-agent ~/.local/bin/hermes-agent

Verify the install:

~/.local/bin/hermes --version

Install the Whisplay IM plugin for Hermes

Clone the Whisplay IM Hermes plugin:

cd
git clone git@github.com:PiSugar/whisplay-im-hermes-plugin.git

If you use HTTPS instead of SSH:

cd
git clone https://github.com/PiSugar/whisplay-im-hermes-plugin.git

Copy the plugin into the Hermes user plugin directory and enable it:

mkdir -p ~/.hermes/plugins/whisplay-im
rsync -av ~/whisplay-im-hermes-plugin/ ~/.hermes/plugins/whisplay-im/
~/.local/bin/hermes plugins enable whisplay-im

Configure the Hermes plugin

Add the Whisplay IM plugin settings to ~/.hermes/.env:

WHISPLAY_IM_BASE_URL=http://127.0.0.1:18888
WHISPLAY_IM_CHAT_ID=whisplay-device
WHISPLAY_IM_ALLOW_ALL_USERS=true
# WHISPLAY_IM_TOKEN=the_same_token_as_whisplay_chatbot

Use 127.0.0.1 when Hermes and Whisplay Chatbot run on the same Raspberry Pi. If Hermes runs on another machine, replace 127.0.0.1 with the chatbot device IP address.

Configure a Hermes model provider

Configure Hermes with the model provider and model you want to use. The interactive model picker is the easiest path:

~/.local/bin/hermes model

You can also configure the provider and model directly. For example, to use DeepSeek:

~/.local/bin/hermes config set model.provider deepseek
~/.local/bin/hermes config set model.default deepseek-chat

Then add the API key required by your selected provider to ~/.hermes/.env and restart the gateway.

Examples:

# DeepSeek
DEEPSEEK_API_KEY=<your-deepseek-api-key>

# OpenRouter
OPENROUTER_API_KEY=<your-openrouter-api-key>

# OpenAI-compatible providers
OPENAI_API_KEY=<your-openai-api-key>

After editing ~/.hermes/.env, keep it private:

chmod 600 ~/.hermes/.env

Run Hermes Gateway

Install Hermes Gateway as a system service that runs as the pi user:

sudo ~/.local/bin/hermes gateway install --system --run-as-user pi --force
sudo ~/.local/bin/hermes gateway start --system

Check the service:

~/.local/bin/hermes gateway status --system
journalctl -u hermes-gateway -f

You should see the Whisplay platform connect in ~/.hermes/logs/gateway.log:

Connecting to whisplay_im...
[whisplay-im] Connected to http://127.0.0.1:18888
✓ whisplay_im connected
Gateway running with 1 platform(s)

Test the connection

Send a test message into the Whisplay IM inbox:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"id":"hermes-test-001","message":"Reply with one short sentence: Hermes is connected to Whisplay IM."}' \
  http://127.0.0.1:18888/whisplay-im/inbox

In ~/.hermes/logs/gateway.log, you should see:

inbound message: platform=whisplay_im user=Whisplay chat=whisplay-device

The Hermes response should be sent back to the Whisplay device through /whisplay-im/send.

Troubleshooting

If Hermes receives messages but replies with a provider error, check that the API key for your selected provider is present in ~/.hermes/.env and that the model is configured:

~/.local/bin/hermes config show

If the plugin is not loaded, confirm it is enabled:

~/.local/bin/hermes plugins list --plain --no-bundled

If the gateway does not connect to Whisplay IM, confirm that the chatbot bridge is running:

curl -s "http://127.0.0.1:18888/whisplay-im/poll?waitSec=1"

A healthy empty queue returns:

{"message":"","messages":[]}

If the Raspberry Pi has slow package downloads, use a local Python package mirror or download wheels on another machine and copy them to the Raspberry Pi, then install with:

~/.hermes/venv/bin/python -m pip install --no-index --find-links /tmp/hermes-wheels <package-name>

Clone this wiki locally