Installation and Hosting

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 a runtime is fundamentally different from two things you might compare it to. Deploying a website means pushing code to a hosting platform — the code runs on their servers, not yours. Installing a desktop app means downloading a closed package — it runs locally, but you cannot change how it works or have it run background services on its own.

Installing Hermes is closer to setting up a development environment. You end up with software on your hardware that can execute tools, persist state, and run background services — under your control, on your machine. That distinction is the whole point: Hermes is not a hosted service. It is a local tool that becomes whatever you configure it to be.

Step 1

Run the install command

On Linux, macOS, or WSL2, open a terminal and run:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

On Windows (native, early beta), open PowerShell:

irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex

One command does all of the following. Watch for each confirmation line in the terminal output:

• •Checks for Git — Only prerequisite. If missing, the installer tells you how to install it and exits.
• •Installs uv — Fast Python package manager. Auto-downloaded if not present.
• •Installs Python 3.11 — Managed by uv — no system-wide install needed.
• •Installs Node.js v22 — Powers browser automation tools (Playwright). Downloaded to ~/.hermes/node/.
• •Installs ripgrep & ffmpeg — Optional but recommended. Installed via system package manager if sudo is available, skipped with a manual-install hint otherwise.
• •Clones the repo — Downloads source to ~/.hermes/hermes-agent/. Tries SSH first, falls back to HTTPS.
• •Creates a virtual environment — Isolates Hermes dependencies from your system Python. Nothing Hermes installs affects other programs.
• •Installs Python & Node dependencies — The longest step — one to five minutes on a fresh install.
• •Sets up the hermes command — Launcher script in ~/.local/bin/hermes. PATH updated for new terminals.
• •Creates config directories — ~/.hermes/ structure: config, sessions, skills, memory, cron, logs. Seeds .env, config.yaml, and SOUL.md templates.

If the installer requests sudo, it is only for optional system packages (ripgrep, ffmpeg). The core install works without elevated privileges. Decline sudo and those tools are skipped — file search uses a slower fallback, voice transcription won't work, but everything else runs fine.

Step 2

Run the setup wizard

After the installer finishes, you need to tell Hermes how to reach an AI model. Without a model provider and API key, the agent has no brain to think with.

hermes setup

The wizard walks you through three decisions:

1. Choose a model provider — Hermes calls external model providers (Nous Portal, OpenRouter, OpenAI, Anthropic, Google, or any OpenAI-compatible endpoint). Your choice is recorded in config.yaml. Switch any time with hermes model.
2. Enter your API key — Stored in ~/.hermes/.env. Never share or commit this file. Verify with hermes doctor.
3. Configure tools — Start with defaults (file tools, web search, shell commands). Change later with hermes tools.

Deployment

Where to install: local, VPS, or Docker

The install command is the same everywhere. What differs is what happens after install — and that depends on what you need the agent to do. Start local. Move to VPS when you need always-on services. Add Docker when you want reproducibility or isolation.

Key Distinction

Hosting the agent ≠ hosting the thing it works on

Hermes is a worker, not a website. If you have an agent that edits your website, the website still needs its own hosting (Netlify, Vercel, GitHub Pages). Hermes does not replace that. It is the worker that makes changes, opens pull requests, runs tests, and deploys — but the product it works on lives where it has always lived.

Key Distinction

Installing the runtime vs configuring the agent

Installing places the runtime on a machine — the same code, tools, and directory layout regardless of what you plan to do with it. Configuring tells the runtime which model to use, which tools to enable, and how the agent should behave. The installer handles the first part. The setup wizard bridges into the second. But configuration is ongoing — you will adjust profiles, add skills, and refine memory long after the initial install.

Step 3

Verify your installation

Work through this checklist after install and setup. If any step fails, hermes doctor is your first stop for diagnosis.

Safety

What applies everywhere, regardless of path

Some rules are the same no matter where Hermes runs. These are the ones that catch people off guard:

• •Never commit .env to version control — Add it to .gitignore in every project that touches ~/.hermes/. A private repo is still a secret leak waiting to happen.
• •Do not run two agents on the same ~/.hermes/ directory simultaneously — Concurrent writers can corrupt session history and cron state. Use separate profiles (which isolate data) or separate directories.
• •Back up before updating — Copy .env and config.yaml to a safe location before running hermes update. A config format change could break your setup; a backup lets you roll back in minutes.
• •Lock down approvals on servers — For unattended gateway or cron, use smart approval mode (auxiliary LLM assesses risk) or restrict the toolset so dangerous commands cannot run. Chapter 13 covers this in detail.
• •Monitor disk space — Session logs and cron output accumulate. On a VPS with limited storage, an unchecked log directory fills the disk silently. Enable the disk-cleanup plugin shipped with Hermes.