Initial Configuration Guide

Hermes Agent Setup

After installing, the goal is one clean working chat: connect one model provider, check health, run a small task, and confirm the session resumes. Add messaging, cron, skills, and voice only after that works — the same order the official quickstart recommends.

On a fresh install, hermes setup offers three modes: Quick Setup (Nous Portal sign-in), Full Setup (walk through every provider and tool yourself), and Blank Slate (only a model plus file and terminal tools; everything else off until you enable it). Hermes Desktop has its own first-run onboarding for connecting a provider.

Checked against the official quickstart on September 26, 2026.

Prerequisite: Completed the one-line binary install? If not, run through the Installation Guide first.

Connect Your Model Provider

Pick one path now; you can add others later and switch with /model. For help choosing, see Hermes models and providers; for plans, see Nous Portal.

Option A: Nous Portal (Quick Setup)

Official recommendation

Browser login, no API keys. The free plan covers free models; paid plans (from $20/month) add the wider catalog and the Tool Gateway for web search, image generation, text-to-speech, and cloud browser tools.

$hermes setup --portal

Opens a browser sign-in; the token is stored in ~/.hermes/auth.json. On a headless server, see the official OAuth-over-SSH guide.

Option B: API key or an existing subscription

Pay-As-You-Go

Paste an API key (OpenRouter, Anthropic, OpenAI, Google, DeepSeek, and many more), or sign in with a plan you already pay for — ChatGPT/Codex, Claude Max with extra usage credits, GitHub Copilot, or SuperGrok — from the hermes model menu.

# Pick a provider and sign in or paste a key
$hermes model
$
# Or store a key directly (written to ~/.hermes/.env)
$hermes config set OPENROUTER_API_KEY sk-or-v1-...

Claude Pro cannot be used this way; use an Anthropic API key instead. Details per plan are on the models page.

Option C: Local Offline Models (Ollama / vLLM)

Local Inference

Run inference on your own hardware. Hermes needs a tool-calling model with at least a 64K context window, and many local servers default lower. Cloud tools you enable can still send data off-device.

# Serve a tool-capable model with a 64K+ context window,
# e.g. Ollama with -c 65536 or llama.cpp with --ctx-size 65536
$
# Point Hermes at the local server
$hermes model
# Choose "Custom endpoint"; URL: http://localhost:11434/v1 (Ollama)
# Enter the exact model name; leave the API key blank

Hermes can also download and run llama.cpp models for you from Desktop (Settings → Providers → Local Models; canary builds or the --local flag).

Select Your Primary Model (`hermes model`)

Run the interactive model selector at any time to switch providers and select your default model:

Interactive Model Selector

bash

$hermes model

Where settings are stored

Hermes Agent stores active model configurations in ~/.hermes/config.yaml and environment keys in ~/.hermes/.env. You can inspect or edit these files directly with your preferred editor. On native Windows, the default data folder is %LOCALAPPDATA%\hermes; custom profiles use their own folder.

Run Health Checks (`hermes doctor`)

Check configuration, dependencies, and service health before testing your first prompt:

Run Health Check

bash

$hermes doctor

Doctor Verification: Review any warnings and follow the suggested fixes. Verify model connectivity with the first prompt below.

Execute Your First Agent Prompt

Test interactive chat mode or run a direct one-shot CLI prompt to verify tool execution:

Interactive Chat

$hermes          # classic CLI
$hermes --tui    # full-screen TUI

The banner should show your provider and model. Ask for something checkable, such as “summarize this repo in 5 bullets”, and continue for more than one turn.

One-Shot Command

$hermes chat --oneshot -q "Inspect current directory git status"

Answers the query and exits. Without --oneshot, -q now seeds an interactive session instead.

Confirm the session saved

$hermes --continue   # resumes your most recent session

If resume fails, check you are in the same profile (hermes sessions list).

Where to Go From Here

Once a plain chat works, add one layer at a time. Messaging runs through the gateway — Telegram or Discord.

Models & providers →

Compare access paths and route side jobs to cheaper auxiliary models.

Explore Models Guide

Telegram Bot Gateway →

Chat with Hermes from your phone via @BotFather integration and secure user ID allowlists.

Connect Telegram

Skills →

Install reusable workflows from the hub, or let Hermes save its own.

Explore Skills

Persistent Memory Architecture →

What Hermes remembers between sessions, and why a new fact appears only in the next session.

Understand Memory