본문으로 건너뛰기

Windows (Native) Guide - Early Beta

Early BETA

native Windows support는 early beta입니다. 설치와 실행은 가능하고 Windows footgun lint도 통과하지만, Linux/macOS/WSL2 경로만큼 넓게 실전 검증되지는 않았습니다. 특히 subprocess handling, path quirks, non-ASCII console output 주변에 rough edge가 있을 수 있습니다. 재현 가능한 문제가 있으면 issues에 repro steps를 남겨 주세요. 지금 가장 검증된 Windows 환경이 필요하다면 WSL2 기반 Linux/macOS installer 경로를 사용하세요.

Hermes는 Windows 10과 Windows 11에서 native로 실행됩니다. WSL, Cygwin, Docker가 필요 없습니다. 이 문서는 deep dive입니다. native에서 무엇이 동작하는지, 무엇이 WSL 전용인지, installer가 실제로 무엇을 하는지, Windows 전용으로 만져야 할 knob은 무엇인지 설명합니다.

설치만 하고 싶다면 landing page 또는 Installation page의 one-liner면 충분합니다. 예상과 다른 동작을 만났을 때 이 문서로 돌아오세요.

WSL을 원한다면

dashboard embedded terminal, fork semantics, Linux-style file watchers 같은 POSIX 환경이 필요하다면 **Windows (WSL2) Guide**를 참고하세요. 둘은 함께 설치해도 충돌하지 않습니다. native data는 %LOCALAPPDATA%\hermes, WSL data는 ~/.hermes에 저장됩니다.

Quick install​

PowerShell 또는 Windows Terminal을 열고 실행합니다.

irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex

admin 권한은 필요 없습니다. installer는 %LOCALAPPDATA%\hermes\에 설치하고 hermes를 User PATH에 추가합니다. 설치가 끝나면 새 terminal을 여세요.

Installer options(parameter 전달에는 scriptblock form이 필요):

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1))) -NoVenv -SkipSetup -Branch main
ParameterDefaultPurpose
-Branchmain특정 branch clone. PR 테스트에 유용
-NoVenvoffvenv 생성을 건너뜀. advanced: Python을 직접 관리
-SkipSetupoffpost-install hermes setup wizard 생략
-HermesHome%LOCALAPPDATA%\hermesdata directory override
-InstallDir%LOCALAPPDATA%\hermes\hermes-agentcode location override

Installer가 실제로 하는 일​

순서대로 다음을 수행합니다.

  1. uv bootstrap - Astral의 빠른 Python manager입니다. %USERPROFILE%\.local\bin에 설치됩니다.
  2. Python 3.11 설치 - uv를 통해 설치합니다. 기존 Python은 필요 없습니다.
  3. Node.js 22 설치 - winget이 있으면 winget, 없으면 portable Node tarball을 %LOCALAPPDATA%\hermes\node 아래에 풀어 설치합니다. browser tool과 WhatsApp bridge에 사용됩니다.
  4. Portable Git 설치 - git이 PATH에 있으면 그것을 사용합니다. 없으면 공식 git-for-windows release에서 trimmed self-contained PortableGit(약 45 MB)을 %LOCALAPPDATA%\hermes\git에 받습니다. admin 권한이나 Windows installer registry가 필요 없고, 기존 설치에 간섭하지 않습니다.
  5. repo clone - %LOCALAPPDATA%\hermes\hermes-agent에 clone하고 그 안에 virtualenv를 만듭니다.
  6. tiered uv pip install - 먼저 .[all]을 시도하고, GitHub rate limit 등으로 git+https dependency가 흔들리면 점진적으로 작은 extras(.[messaging,dashboard,ext] -> .[messaging] -> .)로 fallback합니다. "dependency 하나가 흔들려 bare install로 떨어지는" 실패를 막습니다.
  7. messaging SDK 자동 설치 - .env에 TELEGRAM_BOT_TOKEN, DISCORD_BOT_TOKEN, SLACK_BOT_TOKEN, SLACK_APP_TOKEN, WHATSAPP_ENABLED가 있으면 python -m ensurepip --upgrade와 targeted pip install을 실행해 각 platform SDK가 실제로 import 가능하게 합니다.
  8. HERMES_GIT_BASH_PATH 설정 - 해석된 bash.exe 경로를 설정해 fresh shell에서도 Hermes가 deterministic하게 찾도록 합니다.
  9. %LOCALAPPDATA%\hermes\bin을 User PATH에 추가 - 새 terminal을 열면 hermes command를 사용할 수 있습니다.
  10. hermes setup 실행 - model, provider, toolsets를 설정하는 일반 first-run wizard입니다. -SkipSetup으로 생략할 수 있습니다.

