How-To Guide
Install Hermes Agent: Choose Your Platform, Then Verify One Reply
Install Hermes Agent using the official Windows, macOS or Linux path. Choose Desktop or CLI, check the launcher and provider, and avoid deleting existing agent data.
Quick answer
Choose one installation owner first: a bundled Desktop package or the source CLI installer. On Linux, supported macOS and WSL2, run curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash; on native Windows use iex (irm https://hermes-agent.nousresearch.com/install.ps1). Reload your shell or open a new PowerShell window, run hermes --version and hermes doctor, configure one provider with hermes model, then verify hermes chat -q "Reply with OK. Do not use tools.". A response can incur provider usage charges.
The goal is one working Hermes session, not a stack of partially configured integrations. This runbook follows the official installation documentation, checked October 30, 2026. Commands below are source-verified instructions, not a timed clean-machine installation benchmark. Existing users should start with the safe update guide, not install a second runtime over package-owned files. If you prefer managed browser/mobile access and uptime instead of operating a local runtime, compare FlyHermes pricing.
$49/mo or $39/mo billed yearly · AI included · 14‑day guarantee
Before you start:
- ☑A supported platform and architecture: check the official platform matrix before downloading; current macOS installer support is Apple Silicon, not Intel.
- ☑For the Windows MSIX Desktop package: Windows 11 22H2 or later. The native source script supports Windows 10 and 11.
- ☑For the POSIX source script: Git, curl, tar and SHA-256 utilities. Windows can provision pinned Git if missing.
- ☑Permission to download the selected distribution and dependencies; a source build may require a compiler and platform libraries.
- ☑A provider account or supported local model endpoint. Installing the application does not create model entitlement or credit.
- ☑If Hermes already exists: identify its installation owner, active profile and data home, and back up important state before changing it.
Steps
- 1
Choose Desktop or a source CLI install
For the packaged desktop, download from the official Hermes website. Windows .appinstaller opens in App Installer; macOS DMG installs Hermes.app into Applications. These bundles include the base runtime and prebuilt interfaces. Hermes-Setup is a different bootstrap installer that builds a source installation. Choose one lane rather than running every installer.
- 2
Run the installer for your shell
In Linux, supported macOS or WSL2 use
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash. In native Windows PowerShell useiex (irm https://hermes-agent.nousresearch.com/install.ps1). Both execute downloaded code: inspect the official script first if your policy requires it. Do not paste the Bash command into PowerShell. New source installs default to stable releases; main is an explicit opt-in, not a first-run requirement. - 3
Verify which launcher your terminal uses
On POSIX reload the appropriate shell file, such as
source ~/.zshrcorsource ~/.bashrc, then runcommand -v hermes. On Windows open a new PowerShell window and runGet-Command hermes -All. Then runhermes --version. Multiple Windows candidates can mean a source launcher shadows an MSIX execution alias; use the Windows install recovery guide rather than appending random PATH entries. - 4
Check installation provenance and data paths
Run
hermes doctor,hermes config pathandhermes config env-path. Source code and user data are not the same thing: POSIX defaults to a checkout inside~/.hermes/hermes-agent; Windows defaults to%LOCALAPPDATA%\hermes\hermes-agent. Bundled app files live inside their package. HERMES_HOME overrides user-data location. The profiles guide explains named-profile isolation. Keep path output private when it exposes account names. - 5
Configure one model route
Run
hermes modelorhermes setupand complete the provider login or key prompt locally. Usehermes setup --portalonly if you intentionally choose Nous Portal; it is not FlyHermes. Do not paste API keys into a chat or commit them. Review provider access and costs before assuming a subscription covers every endpoint. - 6
Prove the first response
Run
hermes chat -q "Reply with OK. Do not use tools."in the same installation and profile you configured. Acceptance means the intended launcher reports its version, doctor has no blocking failure, and that profile receives a response. A response from another installed build does not prove Desktop works. A paid model request may cost money; this small prompt is a connectivity check, not a tool-use benchmark. - 7
Add the interface you actually need
After the CLI passes, run
hermes dashboardfor the local browser surface orhermes desktopto add Desktop from a source CLI install. Follow the dashboard setup guide before remote exposure. Native Windows dashboard Chat uses pywinpty/ConPTY; WSL2 uses a POSIX PTY. Neither a dashboard loading nor a CLI answer proves a remote gateway can deliver messages. - 8
Add only one workflow and test its result
Choose one next step: a Docker deployment, a messaging channel or a repository task. Do not add them all before the first response. Verify the exact output or channel reply separately. For ongoing operations, compare self-hosted versus managed responsibility: browser Chat exists in self-hosted Hermes; managed hosting changes who operates it, not whether an agent can ever fail.
- 9
Keep the update owner with the install
Source checkouts use
hermes update; Windows sideload MSIX uses Desktop Update/App Installer; Store packages use Store; macOS bundles use their Desktop updater. Docker updates replace the image while preserving its data mount. Follow the official update ownership table. PM manages dependencies; it is not a substitute application updater.
Pro Tips
- 💡Record installation method, version, chosen profile and the acceptance-test result before adding integrations.
- 💡Bundled Desktop does not build its base runtime on first launch. Source compiler/npm failures belong to a different lane.
- 💡Do not treat a successful first run as proof of unattended uptime, backup coverage or channel delivery.
- 💡WSL2 has a separate Linux filesystem and Hermes home; moving there is a deliberate runtime change, not an automatic Windows fix.
- 💡Use the backup workflow before repairing an existing data home. A profile export alone excludes credentials.
- 💡A package manager command with a similar name is not proof it installs Nous Research Hermes Agent. Verify the official project instead of guessing a Homebrew formula.
Troubleshooting
❌ hermes is missing after install
✅ On POSIX reload your shell and inspect command -v hermes. On Windows open a new PowerShell session and inspect Get-Command hermes -All. Do not reinstall before checking launcher ownership.
❌ Doctor reports a missing managed tool or dependency
✅ Run hermes pm doctor and follow the exact repair printed by the current install. PM owns managed versions; replacing arbitrary system Python or Node versions does not prove that runtime is repaired.
❌ An external or symlinked Hermes home is unavailable
✅ Restore the intended volume or correct the link target and permissions before retrying. Do not delete config or create a substitute local directory just to suppress the error; that can write state to the wrong disk. The official installation guide classifies this as storage availability, not invalid YAML.
❌ The application opens but the model rejects the request
✅ Inspect the actual provider error, selected profile and endpoint. Use the authentication recovery guide. Installing again does not replenish quota or change model entitlement.
❌ Windows Chat alone fails
✅ Current native Chat uses pywinpty/ConPTY. Check doctor and PM diagnostics for the native dependency. Some older WSL/dashboard prose still says POSIX-only; the current Windows feature matrix supersedes that blanket restriction. WSL2 is an alternative, not a mandatory Chat dependency.
❌ Source installer cannot install a Linux system library
✅ Give the exact package-manager command printed by the installer to the administrator. PM provides managed tool binaries, not every distribution library. Do not run the entire agent as root merely to bypass missing system dependencies.
FAQ
How do I install Hermes Agent on Windows?
Choose the bundled Desktop package for Windows 11 22H2 or later, or run the official install.ps1 script in PowerShell for native Windows 10/11 source installation. Open a new terminal, verify launcher/version/doctor, choose a provider and test one reply.
Do I need WSL2 or Docker?
No. Native Windows supports the CLI and dashboard Chat through ConPTY. Choose WSL2 for Linux/POSIX tooling; choose Docker for deliberate container deployment. Both introduce separate filesystem and runtime boundaries.
Can I install Hermes Agent with Homebrew?
Use the current official installation documentation rather than assuming brew install hermes names this project. This guide verifies the official package/script paths, not an independently maintained Homebrew formula.
Why does the first model request fail after installation?
Application installation and model access are separate. Select the intended provider/profile, check credentials, entitlement, balance and endpoint, then repeat one small harmless request.
Will reinstalling erase my memory and sessions?
Application files and user data have different ownership. Back up the intended Hermes home first and repair through the installation owner. Do not delete the data root as an application repair.
When should I use FlyHermes instead?
Choose managed browser/mobile access and uptime if you do not want to own the runtime, updates, networking and gateways. Choose self-hosted Hermes when direct local control matters. Managed operations are not a guarantee that every model or custom workflow succeeds.
Related setup and cost guides
FlyHermes pricing comparison
Compare the managed cloud path against owning a self-hosted Hermes setup.
Hermes Web UI / dashboard
Add browser-based visibility after the CLI smoke test passes.
Hermes Desktop install troubleshooting on Windows
Fix native Windows PATH, proxy, dependency, loading, and WSL2 boundary problems.
Deploy Hermes on a VPS
Use this when you want always-on self-hosting instead of FlyHermes cloud.
Notion integration
Connect workspace automation after the base Hermes install is healthy.