- 16
- May
After our intro article on What Is Hermes Agent?, the most common question was "is it hard to install?" The answer: Nous Research designed Hermes to install in 60 seconds through a single one-liner. This guide walks you through install, config, and your first agent run — across 4 operating systems plus Docker and VPS.
System Requirements
Hermes' official docs say it runs on anything from a $5/month VPS up to a GPU cluster or serverless infrastructure. For first-time installs, here are recommended specs:
| Component | Minimum | Recommended |
|---|---|---|
| RAM | 2 GB | 4–8 GB (16+ GB if running a local model) |
| Disk | 2 GB free | 10 GB+ (for memory store + skills) |
| OS | macOS 13+, Ubuntu 22+, Windows 11 (WSL2 or native), Termux | Ubuntu 24 LTS (for VPS) |
| Python | No need to install ahead — installer brings Python 3.11 | Uses uv automatically |
| Network | Internet connection | Public IP/Cloudflare tunnel if you need webhooks |
Why the new installer is great: no prep work — the script installs uv, Python 3.11, clones the repo, and creates a virtualenv all at once without sudo.
Step 1 — Install Hermes by OS
macOS / Linux / WSL2
Open Terminal and run the one-liner:
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
The script does 4 things:
- Installs uv (the fast Python package manager from Astral)
- Installs Python 3.11 into
~/.hermes - Clones NousResearch/hermes-agent
- Creates a virtualenv and installs dependencies
Windows (Native PowerShell — Early Beta)
Open PowerShell (no admin needed) and run:
irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex
Note: the native Windows installer is still early beta. If you hit path/permission issues, switch to WSL2 (Windows Subsystem for Linux) and run the Linux installer — it's more stable.
Android (Termux)
Install Termux from F-Droid (not Google Play — that build is outdated), open it, then run:
pkg install -y curl curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
Step 2 — Pick an LLM Provider
After install, the next step is picking which LLM Hermes will call. Three popular options:
Option A — Claude API (recommended for first run)
Claude has the most accurate tool use — best fit for agents.
- Sign up for an Anthropic API account and add credit
- Create an API key at console.anthropic.com
- Set the environment variable:
export ANTHROPIC_API_KEY="sk-ant-xxxxx"
Option B — OpenRouter (200+ models)
- Sign up at openrouter.ai and add credit
- Create an API key
- Set:
export OPENROUTER_API_KEY="sk-or-xxxxx"
Option C — Local Model (free, $0)
Use Ollama to run Llama 3 / Qwen on your own machine — perfect for data privacy.
# macOS / Linux brew install ollama # or: curl -fsSL https://ollama.com/install.sh | sh ollama pull llama3.1:8b ollama serve &
Step 3 — Run the Setup Wizard
The first time you run Hermes, an interactive wizard helps you configure:
hermes init
The wizard asks:
| Question | Recommended Answer |
|---|---|
| Default LLM provider? | anthropic |
| Default model? | claude-opus-4-7 or claude-sonnet-4-6 |
| Terminal backend? | local (switch to docker later) |
| Browser backend? | local-chromium (free) or browserbase (cloud) |
| Memory store path? | ~/.hermes/memory (default) |
Config is written to ~/.hermes/config.toml — editable any time.
Step 4 — First Run (CLI)
Run Hermes in CLI mode to test:
hermes chat
Try simple test prompts:
> List files in ~/Downloads and tell me which ones are larger than 100MB > Search the web for the latest news on "ERP cloud Thailand 2026" and summarize in 5 lines > Write a Python script that reads a CSV and plots a histogram
If Hermes responds and runs the tools successfully — install is complete.
Step 5 — Connect Telegram Bot
After CLI works, connecting a messaging platform lets you control Hermes from your phone — Telegram is the easiest to set up.
- Create a bot with BotFather:
- Open Telegram and chat with
@BotFather - Send
/newbotand pick a name + username - Copy the HTTP API token
- Open Telegram and chat with
- Configure Hermes:
hermes integrations add telegram # paste the bot token when prompted # set allowed user IDs (so only you can talk to it)
- Start the gateway:
hermes serve
Find your bot in Telegram and send it a message — Hermes will reply and accept commands.
Step 6 — Deploy to a VPS (24/7)
Running on your own laptop means leaving it on all the time. The popular alternative is deploying to a cheap VPS:
| VPS Provider | Recommended Plan | Notes |
|---|---|---|
| DigitalOcean | Basic Droplet 2GB ~$12/mo | Has a Singapore region — low latency for Thailand |
| Hetzner | CX22 ~€4.59/mo | Very cheap, but EU regions only |
| AWS Lightsail | $5/mo plan | Singapore region available |
| Linode | Nanode 1GB $5/mo | Great for first-time users |
Deploy steps on an Ubuntu VPS:
# 1. SSH into VPS and create a new user (don't run as root) ssh root@your-vps-ip adduser hermes usermod -aG sudo hermes su - hermes # 2. Install Hermes curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash # 3. Config + add API key hermes init # 4. Create a systemd service sudo tee /etc/systemd/system/hermes.service > /dev/null <<EOF [Unit] Description=Hermes Agent After=network.target [Service] Type=simple User=hermes WorkingDirectory=/home/hermes ExecStart=/home/hermes/.hermes/bin/hermes serve Restart=always [Install] WantedBy=multi-user.target EOF sudo systemctl enable --now hermes sudo systemctl status hermes
Step 7 — Docker Deploy (Alternative)
If you prefer Docker over systemd:
docker run -d \ --name hermes \ --restart unless-stopped \ -e ANTHROPIC_API_KEY="sk-ant-xxxxx" \ -e TELEGRAM_BOT_TOKEN="123:abcxyz" \ -v hermes_data:/root/.hermes \ ghcr.io/nousresearch/hermes-agent:latest serve
Common Troubleshooting
| Issue | Fix |
|---|---|
command not found: hermes |
Add ~/.hermes/bin to $PATH or open a new terminal |
| Permission denied (Linux) | Don't use sudo with the installer — it breaks ownership |
| SSL cert error | Update CA certs: sudo apt install ca-certificates |
| Telegram doesn't reply | Check that your Telegram user ID is in allowed_users in config |
| Out of memory on a 1GB VPS | Add 2GB swap or upgrade to a 2GB plan |
| Browser tool fails | Install extra dependencies: hermes setup browser |
Security Considerations Before Deploy
1. Never expose the agent directly to the public internet — use Cloudflare Tunnel or an SSH tunnel.
2. Always set allowed_users — otherwise anyone could control your bot.
3. Store API keys in a secret manager, not in .env files committed to git (see 2FA).
4. Limit shell access — configure terminal.allowed_commands to only what you actually need.
5. Run as a non-root user — if Hermes is hit by a prompt injection, the blast radius stays contained (read more: AI Cyberattack).
Next Steps
Now that install and deploy are done, try going further:
- Read 5 Real Use Cases for Hermes Agent in Organizations for inspiration
- Compare Hermes against Claude Code, OpenClaw, Cursor to pick the right tool
- Schedule cron jobs from the wizard:
hermes cron add - Add MCP servers:
hermes mcp add <url>
Installing Hermes on a $5 VPS and wiring up a Telegram bot takes about 30 minutes — but the time-eater is "configuring permissions safely." Don't ship a deploy that skips the security steps.
- Saeree ERP Team
If you need an ERP that integrates with external AI agents like Hermes via APIs with full audit trails, Saeree ERP offers fine-grained access control to limit what AI agents can do. Schedule a demo.
References
- Nous Research — Hermes Agent Official
- GitHub Install Script — NousResearch/hermes-agent
- Hermes Documentation — hermes-agent.nousresearch.com/docs
- DataCamp Tutorial — Nous Research Hermes Agent: Setup and Tutorial Guide
- Open-Techstack — How to Set Up Hermes Agent for Local Automation Workflows
