Hermes Agent Deep Deployment and Usage Tutorial

The AI Agent landscape has evolved rapidly. Among the most talked-about open-source frameworks in 2026, Hermes Agent — developed by Nous Research — has emerged as a standout project, gaining over 50,000 GitHub stars within weeks of its launch. Unlike traditional chatbot wrappers or simple CLI tools, Hermes Agent is a self-improving AI Agent runtime designed to learn from every interaction, build skills autonomously, and maintain long-term memory across sessions.

This tutorial covers everything from initial installation to advanced production deployment. Whether you are a solo developer experimenting locally or a team deploying Hermes Agent at scale with Docker, messaging platform integrations, and API endpoints, this guide will walk you through every step — with real commands, configuration files, and expert recommendations.

What Makes Hermes Agent Different

Before diving into installation, it is important to understand what sets Hermes Agent apart from other frameworks like OpenClaw.

Core Design Philosophy

Most AI Agent frameworks are stateless — they forget everything after each session, require manual skill installation, and cannot improve over time. Hermes Agent flips this paradigm with three core mechanisms:

Automatic Memory Writing: Every interaction is analyzed and stored. The agent remembers your preferences, past decisions, and context across sessions.
Autonomous Skill Extraction: When the agent successfully completes a complex task, it automatically distills the workflow into a reusable SKILL.md file.
Self-Optimizing Workflows: Through an internal learning loop, the agent refines its approaches over time — no manual prompt engineering or fine-tuning required.

Quick Comparison: Hermes Agent vs. OpenClaw

Technology Stack: Hermes Agent uses Python 3.11 with the uv package manager. OpenClaw uses Node.js (≥22).
Deployment Philosophy: Hermes Agent is designed as a server-resident, self-evolving system with serverless support. OpenClaw follows a local-first, single-user approach.
Memory System: Hermes Agent uses SQLite with FTS5 full-text search plus 8 external memory plugins (Hindsight, Mem0, etc.). OpenClaw relies on flat-file storage.
Skill System: Hermes Agent auto-creates skills from experience. OpenClaw requires manual installation from ClawHub marketplace.
Cost Model: Hermes Agent supports serverless backends (Daytona, Modal) for near-zero idle cost. OpenClaw typically runs on always-on local machines.

Bottom line: If you want a plug-and-play local assistant, OpenClaw is fine. If you want an agent that grows smarter with every interaction and can scale to production, Hermes Agent is the stronger choice.

System Requirements

Before installing Hermes Agent, ensure your environment meets these prerequisites:

Operating System: Linux (Ubuntu/Debian recommended), macOS, Windows via WSL2, or Android Termux
Python: 3.10 or higher (3.11 recommended)
RAM: Minimum 4 GB for API-based usage; 16 GB+ for running local models
Network: Must be able to access GitHub and your chosen LLM provider's API endpoint
Disk Space: At least 2 GB for the agent itself; more for Docker images if using containerized deployment

Critical Warning: Do not run the installation script with sudo. Use a normal user account. Running with elevated privileges causes permission conflicts that are difficult to resolve later.

Installation Methods

Hermes Agent supports multiple installation approaches. Choose the one that best fits your use case.

Method 1: One-Line Install Script (Recommended for Local Testing)

This is the fastest way to get started:

bash

# Download and execute the official installation script
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
 
# Reload environment variables
source ~/.bashrc
 
# Verify installation
hermes --version
 
# Expected output: hermes v0.8.0 (v2026.4.8) or later

The script automatically handles Python dependency installation, path configuration, and triggers the initial setup wizard.

If the hermes command is not found after installation:

bash

# Check if ~/.local/bin is in your PATH
echo $PATH | grep local
 
# If not, add it manually
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Method 2: Docker Deployment (Recommended for Servers)

Docker provides environment consistency and isolation, making it ideal for server deployments.

Step 1: Create the persistent data directory

bash

1	`mkdir -p ~/.hermes`

Step 2: Initialize configuration interactively

bash

