How to Connect Hermes Desktop to a Remote Hermes Backend

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.

Dashboard login is not gateway restart authority#

Connecting Desktop to a remote backend and administering its messaging service are different privileges. Current dashboard Channels documentation says restarting a system-scope gateway from the browser uses sudo -n; missing permission causes an immediate refusal. A successful login or Chat response does not grant that operating-system privilege.

Record the remote host, profile and actual service owner. If a channel credential changed, have that owner perform the authorized restart, then verify the channel rather than rebuilding Desktop or creating a second backend. Keep dashboard authentication, provider authentication and OS service permissions as three separate entries in the handoff. See the dashboard control runbook for the acceptance sequence.

Resolve a backend-owner conflict before reconnecting Desktop#

A remote client does not need a second dashboard supervisor just because a new port is free. The current Dashboard reference documents a host-owning backend: a new dashboard launch that cannot use its requested host or port refuses with exit 78 and names the existing owner. Desktop's own loopback backends are explicitly excluded from this ownership claim.

On the remote host, inspect hermes dashboard --status and the actual service journal. Match the owning account, backend address and launch method to the connection saved in Desktop. Reuse the intended service, or arrange a maintenance window to stop its supervisor before replacing it. Starting a different port is not a substitute for deciding which backend should own the host. Use --isolated only when you intentionally need a separate profile server and understand its authentication boundary.

After resolving the conflict, test the same registered Desktop connection and profile. Confirm a harmless streamed reply, then check any messaging gateway separately. The dashboard service example includes a systemd guard against retrying exit 78 forever. For managed browser/mobile access instead of remote-service administration, compare FlyHermes plans; do not assume its hosted workspace is a drop-in Desktop endpoint.

Choose the gateway before the profile#

In current Desktop builds, open Settings → Gateways, then use the registered connection's Test action. The official connection guide says this test covers HTTP and WebSocket reachability. That is stronger than opening the public /api/status endpoint by itself. It still does not prove a specific tool, account permission or scheduled delivery.

Select the intended gateway in Sessions, then its profile. Two machines can both have a default profile without sharing state. Making a registry entry Primary changes the fallback for calls that omit a gateway; it does not switch the current Sessions workspace. Before diagnosing missing memory or files, check the displayed gateway, profile and a harmless known file on that backend.

A useful no-side-effect test is: “Report your current working directory and whether this known project folder exists. Do not edit files or start jobs.” Use a non-sensitive folder name and compare the result with the owning host. If it is wrong, repair the connection selection rather than copying credentials or deleting profiles.

After a full restart, Desktop normally opens Sessions on Primary unless the last-used-gateway preference is enabled. Record that choice when handing the setup to another operator. The self-hosted versus FlyHermes decision explains why a convenient remote client still leaves backend ownership with you.

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.

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.

Use the current multi-connection test#

In current Desktop builds, Settings → Gateways stores named local, remote, SSH, and cloud sources. Give every source a unique device name and run Test: it checks both HTTP and WebSocket legs, which is stronger than a public status probe. The selected profile's memory, sessions, cron jobs, and messaging state remain on the owning machine. Use the Dashboard and Web UI guide for auth, /api/ws, private access, and control-plane troubleshooting.

Do not rebuild Desktop for every remote Chat failure#

If the window opens but a remote Chat does not, use the Desktop after-update recovery guide to classify connection state before rebuilding. A healthy renderer plus failed Chat usually means the selected backend/profile, provider, authentication ticket, Host guard, or /api/ws path—not damaged Desktop assets.

When Desktop connects but the dashboard does not#

A remote status probe, the Hermes Dashboard, and live Chat test different paths. If Desktop sees the backend but the browser fails, verify the dashboard process and port, then authentication and WebSocket. Do not replace provider credentials until the transport layer is proven.

Record client and backend builds before updating remote connections#

Do not interpret different Desktop and Docker version labels as an automatic compatibility failure. The native application's package version, client commit and agent backend version identify different things. Follow the Desktop build-identification checklist and keep an explicit record for each registered connection:

• Connection name and actual host; redact private addresses before sharing publicly.
• Backend install method, running version and owning profile.
• Client application channel and build commit before and after relaunch.
• One reproducible symptom and the timestamp of its last test.

Current Desktop update documentation says a multi-target update can handle the connected backend, other eligible registered gateways, then Desktop. Review targets before pressing Update now: a local-looking control can affect remote work. Keep Docker image updates on their documented pull/recreate path and preserve the existing data mount. A package-managed installation is not a source checkout.

After maintenance, reconnect to the same named host and profile, run the connection test, then verify a harmless streamed prompt and backend file read. Check required messaging channels independently. If the client commit advanced but Chat still fails, investigate the authenticated transport and provider logs rather than repeating the updater. These are documented operating checks, not a claim that this guide reproduced every client/backend combination.

Verify login completion before changing the backend#

A successful Nous Portal sign-in does not by itself prove a working remote dashboard session. Check three stages: identity-provider sign-in, return to the registered /auth/callback, and acceptance of the resulting dashboard session. Match the registered HTTPS callback with HERMES_DASHBOARD_PUBLIC_URL, including the hostname and any non-default port. Follow the Hermes server security checklist before making the endpoint public.

For Nous OAuth, the documented registration shape is:

hermes dashboard register --redirect-uri https://dashboard.example.com/auth/callback

Replace the example hostname and run registration on the owning host. This changes OAuth registration; it is not a harmless diagnostic command to repeat on every failed sign-in. Start a fresh ordinary login and correlate its timestamp with backend authentication logs. Do not manually replay a callback: a direct visit lacks the normal PKCE state and cannot prove whether the real flow works. Share only redacted error names and timestamps, never cookies, codes, full authorization URLs or credentials.

• If the browser never returns from Portal, investigate the redirect stage before debugging WebSockets.
• If dashboard login completes but Chat fails, then inspect the accepted session, selected backend/profile and WebSocket guard.
• If a public management page works while signed out, restrict exposure and repair the auth boundary before testing more agent actions.

Use the built-in username/password provider only on a trusted LAN or VPN. Public HTTPS requires Nous OAuth or a conformant OIDC provider, plus controlled access to the origin. Do not remove authentication to make the connection test green. These distinctions follow the official Dashboard documentation; they are diagnostic checks, not a claim that every current login failure has the same cause.