본문으로 건너뛰기

Windows (WSL2) Guide

Hermes Agent는 이제 native Windows와 WSL2를 모두 지원합니다. 이 문서는 WSL2 경로를 다룹니다. native PowerShell 설치는 별도 문서인 **Windows (Native) Guide**를 참고하세요.

WSL2를 선택하는 편이 좋은 경우:

  • dashboard의 embedded terminal(/chat tab)을 쓰고 싶다. 이 pane은 POSIX PTY가 필요하므로 WSL2 전용입니다.
  • POSIX-heavy development를 하고 있고, Hermes session이 dev tools와 같은 filesystem/path를 공유하길 원한다.
  • 이미 WSL2 환경이 있고 두 번째 설치를 유지하고 싶지 않다.

native Windows로도 충분하거나 더 나은 경우:

  • interactive chat, gateway(Telegram/Discord 등), cron scheduler, browser tool, MCP servers, 대부분의 Hermes 기능은 Windows에서 native로 실행됩니다.
  • file을 참조하거나 URL을 열 때마다 WSL-Windows 경계를 신경 쓰고 싶지 않다.

WSL2에서는 사실상 두 대의 computer가 함께 동작합니다. Windows host와 WSL이 관리하는 Linux VM입니다. 대부분의 혼란은 지금 어느 쪽에 있는지 확실하지 않을 때 생깁니다.

이 guide는 Hermes에 직접 영향을 주는 split만 다룹니다. WSL2 설치, Windows와 Linux 사이의 file 이동, 양방향 networking, 실제로 자주 부딪히는 pitfalls입니다.

왜 WSL2인가? native Windows와 비교​

native Windows 설치는 Windows에서 직접 실행됩니다. Windows terminal(PowerShell, Windows Terminal 등), Windows filesystem paths(C:\Users\...), Windows processes를 사용합니다. Hermes는 shell command 실행에 Git Bash를 사용합니다. Claude Code와 다른 agent들이 현재 Windows를 다루는 방식과 같은 전략이며, POSIX-vs-Windows gap을 전체 rewrite 없이 우회합니다.

WSL2는 lightweight VM 안에서 실제 Linux kernel을 실행합니다. 따라서 그 안의 Hermes는 Ubuntu에서 실행하는 것과 거의 동일합니다. fork, /tmp, UNIX sockets, signal semantics, PTY-backed terminals, bash/zsh, Linux에서와 같은 동작을 하는 rg, git, ffmpeg가 필요하다면 이 점이 중요합니다.

WSL2의 practical consequences:

  • Hermes CLI, gateway, sessions, memory, skills, tool runtimes는 모두 Linux VM 안에 있습니다.
  • Windows programs(browser, native apps, 로그인된 profile의 Chrome)는 VM 밖에 있습니다.
  • 두 세계가 대화해야 할 때마다 boundary를 건넙니다. files 공유, URL 열기, Chrome 제어, local model server 접속, Hermes gateway를 phone에 노출하는 일이 여기에 해당합니다. 이 문서는 바로 그 boundary를 다룹니다.

WSL2 설치​

Admin PowerShell 또는 Windows Terminal에서:

wsl --install

깨끗한 Windows 10 22H2+ 또는 Windows 11 machine에서는 WSL2 kernel, Virtual Machine Platform feature, 기본 Ubuntu distro가 설치됩니다. 재부팅을 요구하면 재부팅하세요. 이후 Ubuntu가 열리고 Linux username + password를 묻습니다. 이는 Windows account와 별개의 새 Linux user입니다.

실제로 WSL2인지, legacy WSL1이 아닌지 확인합니다.

wsl --list --verbose

VERSION 2가 보여야 합니다. distro가 VERSION 1이면 변환하세요.

wsl --set-version Ubuntu 2
wsl --set-default-version 2

Hermes는 WSL1에서 안정적으로 동작하지 않습니다. WSL1은 Linux syscalls를 즉석에서 translate하므로 procfs, signals, network 동작이 실제 Linux와 다릅니다.

Distro 선택​

