How to uninstall Hermes Agent cleanly (Linux, Windows, and Mac)

In 60 seconds: if the CLI still works, run hermes uninstall and choose whether to keep ~/.hermes/ for a future reinstall. Then remove any remaining binary and repo with rm -f ~/.local/bin/hermes and rm -rf ~/.hermes/hermes-agent. If the gateway runs as a managed service, stop it with hermes gateway stop, then disable it with systemctl --user disable hermes-gateway on Linux, launchctl remove ai.hermes.gateway on macOS, or schtasks /Delete /F /TN "Hermes Gateway" on Windows. A full reset, including the virtualenv and Playwright caches, uses rm -rf ~/.hermes ~/.cache/ms-playwright.

Hermes Agent stores components in several filesystem locations. A partial uninstall can leave behind its binary, repo, virtualenv, state, or gateway service. This guide covers the official uninstaller, a manual cleanup, and the service-only path for an orphaned gateway.

Before uninstalling: stop everything

Before running the uninstaller, close anything that might have open handles on the binary or venv:

• Close any open hermes REPL in other terminals.
• Exit Hermes Desktop if you’re using it (Windows / macOS).
• Stop the gateway: hermes gateway stop.

On Windows, hermes.exe stays locked while Hermes Desktop, the gateway, or a Python REPL is using it. Deleting the virtualenv or binary before those processes stop can produce an “access denied” error or a failed rename.

Path 1: use hermes uninstall

If hermes --version responds, this is the recommended path. The uninstaller automatically detects whether you installed in per-user mode or root-mode and cleans what corresponds.

hermes uninstall

At the end of the process, the uninstaller asks:

Keep ~/.hermes/ (config, auth, sessions, skills) for a future reinstall? [Y/n]

• Y (recommended default): keeps ~/.hermes/, which saves you from reconfiguring provider keys, channels, and other settings after a reinstall.
• n: removes ~/.hermes/ entirely, so you start from scratch next time.

After running the uninstaller, you still have the binary at ~/.local/bin/hermes and the repo checkout at ~/.hermes/hermes-agent/. The uninstaller removes them in some cases; if they remain, manual is:

rm -f ~/.local/bin/hermes           # binary symlink
rm -rf ~/.hermes/hermes-agent       # repo checkout
# Optional: remove the venv
rm -rf ~/.hermes/venvs

If you installed in root-mode (sudo):

sudo rm -f /usr/local/bin/hermes
sudo rm -rf /usr/local/lib/hermes-agent

Path 2: remove each component manually

If you prefer to understand each step (servers with audit, custom setups, container cleanup), this is the order.

Step 1: stop the gateway

hermes gateway stop

If it was registered as a managed service:

# Linux
systemctl --user disable hermes-gateway

# macOS
launchctl remove ai.hermes.gateway

# Windows (PowerShell)
schtasks /Delete /F /TN "Hermes Gateway"

Step 2: remove the binary

Per-user (default):

rm -f ~/.local/bin/hermes

Root-mode:

sudo rm -f /usr/local/bin/hermes

Step 3: remove the repo

Per-user:

rm -rf ~/.hermes/hermes-agent

Root-mode:

sudo rm -rf /usr/local/lib/hermes-agent

Step 4: optionally remove the virtualenv

# Per-user
rm -rf ~/.hermes/venvs

# Root-mode
sudo rm -rf /usr/local/lib/hermes-agent/venv

Step 5: optionally remove config, auth, sessions, and skills

If you decided not to keep ~/.hermes/:

# Linux / macOS
rm -rf ~/.hermes

# Windows (PowerShell)
Remove-Item -Recurse -Force "$env:USERPROFILE\.hermes"

Step 6: optionally remove Playwright caches

Chromium stays cached at ~/.cache/ms-playwright/ (Linux/macOS) or %LOCALAPPDATA%\ms-playwright\ (Windows). They weigh ~150-300 MB. If you’re not going to reinstall Hermes soon or want to free up space:

# Linux / macOS
rm -rf ~/.cache/ms-playwright

# Windows (PowerShell)
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\ms-playwright"

Path 3: remove an orphaned service

If you installed without curl | bash (for example cloning the repo and setting up a systemd unit manually), or if the CLI is no longer available but the service is still running:

Stop and disable the service

# Linux
systemctl --user stop hermes-gateway
systemctl --user disable hermes-gateway

# macOS
launchctl unload ~/Library/LaunchAgents/ai.hermes.gateway.plist   # if you have the plist
launchctl remove ai.hermes.gateway

# Windows (PowerShell)
schtasks /Delete /F /TN "Hermes Gateway"

Remove the binary and files

rm -f ~/.local/bin/hermes
rm -rf /path/to/hermes-agent        # the path where you cloned it

And if you configured a custom HERMES_HOME:

unset HERMES_HOME
rm -rf /path/to/your/hermes/home

If you installed via Docker or NixOS

Docker: delete the image and the containers.

docker ps -a | grep hermes         # list containers
docker rm -f hermes-gateway        # remove container (adjust the name)
docker images | grep hermes        # list images
docker rmi hermes-agent:latest     # remove image

NixOS / Nix profile: Nix installations are immutable and managed by generations.

nix profile list | grep hermes     # see what generations exist
nix profile remove hermes-agent    # remove
# Optional: clean old generations
nix-collect-garbage -d

For setups with the NixOS module, remove the module from your configuration.nix and rebuild.

If you installed as a service user without sudo

If you followed the recommended pattern of install without sudo, the service user has ~/.local/bin/hermes and ~/.hermes/. The uninstall is the same as per-user mode, but watch out for the admin:

• The admin who ran sudo npx playwright install-deps chromium can remove those system libraries with apt remove (they’re standard Chromium libraries), but won’t affect other users who don’t need them.
• If you created a system-wide symlink (sudo ln -s /home/hermes/.hermes/hermes-agent/venv/bin/hermes /usr/local/bin/hermes), remember to remove it:

sudo rm -f /usr/local/bin/hermes

Post-uninstall verification

After uninstalling, verify nothing remains:

# macOS / Linux
which hermes                           # should return nothing
launchctl list | grep hermes           # should list nothing
systemctl --user list-units --type=service | grep hermes   # should list nothing
ls -la ~/.hermes 2>/dev/null           # No such file or directory (if you removed config)

# Windows (PowerShell)
Get-Command hermes -ErrorAction SilentlyContinue
Get-ScheduledTask | Where-Object {$_.TaskName -like "*Hermes*"}
Test-Path "$env:USERPROFILE\.hermes"   # False if you removed config

If everything returns empty / False, the uninstall is complete.

Reinstalling later

If you plan to reinstall (for example upgrade to a new version), you can keep ~/.hermes/:

# Stop daemon, keep everything else
hermes gateway stop
hermes uninstall         # answer "Y" to "keep ~/.hermes/"

After reinstalling, the preserved config and skills are already in place. Run hermes doctor to verify the installation.

Before deleting ~/.hermes/, make a copy if it contains custom skills, provider configuration, or sessions you may need later. The other removal steps can be repeated; that state directory is the part you cannot recover after deletion.