Getting Started with Hermes Agent — Install, Setup & First Conversation

Hermes Agent··Updated ·9 min read·getting-startedinstallationhermes-agentquickstart

Install Hermes Agent, run hermes setup --portal, pick a provider, and have your first conversation in under 5 minutes. The complete starting point for everyone.

TLDR: Hermes Agent is the self-improving AI agent from Nous Research — an autonomous agent with a built-in learning loop, persistent memory, 20+ LLM providers, and a multi-platform gateway. Install in one command and start chatting in under 5 minutes.

What is Hermes Agent?

Hermes Agent isn’t a chatbot wrapper around a single API or a coding copilot tethered to an IDE. It’s an autonomous agent that gets more capable the longer it runs. It lives wherever you put it — a $5 VPS, a GPU cluster, or serverless infrastructure like Daytona or Modal that costs nearly nothing when idle.

Key capabilities:

  • Closed learning loop — Creates skills from experience, improves them during use, and builds a deepening model of who you are across sessions
  • Runs anywhere — 6 terminal backends (local, Docker, SSH, Daytona, Singularity, Modal)
  • 20+ messaging platforms — Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Teams, and more
  • 60+ built-in tools — Terminal, file ops, web search, browser, code execution, image generation
  • MCP support — Connect any Model Context Protocol server

Learning Path

Not sure where to go after this guide? Follow this progression:

Step Guide What You’ll Learn
1 You are here → Getting Started Install, configure a provider, run your first chat
2 CLI Mastery Sessions, slash commands, TUI, all CLI flags
3 Providers All 20+ providers, credential pools, model switching
4 Gateway Setup Telegram, Discord, Slack — make Hermes a bot
5 Memory System Persistent cross-session memory and Honcho
6 Multi-Agent Profiles, subagents, parallel workflows
7 Automation Cron jobs, webhooks, scheduled tasks
8 Troubleshooting Common issues and recovery toolkit

1. Install Hermes Agent

Quick Install (Linux / macOS / WSL2 / Android)

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

Windows (native PowerShell)

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

What the Installer Does

The installer handles everything automatically — all dependencies (Python 3.11 via uv, Node.js v22, ripgrep, ffmpeg), the repo clone at ~/.hermes/hermes-agent/, virtual environment creation, and a global hermes command symlinked to ~/.local/bin/hermes. By the end, you can type hermes and get a working agent.

After it finishes, reload your shell:

source ~/.bashrc   # or source ~/.zshrc

For detailed install options — including non-sudo system service installs, root-mode FHS layout, and what happens on each platform — see the official Installation Guide.

2. Choose a Provider (The Fastest Path)

The single most important setup step. Hermes supports 30+ LLM providers, but for first-time users there’s one clearly recommended path.

Fastest Path: Nous Portal

One subscription covers 300+ models plus the Tool Gateway (web search, image generation, TTS, cloud browser). Skip the per-tool key juggling:

hermes setup --portal

That single command does three things:

  1. Opens a browser-based OAuth login to Nous Portal
  2. Sets Nous as your LLM provider with a capable default model
  3. Enables the Tool Gateway — web search, image generation, TTS, and a cloud browser

No API keys to copy, no .env files to edit, no model names to look up. You’re authenticated and configured in under 30 seconds.

Alternative: hermes model

If you already have an API key for another provider — or you want to use a local model via Ollama — run:

hermes model

This walks you through an interactive menu of all supported providers.

Provider What It Is Setup
Nous Portal Subscription-based, zero-config OAuth via hermes model or hermes setup --portal
OpenAI Codex ChatGPT OAuth, Codex models Device code auth via hermes model
Anthropic Claude models directly OAuth or API key via hermes model
OpenRouter Multi-provider routing Paste your API key
DeepSeek Direct API access Set DEEPSEEK_API_KEY
Google AI Studio Gemini models Set GOOGLE_API_KEY
Custom Endpoint Ollama, vLLM, SGLang Set base URL + API key

Important: Hermes requires a model with at least 64K tokens of context window. Most hosted models (Claude, GPT, Gemini, Qwen, DeepSeek) meet this easily. For local models, set --ctx-size 65536 or equivalent.

For a complete catalog of all supported providers with env vars and setup details, see the official AI Providers page.

How Settings Are Stored

Hermes separates secrets from normal config automatically:

  • Secrets and tokens → ~/.hermes/.env
  • Non-secret settings → ~/.hermes/config.yaml

