Chapter 3: Initial Setup Wizard

Cuttlefish says: 🦑 "Installed Hermes but not sure how to get it talking? Don't worry — follow the setup wizard and bring the cuttlefish to life!"

1. hermes setup — One-Click Configuration Wizard 🧙

After installing Hermes Agent, the first thing to do is run the interactive setup wizard:

bash

hermes setup

The wizard guides you step by step through all core configuration. The entire process takes about 2-3 minutes.

Wizard Steps

Step	Configuration Item	Description
1	Select LLM Provider	Choose your AI model service provider
2	Enter API Key	Fill in the key you obtained from the provider
3	Select Default Model	Choose from the provider's available models
4	Configure Tool Permissions	Select which tools the Agent can use
5	Confirm and Save	Preview configuration, then write to `~/.hermes/.env`

TIP

You can also re-run hermes setup at any time to modify your configuration. The wizard automatically detects existing settings and pre-fills your current values — no need to start from scratch.

2. Choose an LLM Provider 🏪

This is the most critical step in the wizard — choosing who powers the cuttlefish's brain. Hermes Agent supports multiple LLM providers, each with its own strengths:

Provider Comparison

Provider	Provider ID	Strengths	Free Tier	China Direct	Rating
Nous Portal	`nous`	Official default, works out of the box	✅ Free tier available	❌ Needs proxy	⭐⭐⭐⭐
GLM (Zhipu)	`glm`	Chinese-optimized, strong Chinese language skills	✅ Free tier available	✅ Direct	⭐⭐⭐⭐⭐
OpenRouter	`openrouter`	Aggregates 200+ models, flexible switching	✅ Some models free	❌ Needs proxy	⭐⭐⭐⭐⭐
Kimi (Moonshot)	`kimi`	Long context, excellent Chinese understanding	✅ Free tier available	✅ Direct	⭐⭐⭐⭐
MiniMax	`minimax`	Chinese provider, strong voice capabilities	✅ Free tier available	✅ Direct	⭐⭐⭐
OpenAI	`openai`	GPT series, comprehensive capabilities	❌ Paid only	❌ Needs proxy	⭐⭐⭐⭐
Anthropic	`anthropic`	Claude series, excels at writing and reasoning	❌ Paid only	❌ Needs proxy	⭐⭐⭐⭐

How to Choose?

You're in China and want something that works out of the box?
  └─→ Choose GLM or Kimi (direct connection, generous free tier)

You want the widest selection of models?
  └─→ Choose OpenRouter (200+ models to pick from)

You want to try the officially recommended default?
  └─→ Choose Nous Portal (free tier, works out of the box)

Budget is not an issue, want the strongest capabilities?
  └─→ Choose OpenAI or Anthropic

3. Get an API Key 🔑

After choosing a provider, you need an API Key to allow Hermes to communicate with the LLM service. Here are step-by-step guides for the two most popular providers.

3.1 Get a GLM (Zhipu) API Key

Steps:

Open the Zhipu open platform: https://open.bigmodel.cn
Click "Register/Login" in the upper right corner and complete registration
After logging in, go to the console and click "API Keys" in the left menu
Click "Create API Key" — the system will generate a new key
Copy the displayed API Key (format similar to xxxxxx.xxxxxx)

WARNING

The API Key is only shown in full once after creation! Make sure to copy and save it immediately. If you forget it, you'll need to delete and recreate it.

Configuration example:

bash

# In ~/.hermes/.env (or auto-filled via hermes setup)
LLM_PROVIDER=glm
GLM_API_KEY=***
LLM_MODEL=glm-4-flash

3.2 Get an OpenRouter API Key

Steps:

Open OpenRouter: https://openrouter.ai
Click "Sign In" in the upper right corner, log in with Google or GitHub
After logging in, click "Keys" in the left menu
Click "Create Key", enter a name (e.g., hermes-agent)
Copy the generated API Key (format similar to ***)

TIP

OpenRouter offers some free models (like the Llama series) — no need to top up. Paid models require adding Credits first.

Configuration example:

bash

# In ~/.hermes/.env (or auto-filled via hermes setup)
LLM_PROVIDER=openrouter
OPENROUTER_API_KEY=***
LLM_MODEL=meta-llama/llama-3.1-70b-instruct

3.3 Other Providers Quick Reference

Provider	Registration URL	API Key Prefix
Nous Portal	portal.nousresearch.com	`nous-`
Kimi (Moonshot)	platform.moonshot.cn	`sk-`
MiniMax	api.minimax.chat	Custom
OpenAI	platform.openai.com	`sk-`
Anthropic	console.anthropic.com	`sk-ant-`

4. hermes model — Switch Models 🔄

After configuration, you may want to switch models or providers at any time. No need to re-run hermes setup — just use the hermes model command:

View Current Model

bash

hermes model

Example output:

Current configuration:
  Provider: glm
  Model:    glm-4-flash

List Available Models

bash

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

# List models for a specific provider
hermes model list --provider openrouter

Switch Provider and Model

bash

# Switch to GLM provider
hermes model set --provider glm

