Welcome to the Easiest Install You'll Ever Do | Easy Understand Hermes Agent

Welcome to the Easiest Install You’ll Ever Do

If you’ve been putting off trying Hermes Agent because you’re worried about a painful setup, stop right there. The new installer does almost everything for you. In fact, if you can copy and paste a single command, you’re about two minutes away from chatting with your new AI assistant.

Let’s walk through the whole thing, step by step.

Install Commands at a Glance

Every supported install path, the command it runs, and what it needs first:

Platform	Install method	Command / file	Needs before you start
macOS / Windows	Hermes Desktop package	Open the `.appinstaller` (Windows) or the DMG (macOS)	macOS build is Apple Silicon only
Linux / macOS / WSL2	One-line source script	`curl -fsSL https://hermes-agent.nousresearch.com/install.sh \| bash`	Git, curl, tar, SHA-256 utilities
Native Windows	PowerShell script	`iex (irm https://hermes-agent.nousresearch.com/install.ps1)`	PowerShell
Android (aarch64)	Signed Termux APT package	`pkg install hermes-agent` after adding the signed repo	Standard Termux app — not `install.sh`
Any install	Add the desktop app later	`hermes desktop`	—

You never install Python, Node.js, ripgrep or FFmpeg by hand: the installer clones the source, bootstraps uv, and handles all of them for you.

The Absolute Fastest Way: Hermes Desktop

If you’re on macOS or Windows, the easiest route is to grab the Hermes Desktop package from our website.

Windows: open the .appinstaller download with Windows App Installer. It installs the signed MSIX bundle and records its update source. Microsoft Store packages have separate Store ownership.
macOS: open the DMG, then copy Hermes.app to Applications. The ZIP artifact carries the signed app used by the automatic updater.

Bundled packages contain the agent, Python, supported dependencies, and prebuilt interfaces, so the first launch does not build that base runtime. Provider access and optional integrations can still require network access.

One thing to know: the macOS installer is Apple Silicon only. Intel Macs aren’t a supported platform.

A Hermes-Setup bootstrap installer is different: it downloads a source installation and builds the desktop app. See Hermes Desktop for details.

There is no separate remote-only Desktop download. To use Desktop with a Hermes backend on another machine, install one of the packages above and connect it from Settings → Gateways; see Connecting to a remote backend.

Command-Line Only? One Line Does It

Prefer to stay in the terminal? No problem.

On Linux, macOS, or WSL2:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

A new install lands on the latest stable release, the channel hermes update follows from then on. To install the tip of main instead, pass --channel main on POSIX or -Channel main on Windows (or set HERMES_INSTALL_CHANNEL=main first, for the one-liners).

On native Windows (PowerShell):

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

That’s it. Seriously. If you change your mind later and want the desktop app too, just run:

hermes desktop

On Android (Termux): use the Termux APT package on aarch64 devices. Configure its signed repository before running pkg install hermes-agent. The desktop/server scripts are not the Termux installation path.

What the Installer Does for You

Here’s the part that used to be a headache: dependencies. The installer now handles everything automatically. The scripts clone the source, bootstrap uv, and delegate dependency preparation to PM, which provides pinned Python, Node.js, npm, ripgrep, and FFmpeg. The source installation selects the all Python extra, not every optional extra. You don’t need to manually install Python, Node.js, ripgrep, or ffmpeg. It detects what’s missing, installs it, wires up the global hermes command, and even helps with your LLM provider configuration.

PM also installs the browser and computer-use tools by default: a pinned Chromium (Chrome for Testing) that Hermes launches for local browsing, plus cua-driver (the computer-use driver, on macOS, Windows and glibc Linux). If a download fails, the install still completes and prints the command to retry. The browser driver behind browser_exec (browser-harness, the engine of the Browser Use CLI) is a regular Python dependency, so every install — the Desktop app included — already has it. Where PM has no Chromium build (Android/Termux, musl Linux), Hermes uses a system chromium on PATH instead. Other optional tools use their feature-specific installation paths.

To leave the browser tools out, pass --skip-browser on POSIX or -SkipBrowser on Windows; for the computer-use driver, use --skip-computer-use / -SkipComputerUse. Hermes remembers these choices: later installs and hermes update do not add them back. Run hermes pm install chromium or hermes pm install cua-driver to install them and undo the choice.

The scripts create a launcher and prepare the data directory. Interactive runs also invoke setup and gateway configuration. --non-interactive on POSIX, or -NonInteractive on Windows, skips stages that need input. The optional --include-desktop / -IncludeDesktop stage builds the desktop from source.

On a terminal the scripts show one status line per step and write the output of git, uv and the builds to logs/install.log under the Hermes data directory; a failed step prints its last lines and the log path. CI (CI or GITHUB_ACTIONS set), redirected output, --verbose / -Verbose or HERMES_INSTALL_VERBOSE=1 stream everything instead.

By the time it finishes, you’re ready to chat.

Where Everything Goes

Depending on how you install, the files land in different places:

