Hermes Agent is an open source AI agent that turns your terminal into an intelligent assistant. Unlike classic chatbots like ChatGPT or Claude in a browser, Hermes doesn't just chat: it acts. It executes commands, reads and modifies files, browses the web, manages your emails, controls your smart home, and much more — all from your terminal or your favorite messaging platforms.
Developed by NousResearch and hosted on GitHub, Hermes Agent stands out with its action-centric approach rather than conversation. It's a truly autonomous assistant that understands context, uses tools, and adapts to your workflows. And it's completely free if you provide your own API key.
In this article, we'll discover what Hermes Agent is, why it stands out from the competition, and install it step by step — whether on your local machine, on a VPS for a 24/7 bot, or even on Android via Termux.
Why Choose Hermes Agent?
The AI agent market is exploding, but most solutions are proprietary, expensive, or limited to basic conversation. Hermes Agent checks boxes that few competitors cover simultaneously.
Open source and free
The code is on GitHub, the community is active, and you're not locked into a paid ecosystem. You only pay for the API costs of the model you choose — and with models like DeepSeek (which offers a free model) or free OpenRouter options, the bill can be near zero. No mandatory monthly subscription, no features locked behind a paywall.
Multi-model provider
Hermes isn't tied to a single AI model. You can use Claude (Anthropic), GPT (OpenAI), Gemini, DeepSeek, Qwen, Llama, or any OpenAI-compatible endpoint. Switch models with a single command if you find a better value. This flexibility is rare among AI agents, which are typically locked to one provider.
In practice, you can start with Claude for quality, switch to DeepSeek for simple tasks to reduce costs, and use a local model via Ollama for sensitive data — all without leaving Hermes.
68 built-in tools
Terminal, file management, web search, automated browser, email, GitHub, Spotify, vision (image analysis), image generation, TTS (text-to-speech), STT (speech-to-text), cron jobs, task delegation, kanban database — the list is impressive. Most AI agents limit themselves to 5 or 10 tools. Hermes offers 68, and each tool can be enabled or disabled based on your needs and trust level.
Multi-platform gateway
One agent, all your platforms: Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant, Microsoft Teams. Configure once, and your assistant is available everywhere with the same context and capabilities. This feature alone justifies adopting Hermes for anyone managing multiple communication channels.
Persistent and extensible memory
Unlike most chatbots that forget everything between sessions, Hermes maintains cross-session memory through multiple mechanisms: context files (CLAUDE.md, AGENTS.md), persistent declarative memory injected into every session, and a skills system (reusable competencies) that serves as procedural memory.
Skills: the agent that learns
The skills system is perhaps Hermes' most underestimated feature. Skills are knowledge documents the agent loads on demand. But more importantly, Hermes can create its own skills after solving a complex problem. It memorizes the procedure and reuses it in future sessions — a form of automated procedural learning that makes it increasingly competent over time.
Technical Prerequisites
Before installing Hermes Agent, here's what you need:
Operating system
Linux, macOS, or WSL2. Native Windows is not supported. If you're on Windows, install WSL2 (Windows Subsystem for Linux) — it's free and installation takes 5 minutes. Open PowerShell as administrator and type wsl --install, then restart.
macOS users don't need anything special — the installer works natively on both Intel and Apple Silicon.
Android users can install via Termux, a Linux terminal available on the Play Store or F-Droid. The installer automatically detects Termux and adapts the installation.
Git (only prerequisite)
This is the only package you need to install manually. The installer handles everything else:
- uv (ultra-fast Python package manager)
- Python 3.11 (via uv, no sudo needed)
- Node.js v22 (for browser automation and WhatsApp bridge)
- ripgrep (ultra-fast file search)
- ffmpeg (audio conversion for TTS)
On Ubuntu/Debian: sudo apt install git
On macOS: brew install git (or installed by default with Xcode CLT)
LLM API key
You need at least one AI model provider. The most accessible options:
Anthropic (Claude) — API key at console.anthropic.com. Best performing models for code and reasoning. Pay-per-token pricing.
OpenAI — API key at platform.openai.com. Access to GPT-4o, GPT-4, and reasoning models. Pay-per-token pricing.
OpenRouter — API key at openrouter.ai. Aggregator giving access to dozens of models (Claude, GPT, Llama, Mistral, etc.) from a single key. Some models are free.
DeepSeek — API key at platform.deepseek.com. Excellent value, often 10x cheaper than Anthropic for comparable performance on some tasks.
Nous Portal — Integrated subscription directly in Hermes, zero configuration. The simplest option to get started without managing an API key.
Minimum required: 64,000 tokens of context. Virtually all modern models (Claude, GPT-4, Gemini, Qwen, DeepSeek) far exceed this threshold. If you use a local model via Ollama or llama.cpp, make sure to configure at least 64K context (--ctx-size 65536).
Installing on Your Local Machine
Hermes Agent installation is designed to be as simple as possible — a single command on supported systems.
The one-line installer
Open your terminal and run:
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
The installer detects your system (Linux, macOS, WSL2, or Termux) and configures everything automatically:
- Clones the GitHub repository
- Installs Python 3.11 via uv (no sudo needed)
- Installs Node.js v22 for browser automation
- Configures ripgrep for file searching
- Installs ffmpeg for audio conversion
- Creates the Python virtual environment
- Makes the
hermescommand globally available in your PATH
The process typically takes between 1 and 3 minutes depending on your connection speed and machine power.
After installation
Reload your shell so the hermes command is available:
source ~/.bashrc
# or if you use zsh:
source ~/.zshrc
Verify everything works:
hermes --version
If you see a version number, the installation is successful. If you get hermes: command not found, make sure your shell was reloaded, or manually add the path to your PATH.
Where are files installed?
The installer places files differently depending on whether you install in user mode or root mode:
User mode (default, without sudo):
- Source code: ~/.hermes/hermes-agent/
- Binary: ~/.local/bin/hermes (symlink)
- Data: ~/.hermes/
Root mode (if you use sudo curl ... | sudo bash):
- Source code: /usr/local/lib/hermes-agent/
- Binary: /usr/local/bin/hermes
- Data: /root/.hermes/ (or $HERMES_HOME)
Root mode uses a standard FHS layout that matches where other system-wide developer tools live on Linux. It's useful for shared deployments where one system install serves multiple users. Per-user config (auth, skills, sessions) still lives under each user's ~/.hermes/.
Installing on a VPS for a 24/7 Bot
For permanent usage — Telegram bot, scheduled automation, cron jobs, multi-platform gateway — a VPS (Virtual Private Server) is the ideal solution. Hermes Agent runs in the background and stays available permanently, without depending on your personal computer.
Why a VPS for Hermes?
Hermes Agent consumes very few local resources: all AI processing is done by the model provider (Anthropic, OpenAI, etc.), not your machine. The VPS only runs the Hermes process and the messaging gateway. You therefore don't need a GPU VPS — a basic VPS is more than enough.
Choosing a suitable VPS
Recommended configuration:
- 1 vCPU minimum
- 1 GB RAM minimum (2 GB recommended for comfort)
- 10 GB SSD storage
- Ubuntu 22.04 or 24.04 LTS (recommended for compatibility)
Hostinger offers KVM VPS perfectly suited for this use case, starting from a few euros per month. Their VPS are fast, well-documented, and Ubuntu installation is one click from their management panel. They also offer excellent value for small projects like a Telegram bot or an automation agent.
VPS installation procedure
Once your VPS is provisioned and Ubuntu installed, connect via SSH:
ssh root@your-vps-ip
Update the system and install git:
apt update && apt upgrade -y
apt install git -y
Launch the Hermes installer:
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
Reload the shell:
source ~/.bashrc
Hermes Agent will install in root mode on the VPS. The data directory will be /root/.hermes/, and the source code in /usr/local/lib/hermes-agent/.
Provider configuration on the VPS
After installation, configure your model provider:
hermes model
The interactive menu guides you through choosing a provider and entering the API key. For a dedicated bot VPS, here are the recommended configurations:
Intensive usage (lots of conversations, complex tasks): Anthropic Claude — most reliable for long, multi-step tasks.
Budget usage (simple bot, light automation): DeepSeek — 10x cheaper, solid performance.
Free usage (testing, development): OpenRouter with free models or Nous Portal.
Background launch with systemd
To keep Hermes running permanently and restart automatically on issues, the recommended method is systemd:
cat > /etc/systemd/system/hermes.service << 'EOF'
[Unit]
Description=Hermes Agent Gateway
After=network.target
[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/hermes gateway
Restart=always
RestartSec=10
Environment=HERMES_HOME=/root/.hermes
[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload
systemctl enable hermes
systemctl start hermes
Verify everything works:
systemctl status hermes
hermes gateway status
Your agent now runs 24/7 and restarts automatically on crash or VPS reboot.
Alternative: tmux (for quick testing)
If you want to test quickly without configuring systemd:
tmux new -s hermes
hermes gateway
# Ctrl+B then D to detach
# tmux attach -t hermes to reattach
Note: tmux doesn't restart automatically after a VPS reboot. For production, prefer systemd.
Installing on Android via Termux
Hermes Agent also works on Android thanks to Termux — a complete Linux terminal for mobile. It's perfect for chatting with the agent on the go, doing web searches, or managing files.
Android prerequisites
- Install Termux from F-Droid (recommended) or the Play Store
- Open Termux and let the app initialize its packages
Installation
Run the installer — it automatically detects Termux and adapts:
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
The Termux installer specifically configures:
- Dependencies via pkg (Termux's package manager)
- Python virtual environment with python -m venv
- ANDROID_API_LEVEL variable for Android wheel builds
- A set of Android-compatible extras
Reload the shell:
source ~/.bashrc
Android limitations
Some features are limited or unavailable on Termux: the automated browser and WhatsApp bridge are disabled by default. Disk space is often more constrained, and performance depends on your device. It's an excellent complement for chat and search, but resource-intensive tasks are better suited to a VPS.
Initial Configuration and First Chat
The interactive setup
The simplest way to configure everything in one pass:
hermes setup
This interactive wizard guides you through:
- AI model and provider selection
- API key entry
- Enabled tools selection
- Messaging platform configuration
- General preferences
Manual configuration (advanced)
If you prefer to control every parameter, two files manage your configuration:
~/.hermes/.env — secrets and tokens (never commit this):
ANTHROPIC_API_KEY=sk-ant-...
OPENROUTER_API_KEY=sk-or-...
~/.hermes/config.yaml — non-sensitive configuration:
model: anthropic/claude-sonnet-4
terminal:
backend: local
Use hermes config set to modify values — the right file is automatically updated based on the value type:
hermes config set model anthropic/claude-sonnet-4
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-v1-...
Diagnostics: hermes doctor
Hermes includes a comprehensive diagnostic tool:
hermes doctor
This command checks your entire installation: system dependencies, configuration, API key, network connectivity, permissions. If something's wrong, hermes doctor tells you exactly what to fix and how.
First launch
Start your first session:
hermes # Classic CLI (prompt_toolkit)
hermes --tui # Modern TUI interface (recommended)
The TUI interface offers a more modern experience with modals, mouse selection, and non-blocking input. Both interfaces share the same sessions, slash commands, and configuration — try both and choose the one that suits you.
Test with a concrete, verifiable request:
Summarize the contents of my current directory in 5 points.
What's the disk usage? Show the top 5 largest directories.
Search for the 3 latest Node.js versions and explain the differences.
Session resume
Sessions are saved automatically. To pick up where you left off:
hermes --continue
# or shortcut:
hermes -c
Common Troubleshooting
| Problem | Solution |
|---|---|
hermes: command not found |
Reload your shell: source ~/.bashrc or check your PATH |
API key not set |
Run hermes model to configure your provider |
| Broken config after an update | hermes config check then hermes config migrate |
| Empty or incoherent responses | Check provider and model with hermes model |
| Gateway won't start | hermes gateway status to diagnose |
hermes --continue can't find session |
Verify with hermes sessions list that you're in the right profile |
| Model unavailable | Check your API quota or switch models |
If in doubt, the recommended recovery sequence is:
hermes doctor
hermes model
hermes setup
hermes sessions list
hermes --continue
This sequence brings you from a "broken" state back to a functional state in a few commands.
Conclusion
Hermes Agent is likely the most complete open source AI agent available today. Its installation is designed to be accessible to everyone — a single command and a few minutes are enough to go from zero to a fully functional AI assistant capable of executing commands, browsing the web, and managing your files.
Whether you install it on your local machine for daily development use, or on a VPS for a 24/7 Telegram bot, the procedure is identical and the barrier to entry is minimal. Choosing a VPS via Hostinger offers an excellent starting point for a few euros per month.
The real power of Hermes Agent reveals itself when you start leveraging its advanced tools: automating recurring tasks, managing complex projects, orchestrating multiple agents in parallel. That's what we'll explore in the upcoming articles in this series — from daily use with the CLI to advanced automation with cron jobs, skills, and task delegation.
If you haven't installed Hermes Agent yet, now's the time. Take 5 minutes, run the installer, configure your favorite model, and say hello to your new assistant.