# Switch to a specific model
hermes model set --model glm-4-plus

# All at once: switch both provider and model
hermes model set --provider openrouter --model meta-llama/llama-3.1-70b-instruct

Recommended Models

GLM Series:

Model Name	Strengths	Use Case
`glm-4-flash`	Fast, generous free tier	Daily chat, quick Q&A
`glm-4-plus`	Stronger capabilities, better reasoning	Complex tasks, code generation
`glm-4-long`	Ultra-long context	Long document processing

OpenRouter Popular Models:

Model Name	Strengths	Cost
`meta-llama/llama-3.1-70b-instruct`	Open-source benchmark, strong overall	Free
`google/gemini-2.0-flash-exp`	Google's latest model	Free
`anthropic/claude-3.5-sonnet`	Excellent writing and reasoning	Paid
`openai/gpt-4o`	OpenAI's flagship model	Paid

5. hermes tools — Configure Tools 🛠️

Hermes Agent is powerful because it can call various tools to complete tasks. Use the hermes tools command to manage tool permissions:

View Tool Status

bash

hermes tools list

Example output:

Tool list:
  ✅ terminal    Terminal command execution (enabled)
  ✅ file        File read/write operations (enabled)
  ✅ browser     Browser access (enabled)
  ❌ search      Web search (disabled)
  ✅ patch       File editing (enabled)

Enable/Disable Tools

bash

# Enable a single tool
hermes tools enable search

# Disable a single tool
hermes tools disable browser

# Batch enable
hermes tools enable terminal file patch

Tool Descriptions

Tool	ID	Function	Security Note
Terminal	`terminal`	Execute shell commands	⚠️ Can execute arbitrary commands; watch permissions
File	`file`	Read and search files	✅ Read-only, safe
Patch	`patch`	Find-and-replace file editing	⚠️ Modifies file contents
Browser	`browser`	Access web pages, scrape content	✅ Read-only, safe
Search	`search`	Search file contents and names	✅ Read-only, safe

Security Note

The terminal tool allows the Agent to execute arbitrary shell commands, including dangerous operations like deleting files. In untrusted environments, you can disable this tool first:

bash

hermes tools disable terminal

Re-enable it once you trust the Agent's behavior.

6. Configuration File Structure 📁

Hermes Agent's configuration files are stored in the ~/.hermes/ directory. Understanding these files helps you manage and troubleshoot more effectively.

Directory Structure

~/.hermes/
├── .env              # Core configuration (environment variables)
├── config.yaml       # Advanced configuration (optional)
├── history/          # Conversation history
└── plugins/          # Plugin directory

.env File Details

The .env file is Hermes' core configuration, using KEY=VALUE format:

bash

# ===== LLM Configuration =====
LLM_PROVIDER=glm              # Current provider
LLM_MODEL=glm-4-flash         # Current model
LLM_API_KEY=***               # Generic API Key (used by some providers)

# ===== Provider-Specific Keys =====
GLM_API_KEY=***               # Zhipu API Key
OPENROUTER_API_KEY=***        # OpenRouter API Key
OPENAI_API_KEY=***            # OpenAI API Key
ANTHROPIC_API_KEY=your-a...-key  # Anthropic API Key
NOUS_API_KEY=***              # Nous Portal API Key
KIMI_API_KEY=***              # Kimi API Key
MINIMAX_API_KEY=***           # MiniMax API Key

# ===== Tool Configuration =====
TOOLS_TERMINAL=true           # Enable terminal tool
TOOLS_FILE=true               # Enable file tool
TOOLS_PATCH=true              # Enable patch tool
TOOLS_BROWSER=true            # Enable browser tool
TOOLS_SEARCH=true             # Enable search tool

config.yaml (Advanced Configuration)

config.yaml is used for more granular behavior tuning. You typically don't need to edit it manually:

yaml

# ~/.hermes/config.yaml example
agent:
  max_turns: 30               # Max execution turns per task
  timeout: 300                # Timeout in seconds

llm:
  temperature: 0.7            # Generation temperature (0-1, higher = more random)
  max_tokens: 4096            # Max tokens per response

logging:
  level: info                 # Log level: debug, info, warning, error
  file: ~/.hermes/hermes.log  # Log file path

Cuttlefish Tip 🦑

In most cases, hermes setup and the hermes model/hermes tools commands handle all configuration. You only need to manually edit these files when fine-tuning Agent behavior.

Manually Edit Configuration Files

If you want to directly edit the .env file:

bash

# Open with your preferred editor
nano ~/.hermes/.env
# or
vim ~/.hermes/.env
# or
code ~/.hermes/.env

After saving changes, Hermes automatically loads the new configuration — no restart needed.

7. hermes doctor — Health Check 🩺

After configuration is complete, it's strongly recommended to run a health check to confirm everything is working:

bash

hermes doctor

What does doctor check?