Feature matrix​

dashboard의 embedded terminal pane을 제외한 대부분의 기능은 native Windows에서 실행됩니다.

FeatureNative WindowsWSL2
CLI(hermes chat, hermes setup, hermes gateway 등)지원지원
Interactive TUI(hermes --tui)지원지원
Messaging gateway(Telegram, Discord, Slack, WhatsApp, 15+ platforms)지원지원
Cron scheduler지원지원
Browser tool(Chromium via Node)지원지원
MCP servers(stdio and HTTP)지원지원
Local Ollama / LM Studio / llama-server지원지원(WSL networking 필요)
Web dashboard(sessions, jobs, metrics, config)지원지원
Dashboard /chat embedded terminal pane미지원(POSIX PTY 필요)지원
Auto-start at login지원(schtasks)지원(systemd)

dashboard의 /chat tab은 POSIX PTY(ptyprocess)를 통해 실제 terminal을 embed합니다. native Windows에는 같은 primitive가 없습니다. Python의 pywinpty / Windows ConPTY로 구현할 수는 있지만 별도 implementation이므로 future work로 봅니다. dashboard의 나머지 기능은 native로 동작하며, 이 tab만 "use WSL2 for this" banner를 보여줍니다.

Windows에서 shell command 실행 방식​

Hermes의 terminal tool은 Git Bash를 통해 command를 실행합니다. Claude Code가 쓰는 전략과 같습니다. 모든 tool을 rewrite하지 않고 POSIX-vs-Windows gap을 우회합니다.

bash.exe resolution order:

  1. HERMES_GIT_BASH_PATH environment variable이 있으면 우선 사용.
  2. %LOCALAPPDATA%\hermes\git\usr\bin\bash.exe(installer-managed PortableGit).
  3. %LOCALAPPDATA%\hermes\git\bin\bash.exe(older Git-for-Windows layout).
  4. system Git-for-Windows install(%ProgramFiles%\Git\bin\bash.exe 등).
  5. 마지막 fallback으로 PATH에 있는 MSYS2, Cygwin, 기타 bash.exe.

installer는 HERMES_GIT_BASH_PATH를 명시적으로 설정해 fresh PowerShell session이 다시 탐색하지 않아도 되게 합니다. 특정 bash를 쓰고 싶다면 override하세요. 예: system Git Bash 또는 symlink를 통한 WSL-hosted bash.

Pitfall: MinGit layout은 full Git-for-Windows installer와 다릅니다. bash가 bin\bash.exe가 아니라 usr\bin\bash.exe 아래에 있습니다. Hermes는 둘 다 확인합니다. MinGit zip을 직접 푼다면 non-busybox variant(MinGit-*-64-bit.zip)를 고르세요. busybox build는 bash 대신 ash를 제공하고 coreutils가 많이 빠져 있습니다.

Windows UTF-8 console​

Windows에서 Python의 기본 stdio는 active code page를 사용합니다. 대개 cp1252 또는 cp437입니다. Hermes banner, slash-command list, tool feed, Rich panels, skill descriptions에는 Unicode가 들어갑니다. 아무 처리도 없으면 UnicodeEncodeError: 'charmap' codec can't encode character로 crash할 수 있습니다.

수정은 hermes_cli/stdio.py::configure_windows_stdio()에 있으며, 모든 entry point(cli.py::main, hermes_cli/main.py::main, gateway/run.py::main) 초기에 호출됩니다.