1	`docker run -it --rm \`
2	`- v ~/.hermes:/opt/data \`
3	`nousresearch/hermes-agent setup`

Step 3: Run the gateway in the background

bash

docker run -d \
  - -name hermes \
  - -restart unless-stopped \
  - v ~/.hermes:/opt/data \
  - p 8642:8642 \
  nousresearch/hermes-agent gateway run

Step 4: Verify the service is running

bash

# Check container status
docker ps
 
# Check health endpoint
curl http://127.0.0.1:8642/health
 
# Expected: {"status":"ok"}
 
# View logs
docker logs -f hermes

Method 3: Docker Compose (Recommended for Production)

For long-running production deployments, Docker Compose offers better maintainability:

Create docker-compose.yml:

yaml

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    ports:
      - "8642:8642"   # API Server port
      - "9119:9119"   # Dashboard port
    volumes:
      - ${HOME}/.hermes:/opt/data
    environment:
      HERMES_DASHBOARD: "1"
      API_SERVER_ENABLED: "true"
      API_SERVER_HOST: "0.0.0.0"
      API_SERVER_KEY: "${API_SERVER_KEY}"
      API_SERVER_CORS_ORIGINS: "https://chat.example.com"
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: "2.0"

Operational commands:

bash

# Start services
docker compose up -d
 
# View logs
docker logs -f hermes
 
# Stop services
docker compose down
 
# Upgrade to latest version (backup first!)
tar -czf hermes-backup-$(date +%F).tar.gz ~/.hermes
docker compose pull
docker compose up -d

Important: The ~/.hermes/ directory contains all configuration, memory, skills, sessions, and logs. Always mount it as a volume — otherwise, everything is lost when the container is recreated.

Method 4: Manual Installation (For Network-Restricted Environments)

If your server cannot access GitHub directly:

bash

# Clone the repository (use a mirror if needed)
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
 
# Install dependencies
pip install -r requirements.txt
 
# Run directly
python -m hermes

Method 5: Cloud Marketplace (Fastest for Non-Technical Users)

Several cloud providers now offer pre-built Hermes Agent images. For example, Tencent Cloud Lighthouse offers a Hermes Agent template:

Purchase a 2-core 4 GB lightweight application server
Select the Hermes Agent image template
Log in via the web terminal as the lighthouse user
Run hermes setup to configure your model and API key

This eliminates all manual installation steps and is ideal for beginners.

Initial Configuration

After installation, Hermes Agent needs to be configured with a language model provider, tools, and optionally a messaging gateway.

Step 1: Run the Setup Wizard

For first-time users, the complete wizard is recommended:

bash

1	`hermes setup`

The wizard will walk you through:

Model provider selection
API key configuration
Tool enablement
Messaging gateway setup (optional, can be skipped)

Use the up/down arrow keys to navigate and Enter to confirm selections.

Step 2: Configure Your LLM Provider

Hermes Agent supports 200+ models through multiple providers. You can configure this separately:

bash

1	`hermes model`

Supported providers include:

Nous Portal: Official Hermes-series models with native function calling support
OpenRouter: Access to 200+ models including Claude, GPT, Gemini
OpenAI: GPT-4o, GPT-4o-mini, and others
Kimi: Long-context model, accessible from China
MiniMax: Multimodal Chinese model
Z.AI (GLM): Zhipu AI's GLM series
DeepSeek, Qwen, Doubao: Other popular Chinese providers

Example: Configuring with an OpenAI-compatible provider

If you are using a third-party OpenAI-compatible aggregation platform, configure it via environment variables:

bash

1	`# Edit the environment file`
2	`vim ~/.hermes/.env`

Add these lines:

env

1	`OPENAI_API_KEY=sk-your-api-key-here`
2	`OPENAI_BASE_URL=https://your-provider.com/v1`

Then set the model in config:

bash

1	`hermes config set model.provider openai`
2	`hermes config set model.default gpt-4o`

Common Mistake: When setting OPENAI_BASE_URL, include only the base path up to /v1. Do not append /chat/completions — the SDK concatenates this automatically.

Correct: https://api.provider.com/v1 Incorrect: https://api.provider.com/v1/chat/completions

Step 3: Configure Tools

bash

1	`hermes tools`

This lets you enable or disable built-in tool modules:

