How to Uninstall Hermes Agent: Step-by-Step Guide

Uninstalling Hermes Agent is not a single operation. You can remove it with one command, delete all files and config, or just disable a lingering service. This guide covers all three paths, plus how to verify the uninstall worked and what to keep if you plan to reinstall later.

Why You're Uninstalling (and What Happens)

Hermes Agent is a local AI tool that runs as a background service or desktop application. When you uninstall it, you have three realistic scenarios:

Scenario 1: You're switching to managed hosting. You want Hermes gone from your machine, config preserved in case you come back. Use Path 1 (easy CLI uninstall). This is also the default if you just want it off your laptop but might reinstall later.

Scenario 2: You're moving to a new machine. You want a complete wipe: no config files, no cache, no service lingering. Use Path 2 (manual file deletion). Export your data first if it matters.

Scenario 3: You uninstalled Hermes, but systemd/launchctl/Task Scheduler still has an entry. The desktop app or CLI is gone, but the OS still tries to start it. Use Path 3 (service-only cleanup). This is common if you installed via package manager or Nix.

Most users are in Scenario 1. If you're not sure, start with Path 1. You can always delete files later.

Before You Start: Stop Everything

Before you uninstall, stop the Hermes Agent process. If you skip this on Windows, the uninstall may fail with a "file is in use" error.

On all platforms: Close the Hermes Agent desktop application if it's running. Look for "Hermes" or "Agent" in your system tray or menu bar and quit it.

On Windows: Stop the Hermes service. Open PowerShell as Administrator and run:

Stop-Service -Name HermesAgent -Force