Ubuntu(LTS)를 기준으로 테스트합니다. Debian도 동작합니다. Arch와 NixOS도 원하는 사용자는 쓸 수 있지만, one-line installer는 Debian 계열 apt system을 가정합니다. 해당 경로는 Nix setup guide를 참고하세요.

hermes gateway처럼 계속 실행할 process는 systemd로 관리하는 편이 쉽습니다. modern WSL에서는 distro 안에서 한 번만 활성화하면 됩니다.

sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true

[interop]
enabled=true
appendWindowsPath=true

[automount]
options = "metadata,umask=22,fmask=11"
EOF

그 다음 PowerShell에서:

wsl --shutdown

WSL terminal을 다시 열고 ps -p 1 -o comm=가 systemd를 출력하는지 확인하세요.

위 metadata mount option은 중요합니다. 이 옵션이 없으면 /mnt/c/...의 file이 실제 Linux permission bits를 저장할 수 없어, Windows path 아래 script에서 chmod +x 같은 작업이 깨질 수 있습니다.

WSL 안에 Hermes 설치​

WSL2 shell이 열린 상태에서:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc
hermes

installer는 WSL2를 일반 Linux로 처리합니다. WSL 전용 추가 작업은 필요 없습니다. 전체 layout은 Installation을 참고하세요.

Filesystem: Windows와 WSL2 경계 넘기​

가장 많이 헷갈리는 부분입니다. 두 개의 filesystem이 있고, file을 어디에 두는지가 성능과 정확성, tool visibility에 영향을 줍니다.

두 방향​

Direction실제 위치사용할 path
WSL에서 보는 Windows diskC:\Users\you\Documents/mnt/c/Users/you/Documents
Windows에서 보는 WSL disk/home/you/code\\wsl$\Ubuntu\home\you\code 또는 newer build의 \\wsl.localhost\Ubuntu\...

둘 다 real path이고 둘 다 동작하지만 같은 filesystem은 아닙니다. 내부적으로 9P network protocol로 bridged됩니다. 그 결과 성능과 semantics 차이가 실제로 생깁니다.

Hermes와 project를 어디에 둘 것인가​

경험칙: Linux 성격의 것은 Linux filesystem 안에 두세요.

  • Hermes install(~/.hermes/) - Linux side. installer가 이미 이렇게 합니다.
  • WSL에서 작업할 git repos - Linux side(~/code/..., ~/projects/...).
  • models, datasets, venvs - Linux side.

이렇게 하면 얻는 장점:

  • 빠른 I/O. /mnt/c/... 작업은 9P를 거치며 native ext4보다 10-100배 느릴 수 있습니다. ~/code에서는 즉시 끝나는 10k-file repo의 git status가 /mnt/c에서는 15초 이상 걸릴 수 있습니다.
  • 정확한 permissions. /mnt/c의 Linux permission bits는 best-effort emulation입니다. ssh가 "bad permissions"로 key를 거부하거나 chmod +x가 조용히 실패하는 일이 흔합니다.
  • 신뢰할 수 있는 file watchers. 9P를 넘는 inotify는 불안정합니다. dev servers나 test runners가 /mnt/c에서 변경을 놓치는 일이 자주 있습니다.
  • case-sensitivity surprise 방지. Windows path는 기본적으로 case-insensitive이고 Linux는 case-sensitive입니다. Readme.md와 README.md가 동시에 있는 project는 어느 쪽에서 작업하느냐에 따라 다르게 동작합니다.

Windows GUI app에서 바로 열어야 하거나 Windows Chrome의 DevTools MCP가 current directory를 Windows에서 접근 가능한 path로 요구하는 등 Windows side에 file이 있어야 하는 구체적 이유가 있을 때만 /mnt/c에 두세요.

file 이동​

Windows에서 WSL로: 가장 쉬운 방법은 Explorer 주소 표시줄에 \\wsl.localhost\Ubuntu를 입력하는 것입니다. 그런 다음 \home\&lt;you&gt;\...로 drag-drop할 수 있습니다. 또는 PowerShell에서:

wsl cp /mnt/c/Users/you/Downloads/file.pdf ~/incoming/

WSL에서 Windows로: /mnt/c/Users/&lt;you&gt;/...에 복사하면 Windows Explorer에 바로 보입니다.

