docs(windows): comprehensive native Windows guide + install one-liner on landing page (early beta) by teknium1 · Pull Request #22089 · NousResearch/hermes-agent

teknium1 · 2026-05-08T21:41:19Z

Status: Early BETA. These docs cover the native Windows support from #21561, which is early beta. Expect rough edges — please file issues with repro steps. For the most battle-tested Windows setup today, use the Linux/macOS installer inside WSL2. Follow-up framing pass: #22115.

Summary

Ships user-facing docs for the native Windows support that landed in #21561. Landing page now has the install command inline; there's a dedicated Windows guide covering everything a user might hit.

What changed

website/docs/index.md — adds an inline Install section right under the hero CTAs with both one-liners:
- Linux/macOS/WSL2: curl -fsSL .../install.sh | bash
- Windows: irm .../install.ps1 | iex
website/docs/user-guide/windows-native.md — new 300-line guide covering install, feature matrix, Git Bash resolution, UTF-8 console shim, editor handling, Ctrl+Enter, gateway as a Scheduled Task, data layout, uninstall, process-management internals (bpo-14484), and 10+ pitfalls.
website/sidebars.ts — wires the new page in above the existing WSL2 guide.
website/docs/user-guide/windows-wsl-quickstart.md — cross-link now points at the dedicated native page instead of the installation.md anchor.
website/docs/reference/environment-variables.md — documents HERMES_GIT_BASH_PATH and HERMES_DISABLE_WINDOWS_UTF8 (were previously undocumented).

Validation

Local Docusaurus build skipped for speed; docs-site-checks on CI will catch any YAML or broken-link issues.
All internal links use relative .md paths or /docs/... absolute paths that match existing conventions.

…g page New page: website/docs/user-guide/windows-native.md — comprehensive Windows-native deep dive covering: - Quick install (irm | iex) and parameterized form - What the installer does end-to-end (uv, Python 3.11, Node 22, PortableGit, messaging SDK bootstrap) - Feature matrix: native Windows vs WSL2 (dashboard /chat is WSL-only) - How Hermes runs shell commands on Windows (Git Bash resolution, HERMES_GIT_BASH_PATH override, MinGit layout pitfall) - UTF-8 console shim (configure_windows_stdio, opt-out via HERMES_DISABLE_WINDOWS_UTF8) - Editor handling (notepad default, VSCode/Notepad++/nvim overrides, why Ctrl-X Ctrl-E used to silently do nothing) - Ctrl+Enter for newline in the CLI - Gateway as a Scheduled Task (schtasks + Startup-folder fallback, pythonw.exe detached spawn, why not a Windows Service) - Data layout (%LOCALAPPDATA%\hermes vs %USERPROFILE%\.hermes split) - PATH after install, environment variables, uninstall - Process management internals (bpo-14484 os.kill(pid, 0) footgun, _pid_exists primitive, check-windows-footguns.py CI gate) - 10+ concrete pitfalls with fixes Also: - docs/index.md: add inline 'Install' section with both Linux/macOS curl and Windows irm|iex one-liners right under the hero CTAs. Updates the quick-links row to include 'native Windows'. - sidebars.ts: add Windows (Native) entry above Windows (WSL2). - windows-wsl-quickstart.md: point native-install cross-link at the new dedicated page (was going to installation.md#windows-native). - reference/environment-variables.md: document HERMES_GIT_BASH_PATH and HERMES_DISABLE_WINDOWS_UTF8 (previously undocumented).

Adds early-beta framing to every user-facing surface where native Windows is introduced — landing page install block, Installation page, Windows (Native) guide, contributor notes, and README. Sets expectations that the path installs and runs but hasn't been road-tested as broadly as POSIX, and points users who want maximum stability at WSL2 instead. Follow-up to #21561 (native Windows support) and #22089 (Windows docs).

…g page (NousResearch#22089) New page: website/docs/user-guide/windows-native.md — comprehensive Windows-native deep dive covering: - Quick install (irm | iex) and parameterized form - What the installer does end-to-end (uv, Python 3.11, Node 22, PortableGit, messaging SDK bootstrap) - Feature matrix: native Windows vs WSL2 (dashboard /chat is WSL-only) - How Hermes runs shell commands on Windows (Git Bash resolution, HERMES_GIT_BASH_PATH override, MinGit layout pitfall) - UTF-8 console shim (configure_windows_stdio, opt-out via HERMES_DISABLE_WINDOWS_UTF8) - Editor handling (notepad default, VSCode/Notepad++/nvim overrides, why Ctrl-X Ctrl-E used to silently do nothing) - Ctrl+Enter for newline in the CLI - Gateway as a Scheduled Task (schtasks + Startup-folder fallback, pythonw.exe detached spawn, why not a Windows Service) - Data layout (%LOCALAPPDATA%\hermes vs %USERPROFILE%\.hermes split) - PATH after install, environment variables, uninstall - Process management internals (bpo-14484 os.kill(pid, 0) footgun, _pid_exists primitive, check-windows-footguns.py CI gate) - 10+ concrete pitfalls with fixes Also: - docs/index.md: add inline 'Install' section with both Linux/macOS curl and Windows irm|iex one-liners right under the hero CTAs. Updates the quick-links row to include 'native Windows'. - sidebars.ts: add Windows (Native) entry above Windows (WSL2). - windows-wsl-quickstart.md: point native-install cross-link at the new dedicated page (was going to installation.md#windows-native). - reference/environment-variables.md: document HERMES_GIT_BASH_PATH and HERMES_DISABLE_WINDOWS_UTF8 (previously undocumented).

…ch#22115) Adds early-beta framing to every user-facing surface where native Windows is introduced — landing page install block, Installation page, Windows (Native) guide, contributor notes, and README. Sets expectations that the path installs and runs but hasn't been road-tested as broadly as POSIX, and points users who want maximum stability at WSL2 instead. Follow-up to NousResearch#21561 (native Windows support) and NousResearch#22089 (Windows docs).