Skip to content

Hermes Agent Quickstart

This guide gets you from zero to a working Hermes setup that survives real use. Install, choose a provider, verify a working chat, and know exactly what to do when something breaks.

The Fastest Path

Pick the row that matches your goal:

GoalDo this firstThen do this
I just want Hermes working on my machinehermes setupRun a real chat and verify it responds
I already know my providerhermes modelSave the config, then start chatting
I want a bot or always-on setuphermes gateway setup after CLI worksConnect Telegram, Discord, Slack, or another platform
I want a local or self-hosted modelhermes model → custom endpointVerify the endpoint, model name, and context length
I want multi-provider fallbackhermes model firstAdd routing and fallback only after the base chat works

Rule of thumb: if Hermes cannot complete a normal chat, do not add more features yet. Get one clean conversation working first, then layer on gateway, cron, skills, voice, or routing.


1. Install Hermes Agent

With the Hermes Desktop installer (recommended)

To easily install the command-line and desktop applications, download the Hermes Desktop installer from the official website and run it.

Without Hermes Desktop

For a command-line only install:

Linux / macOS / WSL2 / Android (Termux)

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

Windows (native)

Run in PowerShell:

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

After it finishes, reload your shell:

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

2. Choose a Provider

The single most important setup step. Use hermes model to walk through the choice interactively:

hermes model

Easiest path — Nous Portal: one subscription covers 300+ models plus the Tool Gateway (web search, image generation, TTS, cloud browser). On a fresh install:

hermes setup --portal

Good Defaults

ProviderWhat it isHow to set up
Nous PortalSubscription-based, zero-configOAuth login via hermes model
OpenAI CodexChatGPT OAuth, uses Codex modelsDevice code auth via hermes model
AnthropicClaude models (Max plan or API key)hermes model → OAuth or API key
OpenRouterMulti-provider routingEnter API key
Fireworks AIDirect OpenAI-compatible APIFIREWORKS_API_KEY
Z.AIGLM / Zhipu modelsGLM_API_KEY / ZAI_API_KEY
DeepSeekDirect DeepSeek APIDEEPSEEK_API_KEY
Hugging Face20+ open models via unified routerHF_TOKEN
AWS BedrockClaude, Nova, Llama via Converse APIIAM role or aws configure
Azure FoundryAzure AI Foundry-hosted modelsAZURE_FOUNDRY_API_KEY + base URL
Google AI StudioGemini modelsGOOGLE_API_KEY
xAIGrok modelsXAI_API_KEY
Custom EndpointvLLM, SGLang, Ollama, or any OpenAI-compatible APISet base URL + API key

Hermes requires a model with at least 64,000 tokens of context. Most hosted models meet this easily.

How Settings Are Stored

  • Secrets and tokens → ~/.hermes/.env
  • Non-secret settings → ~/.hermes/config.yaml
hermes config set model anthropic/claude-opus-4.6
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...

3. Run Your First Chat

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

You’ll see a welcome banner with your model, available tools, and skills. Use a prompt that’s specific and easy to verify:

Summarize this repo in 5 bullets and tell me what the main entrypoint is.

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

4. Verify Sessions Work

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

5. Try Key Features

Terminal access

❯ What's my disk usage? Show the top 5 largest directories.

Slash commands

Type / to see an autocomplete dropdown:

CommandWhat it does
/helpShow all available commands
/toolsList available tools
/modelSwitch models interactively
/saveSave the conversation

Multi-line input

Press Alt+Enter, Ctrl+J, or Shift+Enter to add a new line.

Interrupt the agent

Type a new message and press Enter — it interrupts the current task. Ctrl+C also works.

6. Add the Next Layer

Only after the base chat works:

Bot or messaging gateway

hermes gateway setup

Connect Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant, or Microsoft Teams.

Sandboxed terminal

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

Voice mode

cd ~/.hermes/hermes-agent
uv pip install -e ".[voice]"

Then in the CLI: /voice on. Press Ctrl+B to record.

Skills

hermes skills browse                      # list everything available
hermes skills search kubernetes           # find skills by keyword
hermes skills install openai/skills/k8s   # install one

MCP servers

# Add to ~/.hermes/config.yaml
mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

Common Failure Modes

SymptomLikely causeFix
Empty or broken repliesProvider auth or model selection wrongRun hermes model again
Custom endpoint returns garbageWrong base URL or model nameVerify in a separate client first
Gateway starts but nobody can messageBot token or allowlist incompleteRe-run hermes gateway setup
--continue can’t find sessionSwitched profiles or never savedCheck hermes sessions list
Model unavailable or odd fallbackRouting settings too aggressiveKeep routing off until base is stable

Recovery Toolkit

  1. hermes doctor
  2. hermes model
  3. hermes setup
  4. hermes sessions list
  5. hermes --continue
  6. hermes gateway status

Quick Reference

CommandDescription
hermesStart chatting
hermes modelChoose your LLM provider and model
hermes toolsConfigure which tools are enabled per platform
hermes setupFull setup wizard
hermes doctorDiagnose issues
hermes updateUpdate to latest version
hermes gatewayStart the messaging gateway
hermes --continueResume last session

Source: Hermes Agent Documentation