이 함수가 하는 일:

  1. kernel32.SetConsoleCP / SetConsoleOutputCP로 console code page를 CP_UTF8(65001)로 전환.
  2. sys.stdout / sys.stderr / sys.stdin을 UTF-8, errors='replace'로 reconfigure.
  3. child Python subprocess도 UTF-8을 상속하도록 PYTHONIOENCODING=utf-8, PYTHONUTF8=1 설정. setdefault를 사용하므로 사용자 override가 우선합니다.
  4. EDITOR와 VISUAL이 모두 없으면 EDITOR=notepad 설정. 아래 Editor section 참고.

idempotent하며 non-Windows에서는 no-op입니다.

Opt out: 환경변수 HERMES_DISABLE_WINDOWS_UTF8=1을 설정하면 legacy cp1252 stdio path로 돌아갑니다. encoding bug를 bisect할 때 유용할 수 있지만, 일반적으로 올바른 설정은 아닙니다.

Editor(Ctrl-X Ctrl-E, /edit)​

이전에는 Windows에서 Ctrl-X Ctrl-E를 누르거나 /edit를 입력해도 조용히 아무 일도 일어나지 않았습니다. prompt_toolkit의 fallback editor list는 POSIX absolute paths(/usr/bin/nano, /usr/bin/pico, /usr/bin/vi 등)에 고정되어 있어 Windows에서는 full Git for Windows가 설치되어 있어도 resolve되지 않았습니다.

Hermes의 Windows stdio shim은 이제 기본값으로 EDITOR=notepad를 설정합니다. Notepad는 모든 Windows 설치에 포함되어 있고 blocking editor로 동작합니다. subprocess.call(["notepad", file])은 window가 닫힐 때까지 block합니다.

User override가 우선합니다. setdefault 전에 확인됩니다.

EditorPowerShell command
VS Code$env:EDITOR = "code --wait"
Notepad++$env:EDITOR = "'C:\Program Files\Notepad++\notepad++.exe' -multiInst -nosession"
Neovim$env:EDITOR = "nvim"
Helix$env:EDITOR = "hx"

VS Code에서는 --wait flag가 중요합니다. 없으면 editor가 즉시 return하고 Hermes는 빈 buffer를 받습니다.

영구 설정하려면 PowerShell profile에 넣으세요.

# In $PROFILE
$env:EDITOR = "code --wait"

또는 System Settings의 User environment variable로 설정하면 새 shell 전체에 적용됩니다.

CLI에서 Ctrl+Enter로 newline 입력​

Windows Terminal은 Ctrl+Enter를 dedicated key sequence로 전달합니다. Hermes는 이를 "insert newline"으로 bind합니다. 따라서 CLI에서 multi-line prompt를 작성할 때 Esc 후 Enter에 의존하지 않아도 됩니다. Windows Terminal, VS Code integrated terminal, VT escape sequences를 지원하는 modern Windows console host에서 동작합니다.

legacy cmd.exe console에서는 Ctrl+Enter가 plain Enter로 collapse됩니다. 이 경우 Esc Enter를 사용하거나 Windows Terminal로 전환하세요. Windows 11에는 기본 설치되어 있고 무료입니다.

Windows login 시 gateway 실행​

Windows에서 hermes gateway install은 Scheduled Tasks를 사용하고, 실패 시 Startup folder fallback을 사용합니다. admin 권한은 필요 없습니다.

Install​

hermes gateway install

내부 동작:

  1. schtasks /Create /SC ONLOGON /RL LIMITED /TN HermesGateway - 사용자 login 때 standard(non-elevated) permission으로 실행되는 task 등록. UAC prompt 없음.
  2. group policy로 schtasks가 차단되면 %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup에 start /min cmd.exe /d /c <wrapper> shortcut을 작성합니다. 효과는 같지만 조금 더 투박합니다.
  3. gateway를 python.exe가 아니라 **pythonw.exe**로 detached spawn합니다. pythonw.exe는 console이 붙지 않으므로 같은 process group의 sibling process에서 Ctrl+C를 눌렀을 때 발생하는 CTRL_C_EVENT broadcast에 영향을 받지 않습니다.