cp ~/reports/output.pdf /mnt/c/Users/you/Desktop/

WSL file을 Windows app(GUI editor, browser 등)에서 열기: explorer.exe 또는 wslview를 사용합니다.

sudo apt install wslu     # 한 번만 설치. wslview, wslpath, wslopen 등 제공
wslview ~/reports/output.pdf    # Windows default handler로 열기
explorer.exe .                  # 현재 WSL directory를 Windows Explorer로 열기

두 세계의 path 변환:

wslpath -w ~/code/project        # \\wsl.localhost\Ubuntu\home\you\code\project
wslpath -u 'C:\Users\you'        # /mnt/c/Users/you

Line endings, BOMs, git​

Windows editor로 file을 수정하면 CRLF line ending이 들어갈 수 있습니다. Linux side에서 bash나 Python이 읽을 때 shell script가 bad interpreter: /bin/bash^M로 깨지거나, BOM이 붙은 .env file 때문에 Python이 실패할 수 있습니다.

WSL 안의 git config를 다음처럼 두는 것이 안전합니다. Windows 쪽 git config가 아닙니다.

git config --global core.autocrlf input
git config --global core.eol lf

이미 CRLF가 들어간 file은:

sudo apt install dos2unix
dos2unix path/to/script.sh

"WSL 안에 clone할까, /mnt/c에 clone할까?"​

WSL 안에 clone하세요. 특정한 이유가 없다면 항상 그렇습니다. 일반적인 Hermes workflow(hermes chat, repo를 rg/ripgrep하는 tool calls, file watchers, background gateway)는 /mnt/c/Users/you/myrepo보다 ~/code/myrepo에서 훨씬 빠르고 안정적입니다.

예외는 Windows binary를 launch하는 MCP bridge입니다. cmd.exe를 통해 chrome-devtools-mcp를 쓰는 경우(MCP guide: WSL to Windows Chrome), Hermes current working directory가 ~이면 Windows가 UNC warning을 낼 수 있습니다. 이 경우 해당 session은 /mnt/c/ 아래에서 Hermes를 시작해 Windows process가 drive-letter cwd를 갖도록 하세요.

Networking: WSL과 Windows​

WSL2는 자체 network stack을 가진 lightweight VM입니다. 즉 WSL 안의 localhost와 Windows의 localhost는 network 관점에서 같은 host가 아닐 수 있습니다. service마다 traffic이 어느 방향으로 흐르는지 판단하고 맞는 bridge를 골라야 합니다.

자주 나오는 경우는 두 가지입니다.

Case 1 - WSL의 Hermes가 Windows service에 접속​

가장 흔한 경우입니다. Ollama, LM Studio, llama-server를 Windows에서 실행하고, WSL 안의 Hermes가 여기에 접속해야 합니다.

정석 안내는 providers guide에 있습니다: WSL2 Networking for Local Models

짧게 요약하면:

  • Windows 11 22H2+: mirrored networking mode를 켭니다. %USERPROFILE%\.wslconfig에 networkingMode=mirrored를 설정하고 wsl --shutdown을 실행합니다. 그러면 양방향 localhost가 동작합니다.
  • Windows 10 또는 older builds: Windows host IP(WSL virtual network의 default gateway)를 사용하고, Windows server가 127.0.0.1이 아니라 0.0.0.0에 bind하도록 해야 합니다. Windows Firewall rule도 보통 필요합니다.

Ollama / LM Studio / vLLM / SGLang bind address, firewall rule one-liners, dynamic IP helpers, Hyper-V firewall workaround 등 전체 table은 위 guide를 참고하세요. 여기서 중복하지 않습니다.

Case 2 - Windows 또는 LAN device가 WSL의 Hermes에 접속​

반대 방향입니다. 다음이 필요할 때 해당됩니다.

  • Windows browser에서 Hermes web dashboard 사용
  • Windows-side tool에서 hermes gateway가 노출하는 OpenAI-compatible API server 사용. API Server feature page를 참고하세요.
  • Telegram, Discord 같은 messaging gateway가 local webhook URL을 호출해야 하는 테스트. 보통 raw port forwarding보다 cloudflared/ngrok를 씁니다.

Subcase 2a: Windows host 자체에서 접속​

