Hermes Agent configuration file

After installation, all configuration and data are stored in~/.hermes/Below:

~/.hermes/
├── config.yaml      # 主配置文件（模型、工具、终端后端等）
├── .env             # API 密钥和 Secret（不提交到版本库）
├── auth.json        # OAuth 凭据（Nous Portal 等）
├── SOUL.md          # Agent 人格设定文件
├── memories/        # 持久记忆（MEMORY.md、USER.md）
├── skills/          # 技能文件（Agent 自动创建和管理）
├── cron/            # 定时任务配置
├── sessions/        # 网关会话记录
└── logs/            # 日志（API 密钥自动脱敏）

Important Principles：

Secrets (API keys, tokens, passwords)→ Store.env
General configuration (models, tools, terminal backends, etc.)→ Storeconfig.yaml
Usagehermes config set KEY VALUECommands automatically route to the correct file

Select model provider

Run the following command to enter interactive selection:

hermes model

Recommended path: Nous Portal (easiest)

One subscription covers 300+ models + Tool Gateway (web search, image generation, TTS, cloud browser), no need to apply for multiple API keys separately:

hermes setup

After execution, log in via OAuth, and provider configuration and Tool Gateway activation are completed automatically.

Overview of common providers

provider	Features	Configuration Method
Nous Portal	Subscription-based, 300+ models, Tool Gateway	`hermes setup --portal`OAuth login
Anthropic	Claude series, Max subscription supports OAuth	`ANTHROPIC_API_KEY`or OAuth
OpenAI Codex	ChatGPT OAuth, Codex model	`hermes model`→ OAuth device code
OpenRouter	Multi-provider routing, 200+ models	`OPENROUTER_API_KEY`
xAI Grok OAuth	SuperGrok / Premium+ subscription, no API Key required	`hermes model` → xAI Grok OAuth
GitHub Copilot	Copilot subscription (GPT, Claude, Gemini)	`hermes model` → OAuth
Google AI Studio	Gemini Series	`GOOGLE_API_KEY`
DeepSeek	DeepSeek series	`DEEPSEEK_API_KEY`
Local models (Ollama)	Fully local, no cost	Set custom Base URL

