Beginner guide · Hermes Agent
How to install Hermes Agent (Mac, Windows, Linux)
Short answer: on a Mac with Apple silicon or a Windows PC, download the Hermes Desktop app from the Hermes website. On Linux (or if you want command line only), run one install command, then hermes setup to connect an AI model. Test one plain chat before you connect Telegram, email or anything else, and keep approvals on.
Updated · By BotsDoThat
Every command here is from Nous Research's official Hermes docs, linked inline. Hermes changes often, so check the linked page if a step looks different.
Before you start
- A computer that stays on if you want it to answer you all day: your own Mac, Windows PC, Linux machine or a server. Prefer not to run one? Hermes Cloud is a hosted, always-on Hermes included with paid Nous Portal plans (Hermes).
- Mac users: the macOS installer is Apple silicon only; Intel Macs are not a supported platform (install docs).
- An AI model. Options include a Nous Portal subscription, your ChatGPT or Codex subscription, an Anthropic, OpenRouter or Google AI Studio key, or a local model. The model needs at least 64,000 tokens of context; for a local model, set its context size to 64K (quickstart).
- Ten quiet minutes and one test job. Don't connect your real inbox on day one.
Step 1: Install Hermes Agent
Easiest: the desktop app (Mac or Windows)
The quickstart calls the Hermes Desktop installer the recommended route on macOS and Windows (quickstart). Download it from the Hermes website. On Windows, open the .appinstaller file with Windows App Installer. On a Mac, open the DMG and copy Hermes.app to Applications. The bundle already contains the agent and what it needs to run (install docs).
Command line: Linux, macOS or WSL2
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
Command line: Windows (PowerShell)
iex (irm https://hermes-agent.nousresearch.com/install.ps1)
Then reload your terminal (source ~/.bashrc or source ~/.zshrc). The installer also adds a browser and a computer-use driver by default; add --skip-browser or --skip-computer-use (Windows: -SkipBrowser, -SkipComputerUse) to leave them out. Want the desktop app later? Run hermes desktop (install docs).
Android phones (aarch64) use the Termux package (pkg install hermes-agent), not these scripts. Docker installs update by pulling the image, for example docker pull nousresearch/hermes-agent:latest (install docs, updating).
Running a command that pipes a web script into your shell means trusting that site. Copy it only from the official docs page.
Step 2: Connect an AI model
Run hermes setup. On a fresh install it offers three modes (quickstart):
- Quick Setup (Nous Portal): sign in, no API keys to manage; billed to a Nous Portal subscription. Shortcut:
hermes setup --portal. - Full Setup: pick each provider and tool yourself and bring your own keys, or sign in with a ChatGPT/Codex plan.
- Blank Slate: almost everything starts off (only the model, file and terminal tools). The careful choice if you want to turn on tools one at a time.
Already know your provider? hermes model does just that step. Secrets go to ~/.hermes/.env and normal settings to ~/.hermes/config.yaml (quickstart). Coming from OpenClaw? hermes setup offers to import your setup when it finds one; see also Migrate from OpenClaw. Worried about the bill? See switch Hermes to a cheaper model and what an AI agent costs per month.
Step 3: Run one test chat
Start hermes (or hermes --tui for the newer screen). The docs' advice: if Hermes can't finish a normal chat, don't add features yet (quickstart). It's working when:
- the banner shows the model you picked,
- it replies without an error and keeps going for more than one turn,
hermes -cbrings you back to the same conversation.
Step 4: Make it safe before you connect anything
- Keep approvals on. The default “smart” mode lets a helper model approve low-risk commands, deny dangerous ones and ask you when unsure; “manual” always asks. Don't set approvals to off or start with
--yolo, which skip the prompts (Hermes security). - Use the sandbox.
hermes config set terminal.backend dockerruns the agent's commands in a container instead of on your computer (quickstart). - Add chat apps last.
hermes gateway setupconnects Telegram, Discord, Slack, WhatsApp, Signal or email. Unknown people are denied unless you allowlist them or approve a pairing code withhermes pairing approve; never setGATEWAY_ALLOW_ALL_USERS=true(Hermes security). - Protect your keys:
chmod 600 ~/.hermes/.env, and set a spend limit at your AI provider: set spend limits and usage alerts on your AI accounts. - Start with read-only jobs. A summary or a watcher before anything that sends, buys or deletes. More: is it safe to give an AI agent your email? and how to keep an AI agent from deleting your files.
If the install fails
| What you see | What to do |
|---|---|
hermes: command not found | Reload your shell (source ~/.bashrc) or check PATH |
API key not set | Run hermes model to set up a provider |
| Opens, but replies are empty or broken | Run hermes model again and check provider, model and sign-in |
| Bot connected, but nobody can message it | Re-run hermes gateway setup; check hermes gateway status and your allowlist |
| Anything else | hermes doctor, then hermes model, then hermes setup |
From install docs and quickstart. The installer writes a log to logs/install.log in the Hermes data folder.
Updating and uninstalling
Command-line installs update with hermes update; the desktop app updates from its own Update control. To remove it, run hermes uninstall --dry-run first to see what would go, and hermes backup if you might come back (updating docs).
What to hand it first
Any of our 12 blueprints works as instructions for Hermes. Good first ones: Morning Inbox Briefing and Web Page Watcher. Write your own with the 6-part instructions template. Still choosing? OpenClaw vs Hermes Agent or OpenClaw alternatives for beginners.
Questions
How do I install Hermes Agent?
On a Mac with Apple silicon or a Windows PC, the docs recommend the Hermes Desktop installer from the Hermes website. For a command-line install, run curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash on Linux, macOS or WSL2, or iex (irm https://hermes-agent.nousresearch.com/install.ps1) in PowerShell on Windows. Then run hermes setup to connect a model.
How do I install Hermes Agent on Windows?
Either download the Windows desktop package from the Hermes website and open it with Windows App Installer, or run iex (irm https://hermes-agent.nousresearch.com/install.ps1) in PowerShell for a command-line install. WSL2 also works with the Linux installer.
Does Hermes Agent work on an Intel Mac?
Not officially. The installation docs say the macOS installer is Apple silicon only and that macOS on Intel processors is not a supported platform.
Is Hermes Agent safe?
It has real safety controls, but the defaults are not a lock. By default it asks (or has a helper model judge) before dangerous commands, scheduled jobs deny dangerous commands, and unknown people who message your bot are denied unless you pair or allowlist them. It still runs commands on your own computer unless you switch on the Docker sandbox, and turning approvals off or using --yolo removes the prompts. Give it only the accounts it needs.
Hermes Agent install failed. What should I do?
Run hermes doctor first; it reports what's missing. If the shell says hermes: command not found, reload it (source ~/.bashrc or ~/.zshrc). If it says API key not set, run hermes model. The installer writes a log to logs/install.log in the Hermes data folder, and a failed step prints its last lines.
Is Hermes Agent free?
The software is free and open source under the MIT license. You pay for the AI model you connect (or use a plan you already have, like a ChatGPT or Codex subscription), and Nous Portal is an optional paid subscription.
How do I update or uninstall Hermes Agent?
For a command-line install, run hermes update; the desktop app has its own Update control. To remove it, run hermes uninstall --dry-run first to see what would go, and hermes backup if you might want your setup later.