I Packaged Hermes AI into a Windows One-Click Installer

Compressing a 15-step manual installation into a single double-click. Here's how I did it and what I learned. Detailed graphic and textual introduction:https://qinghuanandejiangshi.github.io/

The Problem: "I Don't Know How to Install This"

Hermes Agent has been gaining traction on GitHub lately. It's a fully open-source AI coding assistant that runs entirely locally — no subscriptions, no cloud dependency, just your API key and a terminal.

After using it myself, I wanted to recommend it to a few non-developer friends. The response I got back was predictable:

"I need to set up WSL2 first, then install Ubuntu, then configure a Python environment… this is way too complicated."

They were right. The official documentation is clear and well-written — for developers. But for anyone who hasn't spent time in a terminal, even a handful of commands can be a complete blocker. One unexpected permission prompt, one typo in a path, and the whole process falls apart.

So I decided to build a one-click installer.

Inspiration: The USB Drive Installer Model

Before starting, I came across a similar project: u-claw, which packages OpenClaw (another AI tool) into a USB-drive-friendly installer. The concept is simple and powerful — handle all the complexity in advance, so the user only has to do the last step.

My goal was to do the same for Hermes Agent + Hermes WebUI, targeting Windows specifically, with offline installation support so the whole thing can be distributed on a USB drive.

The Hard Parts

Hermes Agent doesn't support native Windows — it requires WSL2 (Windows Subsystem for Linux). That means the installer needs to:

Enable WSL2 and the VirtualMachinePlatform feature
Install the Ubuntu distribution
Install the uv package manager inside Ubuntu
Use uv to install hermes-agent
Extract and configure hermes-webui with the correct Python environment
Keep a web server running persistently in the background

Each step sounds simple. Each step had at least one non-obvious problem.

Problem 1: WSL Kills Background Processes

The hardest issue was keeping the server alive. When you launch a background process via wsl -d Ubuntu -- bash script.sh, the process gets killed with SIGKILL when the script exits. The user opens their browser, the page loads briefly, then the connection drops.

The fix: use PowerShell's Start-Process to launch a completely separate, hidden WSL window. Combined with bash's exec to replace the shell process with Python, the WSL session stays alive exactly as long as the Python server runs. Closing the installer window has no effect on it.

Problem 2: The Browser Omits the Port in the Origin Header

The WebUI has CSRF protection that compares the request's Origin header against the server's Host header. In theory, both should be 127.0.0.1:8787 — a clean match.

In practice, the browser was sending Origin: http://127.0.0.1 (no port), while the server received Host: 127.0.0.1:8787. They didn't match, so every POST request returned 403.

The cause: a stale browser session from a previous visit had a portless origin cached. The fix was to set the HERMES_WEBUI_ALLOWED_ORIGINS environment variable at startup to explicitly allow both origin variants.

Problem 3: PowerShell 5.1 Compatibility

Windows 10 ships with PowerShell 5.1, which has a few quirks worth documenting:

The .NET Framework 4.x TextBox control doesn't support the PlaceholderText property
PowerShell here-strings use CRLF line endings; bash scripts require LF
$() subexpressions inside WSL command strings get eagerly expanded by PowerShell before reaching bash

Each of these required a workaround: writing commands to temp files, manually converting line endings, explicit escaping.

The Result

After all of that, the installation flow looks like this:

Right-click 一键启动.bat → Run as Administrator
Wait for automatic installation (10–30 minutes depending on network speed)
A GUI dialog appears — enter your API key (DeepSeek recommended; free tier is sufficient for daily use)
Browser opens automatically to http://127.0.0.1:8787

For all subsequent uses: double-click 后续启动.bat. The browser opens in seconds.

Additional features that came out of the process:

Offline mode — place the source ZIPs in resources/ and the installer skips all network downloads
Resumable installation — progress is checkpointed; re-running picks up where it left off
Chinese mirror support — Aliyun PyPI mirror is used automatically, significantly improving download speeds within China

A Thought on Accessibility

This small project got me thinking about something broader: the value of a tool is largely determined by how many people can actually use it.

Hermes Agent is genuinely powerful. But if the installation barrier causes 90% of potential users to give up at step one, its real-world impact is severely limited. Reducing a 15-step process to a single click isn't laziness — it's removing friction that shouldn't be there in the first place.

If you're a developer trying to share AI tools with non-technical colleagues or family members, I hope this project and the approach behind it are useful.

Project: github.com/qinghuanandejiangshi/Hermes-one-clink

Stars and issues welcome ⭐