Method	Code	CLI entry point	Default user data
POSIX source script	`~/.hermes/hermes-agent/`	`~/.local/bin/hermes` wrapper	`~/.hermes/`
Windows source script	`%LOCALAPPDATA%\hermes\hermes-agent\`	`%LOCALAPPDATA%\hermes\bin\`	`%LOCALAPPDATA%\hermes\`
Desktop bundle	Inside the installed app package	Packaged launchers; Windows execution aliases	Platform default Hermes data directory
Docker	`/opt/hermes/`	Image entrypoint and `hermes` shim	Mounted `/opt/data/`
Termux APT	`$PREFIX/lib/hermes-agent/`	Symlinks in `$PREFIX/bin/`	`~/.hermes/`

HERMES_HOME selects user data. The POSIX script’s --dir selects its source checkout independently. Windows provides -HermesHome and -InstallDir. Running the POSIX script as root does not select an automatic FHS layout: it uses root’s home unless you provide an explicit source path.

PM’s tool store and per-install Python generations have separate lifetimes. See Package management for their locations. Do not remove the data root to repair an application installation.

After Installation: Start Chatting

Once the installer finishes, reload your shell and go:

source ~/.bashrc   # or: source ~/.zshrc
hermes             # Start chatting!

Tweak Things Later (Without Reinstalling)

Want to change your model, enable different tools, or connect a messaging platform? There are dedicated commands for that:

hermes model          # Choose your LLM provider and model
hermes tools          # Configure which tools are enabled
hermes gateway setup  # Set up messaging platforms
hermes config set     # Set individual config values
hermes config get     # Inspect individual config values
hermes setup          # Or run the full setup wizard

The Fastest Path: Nous Portal

Here’s a pro tip. Instead of juggling API keys for every single tool, use the Nous Portal. One subscription covers 300+ models plus the Tool Gateway (web search, image generation, TTS, cloud browser). To set it all up in one shot:

hermes setup --portal

That logs you in, sets Nous as your provider, and turns on the Tool Gateway. Done.

Moving From Another Machine?

Don’t rebuild everything from scratch. Use hermes import to restore a full backup, or hermes profile import to bring over a single agent. Just remember: a profile export doesn’t include credentials by design, so for a true backup, use hermes backup.

What You Need Beforehand (Almost Nothing)

For the POSIX source script, provide Git, curl, tar, and SHA-256 utilities. Windows can bootstrap its pinned Git for Windows archive when Git is absent. The script always downloads its verified uv pin; a uv already on your PATH is never used.

Current first-party installations run on Python 3.14. The broader >=3.11,<3.15 range in pyproject.toml lets older Python installations run the updater before PM switches them to 3.14; it does not promise current runtime support on 3.11–3.13. PM selects the managed tool versions from pm/lock.json; it does not adopt arbitrary system Node versions as the installed runtime.

Source builds can require a native compiler and platform development libraries. Building Electron from source adds Node native-module requirements. These build prerequisites do not apply to installing a complete desktop package. Linux Chromium also requires system libraries supplied by the distribution.

On glibc Linux, the managed Node.js links libatomic.so.1, which minimal Debian, Ubuntu and RHEL-family images do not ship. When the library is missing, the installer and hermes update install the distro package (libatomic1 on apt and zypper, libatomic on dnf/yum and apk, gcc-libs on pacman). They run the package manager directly as root, or as sudo -n otherwise. An interactive run asks for your sudo password once, before installing dependencies. --non-interactive runs never prompt. If the install cannot run, the error names the exact command for the package manager it found.

The current source installer does not run Playwright’s --with-deps step. Apart from Node.js’s libatomic (see above), it does not install system packages. PM manages tool binaries; the administrator supplies system libraries. A service user without sudo gets the exact libatomic command to ask an administrator to run.

That’s it. No manual Python, no manual Node.js, no manual anything. The installer handles it all.

A Note for Nix Users

Nix is no longer an explicitly supported install path (best-effort only). If you’re already using Nix, there’s a dedicated setup guide with a flake and NixOS module. Check the Nix & NixOS Setup guide for details.

Symlinked Home Directories and External Storage

Hermes supports a symlinked HERMES_HOME and symlinked home subdirectories, including hooks, skills, sessions, and logs. During home initialization, existing directory links are preserved, and permissions on linked directories (and descendants such as logs/curator) are left to their owner.

If a link target is missing, inaccessible, or not a directory, initialization stops with a storage error naming the path and link target. Hermes does not replace the link or create its missing target: doing so could write data onto the local disk while an external or NAS volume is unmounted. Check the reported link, restore the mount or correct its target, and verify access permissions before retrying. For a deliberately new dotfiles target, create it yourself only after confirming the intended storage is available.

hermes doctor reports these failures as storage problems, not invalid YAML. Keep your existing config.yaml; running hermes setup is not the repair for an unavailable directory. This is a directory-availability check, not a mount monitor: an existing directory cannot establish that the intended volume is mounted.

Wrapping Up

That’s the whole story. One command, a couple of minutes, and you’re chatting with Hermes. No more dependency hell, no more manual configuration. Go give it a try — you’ll be glad you did.

Keep reading: Hermes on NixOS — On a declarative system? See Hermes on NixOS for the flake input and the NixOS module.