bbea5b98b9
platform-support.md already lists "macOS on x86 (Intel) processors" under Unsupported, but the two pages users actually land on don't reflect it: installation.md recommends the macOS installer without qualification, and desktop.md says the app "runs on macOS, Windows, and Linux". Cross-reference the existing policy from both pages so Intel users find it before downloading rather than after "Bad CPU type in executable". No change in platform support is proposed or implied. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
201 lines
11 KiB
Markdown
201 lines
11 KiB
Markdown
---
|
|
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.
|