hermes-windows-setup

Files (4)

• SKILL.md
• multi-service-bootstrapper.md · references/
• reasonix-migration-techniques.md · references/
• weixin-gateway-setup.md · references/

SKILL.md (first lines)

# Hermes Windows Setup — Desktop Configuration & Troubleshooting

## Overview

Hermes Desktop on Windows uses `%LOCALAPPDATA%/hermes/` (typically `C:\Users\<user>\AppData\Local\hermes\`) for config, logs, skills, and environment. This path differs from the Linux/macOS convention of `~/.hermes/`.

Key Windows-specific paths:
- Config: `%LOCALAPPDATA%/hermes/config.yaml`
- Skills: `%LOCALAPPDATA%/hermes/skills/`
- Env file: `%LOCALAPPDATA%/hermes/.env`
- Binary: `%LOCALAPPDATA%/hermes/hermes.exe`

## Autostart

1. Press `Win+R`, type `shell:startup`, press Enter.
2. Create a shortcut to `%LOCALAPPDATA%/hermes/hermes.exe` in the startup folder.
3. Add `--silent` argument to the shortcut's Target field for minimized startup:
   ```
   %LOCALAPPDATA%\hermes\hermes.exe --silent
   ```

### Silent Startup Verification

After reboot or manual launch:

```powershell
# Check process is running
Get-Process hermes
# Check logs
Get-Content "$env:LOCALAPPDATA\hermes\hermes.log" -Tail 10
```

## Windows Process Management

- **Graceful stop:** `Ctrl+C` in the terminal where hermes.exe was launched
- **Force kill:** `taskkill /f /im hermes.exe`
- **Check running:** `tasklist /fi "imagename eq hermes.exe"`
- **Kill by PID (safe):** `taskkill /f /pid <PID>` — never `taskkill /f /im python.exe` (kills ALL Python processes: Gateway, Nova, Kokoro, MCP, Knowledge Bridge — not just the intended one)

### Multi-Service Lifecycle Orchestration

When Hermes Agent has bound background services (ComfyUI/Nova, Kokoro TTS, Knowledge Bridge, etc.), manage them as a unified system rather than independent processes:

**Master bootstrapper pattern** — place a single `.vbs` in the Startup folder (`shell:startup`) that orchestrates all services in dependency order with HTTP health checks between each step:

```
Startup sequence:
  1. FlClash proxy (network dependency — reset proxy, then launch)
  2. Hermes Gateway (core — `hermes gateway run --replace`)
  3. Nova AI / ComfyUI (wait up to 60s for model load, health-check port 8188)
  4. Kokoro TTS (delay 2s to stagger GPU load, health-check port 8880, wait up to 45s)
  5. Knowledge Bridge (health-check port 8080, wait up to 15s)
  6. Apply process priorities (call Set-HeremesPriority.ps1 -Apply)
```

Each step does an HTTP GET against the service's known endpoint before declaring success. The bootstrapper writes a timestamped log to `%USERPROFILE%\.hermes-bootstrapper.log`.

Key VBS functions for health checks:
```vbs
Function IsHealthy(url, timeoutMs)
    Dim Http
    Set Http = CreateObject("MSXML2.ServerXMLHTTP.6.0")
    On Error Resume Next
    Http.open "GET", url, False
    Http.setTimeouts 2000, 2000, 2000, timeoutMs
    Http.send ""
    IsHealthy = (Err.Number = 0 And Http.Status >= 200 And Http.Status < 500)
    On Error GoTo 0
End Function
```

**Process priority scheme** — background GPU services should yield CPU to the interactive agent:

| Component | Priority Class | Win32 Priority | Rationale |
|-----------|---------------|---------------|-----------|
| Hermes Desktop (UI) | AboveNormal | 10 | User-facing, must be responsive |
| Hermes Gateway | AboveNormal | 10 | Core agent service |
| Agent Sessions / MCP | Normal | 8 | Responsive tool calls |
| Nova AI (ComfyUI) | BelowNormal | 6 | Background GPU inference (~900MB–1.2GB) |
| Kokoro TTS | BelowNormal | 6 | Background GPU inference (~1.8GB) |
| Knowledge Bridge | BelowNormal | 6 | Background query service |

Use a `.ps1` script with `-Apply` and `-Status` flags:
```powershell
powershell -ExecutionPolicy Bypass -File "$env:USERPROFILE\.hermes\scripts\Set-HermesPriority.ps1" -Apply   # set priorities
powershell -ExecutionPolicy Bypass -File "$env:USERPROFILE\.hermes\scripts\Set-HermesPriority.ps1" -Status  # report
```

The script identifies processes by CommandLine pattern matching (safe, PID-agnostic):
```powershell
$AllPython = Get-WmiObject Win32_Process | Where-Object {
    $_.Name -like 'python*' -or $_.Name -eq 'Hermes.exe'
}
$Groups['Gateway'] = $AllPython | Where-Object { $_.CommandLine -like '*hermes_cli*serve*' }
$Groups['NovaAI']  = $AllPython | Where-Object { $_.CommandLine -like '*ComfyUI*main*' }
$Groups['Kokoro']  = $AllPython | Where-Object { $_.CommandLine -like '*uvicorn*8880*' }
```

Fallback to `Get-CimInstance` if `Get-WmiObject` is unavailable.

**Startup folder hygiene** — maintain a single non-redundant set of scripts in `shell:startup`. Consolidate duplicates before adding the bootstrapper. Typical layout after cleanup:
```
FlClash-SafeStart.vbs       # Proxy safe launcher
Hermes Desktop.lnk           # Desktop GUI shortcut
Hermes-Bootstrapper.vbs      # Unified orchestrator (replaces standalone AI service launchers)
Hermes-Gateway.vbs           # (optional — kept for backward compat)
Outlook_Launch.vbs           # (optional — if needed)
```

### Binding Knowledge Injection

Place an `AGENTS.md` (or `.hermes.md`) at `%USERPROFILE%\.hermes\` to auto-load service management knowledge into every session. Include:
- Service names, ports, roles
- Start/stop commands for each service
- Priority scheme overview  
- Pitfalls (e.g. "never `taskkill /f /im python.exe`")
- Path to the priority manager script and bootstrapper log

This file loads at session start, so the agent knows what processes it owns and how to manage them without being told each time.

From statertly-pixel/mcp-cloud-deploy, MIT.

More from statertly-pixel/mcp-cloud-deploy