This document explains the installation process for Hermes Agent, detailing installation methods (curl|bash, PowerShell, manual, Nix flake), dependency provisioning, and platform-specific considerations.
Hermes Agent features a zero-configuration, fully automated installer designed to provision its own isolated Python environment and dependencies to guarantee cross-platform compatibility and minimal system interference. The core installation logic is implemented in several key scripts:
scripts/install.sh for POSIX-compliant systems (Linux, macOS, WSL2, Android Termux) scripts/install.sh1-15scripts/install.ps1 for Windows PowerShell environments scripts/install.ps11-13setup-hermes.sh for developers setting up a manual clone setup-hermes.sh1-18The installer automates system detection, dependency management (including the uv Python package manager), Python environment setup, repository cloning, and CLI integration. For advanced users and automated deployments, Hermes also supports a Nix flake and NixOS modules for declarative installation.
The installer executes a structured sequence:
install.sh) or uses PowerShell's built-in capabilities (for install.ps1).uv Package Manager Installation: Provisions uv, a fast Python environment and package manager. On Windows, the script handles false positives from antivirus by providing verification steps.uv if needed scripts/install.sh285-309 scripts/install.ps1132-192git, curl, ffmpeg, and node scripts/install.sh311-399 (for install.sh). On Windows, it bundles a portable MinGit to ensure isolation from system Git.install.sh) or git clone (for install.ps1).uv to create a Python virtual environment and pip-install dependencies, isolating Hermes runtime scripts/install.sh494-529 (for install.sh). Core dependencies are exact-pinned to prevent supply-chain attacks pyproject.toml20-28hermes CLI binary in user local bin paths scripts/install.sh531-569 (for install.sh) or adds to PATH (for install.ps1).hermes setup interactively to finalize configuration scripts/install.sh610-628 (for install.sh) or hermes setup (for install.ps1).Sources: scripts/install.sh210-628 scripts/install.ps172-596 pyproject.toml20-28
Run the POSIX shell install script directly via curl:
This script automatically detects platform specifics. For Termux (Android), it uses standard Python virtual environments (venv) and pip instead of uv due to binary compatibility constraints scripts/install.sh6-7
Use the PowerShell installation command:
The installer handles provisioning uv, Python 3.11, and Node.js. It also manages console encoding to UTF-8 to ensure that progress bars and non-ASCII characters render correctly scripts/install.ps184-89
Sources: scripts/install.sh8-87 scripts/install.ps17-21
Developers can manually clone and set up Hermes using the provided setup script:
The setup-hermes.sh script automates the creation of a .venv using uv (on desktop) or python -m venv (on Termux) and installs the correct dependency set setup-hermes.sh169-182
Sources: setup-hermes.sh1-18 setup-hermes.sh169-182
Hermes Agent supports Nix for reproducible and declarative installs.
pkgs.buildNpmPackage and bundled via esbuild nix/tui.nix9-33pkgs.buildNpmPackage.importNpmLock to resolve Node dependencies offline, ensuring builds are reproducible without network access nix/lib.nix172pythonSrc filters reduce rebuild scope by excluding JS/TS/docs directories from the Python venv derivation nix/lib.nix72-145Sources: nix/tui.nix9-33 nix/lib.nix72-172
The desktop application for Hermes Agent uses a Tauri bootstrap installer. This installer leverages the install.ps1 script on Windows and install.sh on macOS/Linux to provision the core Hermes CLI and its dependencies. The --include-desktop flag is passed to the installer to trigger the desktop app build process scripts/install.ps145-60 scripts/install.sh137
The desktop app build process ensures that a launchable binary is created. For example, on Windows, it can build apps/desktop into a launchable Hermes.exe scripts/install.ps145-59
Sources: scripts/install.ps145-60 scripts/install.sh137
This diagram traces the flow from initial script invocation through system detection and environment setup:
Sources: scripts/install.sh210-628 scripts/install.ps172-596
This diagram associates system names with specific code entities and filesystem locations:
Sources: scripts/install.sh48-58 scripts/install.ps145-60 scripts/install.sh137 nix/lib.nix21-25 nix/tui.nix9-33 hermes_cli/__init__.py21-92
Hermes Agent uses uv to manage its environment and dependency resolution. While specific pins reside in pyproject.toml, the system also relies on a dynamic lazy_deps mechanism for optional integrations.
The system distinguishes between environment-level provisioning and runtime package management:
scripts/install.sh and scripts/install.ps1 using uv to ensure a compatible Python version scripts/install.sh59hermes_cli/managed_uv.py module provides helpers to ensure uv is available at runtime for self-updates and dependency verification hermes_cli/managed_uv.py1-20node and npm. The build process uses esbuild to bundle the TUI into a distributable format nix/tui.nix15-19anthropic, firecrawl-py, exa-py) are lazily installed via tools/lazy_deps.py when a user activates a specific provider or tool tools/lazy_deps.py18-66 Only packages used by every session belong in core dependencies pyproject.toml34-39Hermes includes a built-in update command (hermes update) that manages the git state and environment refresh.
git stash push --include-untracked to prevent merge conflicts and restore them afterwards tests/hermes_cli/test_update_autostash.py59-82package-lock.json by comparing hashes and triggers an npm install if necessary tests/hermes_cli/test_cmd_update.py80-87Sources: scripts/install.sh59 tools/lazy_deps.py18-66 tests/hermes_cli/test_update_autostash.py59-82 tests/hermes_cli/test_cmd_update.py80-87 pyproject.toml34-39
FIRST~1.LAS) to long forms to prevent PowerShell provider errors during build stages scripts/install.ps1109-133tzdata package for IANA timezone support in Python's zoneinfo pyproject.toml93-98pywinpty for native terminal operations and psutil for cross-platform PID management pyproject.toml94-113npmDeps derived from importNpmLock for workspace-wide dependency resolution nix/lib.nix172venv and pip scripts/install.sh6-7Sources: scripts/install.ps184-133 pyproject.toml93-113 nix/lib.nix72-172 scripts/install.sh6-7
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.