Can native Windows and WSL2 coexist?
The official installation docs say native and WSL2 installs can coexist cleanly because their data directories differ.
Native vs WSL2 vs Docker
Hermes Agent on Windows
Use WSL2 when you want the most battle-tested path. Use native Windows when you specifically need a Windows-native setup and can tolerate early-beta rough edges. Use Docker when deployment isolation matters more than direct desktop convenience.
Agent Guide is an independent editorial resource. It is not affiliated with, endorsed by, or sponsored by Nous Research, Hermes Agent, or Hermes/Hermes brand owners. Product names and marks belong to their respective owners.
Intent
hermes-agent-windows-install
Sources
5
Schema
2
Links
6
Decision matrix
| Path | Best for | Trade-off |
|---|---|---|
| WSL2 | Most Linux-like Hermes experience | Requires WSL setup and Linux filesystem habits. |
| Native Windows | Users avoiding WSL2 or Docker | Treat as early beta and verify shell/browser behavior. |
| Docker | Cleaner service-style operation | Needs Docker Desktop and volume/network understanding. |
Native Windows checks
- Run PowerShell as a normal user unless the official docs require otherwise.
- Confirm
hermes --helpworks in a new shell. - Check that Git Bash or the bundled shell dependency is available for terminal-tool behavior.
- Avoid connecting credentials until a simple non-sensitive task succeeds.
Troubleshooting pattern
- Capture the exact command and shell where the failure happens.
- Check whether the same command works inside WSL2.
- If terminal-tool behavior differs, test Docker before modifying production files.
- Document the environment in the page update notes if the failure becomes repeatable.
Windows success criteria
- PowerShell install completes without requiring administrator rights unless your environment policy requires it.
- A new shell can find
hermesfrom User PATH. - PortableGit or an existing Git install is available for shell-dependent behavior.
- You understand that the dashboard chat terminal pane is the main WSL2-only feature called out in official docs.
When to switch paths
| Symptom | Switch to | Why |
|---|---|---|
| Native terminal behavior differs from docs | WSL2 | It gives a Linux-like shell and file layout. |
| You need a stable service boundary | Docker | Container state and mounts are easier to isolate. |
| You only need desktop convenience | Native Windows or desktop installer | The official installer handles Python, Node, Git Bash, ripgrep, and ffmpeg. |
| You need to debug scripts deeply | WSL2 or Linux | Most shell examples and issue reports are easier to compare there. |
Agent Guide judgment
For Windows users, WSL2 is usually the most explainable first path because it behaves closer to the Linux examples. Native Windows is useful when desktop convenience matters, but every shell, PATH, Git Bash, and browser-control issue needs more careful capture.
If a native Windows error is hard to classify, stop debugging the product and classify the environment first: PowerShell, Git Bash, WSL2, Docker Desktop, PATH, and data directory.
Windows smoke test
- Run the installer in the intended shell, then open a new shell.
- Confirm
hermesresolves without relying on the installer session. - Check whether Git Bash or required shell tooling is present.
- Run one non-sensitive task before connecting provider keys or project folders.
Windows diagnostic packet
- PowerShell version and whether install used native Windows, WSL2, Docker, or desktop installer.
- Whether PortableGit or Git Bash was installed and
HERMES_GIT_BASH_PATHresolves. - Whether the failure is in CLI, gateway, cron, browser tool, MCP, or dashboard chat terminal.
- Whether
HERMES_DISABLE_WINDOWS_UTF8=1changes an encoding-related bug. - Whether the same task succeeds in WSL2 or Docker.
Official sources reviewed
| Source | Used for | Last checked | Confidence |
|---|---|---|---|
| Hermes Agent installation guide | Install commands, prerequisites, Windows/native installer details, and post-install checks. | 2026-06-05 | high |
| Hermes Agent configuration guide | Provider, model, backend, and environment configuration patterns. | 2026-06-05 | high |
| NousResearch/hermes-agent on GitHub | Repository discovery, release/source inspection, issues, and contribution context. | 2026-06-05 | high |
| Hermes Agent FAQ and troubleshooting | Command-not-found, provider, Docker, gateway, messaging, WSL, macOS PATH, and local model troubleshooting. | 2026-06-05 | high |
| Reddit r/hermesagent community start thread | Community demand signals for Docker vs local vs VPS, memory/context, OpenRouter, and install anxiety; not used as product truth. | 2026-06-05 | low |
Known caveats: Hermes Agent is moving quickly. Treat commands and support status as current only as of the verification date, then check the official docs before changing production systems.
FAQ
What should I capture in a Windows bug report?
Capture shell type, command, sanitized output, whether Git Bash is present, and whether the same command works in WSL2.
Operator checklist
Get the Agent Guide launch checklist
Receive the smoke-test order for install path, sandbox boundary, provider setup, source review, and production checks.