Windows Hermes Setup

Windows — Hermes Agent Setup & Pitfalls

Field-discovered Windows issues and their fixes. All operators on Windows should read this first.

Path Convention

All source code repos go under D:\Source\Repos\\\.

Example: D:\Source\Repos\GitHub.com\shikanime-studio\skills

Do not clone repos to C:\Users\\ — that location is not shared and not backed by the canonical path convention.

Python

python is the Microsoft Store stub — it opens the Store instead of running Python.

Always use:

python3 -c "..."
# or
uv run python -c "..."

uv run python works without any system Python install.

Hermes Update

hermes update fails while the gateway is running — Windows locks the executable.

# Stop gateway first
hermes gateway stop
hermes update --yes

# Or force (may need reboot to fully replace)
hermes update --force --yes

Config Encoding

config.yaml saved with UTF-8 BOM causes HTTP 400 "No models provided."

Re-save as UTF-8 without BOM. hermes config edit handles this correctly; Notepad does not.

GPG Signing

Windows Defender silently blocks gpg and gpg-agent. jj signs commits but produces no signature when Defender intercepts.

If signing silently fails, check Defender's app control / SmartScreen settings.

Shell

Hermes terminal on Windows runs through bash (git-bash / MSYS), NOT PowerShell or cmd.exe.

Use POSIX syntax: ls, $HOME, &&, |, single-quoted strings. PowerShell builtins (Get-ChildItem, $env:FOO, Select-String) will NOT work.

kubectl Context

tailscale configure kubeconfig switches the active context to the new cluster.

Always verify before running cluster commands:

kubectl config current-context
kubectl config use-context 

execute_code / Sandbox

WinError 10106 — sandbox child process can't create AF_INET socket.

Root cause: Hermes's env scrubber drops SYSTEMROOT / WINDIR. Python's socket module needs SYSTEMROOT to locate mswsock.dll.

Diagnose inside execute_code:

import os; print(os.environ.get("SYSTEMROOT"))

Key Paths

| Purpose | Path | | ----------- | -------------------------------------------------- | | Config | C:\Users\\AppData\Local\hermes\config.yaml | | Skills | C:\Users\\AppData\Local\hermes\skills\ | | Sessions DB | C:\Users\\AppData\Local\hermes\state.db | | Logs | C:\Users\\AppData\Local\hermes\logs\ |

skillmanage crossprofile

When editing skills that belong to another Hermes profile, skill_manage and write_file are blocked by default. Pass cross_profile=true only when explicitly directed to edit another profile's assets.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shikanime-labs
• Source: shikanime-labs/skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.