Run it
Wiring the desktop app to a backend
The desktop app decides where to send requests from one file, <code>connection.json</code>, and only two of its fields matter: <code>mode</code> and the <code>remote.url</code> it points at. Authentication is a third field, <code>authMode</code>, and it is not the password. On this machine the file reads mode local with an https URL parked in a remote block nobody uses - a working state that looks wrong. The failure that wastes the most time is not the file at all: an Ubuntu distro reported as Stopped by wsl.exe -l -v, with nothing listening on the serve port.
Two processes have to agree before the desktop app can talk to an agent: a server listening somewhere, and a small file on the Windows side that says where. When they disagree you get a symptom that looks like a configuration error but usually is not, and the file looks fine while the thing it points at is asleep.
What the connection file actually decides
The desktop app does not discover a backend. It reads one file, and that file has three levels. mode chooses the wiring: local means a backend on this machine, remote means a backend reached over the network. remote is a block holding url and authMode, and it is read only when the wiring calls for it. profiles is a map of per-profile overrides that sits on top of both.
That ordering explains the state that looks wrong. Here is the file on this machine, with the address and the profile names redacted:
$ python -c "…json shape only…"
mode: <str, len=5> # "local"
remote: dict
url: <str, len=24> # http://<redacted>:8765
authMode: <str, len=5> # "oauth"
profiles: dict # {}
mode is local, and there is still a remote block with a URL in it. Nothing is broken. The block is dormant: with mode: local the desktop does not read it. People edit the URL, see no change, and conclude the file is cached or ignored. It is neither - the field that selects the block says local.
Three wirings, three different failures
| Wiring | What listens | What fails when it is wrong |
|---|---|---|
| Backend on the same machine | The serve process, on loopback | A dead process is reported as a refused connection; the file is fine |
| Backend inside WSL | The serve process inside the distro, reachable from Windows | A stopped distro: refused connection with no config change needed |
| Backend on another host | The serve process bound to a routable address, with auth on | Auth mismatch or a firewall; the file is right and the request still fails |
Only the third row needs a password. That matters because the second row is where most people start, and it is the one where an authentication problem is least likely to be the cause.
The failure that looks like config but is a stopped distro
This is the whole point of the article, and it takes two commands. First, ask Windows what state the distro is in:
$ wsl.exe -l -v
NAME STATE VERSION
* Ubuntu Stopped 2
Then, from inside the distro, ask what is listening on the port the server would use:
$ wsl.exe -d Ubuntu -- bash -lc 'ss -tlnp | grep -E ":9119|:9911"'
9119/9911 无监听
Nothing. No listener, because there is no running distro to hold one. A WSL distribution stops when nothing needs it, and the agent server inside it stops with it. From the desktop app this is indistinguishable from a wrong port or a wrong host: you get a refused connection and a file that looks correct.
The fix is to start the distro and the server, in that order, and to treat the server as something that has to be verified rather than assumed:
wsl.exe -d Ubuntu -- bash -lc 'ss -tlnp | grep 9119'
# no output = still down; start the server, then re-run the same command
If you want it to survive the terminal you started it from, it has to be detached properly. nohup alone is not enough on every setup; a process that stays attached to the session dies with it. Check the parent id after starting it - a parent of 1 means it is genuinely detached:
ps -o pid,ppid,cmd -C hermes | head
secret is not the password
The second trap lives in the server config, not the connection file. When the server is started bound to a routable address it turns authentication on and writes a basic_auth block:
basic_auth:
username: admin
password_hash: scrypt… # hash of the password, not the password
secret: … # internal signing secret, not a credential
Three different things sit next to each other and two of them are named in a way that invites the wrong copy-paste. The password the desktop needs is the plaintext one, shown once when it is generated; password_hash cannot be turned back into it, and secret is not it either. Copying secret into the connection file produces an authentication failure that reads like a wrong password - and the password cannot be recovered, only regenerated by removing the block and restarting.
Which field picks the mechanism
authMode selects how the request is authenticated, and both values we have seen are legitimate:
oauth- the desktop forwards a token from the cloud gateway. No username and no password in the file. Seeing this value is not a misconfiguration.basic- the desktop sends a username and a password to the local server. Requires the server to have authentication enabled.
The mistake is to “fix” an oauth file into a basic one because a tutorial said so. If the gateway session is expired you get a token complaint, not a password prompt, and the fix is to sign in again rather than to rewrite the file.
The memory panel reads a different file
Worth stating because it costs an hour to notice: the memory panel is not a view of the backend. It reads the memory files in the desktop machine’s local data directory, whatever the connection mode is. With a remote or WSL backend, there are two copies of memory and the panel shows the local one - which on a fresh Windows install is empty or stale. Empty panel plus a working backend is not a bug; it is two stores that have not been synced.
Profiles: three places that must agree
A named profile has to be selected in three places and they are not the same switch:
- The CLI’s sticky default, written by the profile command - affects new CLI sessions only.
- A desktop-side active-profile file, passed to the backend at launch - this one wins over the sticky default, and it is only read at startup.
- The serve process itself, which enumerates profiles per request and needs no restart.
On this machine the desktop-side file does not exist, so the desktop starts with the default profile regardless of what the CLI was last set to. If a session comes up on the wrong profile, check the launch file before touching anything else.
How you know it worked
Three checks, in increasing order of confidence:
- The port answers from Windows:
curl -s -o /dev/null -w '%{http_code}' http://localhost:9119/api/statusreturns 200 rather than an empty response. If it returns nothing at all, the listener is not there. - The status payload lists the profiles you expect - the server enumerates them, so a missing profile is visible here rather than in the UI.
- The desktop completes a session: a reply arrives, and the memory panel matches the copy you expect it to read. If the panel is empty while the session works, you have the two-copy problem, not a connection problem.
A single green check is not enough: a listening port with a broken auth path fails at step 3, and a working session with an empty panel fails at the last clause.
How to undo it
Copy the file before you edit it, because there is no reset button and the values are not recoverable:
cp "$APPDATA/hermes/connection.json" "$APPDATA/hermes/connection.json.bak"
To undo a change, restore that copy and restart the desktop app - the file is read at launch, so a running session keeps the old values until it is restarted. If you enabled basic authentication and lost the password, delete the basic_auth block in the server config and restart the server: a new password is generated, and the sessions created under the old one are dropped. That last part is the cost, and it is worth knowing before you experiment rather than after.
What we did not test
The desktop app on macOS and on Linux, a Windows machine with more than one WSL distribution, and the case where the backend runs on a remote host behind NAT. The dump above is one machine in one state; the commands are portable, the conclusions about “refused connection” are the ones that repeated for us.
Related
Questions people actually ask
Where does the desktop app read the connection from?
One JSON file in the roaming app-data directory: connection.json on Windows. It has a mode field, an optional remote block with url and authMode, and an optional profiles map for per-profile overrides.
Is authMode the same as a password?
No. authMode selects the mechanism: oauth means the desktop forwards a cloud gateway token, basic means it sends a username and password to the local server. A separate password_hash inside the server config is not the password either - it is the scrypt hash of it, and the plaintext only exists at the moment it is generated.
Why does the memory panel look empty when the backend has memory?
The panel reads the local memories directory on the desktop machine, not the backend over the connection. Two machines, two copies; if they are not synced, the panel shows what the local copy has, which may be nothing.
The desktop says connection refused. Is the config wrong?
Check the distro first. A WSL distribution that is not running cannot accept connections, and wsl.exe -l -v reports it as Stopped. Nothing in connection.json will tell you that, and nothing in the config needs to change.
Do I need to restart the backend after changing profiles?
The serve process enumerates profiles at request time, so its own restart is not required. What does not hot-switch is the desktop session: it passes a profile at launch, so a running session keeps the one it started with.
Sources
- Hermes Agent documentation
- Microsoft Learn: basic WSL commands
- ss(8) - another utility to investigate sockets
Last checked: 2026-11-18 · The file dump, the wsl.exe -l -v output and the empty socket listing below were read on this machine on 2026-11-18. The URL and the profile name are redacted; the field names and their lengths are as they appeared.