This page provides a high-level guide for installing and configuring Hermes Agent, from initial setup to your first conversation. Hermes is designed for users who live in the terminal but also offers a robust messaging gateway for external platforms, a TUI, a web dashboard, and a desktop application website/docs/reference/cli-commands.md32-89
Hermes Agent is cross-platform, supporting Linux, macOS, WSL2, native Windows, and Android (via Termux). The primary installation method uses uv for fast Python provisioning and dependency management scripts/install.sh6 scripts/install.ps15
curl | bash installer handles platform-specific setup and dependency provisioning scripts/install.sh9-12 It supports an FHS-style root install layout where code is at /usr/local/lib/hermes-agent and the command is linked to /usr/local/bin/hermes scripts/install.sh180-185venv and pip on Termux, as uv is primarily for desktop/server installs scripts/install.sh6uv to manage a portable Python environment and handles 8.3 short-path normalization for user profiles with spaces scripts/install.ps194-107For details, see Installation.
Sources: scripts/install.sh1-12 scripts/install.ps11-13 scripts/install.ps149-59 website/docs/getting-started/quickstart.md49-78
Hermes stores all user data and settings in the HERMES_HOME directory, which defaults to ~/.hermes/ on POSIX systems scripts/install.sh48 and $env:LOCALAPPDATA\hermes on Windows scripts/install.ps126 Configuration follows a hierarchy where CLI arguments take precedence over file-based settings website/docs/user-guide/configuration.md53-60
Sources: website/docs/user-guide/configuration.md53-64 scripts/install.sh48 scripts/install.ps126
The hermes setup command launches an interactive wizard that configures models and environment settings website/docs/reference/cli-commands.md48 For the easiest path, hermes setup --portal configures a model provider and tool gateway via one OAuth login website/docs/user-guide/configuration.md11-12
| File | Contents |
|---|---|
config.yaml | Non-secret settings (model, terminal, timeouts, feature flags) website/docs/user-guide/configuration.md19 |
.env | API keys and secrets only (API keys, tokens, passwords) website/docs/user-guide/configuration.md20 |
SOUL.md | Primary agent identity and persona website/docs/user-guide/configuration.md22 |
auth.json | OAuth provider credentials (Nous Portal, etc.) website/docs/user-guide/configuration.md21 |
For a full reference of configuration keys and the setup process, see Configuration and Setup.
Sources: website/docs/user-guide/configuration.md7-28 website/docs/getting-started/quickstart.md98-106
Hermes features a multi-provider authentication system that supports OAuth device code flows and traditional API key providers website/docs/integrations/providers.md13-54
~/.hermes/.env for providers such as OpenRouter, Fireworks AI, Google AI Studio, and Anthropic website/docs/reference/environment-variables.md11-74.env files website/docs/user-guide/configuration.md53-64Sources: website/docs/reference/environment-variables.md11-74 hermes_cli/managed_uv.py62-64 website/docs/user-guide/configuration.md53-64
For details on specific provider requirements and OAuth flows, see Authentication and Providers.
Hermes maintains a model catalog and provides tools for model switching without code changes.
hermes model command provides a terminal interface for choosing providers and models website/docs/reference/cli-commands.md41Sources: website/docs/reference/cli-commands.md41 website/docs/user-guide/configuration.md19 hermes_cli/managed_uv.py59-60
For details, see Model Selection and Management.
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.