{"slug": "hermes-agent-headless-server-remote-desktop-setup", "title": "Hermes Agent: Headless Server + Remote Desktop Setup", "summary": "Hermes Agent now supports a headless server setup with remote desktop access, requiring two server processes (serve backend and gateway) and a single client connection. The architecture separates the API/dashboard from messaging channels, with both processes sharing the same configuration directory. This enables persistent operation via systemd service and basic auth for LAN security.", "body_md": "# Hermes Agent: Headless Server + Remote Desktop Setup\n\nHeadless Hermes server with remote desktop access\n\nRunning Hermes Agent on a headless server while connecting from a desktop client on another machine requires two server processes and a single client connection.\n\nThe architecture separates the Hermes backend into two server-side processes and one client-side surface. The `hermes serve`\n\nbackend handles the API and dashboard connections, while the `hermes gateway run`\n\nprocess manages messaging channels independently. The desktop client connects to the serve backend, not the gateway.\n\n--host 0.0.0.0\n\n:9119\"] gateway[\"hermes gateway run\n\nTelegram, Discord, Slack\"] end subgraph Client[\"DESKTOP PC\"] desktop[\"hermes desktop\n\n(WebSocket connection)\"] end desktop <--->|WebSocket| serve gateway -.->|Shares ~/.hermes/| serve\n\nTwo processes on the server, one app on the client. Both server processes share the same `~/.hermes/`\n\nconfig, skills, memory, and sessions. Cron jobs execute on the server where the gateway runs.\n\nFor installation, provider setup, and initial configuration, start with the [Hermes AI Assistant — Install, Setup, Workflow, and Troubleshooting](https://www.glukhov.org/ai-systems/hermes/).\n\n## Set up the headless server\n\n### 1. Configure authentication\n\nBasic auth provides sufficient protection for a trusted LAN. Add credentials to the environment file:\n\n```\ncat >> ~/.hermes/.env << 'EOF'\nHERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin\nHERMES_DASHBOARD_BASIC_AUTH_PASSWORD=choose-a-strong-password\nHERMES_DASHBOARD_BASIC_AUTH_SECRET=$(openssl rand -base64 32)\nEOF\nchmod 600 ~/.hermes/.env\n```\n\nThe `.env`\n\nfile lives alongside `config.yaml`\n\nunder `~/.hermes/`\n\n. Hermes resolves configuration with CLI overrides first, then `config.yaml`\n\n, then `.env`\n\n, then built-in defaults. Secrets belong in `.env`\n\n.\n\n### 2. Start the backend\n\nRun the serve backend on all interfaces:\n\n```\nhermes serve --host 0.0.0.0 --port 9119\n```\n\nThe backend listens on port 9119 and accepts WebSocket connections from the desktop client. Verify it is running with a quick status check:\n\n```\ncurl -s http://localhost:9119/api/status | jq '.auth_required, .auth_providers'\n# Expected: true  \"basic\"\n```\n\n### 3. Run as a systemd service\n\nFor a persistent server that survives reboots, install a user-level systemd service. Create the unit file at `/etc/systemd/user/hermes-serve.service`\n\n:\n\n```\n[Unit]\nDescription=Hermes Agent Serve Backend\n\n[Service]\nEnvironmentFile=%h/.hermes/.env\nExecStart=/home/rg/.hermes/hermes-agent/venv/bin/python -m hermes_cli.main serve --host 0.0.0.0 --port 9119\nRestart=on-failure\n\n[Install]\nWantedBy=default.target\n```\n\nReload the daemon, enable the service, and start it:\n\n```\nsystemctl --user daemon-reload\nsystemctl --user enable hermes-serve\nsystemctl --user start hermes-serve\n```\n\nCheck the service status:\n\n```\nsystemctl --user status hermes-serve\n```\n\n### 4. Start the gateway\n\nThe gateway is a separate process that handles messaging channels — Telegram, Discord, Slack, and others. Start it independently:\n\n```\nhermes gateway run\n```\n\nThe gateway and the serve backend are two separate processes. The gateway manages sessions, runs cron jobs, and routes messages. The serve backend provides the API surface for desktop and web dashboard connections. They share the same home directory but run independently.\n\nFor the full list of gateway commands and subcommands, see the [Hermes Agent CLI cheat sheet](https://www.glukhov.org/ai-systems/hermes/hermes-agent-cli-cheatsheet/).\nIf your primary interface is mobile messaging, pair this setup with [Hermes Voice Control from Your Phone](https://www.glukhov.org/ai-systems/hermes/hermes-voice-control/) for voice-first workflows on top of the same gateway process.\n\n### 5. Verify the backend\n\nConfirm the backend is responding and authentication is active:\n\n```\ncurl -s http://localhost:9119/api/status | jq '.auth_required, .auth_providers'\n```\n\nExpected output:\n\n```\ntrue\n\"basic\"\n```\n\nIf authentication is not enabled, the response will show `false`\n\nfor `auth_required`\n\n. Check that the `.env`\n\nfile contains the correct variables and that the service has restarted after configuration changes.\n\n## Connect from the desktop client\n\n### Option A: Hermes Desktop App\n\nInstall Hermes Desktop from the [official site](https://hermes-agent.nousresearch.com/). Launch the app, navigate to **Settings → Gateway → Remote gateway**, and enter the server address:\n\n```\nhttp://<server-ip>:9119\n```\n\nSign in with the username and password you configured on the server.\n\nAlternatively, set the remote URL via environment variable:\n\n```\nHERMES_DESKTOP_REMOTE_URL=http://<server-ip>:9119 hermes desktop\n```\n\n### Option B: Web dashboard\n\nOpen `http://<server-ip>:9119`\n\nin 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.\n\n### Option C: CLI\n\nFrom the desktop PC’s terminal, configure the remote URL via the desktop app settings or the `HERMES_DESKTOP_REMOTE_URL`\n\nenvironment variable. The CLI surface connects through the same WebSocket channel as the desktop app.\n\n## Network and security considerations\n\n| Scenario | Recommendation |\n|---|---|\n| Trusted LAN | `--host 0.0.0.0` + basic auth |\n| Exposed to internet | Use Tailscale (`--host <tailscale-ip>` ) or OAuth provider |\n| Firewall | Open port 9119 TCP on the server |\n\nFor a trusted local network, basic auth on `0.0.0.0`\n\nis adequate. If the server is exposed to the internet, use Tailscale to bind to the Tailscale IP instead of `0.0.0.0`\n\n, 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.\n\n## Important process distinctions\n\nUnderstanding the separation between the two server processes prevents common configuration mistakes:\n\n— The backend that the desktop app and web dashboard connect to. Handles the API surface and WebSocket connections.`hermes serve`\n\n— The process that handles Telegram, Discord, Slack, and other messaging channels. Manages sessions, runs cron jobs, and routes messages.`hermes gateway run`\n\n- These are\n**two separate processes** on the server. They share`~/.hermes/`\n\nconfig, skills, memory, and sessions, but run independently. - Cron jobs execute on the server where the gateway runs.\n- Profiles, skills, and memory are configured on the server side. The client connects to the already-configured backend.\n\nFor profile-first configuration and skills tuned to different production roles, see [Hermes AI Assistant Skills for Real Production Setups](https://www.glukhov.org/ai-systems/hermes/production-setup/).\n\n## Troubleshooting\n\n### Desktop cannot connect to the server\n\n- Verify the backend is running:\n`systemctl --user status hermes-serve`\n\n- Check the port is open:\n`ss -tlnp | grep 9119`\n\n- Test from the server:\n`curl -s http://localhost:9119/api/status`\n\n- Test from the client machine:\n`curl -s http://<server-ip>:9119/api/status`\n\n- If the client test fails, check firewall rules:\n`sudo ufw status`\n\nor`sudo iptables -L`\n\n### Authentication fails\n\n- Confirm\n`.env`\n\nfile has correct permissions:`ls -la ~/.hermes/.env`\n\n(should be`600`\n\n) - Verify the secret was generated:\n`grep HERMES_DASHBOARD_BASIC_AUTH_SECRET ~/.hermes/.env`\n\n- Restart the service after config changes:\n`systemctl --user restart hermes-serve`\n\n### Gateway does not respond to messages\n\nThe gateway is a separate process from the backend. If the desktop connects but messaging platforms do not work:\n\n- Check gateway status:\n`hermes gateway status`\n\n- Start the gateway if stopped:\n`hermes gateway start`\n\n- Review logs:\n`hermes logs gateway -f`\n\n## References\n\n[Hermes Agent Desktop App Documentation](https://hermes-agent.nousresearch.com/docs/user-guide/desktop)[Hermes Agent Configuration Guide](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)[Hermes Agent Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging)[Hermes AI Assistant — Install, Setup, Workflow, and Troubleshooting](https://www.glukhov.org/ai-systems/hermes/)[Hermes Agent CLI cheat sheet — commands, flags, and slash shortcuts](https://www.glukhov.org/ai-systems/hermes/hermes-agent-cli-cheatsheet/)[Hermes AI Assistant Skills for Real Production Setups](https://www.glukhov.org/ai-systems/hermes/production-setup/)\n\nThis article is part of the [AI Systems](https://www.glukhov.org/ai-systems/) cluster, which covers self-hosted assistants, retrieval architecture, local LLM infrastructure, and observability.", "url": "https://wpnews.pro/news/hermes-agent-headless-server-remote-desktop-setup", "canonical_source": "https://www.glukhov.org/ai-systems/hermes/hermes-remote-backend-desktop/", "published_at": "2026-07-08 00:00:00+00:00", "updated_at": "2026-07-08 11:59:21.936311+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-infrastructure"], "entities": ["Hermes Agent", "Telegram", "Discord", "Slack"], "alternates": {"html": "https://wpnews.pro/news/hermes-agent-headless-server-remote-desktop-setup", "markdown": "https://wpnews.pro/news/hermes-agent-headless-server-remote-desktop-setup.md", "text": "https://wpnews.pro/news/hermes-agent-headless-server-remote-desktop-setup.txt", "jsonld": "https://wpnews.pro/news/hermes-agent-headless-server-remote-desktop-setup.jsonld"}}