Repository navigation
[Feature] Native Windows support — working setup & guide (no Docker/WSL2) #1952
Description
What I got working
Hermes WebUI running natively on Windows 10/11 — no Docker, no WSL2, no VM overhead.
Guide: https://github.com/markwang2658/hermes-windows-native-guide
Setup: https://github.com/markwang2658/hermes-windows-native
How I bypassed the "Windows not supported" bootstrap
Your README says Native Windows is not supported for this bootstrap yet. I worked around it with:
- Manual env vars — set
HERMES_WEBUI_AGENT_DIR,HERMES_WEBUI_STATE_DIR,HERMES_WEBUI_HOST,HERMES_WEBUI_PORTin PowerShell before launching - Direct server.py invocation — skipped
ctl.sh start/bootstrap.pyentirely, calledpython hermes-webui/server.pydirectly - Isolated state dir — used
~/.hermes/webui-winto avoid conflicts with any WSL installations
WebUI-specific notes on Windows
- ✅ Chat, workspace browser, session management all work
- ✅ 7 themes render correctly
- ✅ Settings panel saves config properly
⚠️ File paths in workspace browser show POSIX-style/sometimes (minor)⚠️ Some shell commands from agent tools assume bash (expected)
Memory comparison
| Setup | RAM usage |
|---|---|
| WSL2 + Docker | ~1080 MB |
| WSL2 only | ~800 MB |
| Native Windows (mine) | ~330 MB |
What could be upstreamed
A start.ps1 equivalent of ctl.sh start would let Windows users skip the bootstrap entirely. Happy to contribute scripts or test PRs.
Activity
nesquena-hermes commentedon May 9, 2026
Thanks @markwang2658 — useful field report and a meaningful memory delta vs. WSL2/Docker (~330 MB vs ~1080 MB).
Two things worth separating here:
Your guide as-is — already valuable to the next Windows user who lands on the README's "Native Windows is not supported for this bootstrap yet" line. I'll link your repo from the README's Windows section as a community-maintained native setup pointer (PR-able by anyone — happy to take a small docs-only PR if you'd like).
Upstreaming a
start.ps1/ native bootstrap — this is the bigger ask, and it's where the trade-off lives. The current bootstrap (bootstrap.py+ctl.sh) handles three things you sidestep manually: dependency resolution into the agent venv,state_dir/agent_dirdiscovery, and a stable PID/log layout for restarts. A native Windows path would need to either (a) reproduce that machinery in PowerShell, or (b) makebootstrap.pyitself Windows-aware (more code in one place but fewer divergent code paths). Option (b) is the better long-term shape but it's a real chunk of work, and the maintenance cost is non-trivial (Windows CI runner, path-separator audit across the file tree, line-ending tests).Marking this as
hold+ Product Review for now — it's not a blocker for the next sprint, but it's a real feature request and worth a deliberate scoping decision rather than landing piecemeal. If you want to drive option (a) as a starter PR (start.ps1+ a "Native Windows" README section that links your guide), that's a clean, contained, low-risk PR I'd merge.nesquena-hermes commentedon May 24, 2026
Both halves resolved in v0.51.121:
feat(windows): native Windows community-guide link + start.ps1 launch…
fix(container): update image ghcr.io/nesquena/hermes-webui (0.51.108 …
Release v0.51.236 — Release HD (stage-q7) (#3491)
Release v0.51.239 — Release HG (stage-q10) (#3494)
fix(container): update image ghcr.io/nesquena/hermes-webui (0.51.230 …
feat(windows): native Windows community-guide link + start.ps1 launch…
Release v0.51.236 — Release HD (stage-q7) (nesquena#3491)
Release v0.51.239 — Release HG (stage-q10) (nesquena#3494)
feat(windows): native Windows community-guide link + start.ps1 launch…