spawn flags: DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP | CREATE_NO_WINDOW | CREATE_BREAKAWAY_FROM_JOB

Manage​

hermes gateway status      # schtasks + Startup folder + running PID merged view
hermes gateway start # scheduled task를 지금 시작
hermes gateway stop # graceful SIGTERM equivalent(psutil을 통한 TerminateProcess)
hermes gateway restart
hermes gateway uninstall # schtasks entry, Startup shortcut, pid file 제거

hermes gateway status는 idempotent입니다. 여러 번 호출해도 gateway를 실수로 죽이지 않습니다. 이전 구현에서는 os.kill(pid, 0)이 Windows에서 CTRL_C_EVENT와 충돌해 status 확인이 gateway를 죽이는 문제가 있었습니다. 자세한 내용은 아래 process management internals를 참고하세요.

왜 Windows Service가 아닌가?​

service 설치에는 admin 권한이 필요하고 lifecycle이 user login이 아니라 machine boot에 묶입니다. 일반적인 Hermes 사용자가 원하는 것은 "로그인하면 gateway 사용 가능, 로그아웃하면 gateway 종료"입니다. Scheduled Tasks는 elevation 없이 정확히 그 동작을 제공합니다. 정말 service가 필요하다면 nssm 또는 sc create를 직접 사용할 수 있지만, 보통은 필요 없습니다.

Data layout​

PathContents
%LOCALAPPDATA%\hermes\hermes-agent\Git checkout + venv. 삭제 후 재설치해도 됩니다.
%LOCALAPPDATA%\hermes\git\PortableGit. installer가 provision한 경우만 존재
%LOCALAPPDATA%\hermes\node\Portable Node.js. installer가 provision한 경우만 존재
%LOCALAPPDATA%\hermes\bin\hermes.cmd shim. User PATH에 추가됨
%USERPROFILE%\.hermes\사용자 config, auth, skills, sessions, logs. 재설치 후에도 유지

이 분리는 의도적입니다. %LOCALAPPDATA%\hermes는 disposable infrastructure입니다. 지워도 one-liner가 복구합니다. %USERPROFILE%\.hermes는 사용자 data입니다. config, memory, skills, session history가 들어 있으며 Linux install과 같은 모양입니다. 이 directory를 machine 간 mirror하면 Hermes 상태도 함께 옮겨집니다.

HERMES_HOME override: environment variable을 다른 data directory로 지정할 수 있습니다. Linux와 같은 방식으로 동작합니다.

Browser tool​

browser tool은 Node helper인 agent-browser로 Chromium을 제어합니다. Windows에서는:

  • installer가 npm을 통해 agent-browser를 PATH에 둡니다.
  • shutil.which("agent-browser", path=...)가 .cmd shim을 자동으로 찾습니다. CreateProcessW는 extensionless shebang을 실행할 수 없으므로 Hermes는 항상 .CMD wrapper로 resolve합니다. shebang script를 직접 호출하지 말고 .cmd를 거치세요.
  • Playwright Chromium은 첫 실행 시 자동 설치됩니다(npx playwright install chromium). 설치가 실패하면 hermes doctor가 fix-it hint와 함께 보여줍니다.

Windows에서 Hermes 실행 시 practical notes​

설치 후 PATH​

installer는 %LOCALAPPDATA%\hermes\bin을 [Environment]::SetEnvironmentVariable로 User PATH에 추가합니다. 이미 열려 있는 terminal은 이 변경을 받지 않습니다. 설치 후 새 PowerShell window 또는 Windows Terminal tab을 여세요. 잘 모르면 수동으로 $env:PATH += ...를 붙이지 마세요.

확인:

Get-Command hermes        # C:\Users\<you>\AppData\Local\hermes\bin\hermes.cmd 출력
hermes --version

Environment variables​

