Hermes Agent Windows Install: Tips, Tricks, and Best Practices Guide

Hermes Agent runs natively on Windows 10 and Windows 11, with no WSL, Cygwin, or Docker required to get started. A Hermes Agent Windows install works fine out of the box, but a few settings quietly decide whether the setup stays smooth or turns into troubleshooting later. This guide walks through the ones actually worth knowing, from install through everyday use.

Installing Hermes Agent on Windows

Hermes offers two ways to get set up on Windows, and both land you in the same install.

1) PowerShell installer vs. the desktop installer

Two install paths exist. The PowerShell installer suits anyone already working in a terminal. The desktop installer is a better fit when handing Hermes to a non-developer, or when a double-click .exe experience is preferred over PowerShell.

Both installers provision the same dependencies and land in the same %LOCALAPPDATA%\hermes data directory and %LOCALAPPDATA%\hermes\hermes-agent code directory, so switching between the GUI and the CLI later works without a reinstall.

2) Passing install flags with the scriptblock form

The plain PowerShell installer command installs Hermes with default settings and cannot take parameters on its own. If a specific branch, commit, or tag is needed, or if the setup wizard should be skipped, wrap the installer in the scriptblock form instead:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1))) -NoVenv -SkipSetup -Branch main

This matters most in two cases: testing a pull request before it merges (-Branch <branch-name>), or locking a production machine to a known-good build instead of tracking main (-Commit <sha> or -Tag v0.14.0). -Commit overrides -Branch if both are set. Most first-time installs won’t need any of these flags.

Configuring the Hermes CLI for daily use

A couple of small settings make the CLI noticeably faster to work in day to day.

1) Setting a custom editor for /edit

Hermes uses the /edit command (or Ctrl-X Ctrl-E) to open a text editor for composing longer input. On Windows, Hermes now defaults this to Notepad automatically, so /edit works out of the box. Notepad is fine for quick edits, but a code editor is usually a better fit for anything longer. Point EDITOR at one explicitly:

$env:EDITOR = "code --wait"

The --wait flag matters for VS Code specifically. Without it, the editor process returns immediately and Hermes receives an empty buffer instead of the edited content. Add the line to $PROFILE so it persists across terminal sessions, or set it as a User environment variable in System Settings so it applies everywhere, including the desktop app.

2) Writing multi-line prompts with Ctrl+Enter

Windows Terminal, the VS Code integrated terminal, and any modern console host that supports VT escape sequences let Hermes bind Ctrl+Enter to insert a newline, so multi-line prompts can be composed directly in the CLI instead of pasting them in.

On legacy cmd.exe consoles this key combination collapses to a plain Enter. Use Esc then Enter instead, or move to Windows Terminal, which ships by default on Windows 11 and is free on Windows 10.

Troubleshooting common Hermes Agent issues on Windows

Most Windows-specific issues trace back to one of two causes: how Hermes finds a shell, or how it resolves network connections.

1) Fixing terminal commands that fail unexpectedly

Hermes runs shell commands through Git Bash rather than a native Windows shell, the same approach Claude Code uses. This only matters day-to-day if a terminal command behaves unexpectedly or Hermes can’t find a shell at all — in that case, it helps to know the resolution order: the HERMES_GIT_BASH_PATH environment variable if set, the installer-managed PortableGit path, an older Git-for-Windows layout, a system-wide Git for Windows install, then any bash.exe on PATH as a last resort.

If manually pointing Hermes at a MinGit install, use the non-busybox build (MinGit-*-64-bit.zip). The busybox variant ships ash instead of bash and is missing most coreutils, which breaks tools that expect real bash behavior.

2) Fixing startup hangs caused by broken IPv6

If Hermes appears to hang on startup or on outbound API calls, the cause is often a machine with broken or unreachable IPv6 connectivity. Python tries AAAA records first by default, which can stall for the full TCP timeout before falling back to IPv4.

Force IPv4 directly instead of waiting on the fallback:

network:
  force_ipv4: true

Running Hermes Agent in the background

Beyond the interactive CLI, Hermes can run as a standing gateway with its own execution and isolation settings.

1) Auto-starting the gateway at Windows login

hermes gateway install registers a Scheduled Task (schtasks /Create /SC ONLOGON /RL LIMITED /TN HermesGateway) that starts the gateway at login with standard, non-elevated permissions, so no UAC prompt appears. If Scheduled Tasks are blocked by group policy, Hermes falls back to a Startup-folder shortcut instead.

Either way, the gateway process runs through pythonw.exe rather than python.exe. This is what stops the gateway from being killed if Ctrl+C is pressed in another terminal window on the same machine — a real issue on Windows before this was addressed, since console-wide Ctrl+C signals could otherwise reach it.

2) Choosing a terminal backend: local vs. Docker vs. cloud

Hermes supports seven terminal backends, each controlling where the agent’s shell commands actually run: local, Docker, SSH, Modal, Daytona, Vercel Sandbox, and Singularity.