Model context window requirements: Hermes requires the model to support at least64,000 tokenscontext. When using local models, ensure that sufficient context size is set in the startup parameters (e.g.--ctx-size 65536）。

Switch provider

You can switch at any time without modifying any code:

hermes model

Three Setup modes

First Runhermes setupAt that point, you will be prompted to select an initialization mode:

Mode 1: Quick Setup (Nous Portal)

Free OAuth login, automatically configures models + Tool Gateway (web search, image generation, TTS, browser).Recommended for new users.

Mode 2: Full Setup

Manually configure providers, tool sets, messaging platforms, etc. one by one. Suitable for users with clear requirements and their own API keys.

Mode 3: Blank Slate (Blank Starting Point)

Keep only the minimal runtime set (providers, file tools, terminal tools), everything else is off. Suitable for advanced users who need precise control over the Agent's capability boundaries. Blank mode explicitly writes configuration to preventhermes updatefrom automatically enabling new features afterward.

Start the first conversation

After configuration is complete, start Hermes:

hermes          # 经典 CLI 模式
hermes --tui    # 现代 TUI 模式（推荐，支持鼠标、弹窗等）

After startup, a welcome banner will be displayed, showing the current model, available tools, and loaded skills.

Verify everything works normally

Test with a simple but specific prompt:

Check my current directory, tell me what files are in it, and identify the main project entry file.

Success Indicator：

The banner correctly displays the model/provider you selected
The Agent responds normally without any error messages
Can call tools when needed (terminal, file reading, etc.)
Conversations can continue for more than one turn

Verify session recovery

Confirm cross-session continuity works correctly:

Check my current directory, tell me what files are in it, and identify the main project entry file.

Basic TUI interface operations

Runhermes --tuiAfter entering modern TUI mode, common operations:

Operation	Shortcuts
Send Message	`Enter`
Line break for multi-line input	`Alt+Enter`or`Ctrl+J`
Interrupt the Agent's current task	After directly entering a new message`Enter`
Forced Interruption	`Ctrl+C`
View all commands	Input`/`Trigger auto-completion

Core slash commands

Command	Function
`/help`	Show all available commands
`/tools`	List currently enabled tools
`/model`	Switch models at runtime
`/memory`	View and manage Agent memory
`/skills`	View and manage skills
`/save`	Save current conversation
`/new`	Start a new session (keep current settings)
`/verbose`	Switch tool call verbose output level
`/voice on`	Enable voice input mode

Terminal execution backend configuration

Hermes supports six terminal execution environments, determining where the Agent's Shell commands run:

Backend	Where commands are executed	Isolation Level	Applicable scenarios
`local`(Default)	Execute directly on the local machine	None	Development, personal use
`docker`	Inside a Docker container	Complete Isolation	Secure sandbox, CI/CD
`ssh`	Remote server	Network boundaries	Remote development, high-performance machines
`modal`	Modal cloud sandbox	Full (cloud VM)	Temporary cloud computing, evaluation
`daytona`	Daytona workspace	Full (cloud container)	Managed cloud development environment
`singularity`	Singularity Container	Namespace isolation	HPC clusters, shared machines

Switch to Docker backend (recommended for production)

hermes config set terminal.backend docker

Or edit directly~/.hermes/config.yaml：

terminal:
  backend: docker
  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"

Safety Instructions: DefaultlocalThe backend gives the Agent the same filesystem permissions as you. If you want to limit the Agent's scope of operations, switch todockerThe backend is the simplest and most effective way.

Toolset management

Hermes groups 70+ built-in tools into 28 tool sets, which can be enabled or disabled as needed:

hermes tools    # 打开可视化工具集管理界面（curses UI）

Main toolsets

toolset	Included Capabilities
`filesystem`	File read/write, directory operations
`terminal`	Shell command execution
`web`	Web search, content extraction
`browser`	Full browser automation (requires Playwright)
`code`	Code execution (`execute_code`tool)
`vision`	Image Analysis
`audio`	Speech-to-text, TTS
`memory`	Memory management tools
`skills`	Skill management tools
`mcp`	MCP server toolset (dynamic)

Disable a specific toolset: This tool set completely disappears from the system prompt, not just disabled—this saves tokens and prevents the Agent from misusing tools it shouldn't use.

Common configuration management commands

# 查看当前完整配置
hermes config

# 用编辑器打开 config.yaml
hermes config edit

# 设置单个配置值（自动路由到正确文件）
hermes config set model anthropic/claude-sonnet-4-6
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...   # 自动存入 .env

# 检查是否有新版本引入的配置项未填写
hermes config check

# 交互式补全缺失配置
hermes config migrate

# 诊断所有配置问题
hermes doctor

# 更新到最新版本
hermes update

Common troubleshooting

Question 1:`hermes: command not found`

# 刷新 Shell 配置
source ~/.bashrc   # 或 source ~/.zshrc

# 如果仍然找不到，检查 PATH
echo $PATH
# 确保 ~/.local/bin 在其中
export PATH="$HOME/.local/bin:$PATH"

Question 2:`API key not set`/ Model unresponsive

# 重新配置提供商
hermes model

# 或直接设置 API Key
hermes config set OPENROUTER_API_KEY sk-or-...

Issue 3: Empty or garbled replies

It may be due to incorrect provider authentication or model selection:

# 重新选择模型
hermes model

# 全面诊断
hermes doctor

Issue 4: Insufficient context window error

Hermes requires the model to support at least 64K Token context. Switch to a model with a larger context, or increase the context parameter when using local models (e.g., Ollama:OLLAMA_NUM_CTX=65536）。

Question 5:`hermes --continue`Cannot find old conversations

# 查看所有会话
hermes sessions list

# 确认当前 Profile
hermes profile list

Universal recovery toolkit

If you encounter any strange issues, follow the steps below in order:

hermes doctor           # 1. 诊断
hermes model            # 2. 检查模型配置
hermes setup            # 3. 重新向导配置
hermes sessions list    # 4. 查看会话状态
hermes --continue       # 5. 尝试恢复会话
hermes gateway status   # 6. 检查网关状态（如已启用）

Advanced configuration preview

After completing the basic installation, the following features can be enabled as needed (detailed in subsequent chapters):

Connect to messaging platform

hermes gateway setup    # 交互式配置 Telegram、Discord、Slack 等
hermes gateway          # 启动消息网关

Enable voice mode

# 安装语音依赖
cd ~/.hermes/hermes-agent
uv pip install -e ".[voice]"

# 在 CLI 中启用
/voice on
# 按 Ctrl+B 开始录音

Connect MCP servers

In~/.hermes/config.yamlAdd in:

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

hermes mcp    # 交互式管理 MCP 服务器

Editor integration (ACP)

hermes acp    # 启动编辑器 Agent 模式（VS Code / Zed / JetBrains）

Quick command reference

Command	Description
`hermes`	Start CLI conversation
`hermes --tui`	Start TUI conversation (recommended)
`hermes desktop`	Launch desktop app
`hermes model`	Select/Switch LLM provider and model
`hermes setup`	Full Setup wizard
`hermes setup --portal`	Quick configuration of Nous Portal
`hermes tools`	Configure toolset
`hermes doctor`	Diagnose configuration issues
`hermes update`	Update to the latest version
`hermes gateway`	Start message gateway
`hermes gateway setup`	Configure messaging platform
`hermes --continue`	Resume most recent conversation
`hermes config set KEY VAL`	Set configuration items
`hermes sessions list`	View conversation history
`hermes profile list`	View Agent Profile

other extensions