Check Item	Description	Pass Criteria
🐍 Python environment	Python version and virtual environment	Python >= 3.10
📁 Configuration directory	Whether `~/.hermes/` directory exists	Directory exists and is read/writable
🔑 API Key	Whether a valid API Key is configured	Key is not empty and format is correct
🌐 Network connectivity	Can it reach the LLM service endpoint	HTTP request returns normally
🤖 Model availability	Can it successfully call the specified model	API call returns no errors
🛠️ Tool status	Are enabled tools working	All dependencies present
📦 Dependency integrity	Are required Python packages installed	All package versions match

Example of Normal Output

🩺 Hermes Agent Health Check

✅ Python environment     — Python 3.12.0 (venv)
✅ Configuration directory — ~/.hermes/ exists and is read/writable
✅ API Key                — GLM_API_KEY configured
✅ Network connectivity   — Successfully connected to open.bigmodel.cn
✅ Model availability     — glm-4-flash calling normally
✅ Tool status            — 4/5 enabled, all working
✅ Dependency integrity   — All dependencies installed

🎉 All good! Cuttlefish is ready.

What If There's a Problem?

If any check shows ❌, hermes doctor will provide specific fix suggestions. Common issues:

❌ API Key — Not configured
   Suggestion: Run hermes setup or manually edit ~/.hermes/.env

❌ Network connectivity — Cannot connect to open.bigmodel.cn
   Suggestion: Check network connection; users in China can access Zhipu without a proxy

❌ Model availability — API returns 401 Unauthorized
   Suggestion: API Key is invalid or expired, please obtain a new one

8. Quick Test: Your First Conversation 💬

With all configuration done, it's time to chat with the cuttlefish!

Start Hermes

bash

hermes

You'll see the welcome screen:

🦑 Hermes Agent v0.x.x
   Provider: glm | Model: glm-4-flash
   Tools: terminal, file, patch, browser, search

>

Try These Prompts

> Hello, Cuttlefish! Please introduce yourself

> Show me the current system information

> List the files in the current directory

> Write a quicksort algorithm in Python

Cuttlefish Tip 🦑

The first conversation may be a bit slow (model cold start), but subsequent ones will be much faster. If there's no response for a long time, press Ctrl+C to cancel, then run hermes doctor to check the network.

Common Interactive Commands

Command	Description
`/help`	View help
`/model`	View current model
`/tools`	View tool status
`/clear`	Clear conversation history
`/exit` or `Ctrl+C`	Exit Hermes

Summary

In this chapter we completed the core configuration of Hermes Agent, bringing the cuttlefish to life:

hermes setup — Interactive wizard for step-by-step initial configuration
Choose LLM provider — Select the right AI brain based on your scenario
Get API Key — Detailed registration process for GLM and OpenRouter
hermes model — Switch providers and models at any time
hermes tools — Flexible tool permission management
Configuration files — Understand the structure of ~/.hermes/.env and config.yaml
hermes doctor — One-command check for all configuration
First conversation — Say hi to the cuttlefish and verify everything works

Cuttlefish 🦑 now has a brain, tools, and memory. Next, let's connect it to your chat platform!

👉 Next Chapter: Chapter 4: Chat Platform Integration

Chapter 3: Initial Setup Wizard ​

1. hermes setup — One-Click Configuration Wizard 🧙 ​

Wizard Steps ​

2. Choose an LLM Provider 🏪 ​

Provider Comparison ​

How to Choose? ​

3. Get an API Key 🔑 ​

3.1 Get a GLM (Zhipu) API Key ​

3.2 Get an OpenRouter API Key ​

3.3 Other Providers Quick Reference ​

4. hermes model — Switch Models 🔄 ​

View Current Model ​

List Available Models ​

Switch Provider and Model ​

Recommended Models ​

5. hermes tools — Configure Tools 🛠️ ​

View Tool Status ​

Enable/Disable Tools ​

Tool Descriptions ​

6. Configuration File Structure 📁 ​

Directory Structure ​

.env File Details ​

config.yaml (Advanced Configuration) ​

Manually Edit Configuration Files ​

7. hermes doctor — Health Check 🩺 ​

What does doctor check? ​

Example of Normal Output ​

What If There's a Problem? ​

8. Quick Test: Your First Conversation 💬 ​

Start Hermes ​

Try These Prompts ​

Common Interactive Commands ​

Summary ​

Chapter 3: Initial Setup Wizard

1. hermes setup — One-Click Configuration Wizard 🧙

Wizard Steps

2. Choose an LLM Provider 🏪

Provider Comparison

How to Choose?

3. Get an API Key 🔑

3.1 Get a GLM (Zhipu) API Key

3.2 Get an OpenRouter API Key

3.3 Other Providers Quick Reference

4. hermes model — Switch Models 🔄

View Current Model

List Available Models

Switch Provider and Model

Recommended Models

5. hermes tools — Configure Tools 🛠️

View Tool Status

Enable/Disable Tools

Tool Descriptions

6. Configuration File Structure 📁

Directory Structure

.env File Details

config.yaml (Advanced Configuration)

Manually Edit Configuration Files

7. hermes doctor — Health Check 🩺

What does doctor check?

Example of Normal Output

What If There's a Problem?

8. Quick Test: Your First Conversation 💬

Start Hermes

Try These Prompts

Common Interactive Commands

Summary