File operations (read, write, search)
Shell command execution
Network requests
Browser automation
And more

For production use, be selective about which tools to enable. Only activate what your use case requires to minimize security exposure.

Step 4: Verify Your Setup

bash

# Run environment diagnostics
hermes doctor
 
# Start an interactive session to test
hermes

Send a test message. If the agent responds correctly, your setup is working.

Understanding the Configuration Files

Hermes Agent stores all its data in ~/.hermes/. Understanding this directory structure is essential for troubleshooting and production management:

code

~/.hermes/
├── config.yaml       # Main configuration file
├── .env              # Environment variables (API keys, secrets)
├── auth.json         # Authentication data
├── SOUL.md           # Agent identity and personality definition
├── memories/         # Long-term memory storage
├── skills/           # Auto-generated and custom skills
├── cron/             # Scheduled task definitions
├── sessions/         # Conversation history
├── logs/             # Runtime logs
└── state.db          # SQLite database (FTS5 index, state)

The config.yaml File

This is the primary configuration file. Configuration priority follows this order:

CLI parameters > config.yaml > .env > defaults

Here is a well-documented example:

yaml

# Model configuration
model:
  provider: openai          # LLM provider identifier
  default: gpt-4o           # Default model to use
 
# Terminal / execution backend
terminal:
  backend: docker           # Options: local, docker, ssh, modal, daytona, singularity
  timeout: 180              # Execution timeout in seconds
  container_persistent: true # Keep containers alive between tasks
 
# Approval and safety
approvals:
  mode: smart               # Options: none, smart, always
  timeout: 60               # Auto-approve timeout
 
# Long-term memory
memory:
  memory_enabled: true      # Enable cross-session memory
  user_profile_enabled: true # Build user preference profile
  memory_char_limit: 2200   # Character limit per memory entry
 
# Security hardening
security:
  allow_private_urls: false  # Block SSRF and internal network access

Key recommendations for production:

Set terminal.backend to docker — never let the agent execute directly on the host in production
Keep approvals.mode on smart — do not disable the approval mechanism
Set allow_private_urls to false to prevent SSRF attacks
Enable memory for the best self-improvement experience

The .env File

Store all sensitive credentials here:

env

# LLM Provider credentials
OPENAI_API_KEY=sk-your-api-key
OPENAI_BASE_URL=https://api.openai.com/v1
 
# API Server configuration
API_SERVER_ENABLED=true
API_SERVER_PORT=8642
API_SERVER_HOST=0.0.0.0
API_SERVER_KEY=your-secure-random-string-here
API_SERVER_CORS_ORIGINS=https://your-frontend.com
 
# Dashboard configuration
HERMES_DASHBOARD=1
HERMES_DASHBOARD_HOST=0.0.0.0
HERMES_DASHBOARD_PORT=9119
 
# Messaging platform tokens (examples)
TELEGRAM_BOT_TOKEN=123456:ABC-DEF
FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=your_secret

Critical distinction: OPENAI_API_KEY is what Hermes uses to call the LLM. API_SERVER_KEY is what external applications use to call Hermes. Do not confuse them.

Execution Backends Explained

One of Hermes Agent's most powerful features is its flexible execution backend system. Each backend determines where and how the agent executes tasks:

local: Direct execution on the host machine. Good for development and testing. Not recommended for production because the agent has full host access.
docker: Tasks run inside isolated containers. This is the recommended production backend because it limits the agent's blast radius.
ssh: Execute tasks on a remote server via SSH. Useful for managing remote infrastructure.
daytona: Serverless persistent environments. Cost-effective at roughly $5/month for a basic VPS. Ideal for intermittent workloads.
modal: Cloud function execution with pay-per-use billing. Best for bursty, compute-intensive tasks.
singularity: Designed for HPC (High-Performance Computing) clusters and research environments.

To switch backends:

bash

1	`hermes config set terminal.backend docker`

Messaging Platform Integrations

Hermes Agent can connect to 15+ messaging platforms through its gateway system, making it accessible from tools your team already uses.

Setting Up the Gateway

bash

# Interactive gateway setup
hermes gateway setup
 
