| --- |
| sidebar_position: 2 |
| title: "Installation" |
| description: "Install Hermes Agent on Linux, macOS, WSL2, native Windows, or Android via Termux" |
| --- |
| |
| # Installation |
|
|
| Get Hermes Agent up and running in under two minutes! |
|
|
| :::tip Platform Support |
| For the full platform support matrix (which OSes, distribution methods, and |
| platform-gated features are supported), see **[Platform Support](./platform-support.md)**. |
| ::: |
|
|
| ## Quick Install |
| ### With the Hermes Desktop installer on macOS or Windows (recommended) |
| To easily install the command-line and desktop applications, [download the Hermes Desktop installer](https://hermes-agent.nousresearch.com/) from our website and run it. |
|
|
| :::note |
| The macOS installer is **Apple Silicon only**. macOS on x86 (Intel) processors is [not a supported platform](./platform-support.md#unsupported). |
| ::: |
|
|
| ### Without Hermes Desktop: |
| For a command-line only install without Hermes Desktop, run: |
|
|
| #### Linux / macOS / WSL2 / Android (Termux) |
| ```bash |
| curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash |
| ``` |
|
|
| #### Windows (native) |
|
|
| Run in powershell: |
| ```powershell |
| iex (irm https://hermes-agent.nousresearch.com/install.ps1) |
| ``` |
|
|
| If you want to install & run Hermes Desktop after a command-line only install, simply run |
| ```bash |
| hermes desktop |
| ``` |
|
|
| ### What the Installer Does |
|
|
| The installer handles everything automatically — all dependencies (Python, Node.js, ripgrep, ffmpeg), the repo clone, virtual environment, global `hermes` command setup, and LLM provider configuration. By the end, you're ready to chat. |
|
|
| #### Install Layout |
|
|
| Where the installer puts things depends on whether you're installing as a normal user or as root: |
|
|
| | Installer | Code lives at | `hermes` binary | Data directory | |
| | -------------------------------------- | ------------------------------ | --------------------------------------- | ------------------------------------ | |
| | Per-user (git installer) | `~/.hermes/hermes-agent/` | `~/.local/bin/hermes` (symlink) | `~/.hermes/` | |
| | Root-mode (`sudo curl … \| sudo bash`) | `/usr/local/lib/hermes-agent/` | `/usr/local/bin/hermes` | `/root/.hermes/` (or `$HERMES_HOME`) | |
|
|
| The root-mode **FHS layout** (`/usr/local/lib/…`, `/usr/local/bin/hermes`) matches where other system-wide developer tools land on Linux. It's useful for shared-machine deployments where one system install should serve every user. Per-user config (auth, skills, sessions) still lives under each user's `~/.hermes/` or explicit `HERMES_HOME`. |
|
|
| ### After Installation |
|
|
| Reload your shell and start chatting: |
|
|
| ```bash |
| source ~/.bashrc # or: source ~/.zshrc |
| hermes # Start chatting! |
| ``` |
|
|
| To reconfigure individual settings later, use the dedicated commands: |
|
|
| ```bash |
| 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 to configure everything at once |
| ``` |
|
|
| :::tip Fastest path: Nous Portal |
| One subscription covers 300+ models plus the [Tool Gateway](/user-guide/features/tool-gateway) (web search, image generation, TTS, cloud browser). Skip the per-tool key juggling: |
|
|
| ```bash |
| hermes setup --portal |
| ``` |
|
|
| That logs you in, sets Nous as your provider, and turns on the Tool Gateway in one command. |
| ::: |
|
|
| :::tip Already running Hermes on another machine? |
| You don't need to rebuild your setup from scratch. Restore a full backup with `hermes import` (see [Exporting Hermes to another machine](/reference/faq#exporting-hermes-to-another-machine)), or bring over a single agent with `hermes profile import` (see [Moving a single profile to another machine](/reference/faq#moving-a-single-profile-to-another-machine)). Note that a profile export excludes credentials by design, so an export alone is not a full backup — [`hermes backup` vs `hermes profile export`](/reference/faq#hermes-backup-vs-hermes-profile-export) explains which to use. |
| ::: |
|
|
| --- |
|
|
| ## Prerequisites |
|
|
| **Installer:** On non-Windows platforms, the only prerequisite is **Git**. On Linux, also make sure `curl` and `xz-utils` are available (the installer downloads Node.js as a `.tar.xz` archive). The desktop app additionally requires `g++` (or `build-essential` on Debian/Ubuntu) to compile native modules. The installer automatically handles everything else: |
|
|
| - **uv** (fast Python package manager) |
| - **Python 3.11** (via uv, no sudo needed) |
| - **Node.js v26** (for browser automation and WhatsApp bridge; existing system Node 22.22+, 24.11+, or 26+ is used as-is) |
| - **ripgrep** (fast file search) |
| - **ffmpeg** (audio format conversion for TTS) |
|
|
| :::info |
| You do **not** need to install Python, Node.js, ripgrep, or ffmpeg manually. The installer detects what's missing and installs it for you. Just make sure `git` is available (`git --version`). On Linux, ensure `curl` and `xz-utils` are installed (`sudo apt install curl xz-utils` on Debian/Ubuntu). For the desktop app, also install `build-essential` (`sudo apt install build-essential`). |
| ::: |
|
|
| :::tip Nix users |
| Nix is **no longer an explicitly supported install path** (best-effort only). If you already use Nix (on NixOS, macOS, or Linux), there's a dedicated setup path with a Nix flake, declarative NixOS module, and optional container mode. See the **[Nix & NixOS Setup](./nix-setup.md)** guide. |
| ::: |
|
|
| --- |
|
|
| ## Manual / Developer Installation |
|
|
| If you want to clone the repo and install from source — for contributing, running from a specific branch, or having full control over the virtual environment — see the [Development Setup](../developer-guide/contributing.md#development-setup) section in the Contributing guide. |
|
|
| --- |
|
|
| ## Non-Sudo / System Service User Installs |
|
|
| Running Hermes as a dedicated unprivileged user (e.g. a `hermes` systemd service account, or any user without `sudo` access) is supported. The only thing on the install path that genuinely needs root is Playwright's `--with-deps` step, which `apt`-installs shared libraries (`libnss3`, `libxkbcommon`, etc.) used by Chromium. The installer detects whether sudo is available and gracefully degrades when it isn't — it will install the Chromium binary into the service user's own Playwright cache and print the exact command an administrator needs to run separately. |
|
|
| **Recommended split (Debian/Ubuntu):** |
|
|
| 1. **One time, as an admin user with sudo**, install the system libraries Chromium needs: |
| ```bash |
| sudo npx playwright install-deps chromium |
| ``` |
| (You can run this from anywhere — `npx` will fetch Playwright on the fly.) |
|
|
| 2. **As the unprivileged service user**, run the regular installer. It will detect the missing sudo, skip `--with-deps`, and install Chromium into the user's local Playwright cache: |
| ```bash |
| curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash |
| ``` |
|
|
| If you want to skip the Playwright step entirely — for example because you're running headless and don't need browser automation — pass `--skip-browser`: |
| ```bash |
| curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --skip-browser |
| ``` |
|
|
| The installer also pre-installs [`cua-driver`](../user-guide/features/computer-use.md) so the Computer Use toolset works the moment you enable it; pass `--skip-computer-use` to opt out (it will then install on demand when you enable the tool). |
|
|
| 3. **Make `hermes` available to the service user's shells.** The installer writes the launcher to `~/.local/bin/hermes`. System service accounts often have a minimal PATH that doesn't include `~/.local/bin`. Either add it to the user's environment, or symlink the launcher into a system location: |
| ```bash |
| # Option A — add to the service user's profile |
| echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc |
| |
| # Option B — symlink system-wide (run as an admin) |
| sudo ln -s /home/hermes/.hermes/hermes-agent/venv/bin/hermes /usr/local/bin/hermes |
| ``` |
|
|
| 4. **Verify:** `hermes doctor` should now run cleanly. If you get `ModuleNotFoundError: No module named 'dotenv'`, you're invoking the repo source `hermes` file (`~/.hermes/hermes-agent/hermes`) with system Python instead of the venv launcher (`~/.hermes/hermes-agent/venv/bin/hermes`) — fix step 3. |
|
|
| 5. **Running the messaging gateway from this account?** A user-level service stops at logout and does not start at boot until you enable lingering for the service user: |
|
|
| ```bash |
| sudo loginctl enable-linger <service-user> |
| ``` |
|
|
| See [Messaging Gateway](/user-guide/messaging/) for the service setup itself. |
|
|
| The same pattern works on Arch (the installer uses pacman with the same sudo-detection logic), Fedora/RHEL, and openSUSE — those distros don't support `--with-deps` at all, so an administrator always installs the system libraries separately. The relevant `dnf`/`zypper` commands are printed by the installer. |
|
|
| --- |
|
|
| ## Troubleshooting |
|
|
| | Problem | Solution | |
| |---------|----------| |
| | `hermes: command not found` | Reload your shell (`source ~/.bashrc`) or check PATH | |
| | `API key not set` | Run `hermes model` to configure your provider, or `hermes config set OPENROUTER_API_KEY your_key` | |
| | Missing config after update | Run `hermes config check` then `hermes config migrate` | |
|
|
| For more diagnostics, run `hermes doctor` — it will tell you exactly what's missing and how to fix it. |
|
|
| ### 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. |
|
|
| ## Install method auto-detection |
|
|
| Hermes auto-detects whether it was installed via the git installer, Docker, or NixOS, and `hermes update` prints the matching update command for that path. There's no env var to set — the detection is based on the install layout (`~/.hermes/hermes-agent/` checkout, Docker image stamp, or Nix store path). `hermes doctor` also surfaces the detected method under its environment summary. |
|
|