The CLI handles it:

hermes config set model anthropic/claude-opus-4.6
hermes config set terminal.backend docker

3. Your First Conversation

Start Chatting

hermes            # classic CLI
hermes --tui      # modern TUI (recommended)

You’ll see a welcome banner showing your model, provider, available tools, and loaded skills. Try a prompt that’s specific and easy to verify:

What's my current directory? Show me the top 5 largest files here.

Or something more open-ended:

Summarize what Hermes Agent is and what tools I have available.

What Success Looks Like

  • The welcome banner shows your chosen model and provider
  • Hermes replies without errors
  • It can use a tool if needed (terminal, file read, web search)
  • The conversation continues naturally for multiple turns

Slash Commands

Type / to see an autocomplete dropdown of all in-session commands:

Command What It Does
/help Show all available commands
/tools List enabled tools
/model Switch models interactively
/personality pirate Try a fun personality
/save Save the conversation
/compress Compress conversation context
/retry Regenerate the last response

Session Persistence

Before moving on, verify that sessions save and resume correctly:

hermes --continue    # Resume the most recent session
hermes -c            # Short form

This should bring you right back to your last conversation. If it doesn’t, check which profile you’re in with hermes sessions list.

4. Next Steps & Key Features

Once your base chat is working, layer on more capabilities in this order.

Connect a Messaging Platform

hermes gateway setup

Interactively configure Telegram, Discord, Slack, WhatsApp, or any of the 20+ supported platforms. See the official Messaging Gateway docs for full details.

Install Skills

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. They ship as slash commands and auto-load when needed:

hermes skills browse                      # list everything available
hermes skills search kubernetes           # find skills by keyword
hermes skills install openai/skills/k8s   # install one (security scan runs first)

Configure Tools & Toolsets

hermes tools    # enable/disable tools per platform

Hermes ships with 60+ built-in tools including terminal, file operations, web search, browser automation, code execution, and image generation. Control exactly which are available on each platform.

Set Up Automations

Once your CLI or bot is stable, schedule recurring tasks with the built-in cron system:

hermes cron create --schedule "0 8 * * 1" --task "Send me a weekly summary of my GitHub issues"

Run Hermes Remotely

For production setups, run the agent in a sandboxed environment:

hermes config set terminal.backend docker    # Docker isolation
hermes config set terminal.backend ssh       # Remote server

Recovery Toolkit

When something feels off, run through this sequence:

  1. hermes doctor — diagnostic check
  2. hermes model — verify provider and auth
  3. hermes setup — re-run the setup wizard
  4. hermes sessions list — check session health
  5. hermes --continue — resume last session
  6. hermes gateway status — verify messaging gateway

That order gets you from broken vibes back to a known state fast. See the Troubleshooting guide for deep dives into specific issues.

Quick Reference

Command What It Does
hermes Start interactive chat
hermes --tui Start TUI (recommended)
hermes model Choose LLM provider and model
hermes setup --portal Fastest setup — OAuth + Tool Gateway
hermes tools Configure enabled tools per platform
hermes doctor Diagnose configuration issues
hermes update Update to the latest version
hermes gateway setup Configure messaging platforms
hermes --continue Resume the last session

Deepen Your Knowledge

Continue your learning journey with these dedicated Quick Start guides:

  • CLI Mastery — All CLI flags, session management, TUI features, and slash command reference
  • Providers — Every supported LLM provider, credential pools, local model configuration, model-switching strategies
  • Gateway Setup — Connect Telegram, Discord, Slack, WhatsApp, Signal, Email, Teams, and more
  • Memory & Profiles — Persistent memory, Honcho integrations, cross-session recall, profile management
  • Multi-Agent — Run multiple independent Hermes agents, subagent delegation, parallel workflows
  • Automation — Cron jobs, webhooks, scheduled tasks, event-driven pipelines
  • Troubleshooting — Common failure modes, recovery sequences, diagnostic commands

All guides are verified against the latest Hermes Agent release. Bookmark the official Hermes Agent Documentation for authoritative reference, CLI command listings, and feature deep dives.

Community & Resources

References

📖 Related Reads

  • NiteAgent — AI agent development, frameworks, and production patterns
  • NoCode Insider — AI workflow automation with no-code tools, agents, and APIs

Cross-links automatically generated from Hermes Tutorials.