The local backend runs commands directly on the machine with no isolation and is the default for personal use. For anything that runs untrusted or agent-generated commands regularly, Docker is the safer choice since it isolates execution inside a single persistent container shared across the session. SSH, Modal, Daytona, and Vercel Sandbox all move execution off the local machine entirely, which suits remote development or ephemeral cloud compute.

Since the local backend has the same filesystem access as the signed-in Windows account, use hermes tools to disable tools that aren’t needed, or switch to the Docker backend for real sandboxing.

3) Isolating profiles with terminal.home_mode

By default (home_mode: auto), Hermes keeps subprocess HOME pointed at the real OS-user home directory on Windows installs, which lets tools like git, ssh, gh, and npm find credentials already set up in the normal shell. Most installs never need to touch this.

Switching to home_mode: profile isolates tool config per Hermes profile, using {HERMES_HOME}\home instead. That’s worth doing when a profile needs its own git identity, SSH keys, or GitHub CLI login separate from the main Windows account — but ~/.ssh, ~/.gitconfig, and similar host config won’t be visible unless deliberately linked into the profile home first. HERMES_REAL_HOME is set automatically so scripts can still find the real account home when needed.

Advanced configuration and update settings

A couple of config.yaml settings are worth setting once rather than leaving on defaults.

1) Setting the right update backup level

hermes update respects updates.pre_update_backup in config.yaml, with three levels: quick (default, snapshots config, cron jobs, pairing data, and auth), full (adds a zip of the entire HERMES_HOME directory), and off.

For a personal or test install, the quick default is enough. For an install running scheduled jobs or a messaging gateway that would be painful to reconfigure, switching to full is worth the extra update time. Files over 1 GiB are skipped in either mode, so very large data directories won’t be fully captured by the backup.

2) Setting up SOUL.md and AGENTS.md correctly

Hermes treats SOUL.md and project instruction files as separate scopes, and mixing them up leads to confusing behavior. SOUL.md defines the agent’s core identity and is loaded from $HERMES_HOME/SOUL.md independently of any project. Project-level instruction files use a priority system where only the first match loads: .hermes.md, then AGENTS.md, then CLAUDE.md, then .cursorrules.

AGENTS.md is the exception to “first match wins”: it’s hierarchical, so files in subdirectories are combined rather than overridden. All loaded context files are capped at context_file_max_chars (20,000 by default) with smart truncation, so very long instruction files may be cut before Hermes finishes reading them.

Hermes Agent security and safety best practices

Hermes Agent can read files, run shell commands, and browse the web on your behalf, so a few settings are worth locking down before letting it run unattended.

1) Skip admin rights for install and runtime

Both the PowerShell installer and hermes gateway install are designed to work without administrator privileges. The installer writes only to %LOCALAPPDATA%\hermes, and the gateway autostart task runs at standard, non-elevated permissions through Scheduled Tasks. There’s no reason to launch Hermes from an elevated PowerShell session for normal use, and doing so only widens what a mistaken or malicious command could touch.

2) Disabling tools you don’t need

The local terminal backend gives Hermes the same filesystem access as the signed-in Windows account, including everything that account can read, write, or delete. Run hermes tools to turn off individual tools that aren’t needed for a given workflow instead of leaving the full toolset enabled by default.

3) Sandboxing untrusted tasks with Docker

For tasks that involve untrusted code, scraped web content, or repositories from outside sources, switch terminal.backend to docker instead of running commands on the local backend. Docker isolates command execution inside a single persistent container with namespace and cap-drop isolation, so a manipulated instruction embedded in a file or webpage can’t reach the rest of the Windows install.

4) Referencing API keys instead of hardcoding them

Rather than writing API keys directly into config.yaml, reference them as environment variables:

auxiliary:
  vision:
    api_key: ${GOOGLE_API_KEY}

Cursor-style ${env:VAR_NAME} syntax works the same way, and other secret backends (${file:...}, ${vault:...}, ${bitwarden:...}) can inject values into the environment at startup through the secrets: block instead of storing them inline. If a referenced variable isn’t set, the placeholder is left as-is rather than silently failing, so a missing key shows up immediately instead of causing a confusing downstream error.

5) Isolating credentials per profile

By default, Hermes lets tool subprocesses use the real Windows account’s HOME, which means git, ssh, gh, and similar CLIs share whatever credentials are already configured system-wide. If a Hermes profile is used for less trusted work, setting terminal.home_mode: profile stops it from automatically inheriting ~/.ssh, ~/.gitconfig, or saved CLI logins, since tool subprocesses then use {HERMES_HOME}\home instead.

Frequently Asked Questions

Related Guides

• How Microsoft Scout Delegates Tasks to Sub-Agents (Explore, Research, and More)
• How to Install Microsoft Scout Agent on Windows and macOS
• AI Agent Stuck in a Loop? 7 Agent Failures and How to Fix Them
• How to Use SkillOpt to Enable LLM Agents to Learn New Skills Without Fine-Tuning
• CVE-2026-48710 (BadHost): Starlette Flaw Puts Millions of AI Agents at Risk
• Mark Zuckerberg AI Agent Could Replace CEO Tasks at Meta