If that fails (service doesn't exist), move on. Kill the process directly:

Stop-Process -Name hermes -Force
Stop-Process -Name hermes-agent -Force

On macOS: Stop the Hermes launchd service:

launchctl stop com.nousresearch.hermes
launchctl unload ~/Library/LaunchAgents/com.nousresearch.hermes.plist

Then kill any running process:

pkill -f hermes

On Linux: If running as a systemd service:

sudo systemctl stop hermes-agent
sudo systemctl disable hermes-agent

If running as a standalone process:

pkill -f hermes

Choose Your Path

Answer these two questions:

Do you have the hermes or hermes-agent command available in your terminal?

• Yes: You installed via package manager, Homebrew, or pip. Use Path 1 first. If that fails or you want a complete wipe, move to Path 2.
• No: You installed manually, via Docker, or the service is orphaned. Use Path 2 or Path 3.

Do you want to keep your config files (API keys, model settings, model cache)?

• Yes: Use Path 1, or use Path 2 with selective deletion.
• No: Use Path 2 (complete wipe) to delete everything.

Path 1: Easy Uninstall (Preserve Config)

If you have the hermes command, this is the safest path. It removes the application but leaves your configuration directory intact.

Step 1: Verify the command exists.

which hermes

# or
which hermes-agent

If you see a path (e.g., /usr/local/bin/hermes), continue. If you see "not found," skip to Path 2.

Step 2: Run the uninstall command.

On most systems:

hermes uninstall

Some versions require:

hermes-agent uninstall

The command will prompt you to confirm removal. It will also ask if you want to keep or delete your config. Choose "keep" unless you want a fresh start.

Step 3: Check the output.

The command should report:

• "Hermes Agent uninstalled successfully"
• "Configuration preserved at [path]" (if you chose to keep config)
• On Windows: "Service HermesAgent stopped and removed"

If you see "Error: uninstall failed" or "Permission denied," the service may still be running. Go back and re-run the stop commands. Then try uninstall again.

Windows-specific note: GitHub issue #34185 reports that hermes uninstall --full sometimes fails with "Access Denied" on Windows 11. If this happens, skip to Path 2 and manually delete the files. The issue is usually a file lock from Windows Defender scanning the Hermes directory while you're uninstalling.

Path 2: Complete Clean Wipe

Use this if Path 1 failed, if you have no CLI command, or if you want zero trace of Hermes Agent.

On Windows:

Open PowerShell as Administrator. Stop the service first (see "Before You Start").

Then delete the installation directory. Common locations:

# If installed via Windows installer:
Remove-Item -Path "C:\Program Files\Hermes Agent" -Recurse -Force

# If installed via Scoop:
Remove-Item -Path "C:\Users\$env:USERNAME\scoop\apps\hermes-agent" -Recurse -Force

# If installed via Chocolatey:
Remove-Item -Path "C:\ProgramData\Hermes" -Recurse -Force

Then remove config and cache:

# User config:
Remove-Item -Path "$env:APPDATA\HermesAgent" -Recurse -Force
Remove-Item -Path "$env:APPDATA\hermes" -Recurse -Force

# Cache (optional, but recommended for complete wipe):
Remove-Item -Path "$env:LOCALAPPDATA\HermesAgent" -Recurse -Force
Remove-Item -Path "$env:LOCALAPPDATA\hermes" -Recurse -Force

Remove the Windows service entry:

Get-Service -Name HermesAgent -ErrorAction SilentlyContinue | Remove-Service -Force

On macOS:

Remove the application:

rm -rf /Applications/Hermes\ Agent.app
rm -rf /Applications/Hermes.app

Remove config and cache:

rm -rf ~/.config/hermes
rm -rf ~/.cache/hermes
rm -rf ~/Library/Preferences/com.nousresearch.hermes*
rm -rf ~/Library/Caches/com.nousresearch.hermes*

Remove the launchd entry:

rm -f ~/Library/LaunchAgents/com.nousresearch.hermes.plist

On Linux:

Remove the binary and config:

# If installed in /usr/local/bin:
sudo rm -f /usr/local/bin/hermes /usr/local/bin/hermes-agent

# If installed via package manager (apt, dnf, pacman):
sudo apt remove hermes-agent  # Debian/Ubuntu
sudo dnf remove hermes-agent  # Fedora
sudo pacman -R hermes-agent   # Arch

# Remove config:
rm -rf ~/.config/hermes
rm -rf ~/.cache/hermes
rm -rf ~/.local/share/hermes

# If installed as a systemd user service:
rm -f ~/.config/systemd/user/hermes-agent.service
systemctl --user daemon-reload

Path 3: Service-Only Cleanup

Use this if Hermes is already gone, but your OS still tries to start it on boot.

On Windows:

Open Task Scheduler (search "Task Scheduler" in Start menu). Look for a task named "Hermes" or "HermesAgent". Right-click it and choose "Delete."

Alternatively, in PowerShell as Administrator:

Get-ScheduledTask -TaskName *Hermes* | Unregister-ScheduledTask -Confirm:$false

On macOS:

Remove the launchd entry:

launchctl unload ~/Library/LaunchAgents/com.nousresearch.hermes.plist 2>/dev/null
rm -f ~/Library/LaunchAgents/com.nousresearch.hermes.plist
rm -f /Library/LaunchDaemons/com.nousresearch.hermes.plist
launchctl unload /Library/LaunchDaemons/com.nousresearch.hermes.plist 2>/dev/null

On Linux:

Disable and remove the systemd service:

sudo systemctl disable hermes-agent
sudo rm -f /etc/systemd/system/hermes-agent.service
sudo rm -f /etc/systemd/user/hermes-agent.service
sudo systemctl daemon-reload

Special Cases: Docker, NixOS, and Service Users

If you installed Hermes in Docker:

Stop and remove the container:

docker stop hermes-agent
docker rm hermes-agent

Remove the image if you don't plan to use it again:

docker rmi nousresearch/hermes:latest

# or
docker rmi nousresearch/hermes-agent:latest

Clean up volumes (this deletes saved data; be sure you have backups):

docker volume rm hermes_data 2>/dev/null

If you installed Hermes via NixOS:

Edit your configuration.nix or home-manager config. Remove the hermes-agent package from your environment or services block:

# Remove this line:
environment.systemPackages = [ pkgs.hermes-agent ];

Then rebuild:

sudo nixos-rebuild switch

# or (for home-manager):
home-manager switch

If Hermes was installed as a service user (non-root on Linux):

Sometimes Hermes runs under a dedicated user account. Kill the process:

sudo -u hermes pkill -u hermes

Then remove the service:

sudo userdel -r hermes 2>/dev/null

Verify It's Gone

Run these checks to confirm the uninstall is complete.

On all platforms, check for running processes:

# macOS / Linux:
pgrep -i hermes

# Windows (PowerShell):
Get-Process -Name *hermes* -ErrorAction SilentlyContinue

If these return nothing, the process is not running.

Check for the CLI command:

which hermes
which hermes-agent

Both should return "not found" or no output.

On Windows, verify the service is gone:

Get-Service -Name HermesAgent -ErrorAction SilentlyContinue

Should return nothing or "Service does not exist."

On macOS, verify launchd is clean:

launchctl list | grep -i hermes

Should return no lines.

On Linux, verify systemd is clean:

sudo systemctl list-units --all | grep hermes

Should return no lines.

Reinstalling Later?

If you used Path 1 and kept your config, reinstalling is simple. Follow our guide on how to install Hermes Agent to get started again. Your configuration will be restored automatically.

If you used Path 2 (complete wipe), you'll start fresh. That's fine if you're moving to Opsily's managed Hermes hosting instead. You won't need to manage uninstalls or service restarts yourself.

Frequently Asked Questions

How do I stop Hermes Agent without uninstalling it?

Just disable the service. On Linux: sudo systemctl disable hermes-agent and sudo systemctl stop hermes-agent. On macOS: launchctl unload ~/Library/LaunchAgents/com.nousresearch.hermes.plist. On Windows: disable it in Task Scheduler or use Stop-Service -Name HermesAgent. The application stays installed; you can re-enable it anytime.

How do I delete my Hermes agent from my Mac?

The safest way is Path 1: run hermes uninstall if you have the CLI, then choose "keep config" if you might reinstall. Otherwise, use Path 2: remove /Applications/Hermes*.app, delete ~/.config/hermes, ~/.cache/hermes, and ~/Library/Preferences/com.nousresearch.hermes*, then remove the launchd file.

How do I completely uninstall Hermes Agent?

Use Path 2 (complete clean wipe). Stop the service first, then delete the installation directory, config folder, and cache. On Windows, also remove the service entry with Get-Service -Name HermesAgent -ErrorAction SilentlyContinue | Remove-Service -Force. On macOS, delete the .app bundle and launchd file. On Linux, uninstall via package manager, then delete config and systemd service files.

What if the uninstall fails on Windows with "Access Denied"?

This is usually Windows Defender or antivirus scanning the Hermes directory while you're deleting it. Exclude the directory from real-time scanning, then try again. Or, restart in Safe Mode and run the uninstall from there. If that doesn't work, use Path 3 to manually remove files one at a time.

Can I keep my Hermes Agent config without keeping the application?

Yes. If you use Path 1 and choose "keep config," the uninstall preserves your configuration directory. You can also manually backup your config before any uninstall: copy ~/.config/hermes or %APPDATA%\HermesAgent to a safe location. Then you can delete everything else.

How much disk space does Hermes Agent use?

The application itself is 50-100 MB. Model cache can grow to 1-5 GB depending on which models you've downloaded. If you delete the cache folder during uninstall (Path 2), you free all of that space.

Do I need to remove Hermes Agent before upgrading it?

No. The upgrade command (if available) handles in-place updates. If you want to upgrade, run hermes update or reinstall from the Hermes Agent documentation. You only need to uninstall if you want it completely gone.

The Bottom Line

Uninstalling Hermes Agent is straightforward if you know which path you need. Most users want Path 1 (CLI uninstall with config preserved). If that fails or you want a complete wipe, Path 2 handles it. Service lingering? Path 3 cleans it up. Verify the uninstall with the checks above, and you're done.

If you're uninstalling because managing self-hosted Hermes is friction, consider trying Opsily's managed Hermes hosting. No uninstalls. No services to manage. Just deploy and run.