1 What Is Hermes Agent?
Hermes Agent is a fully open-source AI assistant built by Nous Research that lives in your terminal, on your messaging platforms, and inside your workflows. Unlike cloud-only AI chatbots, Hermes runs locally and has direct access to your file system, terminal, browser, and a rich ecosystem of tools and skills.
Think of it as an AI-native operating layer: you install it once, connect your preferred LLM provider (30+ supported), and get an agent that can read files, run shell commands, manage Git workflows, search the web, generate images, control smart home devices, and much more — all from a single conversational interface.
CLI / TUI
Tools & Skills
30+ Options
hermes model — zero lock-in.2 Who This Is For
This quickstart guide is designed for anyone who wants the shortest path from zero to a working Hermes setup. Specifically:
- Brand new users — you've heard about Hermes and want to get it running fast
- Provider switchers — you already have an API key and don't want to waste time on config mistakes
- Team/bot operators — you're setting up Hermes as a shared assistant or always-on workflow
- Frustrated installers — you've been in the "it installed, but it does nothing" limbo before
3 The Fastest Path
Pick the row that matches your goal and follow the steps. Don't overthink it — you can always reconfigure later.
| Goal | Do This First | Then Do This |
|---|---|---|
| Just get Hermes working | hermes setup |
Run a real chat and verify it responds |
| I already know my provider | hermes model |
Save the config, then start chatting |
| I want a bot / always-on | hermes gateway setup after CLI works |
Connect Telegram, Discord, Slack, etc. |
| I want a local model | hermes model → custom endpoint |
Verify endpoint, model name, and context length |
| Multi-provider fallback | hermes model first |
Add routing/fallback only after base chat works |
4 Install Hermes Agent
Option A: Hermes Desktop (macOS / Windows — Recommended)
The easiest path. Download the Hermes Desktop installer from the official website and run it. This installs both the command-line and desktop applications.
Option B: Command-Line Only
For Linux, macOS, WSL2, or Android (Termux):
For Windows (native PowerShell):
After installation finishes, reload your shell:
5 Choose a Provider
This is the single most important setup step. Use the interactive model selector:
Easiest Path: Nous Portal
One subscription covers 300+ models plus the Tool Gateway (web search, image generation, TTS, cloud browser). On a fresh install:
That logs you in via OAuth, sets Nous as your provider, and turns on the Tool Gateway — all in one command.
Setup Modes
On a fresh install, hermes setup offers three modes:
- Quick Setup (Nous Portal) — Free OAuth login, no API keys needed. Sets up a model plus the Tool Gateway tools. The recommended fast path.
- Full Setup — Walk through every provider, tool, and option yourself (bring your own keys).
- Blank Slate — Everything starts disabled except the bare minimum: provider & model, File Operations, and Terminal toolset. Pick this when you want a minimal, fully-controlled agent and intend to enable only what you need.
Popular Providers at a Glance
| Provider | What It Is | How to Set Up |
|---|---|---|
| Nous Portal | Subscription-based, zero-config | OAuth login via hermes model |
| Anthropic | Claude models directly | OAuth (Max plan) or API key |
| OpenAI Codex | ChatGPT OAuth, Codex models | Device code auth via hermes model |
| OpenRouter | Multi-provider routing | Enter your API key |
| Google AI Studio | Gemini models | Set GOOGLE_API_KEY |
| DeepSeek | Direct DeepSeek API | Set DEEPSEEK_API_KEY |
| xAI | Grok models | Set XAI_API_KEY or OAuth |
| GitHub Copilot | Copilot subscription | OAuth via hermes model |
| Custom Endpoint | vLLM, Ollama, SGLang, etc. | Set base URL + API key |
Hermes supports 30+ providers in total, including Hugging Face, AWS Bedrock, Azure Foundry, Alibaba Cloud, Kimi/Moonshot, LM Studio, NVIDIA NIM, and many more. See the full Providers page for the complete catalog.
--ctx-size 65536 (llama.cpp) or -c 65536 (Ollama).How Settings Are Stored
Hermes separates secrets from normal config:
- Secrets and tokens →
~/.hermes/.env - Non-secret settings →
~/.hermes/config.yaml
hermes model — no lock-in. The right value goes to the right file automatically.6 Run Your First Chat
You'll see a welcome banner with your model, available tools, and skills. Try a prompt that's specific and easy to verify:
What Success Looks Like
- ✅ The banner shows your chosen model/provider
- ✅ Hermes replies without error
- ✅ It can use a tool if needed (terminal, file read, web search)
- ✅ The conversation continues normally for more than one turn
prompt_toolkit CLI and a newer TUI with modal overlays, mouse selection, and non-blocking input. Both share the same sessions, slash commands, and config. Try each with hermes vs hermes --tui.7 Verify Sessions Work
Before moving on, make sure session resume works:
This should bring you back to the session you just had. If it doesn't, check whether you're in the same profile and whether the session actually saved. This matters later when you're juggling multiple setups or machines.
hermes sessions list to see all saved sessions and confirm your work is persisting.8 Key Features to Try
Terminal Access
The agent can run shell commands on your behalf:
Hermes runs the commands and shows results inline — no copy-pasting between windows.
Slash Commands
Type / to see an autocomplete dropdown of all commands:
| Command | What It Does |
|---|---|
/help | Show all available commands |
/tools | List available tools |
/model | Switch models interactively |
/personality pirate | Try a fun personality |
/save | Save the conversation |
Multi-Line Input
Press Alt+Enter, Ctrl+J, or Shift+Enter to add a new line. Shift+Enter requires a terminal that sends it as a distinct sequence (Kitty, foot, WezTerm, Ghostty by default; iTerm2 and Alacritty need Kitty keyboard protocol enabled). Alt+Enter and Ctrl+J work everywhere.
Interrupt the Agent
If the agent is taking too long, type a new message and press Enter — it interrupts the current task and switches to your new instructions. Ctrl+C also works.
9 Add the Next Layer
Only do this after the base chat works. Pick what you need:
🤖 Messaging Gateway (Bot / Shared Assistant)
Connect to Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant, or Microsoft Teams.
🔧 Tools & Automation
hermes tools— tune tool access per platformhermes skills— browse and install reusable workflows- Cron — only after your bot or CLI setup is stable
🛡️ Sandboxed Terminal
For safety, run the agent's terminal inside Docker or on a remote server:
🎙️ Voice Mode
Includes faster-whisper for free local speech-to-text.
📦 Skills System
Skills are on-demand instruction documents that teach Hermes how to do specific tasks — deploy to Kubernetes, open a GitHub PR, fine-tune a model, search for GIFs. Each is a SKILL.md file with a name, description, and step-by-step procedure.
Every installed skill becomes a slash command automatically:
🔌 MCP Servers
Add to ~/.hermes/config.yaml:
✏️ Editor Integration (ACP)
ACP support ships with the standard [all] extras, so the curl installer already includes it:
10 Common Failure Modes & Recovery
These are the problems that waste the most time. Know them, avoid them.
| Symptom | Likely Cause | Fix |
|---|---|---|
| Empty or broken replies | Provider auth or model wrong | Run hermes model again |
| Custom endpoint returns garbage | Wrong URL, model name, or incompatible API | Verify endpoint in a separate client first |
| Gateway starts but no messages | Bot token, allowlist, or platform setup incomplete | Re-run hermes gateway setup |
| Can't find old session | Switched profiles or session didn't save | Check hermes sessions list |
| Model unavailable or odd fallback | Routing/fallback too aggressive | Keep routing off until base is stable |
hermes doctor flags issues |
Config values missing or stale | Fix config, retest plain chat |
Recovery Toolkit
When something feels off, run these commands in order:
11 Quick Reference
| Command | Description |
|---|---|
hermes | Start chatting |
hermes model | Choose your LLM provider and model |
hermes tools | Configure which tools are enabled per platform |
hermes setup | Full setup wizard (configures everything at once) |
hermes doctor | Diagnose issues |
hermes update | Update to latest version |
hermes gateway | Start the messaging gateway |
hermes --continue | Resume last session |
hermes skills | Browse and install reusable workflows |
hermes acp | Launch editor integration (ACP) |
🎯 Key Takeaways
🔑 Key Takeaways
- Install in one command — a single
curl(or PowerShelliex) gets you from nothing to a working install in under a minute. - Nous Portal is the fastest path —
hermes setup --portalhandles OAuth login, provider setup, and Tool Gateway in one shot. - 30+ providers, zero lock-in — switch between Anthropic, OpenAI, Google, DeepSeek, Hugging Face, local models, and many more with
hermes model. - 64K minimum context is mandatory — Hermes requires at least 64,000 tokens of context for multi-step tool-calling workflows.
- Get one clean chat working first — don't add gateway, cron, skills, or routing until the base CLI chat responds without errors.
- Two interfaces available — the classic CLI (
hermes) and the modern TUI (hermes --tui) share the same sessions, commands, and config. - Skills are first-class — browse, install, and use skills as slash commands. The agent also auto-loads matching skills during conversation.
- Messaging gateway supports 7+ platforms — Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant, and Teams are all supported.
- Sandboxing is built in — run the agent's terminal in Docker or on a remote SSH server for safety.
hermes doctoris your best friend — when something feels off, it diagnoses config issues and suggests fixes.
🔗 Resources & Links
- Hermes Agent Quickstart (Official Docs) — the source page for this article
- Full Installation Guide — detailed install options, prerequisites, and troubleshooting
- AI Providers Reference — complete list of all 30+ supported providers and setup steps
- CLI Guide — master the terminal interface
- Messaging Gateway — connect Telegram, Discord, Slack, and more
- Skills System — reusable workflows and knowledge
- Tools & Toolsets — explore available capabilities
- Hermes Agent GitHub Repository — source code and contributions
- Hermes Agent Website — downloads, news, and community