# Or start the gateway directly
hermes gateway run

Telegram Integration

Create a bot via @BotFather on Telegram and obtain the bot token
Configure the token:

bash

1	`hermes config set TELEGRAM_BOT_TOKEN "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"`

Start the gateway:

bash

1	`hermes gateway run`

Send a message to your bot on Telegram to verify connectivity

Tip: If you plan to use Telegram, deploy your server in an overseas region (e.g., Singapore) to avoid connectivity issues with Telegram's API.

Feishu (Lark) Integration

Go to the Feishu Open Platform and create an application
Enable Bot capability for the application
Copy the App ID and App Secret
Edit ~/.hermes/.env:

env

FEISHU_APP_ID=cli_xxxxxxxx
FEISHU_APP_SECRET=your_app_secret
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket
FEISHU_GROUP_POLICY=allowlist
FEISHU_ALLOWED_USERS=ou_your_open_id

Ensure ~/.hermes/config.yaml includes:

yaml

group_sessions_per_user: true
 
platforms:
  feishu:
    extra:
      ws_reconnect_interval: 120
      ws_ping_interval: 30

The group_sessions_per_user: true setting ensures different users in the same group maintain separate conversation contexts.

Start the gateway and verify:

bash

1	`hermes gateway run`
2
3	`# Check gateway state`
4	`cat ~/.hermes/gateway_state.json`

A successful connection shows:

json

{
  "gateway_state": "running",
  "platforms": {
    "feishu": {
      "state": "connected"
    }
  }
}

Other Supported Platforms

The same gateway system supports Discord, Slack, WhatsApp, Signal, WeChat, Enterprise WeChat (WeCom), DingTalk, and QQ. The configuration pattern is similar for each — obtain the platform's bot credentials and add them to your `.env` file.

The API Server

Hermes Agent can expose an OpenAI-compatible API server, allowing any application that speaks the OpenAI protocol to use your agent as a backend.

Enabling the API Server

Add these settings to your .env:

env

API_SERVER_ENABLED=true
API_SERVER_PORT=8642
API_SERVER_HOST=0.0.0.0
API_SERVER_KEY=your-secure-random-key
API_SERVER_CORS_ORIGINS=https://your-frontend.com

Calling the API

Example: Direct call to Hermes Agent's API server

bash

curl http://localhost:8642/v1/chat/completions \
  - H "Authorization: Bearer your-secure-random-key" \
  - H "Content-Type: application/json" \
  - d '{
    "model": "hermes",
    "messages": [
      {"role": "user", "content": "Analyze the system logs for errors in the last hour"}
    ]
  }'

This means you can point tools like ChatGPT-next-web, LobeChat, or any OpenAI-compatible client directly at your Hermes Agent instance.

Scheduled Tasks with Built-In Cron

Hermes Agent includes a natural language task scheduler — one of its most practical features for automation.

Creating Scheduled Tasks

bash

# Example: Daily morning email summary
hermes schedule "Every day at 8 AM, summarize yesterday's emails and send to Telegram"
 
# Example: Weekly report generation
hermes schedule "Every Friday at 5 PM, generate a weekly project status report"

Managing Tasks

bash

# List all scheduled tasks
hermes schedule list
 
# Remove a specific task
hermes schedule remove <task-id>

The agent interprets your natural language description and converts it into a cron schedule. This eliminates the need to write raw cron expressions for most use cases.

Self-Improvement: Memory and Skills Deep Dive

The most distinctive aspect of Hermes Agent is its closed-loop learning system. Understanding how it works helps you get the most out of the platform.

How Memory Works

Hermes Agent uses SQLite with FTS5 full-text search as its primary memory engine, supplemented by 8 external memory plugins. Every conversation contributes to three types of memory:

User Profile (USER.md): Preferences, communication style, frequently used tools — capped at a reasonable character limit to prevent bloat
Session Memory: Context from recent conversations, retrievable via semantic search
Episodic Memory: Significant events and decisions stored with timestamps

The memory system operates on a retrieval-augmented basis. When you start a new conversation, the agent automatically searches its memory for relevant context before responding. This is why it feels like talking to someone who remembers you, rather than starting from scratch each time.

