Installing Hermes AI on Windows: Desktop, PowerShell, and WSL2

Hermes Agent supports Windows 10 and Windows 11. Users can choose from three deployment scenarios: native execution via PowerShell, the Hermes Desktop graphical application, or a WSL2 environment. Choosing the right path depends on your required build tools, terminal requirements, and filesystem architecture.

Choosing Your Installation Path: Native Environment vs. WSL2

Before installing, it is essential to determine the runtime context for your tasks:

• Native PowerShell and Hermes Desktop share the same data layout: source code and the virtual environment reside in %LOCALAPPDATA%\hermes\hermes-agent, while user settings, session history, and skills are stored in %LOCALAPPDATA%\hermes. The desktop interface and console CLI are interchangeable and operate on the exact same state.
• WSL2 isolates the environment inside a Linux virtual machine and stores configuration separately in ~/.hermes.

Architecture Selection Examples

1. Windows-centric projects (PowerShell / .NET / system utilities): If you automate host workflows, run background gateways for Telegram or Discord via Windows Task Scheduler, and operate on local NTFS files, choose native PowerShell or Hermes Desktop.
2. Linux-stack projects (Docker, Make, POSIX scripts): If your agent needs to compile Linux binaries, interact with UNIX sockets, or manage sessions via the built-in terminal in the web dashboard, deploy the agent in WSL2. In native Windows builds, the web dashboard supports metrics and configuration, but the /chat embedded terminal tab requires a POSIX PTY and is only available under WSL2.

---

Option 1: Native Installation via PowerShell

The native installer does not require administrative privileges and automatically provisions the uv package manager, an isolated Python 3.11 runtime, Node.js for browser automation tools, and PortableGit. You do not need to install Python globally on your system.

Open a standard PowerShell console and run:

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

The script adds %LOCALAPPDATA%\hermes\bin to the current user’s PATH environment variable. Once the script finishes, close the console window and open a new terminal session to apply the updated PATH. For advanced script parameters, refer to the official Windows Native guide.

---

Option 2: Hermes Desktop Graphical Client

Hermes Desktop provides a windowed interface featuring a session sidebar, a visual skill graph, tab support, and parallel agent management.

1. Download the installer from the Hermes Desktop documentation page.
2. Run the downloaded installer. On first launch, the application will automatically trigger the dependency setup script inside %LOCALAPPDATA%\hermes.

If you have already configured the agent via PowerShell, the desktop application will immediately pick up existing API keys and saved conversations.

---

Option 3: Installation Inside WSL2

WSL2 provides a standard Linux environment (ext4 filesystem, POSIX signals, PTY support).

Step 1. Prepare WSL2

In a PowerShell console with administrative privileges (Run as Administrator), run:

wsl --install

Restart your computer if prompted by the system, then configure your Linux username and password. Next, verify your distribution version:

wsl --list --verbose

Ensure that the VERSION column displays 2 for your selected distribution (Ubuntu by default).

Step 2. Deploy Hermes Agent

Open your Ubuntu terminal and run the installation command according to the WSL2 quickstart guide:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc

Important: Store your working repositories and project files inside the Linux filesystem (for example, ~/projects/), rather than on a mounted Windows drive (/mnt/c/). Cross-boundary file calls over the 9P protocol can cause slower I/O performance and sluggish git operations.

---

Environment Verification and First Run

Diagnostics and execution must be performed in the corresponding terminal for each environment: use PowerShell for native installations and Hermes Desktop, and use the Ubuntu terminal for WSL2.

For native installations and Hermes Desktop, open a new PowerShell session and run:

Get-Command hermes
hermes --version
hermes doctor

For WSL2 installations, open the Ubuntu terminal and run diagnostics:

command -v hermes
hermes --version
hermes doctor

The hermes doctor command verifies path resolution for git, the Chromium browser engine, and auxiliary dependencies.

Before starting a chat session, configure your model provider: if it is not already set up, run hermes setup first and select your model provider (in PowerShell for the native environment, or in the Ubuntu terminal for WSL2).

Once configured, initiate a standard conversation in your terminal and test it with a task that does not require file writes; note that hermes chat does not enforce permission sandboxing:

hermes chat

As your first prompt, submit an instruction that does not require disk writes (such as asking for an architectural concept explanation). The expected result is a successful initialization of your configured model provider and clean streaming text output without encoding errors.

For optional model configuration details, refer to the BetterToken documentation.

---

Troubleshooting Common Issues

Observed Symptom	Cause	Solution
hermes: The term 'hermes' is not recognized	The active console session has not reloaded the updated User PATH.	Restart your PowerShell window or invoke the binary directly: & "$env:LOCALAPPDATA\hermes\bin\hermes.exe".
The /chat tab in the web dashboard shows an error banner	Native Windows lacks POSIX PTY system mechanisms.	Session and task management works natively, but for the web terminal in /chat, run the agent inside WSL2.
WinError 193: %1 is not a valid Win32 application	Attempting to invoke a script directly without the .cmd wrapper.	On Windows, execute Node and npm tools with their explicit extension (for example, npx.cmd).
Question marks (?) instead of Unicode characters in CLI	Outdated console host lacking CP 65001 support.	Use Windows Terminal. Ensure the HERMES_DISABLE_WINDOWS_UTF8 environment variable is not set to 1.
High latency during git status inside WSL2	Project working directory is located at /mnt/c/....	Relocate the repository into the distribution’s Linux home directory (~/code/...) to leverage native ext4 performance.