.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
The official Hermes Agent installer is a single curl command that, on a clean Ubuntu box, takes about 90 seconds and leaves you with a working hermes binary. That's the happy path.
The unhappy path is when the script fails halfway through, drops a partial install in ~/.hermes and leaves you wondering what to undo.
This guide covers both, plus the bits the README skips: where the files land, how to put hermes on your PATH if the installer's PATH-edit step misses your shell and the manual install steps if you'd rather not pipe a script straight from GitHub into bash.
Everything below is written against the v0.12 series of Hermes Agent, which is the line that landed in late April 2026. The CLI surface and install layout have been stable since v0.10. If you're reading this on a much newer release the broad shape will be the same, but check hermes --version after install to confirm.
Skipping all of this with the LumaDock 1-click template
If you'd rather not deal with prerequisites, PATH edits or post-install verification, the LumaDock Hermes Agent VPS template ships with the install already done on Ubuntu 24.04. You pick a plan, the server boots with hermes on the PATH, the data directory pre-created and the systemd unit ready to start. For people running Hermes for personal use, that takes you from "let me read the install script first" to "the agent is online" in about three minutes. The rest of this article is for everyone else.
What you need on the server before you start
Hermes assumes a Linux box with a normal user account and outbound HTTPS. The installer is happy on Ubuntu 22.04, 24.04 and 26.04. Debian 12 and 13 work too, the steps are identical. AlmaLinux and Rocky users need to swap the apt commands for dnf, but the installer itself is distro-aware and handles that automatically.
One real prerequisite the docs are quiet about: Git. The installer clones the repo into ~/.hermes/hermes-agent/ and will refuse to run without git available. On a fresh Ubuntu Server image, that's sudo apt update && sudo apt install -y git curl ca-certificates. The other tools the script needs (uv, Python 3.11, Node.js v22, ripgrep, ffmpeg) are installed by the script itself, so you don't have to bring them.
For storage, plan for at least 3 to 5 GB free under your home directory. The Python virtualenv plus Node modules plus a few hundred MB of skill content adds up faster than you'd think. If you're on a tight VPS and /home is a small partition while /var has more room, set HERMES_HOME before running the installer to redirect the data dir.
Run the installer
The official one-liner is the same on every supported platform:
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bashIf you're allergic to curl | bash, fair enough. Pipe it to a file first, read it, then run it:
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh -o /tmp/hermes-install.sh
less /tmp/hermes-install.sh
bash /tmp/hermes-install.shThe script does roughly five things in order. It detects your OS and shell. It installs uv (the Python package manager Astral builds, which is what Hermes uses to manage its venv). It clones NousResearch/hermes-agent into ~/.hermes/hermes-agent/. It creates a Python 3.11 virtualenv under that clone and runs uv pip install against the repo. Finally it writes a wrapper script to ~/.local/bin/hermes and edits your shell rc files (~/.bashrc, ~/.zshrc, etc.) to put ~/.local/bin on your PATH if it isn't already.
That last step is the one that breaks for people. If you're running the installer inside tmux, over an SSH session that doesn't source .bashrc on connect or under a shell that the installer doesn't recognize (looking at you, fish), the PATH edit either gets written to a file you don't read or doesn't get written at all. The fix is to either log out and back in or run source ~/.bashrc manually or just add export PATH="$HOME/.local/bin:$PATH" to the shell rc file you use.
Where Hermes puts its files
Hermes uses two install layouts. The script picks one at install time based on which user ran it.
The per-user layout is the default and it's what most VPS deployments end up with. Code lives under ~/.hermes/hermes-agent/ (the repo clone plus its venv at .venv/). Data lives directly under ~/.hermes/: that's where you'll find config.yaml, .env, the memories/ directory holding MEMORY.md, USER.md and SOUL.md, the skills/ directory and the state.db SQLite file that holds session history. The CLI wrapper is at ~/.local/bin/hermes.
The root / FHS layout is what you get if you run the installer as root with HERMES_FHS=1 set or if you're packaging Hermes for system-wide use. Code lands at /usr/local/lib/hermes-agent/, the binary at /usr/local/bin/hermes and data goes wherever HERMES_HOME points (usually /var/lib/hermes or /root/.hermes if you didn't set it).
Most single-user VPS setups should stick with the per-user layout. It's simpler, the file permissions are always sane and updates via hermes update work without sudo. The FHS layout is worth using only if you need multiple Linux users on the same box to share a single Hermes install, which is rare in practice.
Pick a provider on first run
With hermes on your PATH, run hermes setup. The wizard offers two routes on first run: Quick setup (provider, model and messaging in a tight five-minute flow, recommended for most people) or Full setup (everything, including the optional knobs you probably won't touch on day one). Pick Quick. You can come back to the rest later.
On a LumaDock Hermes Agent VPS you'll see a similar five-option first-login menu before hermes setup even runs. The Hermes Agent VPS setup guide in our knowledge base walks through that menu and the web dashboard route in detail; come back here when you're ready for the manual install path or the deeper-dive bits.
The provider picker shows the full list with quick descriptions. If you're new to all this, the easiest path is the Nous Portal option. It uses OAuth, so you don't paste an API key and it includes free access to the Xiaomi MiMo v2 Pro model which is good enough for most agentic work and won't bill you a cent for personal use. The MiMo free tier is rate-limited rather than dollar-limited, so you can lean on it heavily without worrying about cost shock.
If you want a bigger model for harder reasoning, the second-easiest path is OpenRouter with an API key, which gives Hermes access to 200+ models from Claude to GPT-5 to local-style open weights. You set OPENROUTER_API_KEY in ~/.hermes/.env and pick a model with hermes model or the in-CLI /model openrouter:anthropic/claude-3.7-sonnet command.
One thing worth knowing before you go any further: Hermes requires a model with at least 64k tokens of context. The agent's system prompt plus tool definitions plus a handful of skills already eats 12k to 14k tokens before you've said anything (more on that in how to cut your Hermes token bill). On a 32k-context model the agent will work for a few turns then start losing the plot when it tries to compress. Stick with 64k or above.
What hermes doctor checks and how to read its output
Run hermes doctor immediately after setup. It walks through everything that could be wrong with a fresh install and reports each one as ok, warn or fail. The checks I've seen it run, in roughly the order they appear:
- Python version is 3.11 or higher
- Node.js is on the path and version 22 or higher
ripgrepandffmpegare reachable~/.hermes/.envexists and is readable- At least one provider has a usable credential
- The state database opens without errors
- Disk space under
~/.hermes/is above some sensible floor - The repo is on a known commit, not detached or dirty
If hermes doctor flags a missing provider credential after you set up Nous Portal, the fix is usually that the OAuth flow finished but the token didn't get written. Run hermes config set provider nous-portal followed by hermes model to re-pick a model. That nudges Hermes to refresh the token.
If it warns about Node version, that's the installer falling back to whatever Node was already on the box. The fix is to uv tool install nodejs or to install Node 22 via your package manager. Hermes uses Node for some of its tool execution surfaces (especially the browser tooling and certain MCP servers), so it's not optional.
Manual install when the curl script breaks
The installer does fail sometimes. The most common reason on a small VPS is that uv's install step times out behind a slow link, leaving you with a partial state. The second most common is the script's PATH edit step running on a shell config it doesn't recognize. In both cases you can finish the install by hand.
Start clean by removing what's there. rm -rf ~/.hermes wipes the data and code. If you'd rather keep any data that already got written (memories, .env), back up ~/.hermes/.env and ~/.hermes/memories/ first.
Install uv manually:
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrcClone the repo and create the venv:
mkdir -p ~/.hermes
git clone https://github.com/NousResearch/hermes-agent ~/.hermes/hermes-agent
cd ~/.hermes/hermes-agent
uv venv --python 3.11
uv pip install -e .Then create the wrapper script that the installer would have written:
mkdir -p ~/.local/bin
cat > ~/.local/bin/hermes <<'EOF'
#!/usr/bin/env bash
exec ~/.hermes/hermes-agent/.venv/bin/hermes "$@"
EOF
chmod +x ~/.local/bin/hermes
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrcRun hermes --version to confirm. If that prints a version, the manual install worked and you can run hermes setup exactly as if the curl script had finished cleanly.
WSL2, macOS and Termux notes
The same one-liner works on WSL2 (treat it as Linux), macOS (Apple Silicon and Intel both fine) and Termux on Android. A few platform-specific things worth knowing.
On WSL2 the install lands inside the Linux filesystem (/home/<user>/.hermes), not the mounted Windows drive. Don't try to put ~/.hermes on /mnt/c/; SQLite WAL files don't behave well across the 9p file system bridge and you'll see weird locking errors during normal use.
On macOS the installer doesn't auto-add ~/.local/bin to zsh's default PATH. Add export PATH="$HOME/.local/bin:$PATH" to ~/.zshrc after the install or just symlink the binary into /usr/local/bin if you have it on PATH already.
On Termux the installer auto-detects the Termux environment and switches to a curated install path that uses Termux's pkg for system dependencies and a .[termux] Python extra to skip incompatible packages. WhatsApp gateway and browser automation are skipped on Termux because they don't have working backends on Android. Everything else, including Telegram and the full memory and skill system, works fine.
What to do next
Once hermes doctor is happy, three follow-on tutorials cover the steps that turn a working install into something you leave running.
If you came from OpenClaw, migrating from OpenClaw to Hermes walks through hermes claw migrate and what gets carried across. If you want the agent to stay online after you log out, the systemd guide for Hermes wires it up as a real service. And if you're running this for production work for anyone other than yourself, the production hardening checklist is the one to read before you put it on a public IP.
