Hermes Desktop is useful when you want a native app surface while the real agent runtime lives somewhere else: a laptop, a lab machine, a VPS, or a managed backend. Bot Mode follows the same ownership rule: the Desktop roster can show Bots from registered local, remote, SSH, cloud, and Docker connections, but each Bot's profile, memory, sessions, tools, and routines remain on its owning backend. The important boundary is simple: Desktop is the client surface; the backend owns the agent runtime, tools, profiles, credentials, memory, and gateways. Prove Desktop locally before adding that boundary; on Windows, use the Desktop install troubleshooting guide first when bootstrap, PATH, proxy, or provider setup is still failing.
Quick answer#
Connect Hermes Desktop to a remote backend by running hermes serve --host <trusted-interface> --port 9119 on the remote machine, protecting the non-loopback bind with Nous OAuth, OIDC, or trusted-network Basic Auth, and selecting Settings → Gateway → Remote gateway in Desktop. Use hermes dashboard instead only when you also want the browser admin UI: it runs the same backend role plus Web UI. Keep the messaging gateway as a separate service and verify both the Desktop prompt and any real Telegram/Discord delivery.
Before adding a remote boundary, complete the first useful Hermes setup workflow against the local backend. Then reconnect Desktop to the remote backend and repeat the same bounded prompt. Matching results tell you the provider and task are healthy; differences narrow the problem to remote authentication, networking, profile selection, or backend state.
When a remote backend makes sense#
A remote backend is the self-hosted middle ground: better than a sleeping laptop, but still your server, credentials, dashboard boundary, provider lane, and gateway uptime. If the user really wants a managed browser/mobile control surface instead of backend operations, point them to the self-hosted vs hosted AI agent guide and FlyHermes pricing.
Use a remote backend when:
- The agent must keep running after your laptop sleeps.
- You want Telegram, Discord, webhook, or cron jobs to stay online from a VPS.
- The machine with models, Docker, browser automation, or private network access is not the machine with the UI.
- A teammate needs a clearer app surface without shell access.
If you only want a managed browser/mobile experience and channel uptime, compare this with FlyHermes. Remote Desktop plus self-hosting still leaves you responsible for server operations.
What changed recently#
The latest Hermes GitHub work improved Desktop and provider setup in three practical ways:
- Local/custom endpoints can be configured without pretending they need a hosted API key.
- Local/custom endpoints are wired into model assignment, so Desktop can route to the backend you actually selected.
- Desktop update handling is safer for managed clones, reducing the chance that update stash/restore behavior clobbers source state.
That makes a Desktop-to-backend setup less brittle, especially for users combining a native UI with self-hosted models or a remote Hermes service.
Setup checklist#
- Update Hermes Desktop and the remote Hermes install, then run
hermes doctoron the server. - Start
hermes serve --host <trusted-interface> --port 9119, or usehermes dashboardif you also need browser administration. - Configure Nous OAuth or OIDC for an internet-reachable host; use Basic Auth only on a trusted LAN or VPN. Confirm
/api/statusreportsauth_required: trueand the expected provider. - In Desktop, open Settings → Gateway → Remote gateway, enter the backend URL, sign in, save, and reconnect.
- Put
hermes serveunder a systemd user service on Linux so it survives logout and reboot. Load%h/.hermes/.env, run as the same Hermes user, and enable lingering. - Configure any local/custom model endpoint on the backend, not only in Desktop.
- Run one harmless Desktop prompt and inspect the backend log. If messaging matters, start the separate gateway and prove one real channel delivery.
Security boundary#
A remote backend is powerful because it owns the tool runtime. Treat it like an admin service:
- Do not publish the dashboard directly to the internet.
- Keep provider keys on the backend, not scattered across clients.
- Use separate Hermes profiles for personal, work, and bot contexts.
- Use the gateway troubleshooting guide when a channel stops replying instead of rotating every credential at once.
Desktop vs Web UI vs FlyHermes#
- Hermes Desktop: native client surface for local or remote Hermes work.
- Self-hosted Web UI: operations dashboard for config, provider, profile, memory, skills, cron, tools, and gateway status.
- FlyHermes: hosted cloud path for browser/mobile access, connected channels, and managed uptime.
The right choice depends on whether you want to operate the backend yourself. If yes, Desktop plus a remote backend is a strong setup. If no, use the hosted path.
Remote backend safety checks#
Treat a remote Desktop backend like a production agent service, not just a UI preference. The backend can hold provider credentials, memory, skills, tools, browser profiles, and gateway config, so the safest setup is a private network path: localhost forwarding, VPN, Tailscale, SSH tunnel, or an authenticated reverse proxy. After connecting, test one harmless CLI-style task from Desktop, then verify logs and profile state on the backend.
If the backend also runs Telegram, Discord, cron, or webhooks, prove those channels independently. Desktop can show that the backend is reachable, but it does not prove that a Telegram topic, Discord channel, or scheduled job will deliver correctly. Pair this page with the gateway troubleshooting guide and the self-hosted vs hosted AI agent comparison before exposing the service to real work.
A final smoke test should include opening the Desktop client, sending one harmless prompt, confirming the backend log records that request, and checking that no public unauthenticated dashboard URL was introduced during setup.
Remote Gateway uses hermes serve, not the OpenAI API server#
Hermes Desktop Remote Gateway connects to the remote hermes serve backend on port 9119. hermes dashboard can fill the same backend role when you also want the browser admin panel, but you normally choose one of those processes on a port. The optional OpenAI-compatible API server on port 8642 is a separate surface for API clients; it is not Desktop Remote Gateway.
For persistent Linux operation, run hermes serve as a systemd user service under the same account that owns Hermes. Load %h/.hermes/.env, preserve PATH and Docker access, enable the unit, and enable lingering if it must start before login. The dashboard runbook provides a complete unit you can adapt by changing dashboard to serve in ExecStart.
The messaging gateway is independent again: Desktop can connect successfully while Telegram or Discord remains offline. Start and verify the gateway separately, select the intended profile in Desktop, run one harmless tool call, and then test the exact channel or cron destination. For the ownership decision, use the self-hosted vs hosted AI agent guide.
Closing Desktop should not stop the remote runtime#
In a real remote-backend setup, Desktop is only the client. Close it, let the local laptop sleep, and verify the remote Hermes service still completes one scheduled job and delivers to the intended channel. If the work stops, the runtime still depends on the client machine or service wiring. Use the self-hosted vs hosted ownership test to isolate the boundary.
Diagnose remote readiness and Chat as separate connections#
Desktop can report a backend as ready because public GET /api/status answered, while live Chat still fails on the authenticated /api/ws path. On the remote Hermes dashboard, confirm auth_required: true, the expected auth provider, the exact port 9119 URL, and a non-loopback bind. Retry after signing in: 4401 means the WebSocket ticket did not authenticate; 4403 usually means the Host header or peer guard rejected the request. If the team does not want to maintain this auth and WebSocket path, use FlyHermes for managed browser/mobile access.