Hermes는 $env:X(process-scope)와 User environment variables(permanent, System Properties -> Environment Variables)를 모두 존중합니다. API keys는 %USERPROFILE%\.hermes\.env에 넣는 것이 일반적이며 Linux와 같습니다.

OPENROUTER_API_KEY=sk-or-...
TELEGRAM_BOT_TOKEN=...

특별히 모든 Windows process가 secret을 보게 만들고 싶은 경우가 아니라면 User environment variables에 secret을 넣지 마세요.

Windows-specific env vars​

native Windows install에만 영향을 주는 변수입니다.

VariableEffect
HERMES_GIT_BASH_PATHbash.exe discovery override. full Git-for-Windows, symlink를 통한 WSL bash, MSYS2, Cygwin 등 어느 bash든 지정 가능. installer가 자동 설정합니다.
HERMES_DISABLE_WINDOWS_UTF81이면 UTF-8 stdio shim을 끄고 locale code page로 fallback. encoding bug bisect용
EDITOR / VISUAL/edit와 Ctrl-X Ctrl-E에 사용할 editor. 둘 다 없으면 Hermes가 notepad로 default 설정

Uninstall​

PowerShell에서:

hermes uninstall

clean path입니다. schtasks entry, Startup folder shortcut, hermes.cmd shim을 제거하고 %LOCALAPPDATA%\hermes\hermes-agent\를 삭제하며 User PATH를 정리합니다. 재설치를 고려해 %USERPROFILE%\.hermes\(config, auth, skills, sessions, logs)는 그대로 둡니다.

정말 전부 지우려면:

hermes uninstall
Remove-Item -Recurse -Force "$env:USERPROFILE\.hermes"
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\hermes"

hermes uninstall CLI subcommand는 schtasks entry가 older install에서 다른 task name으로 등록된 경우도 처리합니다. hardcoded task name이 아니라 install path로 검색합니다.

Process management internals​

이 section은 background material입니다. "왜 자꾸 스스로 죽지?" 같은 문제를 debug할 때만 보세요.

Linux와 macOS에서 POSIX idiom인 os.kill(pid, 0)은 no-op permission check입니다. "이 PID가 살아 있고 signal을 보낼 수 있는가?"를 확인합니다. Windows에서 Python의 os.kill은 sig=0을 CTRL_C_EVENT에 map합니다. 둘 다 integer value 0이라 충돌하고, GenerateConsoleCtrlEvent(0, pid)를 통해 target PID가 속한 전체 console process group에 Ctrl+C를 broadcast합니다. 이는 bpo-14484이며 2012년부터 열려 있습니다. 현재 동작에 의존하는 script를 깨뜨릴 수 있어 수정되지 않을 가능성이 큽니다.

결과적으로 Windows에서 os.kill(pid, 0)으로 "PID가 살아 있는지 확인"하던 codepath는 target을 조용히 죽일 수 있었습니다. Hermes는 이런 모든 위치(11 files의 14 call sites)를 gateway.status._pid_exists()로 옮겼습니다. 이 함수는 psutil.pid_exists()를 사용하고, Windows에서는 OpenProcess + GetExitCodeProcess로 확인하므로 signal을 보내지 않습니다. plugin이나 patch를 작성한다면 psutil.pid_exists() 또는 gateway.status._pid_exists()를 사용하세요. os.kill(pid, 0)은 쓰지 마세요.

scripts/check-windows-footguns.py는 이를 CI에서 강제합니다. 새 os.kill(pid, 0) call이 들어오면, 해당 line에 # windows-footgun: ok - &lt;reason&gt; marker가 없는 한 Windows footguns (blocking) check가 실패합니다.

Common pitfalls​

설치 직후 hermes: command not found가 납니다. 새 PowerShell window를 여세요. installer가 %LOCALAPPDATA%\hermes\bin을 User PATH에 추가했지만 기존 shell은 갱신되지 않습니다. 당장 실행하려면 & "$env:LOCALAPPDATA\hermes\bin\hermes.cmd"를 사용할 수 있습니다.

