Running Hermes Agent on a headless server while connecting from a desktop client on another machine requires two server processes and a single client connection.
The architecture separates the Hermes backend into two server-side processes and one client-side surface. The hermes serve backend handles the API and dashboard connections, while the hermes gateway run process manages messaging channels independently. The desktop client connects to the serve backend, not the gateway.
flowchart LR
subgraph Server["HEADLESS SERVER"]
serve["hermes serve<br/>--host 0.0.0.0<br/>:9119"]
gateway["hermes gateway run<br/>Telegram, Discord, Slack"]
end
subgraph Client["DESKTOP PC"]
desktop["hermes desktop<br/>(WebSocket connection)"]
end
desktop <--->|WebSocket| serve
gateway -.->|Shares ~/.hermes/| serve
Two processes on the server, one app on the client. Both server processes share the same ~/.hermes/ config, skills, memory, and sessions. Cron jobs execute on the server where the gateway runs.
For installation, provider setup, and initial configuration, start with the .
If your primary interface is mobile messaging, pair this setup with . Launch the app, navigate to Settings → Gateway → Remote gateway, and enter the server address:
http://<server-ip>:9119
Sign in with the username and password you configured on the server.
Alternatively, set the remote URL via environment variable:
HERMES_DESKTOP_REMOTE_URL=http://<server-ip>:9119 hermes desktop
Option B: Web dashboard
Open http://<server-ip>:9119 in a browser and sign in with the basic auth credentials. The web dashboard provides a browser-based interface to the Hermes backend without requiring a desktop installation.
Option C: CLI
From the desktop PC's terminal, configure the remote URL via the desktop app settings or the HERMES_DESKTOP_REMOTE_URL environment variable. The CLI surface connects through the same WebSocket channel as the desktop app.
Network and security considerations
| Scenario | Recommendation |
|---|---|
| Trusted LAN | --host 0.0.0.0 + basic auth |
| Exposed to internet | Use Tailscale (--host <tailscale-ip>) or OAuth provider |
| Firewall | Open port 9119 TCP on the server |
For a trusted local network, basic auth on 0.0.0.0 is adequate. If the server is exposed to the internet, use Tailscale to bind to the Tailscale IP instead of 0.0.0.0, or configure an OAuth provider for stronger authentication. Always open port 9119 TCP in the server's firewall when the backend needs to accept external connections.
Important process distinctions
Understanding the separation between the two server processes prevents common configuration mistakes:
hermes serve— The backend that the desktop app and web dashboard connect to. Handles the API surface and WebSocket connections.
hermes gateway run— The process that handles Telegram, Discord, Slack, and other messaging channels. Manages sessions, runs cron jobs, and routes messages.- These are two separate processes on the server. They share
~/.hermes/config, skills, memory, and sessions, but run independently. - Cron jobs execute on the server where the gateway runs.
- Profiles, skills, and memory are configured on the server side. The client connects to the already-configured backend.
For profile-first configuration and skills tuned to different production roles, see
SOCIAL SHARE CARD GENERATOR