Remote Backend: Desktop on a VPS or Home Server

The Desktop as a Thin Client

The Desktop app is not required to run on the same machine as the Hermes agent. The same JSON-RPC/WebSocket protocol that connects the Desktop to its local hermes serve backend can connect to a hermes serve instance running on any machine you can reach over a network -- a home server, a VPS, a work machine, or a powerful desktop machine running in another location.

This transforms the Desktop into a thin client: a graphical interface that runs on your laptop while the actual Hermes agent with all its tools, memory, files, and computational resources runs elsewhere. The agent has access to the remote machine's resources -- its storage, its installed tools, its network position -- while you interact with it from the comfortable graphical interface on your local machine.

Remote backend connections are especially useful when the remote machine has resources your laptop does not: more storage, a local GPU for fast inference, access to a specific network environment, or tools that are cumbersome to install on a laptop.

Setting Up the Server Side

On the machine that will run the Hermes backend (your VPS, home server, or remote desktop), you need Hermes installed and the web dependencies added:

cd ~/.hermes/hermes-agent && uv pip install -e ".[web,pty]"

Then start the server binding to all network interfaces so it can accept remote connections:

hermes serve --host 0.0.0.0 --port 9119

However, running with --host 0.0.0.0 without authentication means anyone who can reach that port can access your Hermes instance and use your API credits. Authentication is required before opening the server to any external network.

For a persistent setup that survives server restarts, install the gateway as a system service:

hermes gateway install

This registers Hermes as a systemd service (on Linux) or a launchd agent (on macOS) that starts automatically on boot and logs to the system journal.

Authentication Option 1: Nous Portal OAuth

Nous Portal OAuth is the recommended authentication method for any server accessible from the public internet or an untrusted network. It works like standard web OAuth: the Desktop app redirects you to the Nous Portal sign-in page when you connect, you authenticate with your Nous account, and a token is issued that the Desktop uses for all subsequent requests.

From the server side, Nous Portal OAuth requires no special configuration beyond enabling it (which is automatic when you connect through the Portal's proxy). The Portal handles the authentication layer; your server handles the agent requests.

The advantage of this approach: you do not need to manage your own authentication credentials or rotate them. Nous Portal handles token lifecycle, expiration, and refresh. If you revoke access, connections using the old token immediately stop working.

Authentication Option 2: Basic Auth for Trusted Networks

For servers on trusted networks -- your home LAN, a VPN, or a private cloud network where you control access at the network level -- basic authentication via a shared secret is simpler than OAuth.

Set the HERMES_DASHBOARD_BASIC_AUTH_SECRET environment variable on the server before starting hermes serve:

HERMES_DASHBOARD_BASIC_AUTH_SECRET=your-long-random-secret hermes serve --host 0.0.0.0

Any client that includes this secret in its connection request is granted access. The Desktop app prompts you for the secret when you connect to a remote backend using basic auth.

For login persistence across restarts, add the environment variable to the server's system environment or to the service configuration so it is set automatically when the service starts. Without persistence, the secret is lost on server restart and clients will fail to authenticate until the secret is re-set.

The secret should be a long, random string -- at least 32 characters. A UUID or the output of openssl rand -hex 32 works well. Store it somewhere safe (a password manager, a secure note) since you will need it to configure clients and to update if you rotate the secret.

Connecting the Desktop to a Remote Backend

Once the server is running with authentication configured, connecting from the Desktop app is straightforward. In Settings, open the Backend section and enter the server's address and port. The Desktop app attempts to connect and prompts you for authentication (OAuth redirect or basic auth secret, depending on which method the server uses).

After successful authentication, the Desktop operates normally -- the chat interface, file browser, agents panel, and all other features work the same way they do with a local backend. The difference is invisible in the UI: all agent execution happens on the remote machine, but the interface runs locally.

Session history and configuration are stored on the remote server (since that is where the agent is running). If you connect a second client to the same remote backend, both clients share the same sessions, configuration, and skills. This enables team workflows: multiple developers connecting to a shared Hermes instance, all working in the same session namespace.

Use Cases for Remote Backends

Remote backends enable a few workflows that are not practical with a local Desktop installation:

Home server as a persistent agent. Keep Hermes running 24/7 on a home server. Access it from your laptop, tablet, or any device with the Desktop app. The agent can run long-running tasks (batch processing, scheduled jobs, file monitoring) while your laptop is off or elsewhere.

Team-shared instance. One server, multiple team members each connecting with the Desktop app. Shared sessions mean the team can collaborate on an active agent session. Shared skills mean everyone has access to the same configured workflows.

Powerful remote workstation. Run Hermes on a machine with a GPU for local inference, while using the Desktop app on a lightweight laptop. The agent uses the GPU for fast responses; the interface runs on a machine that could not support the inference itself.

Network-positioned agent. A server inside a corporate network or a specific cloud VPC can access resources your laptop cannot. Connect your Desktop to a backend on that server and the agent gains access to those resources through its tools while you interact from outside the restricted network.