Windows 11 22H2+에서 mirrored mode가 켜져 있으면 추가 작업이 없습니다. WSL process가 0.0.0.0:8080 또는 127.0.0.1:8080에 bind하면 Windows browser에서 http://localhost:8080으로 접근할 수 있습니다. WSL이 bind를 host로 자동 publish합니다.

NAT mode(Windows 10 / older Windows 11)에서는 기본 "localhost forwarding"이 Linux-side 127.0.0.1 bind를 Windows localhost로 대체로 forward합니다. 따라서 --host 127.0.0.1로 시작한 Hermes service도 Windows에서 http://localhost:PORT로 접근 가능한 경우가 많습니다. 안 된다면:

  • WSL 안에서 0.0.0.0으로 명시적으로 bind합니다.
  • ip -4 addr show eth0 | grep inet으로 WSL VM IP를 찾아 Windows에서 그 IP로 접속합니다.

Subcase 2b: LAN의 다른 device에서 접속​

이 부분이 가장 까다롭습니다. traffic은 LAN device -> Windows host -> WSL VM으로 흐르며 두 hop을 모두 설정해야 합니다.

  1. WSL 안에서 모든 interface에 bind하세요. 127.0.0.1에 listen하는 process는 VM 밖에서 접근할 수 없습니다. 0.0.0.0을 사용하세요.

  2. Windows -> WSL VM port forwarding을 설정하세요. mirrored mode에서는 자동입니다. NAT mode에서는 Admin PowerShell에서 port마다 직접 설정해야 합니다.

    # WSL VM의 현재 IP 가져오기(NAT에서는 WSL restart마다 바뀜)
    $wslIp = (wsl hostname -I).Trim().Split(' ')[0]

    # Windows port 8080 -> WSL:8080 forward
    netsh interface portproxy add v4tov4 `
      listenaddress=0.0.0.0 listenport=8080 `
      connectaddress=$wslIp connectport=8080

    # Windows Firewall 허용
    New-NetFirewallRule -DisplayName "Hermes WSL 8080" `
      -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Allow

    나중에 제거하려면 netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8080를 실행하세요.

  3. LAN device에서 http://&lt;windows-lan-ip&gt;:8080으로 접속하세요.

NAT mode에서는 WSL VM IP가 restart 때마다 바뀌므로 one-shot rule은 다음 wsl --shutdown까지만 안전합니다. 지속적으로 쓰려면 mirrored mode를 사용하거나 Windows login 때 port-proxy step을 실행하는 script를 두세요.

cloud messaging providers(Telegram setWebhook, Slack events 등)에서 오는 webhook이라면 port-forwarding으로 씨름하지 말고 cloudflared tunnel을 쓰세요. webhooks guide를 참고하세요.

Windows에서 Hermes service 장기 실행​

Hermes Tool Gateway와 API server는 long-lived process입니다. WSL2에서는 유지 방법이 몇 가지 있습니다.

위 setup section대로 systemd를 켰다면 hermes gateway와 API server는 일반 Linux machine에서처럼 동작합니다. gateway setup wizard를 실행하세요.

hermes gateway setup

wizard는 WSL이 시작될 때 gateway가 자동으로 올라오도록 systemd user unit 설치를 제안합니다.

Windows login 시 WSL 자체 시작​

WSL VM은 무언가가 사용 중일 때만 살아 있습니다. terminal window 없이 gateway를 계속 reachable하게 하려면 Task Scheduler로 Windows login 때 WSL process를 띄웁니다.

  • Trigger: At log on(사용자)
  • Action: Start a program
    • Program: C:\Windows\System32\wsl.exe
    • Arguments: -d Ubuntu --exec /bin/sh -c "sleep infinity"

이렇게 하면 VM이 살아 있고 systemd-managed gateway도 계속 실행됩니다. Windows 11의 newer wsl --install --no-launch + auto-start flow도 동작하지만, sleep infinity 방식이 portable합니다.

GPU passthrough(local models)​

WSL2는 WSL kernel 5.10.43+부터 NVIDIA GPU를 native로 지원합니다. Windows에 표준 NVIDIA driver를 설치하세요. WSL 안에 Linux NVIDIA driver를 설치하면 안 됩니다. 이후 WSL 안의 nvidia-smi가 GPU를 볼 수 있어야 합니다. 그 다음 CUDA toolkits, torch, vllm, sglang, llama-server는 일반적으로 실제 GPU에 맞춰 build됩니다.

AMD ROCm과 Intel Arc의 WSL2 support는 아직 변화가 많고 Hermes test matrix 밖입니다. 최신 driver에서 동작할 수는 있지만 추천할 recipe는 없습니다.

Windows-native local-model server(Ollama for Windows, LM Studio)가 이미 Windows driver로 GPU를 사용하고 있다면 WSL GPU passthrough는 필요 없습니다. 위 Case 1처럼 network로 WSL에서 접속하면 됩니다.

Common pitfalls​

Windows-hosted Ollama / LM Studio에 "Connection refused"가 납니다. WSL2 Networking을 확인하세요. 대개 server가 127.0.0.1에만 bind되어 있어 0.0.0.0이 필요하거나(Ollama: OLLAMA_HOST=0.0.0.0), firewall rule이 빠져 있습니다.

repo에서 git status / hermes chat이 매우 느립니다. 아마 /mnt/c/... 아래에서 작업 중일 가능성이 큽니다. repo를 Linux side인 ~/code/...로 옮기세요. 체감 속도가 한 자릿수 이상 좋아집니다.

script에서 bad interpreter: /bin/bash^M가 납니다. Windows editor가 넣은 CRLF line ending 때문입니다. dos2unix script.sh를 실행하고, WSL git config에 core.autocrlf input을 설정하세요.

MCP로 실행한 Windows binary에서 "UNC paths are not supported" warning이 뜹니다. Hermes cwd가 Linux filesystem 안에 있고 Windows cmd.exe가 이를 처리하지 못하는 상황입니다. 해당 session은 /mnt/c/...에서 Hermes를 시작하거나, Windows executable을 호출하기 전에 Windows-readable path로 cd하는 wrapper를 사용하세요.

sleep/hibernate 후 clock drift가 생깁니다. host가 sleep에서 깨어난 뒤 WSL2 clock이 몇 분 늦을 수 있고, OAuth/HTTPS API 같은 certificate 기반 동작이 깨질 수 있습니다. 필요할 때 다음을 실행하세요.

sudo hwclock -s

또는 ntpdate를 설치해 login 때 실행하세요.

mirrored mode를 켠 뒤 또는 VPN 연결 시 DNS가 멈춥니다. mirrored mode는 host network settings를 WSL로 proxy합니다. Windows DNS가 VPN split-tunnel이나 corporate resolver 때문에 꼬이면 WSL도 그대로 영향을 받습니다. workaround는 resolv.conf를 수동 override하는 것입니다. /etc/wsl.conf에 generateResolvConf=false를 설정한 뒤 /etc/resolv.conf에 1.1.1.1 또는 VPN DNS를 직접 작성하세요.

installer 실행 후 hermes를 찾을 수 없습니다. installer는 ~/.bashrc를 통해 ~/.local/bin을 shell PATH에 추가합니다. 현재 session에 반영하려면 source ~/.bashrc를 실행하거나 새 terminal을 여세요.

Windows Defender가 WSL files에서 느립니다. Windows에서 WSL files에 접근할 때 Defender가 9P bridge를 통해 scan하므로 /mnt/c류 cross-boundary slowness가 커집니다. WSL 내부에서만 file을 다룬다면 문제되지 않습니다. Windows tools로 \\wsl$\...를 자주 다룬다면 WSL distro path를 real-time scanning에서 제외하는 것을 고려하세요.

disk가 부족합니다. WSL2는 VM disk를 %LOCALAPPDATA%\Packages\... 아래 sparse VHDX로 저장합니다. file을 삭제해도 자동 shrink되지 않습니다. 공간을 회수하려면 wsl --shutdown 후 Admin PowerShell에서 Optimize-VHD -Path <path-to-ext4.vhdx> -Mode Full을 실행하세요(Hyper-V tools 필요). 또는 WSL docs의 diskpart 경로를 사용하세요.

다음으로 볼 문서​