Hermes Agent on Windows: Beginner Install Guide
Goal: install Hermes with the official Hermes Desktop installer, finish the first setup, connect one model/provider, and confirm one useful chat.
Current Windows answer: Windows does not require WSL, Cygwin, Docker, Git, Python, Node, or developer tools before installing Hermes Desktop. The official docs say Hermes runs natively on Windows 10/11. The Desktop installer is the easy Windows path and calls the Windows installer/bootstrap on first launch to provision what Hermes needs.
What you installHermes Desktop, plus the shared Hermes command-line/runtime files used behind the scenes.
What the installer handlesPython via uv, Node, PortableGit, ripgrep, ffmpeg, browser-tool packages, and the local Hermes data folder.
SuccessHermes opens, one model/provider works, and a safe test prompt gets a useful answer.
Step 01
Before you start
You do not need to prepare a developer environment first. Just confirm these basics:
- A Windows 10 or Windows 11 PC with an x86_64 or aarch64 processor. Both are Tier 1 Hermes platforms.
- A normal Windows user account. Admin approval is usually not required for the Hermes per-user install, but Windows may still ask you to approve running a downloaded app.
- Reliable internet and a web browser.
- Permission to download and run the Hermes Desktop installer from the official Hermes site.
- A model/provider login or API key ready, such as Nous Portal, OpenAI/ChatGPT, Anthropic/Claude, Google/Gemini, xAI/Grok, or OpenRouter.
- Email/phone access for provider login verification.
- A password manager or secure note app if you use API keys.
- No passwords, private keys, health, bank, or customer data in first test prompts.
Step 02
Choose the beginner path
| Path | Use when | SAGE9AI note |
|---|
| Hermes Desktop installer | You want the easiest Windows setup. | Recommended. Start here unless a support person tells you otherwise. |
| Windows native PowerShell installer | You are comfortable with Terminal or Desktop download is unavailable. | Supported fallback. It installs to the same native Windows Hermes area. |
| WSL2 | You specifically need Linux-style development, POSIX terminal behavior, or the dashboard embedded terminal pane. | Supported, but not required for normal Desktop/native Windows use. |
Step 03
Install Hermes Desktop on Windows
Use the official Hermes Quickstart and let the Desktop app do the Windows setup work for you.
- Open the official Hermes Quickstart.
- Follow its Hermes Desktop download link and choose the Windows installer that matches your computer.
- Open the downloaded installer from your browser Downloads list or your Downloads folder.
- If Windows SmartScreen appears, confirm the app came from the official Hermes site. Choose the continue/run option only if the file is the Hermes Desktop installer you intentionally downloaded.
- If Windows asks for permission to make changes or run the app, approve only if you trust the source and started this install yourself.
- After install, launch Hermes Desktop from the Start menu.
Important: do not install WSL first. Do not install Python, Git, Node, or Docker first. The Desktop first-launch setup provisions the dependencies Hermes needs. If something is missing later, Hermes will tell you and can bootstrap it.
Step 04
What first launch may do
The first time Hermes Desktop runs, it may take longer than a normal app because it is preparing the Hermes engine behind the scenes.
| You may see... | What it means | Beginner answer |
|---|
| Installing/provisioning dependencies | Hermes is setting up tools it needs, such as Python, Node, PortableGit, ripgrep, ffmpeg, or browser packages. | Let it finish. This can take several minutes on the first run. |
| Windows Defender or security scan delay | Windows is scanning a newly downloaded app and new tool files. | Wait. If blocked, verify you downloaded from the official Hermes site before allowing it. |
| Provider/model setup | Hermes needs one selected provider and model before it can answer. | Choose one connection you recognize, complete its authentication, and wait for setup to confirm it. |
| ChatGPT/Codex device-code page | The browser asks for a 9-character code that is displayed in a Terminal window. | Leave the browser open, use Alt+Tab or the taskbar to find Terminal, then enter the code exactly, including the hyphen. The Terminal window may be behind Hermes or the browser. |
| Tool or gateway setup | Hermes can connect extra services such as messaging, browser, voice, or gateway features. | Skip extras until one basic chat works. |
| Open new terminal / PATH note | The command-line hermes command may need a new terminal window to appear. | For Desktop users, continue in the app. Only open a new terminal if using the CLI fallback. |
Step 05
Choose your first model/provider
Hermes must be connected to a provider and a live model before it can answer. Choose one supported connection you intend to use, complete only its official authentication flow, and confirm a simple test prompt returns an answer.
| Choice | Beginner guidance | Why |
|---|
| Nous Portal | Select this only if Nous Portal is the connection you intend to authorize. | It is a separate subscription/login path; confirm the billing path before continuing. |
| ChatGPT or Codex subscription | Select the OpenAI/Codex subscription option when that is the access you already use. | Hermes uses a device-code flow: the browser requests the code displayed in Terminal. |
| Other providers | Choose a provider you already understand and can authorize. Follow the exact login, OAuth, or API-key method shown for that provider. | First prove one connection works; add alternatives later. |
| API key | Paste only into the setup prompt/settings field, not into a normal chat. | An API key is a secret and may allow paid usage. |
| Model list | Select a currently offered live model for the provider you authorized. | Model tuning can wait. First goal is one working answer. |
| Multiple providers/fallbacks | Skip for now. | Add backups after your first chat works. |
ChatGPT/Codex device-code security: start this sign-in only when Hermes instructs you to. Open the official browser address shown by the command, enter the one-time 9-character code displayed in Terminal, finish sign-in, and return to Hermes. Never share the code, password, token, or saved authentication files. If the page was unexpected or someone sent you the link, close it. Restart provider setup if the temporary code expires.
Step 06
What to skip during first setup
Hermes can do many things, but a beginner should avoid turning on everything during the first install.
| Feature | Beginner answer | Add later when... |
|---|
| Messaging gateway | Skip. | You want Hermes on Telegram, Discord, Slack, WhatsApp, Signal, Teams, email, etc. |
| Cron/scheduled jobs | Skip. | You have one repeatable task and know when it should run. |
| MCP servers / plugins | Skip. | You know exactly which external app/tool Hermes should connect to. |
| Voice/TTS/STT | Skip. | Text chat works and you want voice as an add-on. |
| Local models/Ollama/LM Studio | Skip unless already installed. | You intentionally want local AI models and understand the hardware limits. |
After the basic chat works, ask Hermes: “Help me add one feature safely. Ask before changing files, connecting accounts, or sending messages.”
Step 07
Verify Hermes works
Open a new chat in Hermes Desktop and ask a safe, practical prompt:
Give me a three-step checklist for organizing tomorrow morning. Ask before changing anything on my computer.
You are done with first install when Hermes answers normally. Do not add gateway, cron, voice, MCP, local models, or messaging until this basic chat works.
Good first signs- Hermes Desktop opens without installer errors.
- You can start a new chat.
- The model/provider test or first prompt returns an answer.
- The answer does not ask you to paste secrets into chat.
Safe next prompts- “Explain what you can do on this computer without changing anything.”
- “Help me create a simple starter workflow, but ask before taking actions.”
- “What should I configure next: tools, model, or messaging?”
Step 08
Beginner Windows notes
| Topic | What to know |
|---|
| Where Hermes lives | Native Windows Hermes data normally lives under %LOCALAPPDATA%\hermes. You do not need to open that folder during beginner setup. |
| Desktop and CLI share setup | After first install, Desktop and the PowerShell-installed hermes CLI share the same native Windows install/data area. |
| WSL2 | WSL2 can coexist with native Windows, but it is a separate Linux environment with separate data. Do not mix paths unless you know which side you are on. |
| Dashboard embedded terminal | Most Hermes features run natively on Windows. The dashboard embedded terminal pane is the main feature that needs WSL2/POSIX behavior. |
| Terminal newline | If you use Hermes CLI later, Ctrl+Enter is the Windows-friendly newline shortcut. Alt+Enter may be captured by Windows Terminal. |
Step 09
If something goes wrong
| Symptom | Try this first |
|---|
| Desktop installer will not run | Close the installer, re-download from https://hermes-agent.nousresearch.com/, and run the newly downloaded installer. Check any Windows security message carefully. |
| Installer seems stuck | Wait several minutes on first launch, especially while dependencies download. If it fails, write down the exact error text or take a screenshot. |
| Provider/model setup is confusing | Choose one supported provider you intend to use and follow only the authentication method Hermes currently shows for it. Skip extra fallback providers until later. |
| API key question appears | Only paste a key into the setup/settings field. Do not paste API keys into normal chats or support messages. |
| Hermes opens but does not answer | Check that a model/provider is selected and authenticated. Try a simple prompt. If billing/key/login failed, fix that before configuring tools. |
| Old instructions say to install WSL first | Treat those as stale for this beginner Desktop path. Native Windows/Desktop is currently supported; WSL2 is optional for specific Linux-style needs. |
Step 10
What to do if you get stuck before Hermes works
Normally, once your agent is operational, the best move is to ask Hermes to help fix Hermes. But during install, Hermes may not be running yet. Use an accessible fallback LLM.
Fallback help path: open ChatGPT, Claude, Gemini, Grok, or another chat LLM you can already access. Tell it exactly what happened and ask how to fix it.
Copy and paste this template into that LLM. Replace the bracketed parts with your details:
I am a complete beginner trying to install Hermes Agent Desktop on Windows.
I downloaded it from https://hermes-agent.nousresearch.com/.
My Windows version is: [Windows 10 or Windows 11]
The step I was on: [download / installer / first launch / provider setup / first chat]
What happened: [copy the exact error message or describe the screen]
What I already tried: [list anything you tried]
Please explain the safest next step in plain English. Do not ask me to paste API keys or passwords.
If you contact a person for help, send the error text or screenshot, but redact passwords, API keys, tokens, email verification codes, and private files.
Pro Tip:Once your basic agent is up and running, it can install, configure, and set up anything else you would like within the agent harness. No need to guess or research how to do it, because your agent already knows. Just ask it. For safety, tell it to explain the plan before making changes, connecting accounts, or sending messages.
Sources checked for this update
Hermes official docs checked: Installation, Platform Support, and Quickstart. Key facts: Desktop is recommended on Windows; native Windows 10/11 on x86_64/aarch64 is Tier 1; the installer provisions dependencies; one provider/model must be verified; ChatGPT/Codex subscription authentication uses a device code.
