This guide explains how to connect Hermes Agent to Feishu/Lark and keep it running on an Ubuntu server with systemd. It addresses common deployment pain points such as relying on public callback URLs, installing dependencies into the wrong environment, and dealing with unstable service restarts. Keywords: Hermes, Feishu, WebSocket.
| Parameter | Description |
|---|---|
| Runtime Environment | Ubuntu 22.04+ |
| Integration Protocol | WebSocket |
| Target Platform | Feishu / Lark |
| Deployment Method | CLI + systemd |
| Core Dependencies | uv, lark-oapi, websockets |
| Project Popularity | Not provided in the original article; related sources indicate Hermes is a widely followed open-source Agent project |
Hermes is well suited for Feishu integration through WebSocket
Hermes is an extensible AI Agent gateway and runtime framework. After you connect it to Feishu, it can respond directly to messages in one-on-one chats or group chats. Compared with traditional HTTP callbacks, WebSocket mode does not require a public domain name, TLS certificates, or an externally reachable event callback URL.
This approach is especially suitable for individual developers, test environments, and lightweight production workloads. In practice, the hardest parts are usually not installing Hermes itself, but handling Feishu permissions, placing Python dependencies in the correct environment, and making sure systemd can read the .env file under the user directory.
You must complete Feishu app creation and authorization first
First, go to the Feishu Developer Console and create an Enterprise Internal App. After creation, the system assigns an App ID and App Secret. These are the most critical credentials for binding the Hermes gateway to your Feishu bot.
AI Visual Insight: The image shows where to create an Enterprise Internal App in the Feishu Open Platform. It makes clear that deployment starts on the platform side: developers must create the app instance first before they can obtain the App ID and App Secret and proceed with gateway configuration.
Next, enable bot capabilities and grant the required permissions in the permission management section, including sending direct messages, sending group messages, reading group information, and reading basic user information. The first app release often requires admin approval, which is the first place many deployments get blocked.
The following Feishu permissions are recommended first
| Permission | Purpose |
|---|---|
im:chat:readonly |
Read group chat information |
im:message |
Send direct messages |
im:message.group |
Send group messages |
contact:user.base:readonly |
Read basic user information |
The goal here is not to grant as many permissions as possible. Instead, make sure the bot has the minimum viable permissions required to run. When permissions are incomplete, Hermes can often start successfully, but the message pipeline fails during actual send and receive operations.
Hermes should be installed quickly on the server with the official script
On an Ubuntu 22.04+ server, first confirm that the system has curl and bash. Then run the official installation script so Hermes and its runtime directory can initialize automatically.
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash # Install Hermes in one step
which hermes # Verify that the command is available in the current user's PATHThese commands install Hermes and verify that the CLI is available.
After installation, run the gateway initialization command and enter the Feishu credentials, domain, and connection mode when prompted. Use feishu for the China edition, larksuite for the international edition, and choose websocket as the connection mode.
hermes gateway setup # Enter interactive gateway configurationThis command writes the Feishu integration parameters into Hermes local configuration.
Key parameters in the interactive setup must be entered correctly
Typical parameters include App ID, App Secret, Domain, Connection Mode, whether to enable direct messages, whether to enable group chats, and an optional Home Chat ID. The most important choice here is websocket, because it directly determines whether you need a public callback endpoint.
After configuration, check whether the environment variable file was generated:
FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxx
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket
FEISHU_ALLOW_ALL_USERS=trueThis .env file is the single source of truth for service hosting later.
Feishu dependencies must be installed into Hermes’ own virtual environment
The easiest mistake in the original deployment flow is to run pip install directly. Hermes uses uv to manage its virtual environment, so the Feishu SDK must be installed into the Hermes venv rather than the user’s global Python environment.
cd ~/.hermes/hermes-agent
uv pip install lark-oapi websockets # Install the Feishu SDK and WebSocket dependency
/home/ubuntu/.hermes/hermes-agent/venv/bin/python -c "import lark_oapi; print('ok')" # Verify that the package is installed in the correct environmentThese commands install the Feishu dependencies into the actual Python environment Hermes uses at runtime.
If you see Defaulting to user installation or ModuleNotFoundError: No module named 'lark_oapi', you can almost always conclude that the dependency was installed into the wrong location rather than there being a problem with Hermes itself.
Running Hermes under systemd is the key to stable long-term operation
When Hermes needs to stay online 24/7, do not rely on a foreground terminal session. The standard approach is to install it as a systemd service and let the system start it automatically at boot.
In some environments, sudo cannot directly find the hermes binary installed under the current user. In that case, create a symbolic link first, then install the systemd service.
sudo ln -s /home/ubuntu/.local/bin/hermes /usr/local/bin/hermes # Make hermes visible in the sudo environment
sudo hermes gateway install --system --run-as-user ubuntu # Install the system serviceThis step fixes the mismatch between the root PATH and the regular user PATH.
But installing the service alone is not enough. By default, systemd does not automatically read ~/.hermes/.env from the user directory, so you must explicitly inject the environment file.
[Service]
EnvironmentFile=/home/ubuntu/.hermes/.envThis override ensures that Feishu credentials are also visible when Hermes runs under systemd.
After adding the override, reload and start the service:
sudo systemctl daemon-reload # Reload service definitions
sudo systemctl enable --now hermes-gateway.service # Start the service and enable it at boot
sudo systemctl status hermes-gateway.service # Check service status
sudo journalctl -u hermes-gateway.service -f # Stream logs in real timeThese commands apply the service configuration, verify runtime state, and support log-based troubleshooting.
Most common failures fall into three categories: paths, dependencies, and environment variables
The most common errors include sudo: hermes: command not found, lark-oapi not installed, FEISHU_APP_ID/SECRET not set, and repeated service restarts. These typically map to a missing PATH entry, dependencies not installed into the venv, systemd not loading .env, and stale processes or broken configuration.
A quick troubleshooting reference can significantly reduce debugging time
| Symptom | Root Cause | Fix |
|---|---|---|
sudo: hermes: command not found |
The root environment PATH does not include user commands | Create the /usr/local/bin/hermes symbolic link |
lark-oapi not installed |
The Feishu SDK is not installed in the venv | Run uv pip install under ~/.hermes/hermes-agent |
Defaulting to user installation |
You used standard pip |
Switch to uv pip install |
FEISHU_APP_ID/SECRET not set |
systemd did not load .env |
Add EnvironmentFile in the service override |
status=1/FAILURE |
Broken configuration or stale processes | Run pkill -f hermes and inspect logs |
If you need to restrict access to specific users, disable open access and configure a whitelist:
FEISHU_ALLOW_ALL_USERS=false
FEISHU_ALLOWED_USERS=ou_xxxxxxxx,ou_yyyyyyyyThis configuration limits bot access to a specific list of users.
After changing the configuration, remember to restart the service. Otherwise, the changes will not take effect immediately.
sudo systemctl restart hermes-gateway.service # Apply the updated access control configurationThis command reloads the latest environment variables and gateway configuration.
Final validation should complete a full message loop inside the Feishu client
In Feishu, search for your bot by name, test a direct message first, and then test @bot in a group chat. If the bot returns messages normally, your app permissions, WebSocket connection, Hermes gateway, and systemd hosting are all working end to end.
For production readiness, the real acceptance criterion is not just active (running). It is whether Hermes can receive messages from Feishu reliably, send responses reliably, and provide traceable logs. That is what confirms the deployment loop is truly complete.
FAQ
1. Why use WebSocket instead of a callback URL?
In WebSocket mode, the client establishes the long-lived connection proactively. You do not need a public IP, domain name, or HTTPS callback URL. That makes it a better fit for personal deployments, cloud VM testing, and low-cost production rollouts.
2. Why does Hermes still report a missing module even though I installed lark-oapi?
Because the package was most likely installed into the user’s Python environment rather than the Hermes virtual environment. Go to ~/.hermes/hermes-agent and run uv pip install lark-oapi websockets.
3. systemd is running. Why does it still say FEISHU_APP_ID is not set?
This usually means the systemd process did not read ~/.hermes/.env. Add EnvironmentFile=/home/ubuntu/.hermes/.env through sudo systemctl edit hermes-gateway.service, then run daemon-reload and restart the service.
[AI Readability Summary]
This guide reconstructs the complete deployment workflow for integrating Hermes with Feishu/Lark, including Feishu internal app creation, permission configuration, Hermes installation, dependency setup, systemd service hosting, and troubleshooting. The core value is that WebSocket mode avoids public callback requirements and lets you attach an AI Agent to Feishu direct messages and group chats quickly and reliably.