How Skills Work

When the agent successfully completes a complex multi-step task, it can automatically extract the workflow into a SKILL.md file. Skills are loaded progressively to save tokens:

List view: A summary of all available skills
Full content view: The complete skill definition when selected
Specific file view: Individual files within a skill when needed

This three-tier loading mechanism is a clever optimization. Instead of stuffing all skills into every prompt (which would waste tokens and degrade performance), the agent loads only what it needs, when it needs it.

Customizing the Agent Identity

The SOUL.md file defines your agent's personality, values, and behavioral guidelines:

markdown

# My Agent Identity
 
## Core Values
- Always prioritize accuracy over speed
- Explain reasoning before giving answers
- Ask for clarification when requests are ambiguous
 
## Communication Style
- Professional but approachable
- Use bullet points for multi-step answers
- Include code examples when discussing technical topics
 
## Domain Expertise
- Python backend development
- DevOps and CI/CD pipelines
- Data analysis with pandas and SQL

You can edit this file directly:

bash

1	`vim ~/.hermes/SOUL.md`

Migrating from OpenClaw

If you are currently using OpenClaw, Hermes Agent provides a built-in migration tool:

bash

1	`hermes migrate --from openclaw`

This automatically transfers:

SOUL.md: Your agent's identity configuration
Memory: All stored memories and user profiles
Skills: Installed skill definitions
API Keys: Provider credentials

The migration is designed to be seamless — your new Hermes Agent will pick up right where your OpenClaw instance left off, but with the added benefit of self-improvement capabilities.

Production Deployment Best Practices

Security Hardening

Always use the Docker backend in production. Never allow the agent to execute commands directly on the host.
Keep allow_private_urls: false to prevent SSRF attacks.
Use approvals.mode: smart at minimum. The none mode disables all safety confirmations.
Restrict API server access with a strong API_SERVER_KEY and proper CORS origins.
Limit messaging platform access using allowlists (FEISHU_ALLOWED_USERS, etc.).

Data Persistence and Backup

The ~/.hermes/ directory is everything. Implement a regular backup schedule:

bash

# Create a dated backup
tar -czf /backup/hermes-$(date +%F).tar.gz ~/.hermes/
 
# Automate with cron (add to crontab -e)
0 2 * * * tar -czf /backup/hermes-$(date +\%F).tar.gz ~/.hermes/

Resource Management

In Docker Compose, set explicit resource limits:

yaml

deploy:
  resources:
    limits:
      memory: 4G
      cpus: "2.0"

Monitor actual usage with docker stats hermes and adjust as needed. The 4 GB memory limit is a good starting point for most workloads.

Monitoring

Use the built-in health endpoint: curl http://localhost:8642/health
Check the dashboard at http://localhost:9119 for token usage analytics, session history, and logs
Set up external monitoring (e.g., UptimeRobot) to alert you if the health endpoint goes down

Reverse Proxy Setup

For production, place Hermes Agent behind a reverse proxy (Nginx, Caddy, or Traefik) with TLS:

nginx

