Previous chapters covered what Hermes is, how it differs from chat-based AI tools, and what its interfaces look like. This chapter is about getting it onto a machine so you can use it.
Installing Hermes is different from two things you might be comparing it to:
When you deploy a website, you push code to a hosting platform and the platform serves pages to visitors. The code runs on the platform's servers, not on your machine. You never touch the server directly.
When you install an app on your laptop, you download a finished program. It runs locally, but the app is a closed package — you cannot change how it works, and it cannot install its own tools or run background services on its own.
Installing Hermes is closer to setting up a development environment than either of those. The installer places software on a machine that can execute tools, persist state, and run background services. You end up with a that lives on your hardware, under your control.
That distinction — software that runs on your machine and can act on your behalf — is the whole point. Hermes is not a hosted service. It is a local tool that becomes whatever you configure it to be.
On Linux, macOS, or WSL2 (Windows Subsystem for Linux), open a terminal and run:
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bashOn Windows (native, early beta), open PowerShell and run:
irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iexThat single command does all of the following:
What this does: Git is the only prerequisite. If it is missing, the installer tells you how to install it and exits.
How you know it worked: If the installer proceeds past the first few seconds without an error about missing Git, it found Git on your system.
What this does: uv is a fast Python package and version manager. The installer downloads it automatically if it is not already present.
How you know it worked: You will see a line like 'uv found (0.x.x)' or 'uv installed (0.x.x)' in the installer output.
What this does: Hermes runs on Python 3.11. If you do not have it, uv downloads and manages a standalone Python — no system-wide install needed.
How you know it worked: You will see 'Python found: 3.11.x' or 'Python installed: 3.11.x' in the output.
What this does: Node.js powers the browser automation tools (Playwright). The installer downloads it to ~/.hermes/node/ if it is not already on your system.
How you know it worked: You will see 'Node.js v22.x.x found' or 'Node.js v22.x.x installed' in the output.
What this does: ripgrep provides fast file search. ffmpeg handles voice message transcription. Both are optional but recommended. The installer installs them via your system package manager if possible, or skips them with a manual-install hint if sudo is not available.
How you know it worked: You will see 'ripgrep x.x.x found' and 'ffmpeg x.x.x found', or a note explaining how to install them manually.
What this does: The installer downloads the Hermes source code to ~/.hermes/hermes-agent/ on your machine. It tries SSH first, then falls back to HTTPS.
How you know it worked: You will see 'Cloned via SSH' or 'Cloned via HTTPS' in the output, followed by 'Repository ready'.
What this does: A Python virtual environment isolates Hermes's dependencies from your system Python. Nothing Hermes installs affects other Python programs on your machine.
How you know it worked: You will see 'Virtual environment ready (Python 3.11)'.
What this does: All Python packages Hermes needs are installed inside the virtual environment. Node.js packages (for browser tools) are installed in the repo directory. This step takes the longest — one to five minutes on a fresh install.
How you know it worked: You will see 'All dependencies installed' near the end of the output.
What this does: A launcher script is placed in ~/.local/bin/hermes (or /usr/local/bin/hermes if running as root on Linux). Your shell configuration is updated so the command is available in new terminals.
How you know it worked: You will see 'hermes command ready' and 'Added ~/.local/bin to PATH'.
What this does: The installer creates the ~/.hermes/ directory structure (config, sessions, skills, memory, cron, logs) and seeds template files like .env, config.yaml, and SOUL.md.
How you know it worked: You will see 'Configuration directory ready: ~/.hermes/'.
After the installer finishes, your machine has a new directory structure. Understanding what goes where helps later when you need to back up data, rotate secrets, or troubleshoot problems.
~/.hermes/~/.hermes/hermes-agent/The source code and virtual environment. You rarely need to touch this directly.~/.local/bin/hermesThe launcher command. This is what your terminal runs when you type 'hermes'.~/.hermes/config.yamlMain configuration — model provider, default profile, tool settings.~/.hermes/.envSecrets and API keys. Never share this file. Never commit it to version control.~/.hermes/sessions/Conversation history, stored locally.~/.hermes/skills/Procedural knowledge documents — both bundled and agent-created.~/.hermes/memories/Memory files the agent curates across sessions.~/.hermes/cron/Scheduled job definitions and state.~/.hermes/logs/Operational logs for debugging.~/.hermes/SOUL.mdGlobal personality file — edit this to change how Hermes communicates with you.[Screenshot: Terminal showing the output of ls -la ~/.hermes/ after a fresh install, with directories and config files visible.]
One thing to notice: all of this is in your home directory. Nothing is installed system-wide (unless you ran the installer as root on Linux, which uses an FHS layout with code in /usr/local/lib/hermes-agent/ and the command in /usr/local/bin/hermes). The per-user install keeps things simple and avoids needing administrator access for most operations.
After the installer finishes, you need to configure one critical piece: how Hermes connects to an AI model. Without a model provider and an API key, the agent has no brain to think with.
The easiest way to do this is the setup wizard:
hermes setupThe wizard walks you through three decisions:
What this does: Hermes does not ship with its own AI model. It calls external model providers — services that run large language models and charge per request. You pick which provider to use: Nous Portal, OpenRouter, OpenAI, Anthropic, Google, or any OpenAI-compatible endpoint.
How you know it worked: The wizard lists available providers. After you select one, your config.yaml records the choice.
What this does: Your API key is the credential that lets Hermes make requests to the model provider. It is stored in ~/.hermes/.env — a file that should never be shared, committed, or exposed publicly. The wizard prompts you to paste the key, and saves it automatically.
How you know it worked: After entering the key, the wizard confirms it was saved. You can verify by running 'hermes doctor' later — it checks whether the key is present and reachable.
What this does: The wizard asks which toolsets to enable. Most people start with the defaults (file tools, web search, shell commands). You can change this later with 'hermes tools'.
How you know it worked: The wizard shows enabled toolsets after configuration.
Hermes can run in three environments. The install command is the same everywhere, but what happens after install differs based on where you are. Choose your path below.
Running Hermes on your laptop or desktop
This is the default path and the one this guide recommends starting with. You run the install command on your own machine, and Hermes lives there.
What this is good for
Learning how Hermes works, testing agent configurations, running on-demand sessions where you chat with the agent at the terminal. Easiest to reason about because everything is in front of you.
What changes from a basic install
After install and setup, open a new terminal (so PATH changes take effect) and type hermes. The chat interface opens. Nothing else is required.
Limitation
When your laptop sleeps or loses internet, the agent stops. Gateway and cron services only work while the machine is awake and connected. For always-on services, you need a server (VPS path) or Docker running on a server.
Secrets involved
Your model provider API key in ~/.hermes/.env. If you set up a messaging platform (Telegram, Slack, etc.), its bot token also lives in .env.
How to know it is working
Run hermes doctor. It checks your configuration, API key connectivity, tool availability, and data directory health. If everything passes, you are ready to use the agent.
After install and setup, work through this checklist to confirm everything is in place. Each item tells you what to check and what success looks like.
If any step fails, hermes doctor is your first stop for diagnosis. It checks configuration validity, API key reachability, tool availability, and data directory health. Most issues it catches have a suggested fix right in the output.
[Screenshot: Terminal showing the output of hermes doctor with all checks passing — green checkmarks for config, API key, tools, and data directory.]
There is a distinction worth making explicit because it trips up people coming from hosted AI tools:
Places the Hermes runtime on a machine. The runtime is the same regardless of what you plan to do with it — the same code, the same tools, the same directory layout. Installing once is enough for any number of agent configurations.
Tells the runtime which model to use, which tools to enable, how the agent should behave, and what secrets it needs. Configuration is where you define what your agent actually is — its profile, skills, and personality. This is the creative part, and it continues long after install is done.
The installer handles the first part. The setup wizard bridges into the second. But configuration is an ongoing process — you will adjust profiles, add skills, tweak toolsets, and refine memory long after the initial install. Chapters 8 through 13 cover how to do that well.
You installed Hermes on your laptop and it works. Now you want the agent to receive messages on Telegram while your laptop is closed. What needs to change about your setup?