# Remote Desktop Session — 2026-06-06

## Environment

- **Backend host:** debian-ai (192.168.1.50, Tailscale 100.126.244.3)
- **Desktop host:** CachyOS (192.168.1.111, user raymond, fish shell default)
- **Dashboard port:** 9119
- **Hermes version:** 0.15.1 (release 2026.5.29)
- **Desktop version:** v0.15.1 (Electron)

## Symptom

Hermes Desktop on CachyOS boot-loops with "Resolving Hermes backend" → starts local backend → "address already in use" on 127.0.0.1:9120 → restarts.

```
[hermes] [boot] Starting Hermes backend via existing Hermes CLI at /home/raymond/.local/bin/hermes
[...]
ERROR:    [Errno 98] error while attempting to bind on address ('127.0.0.1', 9120): address already in use
[hermes] Hermes backend exited (1)
[hermes] [bootstrap] reset requested by renderer; clearing latched failure
```

## Root Cause

Desktop was trying to start its own LOCAL backend (default behavior) instead of connecting to the remote Debian dashboard. The `connection.json` file at `~/.config/Hermes/connection.json` was missing or pointing to the wrong URL/auth.

## Fix Sequence

### Step 1: Verify remote dashboard

On Debian:
```bash
# Check dashboard listening
ss -ltnp | grep 9119

# Check auth state
curl -s http://127.0.0.1:9119/api/status | python3 -c "import sys,json; d=json.load(sys.stdin); print('auth_required:', d['auth_required'], '| auth_providers:', d['auth_providers'])"
```

### Step 2: Switch to token mode (disable basic auth)

```bash
# Stop dashboard, restart without auth
hermes dashboard --stop
env -u HERMES_DASHBOARD_BASIC_AUTH_USERNAME -u HERMES_DASHBOARD_BASIC_AUTH_PASSWORD \
    hermes dashboard --port 9119 --host 0.0.0.0 --insecure
```

### Step 3: Extract session token

```bash
curl -s http://127.0.0.1:9119/ | python3 -c "
import sys, re
html = sys.stdin.read()
m = re.search(r'__HERMES_SESSION_TOKEN__[\":=]*([a-zA-Z0-9_\-]+)', html)
print(m.group(1) if m else 'not found')
"
```

### Step 4: Configure Desktop (from Debian via SSH)

```bash
ssh raymond@192.168.1.111 'bash -s' <<'SSH_EOF'
mkdir -p ~/.config/Hermes
cat > ~/.config/Hermes/connection.json << 'CONF'
{
  "mode": "remote",
  "remote": {
    "url": "http://192.168.1.50:9119",
    "authMode": "token",
    "token": {
      "encoding": "plain",
      "value": "<TOKEN>"
    }
  }
}
CONF
cat ~/.config/Hermes/connection.json
SSH_EOF
```

Note: Must use `~/.config/Hermes/` (capital H). Lowercase `hermes/` is silently ignored.

### Step 5: Clear stale state and launch Desktop on CachyOS

```bash
# Kill stale processes
pkill -f "hermes.*desktop" 2>/dev/null || true
fuser -k 9120/tcp 2>/dev/null || true

# Clear stale log
rm -f ~/.hermes/logs/desktop.log

# Launch the Desktop app
~/.local/bin/hermes-desktop
```

## Credential Extraction Pitfall

The terminal tool redacts `.env` credential values when grepping/catting them:
```
HERMES_DASHBOARD_BASIC_AUTH_USERNAME=***
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=hermes...2026
```

Workaround: parse the file with Python and write to a temp JSON file:
```python
env_vars = {}
with open('/home/user/.hermes/.env') as f:
    for line in f:
        line = line.strip()
        if not line or line.startswith('#'): continue
        if '=' in line:
            k, v = line.split('=', 1)
            env_vars[k.strip()] = v.strip()

import json
with open('/tmp/hermes-creds.json', 'w') as f:
    json.dump(env_vars, f)
# Now read with: cat /tmp/hermes-creds.json
```

## SSH Shell Quoting (fish on CachyOS)

- Simple commands: `ssh raymond@192.168.1.111 'echo hello'` works
- Multi-line/complex: use `ssh raymond@192.168.1.111 'bash -s' <<'SSH_EOF'`
- Do NOT run GUI-launching commands over SSH (Desktop status hangs due to Electron remote-display detection)
- Use `pgrep -afa hermes-desktop` for process check instead of `hermes-desktop status`
- Read-only inspection is always safe: `cat ~/.config/Hermes/connection.json`, `tail -100 ~/.hermes/logs/desktop.log`