server {
    listen 443 ssl;
    server_name agent.yourcompany.com;
 
    ssl_certificate /etc/letsencrypt/live/agent.yourcompany.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/agent.yourcompany.com/privkey.pem;
 
    location / {
        proxy_pass http://127.0.0.1:8642;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Common Issues and Troubleshooting

Problem: hermes command not found after installation

The installer adds the binary path to ~/.bashrc. Run source ~/.bashrc or open a new terminal. If the problem persists, verify that ~/.local/bin is in your $PATH.

Problem: Agent not responding to messages on Telegram/Feishu

Check the gateway state file at ~/.hermes/gateway_state.json. If the platform shows "disconnected", verify your bot token or app credentials. For Telegram, ensure your server is in a region that can reach Telegram's API.

Problem: Docker container keeps restarting

Check logs with docker logs hermes. The most common cause is a misconfigured .env file — particularly an invalid OPENAI_API_KEY or OPENAI_BASE_URL.

Problem: High memory usage

If the agent's memory database grows too large, you can prune old entries:

bash

1	`hermes memory prune --older-than 30d`

Problem: Permission errors during installation

This almost always means the install script was run with sudo. Remove the ~/.hermes directory, then reinstall as a normal user:

bash

1	`rm -rf ~/.hermes`
2	`curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh \| bash`

Key Takeaways

Hermes Agent represents a meaningful shift in how we think about AI Agents — from static tools that forget everything to dynamic systems that grow more useful over time. Here are the core recommendations:

For local experimentation, use the one-line install script. It takes under 5 minutes.
For server deployment, use Docker Compose with persistent volumes, resource limits, and a reverse proxy.
For production security, always use the Docker execution backend, keep approvals enabled, and restrict API and messaging platform access.
For maximum value, lean into the self-improvement features. The more you use Hermes Agent, the better it gets — give it time to accumulate memory and skills before judging its performance.
For OpenClaw users, the migration tool makes switching painless. Your existing configuration, memory, and skills transfer automatically.

The agent landscape will continue to evolve, but the principles Hermes Agent embodies — persistent memory, autonomous skill acquisition, and continuous self-improvement — are likely to define the next generation of AI Agent systems.

Further Resources

Official GitHub: github.com/NousResearch/hermes-agent
Official Documentation: hermes-agent.nousresearch.com/docs
Community Wiki: github.com/cclank/Hermes-Wiki
Function Calling SDK: github.com/NousResearch/hermes-function-calling

1	`# Download and execute the official installation script`
2	`curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh \| bash`
3
4	`# Reload environment variables`
5	`source ~/.bashrc`
6
7	`# Verify installation`
8	`hermes --version`
9
10	`# Expected output: hermes v0.8.0 (v2026.4.8) or later`

1	`# Check if ~/.local/bin is in your PATH`
2	`echo $PATH \| grep local`
3
4	`# If not, add it manually`
5	`echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc`
6	`source ~/.bashrc`

1	`docker run -d \`
2	`- -name hermes \`
3	`- -restart unless-stopped \`
4	`- v ~/.hermes:/opt/data \`
5	`- p 8642:8642 \`
6	`nousresearch/hermes-agent gateway run`

1	`# Check container status`
2	`docker ps`
3
4	`# Check health endpoint`
5	`curl http://127.0.0.1:8642/health`
6
7	`# Expected: {"status":"ok"}`
8
9	`# View logs`
10	`docker logs -f hermes`

1	`services:`
2	`hermes:`
3	`image: nousresearch/hermes-agent:latest`
4	`container_name: hermes`
5	`restart: unless-stopped`
6	`command: gateway run`
7	`ports:`
8	`- "8642:8642" # API Server port`
9	`- "9119:9119" # Dashboard port`
10	`volumes:`
11	`- ${HOME}/.hermes:/opt/data`
12	`environment:`
13	`HERMES_DASHBOARD: "1"`
14	`API_SERVER_ENABLED: "true"`
15	`API_SERVER_HOST: "0.0.0.0"`
16	`API_SERVER_KEY: "${API_SERVER_KEY}"`
17	`API_SERVER_CORS_ORIGINS: "https://chat.example.com"`
18	`deploy:`
19	`resources:`
20	`limits:`
21	`memory: 4G`
22	`cpus: "2.0"`

1	`# Start services`
2	`docker compose up -d`
3
4	`# View logs`
5	`docker logs -f hermes`
6
7	`# Stop services`
8	`docker compose down`
9
10	`# Upgrade to latest version (backup first!)`
11	`tar -czf hermes-backup-$(date +%F).tar.gz ~/.hermes`
12	`docker compose pull`
13	`docker compose up -d`

1	`# Clone the repository (use a mirror if needed)`
2	`git clone https://github.com/NousResearch/hermes-agent.git`
3	`cd hermes-agent`
4
5	`# Install dependencies`
6	`pip install -r requirements.txt`
7
8	`# Run directly`
9	`python -m hermes`

1	`# Run environment diagnostics`
2	`hermes doctor`
3
4	`# Start an interactive session to test`
5	`hermes`

1	`~/.hermes/`
2	`├── config.yaml # Main configuration file`
3	`├── .env # Environment variables (API keys, secrets)`
4	`├── auth.json # Authentication data`
5	`├── SOUL.md # Agent identity and personality definition`
6	`├── memories/ # Long-term memory storage`
7	`├── skills/ # Auto-generated and custom skills`
8	`├── cron/ # Scheduled task definitions`
9	`├── sessions/ # Conversation history`
10	`├── logs/ # Runtime logs`
11	`└── state.db # SQLite database (FTS5 index, state)`

1	`# Model configuration`
2	`model:`
3	`provider: openai # LLM provider identifier`
4	`default: gpt-4o # Default model to use`
5
6	`# Terminal / execution backend`
7	`terminal:`
8	`backend: docker # Options: local, docker, ssh, modal, daytona, singularity`
9	`timeout: 180 # Execution timeout in seconds`
10	`container_persistent: true # Keep containers alive between tasks`
11
12	`# Approval and safety`
13	`approvals:`
14	`mode: smart # Options: none, smart, always`
15	`timeout: 60 # Auto-approve timeout`
16
17	`# Long-term memory`
18	`memory:`
19	`memory_enabled: true # Enable cross-session memory`
20	`user_profile_enabled: true # Build user preference profile`
21	`memory_char_limit: 2200 # Character limit per memory entry`
22
23	`# Security hardening`
24	`security:`
25	`allow_private_urls: false # Block SSRF and internal network access`

1	`# LLM Provider credentials`
2	`OPENAI_API_KEY=sk-your-api-key`
3	`OPENAI_BASE_URL=https://api.openai.com/v1`
4
5	`# API Server configuration`
6	`API_SERVER_ENABLED=true`
7	`API_SERVER_PORT=8642`
8	`API_SERVER_HOST=0.0.0.0`
9	`API_SERVER_KEY=your-secure-random-string-here`
10	`API_SERVER_CORS_ORIGINS=https://your-frontend.com`
11
12	`# Dashboard configuration`
13	`HERMES_DASHBOARD=1`
14	`HERMES_DASHBOARD_HOST=0.0.0.0`
15	`HERMES_DASHBOARD_PORT=9119`
16
17	`# Messaging platform tokens (examples)`
18	`TELEGRAM_BOT_TOKEN=123456:ABC-DEF`
19	`FEISHU_APP_ID=cli_xxx`
20	`FEISHU_APP_SECRET=your_secret`

1	`# Interactive gateway setup`
2	`hermes gateway setup`
3
4	`# Or start the gateway directly`
5	`hermes gateway run`

1	`FEISHU_APP_ID=cli_xxxxxxxx`
2	`FEISHU_APP_SECRET=your_app_secret`
3	`FEISHU_DOMAIN=feishu`
4	`FEISHU_CONNECTION_MODE=websocket`
5	`FEISHU_GROUP_POLICY=allowlist`
6	`FEISHU_ALLOWED_USERS=ou_your_open_id`

1	`group_sessions_per_user: true`
2
3	`platforms:`
4	`feishu:`
5	`extra:`
6	`ws_reconnect_interval: 120`
7	`ws_ping_interval: 30`

1	`{`
2	`"gateway_state": "running",`
3	`"platforms": {`
4	`"feishu": {`
5	`"state": "connected"`
6	`}`
7	`}`
8	`}`

1	`server {`
2	`listen 443 ssl;`
3	`server_name agent.yourcompany.com;`
4
5	`ssl_certificate /etc/letsencrypt/live/agent.yourcompany.com/fullchain.pem;`
6	`ssl_certificate_key /etc/letsencrypt/live/agent.yourcompany.com/privkey.pem;`
7
8	`location / {`
9	`proxy_pass http://127.0.0.1:8642;`
10	`proxy_set_header Host $host;`
11	`proxy_set_header X-Real-IP $remote_addr;`
12	`proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;`
13	`proxy_set_header X-Forwarded-Proto $scheme;`
14	`}`
15	`}`

1	`curl http://localhost:8642/v1/chat/completions \`
2	`- H "Authorization: Bearer your-secure-random-key" \`
3	`- H "Content-Type: application/json" \`
4	`- d '{`
5	`"model": "hermes",`
6	`"messages": [`
7	`{"role": "user", "content": "Analyze the system logs for errors in the last hour"}`
8	`]`
9	`}'`

1	`# Example: Daily morning email summary`
2	`hermes schedule "Every day at 8 AM, summarize yesterday's emails and send to Telegram"`
3
4	`# Example: Weekly report generation`
5	`hermes schedule "Every Friday at 5 PM, generate a weekly project status report"`

1	`# List all scheduled tasks`
2	`hermes schedule list`
3
4	`# Remove a specific task`
5	`hermes schedule remove <task-id>`

1	`# My Agent Identity`
2
3	`## Core Values`
4	`- Always prioritize accuracy over speed`
5	`- Explain reasoning before giving answers`
6	`- Ask for clarification when requests are ambiguous`
7
8	`## Communication Style`
9	`- Professional but approachable`
10	`- Use bullet points for multi-step answers`
11	`- Include code examples when discussing technical topics`
12
13	`## Domain Expertise`
14	`- Python backend development`
15	`- DevOps and CI/CD pipelines`
16	`- Data analysis with pandas and SQL`

1	`# Create a dated backup`
2	`tar -czf /backup/hermes-$(date +%F).tar.gz ~/.hermes/`
3
4	`# Automate with cron (add to crontab -e)`
5	`0 2 * * * tar -czf /backup/hermes-$(date +\%F).tar.gz ~/.hermes/`

Hermes Agent Deep Deployment and Usage Tutorial

What Makes Hermes Agent Different

Core Design Philosophy

Quick Comparison: Hermes Agent vs. OpenClaw

Bottom line: If you want a plug-and-play local assistant, OpenClaw is fine. If you want an agent that grows smarter with every interaction and can scale to production, Hermes Agent is the stronger choice.

System Requirements

Installation Methods

Method 1: One-Line Install Script (Recommended for Local Testing)

Method 2: Docker Deployment (Recommended for Servers)

Method 3: Docker Compose (Recommended for Production)

Method 4: Manual Installation (For Network-Restricted Environments)

Method 5: Cloud Marketplace (Fastest for Non-Technical Users)

This eliminates all manual installation steps and is ideal for beginners.

Initial Configuration

Step 1: Run the Setup Wizard

Step 2: Configure Your LLM Provider

Step 3: Configure Tools

Step 4: Verify Your Setup

Send a test message. If the agent responds correctly, your setup is working.

Understanding the Configuration Files

The config.yaml File

The .env File

Execution Backends Explained

Messaging Platform Integrations

Setting Up the Gateway

Telegram Integration

Feishu (Lark) Integration

Other Supported Platforms

The same gateway system supports Discord, Slack, WhatsApp, Signal, WeChat, Enterprise WeChat (WeCom), DingTalk, and QQ. The configuration pattern is similar for each — obtain the platform's bot credentials and add them to your .env file.

The API Server

Enabling the API Server

Calling the API

This means you can point tools like ChatGPT-next-web, LobeChat, or any OpenAI-compatible client directly at your Hermes Agent instance.

Scheduled Tasks with Built-In Cron

Creating Scheduled Tasks

Managing Tasks

The agent interprets your natural language description and converts it into a cron schedule. This eliminates the need to write raw cron expressions for most use cases.

Self-Improvement: Memory and Skills Deep Dive

How Memory Works

How Skills Work

Customizing the Agent Identity

Migrating from OpenClaw

The migration is designed to be seamless — your new Hermes Agent will pick up right where your OpenClaw instance left off, but with the added benefit of self-improvement capabilities.

Production Deployment Best Practices

Security Hardening

Data Persistence and Backup

Resource Management

Monitoring

Reverse Proxy Setup

Common Issues and Troubleshooting

Key Takeaways

Further Resources

The same gateway system supports Discord, Slack, WhatsApp, Signal, WeChat, Enterprise WeChat (WeCom), DingTalk, and QQ. The configuration pattern is similar for each — obtain the platform's bot credentials and add them to your `.env` file.