How to install Hermes Agent on Linux

Short answer

Yes, Linux is officially supported. The official docs list Linux on x86_64 and aarch64 (64-bit ARM) as Tier 1, which means the team aims never to break installs and updates there.

The docs say they test on the latest Ubuntu and WSL2. They add that a distro with glibc, systemd and a standard filesystem layout is likely to work well.

On Linux, the main route is the command line installer. If you prefer containers, see How to run Hermes Agent in Docker.

What you need

• A 64-bit Linux system: x86_64 or aarch64.
• Git, curl, tar and SHA-256 utilities.
• No Python or Node.js. The installer provides Python 3.14, Node.js, npm, ripgrep and FFmpeg.
• Minimal Debian or Ubuntu images lack libatomic.so.1. The installer installs libatomic1 for you, and asks for your sudo password once if needed.
• Some source builds need a compiler and dev libraries. The browser tool's Chromium needs system libraries from your distro.

Raspberry Pi: the official docs do not mention it by name. What they support is 64-bit ARM Linux (aarch64), and a Pi running a 64-bit OS falls under that category.

32-bit ARM is not supported. The installer only accepts arm64/aarch64 and x86_64/amd64. On a 32-bit OS it stops with a message that Hermes does not support this host.

Install

Run the official one-liner as your normal user. Do not add sudo.

bash

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

The installer clones the source, sets up its own Python 3.14 and tools, and by default adds a pinned Chromium for the browser tool. New installs follow the stable channel, which is the latest published release.

First run and setup

Reload your shell, then start chatting.

bash

source ~/.bashrc   # or: source ~/.zshrc
hermes             # Start chatting!

bash

hermes model          # Choose your LLM provider and model
hermes tools          # Configure which tools are enabled
hermes gateway setup  # Set up messaging platforms
hermes config set     # Set individual config values
hermes config get     # Inspect individual config values
hermes setup          # Or run the full setup wizard to configure everything at once

The setup wizard offers three modes on a fresh install. Quick Setup uses a Nous Portal login, so there are no API keys to manage. Full Setup lets you bring your own keys. Blank Slate turns on only your provider and model, plus the File Operations and Terminal toolsets.

If you only want to pick a provider and model, run hermes model instead of the full wizard. The official docs say Hermes needs a model with at least 64,000 tokens of context. Smaller models are rejected at startup.

hermes --tui opens the newer terminal interface, which the docs recommend. hermes doctor checks the install, and hermes --continue resumes your last session.

Where your settings live and how to update

• Secrets: ~/.hermes/.env. Other settings: ~/.hermes/config.yaml.
• Identity file: ~/.hermes/SOUL.md. Memories: ~/.hermes/memories/.
• The command is ~/.local/bin/hermes and the code is in ~/.hermes/hermes-agent/.
• Update with hermes update. Preview first with hermes update --check.
• Switch channels with hermes update --set-channel main or hermes update --set-channel stable.

For backups and rollback, see How to update Hermes Agent safely.

Common problems

• You ran the installer with sudo: the FAQ says not to, because it installs to ~/.local/bin. Running as root puts everything in root's home.
• hermes: command not found: reload your shell with source ~/.bashrc.
• Tools you set up in ~/.bashrc, such as nvm or pyenv, are invisible to Hermes: list those files under terminal.shell_init_files in config.yaml.
• Installing for a separate service user: run the installer as that user, add ~/.local/bin to its PATH, and run sudo loginctl enable-linger SERVICE_USER.
• Alpine and other musl distros need the system libstdc++.

More fixes: Hermes Agent install or update failed.

Next step

Next: follow Hermes Agent setup: your first 24 hours. To keep Hermes running after you log out, see How to run Hermes Agent 24/7 on a VPS or home server. To chat from your phone, read Hermes Agent messaging gateway explained.

Spotted something wrong or out of date? Tell us on X at @HermesWatcher↗ (opens in a new tab) and we will fix it.

New Hermes Agent updates every day on X. Follow @HermesWatcher