A complete step-by-step guide to installing Hermes Agent on any platform — Linux, macOS, Windows, Android — connecting it to Telegram, choosing your AI provider, and troubleshooting common issues.

I have set up Hermes Agent more times than I can count — on MacBooks, Ubuntu servers, a HK-based VPS, and even on Android while travelling. Every time I help someone get started, I notice the same problem: the existing guides are either too basic (just the install command) or too scattered (you need four different pages to get the full picture).
This guide fixes that. It covers every install method, every provider option, Telegram setup, the gotchas nobody else documents, and how to actually get value from Hermes once it is running.
By the end you will have a fully working Hermes Agent that you can chat with from your phone via Telegram.
Hermes Agent is an open-source AI agent built by Nous Research. Unlike a standard chatbot, it runs on your own machine or server, connects to whichever AI model you choose, has access to real tools (terminal, browser, file system, web search), and learns and improves over time through a self-generated skills system.
The key differences from tools like ChatGPT or Claude's web interface:
| Feature | ChatGPT / Claude Web | Hermes Agent |
|---|---|---|
| Runs on your machine | ❌ | ✅ |
| Access to your files/terminal | ❌ | ✅ |
| Works via Telegram / WhatsApp | ❌ | ✅ |
| Choose any LLM provider | ❌ | ✅ |
| Learns and saves skills | ❌ | ✅ |
| Persistent memory across sessions |
Before installing, make sure you have:
You do not need to spend much. Here are the most popular options ranked by ease of setup:
| Provider | Best For | Cost | Notes |
|---|---|---|---|
| Nous Portal | Fastest setup | Subscription | OAuth — no API key needed. Includes Firecrawl, image gen, TTS, browser automation |
| OpenRouter | Flexibility | Pay-per-token | Access to 100+ models with one key. Good free tier. |
| Anthropic | Claude models | Pay-per-token | Claude Sonnet 4.6 is excellent. OAuth available for Claude Max subscribers. |
The fastest way to get running. One command handles everything — Python, Node.js, ripgrep, ffmpeg, and the Hermes binary itself.
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bashAfter it completes:
source ~/.bashrc # or: source ~/.zshrc on macOS
hermes # Start chattingThe installer creates everything under ~/.hermes/ and puts the binary at ~/.local/bin/hermes.
pip install hermes-agent
hermes postinstall # Installs Node.js, browser tools, ripgrep, ffmpegUse pip if you already manage a Python environment and want Hermes in it. Skip postinstall if you only need the core agent without browser automation or audio.
Download the signed installer from the GitHub Releases page. Double-click, done. No terminal required for installation.
The desktop app is the best option if you are on Windows and not comfortable with WSL2, or on macOS and want a clean native install without touching the terminal.
iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1)Run this in PowerShell as Administrator. The Windows native installer supports CLI, gateway, cron, browser, and MCP. The only thing that requires WSL2 on Windows is the Dashboard terminal pane.
# In Termux
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bashThe installer auto-detects Termux. Use the .[termux] pip extra if installing via pip on Android.
After installation, run the setup wizard:
hermes setupThis walks you through: 1. Choosing your LLM provider 2. Setting your API key 3. Optionally configuring messaging platforms (Telegram, Discord, etc.)
Fastest path if you use Nous Portal:
hermes setup --portalThis single command handles OAuth login, model selection, and all four Tool Gateway features (Firecrawl, image generation, TTS, browser automation) in one step.
hermes doctorThis is your best friend. It checks every dependency, every API key, every configuration setting, and tells you exactly what is missing and how to fix it. Run it after any setup change.
A healthy output looks like:
✅ Python 3.12.3
✅ Node.js 22.4.0
✅ ripgrep 14.1.0
✅ ffmpeg 6.1.1
✅ Model: anthropic/claude-sonnet-4-6
✅ API key: ANTHROPIC_API_KEY (set)
✅ Gateway: Not configured (optional)If anything shows ❌, the doctor tells you the exact command to fix it.
If you did not configure a provider during setup, or want to add more:
hermes modelThis opens an interactive menu to add providers and API keys. Select your provider, follow the prompts, and Hermes stores the key in ~/.hermes/.env.
To set a model directly:
hermes config set model anthropic/claude-sonnet-4-6
hermes config set ANTHROPIC_API_KEY your-key-hereImportant: Your model must support at least 64K context tokens. If you get errors about context length, either switch models or set:
hermes config set model.context_length 65536If you want to run completely offline with no API costs:
# Install Ollama first: https://ollama.com
ollama pull qwen2.5:32b # or any 64K+ context model
ollama serveThen in Hermes:
hermes model
# Select: Custom endpoint
# API base URL: http://localhost:11434/v1
# API key: ollama
# Model name: qwen2.5:32b
# Context length: 65536This is where Hermes gets genuinely powerful. Once connected, you can message your agent from anywhere — your phone, your laptop, a group chat — and it responds with full tool access.
/newbotbot, e.g., myhermes_bot)7123456789:AAF...Message @userinfobot on Telegram. It replies with your numeric user ID (e.g., 123456789). This is how Hermes knows who is allowed to talk to it.
Do not use your username — it must be the numeric ID.
hermes gateway setupSelect Telegram from the menu, paste your bot token and user ID. That's it.
Or add them manually to ~/.hermes/.env:
TELEGRAM_BOT_TOKEN=7123456789:AAF...
TELEGRAM_ALLOWED_USERS=123456789hermes gateway # Run in foreground (good for testing)
hermes gateway start # Run as background serviceThen open Telegram, find your bot, and send it a message. It should respond within a few seconds.
If you add the bot to a group and it does not respond:
To keep Hermes running 24/7 even after you close your terminal:
hermes gateway install # Install as user service (auto-starts on login)
hermes gateway start # Start it now
hermes gateway status # Check it is runningOn Linux this creates a systemd user service. On macOS it creates a launchd entry. Both restart automatically on crash.
After setup, your Hermes home lives at ~/.hermes/:
~/.hermes/
├── config.yaml # All non-secret settings (model, TUI preferences, tools)
├── .env # API keys and secrets (never commit this)
├── SOUL.md # Agent personality — edit to change how Hermes communicates
├── memories/
│ ├── MEMORY.md # Facts Hermes saves about your environment and preferences
│ └── USER.md # Facts Hermes saves about you
├── skills/ # Procedures Hermes learns and saves for reuse
├── cron/ # Scheduled tasks
├── sessions/ # Chat history (SQLite + JSONL)
└── logs/ # Logs (secrets auto-redacted)The most useful files to know:
Once running, these slash commands work inside any conversation — whether you're in the terminal, Telegram, or Discord:
| Command | What It Does |
|---|---|
/model | Show or switch the current AI model |
/new | Start a fresh conversation |
/compress | Compress the conversation when context gets long |
/status | Show current session info and token usage |
/stop | Stop the agent mid-task |
source ~/.bashrc # Linux
source ~/.zshrc # macOSIf that does not work, check that ~/.local/bin is in your PATH:
echo $PATH | grep local
# If missing:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrcRun hermes doctor first — it will pinpoint exactly what is wrong. The most common causes:
sk-or-, OpenAI keys start with sk-. They are not interchangeable.hermes config set YOUR_KEY_ENV_VAR your-key-value to save it properlyYour model's context window is too small. Either:
hermes model # Switch to a model with 64K+ context
# or
hermes config set model.context_length 65536During a long conversation, use /compress to reduce the context size without losing the key information.
hermes gateway install # Make it a persistent service
hermes gateway start # Start it
hermes gateway status # Verify it is runningOnce Hermes is running, here are the most useful things to explore:
Hermes can learn and save reusable procedures as skills. Browse the community skills marketplace:
hermes skills browse
hermes skills search "github"
hermes skills install github-pr-workflowSkills are like plugins for specific tasks — PR review, blog writing, data analysis, whatever you need repeatedly.
You can schedule recurring tasks in plain English:
"Check the HKMA website every morning at 8am and send me a summary of any new circulars"Hermes sets up the cron job, runs it on schedule, and delivers results to your Telegram.
If you want separate configurations for work and personal use:
hermes profile create work
hermes profile use work
hermes setup # Configure work-specific model and API keysEach profile has its own config, memories, and skills.
*This guide covers everything you need to get Hermes running and productive. If you run into anything not covered here, the official docs at hermes-agent.nousresearch.com/docs are the authoritative reference. Questions about specific setups? Reach out at sheryarshah.com.*
Filed under
Keep reading
More essays on AI growth, SEO & the web.
| Limited |
| ✅ |
| Runs scheduled tasks / cron jobs | ❌ | ✅ |
| Cost | Subscription | Pay your provider directly |
It is not a replacement for having a Claude or ChatGPT account. It is a layer on top of whatever model you choose — giving it tools, memory, autonomy, and a messaging interface.

| Google AI Studio |
| Free start |
| Free tier |
| Gemini models. OAuth available — no card needed to start. |
| Ollama | Offline / private | Free | Run models locally. Requires a decent GPU or good CPU. |
| OpenAI | GPT models | Pay-per-token | Standard API key setup. |
For most people starting out: Google AI Studio (free, no card) or OpenRouter (flexible, generous free credits) are the best first choices.
/voice on | Enable voice replies (requires ffmpeg) |
/update | Update Hermes to the latest version |
/help | Show all available commands |
And from the terminal:
hermes # Start interactive chat
hermes --tui # Modern TUI interface (recommended)
hermes chat -q "your prompt" # One-shot question
hermes config # View current configuration
hermes sessions list # Browse past conversations
hermes skills browse # Browse the skills marketplace
hermes logs # View recent logs
hermes update # Update to latest version© 2026 Sheryar Shah. Engineering-led AI Growth.