tool 실행 중 WinError 193: %1 is not a valid Win32 application이 납니다. .cmd shim을 거치지 않고 shebang script를 직접 호출한 경우입니다. Hermes는 shutil.which(cmd, path=local_bin)로 command를 resolve해 PATHEXT가 .CMD를 잡게 합니다. hardcoded path로 tool을 호출하고 있다면 .cmd variant로 바꾸세요. 예: npx가 아니라 npx.cmd.

[scriptblock]::Create(...)가 The assignment expression is not valid로 실패합니다. 받아 온 install.ps1에 UTF-8 BOM이 붙은 경우입니다. irm | iex form은 BOM을 자동으로 제거하지만 [scriptblock]::Create((irm ...))는 그렇지 않습니다. simple irm | iex form으로 다시 실행하거나, script를 수동으로 내려받아 BOM 없이 저장하세요: [IO.File]::WriteAllText($path, $text, (New-Object Text.UTF8Encoding $false)).

restart 후 gateway가 계속 살아 있지 않습니다. hermes gateway status를 확인하세요. 이 명령은 schtasks entry, Startup-folder shortcut, live PID를 merge해 보여줍니다. schtasks가 등록되어 있는데 실행되지 않는다면 group policy가 ONLOGON trigger를 막고 있을 수 있습니다. schtasks /Query /TN HermesGateway /V /FO LIST로 failure reason을 확인하거나, uninstall 후 HERMES_GATEWAY_FORCE_STARTUP=1로 reinstall해 Startup-folder path로 fallback하세요.

$env:EDITOR를 설정했는데도 /edit가 아무 일도 하지 않습니다. 현재 process에만 설정했을 수 있습니다. shell을 닫았다가 다시 열거나, System Properties -> Environment Variables에서 User scope로 설정하세요. 새 PowerShell window에서 echo $env:EDITOR로 확인합니다.

Browser tool은 launch되지만 tools가 timeout됩니다. Chromium은 첫 실행 시 자동 설치됩니다. rate-limited GitHub나 Playwright CDN 이슈로 설치가 실패했다면 hermes doctor가 missing Chromium과 정확한 npx playwright install chromium fix command를 표시합니다.

agent-browser가 이상한 Node version error로 실패합니다. installer는 Node 22를 %LOCALAPPDATA%\hermes\node에 provision하지만, PATH에서 오래된 system Node 18이 먼저 잡힐 수 있습니다. Hermes의 node directory를 PATH 앞쪽으로 옮기거나, 다른 곳에서 쓰지 않는 system Node install을 제거하세요.

중국어/일본어/아랍어 문자가 CLI에서 ?로 보입니다. UTF-8 stdio shim이 활성화되지 않은 것입니다. HERMES_DISABLE_WINDOWS_UTF8가 설정되어 있지 않은지 확인하세요: Get-ChildItem env:HERMES_DISABLE_WINDOWS_UTF8. 비어 있는데도 ?가 보이면 매우 오래된 console host가 UTF-8을 제대로 지원하지 않을 수 있습니다. Windows Terminal로 전환하세요.

Gateway가 Telegram photos를 보낼 때 BadRequest: payload contains invalid characters가 납니다. Windows 자체 문제는 아니지만 Windows에서 먼저 보일 수 있습니다. 보통 JSON body에 backslash가 escape되지 않은 raw Windows path가 들어간 경우입니다. Telegram에는 Hermes가 normalize한 path가 전달되어야 합니다. custom plugin 안에서 본다면 사용자 input에서 만든 str(Path(...))가 아니라 Hermes-provided path를 넘기고 있는지 확인하세요.

다른 machine에서는 되는데 git pull 후 encoding이 이상합니다. Windows에서 non-UTF-8 editor(구버전 Notepad, 일부 Chinese IME 등)로 Hermes config나 skill을 수정하면 BOM이 붙을 수 있습니다. Hermes는 대부분의 config read에서 utf-8-sig를 tolerate하지만, folded YAML scalar(description: >) 내부 BOM은 YAML parsing을 조용히 깨뜨릴 수 있습니다. file을 plain UTF-8 without BOM으로 다시 저장하세요.

다음으로 볼 문서​