Run it
Install Hermes Agent on Windows and WSL
On Windows the install is one command: uv tool install hermes-agent. It leaves three executables and a 116 MB tool directory you can delete at any time; the state you cannot regenerate lives somewhere else, under %LOCALAPPDATA%\hermes. macOS is not tested here, and this page says so instead of guessing.
Two install paths exist for Hermes Agent and we only ran one. This page is the one we ran on 2026-11-19: uv tool install hermes-agent, on Windows 11, into a throwaway tool directory so the whole thing could be deleted afterwards.
It took one command. It produced three executables, a 116 MB tool directory, and it did not touch the installation that was already on the machine. Everything below is copied from that session.
What the command needs before it runs
- Python 3.11 to 3.13. The published package declares
<3.14,>=3.11. uv fetches its own interpreter if the system one is outside that range, which is most of why the install is self-contained. - About 120 MB of disk for the tool directory alone — we measured 116 MB after the install finished.
- A path uv can write to. On Windows that is under your user profile by default; nothing here needs administrator rights.
The install, as we ran it
$ uv tool install hermes-agent
Resolved 64 packages in 1.21s
+ pydantic==2.13.4
+ pywinpty==2.0.15
+ rich==14.3.3
+ uvicorn==0.54.0
+ websockets==15.0.1
+ ...
Installed 3 executables: hermes, hermes-acp, hermes-agent
warning: `...\bin` is not on your PATH. To use installed tools, run
$env:PATH = "...\bin;$env:PATH" or `uv tool update-shell`.
The dependency list is 60-odd lines, so the three above are only there to show what kind of thing comes along: an HTTP stack, a PTY layer, a terminal renderer. Nothing exotic, nothing that needs a GPU.
Read the last two lines first. Three executables, not one — and the bin directory is not on your PATH until you either run uv tool update-shell or call the binary by full path. That warning is the first thing most people meet, and it is not an install failure.
Verify it before you configure anything
$ hermes --version
Hermes Agent v0.19.0 (2026.7.20) · upstream 0d5fdd60 · local 18a76be1 (+26736 carried commits)
Install directory: ...\tools\hermes-agent\Lib\site-packages
Install method: pip
Python: 3.11.15
OpenAI SDK: 2.24.0
Two lines are worth reading twice:
- Install directory — this is the code, and it is wherever your tool manager put it, not where your notes are.
- Install method: pip — uv installed it, and the binary still reports pip. That is the packaging talking, not a mistake; the wheel is a normal Python distribution either way.
If the command is not found, go back to the PATH warning. If it runs but prints nothing, you are on a version that does not implement --version; ours is 0.19.0 and does.
Where it lands, versus where your state lives
This is the split that matters more than any flag:
| What | Where | Can you delete it |
|---|---|---|
| Code + Python environment | uv’s tool directory (uv tool dir prints it; on Windows the default is %APPDATA%\uv\tools) |
Yes — reinstall rebuilds it |
State: config.yaml, skills, cron, profiles |
%LOCALAPPDATA%\hermes |
No — this is the part you back up |
A reinstall is cheap because it only replaces the left column. Deleting the right column is the expensive mistake, and the folder gives you no warning about which files in it are load-bearing — that read is on the install tree page.
One thing we will not claim: we cannot tell you whether %LOCALAPPDATA%\hermes is created by the first run or by the first configuration, because ours existed before this test. Check for it before you assume the install is complete.
The two places this breaks on Windows
Both happen after the install, when you try to script the agent instead of typing at it.
- git-bash translates paths for you, until it does not.
git -C /d/project rev-parse HEADfrom git-bash reaches a native binary that never heard of MSYS and answersfatal: cannot change to '/d/project': No such file or directory. PassD:/projectinstead. Same applies to anything you hand to the agent’s shell tool. - A bare newline does not submit an interactive prompt. When a PTY is involved, sending
\nleaves the child waiting forever; the line terminator it wants is\r. We have sat in front of this for longer than we will admit — if a prompt looks frozen after you typed, that is the reason.
WSL and remote backends
The install itself is the same inside WSL; what changes is how the desktop app finds it. The desktop client does not discover a backend — it reads one file, and the failure it produces looks nothing like the cause. The two-part answer is on Desktop to a WSL backend: what connection.json decides, and the stopped distro that looks like a broken backend.
What we did not test
- macOS. We have not installed it there. If you are on macOS, this page cannot tell you what breaks.
- Android / Termux. No device, so no page — the sites that rank for it have run it, we have not.
- A one-line shell installer. If one exists, we did not use it. The folder layout on the install tree page holds regardless of which path put the files there.
pip installinto a system Python. Same wheel, different resolver — plausible, unmeasured.
What the install actually did, in numbers
One table, all from the same session, each row reproducible with the command beside it:
| Measured | Value | How we got it |
|---|---|---|
| Resolved packages | 64 | uv tool install output, first line |
| Disk used by the tool directory | 116 MB | du -sh on the directory after install |
| Executables installed | 3 (hermes, hermes-acp, hermes-agent) |
uv’s summary line + ls on the bin directory |
| Version reported by the binary | 0.19.0 (build 2026.7.20) | hermes --version |
| Python it actually runs on | 3.11.15 | hermes --version |
| Files left in bin after uninstall | 0 | ls -A after uv tool uninstall |
Re-run the three commands and you should get the same shape; the sizes move between releases, which is why the version is in the table rather than in a sentence. We did not time the install — the wall clock would be a claim about our network, not about the installer.
How you know it worked
Three checks, in this order, and each one fails differently:
$ uv tool list
hermes-agent v0.19.0
- hermes
- hermes-acp
- hermes-agent
$ hermes --version
Hermes Agent v0.19.0 ...
$ ls "$LOCALAPPDATA/hermes"
config.yaml skills cron profiles ...
If uv tool list is empty, the install did not complete. If it lists the package but hermes is not found, it is the PATH line. If both are fine and the folder is missing, you have the code but have not configured it yet — which is a state, not an error.
How to undo it
$ uv tool uninstall hermes-agent
Uninstalled 3 executables: hermes, hermes-acp, hermes-agent
We ran exactly that at the end of the test: the bin directory came back empty and the tool directory was gone. Your state under %LOCALAPPDATA%\hermes survives an uninstall — which is the point — so delete it by hand only after you have read what is in it.
If you installed a different way, the undo is the same sentence with your installer’s verb: remove the package, keep the state folder.
Related
Questions people actually ask
Can I install it without uv?
Probably — the wheel is on PyPI, so `pip install hermes-agent` into a venv should produce the same three executables. We did not run that path, so we are not claiming it works; only the uv path below is measured.
Why are there three executables?
The package declares three entry points: `hermes` (the CLI you will use), `hermes-agent`, and `hermes-acp` for the ACP adapter. We only exercised `hermes`.
Where is the Python environment?
Inside the tool directory uv creates. The shortest way to find it is `hermes --version`, which prints the site-packages path it is actually running from.
Sources
Last checked: 2026-11-19 · 在一次性工具目录里装 → 跑 --version → 卸载,全程留了原始输出;116 MB 是装完后 du 实测;macOS 与 Android 未测