Getting Started with Hermes Agent

Welcome to the frontier of autonomous agency. Whether you are a developer looking to automate complex workflows or a power user seeking a persistent AI companion, Hermes Agent provides the infrastructure to move from simple prompting to true agentic execution.

What is Hermes Agent?

Hermes Agent, developed by Nous Research, is a high-performance autonomous agent framework designed to bridge the gap between Large Language Models (LLMs) and real-world execution. Unlike standard chatbots, Hermes is an “Agentic OS” that doesn’t just talk—it acts.

Core Capabilities

• The Learning Loop: Hermes features a built-in experiential learning loop. When the agent solves a problem using a specific sequence of tools, it can codify that experience into a “Skill,” allowing it to execute similar tasks faster and more reliably in the future.
• Persistent Memory: Utilizing a sophisticated memory architecture (powered by Honcho), Hermes maintains context across different sessions, platforms, and restarts. It remembers your preferences, past project details, and specific constraints.
• Massive Provider Ecosystem: Out-of-the-box support for 20+ LLM providers, allowing you to swap between frontier models (like GPT-4o or Claude 3.5) and local open-source models (like Llama 3 or Mistral) seamlessly.
• Multi-Platform Gateway: Hermes isn’t tethered to a single terminal. Through the Tool Gateway, you can deploy your agent to Telegram, Discord, and Slack, maintaining a single brain across all your communication channels.
• MCP Protocol Support: Fully compatible with the Model Context Protocol (MCP), enabling Hermes to integrate with a vast array of third-party data sources and tools.
• 60+ Built-in Tools: From filesystem manipulation and shell execution to web scraping and API orchestration, Hermes comes pre-equipped to handle complex technical tasks.
• Deployment Flexibility: Hermes is designed to run anywhere. Whether it’s your local terminal, a remote VPS, a Docker container, or a serverless environment, the installation process remains consistent.

---

Learning Path

To master Hermes Agent, we recommend following this structured progression. Each guide builds upon the previous one to move you from a basic user to an agent architect.

Step	Guide	What You Will Learn
1	You are here $\rightarrow$ Getting Started	Installation, provider configuration, and your first chat
2	CLI Mastery	Session management, slash commands, TUI, and CLI flags
3	Providers	Managing 20+ providers, credential pools, and model switching
4	Gateway Setup	Deploying bots to Telegram, Discord, and Slack
5	Memory System	Persistent cross-session memory and Honcho configuration
6	Multi-Agent	Creating profiles, subagents, and parallel workflows
7	Automation	Setting up cron jobs, webhooks, and scheduled tasks
8	Troubleshooting	Solving common installation issues and state recovery

---

Install Hermes Agent

Hermes is distributed as a lightweight binary with a streamlined installation script that handles dependency resolution and path configuration.

Linux and macOS

Open your terminal and run the following one-liner:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Windows (PowerShell)

For Windows users, run the following command in an administrative PowerShell window:

iwr -useb https://hermes-agent.nousresearch.com/install.ps1 | iex

Verification: After installation, restart your terminal and verify the installation by checking the version:

hermes --version

---

Setup with Nous Portal (Fastest Path)

The quickest way to get Hermes operational is via the Nous Portal. Instead of manually hunting for API keys for five different services, the Portal uses a single OAuth flow to provision your agent.

Run the following command:

hermes setup --portal

How the OAuth Flow Works

1. Authentication: The command will generate a unique pairing code and open your default web browser to the Nous Portal.
2. Authorization: Once you log in, you grant Hermes permission to access your configured model providers.
3. Unified Provisioning: A single login covers:
   • Model Inference: Instant access to your preferred LLM providers.
   • Tool Gateway Tools: Immediate activation of the four core utility tools:
     • Web Search: Real-time internet access for current events.
     • Image Generation: DALL-E 3 / Midjourney integration.
     • TTS (Text-to-Speech): High-fidelity voice synthesis.
     • Browser: Headless browser capability for complex web navigation.

---

Manual Setup

If you prefer to manage your own keys or are operating in an air-gapped environment, you can configure Hermes manually.

The Setup Wizard

Run the interactive wizard to configure your environment step-by-step:

hermes setup

The wizard will prompt you for your preferred provider (e.g., OpenAI, Anthropic, Groq) and ask for the corresponding API key.

Manual Environment Configuration

Hermes stores its configuration in a hidden directory in your home folder. You can edit the .env file directly for bulk updates:

Path: ~/.hermes/.env

Example configuration:

HERMES_PROVIDER=openai
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxx
HERMES_MODEL=gpt-4o
HERMES_MEMORY_BACKEND=honcho

Switching Models on the Fly

You don’t need to restart the agent to change models. Use the hermes model command:

# Switch to Claude 3.5 Sonnet
hermes model claude-3-5-sonnet

# List all available models for your current provider
hermes model list

---

Your First Conversation

Now that Hermes is installed and configured, it’s time to put it to work. Hermes supports three primary interaction modes.

1. Quick Query Mode

For fast, one-off tasks where you don’t need a persistent session, use the -q (query) flag. This is ideal for piping output into other CLI tools.

Example: System Analysis

hermes chat -q "How large is this directory in MB and what are the top 3 largest files?"

Example: General Knowledge

hermes chat -q "What time is it in Tokyo right now and what is the current weather there?"

2. TUI Mode (Terminal User Interface)

For a rich, interactive experience that feels like a professional IDE for AI, launch the TUI:

hermes --tui

The TUI provides a side-panel for memory tracking, a tool-execution log, and a dedicated area for managing different agent profiles.

3. Standard Interactive Mode

Simply run hermes to enter a standard chat session.

hermes

Essential Slash Commands

While in an interactive session, you can use slash commands to control the agent’s behavior without leaving the chat:

Command	Action	Use Case
/model [name]	Changes the LLM	Switch from a fast model to a reasoning model
/forget	Clears current session memory	Start a fresh topic without old context interference
/skill [name]	Lists available learned skills	Check what the agent has “learned” to do
/tool [name]	Forces a specific tool usage	Manually trigger a web search or file read
/exit	Ends the session	Safely save memory and close the agent

---

Next Steps

You have successfully installed Hermes and run your first command. However, you’ve only scratched the surface of what an autonomous agent can do. To move from “chatbot” to “autonomous employee,” explore the following guides:

• CLI Mastery: Learn how to use advanced flags, manage multiple sessions, and master the TUI for maximum productivity.
• Provider Setup: Configure credential pools to automatically failover between providers if one API goes down.
• Gateway Setup: Move Hermes out of the terminal and into your team’s Slack or Discord server.
• Memory and Profiles: Configure Honcho to create a “long-term brain” for your agent that persists across months of usage.
• Multi-Agent Setup: Learn how to create “Specialist” profiles (e.g., a Coder, a Researcher, a Manager) that can collaborate on a single project.
• Advanced Automation: Set up Hermes to run on a schedule (Cron) or respond to incoming webhooks.
• Troubleshooting: Find solutions for common permission errors, API timeouts, and memory corruption.

For the full technical reference, visit the Official Hermes Documentation.

HERO_IMAGE_PROMPT: A high-tech, cinematic wide shot of a holographic terminal interface floating in a dark, minimalist studio. The interface shows a complex network of nodes and flowing data streams in neon cyan and deep violet. A sleek, metallic robotic hand is lightly touching a glowing “Initialize” button. Hyper-realistic, 8k resolution, cyberpunk aesthetic, soft bokeh background with deep blue ambient lighting.