本页导航

关于本仓库

面向有一定工程基础、希望系统性进入 AI / Agent 开发的全栈工程师。内容为个人持续整理的学习笔记：不追求面面俱到，只写真正理解且经实践验证的部分。

仓库结构

AI-Fullstack-Notes/
├── ai/                          # AI / Agent 相关笔记
│   ├── ai-agent-dev-composite-agent.md
│   ├── claude-code-quickstart.md
│   ├── codex-plugin-claude-code.md
│   ├── langchain-architecture.md
│   ├── langgraph-intro.md
│   └── rag-mvp-to-production.md
├── backend/                     # 架构 / 后端笔记
│   ├── high-concurrency-architecture.md
│   ├── nginx-reverse-proxy-load-balance.md
│   └── redis-cache-core-qa.md
├── hermes-agent/                # Hermes Agent 文档（门户 + 各章）
│   ├── index.md
│   ├── getting-started/         # 安装、快速开始、学习路径等（英 * .md / 中 *_zh.md）
│   ├── user-guide/             # 配置、CLI、features、messaging、skills 等
│   ├── guides/                  # 实践教程与技巧
│   ├── developer-guide/        # 架构与扩展开发（中文译本持续对齐英文章）
│   ├── reference/              # CLI / FAQ / 工具 / 环境变量等参考
│   └── integrations/           # 提供商与集成说明
├── infra/                       # 基础设施 / 运维笔记
│   ├── docker-basics-dockerfile.md
│   ├── docker-compose-vs-swarm.md
│   ├── ssh-public-key-auth.md
│   ├── supabase-docker-self-host.md
│   └── ubuntu-redis-install-remote-config.md
├── projects/                    # 项目实战笔记
│   ├── fastsam-demo-v1-fullstack.md
│   ├── fastsam-demo-v2-docker-export.md
│   ├── github-profile-readme-guide.md
│   └── hermes-agent/            # Hermes 个人实战系列（与 hermes-agent/ 文档区分）
│       ├── README.md
│       └── 01-setup-and-project-structure.md
└── tutorials/                   # 教程 / 上手指南
    └── mdbook-github-pages-tutorial.md

笔记索引

AI / Agent

工具 / 开发效率

基础设施 / 运维

架构 / 后端

项目实战

Hermes Agent 文档

独立目录 hermes-agent/ 收录 Hermes Agent 的文档整理；与 projects/hermes-agent/（个人实战笔记系列）并列，用途不同。

教程索引

微信公众号

文章同步发布在微信公众号 小邓同学的研习社，欢迎关注获取更新。

贡献与交流

个人学习向仓库；发现错误或有不同理解，欢迎 提交 Issue 讨论。

LangChain 架构浅析：从零构建 AI 智能应用的底层逻辑

一、什么是 LangChain？

LangChain 是一个开源的大语言模型（LLM）应用开发框架。

如果把大语言模型比作一个极其聪明、但被锁在“小黑屋“里的“大脑“；那么 LangChain 就是为这个大脑插上的**“外接存储”、“网线”以及能干活的“四肢”**。它将开发者在构建 AI 应用时最常遇到的一系列复杂调用流程，标准化成了一个个可灵活拼接的“积木“。

二、LangChain 的核心组件工作流

应用中的各个组件像流水线一样协同工作，每一层都在前一层的基础上进行处理：

三、核心组件详解

1. 模型 I/O（Model I/O）

负责与大语言模型交互的标准化接口层，包含三个子模块：

• 提示词模板（Prompt Templates）：将用户输入动态填充到预设的提示词结构中
• 语言模型（LLMs / Chat Models）：统一封装 OpenAI、Anthropic 等各家模型的调用接口
• 输出解析器（Output Parsers）：将模型返回的非结构化文本解析为结构化数据（如 JSON）

2. 数据检索（Retrieval）

专为 RAG（检索增强生成）场景设计的完整数据管道：

• 文档加载器（Document Loaders）：从 PDF、网页、数据库等各类数据源加载原始内容
• 文本分割器（Text Splitters）：将长文档切分为模型可处理的小块（Chunks）
• 向量存储（Vector Stores）：将切分好的文本转化为向量，持久化存入专属数据库（如 Chroma、Pinecone）
• 检索器（Retrievers）：当用户提问时，将问题同样向量化，去数据库中匹配最相似的段落，作为模型的参考资料

3. 链（Chains）

负责将各类独立操作“串联“成工作流：

• LLMChain：最基础的链，将【提示词模板】与【大模型】绑定执行

• 顺序链（Sequential Chain）：类似工厂流水线，上一步的输出直接作为下一步的输入

  示例：提取文章摘要 → 根据摘要生成营销文案 → 将文案翻译为英文

4. 记忆（Memory）

大模型本身是无状态的（“鱼的记忆”），说完下句忘上句。Memory 组件专门解决多轮对话的历史衔接问题：

• 缓冲记忆（Buffer Memory）：将之前的对话历史原封不动地塞进当次提示词中
• 摘要记忆（Summary Memory）：当对话过长时，自动触发大模型对前文进行压缩总结，节省 Token 消耗

5. 智能体（Agents）

Agent 是 LangChain 中最强大的组件，赋予大模型自主规划和调用外部工具的能力。

常见 Agent 类型

四、常见问题解答（FAQ）

Q1：Agent 是如何决定使用哪个工具的？

Agent 的核心是大模型的“阅读理解“能力。它分析用户提问，并阅读开发者提供的“工具说明书（描述）“，通过以下内部推理循环自动匹配工具：

思考（Thought）→ 行动（Action / 选择工具）→ 观察（Observation / 工具返回结果）→ 循环

Q2：什么是 LangChain 中的 Callbacks？

Callbacks 是 LangChain 的事件钩子系统，允许开发者在链或 Agent 的各个执行节点（如开始、结束、出错）注入自定义逻辑，常用于日志记录、性能监控和链路追踪。

Q3：如何选择 Memory 类型？

选择的核心依据是 Context Window 的限制和成本考量。

Q4：如何评价 LLM 应用的性能？

• RAGAS：专为 RAG 场景设计的评估框架，衡量检索准确率和生成质量
• LangSmith：官方追踪工具，可可视化完整调用链路
• 自定义评估数据集：针对业务场景构建测试集进行基准测试

Q5：LangChain 有什么缺点？

LangChain 封装层级较深，有时会导致调试困难，且版本迭代极快。

应对策略：

• 配合 LangSmith 进行全链路追踪
• 复杂逻辑处改用 LangGraph，提高代码可控性和可读性

LangGraph — 通过图结构重新定义 LLM 应用

LangGraph 简介

LangGraph 是 LangChain 生态系统中的一个重要扩展库，专门用于构建、管理、部署长期运行、有状态、多智能体的复杂工作流。它通过图结构来管理任务流，支持循环、条件分支和动态决策，适用于需要持久化上下文或多代理协作的场景。

• 持久执行：有容灾恢复能力，能长时间运行，当出现问题时，能从中断处自动恢复。
• 人机协同：执行过程的任何时候，通过检查和修改智能体状态，可以无缝地引入人类监督。
• 全面记忆：智能体既有用于持续推理的短期工作记忆，也有跨会话的长期持久记忆。

核心架构与概念

1. 状态机架构

2. 核心组件

图（Graphs）

定义任务执行的逻辑流程，由节点和边组成：

• 包含哪些工作步骤（节点）
• 这些步骤之间如何连接（边）
• 整个流程的走向

状态（State）

贯穿整个图执行过程的共享数据容器，由用户自定义结构，记录着当前程序运行到什么状态：

• 存储当前的信息和数据
• 在所有节点之间共享
• 可以被任何节点读取和更新

节点（Nodes）

图的基础执行单元，本质是函数，接收 State 作为输入并返回更新后的 State：

• 每个节点负责完成一个具体的任务
• 接收当前状态作为输入
• 处理完后返回更新的结果
• 本质上就是 Python 函数

边（Edges）

控制节点间的流转逻辑，分为普通边和条件边：

• 普通边：固定路线，A 完成后总是去 B
• 条件边：根据情况选择路线，类似“如果…就去 A，否则去 B“

主要特性

循环和分支能力

• 支持条件语句和循环结构
• 可以根据状态动态决定执行路径
• 轻松实现复杂的对话流程控制

状态持久化

• 自动保存和管理状态
• 支持暂停和恢复执行
• 便于处理长时间运行的对话

人机协同支持

• 可以在执行过程中插入人工审核
• 支持编辑和修改状态
• 灵活的交互控制机制

多智能体协作

通过“状态驱动的图结构“实现：

• 明确的职责边界
• 可靠的通信协议
• 可观测的运行平台

应用场景

快时尚电商智能客服

• 意图识别代理判断用户问题类型
• 根据意图动态路由到专业代理
• 调用 MCP 工具处理复杂业务逻辑

多轮对话状态管理

在多轮对话系统中，用户需求往往跨越多个阶段，LangGraph 通过状态驱动的图结构可以：

• 将每个对话阶段拆解为独立节点
• 显式管理意图、订单详情、补偿等级等状态信息
• 根据实时上下文自动路由请求

智能体系统

• 机器人控制系统
• 自动驾驶汽车
• 视频游戏 AI
• 聊天机器人

技术优势

相比传统 LangChain

• 显式的状态管理：每个节点只关心自己处理的那部分状态，降低耦合度
• 动态、灵活的代理路由：通过条件边和循环结构实现高度个性化的执行路径
• 易于扩展和维护：新增节点或调整路由只需局部修改
• 支持复杂的状态转换逻辑：无论是多轮对话、条件推理还是长流程任务

工程化支持

• 可视化：提供内置的图可视化方法，直观展示工作流逻辑
• 调试友好：状态在节点间流转并持续更新，便于追踪和调试
• 持久执行：支持检查点机制，可在故障后恢复

更多详细内容见 LangGraph Docs

RAG 实战：从手写 MVP 链路到生产级优化

摘要：从零手写 LangChain RAG 链路，解析切片策略、混合检索、重排序（Rerank）及向量数据库实战指南。

01 核心能力要求

在 RAG（检索增强生成）的工程落地中，我们不能只停留在“知道概念“的层面。一个合格的 RAG 工程师必须具备以下能力：

• ✅ 基础链路闭环 能够手写出完整的：文档加载 → 切片 (Chunking) → 向量化 (Embedding) → 存储 (Vector DB) → 检索 → 提示词组装 → 模型生成
• ✅ 精细化切片策略 不盲目按字数切分，掌握语义切分与 Markdown 标题层级切分
• ✅ 多路召回与重排序 理解为什么单一向量检索不够用，如何引入 Rerank 解决精度问题
• ✅ 混合检索 (Hybrid Search) 能够结合 Elasticsearch (BM25) 的关键词搜索与 Vector 的语义搜索
• ✅ 向量库实战 熟练掌握 Chroma 或 Milvus 的 CRUD 及索引配置

02 标准 LangChain MVP 实现

(Minimum Viable Product)

# --------------------------
# 1. 切片 (Chunking)
# 策略：按字符递归切分，保留上下文
# --------------------------
text_splitter = RecursiveCharacterTextSplitter(
    chunk_size=500,       # 每一块约 500 字符
    chunk_overlap=50,     # 重叠 50 字，保证句子不被腰斩
    separators=["\n\n", "\n", "。", "!", "?"]  # 优先按段落切
)
splits = text_splitter.split_documents(docs)

# --------------------------
# 2. 向量化 & 存储 (Embedding & Vector DB)
# --------------------------
# 调用 OpenAI API 将文字转为向量 [0.1, -0.2, ...]
vectorstore = Chroma.from_documents(
    documents=splits,
    embedding=OpenAIEmbeddings(),
    persist_directory="./chroma_db"  # 持久化存储
)

# --------------------------
# 3. 检索 (Retrieval)
# --------------------------
# 找出最相似的 Top 3 片段
retriever = vectorstore.as_retriever(search_kwargs={"k": 3})
question = "TSLA 2025 Q4 的净利润率是多少？"
retrieved_docs = retriever.invoke(question)

# --------------------------
# 4. 提示词组装 (Prompt Assembly)
# --------------------------
from langchain_core.prompts import ChatPromptTemplate

prompt = ChatPromptTemplate.from_template("""
根据以下上下文回答问题，如果上下文中没有相关信息，请如实说明。

上下文：
{context}

问题：{question}
""")

# --------------------------
# 5. 模型生成 (Generation)
# --------------------------
llm = ChatOpenAI(model="gpt-3.5-turbo")
chain = prompt | llm

# context 由检索出的 docs 拼接而成
response = chain.invoke({
    "question": question,
    "context": "\n\n".join([doc.page_content for doc in retrieved_docs])
})

print(response.content)

03 进阶：RAG 效果不好怎么办？

这是面试和实战中最常见的问题。我们通常从以下三点入手优化：

1. 优化切片策略 (Chunking Strategy)

🔴 痛点 ─

死板地按 500 字切分，容易把 "2025年营收：" 切在上一段，而把具体的 "100亿"切在下一段。检索时上下文丢失，导致大模型幻觉。

🟢 解决方案

语义切分 (Semantic Chunking)

利用 Embedding 计算前后句子的相似度，意思连贯时不切，突变时才切。

Markdown 标题切分

按照 # 一、财务摘要、## 1.1 营收这种层级切分。检索时，内容会带上 财务摘要 > 营收的元数据，极大地提高了上下文准确度。

2. 混合检索 (Hybrid Search)

🔴 痛点

🟢 解决方案 ─

如果用户问 "600519的代码是多少？"，需要结合 Elasticsearch (BM25) 和 Chroma (Vector) 的结果，加权输出。

参考公式：

Final Score = 0.7 × Vector_Score + 0.3 × BM25_Score

3. 重排序 (Rerank)

🔴 痛点 ─

初步检索出的 Top 5 内容，可能混入了只包含关键词但语义无关的噪音。

🟢 解决方案 ─

采用 Two-Stage Retrieval（两阶段检索）：

1. 粗排 — 用向量库快速召回 50 条相关片段（速度快，精度一般）
2. 精排 — 使用 Cross-Encoder（如 bge-reranker）对这 50 条进行精细打分，选出 Top 5 给大模型

效果： 虽然增加了约 200ms 耗时，但准确率会有质的飞跃。

04 向量数据库 (Chroma) 实战速查

1. 创建 / 读取集合

import chromadb

client = chromadb.PersistentClient(path="./db")
collection = client.get_or_create_collection(name="finance_reports")

2. Upsert（更新或插入）

⚠️ 注意：必须指定唯一的 ids，否则数据会重复堆积。

collection.upsert(
    documents=["苹果公司 Q3 营收上涨...", "特斯拉销量下跌..."],
    metadatas=[{"source": "report1.pdf"}, {"source": "report2.pdf"}],
    ids=["doc1", "doc2"]
)

3. Query（查询）

results = collection.query(
    query_texts=["特斯拉销量怎么样？"],
    n_results=2
)

05 深度 Q&A：工程化避坑指南

Q1：PDF 里的表格怎么处理？

直接用 PyPDFLoader 加载表格会变成乱码，语义全毁。

✅ 实战解法： ─

使用 pdfplumber 或 Unstructured
库。检测到表格结构时，将其提取并转化为 Markdown 格式（如 | 科目 | 金额 |），再进行 Embedding。这样向量模型就能理解这是结构化数据，而不是乱码。

Q2：加了 Rerank 速度变慢怎么办？

Rerank 确实会增加 300ms-500ms 的延迟。

✅ 优化策略： ─

限制数量 初筛 50 条，Rerank 只排前 10 条。

流式输出 (Streaming) 后端拿到 LLM 第一个 token 就通过 SSE 推送给前端。用户看到字在蹦，心理等待感会降低很多。

Q3：怎么证明 RAG 变准了？

不能靠感觉，要靠数据。

✅ 评估方法： ─

1. 构建一个包含 50 个高频问题的“金标准测试集“
2. 每次优化策略后，运行脚本计算 召回率 (Recall)（即 Top 3 结果里是否包含正确答案）
3. 只有召回率提升（如从 60% → 80%）时，才上线新代码

Q4：怎么解决“上下文断裂“问题？

比如“茅台营收“这句话，一半在 Chunk A 结尾，数字在 Chunk B 开头。

✅ 实战配置：

利用 chunk_overlap（切片重叠）：

Chunk Size = 500
Overlap = 50 ~ 100

这样 Chunk B 的开头会重复 Chunk A 的结尾，保证关键信息（主语 + 数字）完整出现在至少一个 Chunk 中。

Q5：流程这么长，怎么优化 Latency？

如果用户等 10 秒，体验就崩了。

✅ 三层优化：

本文首发于 小邓同学的研习社

技术笔记｜《AI Agent 开发：零基础构建复合智能体》知识梳理

在人工智能从“对话框“走向“行动派“的今天，AI Agent（智能体）正成为大模型落地的核心形态。本文参考梁志远的《AI Agent 开发：零基础构建复合智能体》，依据智能体系统的标准开发范式，从架构设计、核心内核实现到工程化落地三个维度，剖析如何从零构建一个具备感知、决策与执行能力的复合智能体。

第一部分：地基与原理

1.1 智能体系统架构设计

核心问题：什么是 Agent？它和普通的大模型有什么区别？

AI Agent 的本质是感知-认知-执行（Perception-Cognition-Action, PCA）模型在语言智能体领域的具体化。它不再是被动应答的聊天机器人，而是具备主动决策能力的独立实体。

为了支撑这一闭环，典型的系统架构采用分层部署：

基础模型层（底层 LLM、Embedding、多模态）
        ↓
智能体能力层（核心逻辑）
        ↓
应用接口层（交互终端）

在智能体能力层中，五大核心功能模块各司其职：

• 感知模块（Perception）：连接外部世界的桥梁。负责将非结构化的自然语言（如用户的模糊指令）转换为结构化的意图表示或 JSON 对象。
• 认知模块（Cognition）：智能体的“大脑“与推理中心。涉及信息整合、逻辑推理、策略选择与任务规划。
• 执行模块（Action）：任务的“最后一公里“。将认知决策转换为具体动作（如 API 调用、数据库查询）。
• 记忆模块（Memory）：维持多轮交互与状态保持的关键，存储用户历史与运行中间状态。
• 接口模块（Interface）：确保系统可嵌入多种运行环境（Web、终端等）。

1.2 大模型的能力边界与限制

模型能做什么？有什么短板？

1. 核心能力（模型能做什么）

大模型是 Agent 的引擎，其推理能力决定了 Agent 的上限：

• 逻辑与常识推理：基于训练语料中的世界知识，判断命题合理性。
• 思维链（Chain of Thought）：在面对复杂问题时，生成中间步骤，逐步推导结论。
• 条件与假设验证：模拟“如果……那么……“的情境，这是任务规划的基础。

2. 短板与应对：上下文窗口限制

模型单次推理能看到的 Token 总量（上下文窗口）是有限的。为了在有限的预算内处理海量信息，必须采用窗口控制策略：

• Prompt 压缩与摘要：仅保留核心事实与关键信息片段，对历史对话进行有损压缩。
• Token 预算分配：为 System Prompt、用户输入、工具描述预先设定 Token 预算，防止某一部分挤占推理空间。
• 滑动窗口与截断：分段式输入，保留最近 N 轮对话，较远轮次转入长期记忆或丢弃。

1.3 构建基本流程与任务建模

怎么把用户的需求变成代码任务？

1. 结构化输入

大模型本质是条件生成器，高质量的 Prompt 是任务建模的起点。一个标准的 Prompt 模板应包含：

• System Prompt：定义角色边界（如“你是一个资深 DBA“）。
• Instruction：明确当前任务目标。
• Input Content：提供任务所需的背景信息。
• Output Format：强制模型输出 JSON 或特定 XML 标签，以便程序解析。

2. 流程闭环

智能体的运行不是一次性的问答，而是循环：

感知状态 → 规划路径 → 拆解步骤 → 执行反馈 → 感知状态（循环）

动态规划：通过在 Prompt 中嵌入“状态标签“（如任务阶段：规划中），引导模型根据当前上下文决定是继续执行、分支处理还是终止任务。

第二部分：核心组件详解

2.1 四大模块的深度技术细节

每个模块具体怎么写代码？哪四大模块？

1. 感知模块：从文本到结构

感知不仅是“读“，更是“解析“。该模块利用 Prompt 解析器和辅助函数，将自然语言输入转化为系统可理解的结构化意图。

• 技术点：识别实体要素、抽取任务参数，并处理多模态输入（利用 ViT 等编码器将图像转为统一表示）。

2. 决策模块（认知）：任务链拆解

这是最核心的逻辑单元。认知过程细分为四个步骤：

1. 意图识别与任务分类：确定是查询、生成还是操作。
2. 任务分解：将宏观目标拆解为子步骤序列（DAG 或线性链）。
3. 工具选择：根据子步骤目标，从工具库中匹配最合适的 API。
4. 错误预判：识别潜在失败路径，提前构造容错机制。

3. 行动模块：以工具改变世界

行动模块包含工具注册、调度器与反馈管理。

• 容错与重试机制：外部 API 极不稳定。行动模块必须具备异常捕获能力。如果工具调用失败（如网络超时、参数错误），应触发自动重试或让模型根据报错信息重新生成参数（Self-Correction），而不是直接崩溃。

4. 记忆模块：短期与长期的协作

• 短期记忆（Short-term）：存放在 Prompt 或内存变量中，包含最近几轮对话和中间变量。旨在维持语义连续性，解决指代消解问题。
• 长期记忆（Long-term）：基于向量数据库（Vector DB）如 Chroma 或 FAISS。
  • 存：将重要信息 Embedding 后存入库。
  • 取：通过语义相似度检索（RAG），随时“捞“出相关历史知识。
  • 更新策略：采用滚动更新或基于重要性评分进行记忆剪裁。

2.2 智能体的生命周期管理

一个 Agent 从启动到关闭的全过程

1. 初始化（Initialization）

Agent 启动时需加载模型配置（Temperature, Max Tokens）、注册工具函数表，并加载默认的系统记忆。

2. 运行中：状态追踪（State Tracking）

• Session ID：每个会话必须有唯一标识。
• 断点续传：复杂任务往往跨越长时间周期。系统需周期性将“恢复状态（Resumption State）“持久化存储。一旦中断，可重建 Prompt 上下文，恢复现场继续执行。

3. 注销（Termination）

任务完成后，触发清理操作：释放数据库连接、清除临时缓存、持久化必要的日志，确保系统资源回收。

2.3 与外部系统的集成

Agent 怎么跟外面的世界打交道？

智能体通过以下方式与物理/数字世界交互：

• API 调用：将用户指令映射为 RESTful HTTP 请求。技术上常使用 Function Calling 标准，定义函数结构体由模型填充参数。
• 数据库交互：遵循分层设计：语义解析 → 生成 SQL → 执行查询 → 结果写入记忆。严禁直接让 LLM 无限制操作 DB。
• 文件系统与沙箱：涉及文件读写或代码执行（Code Interpreter）时，必须在隔离的沙箱环境（Docker 容器或虚拟环境）中运行，防止恶意指令破坏宿主机。

第三部分：工程优化与安全

3.1 API 调用设计模式

怎么调大模型更高效？

1. 流式传输

为了解决大模型推理延迟高的问题，采用流式响应机制（Server-Sent Events）。像打字机一样逐个 Token 输出，让用户在完整结果生成前就能看到进度，通过提升首字响应速度优化体验。

2. 上下文缓存与并发

对高频访问的基础知识进行预处理缓存；在处理非依赖性子任务时，设计并行调用链路以提升吞吐量。

3.2 安全与内容控制

怎么防止 Agent 乱说话或干坏事？

1. 敏感词过滤（红线防御）

• 静态防御：使用 Aho-Corasick 自动机算法对输入输出进行高效的关键词匹配（违禁词库）。
• 动态防御：结合语义分析模型，拦截隐晦的违规指令。

2. 防幻觉与可信度评估

• 置信度打分：对模型生成的 Token 序列进行概率打分，低分内容触发拦截。
• 一致性校验：对同一问题进行多次不同 Prompt 的询问，对比答案一致性。
• 引用验证：强制模型在回答中通过 RAG 机制引用知识库来源，若无来源则标记为不可信，进行人工接管。

结语

以上就是基于梁志远老师《AI Agent 开发：零基础构建复合智能体》前两章梳理的核心脉络。从架构设计到工程落地，希望能帮你把 Agent 的内部逻辑理顺。当然，如果想看更底层的代码实现，还是推荐去翻翻原书。

Claude Code CLI 快速教程：从环境搭建到批量处理的实用指令集

Claude Code 配置教程（以 Mac 系统为例）

1. 必备工具

2. 检查 Node.js 版本

node -v

3. 检查 Git 版本

git --version

4. 安装 Claude Code

npm install -g @anthropic-ai/claude-code

5. 验证 Claude Code 安装

claude --version

6. 配置环境变量

cursor ~/.zshrc
# 或
vim ~/.zshrc

写入以下内容：

export ANTHROPIC_BASE_URL="https://******"
export ANTHROPIC_AUTH_TOKEN="******"

7. 重载配置文件

source ~/.zshrc

8. 启动 Claude

claude

常用指令

更多指令见官网：https://code.claude.com/docs/en/overview

Codex 插件接入 Claude Code，AI 编程开始进入双引擎时代

一、前言

今天 OpenAI 悄悄发布了一个新东西：codex-plugin-cc。简单来说，这个插件让你在 Claude Code 里，直接调用 OpenAI 的 Codex 来帮你审查代码、修 bug。

二、什么是 Codex？

Codex 是 OpenAI 推出的 AI 编程助手，专门用来写代码、审查代码、修复 bug。它和 Claude Code、Cursor 这些工具是同类产品，但背靠 OpenAI。之前 Codex 主要是独立运行的，现在它通过这个插件，可以嵌入到 Claude Code 里使用。

三、这个插件能做什么？

1. 代码审查

/codex:review

一行命令，Codex 就会帮你审查当前未提交的代码。审查是只读的，不会修改你的代码。

支持：

• 审查当前改动
• 审查某个分支 vs main 的差异
• 后台运行，不阻塞当前工作

2. 对抗性审查

/codex:adversarial-review challenge whether the caching design is right

普通的代码审查只是挑 bug，而对抗性审查会质疑你的设计决策：

• 这个设计真的合理吗？
• 有没有更好的方案？
• 这里的 tradeoff 是什么？

相当于请了一个“杠精“来审查你的代码，专门挑你设计上的问题。

3. 委托任务

/codex:rescue investigate why the tests are failing
/codex:rescue fix the failing test

直接让 Codex 去调查问题、尝试修复。

你可以指定模型：

• -model spark 用最新最强的模型
• -model gpt-5.4-mini 用更小更快的模型
• -effort medium 控制投入程度

4. 自动化审查门控

/codex:setup --enable-review-gate

开启这个功能后，每次你准备“发货“时，Claude Code 会自动触发 Codex 审查。如果审查发现问题，发货会被阻止。

这个功能适合团队使用，确保每一次代码提交都经过审查。

四、技术实现

这个插件的技术栈并不复杂：

• 调用方式：通过本地 CLI @openai/codex 调用 Codex 服务
• 认证：复用一个 Codex 账号，不需要额外登录
• 配置：支持用户级配置 ~/.codex/config.toml 和项目级配置

换句话说，如果你本地已经装了 Codex，这个插件直接就能用。

五、怎么安装？

前置条件：需要 Node.js 18.18+ 和一个 Codex 账号（ChatGPT 订阅或 API Key 都可以）。

用 Claude Code 添加市场：

/plugin marketplace add openai/codex-plugin-cc

安装插件：

/plugin install codex@openai-codex

重新加载插件：

/reload-plugins

检查 codex（如果 Codex 缺失且 npm 可用，它可以帮你安装 Codex）：

/codex:setup

六、总结

Codex Plugin for Claude Code 这个插件，本质上是把两个 AI 编程工具串联起来：

• Claude Code：日常编程、交互式对话
• Codex：专业的代码审查和修复

一个主打交互，一个主打审查，组合起来就是一个“编程 + 审查“的完整工作流。

如果你同时在用这两个工具，这个插件值得试试。

面向中小型企业内部系统的高并发架构设计思考

在现代企业数字化转型中，为三百至五百名员工提供同时在线、体验流畅、响应稳定的内部系统，已成为系统开发的核心挑战之一。尽管用户规模看似有限，但企业内部系统往往具有复杂业务逻辑、高密度操作、严格权限模型、大量 I/O 请求等特点，使其并发压力并不逊于中型互联网平台。

并发性能的关键不在于拼硬件，而在于在架构层面做到异步化、解耦化、缓存优先、水平扩展与可观测性建设。本文将从后端、数据库、前端、消息队列、负载均衡与可观测性六大维度进行分析思考探讨。

一、后端并发处理：从 WSGI 到 ASGI 的必然演化

1. WSGI 模型的并发局限

传统 Python Web 框架（如 Flask、Django）依赖 WSGI（同步阻塞模型）。其问题在于：

• 每个请求占据一个线程 / 进程
• 大量 I/O（数据库、外部 API、磁盘）造成阻塞
• 五百用户并发时会出现进程爆炸、上下文切换开销巨大
• 高峰期容易出现系统雪崩

WSGI 模型对 I/O 密集型场景支持有限。每个请求都占用一个线程或进程，一旦请求中涉及外部 I/O（数据库、存储、第三方接口），线程就会被锁住。在并发规模扩大到几百时，进程数增长、切换开销变大，系统吞吐量反而下降。

2. ASGI：企业级高并发的标准解

ASGI 基于事件循环（Event Loop）+ 协程（Coroutine），特点是：

• 单进程可处理成千上万个连接
• I/O 等待时自动让出执行权
• 高效利用 CPU 时间片
• 天然支持 WebSockets、SSE、后台任务等实时业务

采用 ASGI 架构（如 FastAPI）能从根本上改变这一点。事件循环和协程机制让请求在等待 I/O 时主动让出执行权，使单进程能同时处理大量连接。对于企业内部系统常见的场景（表单提交、查询、批量业务处理等），这类并发模型更契合。

3. 协程与 GIL 的关系

GIL 限制 Python 线程的 CPU 并行执行，但企业级系统主要瓶颈在 I/O 而非 CPU。

借助 asyncio：

• I/O 等待期间协程挂起
• 避免线程阻塞
• 单核可以模拟高并发行为

因此：GIL 的限制主要影响 CPU 密集型任务，而内部系统通常以数据库和网络 I/O 为主，只要使用异步框架和异步驱动，就能较好地避免阻塞问题。

二、数据库高并发治理：连接池、异步驱动与查询优化

数据库通常是内部系统的第一瓶颈。

应用层使用 SQLAlchemy 的连接池可以减少频繁建连带来的开销，但当后端服务实例增多时，每个实例的连接池会叠加，容易超过数据库的最大连接数。

因此，大规模并发下通常需要在数据库前面增加 PgBouncer，让其在连接层做统一的复用与限流。通过事务级别的池化，PgBouncer 可以用少量物理连接支撑大量逻辑连接，避免数据库压力过大。

除此之外，查询本身的效率同样重要。慢查询会长时间占用连接，最终导致连接池耗尽。必要的索引、合理的 SQL 结构、避免 N+1 查询，以及使用 asyncpg 等异步驱动，都是提升整体并发能力的关键。

三、Redis：缓存、限流与会话的三重角色

Redis 在高并发架构中承担三个核心任务。

1. 热点缓存（Cache-Aside）

将频繁读取的权限树、组织架构、配置字典、菜单数据缓存至 Redis，可减少 80% 以上数据库读取压力。

采用：

• TTL + 随机偏移（防雪崩）
• 旁路缓存（Cache-Aside）模式

2. 并发限流（Rate Limit）

基于 Redis INCR 实现：固定窗口 / 滑动窗口、令牌桶、漏桶。

用于防止：

• 异常脚本压力
• 爆量操作冲击后端
• 内部压力测试导致系统宕机

3. 会话管理与权限缓存

对比 JWT 与 Redis Session：

在企业场景中，Redis 存储 Session 比 JWT 更易管理，特别是在需要立即登出某个用户时，删除 Redis 中的键即可。企业内部系统推荐 Redis Session + 权限缓存，Session 的查找延迟较低，不会拖慢鉴权流程。

四、React 前端：企业级高频交互与大数据渲染优化

企业内部系统的前端压力主要来自大量数据渲染和高频操作，例如：

• 大量实时数据刷新
• 海量列表渲染（如审批列表、订单列表）
• 多人协同引发的数据竞态
• 复杂权限控制导致的 diff 计算

React 虽然已经有较好的渲染调度能力，但在大型表格和列表中，如果不进行优化，浏览器主线程很容易被拖慢。

1. 列表虚拟化

使用 react-window 或 react-virtualized，只渲染视口区域能显著降低 DOM 节点数量。这对操作大量业务数据的页面非常关键。

2. 状态管理

Redux Toolkit 和 RTK Query 在企业应用中更实际，它们能自动做请求去重、缓存失效控制，减少对后端的不必要请求。

3. 用户交互优化

防抖、节流、请求竞态处理（始终以最新返回的数据为准）等逻辑，对减少实际并发量和提升体验都有帮助。

五、耗时任务与异步队列：把时间从请求链路中拆出去

某些任务（如 AI 处理、大批量导出、同步外部接口）不可同步执行。

内部系统常常有一些耗时任务：大批量导出、AI 处理、大型同步任务等。如果让它们直接在 HTTP 请求中执行，会导致后端 Worker 长时间被占用，继而影响所有用户的响应时间。

标准做法是将这些任务交给 Celery 执行。这种方式可以让任务排队处理，系统不会因为某个用户的重操作卡住整体服务。

优势：

• HTTP 层不被阻塞
• 高峰任务自动排队
• 后台 Worker 可横向扩容
• 让系统不因大任务而卡死

六、Nginx：流量入口的负载均衡与优化

作为入口的 Nginx 主要承担三件事：

1. 负载均衡

• least_conn：更适合请求耗时差异较大的内部系统
• ip_hash：适合 WebSocket 长连接场景

2. 连接数与系统参数

操作系统和 Nginx 的最大文件描述符限制决定了系统能承受多少并发连接。在高并发场景中，这类参数必须根据峰值预期进行调整。

3. SSL 和 HTTP/2

统一在 Nginx 层做 SSL 卸载可以减少后端负担；开启 HTTP/2 的多路复用能加快 React 静态资源加载，尤其在网络状况一般的环境里提升明显。

七、可观测性：企业级系统的“自愈能力“

能否找到瓶颈、能不能及时恢复，比单点性能更重要。

常见做法包括：

• 使用 Prometheus 采集指标（RPS、延迟、连接池占用、队列长度等）
• 使用 Grafana 做可视化
• 使用链路追踪（如 Jaeger）定位请求中具体的耗时环节
• 设置存活和就绪探针，确保负载均衡器只将流量分配给健康实例

在多人协作和频繁发布的场景中，这些监测至关重要。

总结：高并发不是“堆硬件“，而是减少等待、降低阻塞、合理分流

一个稳定的三百至五百人并发内部系统，靠的不是昂贵服务器，而是各个环节的合理架构：

当这些组件协同工作后，系统不但能承受高并发，也更容易扩展、调优和长期维护。

参考：https://gemini.google.com/share/36973feb7c42

Nginx 全解析：反向代理、负载均衡与动静分离一文通

Nginx 是什么？

Nginx 是一款高性能的开源 Web 服务器和反向代理服务器，采用事件驱动的异步非阻塞架构，能以极低的内存消耗轻松处理数万并发连接。它最常见的用途是作为静态资源服务器、反向代理和负载均衡器——即把用户请求分发给后端多台应用服务器，同时对外只暴露 Nginx 自身，从而提升性能、安全性和可用性。

Nginx 通常被用来实现以下四个功能：正向代理、反向代理、负载均衡、动静分离。

正向代理（Forward Proxy）

正向代理是位于客户端和目标服务器之间的代理服务器，代表客户端向目标服务器发送请求。目标服务器只看到代理的 IP，不知道真正的客户端是谁。

客户端知道要访问谁，但让代理“替自己去拿“，隐藏的是客户端身份。

常见用途：

• 科学上网：客户端无法直接访问目标站点，通过代理中转
• 隐藏真实 IP：保护客户端隐私
• 访问控制：企业通过代理限制员工可访问的网站
• 缓存加速：代理缓存常用资源，减少重复请求

与之对应的是反向代理——隐藏的是服务器身份，代表服务器接收客户端请求（Nginx 最典型的用法）。

反向代理（Reverse Proxy）

反向代理是位于后端服务器前面的代理服务器，代表服务器接收客户端请求，再转发给后端真实服务器处理，最后把响应返回给客户端。客户端全程只知道代理的地址，不知道后端服务器的存在。

正向代理“替客户端出门“，反向代理“替服务器迎客“，隐藏的是服务器身份。反向代理服务器和目标服务器对外就是一个服务器，暴露的是代理服务器地址，隐藏了真实服务器 IP 地址。

常见用途：

• 负载均衡：把请求分发到多台后端服务器，避免单点过载
• 安全防护：隐藏真实服务器 IP，收敛攻击面，抵御 DDoS
• SSL 终止：由代理统一处理 HTTPS 加解密，减轻后端负担
• 缓存加速：缓存静态内容，加快响应速度
• 统一入口：一个域名背后对接多个微服务

负载均衡

负载均衡是在反向代理基础之上实现的，就是把用户请求分摊到多台服务器上处理，避免单台服务器过载，从而提升系统的性能、可用性和可扩展性。

核心价值

常见算法

• 轮询（Round Robin）：按顺序依次分配，最简单
• 加权轮询：性能强的服务器分配更多请求
• 最少连接（Least Connections）：优先分给当前连接数最少的服务器
• IP 哈希：同一客户端 IP 始终分到同一台服务器（保持会话）
• 随机：随机选一台

通俗来说：原来一台服务器扛所有请求，变成加一堆服务器大家一起扛，请求来了就分给不同的机器处理，谁都不会被压垮——这就是负载均衡。

动静分离

什么是动静分离？

将动态请求和静态资源分开处理：

• 静态资源：HTML、CSS、JS、图片、视频、字体等，内容固定不变
• 动态请求：需要后端运算的请求，如 API 接口、数据库查询、用户登录等

核心思路：Nginx 直接返回静态文件，动态请求转发给后端服务器（如 Tomcat、Node.js、PHP-FPM）。

为什么要做动静分离？

Redis — 用问答的方式拆解分布式缓存的核心（上）

常规问题

什么是 Redis，为什么要使用它？

Redis 是一个开源的、基于内存运行的键值型（Key-Value）NoSQL 数据库。它以极高的读写速度著称，常被用作缓存、数据库或消息中间件。使用 Redis 的原因有以下几点：

• 高性能：拦截大量请求，保护后端数据库不被大流量冲垮；
• 多数据结构：支持 String、Hash、List、Set、ZSet 等，能直接在内存中处理复杂的业务逻辑；
• 原子性：所有操作均为原子性，天然适合处理计数器、分布式锁等并发场景。

Redis 一般有哪些使用场景？

• 缓存：存储热点数据（如商品、用户信息等），大幅降低数据库压力，提升响应速度。
• 分布式锁：利用 SETNX 等原子操作，解决分布式系统下的资源竞争问题。
• 计数器 / 限流：实现点赞数、播放量统计，或通过计数器限制 API 的访问频率。
• 排行榜：利用 ZSet 自动排序功能，实现实时积分或热度榜单。
• 会话管理：在分布式集群中统一存储用户的登录状态，实现多机共享。
• 消息队列：利用 List 或 Stream 结构，实现简单的异步任务处理和解耦。

Redis 为什么快？

• 基于内存操作：数据直接存储在内存中，省去了磁盘 I/O 的寻道与读写开销（内存访问速度比磁盘快数万倍）。
• 单线程模型：核心网络处理采用单线程，避免了多线程环境下的上下文切换和锁竞争开销，保证了操作的原子性。
• I/O 多路复用：使用 epoll 非阻塞 I/O 模型，单个线程即可高效处理数万个并发连接。
• 高效的数据结构：Redis 内部对各种结构（如 SDS 字符串、跳表 SkipList、压缩列表 ZipList）进行了极致的内存优化和算法优化。

数据类型和数据结构

Redis 有哪些数据类型？

五种基础数据类型

三种高级数据类型

新一代数据类型

• Stream：Redis 5.0 新增，主要用于实现持久化的消息队列（类似 Kafka），解决了 List 做队列时消息丢失的问题。

谈谈 Redis 的对象机制（redisObject）

typedef struct redisObject {
    unsigned type:4;       // 1. 类型（对外，即通常说的 5 大数据类型）
    unsigned encoding:4;   // 2. 编码（对内，内部编码）
    unsigned lru:24;       // 3. 记录 LRU/LFU 信息（用于淘汰）
    int refcount;          // 4. 引用计数（用于内存回收）
    void *ptr;             // 5. 指针（指向底层实际的数据结构）
} robj;

设计这套对象机制的原因有以下三点：

• 解耦：命令（如 LLEN）只需要针对 List 类型，不需要关心底层是 ZipList 还是 LinkedList。
• 极致的内存优化：小数据量用紧凑存储（时间换空间），大数据量用高效索引（空间换时间）。
• 智能维护：自带引用计数和访问记录，自动处理内存回收和缓存淘汰。

Redis 数据类型有哪些底层数据结构？

为什么要设计 SDS？

Redis 没有直接使用 C 语言的字符串（char*），而是自己封装了 SDS。C 语言原生的字符串（以 \0 结尾）无法满足 Redis 对高性能和安全性的要求。SDS 的设计优势如下：

• 常数复杂度获取长度：内部记录了 len 属性，读取长度的时间复杂度为 O(1)。
• 杜绝缓冲区溢出：修改前会先检查空间是否足够，不足则自动扩容。
• 减少内存重分配：采用空间预分配和惰性空间释放策略。
• 二进制安全：不以 \0 判断结束，可以存储图片、音频等二进制数据。

一个字符串类型的值能存储的最大容量是多少？

512 MB

为什么会设计 Stream？

在 Stream 出现之前，Redis 的消息发布订阅有明显痛点：

• List 类型：虽能持久化，但不支持多消费组，确认机制（ACK）实现复杂。
• Pub/Sub：无法持久化，消息“发完即丢“，消费者离线会导致消息丢失。

Stream 的设计目标：提供一个支持持久化、支持多消费组、支持消息确认机制的高可用消息队列模型。

Stream 用在什么场景？

• 异步任务处理：需要保证消息不丢失的任务流。
• 多端消费：同一个数据流需要被不同的业务系统（如结算系统、通知系统）同时消费。
• 高性能日志采集：利用其追加写入的特性，记录海量流水数据。

消息 ID 的设计是否考虑了时间回拨的问题？

考虑了。 Stream 的 ID 默认格式是 <millisecondsTime>-<sequenceNumber>。

• 防御机制：Redis 会记录服务器当前最大的 ID 时间戳。
• 处理逻辑：如果系统时间发生回拨，导致产生的时间戳小于上一个 ID，Redis 会强制使用上一次的时间戳，并递增其序列号，从而保证 ID 的单调递增性。

持久化和内存

Redis 的持久化机制是什么？各自的优缺点？一般怎么用？

一般用法：混合持久化（RDB + AOF）。用 RDB 做全量备份，用 AOF 做增量记录，兼顾安全与速度。

Redis 过期键的删除策略有哪些？

Redis 采用 “惰性删除 + 定期删除” 配合使用：

• 惰性删除：访问 key 时才检查是否过期，过期则删除。（省 CPU，费内存）
• 定期删除：每隔一段时间随机抽取一部分 key 检查并删除。（折中方案）

Redis 内存淘汰算法有哪些？

当内存达到 maxmemory 限制时，触发以下算法：

Redis 的内存用完了会发生什么？

• 如果设置了淘汰策略（如 allkeys-lru），Redis 会根据算法自动删除旧数据腾出空间。
• 如果没有设置策略或策略为 noeviction，Redis 将拒绝所有写请求（报错 OOM），但读请求正常。

Redis 如何做内存优化？

• 控制 Key 长度：缩短键名。
• 避免存储大 Key：拆分大的 Hash 或 List。
• 使用高效编码：尽量利用 ZipList（压缩列表）存储小规模数据。
• 设置过期时间：确保冷数据能自动释放。
• 开启内存碎片整理：配置 activedefrag yes。

Redis key 的过期时间和永久有效分别怎么设置？

• 设置过期：EXPIRE key seconds 或 PEXPIRE key milliseconds
• 永久有效：默认创建即永久。若需取消过期时间，使用 PERSIST key

Redis 中的管道有什么用？

• 作用：将多个命令打包一次性发送给服务器，减少网络 RTT（往返时延）。
• 效果：极大提升批量操作的性能。从“发一个收一个“变成“发一堆收一堆“。

Docker 教程：基础命令概念 & Dockerfile

1. Docker 基础概念

1.1 什么是 Docker

Docker 的出现是为了解决软件开发过程中的环境配置问题。软件的运行需要满足两个核心条件：操作系统配置正确，依赖库和组件完整安装。以 Python 应用为例，用户的电脑必须配备 Python 运行时环境、各种第三方依赖包、正确的环境变量配置。当老旧模块和新环境产生冲突时，兼容性更是麻烦的问题。在此背景下诞生了 Docker。

Docker 是一个开源的容器化平台，它使用操作系统级别的虚拟化技术，将应用程序及其依赖项打包到一个轻量级、可移植的容器中。容器可以在任何支持 Docker 的环境中运行，确保应用程序的一致性和可移植性。

1.2 核心概念

Container（容器）

容器是镜像的运行实例，就像是一个独立运行的小型虚拟环境。它本质上是一个被隔离的进程，拥有自己的文件系统、网络和进程空间，但与宿主机共享操作系统内核。就像面向对象编程中从“类“创建出来的“对象“一样，一个镜像可以启动多个容器实例，每个容器都有自己的运行状态和数据。

Image（镜像）

镜像是一个只读的模板文件，包含了运行某个应用程序所需的完整环境：代码、运行时库、系统工具、环境变量、配置文件等所有依赖。它就像面向对象编程中的“类“定义，描述了容器应该是什么样子，但本身不能直接运行，需要通过镜像来创建和启动容器实例。

Dockerfile

Dockerfile 是一个纯文本文件，包含了一系列构建镜像的指令和命令。它定义了从选择基础镜像开始，到安装依赖、复制代码、设置环境变量、暴露端口等一步步构建最终镜像的完整过程。相当于是制作镜像的“配方“或“脚本“，让镜像构建过程可重复、可版本控制。

Repository（仓库）

仓库是存储和分发镜像的中心化服务，就像代码的 Git 仓库一样。Docker Hub 是最大的公共镜像仓库，提供了大量官方和社区维护的镜像供下载使用。企业也可以搭建私有仓库来存储内部镜像，实现镜像的版本管理、分发和共享。

1.3 Docker vs 传统虚拟机

1.4 Docker 安装与配置

网上已有很多安装配置教程，不再赘述，具体可参考官网：https://docs.docker.com/desktop/

1.5 Docker 基础命令

Docker 常用指令：https://www.runoob.com/docker/docker-command-manual.html

2. Dockerfile 编写指南

2.1 基本语法

# 基础镜像 - 必须是第一条指令
FROM ubuntu:20.04

# 设置工作目录
WORKDIR /app

# 复制文件到容器
COPY . .
COPY requirements.txt /app/

# 添加文件（支持 URL 和自动解压）
ADD https://example.com/file.tar.gz /tmp/

# 执行命令（构建时）
RUN apt-get update && apt-get install -y python3

# 暴露端口
EXPOSE 8080

# 设置环境变量
ENV NODE_ENV=production

# 容器启动命令
CMD ["python3", "app.py"]

2.2 常用指令

2.3 示例：Python Flask 应用

# 使用官方 Python 镜像
FROM python:3.9-slim

# 设置工作目录
WORKDIR /app

# 复制依赖文件
COPY requirements.txt .

# 安装依赖
RUN pip install --no-cache-dir -r requirements.txt

# 复制应用代码
COPY . .

# 暴露端口
EXPOSE 5000

# 设置环境变量
ENV FLASK_APP=app.py
ENV FLASK_ENV=production

# 启动命令
CMD ["flask", "run", "--host=0.0.0.0"]

3. Docker 核心优势

• 一致性：确保开发、测试、生产环境一致
• 可移植性：在任何支持 Docker 的环境中运行
• 资源效率：比传统虚拟机更轻量级
• 快速部署：秒级启动和扩展

Docker 教程 — Docker Compose vs Docker Swarm

1. Docker Compose 与 Docker Swarm

1.1 基本概念与定位

Docker Compose 是一个用于定义和运行多容器 Docker 应用的工具，通过 YAML 配置文件来管理应用服务的编排。它主要面向单主机环境，特别适合本地开发和小规模部署场景。

Docker Swarm 是 Docker 的原生容器编排平台，能够将多个 Docker 主机组成集群，提供跨节点的容器调度、负载均衡和高可用性功能。它旨在简化生产环境中的容器编排复杂性。

1.2 技术架构差异

2. 个人项目部署场景

推荐使用 Docker Compose

对于个人项目，推荐使用 Docker Compose，因为它在资源消耗、维护成本和学习门槛方面都更加友好——通过单一 YAML 文件即可管理整个应用栈，几分钟内完成部署，无需专业的 DevOps 技能，系统资源占用少，完全能够满足个人项目的小规模负载需求，是性价比最高的容器编排解决方案。

3. 个人项目 Docker 部署架构设计

3.1 配置文件解析 — docker-compose.yml 关键配置

version: '3.8'
services:
  backend:
    image: registry.example.com/my-app/backend:latest
    container_name: my-app-backend
    ports:
      - "8000:8000"
    environment:
      # 环境配置集中管理
      - PYTHONUNBUFFERED=1
      - PYTHONWARNINGS=ignore::DeprecationWarning
      - LOG_LEVEL=INFO
      - APP_ENV=prod
      # 数据库配置
      - DATABASE_URL=${DATABASE_URL}
      - REDIS_URL=${REDIS_URL}
      # JWT配置
      - SECRET_KEY=${SECRET_KEY}
      # 第三方服务配置
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - OPENAI_BASE_URL=${OPENAI_BASE_URL:-https://api.openai.com/v1}
      # 启用定时任务
      - ENABLE_SCHEDULED_JOBS=true
    volumes:
      # 数据持久化
      - ./backend/uploads:/app/uploads
      - ./backend/logs:/app/logs
    command: python run_server.py
    restart: always
    deploy:
      restart_policy:
        condition: on-failure
        delay: 60s
    networks:
      - app-network

  frontend:
    image: registry.example.com/my-app/frontend:latest
    container_name: my-app-frontend
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - REACT_APP_API_URL=http://backend:8000  # 服务间通信
      - REACT_APP_TITLE=我的个人项目
    depends_on:
      - backend  # 服务依赖管理
    restart: always
    deploy:
      restart_policy:
        condition: on-failure
        delay: 60s
    networks:
      - app-network

networks:
  app-network:
    driver: bridge  # 内部网络隔离

3.2 脚本梳理详解

• docker-compose.yml — 定义服务编排的核心文件，包含：

  • builder 阶段：安装依赖（使用 uv 包管理器），构建虚拟环境
  • runner 阶段：复制代码和虚拟环境，构建最终运行镜像，设置环境变量并启动主程序

• Dockerfile.base — 构建基础镜像的配置文件：

  • 基于可配置的基础镜像（镜像地址、名称、标签）构建后端应用镜像
  • 复制项目代码到容器中
  • 设置容器启动时运行指定脚本

• Dockerfile — 构建最终镜像，设计两个主要服务：

  • backend 服务：包含 API 服务和定时任务（jobs 已集成在主应用中）
  • frontend 服务：React 前端应用

3.3 执行顺序

开发或部署前首次使用时：

1. 执行 Dockerfile.base 构建基础镜像
2. 执行 Dockerfile 构建应用镜像
3. 执行 docker-compose.yml 启动服务

已经有镜像时：

• 只需要执行 docker-compose.yml，它会自动拉取镜像并运行容器

5 分钟用 Docker 自建 Supabase

Supabase 是一个开源的 Firebase 替代品，提供数据库、认证、存储、边缘函数等功能。官方提供 Docker 部署方案，几分钟就能在本地跑起来。

1. 安装 Docker Desktop

如果没有 Docker Desktop，先去下载：

👉 https://www.docker.com/products/docker-desktop

安装完成后确保 Docker 正常运行。

2. 克隆 Supabase 仓库

git clone https://github.com/supabase/supabase.git
cd supabase/docker

复制配置文件：

cp .env.example .env

3. 配置管理后台

用 vim 或你熟悉的编辑器打开 .env，找到 Access to Dashboard 部分：

DASHBOARD_USERNAME=username
DASHBOARD_PASSWORD=pwd

改成你自己的用户名和密码。

4. 启动服务

docker compose up -d

第一次启动会拉取镜像，需要等待几分钟。

5. 访问 Supabase

启动完成后：

用刚才配置的账号密码登录管理后台。

6. 玩转 Supabase

自建版本可以做什么：

• 📊 PostgreSQL 数据库 — 完全的 PostgreSQL 权限
• 🔐 用户认证 — 内置邮箱、社交登录
• 📁 文件存储 — 对象存储服务
• ⚡️ 边缘函数 — Deno / Edge Functions
• 📡 实时订阅 — Realtime 数据同步

7. 外网访问（进阶）

自建的 Supabase 默认只能在本地访问，如果想从外网也能访问，可以搭建内网穿透：

• 可以用 Cloudflare Tunnel、frp、cpolar 等工具
• 把本地端口 8000 映射到公网
• 就可以在任何地方访问你的 Supabase 服务

常用命令

停止服务

docker compose down

重启服务

docker compose restart

查看日志

docker compose logs -f

适用场景

• ✅ 本地开发测试
• ✅ 私有化部署
• ✅ 学习研究
• ⚠️ 生产环境不推荐（官方建议用云服务）

Ubuntu 安装 Redis 并配置远程连接指南

1. 更新包列表

sudo apt update

2. 安装 Redis

sudo apt install redis-server -y

3. 启动并设置开机自启

sudo systemctl enable redis-server

4. 验证

sudo systemctl status redis-server

5. 基本配置

sudo vim /etc/redis/redis.conf

修改以下项：

# 允许外部连接（默认只允许本机）
bind 0.0.0.0

# 关闭保护模式
protected-mode no

# 设置密码（必须！否则裸奔极易被入侵挖矿）
requirepass 强密码

6. 重启生效

sudo systemctl restart redis-server

7. 开放防火墙端口

sudo ufw allow 6379/tcp

注意：如果是云服务器（腾讯云/阿里云等），还需要在云控制台的安全组中放行 6379 端口的入站规则。

8. 本地连接

redis-cli -h 你的服务器公网IP -p 6379 -a 你的强密码

连上后输入 ping，返回 PONG 即成功。

排查连接问题

如果连接不上，可以逐步排查：

1. 确认服务端 Redis 是否在运行

# 在线上服务器执行
sudo systemctl status redis-server

2. 检查 Redis 监听地址

sudo grep "^bind" /etc/redis/redis.conf

确保是 bind 0.0.0.0，而不是 bind 127.0.0.1。

3. 确认 Redis 实际监听端口

sudo ss -tlnp | grep 6379

正常应显示 0.0.0.0:6379，如果是 127.0.0.1:6379 说明 bind 没改对或没重启。

4. 检查防火墙

sudo ufw status

确认 6379 已放行。

5. 检查云服务器安全组

去云控制台 → 安全组 → 入站规则，添加：

服务器连接指南：SSH 公私钥认证

核心原理

SSH 免密登录的核心逻辑是**“认卡不认人”**：将本地电脑的公钥（Public Key），存入线上服务器的信任白名单（authorized_keys）中。以后只要本地的私钥能和服务器上的公钥配对成功，就能直接登录，无需输入密码。

操作步骤

第一步：在「本地电脑」获取公钥

$ cd ~/.ssh                      # 进入本地SSH配置目录
$ ls                             # 查看目录内容
$ cat id_ed25519.pub             # 查看并输出公钥内容

在做什么： 去本地的密钥存放地（~/.ssh），找到你的公钥文件（包含 .pub 后缀，代表 Public），把里面以 ssh-ed25519... 开头的内容全部复制下来。

说明： 这里使用的是 ed25519 算法的密钥，这是目前推荐的类型，比传统的 rsa 更安全且更短、解析更快。

第二步：将公钥添加到「线上服务器」

将复制的公钥内容，粘贴到服务器的 ~/.ssh/authorized_keys 文件中。

🔒 注意： 此操作通常仅管理员可控。

拓展小贴士

新电脑没有密钥？ 如果连 id_ed25519 文件都没有，只需在本地执行以下命令一键生成：

ssh-keygen -t ed25519

一条命令搞定复制粘贴？ 上述手动复制公钥到服务器的操作，可以直接用以下命令代替：

ssh-copy-id ubuntu@服务器IP

FastSAM-Demo：基于 SAM 2.1 的全栈图像分割工程实践

GitHub: https://github.com/Eva-Dengyh/FastSAM-Demo

上传图片，点一下，物体被精准高亮。这是 Meta 开源的 SAM 2.1 + 全栈工程化的结合。

背景：什么是图像分割？

图像分割是计算机视觉的核心任务之一：给定一张图片，找出每个像素属于哪个物体。

传统方案需要大量标注数据、精调模型，门槛极高。

2023 年，Meta 发布了 Segment Anything Model（SAM），彻底改变了这一局面——它可以对任意图片、任意物体进行零样本分割，只需要用户给一个点或框作为提示。

2024 年 9 月，Meta 发布了 SAM 2.1，在更小的参数量下实现了更好的效果，同时新增视频分割能力，并以 Apache 2.0 协议完全开源。

为什么选 SAM 2，而不是 SAM 3？

Meta 的 SAM 系列目前有三代，选型时逐一对比：

SAM 3 为什么没选？

SAM 3 于 2025 年 11 月发布，但获取权重需要在 Hugging Face 申请访问权限，审批通过后才能下载。除此之外，SAM 3 强制要求 CUDA GPU（PyTorch 2.7+、CUDA 12.6+），且许可证改为 SAM License（非 Apache 2.0），限制更多。对于想快速跑通 Demo、CPU 本地调试的场景来说，门槛太高了。

SAM 1 为什么没选？

SAM 1 不支持视频分割，且最小模型也有 86M，精度和速度均不如 SAM 2.1 的同尺寸版本。

最终选 SAM 2.1 的理由：

• 最新正式开放版本，权重直接 wget 下载，零申请门槛
• 4 种尺寸（39M ~ 224M），tiny 版本 CPU 也能跑
• 图片和视频分割统一架构，扩展性好
• Apache 2.0 完全开源，商用友好

项目：FastSAM-Demo

FastSAM-Demo 是一个基于 SAM 2.1 的交互式图像分割 Web 应用。

核心交互极简：上传图片 → 点击物体 → 实时高亮分割结果。

核心特性

技术栈

• 后端：FastAPI + SAM 2.1（Python / uv）
• 前端：Next.js 15 + TypeScript + Tailwind CSS v4 + Framer Motion

系统架构

整体分为两层：前端负责交互与渲染，后端负责模型推理。

Browser (Next.js + TypeScript)
│
│  用户点击图片 (x, y)
│
▼
useSegmentation Hook
│ POST /api/segment
▼
FastAPI Server
│
├── Image Cache（复用 embedding，避免重复编码）
│
└── SAM 2.1 ImagePredictor
      ├── set_image()   ← 上传时预计算，耗时一次
      └── predict()     ← 每次点击调用，毫秒级返回

关键设计：Embedding 缓存

SAM 2.1 的推理分两步，耗时差距悬殊：

关键优化：上传图片时一次性计算 embedding 并缓存，后续每次点击只跑轻量的 Mask Decoder。这是交互“毫秒级响应“的核心原因。

数据流全貌

1. 用户上传图片
 → POST /api/upload
 → 后端 set_image()，embedding 缓存到内存
 → 返回 image_id

2. 用户点击图片 (x, y)
 → 前端坐标映射（Canvas 坐标 → 原图坐标）
 → POST /api/segment { image_id, x, y }
 → 后端复用缓存 embedding，调用 predict()
 → SAM 2.1 输出 masks + scores
 → RLE 压缩后返回前端
 → 前端 Canvas 解码渲染，半透明高亮叠加原图

3. 继续点击 → 重复步骤 2，多 mask 叠加显示

SAM 2.1 核心原理

架构

SAM 2.1 由三个核心模块组成：

图片/视频帧
  │
  ▼
Hiera Encoder（图像编码器）
  │ image embedding
  ▼
Mask Decoder ← Prompt Encoder（接收点/框/mask 提示）
  │
  ▼
masks + scores + logits

• Hiera Encoder：比 SAM 1 的 ViT 更高效的层次化视觉编码器，参数量大幅缩减
• Prompt Encoder：将点击坐标、框选区域等提示信息编码
• Mask Decoder：融合图像特征和提示信息，输出分割掩码
• Memory Attention：视频模式下跨帧传递分割信息（本项目图片模式未使用）

模型尺寸对比

CPU 本地 Demo 推荐 tiny，速度与体验均衡。

前端工程化

前端采用 Next.js 15（App Router）+ TypeScript 的现代化方案，分层清晰：

types/       TypeScript 类型定义（与后端 Pydantic Schema 对齐）
lib/         API 封装 + mask RLE 解码 + Canvas 渲染工具
hooks/       useSegmentation（业务逻辑聚合）
components/  ImageUploader / SegmentCanvas / ControlPanel（纯 UI）
app/         Next.js 页面入口

核心原则：组件只管 UI，业务逻辑收归 Hook。

Next.js rewrites 代理后端 API，彻底解决 CORS 问题，前端代码无需关心后端地址。

快速上手

# 克隆项目
git clone https://github.com/Eva-Dengyh/FastSAM-Demo.git
cd FastSAM-Demo

# 一键启动（自动安装依赖 + 下载模型 + 启动前后端）
./start.sh

启动后访问：

• 前端：http://localhost:3000
• 后端 API 文档：http://localhost:8000/docs

不想一键启动？手动步骤也很简单：

# 后端
cd backend && uv sync
mkdir -p checkpoints
wget -O checkpoints/sam2.1_hiera_tiny.pt \
  https://dl.fbaipublicfiles.com/segment_anything_2/092824/sam2.1_hiera_tiny.pt
uv run uvicorn app.main:app --host 0.0.0.0 --port 8000

# 前端（新终端）
cd frontend && npm install && npm run dev

写在最后

这个项目的核心价值在于把 AI 模型 + 全栈工程实践 结合在一起：

• SAM 2.1 提供了世界级的分割能力，且完全开源免费
• FastAPI + Next.js 的全栈方案展示了清晰的工程化思路
• Embedding 缓存、RLE 压缩等细节体现了对性能的关注

如果你对 AI + Web 全栈开发感兴趣，这个项目是一个很好的起点。代码完全开源，欢迎 Star、Fork 和提 Issue。

GitHub: https://github.com/Eva-Dengyh/FastSAM-Demo

基于 SAM 2.1 的图像分割全栈实践 V2：Docker 部署与导出功能落地

FastSAM-Demo 是一个基于 Meta SAM 2.1 的交互式图像分割 Web 应用，用户上传图片后点击目标区域，即可实时完成 AI 分割。本次更新带来 Docker 一键部署与三种导出模式。

适用场景：

• 内容创作 / 设计：快速抠图、替换背景、提取主体，无需 PS 专业技能
• 家具电商：上传家具产品图，一键抠出主体，去除杂乱背景，生成白底或场景合成素材，提升商品图质量
• 数据标注：为目标检测、实例分割等机器学习任务批量生成掩码标注
• 科研与教学：演示 SAM 2.1 能力，验证分割效果，快速出图用于论文插图
• 产品原型验证：在自研图像处理管线中嵌入分割能力，快速跑通概念验证
• 本地隐私处理：全离线运行，医疗影像、工业质检等对数据合规有要求的场景同样适用

🐳 新增：Docker 部署

现在支持一键 Docker 部署，无需手动配置 Python 环境、Node 版本或处理依赖冲突，开箱即用。

适用场景：

• 快速在新机器或服务器上搭建演示环境
• 团队统一开发 / 测试环境，避免「在我这里能跑」问题
• CI/CD 流水线集成，受限环境（无法直接配置 Python/Node）下开箱即用

新增文件

启动命令

docker-compose up --build

• 前端：http://localhost:3001
• 后端：http://localhost:8001

后端使用 uv 管理依赖，安装速度显著快于 pip。前端采用 Next.js 15 standalone 模式构建，镜像体积更小，启动更快。

📥 新增：导出功能

分割完成后，现在可以将结果以三种模式直接导出为 PNG 图片，满足不同下游使用需求。

• 触发条件：有分割结果时显示「导出」按钮
• 掩码色：红、橙、黄、绿、青、蓝、紫、粉（8 色循环，多目标自动区分）
• 导出格式：PNG（无损）

✍️ 写在最后

两个更新都指向同一个目标：让 FastSAM-Demo 更容易用起来。Docker 解决的是「跑起来」的门槛，导出功能解决的是「用出去」的最后一步。

项目完全开源，欢迎 Star、Fork 或提 Issue。

项目地址：https://github.com/Eva-Dengyh/FastSAM-Demo

GitHub 主页进化论：三步定制专属 README 模版

第一步：创建你的个人主页仓库

如果还没创建过，需要先建立一个特殊的仓库：

1. 在 GitHub 上新建一个仓库。

2. 仓库名必须和你的 GitHub 用户名 完全一致（区分大小写）。

3. 勾选 Add a README file。

4. 创建后，这个仓库的 README.md 就会显示在你的个人主页顶部。

第二步：挑选并复制模版

模版库地址：https://github.com/kautukkundan/Awesome-Profile-README-templates/tree/master

这个仓库里的模版按风格分成了几个文件夹，可以进去挑选：

• short-and-sweet：简洁风格。
• code-styled：极客风格，看起来像代码编辑器。
• dynamic-realtime：动态实时更新（通常需要配合 GitHub Actions）。
• elaborate：内容详尽，包含很多图表和介绍。
• multimedia：包含多媒体元素（GIF 等）。

套用方法

1. 浏览文件夹：点击进入上述任一文件夹。

2. 打开文件：你会看到很多以用户名命名的 .md 文件（例如 saviomartin.md）。点击你觉得好看的文件。

3. 复制代码：

   • 情况 A（直接有代码）：如果文件里包含大量的 Markdown 代码（如徽章链接、自我介绍文本），直接点击文件右上角的 Copy raw file 按钮复制全部内容。

   • 情况 B（只有图片/链接）：有些文件可能只展示了一张效果图和一个链接（如 “From xxxx”）。这时你需要点击那个链接跳转到原作者的主页，找到原作者同名仓库（username/username）里的 README.md，然后复制那里的代码。

第三步：修改与个性化

将复制的代码粘贴到你自己仓库的 README.md 中。这一步最关键，因为直接保存会显示别人的信息。你需要做全局替换：

1. 替换用户名：使用文本编辑器的“查找替换“功能，将模版原作者的用户名（例如 saviomartin）全部替换为你自己的 GitHub 用户名。这会自动修复你的统计卡片、徽章和链接。

2. 修改个人信息：

   • 修改自我介绍（“Hi, I’m…”）。
   • 修改社交媒体链接（Twitter, LinkedIn 等）。
   • 修改技能图标（删除你不会的，添加你会的）。

3. 保存提交：点击 Commit changes 保存。

最终实现效果

页面效果参考代码见：https://github.com/Eva-Dengyh/Eva-Dengyh/edit/main/README.md

Hermes Agent 系列

本系列记录 Hermes Agent 的本地运行、配置与扩展实践。文章按主题拆分，便于后续追加新篇。

目录

1. 本地启动与项目结构

Hermes Agent 教程（1）：本地启动与项目结构

项目地址：https://github.com/NousResearch/hermes-agent

启动项目

Step 1：拉取项目到本地

git clone https://github.com/NousResearch/hermes-agent.git

Step 2：进入项目目录

cd hermes-agent

若你放在固定路径，也可使用绝对路径，例如：

cd /Users/YolieDeng/Code/hermes-agent

Step 3：创建并进入虚拟环境

uv venv
source .venv/bin/activate

Step 4：安装项目依赖

uv sync

Step 5：配置 .env

cp .env.example .env

编辑 .env，填入你的 API 密钥。例如使用 MiniMax：

# MINIMAX_API_KEY=your-key-here

Step 6：模型选择与启动

hermes doctor
# 选择适合的模型
hermes model
hermes

成功启动后，终端会出现交互界面，即可开始对话。

项目结构讲解

hermes-agent/
     │
     ├── 📁 核心框架模块
     │   ├── agent/                              # Agent 核心逻辑和执行引擎
     │   ├── gateway/                            # API 网关、请求路由、钩子系统
     │   │   ├── builtin_hooks/                  # 内置钩子集合
     │   │   └── platforms/                      # 多平台适配
     │   ├── hermes_cli/                         # CLI 命令行接口
     │   └── tools/                              # 工具系统和工具调用解析器
     │       ├── browser_providers/              # 浏览器供应商
     │       ├── environments/                   # 工具环境配置
     │       └── neutts_samples/                 # 神经 TTS 示例
     │
     ├── 📁 配置与适配
     │   ├── acp_adapter/                        # ACP 协议适配器
     │   ├── acp_registry/                       # 服务注册表
     │   ├── plugins/                            # 插件系统
     │   │   └── memory/                         # 内存/记忆插件
     │   │       ├── byterover/                  # Byterover 内存实现
     │   │       ├── hindsight/                  # Hindsight 内存实现
     │   │       ├── holographic/                # Holographic 内存实现
     │   │       ├── honcho/                     # Honcho 内存实现
     │   │       ├── mem0/                       # Mem0 内存实现
     │   │       ├── openviking/                 # OpenViking 内存实现
     │   │       ├── retaindb/                   # RetainDB 内存实现
     │   │       └── supermemory/                # SuperMemory 内存实现
     │   └── environments/                       # 环境配置和管理
     │       ├── benchmarks/                     # 基准测试环境
     │       │   ├── tblite/                     # TBLite 基准
     │       │   ├── terminalbench_2/            # 终端基准 2
     │       │   └── yc_bench/                   # YC 基准
     │       ├── hermes_swe_env/                 # Hermes SWE 环境
     │       ├── terminal_test_env/              # 终端测试环境
     │       └── tool_call_parsers/              # 工具调用解析器
     │
     ├── 📁 功能扩展 - Skills（完整技能列表）
     │   └── skills/                             # 完整技能模块集合
     │       │
     │       ├── 📂 苹果生态技能
     │       │   └── apple/
     │       │       ├── apple-notes/            # Apple Notes 集成
     │       │       ├── apple-reminders/        # Apple Reminders 集成
     │       │       ├── findmy/                 # Find My 定位服务
     │       │       └── imessage/               # iMessage 消息
     │       │
     │       ├── 📂 AI Agent 技能
     │       │   └── autonomous-ai-agents/
     │       │       ├── claude-code/            # Claude Code 集成
     │       │       ├── codex/                  # Codex AI 集成
     │       │       ├── hermes-agent/           # Hermes Agent 自身
     │       │       └── opencode/               # OpenCode 集成
     │       │
     │       ├── 📂 创意工具
     │       │   └── creative/
     │       │       ├── ascii-art/              # ASCII 艺术生成
     │       │       ├── ascii-video/            # ASCII 视频生成
     │       │       ├── excalidraw/             # Excalidraw 绘图
     │       │       ├── manim-video/            # Manim 视频制作
     │       │       ├── p5js/                   # P5.js 创意编程
     │       │       └── songwriting-and-ai-music/  # 作曲和 AI 音乐
     │       │
     │       ├── 📂 数据科学
     │       │   └── data-science/
     │       │       └── jupyter-live-kernel/    # Jupyter 实时内核
     │       │
     │       ├── 📂 运维和开发工具
     │       │   ├── devops/
     │       │   │   └── webhook-subscriptions/  # Webhook 订阅
     │       │   ├── diagramming/                # 图表工具
     │       │   └── domain/                     # 域名工具
     │       │
     │       ├── 📂 Email 工具
     │       │   └── email/
     │       │       └── himalaya/               # Himalaya 邮件客户端
     │       │
     │       ├── 📂 Feed 和 RSS
     │       │   └── feeds/                      # Feed 聚合工具
     │       │
     │       ├── 📂 游戏工具
     │       │   └── gaming/
     │       │       ├── minecraft-modpack-server/  # Minecraft 模组服务器
     │       │       └── pokemon-player/         # 宝可梦玩家工具
     │       │
     │       ├── 📂 GIF 工具
     │       │   └── gifs/                       # GIF 生成和处理
     │       │
     │       ├── 📂 GitHub 集成
     │       │   └── github/
     │       │       ├── codebase-inspection/    # 代码库检查
     │       │       ├── github-auth/            # GitHub 认证
     │       │       ├── github-code-review/     # 代码审查
     │       │       ├── github-issues/          # Issue 管理
     │       │       ├── github-pr-workflow/     # PR 工作流
     │       │       └── github-repo-management/ # 仓库管理
     │       │
     │       ├── 📂 索引和缓存
     │       │   └── index-cache/                # 索引缓存
     │       │
     │       ├── 📂 推理工具
     │       │   └── inference-sh/               # 推理 Shell 脚本
     │       │
     │       ├── 📂 休闲娱乐
     │       │   └── leisure/
     │       │       └── find-nearby/            # 附近地点查找
     │       │
     │       ├── 📂 MCP（模型上下文协议）
     │       │   └── mcp/
     │       │       ├── mcporter/               # MCP 转换器
     │       │       └── native-mcp/             # 原生 MCP 支持
     │       │
     │       ├── 📂 媒体工具
     │       │   └── media/
     │       │       ├── gif-search/             # GIF 搜索
     │       │       ├── heartmula/              # 音乐播放器
     │       │       ├── songsee/                # 歌曲识别
     │       │       └── youtube-content/        # YouTube 内容工具
     │       │
     │       ├── 📂 MLOps 工具
     │       │   └── mlops/
     │       │       ├── cloud/                  # 云平台工具
     │       │       ├── evaluation/             # 模型评估
     │       │       ├── huggingface-hub/        # HuggingFace 集成
     │       │       ├── inference/              # 模型推理
     │       │       ├── models/                 # 模型管理
     │       │       ├── research/               # 研究工具
     │       │       ├── training/               # 模型训练
     │       │       └── vector-databases/       # 向量数据库
     │       │
     │       ├── 📂 笔记应用
     │       │   └── note-taking/
     │       │       └── obsidian/               # Obsidian 笔记集成
     │       │
     │       ├── 📂 生产力工具
     │       │   └── productivity/
     │       │       ├── google-workspace/       # Google Workspace 集成
     │       │       ├── linear/                 # Linear 项目管理
     │       │       ├── nano-pdf/               # PDF 工具
     │       │       ├── notion/                 # Notion 集成
     │       │       ├── ocr-and-documents/      # OCR 和文档处理
     │       │       └── powerpoint/             # PowerPoint 制作
     │       │
     │       ├── 📂 红队工具
     │       │   └── red-teaming/
     │       │       └── godmode/                # GodMode 工具
     │       │
     │       ├── 📂 研究工具
     │       │   └── research/
     │       │       ├── arxiv/                  # ArXiv 论文
     │       │       ├── blogwatcher/            # 博客监控
     │       │       ├── llm-wiki/               # LLM Wiki
     │       │       ├── polymarket/             # Polymarket 数据
     │       │       └── research-paper-writing/ # 论文写作
     │       │
     │       ├── 📂 智能家居
     │       │   └── smart-home/
     │       │       └── openhue/                # OpenHue 智能灯控
     │       │
     │       ├── 📂 社交媒体
     │       │   └── social-media/
     │       │       └── xitter/                 # X/Twitter 集成
     │       │
     │       └── 📂 软件开发
     │           └── software-development/
     │               ├── plan/                   # 计划工具
     │               ├── requesting-code-review/ # 代码审查请求
     │               ├── subagent-driven-development/  # 子 Agent 驱动开发
     │               ├── systematic-debugging/   # 系统化调试
     │               ├── test-driven-development/  # TDD 工具
     │               └── writing-plans/          # 计划编写
     │
     ├── 📁 可选技能扩展
     │   └── optional-skills/                    # 可选安装的高级技能包
     │       │
     │       ├── 📂 自主 AI Agent
     │       │   └── autonomous-ai-agents/
     │       │       ├── blackbox/               # BlackBox AI
     │       │       └── honcho/                 # Honcho 框架
     │       │
     │       ├── 📂 区块链技能
     │       │   └── blockchain/
     │       │       ├── base/                   # Base 区块链
     │       │       └── solana/                 # Solana 链
     │       │
     │       ├── 📂 通信工具
     │       │   └── communication/
     │       │       └── one-three-one-rule/     # 一对一通信规则
     │       │
     │       ├── 📂 创意能力
     │       │   └── creative/
     │       │       ├── blender-mcp/            # Blender 3D 建模
     │       │       └── meme-generation/        # 梗图生成
     │       │
     │       ├── 📂 DevOps 高级工具
     │       │   └── devops/
     │       │       ├── cli/                    # DevOps CLI
     │       │       └── docker-management/      # Docker 管理
     │       │
     │       ├── 📂 邮件服务
     │       │   └── email/
     │       │       └── agentmail/              # Agent 邮件服务
     │       │
     │       ├── 📂 健康工具
     │       │   └── health/
     │       │       └── neuroskill-bci/         # 脑机接口工具
     │       │
     │       ├── 📂 MCP 工具
     │       │   └── mcp/
     │       │       └── fastmcp/                # FastMCP 框架
     │       │
     │       ├── 📂 数据迁移
     │       │   └── migration/
     │       │       └── openclaw-migration/     # OpenClaw 迁移工具
     │       │
     │       ├── 📂 MLOps 高级功能（17 个子模块）
     │       │   └── mlops/
     │       │       ├── accelerate/             # Hugging Face Accelerate
     │       │       ├── chroma/                 # Chroma 向量库
     │       │       ├── faiss/                  # Facebook FAISS
     │       │       ├── flash-attention/        # Flash Attention 优化
     │       │       ├── hermes-atropos-environments/  # Atropos 环境
     │       │       ├── huggingface-tokenizers/ # HF Tokenizers
     │       │       ├── instructor/             # Instructor 框架
     │       │       ├── lambda-labs/            # Lambda Labs GPU
     │       │       ├── llava/                  # LLaVA 多模态
     │       │       ├── nemo-curator/           # NeMo Curator
     │       │       ├── pinecone/               # Pinecone 向量 DB
     │       │       ├── pytorch-lightning/      # PyTorch Lightning
     │       │       ├── qdrant/                 # Qdrant 向量 DB
     │       │       ├── saelens/                # SAELENS 框架
     │       │       ├── simpo/                  # SimPO 训练
     │       │       ├── slime/                  # SLIME 框架
     │       │       ├── tensorrt-llm/           # TensorRT LLM
     │       │       └── torchtitan/             # TorchTitan 分布式
     │       │
     │       ├── 📂 生产力扩展
     │       │   └── productivity/
     │       │       ├── canvas/                 # Canvas 协作工具
     │       │       ├── memento-flashcards/     # 闪卡工具
     │       │       ├── siyuan/                 # 思源笔记
     │       │       └── telephony/              # 电话集成
     │       │
     │       ├── 📂 研究高级工具（7 个子模块）
     │       │   └── research/
     │       │       ├── bioinformatics/         # 生物信息学
     │       │       ├── domain-intel/           # 领域智能
     │       │       ├── duckduckgo-search/      # DuckDuckGo 搜索
     │       │       ├── gitnexus-explorer/      # Git 仓库浏览
     │       │       ├── parallel-cli/           # 并行 CLI
     │       │       ├── qmd/                    # Quarto Markdown
     │       │       └── scrapling/              # 网页爬虫
     │       │
     │       └── 📂 安全工具
     │           └── security/
     │               ├── 1password/              # 1Password 集成
     │               ├── oss-forensics/          # OSS 取证工具
     │               └── sherlock/               # Sherlock 用户搜索
     │
     ├── 📁 应用与前端
     │   ├── landingpage/                       # 落地页面
     │   └── website/                            # 项目官网
     │       ├── docs/                           # 网站文档
     │       │   ├── developer-guide/            # 开发者指南
     │       │   ├── getting-started/            # 入门指南
     │       │   ├── guides/                     # 使用指南
     │       │   ├── integrations/               # 集成文档
     │       │   ├── reference/                  # API 参考
     │       │   └── user-guide/                 # 用户指南
     │       ├── scripts/                        # 网站脚本
     │       ├── src/                            # 网站源代码
     │       │   ├── css/                        # 样式文件
     │       │   └── pages/                      # 页面组件
     │       └── static/                         # 静态资源
     │           └── img/                        # 图片资源
     │
     ├── 📁 测试与质量保证
     │   └── tests/                              # 完整测试套件
     │       ├── acp/                            # ACP 适配器测试
     │       ├── agent/                          # Agent 核心测试
     │       ├── cli/                            # CLI 测试
     │       ├── cron/                           # 定时任务测试
     │       ├── e2e/                            # 端到端测试
     │       ├── environments/                   # 环境测试
     │       │   └── benchmarks/                 # 基准测试
     │       ├── fakes/                          # Mock 和 Fake 对象
     │       ├── gateway/                        # 网关测试
     │       ├── hermes_cli/                     # CLI 测试
     │       ├── honcho_plugin/                  # Honcho 插件测试
     │       ├── integration/                    # 集成测试
     │       ├── plugins/                        # 插件测试
     │       │   └── memory/                     # 内存插件测试
     │       ├── run_agent/                      # Agent 运行测试
     │       ├── skills/                         # Skill 单元测试
     │       └── tools/                          # 工具测试
     │
     ├── 📁 构建与部署
     │   ├── docker/                             # Docker 配置
     │   ├── nix/                                # Nix 声明式配置
     │   ├── packaging/                          # 包管理配置
     │   │   └── homebrew/                       # Homebrew 公式
     │   ├── scripts/                            # 辅助脚本
     │   │   └── whatsapp-bridge/                # WhatsApp 桥接脚本
     │   └── docs/                               # 项目文档
     │       ├── migration/                      # 迁移文档
     │       ├── plans/                          # 规划文档
     │       └── skins/                          # 主题/皮肤文档
     │
     ├── 📁 项目资源
     │   ├── assets/                             # 静态资源（图片、图标）
     │   ├── plans/                              # 执行计划存储
     │   ├── datagen-config-examples/            # 数据生成示例配置
     │   └── tinker-atropos/                     # 实验性项目/工具
     │
     └── 📄 根目录核心文件
         ├── 🐍 主要 Python 模块
         │   ├── cli.py                          # 主 CLI 入口（约 410KB）
         │   ├── run_agent.py                    # Agent 执行引擎（约 500KB）
         │   ├── batch_runner.py                 # 批量任务运行器
         │   ├── rl_cli.py                       # 强化学习 CLI
         │   ├── mini_swe_runner.py              # 小型 SWE 运行器
         │   ├── mcp_serve.py                    # MCP 服务入口
         │   ├── trajectory_compressor.py        # 轨迹压缩工具
         │   ├── toolsets.py                     # 工具集管理
         │   ├── toolset_distributions.py        # 工具集分发
         │   ├── model_tools.py                  # 模型工具集
         │   ├── hermes_state.py                 # Agent 状态管理
         │   ├── hermes_logging.py               # 日志系统
         │   ├── hermes_time.py                  # 时间工具
         │   ├── hermes_constants.py             # 常量定义
         │   └── utils.py                        # 工具函数
         │
         ├── 📦 配置文件
         │   ├── pyproject.toml                  # Python 项目配置
         │   ├── requirements.txt                # Python 依赖
         │   ├── setup-hermes.sh                 # 安装脚本
         │   ├── flake.nix                       # Nix 开发环境
         │   ├── flake.lock                      # Nix 依赖锁定
         │   ├── package.json                    # Node.js 项目配置
         │   ├── package-lock.json               # Node.js 依赖锁定
         │   ├── uv.lock                         # UV 包管理器锁定文件
         │   ├── MANIFEST.in                     # 包清单
         │   └── constraints-termux.txt          # Termux 约束
         │
         ├── 🐳 部署配置
         │   └── Dockerfile                      # 容器镜像
         │
         ├── 📝 文档和示例
         │   ├── README.md                       # 项目自述文件
         │   ├── CONTRIBUTING.md                 # 贡献指南
         │   ├── AGENTS.md                       # Agent 文档
         │   ├── LICENSE                         # 许可证
         │   ├── cli-config.yaml.example         # CLI 配置示例
         │   └── RELEASE_v*.md                   # 发版说明
         │       ├── RELEASE_v0.2.0.md
         │       ├── RELEASE_v0.3.0.md
         │       ├── RELEASE_v0.4.0.md
         │       ├── RELEASE_v0.5.0.md
         │       ├── RELEASE_v0.6.0.md
         │       ├── RELEASE_v0.7.0.md
         │       └── RELEASE_v0.8.0.md
         │
         ├── 📂 开发工具
         │   ├── .env                            # 环境变量（本地配置）
         │   ├── .env.example                    # 环境变量模板
         │   ├── .envrc                          # direnv 配置
         │   ├── .gitignore                      # Git 忽略规则
         │   ├── .gitmodules                     # Git 子模块配置
         │   ├── .dockerignore                   # Docker 忽略规则
         │   └── .github/                        # GitHub Actions 配置
         │
         └── 📁 项目管理
             ├── .git/                           # Git 仓库
             ├── .plans/                         # Claude Code 计划
             ├── .venv/                          # Python 虚拟环境
             ├── __pycache__/                    # Python 缓存
             └── .idea/                          # IntelliJ IDEA 配置

说明：仓库体积与版本会变，上述树形结构用于建立整体心智模型；以你本地 git clone 后的实际目录为准。

Hermes Agent Documentation

slug: / sidebar_position: 0 title: “Hermes Agent Documentation” description: “The self-improving AI agent built by Nous Research. A built-in learning loop that creates skills from experience, improves them during use, and remembers across sessions.” hide_table_of_contents: true

Hermes Agent

The self-improving AI agent built by Nous Research. The only agent with a built-in learning loop — it creates skills from experience, improves them during use, nudges itself to persist knowledge, and builds a deepening model of who you are across sessions.

What is Hermes Agent?

It’s not a coding copilot tethered to an IDE or a chatbot wrapper around a single API. It’s an autonomous agent that gets more capable the longer it runs. It lives wherever you put it — a $5 VPS, a GPU cluster, or serverless infrastructure (Daytona, Modal) that costs nearly nothing when idle. Talk to it from Telegram while it works on a cloud VM you never SSH into yourself. It’s not tied to your laptop.

Quick Links

Key Features

• A closed learning loop — Agent-curated memory with periodic nudges, autonomous skill creation, skill self-improvement during use, FTS5 cross-session recall with LLM summarization, and Honcho dialectic user modeling
• Runs anywhere, not just your laptop — 6 terminal backends: local, Docker, SSH, Daytona, Singularity, Modal. Daytona and Modal offer serverless persistence — your environment hibernates when idle, costing nearly nothing
• Lives where you do — CLI, Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost, Email, SMS, DingTalk, Feishu, WeCom, BlueBubbles, Home Assistant — 15+ platforms from one gateway
• Built by model trainers — Created by Nous Research, the lab behind Hermes, Nomos, and Psyche. Works with Nous Portal, OpenRouter, OpenAI, or any endpoint
• Scheduled automations — Built-in cron with delivery to any platform
• Delegates & parallelizes — Spawn isolated subagents for parallel workstreams. Programmatic Tool Calling via execute_code collapses multi-step pipelines into single inference calls
• Open standard skills — Compatible with agentskills.io. Skills are portable, shareable, and community-contributed via the Skills Hub
• Full web control — Search, extract, browse, vision, image generation, TTS
• MCP support — Connect to any MCP server for extended tool capabilities
• Research-ready — Batch processing, trajectory export, RL training with Atropos. Built by Nous Research — the lab behind Hermes, Nomos, and Psyche models

Installation

sidebar_position: 2 title: “Installation” description: “Install Hermes Agent on Linux, macOS, WSL2, or Android via Termux”

Installation

Get Hermes Agent up and running in under two minutes with the one-line installer, or follow the manual steps for full control.

Quick Install

Linux / macOS / WSL2

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Android / Termux

Hermes now ships a Termux-aware installer path too:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

The installer detects Termux automatically and switches to a tested Android flow:

• uses Termux pkg for system dependencies (git, python, nodejs, ripgrep, ffmpeg, build tools)
• creates the virtualenv with python -m venv
• exports ANDROID_API_LEVEL automatically for Android wheel builds
• installs a curated .[termux] extra with pip
• skips the untested browser / WhatsApp bootstrap by default

If you want the fully explicit path, follow the dedicated Termux guide.

::warning Windows Native Windows is not supported. Please install WSL2 and run Hermes Agent from there. The install command above works inside WSL2.

::

What the Installer Does

The installer handles everything automatically — all dependencies (Python, Node.js, ripgrep, ffmpeg), the repo clone, virtual environment, global hermes command setup, and LLM provider configuration. By the end, you’re ready to chat.

After Installation

Reload your shell and start chatting:

source ~/.bashrc   # or: source ~/.zshrc
hermes             # Start chatting!

To reconfigure individual settings later, use the dedicated commands:

hermes model          # Choose your LLM provider and model
hermes tools          # Configure which tools are enabled
hermes gateway setup  # Set up messaging platforms
hermes config set     # Set individual config values
hermes setup          # Or run the full setup wizard to configure everything at once

Prerequisites

The only prerequisite is Git. The installer automatically handles everything else:

• uv (fast Python package manager)
• Python 3.11 (via uv, no sudo needed)
• Node.js v22 (for browser automation and WhatsApp bridge)
• ripgrep (fast file search)
• ffmpeg (audio format conversion for TTS)

:::info You do not need to install Python, Node.js, ripgrep, or ffmpeg manually. The installer detects what’s missing and installs it for you. Just make sure git is available (git --version).

::

::tip Nix users If you use Nix (on NixOS, macOS, or Linux), there’s a dedicated setup path with a Nix flake, declarative NixOS module, and optional container mode. See the Nix & NixOS Setup guide.

::

Manual Installation

If you prefer full control over the installation process, follow these steps.

Step 1: Clone the Repository

Clone with --recurse-submodules to pull the required submodules:

git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

If you already cloned without --recurse-submodules:

git submodule update --init --recursive

Step 2: Install uv & Create Virtual Environment

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create venv with Python 3.11 (uv downloads it if not present — no sudo needed)
uv venv venv --python 3.11

:::tip You do not need to activate the venv to use hermes. The entry point has a hardcoded shebang pointing to the venv Python, so it works globally once symlinked.

::

Step 3: Install Python Dependencies

# Tell uv which venv to install into
export VIRTUAL_ENV="$(pwd)/venv"

# Install with all extras
uv pip install -e ".[all]"

If you only want the core agent (no Telegram/Discord/cron support):

uv pip install -e "."

Step 4: Install Optional Submodules (if needed)

# RL training backend (optional)
uv pip install -e "./tinker-atropos"

Both are optional — if you skip them, the corresponding toolsets simply won’t be available.

Step 5: Install Node.js Dependencies (Optional)

Only needed for browser automation (Browserbase-powered) and WhatsApp bridge:

npm install

Step 6: Create the Configuration Directory

# Create the directory structure
mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills,pairing,hooks,image_cache,audio_cache,whatsapp/session}

# Copy the example config file
cp cli-config.yaml.example ~/.hermes/config.yaml

# Create an empty .env file for API keys
touch ~/.hermes/.env

Step 7: Add Your API Keys

Open ~/.hermes/.env and add at minimum an LLM provider key:

# Required — at least one LLM provider:
OPENROUTER_API_KEY=sk-or-v1-your-key-here

# Optional — enable additional tools:
FIRECRAWL_API_KEY=fc-your-key          # Web search & scraping (or self-host, see docs)
FAL_KEY=your-fal-key                   # Image generation (FLUX)

Or set them via the CLI:

hermes config set OPENROUTER_API_KEY sk-or-v1-your-key-here

Step 8: Add hermes to Your PATH

mkdir -p ~/.local/bin
ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes

If ~/.local/bin isn’t on your PATH, add it to your shell config:

# Bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

# Zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

# Fish
fish_add_path $HOME/.local/bin

Step 9: Configure Your Provider

hermes model       # Select your LLM provider and model

Step 10: Verify the Installation

hermes version    # Check that the command is available
hermes doctor     # Run diagnostics to verify everything is working
hermes status     # Check your configuration
hermes chat -q "Hello! What tools do you have available?"

Quick-Reference: Manual Install (Condensed)

For those who just want the commands:

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone & enter
git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# Create venv with Python 3.11
uv venv venv --python 3.11
export VIRTUAL_ENV="$(pwd)/venv"

# Install everything
uv pip install -e ".[all]"
uv pip install -e "./tinker-atropos"
npm install  # optional, for browser tools and WhatsApp

# Configure
mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills,pairing,hooks,image_cache,audio_cache,whatsapp/session}
cp cli-config.yaml.example ~/.hermes/config.yaml
touch ~/.hermes/.env
echo 'OPENROUTER_API_KEY=sk-or-v1-your-key' >> ~/.hermes/.env

# Make hermes available globally
mkdir -p ~/.local/bin
ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes

# Verify
hermes doctor
hermes

Troubleshooting

For more diagnostics, run hermes doctor — it will tell you exactly what’s missing and how to fix it.

Quickstart

sidebar_position: 1 title: “Quickstart” description: “Your first conversation with Hermes Agent — from install to chatting in 2 minutes”

Quickstart

This guide walks you through installing Hermes Agent, setting up a provider, and having your first conversation. By the end, you’ll know the key features and how to explore further.

1. Install Hermes Agent

Run the one-line installer:

# Linux / macOS / WSL2 / Android (Termux)
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

:::tip Android / Termux If you’re installing on a phone, see the dedicated Termux guide for the tested manual path, supported extras, and current Android-specific limitations.

::

::tip Windows Users Install WSL2 first, then run the command above inside your WSL2 terminal.

::

After it finishes, reload your shell:

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

2. Set Up a Provider

The installer configures your LLM provider automatically. To change it later, use one of these commands:

hermes model       # Choose your LLM provider and model
hermes tools       # Configure which tools are enabled
hermes setup       # Or configure everything at once

hermes model walks you through selecting an inference provider:

:::caution Minimum context: 64K tokens Hermes Agent requires a model with at least 64,000 tokens of context. Models with smaller windows cannot maintain enough working memory for multi-step tool-calling workflows and will be rejected at startup. Most hosted models (Claude, GPT, Gemini, Qwen, DeepSeek) meet this easily. If you’re running a local model, set its context size to at least 64K (e.g. --ctx-size 65536 for llama.cpp or -c 65536 for Ollama).

::

::tip You can switch providers at any time with hermes model — no code changes, no lock-in. When configuring a custom endpoint, Hermes will prompt for the context window size and auto-detect it when possible. See Context Length Detection for details.

::

3. Start Chatting

hermes

That’s it! You’ll see a welcome banner with your model, available tools, and skills. Type a message and press Enter.

❯ What can you help me with?

The agent has access to tools for web search, file operations, terminal commands, and more — all out of the box.

4. Try Key Features

Ask it to use the terminal

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

The agent will run terminal commands on your behalf and show you the results.

Use slash commands

Type / to see an autocomplete dropdown of all commands:

Multi-line input

Press Alt+Enter or Ctrl+J to add a new line. Great for pasting code or writing detailed prompts.

Interrupt the agent

If the agent is taking too long, just type a new message and press Enter — it interrupts the current task and switches to your new instructions. Ctrl+C also works.

Resume a session

When you exit, hermes prints a resume command:

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

5. Explore Further

Here are some things to try next:

Set up a sandboxed terminal

For safety, run the agent in a Docker container or on a remote server:

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

Connect messaging platforms

Chat with Hermes from your phone or other surfaces via Telegram, Discord, Slack, WhatsApp, Signal, Email, or Home Assistant:

hermes gateway setup    # Interactive platform configuration

Add voice mode

Want microphone input in the CLI or spoken replies in messaging?

pip install "hermes-agent[voice]"

# Optional but recommended for free local speech-to-text
pip install faster-whisper

Then start Hermes and enable it inside the CLI:

/voice on

Press Ctrl+B to record, or use /voice tts to have Hermes speak its replies. See Voice Mode for the full setup across CLI, Telegram, Discord, and Discord voice channels.

Schedule automated tasks

❯ Every morning at 9am, check Hacker News for AI news and send me a summary on Telegram.

The agent will set up a cron job that runs automatically via the gateway.

Browse and install skills

hermes skills search kubernetes
hermes skills search react --source skills-sh
hermes skills search https://mintlify.com/docs --source well-known
hermes skills install openai/skills/k8s
hermes skills install official/security/1password
hermes skills install skills-sh/vercel-labs/json-render/json-render-react --force

Tips:

• Use --source skills-sh to search the public skills.sh directory.
• Use --source well-known with a docs/site URL to discover skills from /.well-known/skills/index.json.
• Use --force only after reviewing a third-party skill. It can override non-dangerous policy blocks, but not a dangerous scan verdict.

Or use the /skills slash command inside chat.

Use Hermes inside an editor via ACP

Hermes can also run as an ACP server for ACP-compatible editors like VS Code, Zed, and JetBrains:

pip install -e '.[acp]'
hermes acp

See ACP Editor Integration for setup details.

Try MCP servers

Connect to external tools via the Model Context Protocol:

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

Quick Reference

Next Steps

• CLI Guide — Master the terminal interface
• Configuration — Customize your setup
• Messaging Gateway — Connect Telegram, Discord, Slack, WhatsApp, Signal, Email, or Home Assistant
• Tools & Toolsets — Explore available capabilities

Learning Path

sidebar_position: 3 title: ‘Learning Path’ description: ‘Choose your learning path through the Hermes Agent documentation based on your experience level and goals.’

Learning Path

Hermes Agent can do a lot — CLI assistant, Telegram/Discord bot, task automation, RL training, and more. This page helps you figure out where to start and what to read based on your experience level and what you’re trying to accomplish.

::tip Start Here If you haven’t installed Hermes Agent yet, begin with the Installation guide and then run through the Quickstart. Everything below assumes you have a working installation.

::

How to Use This Page

• Know your level? Jump to the experience-level table and follow the reading order for your tier.
• Have a specific goal? Skip to By Use Case and find the scenario that matches.
• Just browsing? Check the Key Features table for a quick overview of everything Hermes Agent can do.

By Experience Level

By Use Case

Pick the scenario that matches what you want to do. Each one links you to the relevant docs in the order you should read them.

“I want a CLI coding assistant”

Use Hermes Agent as an interactive terminal assistant for writing, reviewing, and running code.

1. Installation
2. Quickstart
3. CLI Usage
4. Code Execution
5. Context Files
6. Tips & Tricks

:::tip Pass files directly into your conversation with context files. Hermes Agent can read, edit, and run code in your projects.

::

“I want a Telegram/Discord bot”

Deploy Hermes Agent as a bot on your favorite messaging platform.

1. Installation
2. Configuration
3. Messaging Overview
4. Telegram Setup
5. Discord Setup
6. Voice Mode
7. Use Voice Mode with Hermes
8. Security

For full project examples, see:

• Daily Briefing Bot
• Team Telegram Assistant

“I want to automate tasks”

Schedule recurring tasks, run batch jobs, or chain agent actions together.

1. Quickstart
2. Cron Scheduling
3. Batch Processing
4. Delegation
5. Hooks

:::tip Cron jobs let Hermes Agent run tasks on a schedule — daily summaries, periodic checks, automated reports — without you being present.

::

“I want to build custom tools/skills”

Extend Hermes Agent with your own tools and reusable skill packages.

1. Tools Overview
2. Skills Overview
3. MCP (Model Context Protocol)
4. Architecture
5. Adding Tools
6. Creating Skills

:::tip Tools are individual functions the agent can call. Skills are bundles of tools, prompts, and configuration packaged together. Start with tools, graduate to skills.

::

“I want to train models”

Use reinforcement learning to fine-tune model behavior with Hermes Agent’s built-in RL training pipeline.

1. Quickstart
2. Configuration
3. RL Training
4. Provider Routing
5. Architecture

:::tip RL training works best when you already understand the basics of how Hermes Agent handles conversations and tool calls. Run through the Beginner path first if you’re new.

::

“I want to use it as a Python library”

Integrate Hermes Agent into your own Python applications programmatically.

1. Installation
2. Quickstart
3. Python Library Guide
4. Architecture
5. Tools
6. Sessions

Key Features at a Glance

Not sure what’s available? Here’s a quick directory of major features:

What to Read Next

Based on where you are right now:

• Just finished installing? → Head to the Quickstart to run your first conversation.
• Completed the Quickstart? → Read CLI Usage and Configuration to customize your setup.
• Comfortable with the basics? → Explore Tools, Skills, and Memory to unlock the full power of the agent.
• Setting up for a team? → Read Security and Sessions to understand access control and conversation management.
• Ready to build? → Jump into the Developer Guide to understand the internals and start contributing.
• Want practical examples? → Check out the Guides section for real-world projects and tips.

:::tip You don’t need to read everything. Pick the path that matches your goal, follow the links in order, and you’ll be productive quickly. You can always come back to this page to find your next step.

::

Hermes Agent 教程（1）：本地启动与项目结构

项目地址：https://github.com/NousResearch/hermes-agent

启动项目

Step 1：拉取项目到本地

git clone https://github.com/NousResearch/hermes-agent.git

Step 2：进入项目目录

cd hermes-agent

若你放在固定路径，也可使用绝对路径，例如：

cd /Users/YolieDeng/Code/hermes-agent

Step 3：创建并进入虚拟环境

uv venv
source .venv/bin/activate

Step 4：安装项目依赖

uv sync

Step 5：配置 .env

cp .env.example .env

编辑 .env，填入你的 API 密钥。例如使用 MiniMax：

# MINIMAX_API_KEY=your-key-here

Step 6：模型选择与启动

hermes doctor
# 选择适合的模型
hermes model
hermes

成功启动后，终端会出现交互界面，即可开始对话。

项目结构讲解

hermes-agent/
     │
     ├── 📁 核心框架模块
     │   ├── agent/                              # Agent 核心逻辑和执行引擎
     │   ├── gateway/                            # API 网关、请求路由、钩子系统
     │   │   ├── builtin_hooks/                  # 内置钩子集合
     │   │   └── platforms/                      # 多平台适配
     │   ├── hermes_cli/                         # CLI 命令行接口
     │   └── tools/                              # 工具系统和工具调用解析器
     │       ├── browser_providers/              # 浏览器供应商
     │       ├── environments/                   # 工具环境配置
     │       └── neutts_samples/                 # 神经 TTS 示例
     │
     ├── 📁 配置与适配
     │   ├── acp_adapter/                        # ACP 协议适配器
     │   ├── acp_registry/                       # 服务注册表
     │   ├── plugins/                            # 插件系统
     │   │   └── memory/                         # 内存/记忆插件
     │   │       ├── byterover/                  # Byterover 内存实现
     │   │       ├── hindsight/                  # Hindsight 内存实现
     │   │       ├── holographic/                # Holographic 内存实现
     │   │       ├── honcho/                     # Honcho 内存实现
     │   │       ├── mem0/                       # Mem0 内存实现
     │   │       ├── openviking/                 # OpenViking 内存实现
     │   │       ├── retaindb/                   # RetainDB 内存实现
     │   │       └── supermemory/                # SuperMemory 内存实现
     │   └── environments/                       # 环境配置和管理
     │       ├── benchmarks/                     # 基准测试环境
     │       │   ├── tblite/                     # TBLite 基准
     │       │   ├── terminalbench_2/            # 终端基准 2
     │       │   └── yc_bench/                   # YC 基准
     │       ├── hermes_swe_env/                 # Hermes SWE 环境
     │       ├── terminal_test_env/              # 终端测试环境
     │       └── tool_call_parsers/              # 工具调用解析器
     │
     ├── 📁 功能扩展 - Skills（完整技能列表）
     │   └── skills/                             # 完整技能模块集合
     │       │
     │       ├── 📂 苹果生态技能
     │       │   └── apple/
     │       │       ├── apple-notes/            # Apple Notes 集成
     │       │       ├── apple-reminders/        # Apple Reminders 集成
     │       │       ├── findmy/                 # Find My 定位服务
     │       │       └── imessage/               # iMessage 消息
     │       │
     │       ├── 📂 AI Agent 技能
     │       │   └── autonomous-ai-agents/
     │       │       ├── claude-code/            # Claude Code 集成
     │       │       ├── codex/                  # Codex AI 集成
     │       │       ├── hermes-agent/           # Hermes Agent 自身
     │       │       └── opencode/               # OpenCode 集成
     │       │
     │       ├── 📂 创意工具
     │       │   └── creative/
     │       │       ├── ascii-art/              # ASCII 艺术生成
     │       │       ├── ascii-video/            # ASCII 视频生成
     │       │       ├── excalidraw/             # Excalidraw 绘图
     │       │       ├── manim-video/            # Manim 视频制作
     │       │       ├── p5js/                   # P5.js 创意编程
     │       │       └── songwriting-and-ai-music/  # 作曲和 AI 音乐
     │       │
     │       ├── 📂 数据科学
     │       │   └── data-science/
     │       │       └── jupyter-live-kernel/    # Jupyter 实时内核
     │       │
     │       ├── 📂 运维和开发工具
     │       │   ├── devops/
     │       │   │   └── webhook-subscriptions/  # Webhook 订阅
     │       │   ├── diagramming/                # 图表工具
     │       │   └── domain/                     # 域名工具
     │       │
     │       ├── 📂 Email 工具
     │       │   └── email/
     │       │       └── himalaya/               # Himalaya 邮件客户端
     │       │
     │       ├── 📂 Feed 和 RSS
     │       │   └── feeds/                      # Feed 聚合工具
     │       │
     │       ├── 📂 游戏工具
     │       │   └── gaming/
     │       │       ├── minecraft-modpack-server/  # Minecraft 模组服务器
     │       │       └── pokemon-player/         # 宝可梦玩家工具
     │       │
     │       ├── 📂 GIF 工具
     │       │   └── gifs/                       # GIF 生成和处理
     │       │
     │       ├── 📂 GitHub 集成
     │       │   └── github/
     │       │       ├── codebase-inspection/    # 代码库检查
     │       │       ├── github-auth/            # GitHub 认证
     │       │       ├── github-code-review/     # 代码审查
     │       │       ├── github-issues/          # Issue 管理
     │       │       ├── github-pr-workflow/     # PR 工作流
     │       │       └── github-repo-management/ # 仓库管理
     │       │
     │       ├── 📂 索引和缓存
     │       │   └── index-cache/                # 索引缓存
     │       │
     │       ├── 📂 推理工具
     │       │   └── inference-sh/               # 推理 Shell 脚本
     │       │
     │       ├── 📂 休闲娱乐
     │       │   └── leisure/
     │       │       └── find-nearby/            # 附近地点查找
     │       │
     │       ├── 📂 MCP（模型上下文协议）
     │       │   └── mcp/
     │       │       ├── mcporter/               # MCP 转换器
     │       │       └── native-mcp/             # 原生 MCP 支持
     │       │
     │       ├── 📂 媒体工具
     │       │   └── media/
     │       │       ├── gif-search/             # GIF 搜索
     │       │       ├── heartmula/              # 音乐播放器
     │       │       ├── songsee/                # 歌曲识别
     │       │       └── youtube-content/        # YouTube 内容工具
     │       │
     │       ├── 📂 MLOps 工具
     │       │   └── mlops/
     │       │       ├── cloud/                  # 云平台工具
     │       │       ├── evaluation/             # 模型评估
     │       │       ├── huggingface-hub/        # HuggingFace 集成
     │       │       ├── inference/              # 模型推理
     │       │       ├── models/                 # 模型管理
     │       │       ├── research/               # 研究工具
     │       │       ├── training/               # 模型训练
     │       │       └── vector-databases/       # 向量数据库
     │       │
     │       ├── 📂 笔记应用
     │       │   └── note-taking/
     │       │       └── obsidian/               # Obsidian 笔记集成
     │       │
     │       ├── 📂 生产力工具
     │       │   └── productivity/
     │       │       ├── google-workspace/       # Google Workspace 集成
     │       │       ├── linear/                 # Linear 项目管理
     │       │       ├── nano-pdf/               # PDF 工具
     │       │       ├── notion/                 # Notion 集成
     │       │       ├── ocr-and-documents/      # OCR 和文档处理
     │       │       └── powerpoint/             # PowerPoint 制作
     │       │
     │       ├── 📂 红队工具
     │       │   └── red-teaming/
     │       │       └── godmode/                # GodMode 工具
     │       │
     │       ├── 📂 研究工具
     │       │   └── research/
     │       │       ├── arxiv/                  # ArXiv 论文
     │       │       ├── blogwatcher/            # 博客监控
     │       │       ├── llm-wiki/               # LLM Wiki
     │       │       ├── polymarket/             # Polymarket 数据
     │       │       └── research-paper-writing/ # 论文写作
     │       │
     │       ├── 📂 智能家居
     │       │   └── smart-home/
     │       │       └── openhue/                # OpenHue 智能灯控
     │       │
     │       ├── 📂 社交媒体
     │       │   └── social-media/
     │       │       └── xitter/                 # X/Twitter 集成
     │       │
     │       └── 📂 软件开发
     │           └── software-development/
     │               ├── plan/                   # 计划工具
     │               ├── requesting-code-review/ # 代码审查请求
     │               ├── subagent-driven-development/  # 子 Agent 驱动开发
     │               ├── systematic-debugging/   # 系统化调试
     │               ├── test-driven-development/  # TDD 工具
     │               └── writing-plans/          # 计划编写
     │
     ├── 📁 可选技能扩展
     │   └── optional-skills/                    # 可选安装的高级技能包
     │       │
     │       ├── 📂 自主 AI Agent
     │       │   └── autonomous-ai-agents/
     │       │       ├── blackbox/               # BlackBox AI
     │       │       └── honcho/                 # Honcho 框架
     │       │
     │       ├── 📂 区块链技能
     │       │   └── blockchain/
     │       │       ├── base/                   # Base 区块链
     │       │       └── solana/                 # Solana 链
     │       │
     │       ├── 📂 通信工具
     │       │   └── communication/
     │       │       └── one-three-one-rule/     # 一对一通信规则
     │       │
     │       ├── 📂 创意能力
     │       │   └── creative/
     │       │       ├── blender-mcp/            # Blender 3D 建模
     │       │       └── meme-generation/        # 梗图生成
     │       │
     │       ├── 📂 DevOps 高级工具
     │       │   └── devops/
     │       │       ├── cli/                    # DevOps CLI
     │       │       └── docker-management/      # Docker 管理
     │       │
     │       ├── 📂 邮件服务
     │       │   └── email/
     │       │       └── agentmail/              # Agent 邮件服务
     │       │
     │       ├── 📂 健康工具
     │       │   └── health/
     │       │       └── neuroskill-bci/         # 脑机接口工具
     │       │
     │       ├── 📂 MCP 工具
     │       │   └── mcp/
     │       │       └── fastmcp/                # FastMCP 框架
     │       │
     │       ├── 📂 数据迁移
     │       │   └── migration/
     │       │       └── openclaw-migration/     # OpenClaw 迁移工具
     │       │
     │       ├── 📂 MLOps 高级功能（17 个子模块）
     │       │   └── mlops/
     │       │       ├── accelerate/             # Hugging Face Accelerate
     │       │       ├── chroma/                 # Chroma 向量库
     │       │       ├── faiss/                  # Facebook FAISS
     │       │       ├── flash-attention/        # Flash Attention 优化
     │       │       ├── hermes-atropos-environments/  # Atropos 环境
     │       │       ├── huggingface-tokenizers/ # HF Tokenizers
     │       │       ├── instructor/             # Instructor 框架
     │       │       ├── lambda-labs/            # Lambda Labs GPU
     │       │       ├── llava/                  # LLaVA 多模态
     │       │       ├── nemo-curator/           # NeMo Curator
     │       │       ├── pinecone/               # Pinecone 向量 DB
     │       │       ├── pytorch-lightning/      # PyTorch Lightning
     │       │       ├── qdrant/                 # Qdrant 向量 DB
     │       │       ├── saelens/                # SAELENS 框架
     │       │       ├── simpo/                  # SimPO 训练
     │       │       ├── slime/                  # SLIME 框架
     │       │       ├── tensorrt-llm/           # TensorRT LLM
     │       │       └── torchtitan/             # TorchTitan 分布式
     │       │
     │       ├── 📂 生产力扩展
     │       │   └── productivity/
     │       │       ├── canvas/                 # Canvas 协作工具
     │       │       ├── memento-flashcards/     # 闪卡工具
     │       │       ├── siyuan/                 # 思源笔记
     │       │       └── telephony/              # 电话集成
     │       │
     │       ├── 📂 研究高级工具（7 个子模块）
     │       │   └── research/
     │       │       ├── bioinformatics/         # 生物信息学
     │       │       ├── domain-intel/           # 领域智能
     │       │       ├── duckduckgo-search/      # DuckDuckGo 搜索
     │       │       ├── gitnexus-explorer/      # Git 仓库浏览
     │       │       ├── parallel-cli/           # 并行 CLI
     │       │       ├── qmd/                    # Quarto Markdown
     │       │       └── scrapling/              # 网页爬虫
     │       │
     │       └── 📂 安全工具
     │           └── security/
     │               ├── 1password/              # 1Password 集成
     │               ├── oss-forensics/          # OSS 取证工具
     │               └── sherlock/               # Sherlock 用户搜索
     │
     ├── 📁 应用与前端
     │   ├── landingpage/                       # 落地页面
     │   └── website/                            # 项目官网
     │       ├── docs/                           # 网站文档
     │       │   ├── developer-guide/            # 开发者指南
     │       │   ├── getting-started/            # 入门指南
     │       │   ├── guides/                     # 使用指南
     │       │   ├── integrations/               # 集成文档
     │       │   ├── reference/                  # API 参考
     │       │   └── user-guide/                 # 用户指南
     │       ├── scripts/                        # 网站脚本
     │       ├── src/                            # 网站源代码
     │       │   ├── css/                        # 样式文件
     │       │   └── pages/                      # 页面组件
     │       └── static/                         # 静态资源
     │           └── img/                        # 图片资源
     │
     ├── 📁 测试与质量保证
     │   └── tests/                              # 完整测试套件
     │       ├── acp/                            # ACP 适配器测试
     │       ├── agent/                          # Agent 核心测试
     │       ├── cli/                            # CLI 测试
     │       ├── cron/                           # 定时任务测试
     │       ├── e2e/                            # 端到端测试
     │       ├── environments/                   # 环境测试
     │       │   └── benchmarks/                 # 基准测试
     │       ├── fakes/                          # Mock 和 Fake 对象
     │       ├── gateway/                        # 网关测试
     │       ├── hermes_cli/                     # CLI 测试
     │       ├── honcho_plugin/                  # Honcho 插件测试
     │       ├── integration/                    # 集成测试
     │       ├── plugins/                        # 插件测试
     │       │   └── memory/                     # 内存插件测试
     │       ├── run_agent/                      # Agent 运行测试
     │       ├── skills/                         # Skill 单元测试
     │       └── tools/                          # 工具测试
     │
     ├── 📁 构建与部署
     │   ├── docker/                             # Docker 配置
     │   ├── nix/                                # Nix 声明式配置
     │   ├── packaging/                          # 包管理配置
     │   │   └── homebrew/                       # Homebrew 公式
     │   ├── scripts/                            # 辅助脚本
     │   │   └── whatsapp-bridge/                # WhatsApp 桥接脚本
     │   └── docs/                               # 项目文档
     │       ├── migration/                      # 迁移文档
     │       ├── plans/                          # 规划文档
     │       └── skins/                          # 主题/皮肤文档
     │
     ├── 📁 项目资源
     │   ├── assets/                             # 静态资源（图片、图标）
     │   ├── plans/                              # 执行计划存储
     │   ├── datagen-config-examples/            # 数据生成示例配置
     │   └── tinker-atropos/                     # 实验性项目/工具
     │
     └── 📄 根目录核心文件
         ├── 🐍 主要 Python 模块
         │   ├── cli.py                          # 主 CLI 入口（约 410KB）
         │   ├── run_agent.py                    # Agent 执行引擎（约 500KB）
         │   ├── batch_runner.py                 # 批量任务运行器
         │   ├── rl_cli.py                       # 强化学习 CLI
         │   ├── mini_swe_runner.py              # 小型 SWE 运行器
         │   ├── mcp_serve.py                    # MCP 服务入口
         │   ├── trajectory_compressor.py        # 轨迹压缩工具
         │   ├── toolsets.py                     # 工具集管理
         │   ├── toolset_distributions.py        # 工具集分发
         │   ├── model_tools.py                  # 模型工具集
         │   ├── hermes_state.py                 # Agent 状态管理
         │   ├── hermes_logging.py               # 日志系统
         │   ├── hermes_time.py                  # 时间工具
         │   ├── hermes_constants.py             # 常量定义
         │   └── utils.py                        # 工具函数
         │
         ├── 📦 配置文件
         │   ├── pyproject.toml                  # Python 项目配置
         │   ├── requirements.txt                # Python 依赖
         │   ├── setup-hermes.sh                 # 安装脚本
         │   ├── flake.nix                       # Nix 开发环境
         │   ├── flake.lock                      # Nix 依赖锁定
         │   ├── package.json                    # Node.js 项目配置
         │   ├── package-lock.json               # Node.js 依赖锁定
         │   ├── uv.lock                         # UV 包管理器锁定文件
         │   ├── MANIFEST.in                     # 包清单
         │   └── constraints-termux.txt          # Termux 约束
         │
         ├── 🐳 部署配置
         │   └── Dockerfile                      # 容器镜像
         │
         ├── 📝 文档和示例
         │   ├── README.md                       # 项目自述文件
         │   ├── CONTRIBUTING.md                 # 贡献指南
         │   ├── AGENTS.md                       # Agent 文档
         │   ├── LICENSE                         # 许可证
         │   ├── cli-config.yaml.example         # CLI 配置示例
         │   └── RELEASE_v*.md                   # 发版说明
         │       ├── RELEASE_v0.2.0.md
         │       ├── RELEASE_v0.3.0.md
         │       ├── RELEASE_v0.4.0.md
         │       ├── RELEASE_v0.5.0.md
         │       ├── RELEASE_v0.6.0.md
         │       ├── RELEASE_v0.7.0.md
         │       └── RELEASE_v0.8.0.md
         │
         ├── 📂 开发工具
         │   ├── .env                            # 环境变量（本地配置）
         │   ├── .env.example                    # 环境变量模板
         │   ├── .envrc                          # direnv 配置
         │   ├── .gitignore                      # Git 忽略规则
         │   ├── .gitmodules                     # Git 子模块配置
         │   ├── .dockerignore                   # Docker 忽略规则
         │   └── .github/                        # GitHub Actions 配置
         │
         └── 📁 项目管理
             ├── .git/                           # Git 仓库
             ├── .plans/                         # Claude Code 计划
             ├── .venv/                          # Python 虚拟环境
             ├── __pycache__/                    # Python 缓存
             └── .idea/                          # IntelliJ IDEA 配置

说明：仓库体积与版本会变，上述树形结构用于建立整体心智模型；以你本地 git clone 后的实际目录为准。

Nix & NixOS Setup

sidebar_position: 3 title: “Nix & NixOS Setup” description: “Install and deploy Hermes Agent with Nix — from quick nix run to fully declarative NixOS module with container mode”

Nix & NixOS Setup

Hermes Agent ships a Nix flake with three levels of integration:

:::info What’s different from the standard install The curl | bash installer manages Python, Node, and dependencies itself. The Nix flake replaces all of that — every Python dependency is a Nix derivation built by uv2nix, and runtime tools (Node.js, git, ripgrep, ffmpeg) are wrapped into the binary’s PATH. There is no runtime pip, no venv activation, no npm install.

For non-NixOS users, this only changes the install step. Everything after (hermes setup, hermes gateway install, config editing) works identically to the standard install.

For NixOS module users, the entire lifecycle is different: configuration lives in configuration.nix, secrets go through sops-nix/agenix, the service is a systemd unit, and CLI config commands are blocked. You manage hermes the same way you manage any other NixOS service.

::

Prerequisites

• Nix with flakes enabled — Determinate Nix recommended (enables flakes by default)
• API keys for the services you want to use (at minimum: an OpenRouter or Anthropic key)

Quick Start (Any Nix User)

No clone needed. Nix fetches, builds, and runs everything:

# Run directly (builds on first use, cached after)
nix run github:NousResearch/hermes-agent -- setup
nix run github:NousResearch/hermes-agent -- chat

# Or install persistently
nix profile install github:NousResearch/hermes-agent
hermes setup
hermes chat

After nix profile install, hermes, hermes-agent, and hermes-acp are on your PATH. From here, the workflow is identical to the standard installation — hermes setup walks you through provider selection, hermes gateway install sets up a launchd (macOS) or systemd user service, and config lives in ~/.hermes/.

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
nix build
./result/bin/hermes setup

NixOS Module

The flake exports nixosModules.default — a full NixOS service module that declaratively manages user creation, directories, config generation, secrets, documents, and service lifecycle.

::note This module requires NixOS. For non-NixOS systems (macOS, other Linux distros), use nix profile install and the standard CLI workflow above.

::

Add the Flake Input

# /etc/nixos/flake.nix (or your system flake)
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    hermes-agent.url = "github:NousResearch/hermes-agent";
  };

  outputs = { nixpkgs, hermes-agent, ... }: {
    nixosConfigurations.your-host = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        hermes-agent.nixosModules.default
        ./configuration.nix
      ];
    };
  };
}

Minimal Configuration

# configuration.nix
{ config, ... }: {
  services.hermes-agent = {
    enable = true;
    settings.model.default = "anthropic/claude-sonnet-4";
    environmentFiles = [ config.sops.secrets."hermes-env".path ];
    addToSystemPackages = true;
  };
}

That’s it. nixos-rebuild switch creates the hermes user, generates config.yaml, wires up secrets, and starts the gateway — a long-running service that connects the agent to messaging platforms (Telegram, Discord, etc.) and listens for incoming messages.

::warning Secrets are required The environmentFiles line above assumes you have sops-nix or agenix configured. The file should contain at least one LLM provider key (e.g., OPENROUTER_API_KEY=sk-or-...). See Secrets Management for full setup. If you don’t have a secrets manager yet, you can use a plain file as a starting point — just ensure it’s not world-readable:

echo "OPENROUTER_API_KEY=sk-or-your-key" | sudo install -m 0600 -o hermes /dev/stdin /var/lib/hermes/env

services.hermes-agent.environmentFiles = [ "/var/lib/hermes/env" ];

:::

::tip addToSystemPackages Setting addToSystemPackages = true does two things: puts the hermes CLI on your system PATH and sets HERMES_HOME system-wide so the interactive CLI shares state (sessions, skills, cron) with the gateway service. Without it, running hermes in your shell creates a separate ~/.hermes/ directory.

::

::info Container-aware CLI When container.enable = true and addToSystemPackages = true, every hermes command on the host automatically routes into the managed container. This means your interactive CLI session runs inside the same environment as the gateway service — with access to all container-installed packages and tools.

• The routing is transparent: hermes chat, hermes sessions list, hermes version, etc. all exec into the container under the hood
• All CLI flags are forwarded as-is
• If the container isn’t running, the CLI retries briefly (5s with a spinner for interactive use, 10s silently for scripts) then fails with a clear error — no silent fallback
• For developers working on the hermes codebase, set HERMES_DEV=1 to bypass container routing and run the local checkout directly

Set container.hostUsers to create a ~/.hermes symlink to the service state directory, so the host CLI and the container share sessions, config, and memories:

services.hermes-agent = {
  container.enable = true;
  container.hostUsers = [ "your-username" ];
  addToSystemPackages = true;
};

Users listed in hostUsers are automatically added to the hermes group for file permission access.

Podman users: The NixOS service runs the container as root. Docker users get access via the docker group socket, but Podman’s rootful containers require sudo. Grant passwordless sudo for your container runtime:

security.sudo.extraRules = [{
  users = [ "your-username" ];
  commands = [{
    command = "/run/current-system/sw/bin/podman";
    options = [ "NOPASSWD" ];
  }];
}];

The CLI auto-detects when sudo is needed and uses it transparently. Without this, you’ll need to run sudo hermes chat manually.

::

Verify It Works

After nixos-rebuild switch, check that the service is running:

# Check service status
systemctl status hermes-agent

# Watch logs (Ctrl+C to stop)
journalctl -u hermes-agent -f

# If addToSystemPackages is true, test the CLI
hermes version
hermes config       # shows the generated config

Choosing a Deployment Mode

The module supports two modes, controlled by container.enable:

To enable container mode, add one line:

{
  services.hermes-agent = {
    enable = true;
    container.enable = true;
    # ... rest of config is identical
  };
}

:::info Container mode auto-enables virtualisation.docker.enable via mkDefault. If you use Podman instead, set container.backend = "podman" and virtualisation.docker.enable = false.

::

Configuration

Declarative Settings

The settings option accepts an arbitrary attrset that is rendered as config.yaml. It supports deep merging across multiple module definitions (via lib.recursiveUpdate), so you can split config across files:

# base.nix
services.hermes-agent.settings = {
  model.default = "anthropic/claude-sonnet-4";
  toolsets = [ "all" ];
  terminal = { backend = "local"; timeout = 180; };
};

# personality.nix
services.hermes-agent.settings = {
  display = { compact = false; personality = "kawaii"; };
  memory = { memory_enabled = true; user_profile_enabled = true; };
};

Both are deep-merged at evaluation time. Nix-declared keys always win over keys in an existing config.yaml on disk, but user-added keys that Nix doesn’t touch are preserved. This means if the agent or a manual edit adds keys like skills.disabled or streaming.enabled, they survive nixos-rebuild switch.

::note Model naming settings.model.default uses the model identifier your provider expects. With OpenRouter (the default), these look like "anthropic/claude-sonnet-4" or "google/gemini-3-flash". If you’re using a provider directly (Anthropic, OpenAI), set settings.model.base_url to point at their API and use their native model IDs (e.g., "claude-sonnet-4-20250514"). When no base_url is set, Hermes defaults to OpenRouter.

::

::tip Discovering available config keys Run nix build .#configKeys && cat result to see every leaf config key extracted from Python’s DEFAULT_CONFIG. You can paste your existing config.yaml into the settings attrset — the structure maps 1:1.

::

{ config, ... }: {
  services.hermes-agent = {
    enable = true;
    container.enable = true;

    # ── Model ──────────────────────────────────────────────────────────
    settings = {
      model = {
        base_url = "https://openrouter.ai/api/v1";
        default = "anthropic/claude-opus-4.6";
      };
      toolsets = [ "all" ];
      max_turns = 100;
      terminal = { backend = "local"; cwd = "."; timeout = 180; };
      compression = {
        enabled = true;
        threshold = 0.85;
        summary_model = "google/gemini-3-flash-preview";
      };
      memory = { memory_enabled = true; user_profile_enabled = true; };
      display = { compact = false; personality = "kawaii"; };
      agent = { max_turns = 60; verbose = false; };
    };

    # ── Secrets ────────────────────────────────────────────────────────
    environmentFiles = [ config.sops.secrets."hermes-env".path ];

    # ── Documents ──────────────────────────────────────────────────────
    documents = {
      "SOUL.md" = builtins.readFile /home/user/.hermes/SOUL.md;
      "USER.md" = ./documents/USER.md;
    };

    # ── MCP Servers ────────────────────────────────────────────────────
    mcpServers.filesystem = {
      command = "npx";
      args = [ "-y" "@modelcontextprotocol/server-filesystem" "/data/workspace" ];
    };

    # ── Container options ──────────────────────────────────────────────
    container = {
      image = "ubuntu:24.04";
      backend = "docker";
      hostUsers = [ "your-username" ];
      extraVolumes = [ "/home/user/projects:/projects:rw" ];
      extraOptions = [ "--gpus" "all" ];
    };

    # ── Service tuning ─────────────────────────────────────────────────
    addToSystemPackages = true;
    extraArgs = [ "--verbose" ];
    restart = "always";
    restartSec = 5;
  };
}

Escape Hatch: Bring Your Own Config

If you’d rather manage config.yaml entirely outside Nix, use configFile:

services.hermes-agent.configFile = /etc/hermes/config.yaml;

This bypasses settings entirely — no merge, no generation. The file is copied as-is to $HERMES_HOME/config.yaml on each activation.

Customization Cheatsheet

Quick reference for the most common things Nix users want to customize:

Secrets Management

:::danger Never put API keys in settings or environment Values in Nix expressions end up in /nix/store, which is world-readable. Always use environmentFiles with a secrets manager.

::

Both environment (non-secret vars) and environmentFiles (secret files) are merged into $HERMES_HOME/.env at activation time (nixos-rebuild switch). Hermes reads this file on every startup, so changes take effect with a systemctl restart hermes-agent — no container recreation needed.

sops-nix

{
  sops = {
    defaultSopsFile = ./secrets/hermes.yaml;
    age.keyFile = "/home/user/.config/sops/age/keys.txt";
    secrets."hermes-env" = { format = "yaml"; };
  };

  services.hermes-agent.environmentFiles = [
    config.sops.secrets."hermes-env".path
  ];
}

The secrets file contains key-value pairs:

# secrets/hermes.yaml (encrypted with sops)
hermes-env: |
    OPENROUTER_API_KEY=sk-or-...
    TELEGRAM_BOT_TOKEN=123456:ABC...
    ANTHROPIC_API_KEY=sk-ant-...

agenix

{
  age.secrets.hermes-env.file = ./secrets/hermes-env.age;

  services.hermes-agent.environmentFiles = [
    config.age.secrets.hermes-env.path
  ];
}

OAuth / Auth Seeding

For platforms requiring OAuth (e.g., Discord), use authFile to seed credentials on first deploy:

{
  services.hermes-agent = {
    authFile = config.sops.secrets."hermes/auth.json".path;
    # authFileForceOverwrite = true;  # overwrite on every activation
  };
}

The file is only copied if auth.json doesn’t already exist (unless authFileForceOverwrite = true). Runtime OAuth token refreshes are written to the state directory and preserved across rebuilds.

Documents

The documents option installs files into the agent’s working directory (the workingDirectory, which the agent reads as its workspace). Hermes looks for specific filenames by convention:

• SOUL.md — the agent’s system prompt / personality. Hermes reads this on startup and uses it as persistent instructions that shape its behavior across all conversations.
• USER.md — context about the user the agent is interacting with.
• Any other files you place here are visible to the agent as workspace files.

{
  services.hermes-agent.documents = {
    "SOUL.md" = ''
      You are a helpful research assistant specializing in NixOS packaging.
      Always cite sources and prefer reproducible solutions.
    '';
    "USER.md" = ./documents/USER.md;  # path reference, copied from Nix store
  };
}

Values can be inline strings or path references. Files are installed on every nixos-rebuild switch.

MCP Servers

The mcpServers option declaratively configures MCP (Model Context Protocol) servers. Each server uses either stdio (local command) or HTTP (remote URL) transport.

Stdio Transport (Local Servers)

{
  services.hermes-agent.mcpServers = {
    filesystem = {
      command = "npx";
      args = [ "-y" "@modelcontextprotocol/server-filesystem" "/data/workspace" ];
    };
    github = {
      command = "npx";
      args = [ "-y" "@modelcontextprotocol/server-github" ];
      env.GITHUB_PERSONAL_ACCESS_TOKEN = "\${GITHUB_TOKEN}"; # resolved from .env
    };
  };
}

:::tip Environment variables in env values are resolved from $HERMES_HOME/.env at runtime. Use environmentFiles to inject secrets — never put tokens directly in Nix config.

::

HTTP Transport (Remote Servers)

{
  services.hermes-agent.mcpServers.remote-api = {
    url = "https://mcp.example.com/v1/mcp";
    headers.Authorization = "Bearer \${MCP_REMOTE_API_KEY}";
    timeout = 180;
  };
}

HTTP Transport with OAuth

Set auth = "oauth" for servers using OAuth 2.1. Hermes implements the full PKCE flow — metadata discovery, dynamic client registration, token exchange, and automatic refresh.

{
  services.hermes-agent.mcpServers.my-oauth-server = {
    url = "https://mcp.example.com/mcp";
    auth = "oauth";
  };
}

Tokens are stored in $HERMES_HOME/mcp-tokens/<server-name>.json and persist across restarts and rebuilds.

# Container mode
docker exec -it hermes-agent \
  hermes mcp add my-oauth-server --url https://mcp.example.com/mcp --auth oauth

# Native mode
sudo -u hermes HERMES_HOME=/var/lib/hermes/.hermes \
  hermes mcp add my-oauth-server --url https://mcp.example.com/mcp --auth oauth

hermes mcp add my-oauth-server --url https://mcp.example.com/mcp --auth oauth
scp ~/.hermes/mcp-tokens/my-oauth-server{,.client}.json \
    server:/var/lib/hermes/.hermes/mcp-tokens/
# Ensure: chown hermes:hermes, chmod 0600

Sampling (Server-Initiated LLM Requests)

Some MCP servers can request LLM completions from the agent:

{
  services.hermes-agent.mcpServers.analysis = {
    command = "npx";
    args = [ "-y" "analysis-server" ];
    sampling = {
      enabled = true;
      model = "google/gemini-3-flash";
      max_tokens_cap = 4096;
      timeout = 30;
      max_rpm = 10;
    };
  };
}

Managed Mode

When hermes runs via the NixOS module, the following CLI commands are blocked with a descriptive error pointing you to configuration.nix:

This prevents drift between what Nix declares and what’s on disk. Detection uses two signals:

1. HERMES_MANAGED=true environment variable — set by the systemd service, visible to the gateway process
2. .managed marker file in HERMES_HOME — set by the activation script, visible to interactive shells (e.g., docker exec -it hermes-agent hermes config set ... is also blocked)

To change configuration, edit your Nix config and run sudo nixos-rebuild switch.

Container Architecture

:::info This section is only relevant if you’re using container.enable = true. Skip it for native mode deployments.

::

When container mode is enabled, hermes runs inside a persistent Ubuntu container with the Nix-built binary bind-mounted read-only from the host:

Host                                    Container
────                                    ─────────
/nix/store/...-hermes-agent-0.1.0  ──►  /nix/store/... (ro)
~/.hermes -> /var/lib/hermes/.hermes       (symlink bridge, per hostUsers)
/var/lib/hermes/                    ──►  /data/          (rw)
  ├── current-package -> /nix/store/...    (symlink, updated each rebuild)
  ├── .gc-root -> /nix/store/...           (prevents nix-collect-garbage)
  ├── .container-identity                  (sha256 hash, triggers recreation)
  ├── .hermes/                             (HERMES_HOME)
  │   ├── .env                             (merged from environment + environmentFiles)
  │   ├── config.yaml                      (Nix-generated, deep-merged by activation)
  │   ├── .managed                         (marker file)
  │   ├── .container-mode                  (routing metadata: backend, exec_user, etc.)
  │   ├── state.db, sessions/, memories/   (runtime state)
  │   └── mcp-tokens/                      (OAuth tokens for MCP servers)
  ├── home/                                ──►  /home/hermes    (rw)
  └── workspace/                           (MESSAGING_CWD)
      ├── SOUL.md                          (from documents option)
      └── (agent-created files)

Container writable layer (apt/pip/npm):   /usr, /usr/local, /tmp

The Nix-built binary works inside the Ubuntu container because /nix/store is bind-mounted — it brings its own interpreter and all dependencies, so there’s no reliance on the container’s system libraries. The container entrypoint resolves through a current-package symlink: /data/current-package/bin/hermes gateway run --replace. On nixos-rebuild switch, only the symlink is updated — the container keeps running.

What Persists Across What

The container is only recreated when its identity hash changes. The hash covers: schema version, image, extraVolumes, extraOptions, and the entrypoint script. Changes to environment variables, settings, documents, or the hermes package itself do not trigger recreation.

::warning Writable layer loss When the identity hash changes (image upgrade, new volumes, new container options), the container is destroyed and recreated from a fresh pull of container.image. Any apt install, pip install, or npm install packages in the writable layer are lost. State in /data and /home/hermes is preserved (these are bind mounts).

If the agent relies on specific packages, consider baking them into a custom image (container.image = "my-registry/hermes-base:latest") or scripting their installation in the agent’s SOUL.md.

::

GC Root Protection

The preStart script creates a GC root at ${stateDir}/.gc-root pointing to the current hermes package. This prevents nix-collect-garbage from removing the running binary. If the GC root somehow breaks, restarting the service recreates it.

Development

Dev Shell

The flake provides a development shell with Python 3.11, uv, Node.js, and all runtime tools:

cd hermes-agent
nix develop

# Shell provides:
#   - Python 3.11 + uv (deps installed into .venv on first entry)
#   - Node.js 20, ripgrep, git, openssh, ffmpeg on PATH
#   - Stamp-file optimization: re-entry is near-instant if deps haven't changed

hermes setup
hermes chat

direnv (Recommended)

The included .envrc activates the dev shell automatically:

cd hermes-agent
direnv allow    # one-time
# Subsequent entries are near-instant (stamp file skips dep install)

Flake Checks

The flake includes build-time verification that runs in CI and locally:

# Run all checks
nix flake check

# Individual checks
nix build .#checks.x86_64-linux.package-contents   # binaries exist + version
nix build .#checks.x86_64-linux.entry-points-sync  # pyproject.toml ↔ Nix package sync
nix build .#checks.x86_64-linux.cli-commands        # gateway/config subcommands
nix build .#checks.x86_64-linux.managed-guard       # HERMES_MANAGED blocks mutation
nix build .#checks.x86_64-linux.bundled-skills      # skills present in package
nix build .#checks.x86_64-linux.config-roundtrip    # merge script preserves user keys

Options Reference

Core

Configuration

Secrets & Environment

Documents

MCP Servers

Service Behavior

Container

Directory Layout

Native Mode

/var/lib/hermes/                     # stateDir (owned by hermes:hermes, 0750)
├── .hermes/                         # HERMES_HOME
│   ├── config.yaml                  # Nix-generated (deep-merged each rebuild)
│   ├── .managed                     # Marker: CLI config mutation blocked
│   ├── .env                         # Merged from environment + environmentFiles
│   ├── auth.json                    # OAuth credentials (seeded, then self-managed)
│   ├── gateway.pid
│   ├── state.db
│   ├── mcp-tokens/                  # OAuth tokens for MCP servers
│   ├── sessions/
│   ├── memories/
│   ├── skills/
│   ├── cron/
│   └── logs/
├── home/                            # Agent HOME
└── workspace/                       # MESSAGING_CWD
    ├── SOUL.md                      # From documents option
    └── (agent-created files)

Container Mode

Same layout, mounted into the container:

Updating

# Update the flake input
nix flake update hermes-agent --flake /etc/nixos

# Rebuild
sudo nixos-rebuild switch

In container mode, the current-package symlink is updated and the agent picks up the new binary on restart. No container recreation, no loss of installed packages.

Troubleshooting

:::tip Podman users All docker commands below work the same with podman. Substitute accordingly if you set container.backend = "podman".

::

Service Logs

# Both modes use the same systemd unit
journalctl -u hermes-agent -f

# Container mode: also available directly
docker logs -f hermes-agent

Container Inspection

systemctl status hermes-agent
docker ps -a --filter name=hermes-agent
docker inspect hermes-agent --format='{{.State.Status}}'
docker exec -it hermes-agent bash
docker exec hermes-agent readlink /data/current-package
docker exec hermes-agent cat /data/.container-identity

Force Container Recreation

If you need to reset the writable layer (fresh Ubuntu):

sudo systemctl stop hermes-agent
docker rm -f hermes-agent
sudo rm /var/lib/hermes/.container-identity
sudo systemctl start hermes-agent

Verify Secrets Are Loaded

If the agent starts but can’t authenticate with the LLM provider, check that the .env file was merged correctly:

# Native mode
sudo -u hermes cat /var/lib/hermes/.hermes/.env

# Container mode
docker exec hermes-agent cat /data/.hermes/.env

GC Root Verification

nix-store --query --roots $(docker exec hermes-agent readlink /data/current-package)

Common Issues

Updating & Uninstalling

sidebar_position: 3 title: “Updating & Uninstalling” description: “How to update Hermes Agent to the latest version or uninstall it”

Updating & Uninstalling

Updating

Update to the latest version with a single command:

hermes update

This pulls the latest code, updates dependencies, and prompts you to configure any new options that were added since your last update.

::tip hermes update automatically detects new configuration options and prompts you to add them. If you skipped that prompt, you can manually run hermes config check to see missing options, then hermes config migrate to interactively add them.

::

What happens during an update

When you run hermes update, the following steps occur:

1. Git pull — pulls the latest code from the main branch and updates submodules
2. Dependency install — runs uv pip install -e ".[all]" to pick up new or changed dependencies
3. Config migration — detects new config options added since your version and prompts you to set them
4. Gateway auto-restart — if the gateway service is running (systemd on Linux, launchd on macOS), it is automatically restarted after the update completes so the new code takes effect immediately

Expected output looks like:

$ hermes update
Updating Hermes Agent...
📥 Pulling latest code...
Already up to date.  (or: Updating abc1234..def5678)
📦 Updating dependencies...
✅ Dependencies updated
🔍 Checking for new config options...
✅ Config is up to date  (or: Found 2 new options — running migration...)
🔄 Restarting gateway service...
✅ Gateway restarted
✅ Hermes Agent updated successfully!

Recommended Post-Update Validation

hermes update handles the main update path, but a quick validation confirms everything landed cleanly:

1. git status --short — if the tree is unexpectedly dirty, inspect before continuing
2. hermes doctor — checks config, dependencies, and service health
3. hermes --version — confirm the version bumped as expected
4. If you use the gateway: hermes gateway status
5. If doctor reports npm audit issues: run npm audit fix in the flagged directory

:::warning Dirty working tree after update If git status --short shows unexpected changes after hermes update, stop and inspect them before continuing. This usually means local modifications were reapplied on top of the updated code, or a dependency step refreshed lockfiles.

::

Checking your current version

hermes version

Compare against the latest release at the GitHub releases page or check for available updates:

hermes update --check

Updating from Messaging Platforms

You can also update directly from Telegram, Discord, Slack, or WhatsApp by sending:

/update

This pulls the latest code, updates dependencies, and restarts the gateway. The bot will briefly go offline during the restart (typically 5–15 seconds) and then resume.

Manual Update

If you installed manually (not via the quick installer):

cd /path/to/hermes-agent
export VIRTUAL_ENV="$(pwd)/venv"

# Pull latest code and submodules
git pull origin main
git submodule update --init --recursive

# Reinstall (picks up new dependencies)
uv pip install -e ".[all]"
uv pip install -e "./tinker-atropos"

# Check for new config options
hermes config check
hermes config migrate   # Interactively add any missing options

Rollback instructions

If an update introduces a problem, you can roll back to a previous version:

cd /path/to/hermes-agent

# List recent versions
git log --oneline -10

# Roll back to a specific commit
git checkout <commit-hash>
git submodule update --init --recursive
uv pip install -e ".[all]"

# Restart the gateway if running
hermes gateway restart

To roll back to a specific release tag:

git checkout v0.6.0
git submodule update --init --recursive
uv pip install -e ".[all]"

:::warning Rolling back may cause config incompatibilities if new options were added. Run hermes config check after rolling back and remove any unrecognized options from config.yaml if you encounter errors.

::

Note for Nix users

If you installed via Nix flake, updates are managed through the Nix package manager:

# Update the flake input
nix flake update hermes-agent

# Or rebuild with the latest
nix profile upgrade hermes-agent

Nix installations are immutable — rollback is handled by Nix’s generation system:

nix profile rollback

See Nix Setup for more details.

Uninstalling

hermes uninstall

The uninstaller gives you the option to keep your configuration files (~/.hermes/) for a future reinstall.

Manual Uninstall

rm -f ~/.local/bin/hermes
rm -rf /path/to/hermes-agent
rm -rf ~/.hermes            # Optional — keep if you plan to reinstall

:::info If you installed the gateway as a system service, stop and disable it first:

hermes gateway stop
# Linux: systemctl --user disable hermes-gateway
# macOS: launchctl remove ai.hermes.gateway

:::

Android / Termux

sidebar_position: 3 title: “Android / Termux” description: “Run Hermes Agent directly on an Android phone with Termux”

Hermes on Android with Termux

This is the tested path for running Hermes Agent directly on an Android phone through Termux.

It gives you a working local CLI on the phone, plus the core extras that are currently known to install cleanly on Android.

What is supported in the tested path?

The tested Termux bundle installs:

• the Hermes CLI
• cron support
• PTY/background terminal support
• MCP support
• Honcho memory support
• ACP support

Concretely, it maps to:

python -m pip install -e '.[termux]' -c constraints-termux.txt

What is not part of the tested path yet?

A few features still need desktop/server-style dependencies that are not published for Android, or have not been validated on phones yet:

• .[all] is not supported on Android today
• the voice extra is blocked by faster-whisper -> ctranslate2, and ctranslate2 does not publish Android wheels
• automatic browser / Playwright bootstrap is skipped in the Termux installer
• Docker-based terminal isolation is not available inside Termux

That does not stop Hermes from working well as a phone-native CLI agent — it just means the recommended mobile install is intentionally narrower than the desktop/server install.

Option 1: One-line installer

Hermes now ships a Termux-aware installer path:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

On Termux, the installer automatically:

• uses pkg for system packages
• creates the venv with python -m venv
• installs .[termux] with pip
• links hermes into $PREFIX/bin so it stays on your Termux PATH
• skips the untested browser / WhatsApp bootstrap

If you want the explicit commands or need to debug a failed install, use the manual path below.

Option 2: Manual install (fully explicit)

1. Update Termux and install system packages

pkg update
pkg install -y git python clang rust make pkg-config libffi openssl nodejs ripgrep ffmpeg

Why these packages?

• python — runtime + venv support
• git — clone/update the repo
• clang, rust, make, pkg-config, libffi, openssl — needed to build a few Python dependencies on Android
• nodejs — optional Node runtime for experiments beyond the tested core path
• ripgrep — fast file search
• ffmpeg — media / TTS conversions

2. Clone Hermes

git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

If you already cloned without submodules:

git submodule update --init --recursive

3. Create a virtual environment

python -m venv venv
source venv/bin/activate
export ANDROID_API_LEVEL="$(getprop ro.build.version.sdk)"
python -m pip install --upgrade pip setuptools wheel

ANDROID_API_LEVEL is important for Rust / maturin-based packages such as jiter.

4. Install the tested Termux bundle

python -m pip install -e '.[termux]' -c constraints-termux.txt

If you only want the minimal core agent, this also works:

python -m pip install -e '.' -c constraints-termux.txt

5. Put hermes on your Termux PATH

ln -sf "$PWD/venv/bin/hermes" "$PREFIX/bin/hermes"

$PREFIX/bin is already on PATH in Termux, so this makes the hermes command persist across new shells without re-activating the venv every time.

6. Verify the install

hermes version
hermes doctor

7. Start Hermes

hermes

Recommended follow-up setup

Configure a model

hermes model

Or set keys directly in ~/.hermes/.env.

Re-run the full interactive setup wizard later

hermes setup

Install optional Node dependencies manually

The tested Termux path skips Node/browser bootstrap on purpose. If you want to experiment later:

npm install

Treat browser / WhatsApp tooling on Android as experimental until documented otherwise.

Troubleshooting

No solution found when installing .[all]

Use the tested Termux bundle instead:

python -m pip install -e '.[termux]' -c constraints-termux.txt

The blocker is currently the voice extra:

• voice pulls faster-whisper
• faster-whisper depends on ctranslate2
• ctranslate2 does not publish Android wheels

uv pip install fails on Android

Use the Termux path with the stdlib venv + pip instead:

python -m venv venv
source venv/bin/activate
export ANDROID_API_LEVEL="$(getprop ro.build.version.sdk)"
python -m pip install --upgrade pip setuptools wheel
python -m pip install -e '.[termux]' -c constraints-termux.txt

jiter / maturin complains about ANDROID_API_LEVEL

Set the API level explicitly before installing:

export ANDROID_API_LEVEL="$(getprop ro.build.version.sdk)"
python -m pip install -e '.[termux]' -c constraints-termux.txt

hermes doctor says ripgrep or Node is missing

Install them with Termux packages:

pkg install ripgrep nodejs

Build failures while installing Python packages

Make sure the build toolchain is installed:

pkg install clang rust make pkg-config libffi openssl

Then retry:

python -m pip install -e '.[termux]' -c constraints-termux.txt

Known limitations on phones

• Docker backend is unavailable
• local voice transcription via faster-whisper is unavailable in the tested path
• browser automation setup is intentionally skipped by the installer
• some optional extras may work, but only .[termux] is currently documented as the tested Android bundle

If you hit a new Android-specific issue, please open a GitHub issue with:

• your Android version
• termux-info
• python --version
• hermes doctor
• the exact install command and full error output

Configuration

sidebar_position: 2 title: “Configuration” description: “Configure Hermes Agent — config.yaml, providers, models, API keys, and more”

Configuration

All settings are stored in the ~/.hermes/ directory for easy access.

Directory Structure

~/.hermes/
├── config.yaml     # Settings (model, terminal, TTS, compression, etc.)
├── .env            # API keys and secrets
├── auth.json       # OAuth provider credentials (Nous Portal, etc.)
├── SOUL.md         # Primary agent identity (slot #1 in system prompt)
├── memories/       # Persistent memory (MEMORY.md, USER.md)
├── skills/         # Agent-created skills (managed via skill_manage tool)
├── cron/           # Scheduled jobs
├── sessions/       # Gateway sessions
└── logs/           # Logs (errors.log, gateway.log — secrets auto-redacted)

Managing Configuration

hermes config              # View current configuration
hermes config edit         # Open config.yaml in your editor
hermes config set KEY VAL  # Set a specific value
hermes config check        # Check for missing options (after updates)
hermes config migrate      # Interactively add missing options

# Examples:
hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...  # Saves to .env

:::tip The hermes config set command automatically routes values to the right file — API keys are saved to .env, everything else to config.yaml.

::

Configuration Precedence

Settings are resolved in this order (highest priority first):

1. CLI arguments — e.g., hermes chat --model anthropic/claude-sonnet-4 (per-invocation override)
2. ~/.hermes/config.yaml — the primary config file for all non-secret settings
3. ~/.hermes/.env — fallback for env vars; required for secrets (API keys, tokens, passwords)
4. Built-in defaults — hardcoded safe defaults when nothing else is set

:::info Rule of Thumb Secrets (API keys, bot tokens, passwords) go in .env. Everything else (model, terminal backend, compression settings, memory limits, toolsets) goes in config.yaml. When both are set, config.yaml wins for non-secret settings.

::

Environment Variable Substitution

You can reference environment variables in config.yaml using ${VAR_NAME} syntax:

auxiliary:
  vision:
    api_key: ${GOOGLE_API_KEY}
    base_url: ${CUSTOM_VISION_URL}

delegation:
  api_key: ${DELEGATION_KEY}

Multiple references in a single value work: url: "${HOST}:${PORT}". If a referenced variable is not set, the placeholder is kept verbatim (${UNDEFINED_VAR} stays as-is). Only the ${VAR} syntax is supported — bare $VAR is not expanded.

For AI provider setup (OpenRouter, Anthropic, Copilot, custom endpoints, self-hosted LLMs, fallback models, etc.), see AI Providers.

Terminal Backend Configuration

Hermes supports six terminal backends. Each determines where the agent’s shell commands actually execute — your local machine, a Docker container, a remote server via SSH, a Modal cloud sandbox, a Daytona workspace, or a Singularity/Apptainer container.

terminal:
  backend: local    # local | docker | ssh | modal | daytona | singularity
  cwd: "."          # Working directory ("." = current dir for local, "/root" for containers)
  timeout: 180      # Per-command timeout in seconds
  env_passthrough: []  # Env var names to forward to sandboxed execution (terminal + execute_code)
  singularity_image: "docker://nikolaik/python-nodejs:python3.11-nodejs20"  # Container image for Singularity backend
  modal_image: "nikolaik/python-nodejs:python3.11-nodejs20"                 # Container image for Modal backend
  daytona_image: "nikolaik/python-nodejs:python3.11-nodejs20"               # Container image for Daytona backend

For cloud sandboxes such as Modal and Daytona, container_persistent: true means Hermes will try to preserve filesystem state across sandbox recreation. It does not promise that the same live sandbox, PID space, or background processes will still be running later.

Backend Overview

Local Backend

The default. Commands run directly on your machine with no isolation. No special setup required.

terminal:
  backend: local

:::warning The agent has the same filesystem access as your user account. Use hermes tools to disable tools you don’t want, or switch to Docker for sandboxing.

::

Docker Backend

Runs commands inside a Docker container with security hardening (all capabilities dropped, no privilege escalation, PID limits).

terminal:
  backend: docker
  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
  docker_mount_cwd_to_workspace: false  # Mount launch dir into /workspace
  docker_forward_env:              # Env vars to forward into container
    - "GITHUB_TOKEN"
  docker_volumes:                  # Host directory mounts
    - "/home/user/projects:/workspace/projects"
    - "/home/user/data:/data:ro"   # :ro for read-only

  # Resource limits
  container_cpu: 1                 # CPU cores (0 = unlimited)
  container_memory: 5120           # MB (0 = unlimited)
  container_disk: 51200            # MB (requires overlay2 on XFS+pquota)
  container_persistent: true       # Persist /workspace and /root across sessions

Requirements: Docker Desktop or Docker Engine installed and running. Hermes probes $PATH plus common macOS install locations (/usr/local/bin/docker, /opt/homebrew/bin/docker, Docker Desktop app bundle).

Container lifecycle: Each session starts a long-lived container (docker run -d ... sleep 2h). Commands run via docker exec with a login shell. On cleanup, the container is stopped and removed.

Security hardening:

• --cap-drop ALL with only DAC_OVERRIDE, CHOWN, FOWNER added back
• --security-opt no-new-privileges
• --pids-limit 256
• Size-limited tmpfs for /tmp (512MB), /var/tmp (256MB), /run (64MB)

Credential forwarding: Env vars listed in docker_forward_env are resolved from your shell environment first, then ~/.hermes/.env. Skills can also declare required_environment_variables which are merged automatically.

SSH Backend

Runs commands on a remote server over SSH. Uses ControlMaster for connection reuse (5-minute idle keepalive). Persistent shell is enabled by default — state (cwd, env vars) survives across commands.

terminal:
  backend: ssh
  persistent_shell: true           # Keep a long-lived bash session (default: true)

Required environment variables:

TERMINAL_SSH_HOST=my-server.example.com
TERMINAL_SSH_USER=ubuntu

Optional:

How it works: Connects at init time with BatchMode=yes and StrictHostKeyChecking=accept-new. Persistent shell keeps a single bash -l process alive on the remote host, communicating via temporary files. Commands that need stdin_data or sudo automatically fall back to one-shot mode.

Modal Backend

Runs commands in a Modal cloud sandbox. Each task gets an isolated VM with configurable CPU, memory, and disk. Filesystem can be snapshot/restored across sessions.

terminal:
  backend: modal
  container_cpu: 1                 # CPU cores
  container_memory: 5120           # MB (5GB)
  container_disk: 51200            # MB (50GB)
  container_persistent: true       # Snapshot/restore filesystem

Required: Either MODAL_TOKEN_ID + MODAL_TOKEN_SECRET environment variables, or a ~/.modal.toml config file.

Persistence: When enabled, the sandbox filesystem is snapshotted on cleanup and restored on next session. Snapshots are tracked in ~/.hermes/modal_snapshots.json. This preserves filesystem state, not live processes, PID space, or background jobs.

Credential files: Automatically mounted from ~/.hermes/ (OAuth tokens, etc.) and synced before each command.

Daytona Backend

Runs commands in a Daytona managed workspace. Supports stop/resume for persistence.

terminal:
  backend: daytona
  container_cpu: 1                 # CPU cores
  container_memory: 5120           # MB → converted to GiB
  container_disk: 10240            # MB → converted to GiB (max 10 GiB)
  container_persistent: true       # Stop/resume instead of delete

Required: DAYTONA_API_KEY environment variable.

Persistence: When enabled, sandboxes are stopped (not deleted) on cleanup and resumed on next session. Sandbox names follow the pattern hermes-{task_id}.

Disk limit: Daytona enforces a 10 GiB maximum. Requests above this are capped with a warning.

Singularity/Apptainer Backend

Runs commands in a Singularity/Apptainer container. Designed for HPC clusters and shared machines where Docker isn’t available.

terminal:
  backend: singularity
  singularity_image: "docker://nikolaik/python-nodejs:python3.11-nodejs20"
  container_cpu: 1                 # CPU cores
  container_memory: 5120           # MB
  container_persistent: true       # Writable overlay persists across sessions

Requirements: apptainer or singularity binary in $PATH.

Image handling: Docker URLs (docker://...) are automatically converted to SIF files and cached. Existing .sif files are used directly.

Scratch directory: Resolved in order: TERMINAL_SCRATCH_DIR → TERMINAL_SANDBOX_DIR/singularity → /scratch/$USER/hermes-agent (HPC convention) → ~/.hermes/sandboxes/singularity.

Isolation: Uses --containall --no-home for full namespace isolation without mounting the host home directory.

Common Terminal Backend Issues

If terminal commands fail immediately or the terminal tool is reported as disabled:

• Local — No special requirements. The safest default when getting started.
• Docker — Run docker version to verify Docker is working. If it fails, fix Docker or hermes config set terminal.backend local.
• SSH — Both TERMINAL_SSH_HOST and TERMINAL_SSH_USER must be set. Hermes logs a clear error if either is missing.
• Modal — Needs MODAL_TOKEN_ID env var or ~/.modal.toml. Run hermes doctor to check.
• Daytona — Needs DAYTONA_API_KEY. The Daytona SDK handles server URL configuration.
• Singularity — Needs apptainer or singularity in $PATH. Common on HPC clusters.

When in doubt, set terminal.backend back to local and verify that commands run there first.

Docker Volume Mounts

When using the Docker backend, docker_volumes lets you share host directories with the container. Each entry uses standard Docker -v syntax: host_path:container_path[:options].

terminal:
  backend: docker
  docker_volumes:
    - "/home/user/projects:/workspace/projects"   # Read-write (default)
    - "/home/user/datasets:/data:ro"              # Read-only
    - "/home/user/outputs:/outputs"               # Agent writes, you read

This is useful for:

• Providing files to the agent (datasets, configs, reference code)
• Receiving files from the agent (generated code, reports, exports)
• Shared workspaces where both you and the agent access the same files

Can also be set via environment variable: TERMINAL_DOCKER_VOLUMES='["/host:/container"]' (JSON array).

Docker Credential Forwarding

By default, Docker terminal sessions do not inherit arbitrary host credentials. If you need a specific token inside the container, add it to terminal.docker_forward_env.

terminal:
  backend: docker
  docker_forward_env:
    - "GITHUB_TOKEN"
    - "NPM_TOKEN"

Hermes resolves each listed variable from your current shell first, then falls back to ~/.hermes/.env if it was saved with hermes config set.

::warning Anything listed in docker_forward_env becomes visible to commands run inside the container. Only forward credentials you are comfortable exposing to the terminal session.

::

Optional: Mount the Launch Directory into /workspace

Docker sandboxes stay isolated by default. Hermes does not pass your current host working directory into the container unless you explicitly opt in.

Enable it in config.yaml:

terminal:
  backend: docker
  docker_mount_cwd_to_workspace: true

When enabled:

• if you launch Hermes from ~/projects/my-app, that host directory is bind-mounted to /workspace
• the Docker backend starts in /workspace
• file tools and terminal commands both see the same mounted project

When disabled, /workspace stays sandbox-owned unless you explicitly mount something via docker_volumes.

Security tradeoff:

• false preserves the sandbox boundary
• true gives the sandbox direct access to the directory you launched Hermes from

Use the opt-in only when you intentionally want the container to work on live host files.

Persistent Shell

By default, each terminal command runs in its own subprocess — working directory, environment variables, and shell variables reset between commands. When persistent shell is enabled, a single long-lived bash process is kept alive across execute() calls so that state survives between commands.

This is most useful for the SSH backend, where it also eliminates per-command connection overhead. Persistent shell is enabled by default for SSH and disabled for the local backend.

terminal:
  persistent_shell: true   # default — enables persistent shell for SSH

To disable:

hermes config set terminal.persistent_shell false

What persists across commands:

• Working directory (cd /tmp sticks for the next command)
• Exported environment variables (export FOO=bar)
• Shell variables (MY_VAR=hello)

Precedence:

Per-backend environment variables take highest precedence. If you want persistent shell on the local backend too:

export TERMINAL_LOCAL_PERSISTENT=true

:::note Commands that require stdin_data or sudo automatically fall back to one-shot mode, since the persistent shell’s stdin is already occupied by the IPC protocol.

::

See Code Execution and the Terminal section of the README for details on each backend.

Skill Settings

Skills can declare their own configuration settings via their SKILL.md frontmatter. These are non-secret values (paths, preferences, domain settings) stored under the skills.config namespace in config.yaml.

skills:
  config:
    wiki:
      path: ~/wiki          # Used by the llm-wiki skill

How skill settings work:

• hermes config migrate scans all enabled skills, finds unconfigured settings, and offers to prompt you
• hermes config show displays all skill settings under “Skill Settings” with the skill they belong to
• When a skill loads, its resolved config values are injected into the skill context automatically

Setting values manually:

hermes config set skills.config.wiki.path ~/my-research-wiki

For details on declaring config settings in your own skills, see Creating Skills — Config Settings.

Memory Configuration

memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200   # ~800 tokens
  user_char_limit: 1375     # ~500 tokens

File Read Safety

Controls how much content a single read_file call can return. Reads that exceed the limit are rejected with an error telling the agent to use offset and limit for a smaller range. This prevents a single read of a minified JS bundle or large data file from flooding the context window.

file_read_max_chars: 100000  # default — ~25-35K tokens

Raise it if you’re on a model with a large context window and frequently read big files. Lower it for small-context models to keep reads efficient:

# Large context model (200K+)
file_read_max_chars: 200000

# Small local model (16K context)
file_read_max_chars: 30000

The agent also deduplicates file reads automatically — if the same file region is read twice and the file hasn’t changed, a lightweight stub is returned instead of re-sending the content. This resets on context compression so the agent can re-read files after their content is summarized away.

Git Worktree Isolation

Enable isolated git worktrees for running multiple agents in parallel on the same repo:

worktree: true    # Always create a worktree (same as hermes -w)
# worktree: false # Default — only when -w flag is passed

When enabled, each CLI session creates a fresh worktree under .worktrees/ with its own branch. Agents can edit files, commit, push, and create PRs without interfering with each other. Clean worktrees are removed on exit; dirty ones are kept for manual recovery.

You can also list gitignored files to copy into worktrees via .worktreeinclude in your repo root:

# .worktreeinclude
.env
.venv/
node_modules/

Context Compression

Hermes automatically compresses long conversations to stay within your model’s context window. The compression summarizer is a separate LLM call — you can point it at any provider or endpoint.

All compression settings live in config.yaml (no environment variables).

Full reference

compression:
  enabled: true                                     # Toggle compression on/off
  threshold: 0.50                                   # Compress at this % of context limit
  target_ratio: 0.20                                # Fraction of threshold to preserve as recent tail
  protect_last_n: 20                                # Min recent messages to keep uncompressed
  summary_model: "google/gemini-3-flash-preview"    # Model for summarization
  summary_provider: "auto"                          # Provider: "auto", "openrouter", "nous", "codex", "main", etc.
  summary_base_url: null                            # Custom OpenAI-compatible endpoint (overrides provider)

Common setups

Default (auto-detect) — no configuration needed:

compression:
  enabled: true
  threshold: 0.50

Uses the first available provider (OpenRouter → Nous → Codex) with Gemini Flash.

Force a specific provider (OAuth or API-key based):

compression:
  summary_provider: nous
  summary_model: gemini-3-flash

Works with any provider: nous, openrouter, codex, anthropic, main, etc.

Custom endpoint (self-hosted, Ollama, zai, DeepSeek, etc.):

compression:
  summary_model: glm-4.7
  summary_base_url: https://api.z.ai/api/coding/paas/v4

Points at a custom OpenAI-compatible endpoint. Uses OPENAI_API_KEY for auth.

How the three knobs interact

:::warning Summary model context length requirement The summary_model must have a context window at least as large as your main agent model’s. The compressor sends the full middle section of the conversation to the summary model — if that model’s context window is smaller than the main model’s, the summarization call will fail with a context length error. When this happens, the middle turns are dropped without a summary, losing conversation context silently. If you override summary_model, verify its context length meets or exceeds your main model’s.

::

Context Engine

The context engine controls how conversations are managed when approaching the model’s token limit. The built-in compressor engine uses lossy summarization (see Context Compression). Plugin engines can replace it with alternative strategies.

context:
  engine: "compressor"    # default — built-in lossy summarization

To use a plugin engine (e.g., LCM for lossless context management):

context:
  engine: "lcm"          # must match the plugin's name

Plugin engines are never auto-activated — you must explicitly set context.engine to the plugin name. Available engines can be browsed and selected via hermes plugins → Provider Plugins → Context Engine.

See Memory Providers for the analogous single-select system for memory plugins.

Iteration Budget Pressure

When the agent is working on a complex task with many tool calls, it can burn through its iteration budget (default: 90 turns) without realizing it’s running low. Budget pressure automatically warns the model as it approaches the limit:

Warnings are injected into the last tool result’s JSON (as a _budget_warning field) rather than as separate messages — this preserves prompt caching and doesn’t disrupt the conversation structure.

agent:
  max_turns: 90                # Max iterations per conversation turn (default: 90)

Budget pressure is enabled by default. The agent sees warnings naturally as part of tool results, encouraging it to consolidate its work and deliver a response before running out of iterations.

Streaming Timeouts

The LLM streaming connection has two timeout layers. Both auto-adjust for local providers (localhost, LAN IPs) — no configuration needed for most setups.

The socket read timeout controls how long httpx waits for the next chunk of data from the provider. Local LLMs can take minutes for prefill on large contexts before producing the first token, so Hermes raises this to 30 minutes when it detects a local endpoint. If you explicitly set HERMES_STREAM_READ_TIMEOUT, that value is always used regardless of endpoint detection.

The stale stream detection kills connections that receive SSE keep-alive pings but no actual content. This is disabled entirely for local providers since they don’t send keep-alive pings during prefill.

Context Pressure Warnings

Separate from iteration budget pressure, context pressure tracks how close the conversation is to the compaction threshold — the point where context compression fires to summarize older messages. This helps both you and the agent understand when the conversation is getting long.

In the CLI, context pressure appears as a progress bar in the tool output feed:

  ◐ context ████████████░░░░░░░░ 62% to compaction  48k threshold (50%) · approaching compaction

On messaging platforms, a plain-text notification is sent:

◐ Context: ████████████░░░░░░░░ 62% to compaction (threshold: 50% of window).

If auto-compression is disabled, the warning tells you context may be truncated instead.

Context pressure is automatic — no configuration needed. It fires purely as a user-facing notification and does not modify the message stream or inject anything into the model’s context.

Credential Pool Strategies

When you have multiple API keys or OAuth tokens for the same provider, configure the rotation strategy:

credential_pool_strategies:
  openrouter: round_robin    # cycle through keys evenly
  anthropic: least_used      # always pick the least-used key

Options: fill_first (default), round_robin, least_used, random. See Credential Pools for full documentation.

Auxiliary Models

Hermes uses lightweight “auxiliary” models for side tasks like image analysis, web page summarization, and browser screenshot analysis. By default, these use Gemini Flash via auto-detection — you don’t need to configure anything.

The universal config pattern

Every model slot in Hermes — auxiliary tasks, compression, fallback — uses the same three knobs:

When base_url is set, Hermes ignores the provider and calls that endpoint directly (using api_key or OPENAI_API_KEY for auth). When only provider is set, Hermes uses that provider’s built-in auth and base URL.

Available providers for auxiliary tasks: auto, openrouter, nous, codex, copilot, anthropic, main, zai, kimi-coding, minimax, any provider registered in the provider registry, or any named custom provider from your custom_providers list (e.g. provider: "beans").

::warning "main" is for auxiliary tasks only The "main" provider option means “use whatever provider my main agent uses” — it’s only valid inside auxiliary:, compression:, and fallback_model: configs. It is not a valid value for your top-level model.provider setting. If you use a custom OpenAI-compatible endpoint, set provider: custom in your model: section. See AI Providers for all main model provider options.

::

Full auxiliary config reference

auxiliary:
  # Image analysis (vision_analyze tool + browser screenshots)
  vision:
    provider: "auto"           # "auto", "openrouter", "nous", "codex", "main", etc.
    model: ""                  # e.g. "openai/gpt-4o", "google/gemini-2.5-flash"
    base_url: ""               # Custom OpenAI-compatible endpoint (overrides provider)
    api_key: ""                # API key for base_url (falls back to OPENAI_API_KEY)
    timeout: 30                # seconds — LLM API call; increase for slow local vision models
    download_timeout: 30       # seconds — image HTTP download; increase for slow connections

  # Web page summarization + browser page text extraction
  web_extract:
    provider: "auto"
    model: ""                  # e.g. "google/gemini-2.5-flash"
    base_url: ""
    api_key: ""
    timeout: 360               # seconds (6min) — per-attempt LLM summarization

  # Dangerous command approval classifier
  approval:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30                # seconds

  # Context compression timeout (separate from compression.* config)
  compression:
    timeout: 120               # seconds — compression summarizes long conversations, needs more time

  # Session search — summarizes past session matches
  session_search:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

  # Skills hub — skill matching and search
  skills_hub:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

  # MCP tool dispatch
  mcp:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

  # Memory flush — summarizes conversation for persistent memory
  flush_memories:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

:::tip Each auxiliary task has a configurable timeout (in seconds). Defaults: vision 30s, web_extract 360s, approval 30s, compression 120s. Increase these if you use slow local models for auxiliary tasks. Vision also has a separate download_timeout (default 30s) for the HTTP image download — increase this for slow connections or self-hosted image servers.

::

::info Context compression has its own top-level compression: block with summary_provider, summary_model, and summary_base_url — see Context Compression above. The fallback model uses a fallback_model: block — see Fallback Model. All three follow the same provider/model/base_url pattern.

::

Changing the Vision Model

To use GPT-4o instead of Gemini Flash for image analysis:

auxiliary:
  vision:
    model: "openai/gpt-4o"

Or via environment variable (in ~/.hermes/.env):

AUXILIARY_VISION_MODEL=openai/gpt-4o

Provider Options

These options apply to auxiliary task configs (auxiliary:, compression:, fallback_model:), not to your main model.provider setting.

Common Setups

Using a direct custom endpoint (clearer than provider: "main" for local/self-hosted APIs):

auxiliary:
  vision:
    base_url: "http://localhost:1234/v1"
    api_key: "local-key"
    model: "qwen2.5-vl"

base_url takes precedence over provider, so this is the most explicit way to route an auxiliary task to a specific endpoint. For direct endpoint overrides, Hermes uses the configured api_key or falls back to OPENAI_API_KEY; it does not reuse OPENROUTER_API_KEY for that custom endpoint.

Using OpenAI API key for vision:

# In ~/.hermes/.env:
# OPENAI_BASE_URL=https://api.openai.com/v1
# OPENAI_API_KEY=sk-...

auxiliary:
  vision:
    provider: "main"
    model: "gpt-4o"       # or "gpt-4o-mini" for cheaper

Using OpenRouter for vision (route to any model):

auxiliary:
  vision:
    provider: "openrouter"
    model: "openai/gpt-4o"      # or "google/gemini-2.5-flash", etc.

Using Codex OAuth (ChatGPT Pro/Plus account — no API key needed):

auxiliary:
  vision:
    provider: "codex"     # uses your ChatGPT OAuth token
    # model defaults to gpt-5.3-codex (supports vision)

Using a local/self-hosted model:

auxiliary:
  vision:
    provider: "main"      # uses your active custom endpoint
    model: "my-local-model"

provider: "main" uses whatever provider Hermes uses for normal chat — whether that’s a named custom provider (e.g. beans), a built-in provider like openrouter, or a legacy OPENAI_BASE_URL endpoint.

::tip If you use Codex OAuth as your main model provider, vision works automatically — no extra configuration needed. Codex is included in the auto-detection chain for vision.

::

::warning Vision requires a multimodal model. If you set provider: "main", make sure your endpoint supports multimodal/vision — otherwise image analysis will fail.

::

Environment Variables (legacy)

Auxiliary models can also be configured via environment variables. However, config.yaml is the preferred method — it’s easier to manage and supports all options including base_url and api_key.

Compression and fallback model settings are config.yaml-only.

::tip Run hermes config to see your current auxiliary model settings. Overrides only show up when they differ from the defaults.

::

Reasoning Effort

Control how much “thinking” the model does before responding:

agent:
  reasoning_effort: ""   # empty = medium (default). Options: none, minimal, low, medium, high, xhigh (max)

When unset (default), reasoning effort defaults to “medium” — a balanced level that works well for most tasks. Setting a value overrides it — higher reasoning effort gives better results on complex tasks at the cost of more tokens and latency.

You can also change the reasoning effort at runtime with the /reasoning command:

/reasoning           # Show current effort level and display state
/reasoning high      # Set reasoning effort to high
/reasoning none      # Disable reasoning
/reasoning show      # Show model thinking above each response
/reasoning hide      # Hide model thinking

Tool-Use Enforcement

Some models occasionally describe intended actions as text instead of making tool calls (“I would run the tests…” instead of actually calling the terminal). Tool-use enforcement injects system prompt guidance that steers the model back to actually calling tools.

agent:
  tool_use_enforcement: "auto"   # "auto" | true | false | ["model-substring", ...]

What it injects

When enabled, three layers of guidance may be added to the system prompt:

1. General tool-use enforcement (all matched models) — instructs the model to make tool calls immediately instead of describing intentions, keep working until the task is complete, and never end a turn with a promise of future action.

2. OpenAI execution discipline (GPT and Codex models only) — additional guidance addressing GPT-specific failure modes: abandoning work on partial results, skipping prerequisite lookups, hallucinating instead of using tools, and declaring “done” without verification.

3. Google operational guidance (Gemini and Gemma models only) — conciseness, absolute paths, parallel tool calls, and verify-before-edit patterns.

These are transparent to the user and only affect the system prompt. Models that already use tools reliably (like Claude) don’t need this guidance, which is why "auto" excludes them.

When to turn it on

If you’re using a model not in the default auto list and notice it frequently describes what it would do instead of doing it, set tool_use_enforcement: true or add the model substring to the list:

agent:
  tool_use_enforcement: ["gpt", "codex", "gemini", "grok", "my-custom-model"]

TTS Configuration

tts:
  provider: "edge"              # "edge" | "elevenlabs" | "openai" | "neutts"
  edge:
    voice: "en-US-AriaNeural"   # 322 voices, 74 languages
  elevenlabs:
    voice_id: "pNInz6obpgDQGcFmaJgB"
    model_id: "eleven_multilingual_v2"
  openai:
    model: "gpt-4o-mini-tts"
    voice: "alloy"              # alloy, echo, fable, onyx, nova, shimmer
    base_url: "https://api.openai.com/v1"  # Override for OpenAI-compatible TTS endpoints
  neutts:
    ref_audio: ''
    ref_text: ''
    model: neuphonic/neutts-air-q4-gguf
    device: cpu

This controls both the text_to_speech tool and spoken replies in voice mode (/voice tts in the CLI or messaging gateway).

Display Settings

display:
  tool_progress: all      # off | new | all | verbose
  tool_progress_command: false  # Enable /verbose slash command in messaging gateway
  tool_progress_overrides: {}  # Per-platform overrides (see below)
  interim_assistant_messages: true  # Gateway: send natural mid-turn assistant updates as separate messages
  skin: default           # Built-in or custom CLI skin (see user-guide/features/skins)
  personality: "kawaii"  # Legacy cosmetic field still surfaced in some summaries
  compact: false          # Compact output mode (less whitespace)
  resume_display: full    # full (show previous messages on resume) | minimal (one-liner only)
  bell_on_complete: false # Play terminal bell when agent finishes (great for long tasks)
  show_reasoning: false   # Show model reasoning/thinking above each response (toggle with /reasoning show|hide)
  streaming: false        # Stream tokens to terminal as they arrive (real-time output)
  show_cost: false        # Show estimated $ cost in the CLI status bar
  tool_preview_length: 0  # Max chars for tool call previews (0 = no limit, show full paths/commands)

In the CLI, cycle through these modes with /verbose. To use /verbose in messaging platforms (Telegram, Discord, Slack, etc.), set tool_progress_command: true in the display section above. The command will then cycle the mode and save to config.

Per-platform progress overrides

Different platforms have different verbosity needs. For example, Signal can’t edit messages, so each progress update becomes a separate message — noisy. Use tool_progress_overrides to set per-platform modes:

display:
  tool_progress: all          # global default
  tool_progress_overrides:
    signal: 'off'             # silence progress on Signal
    telegram: verbose         # detailed progress on Telegram
    slack: 'off'              # quiet in shared Slack workspace

Platforms without an override fall back to the global tool_progress value. Valid platform keys: telegram, discord, slack, signal, whatsapp, matrix, mattermost, email, sms, homeassistant, dingtalk, feishu, wecom, weixin, bluebubbles.

interim_assistant_messages is gateway-only. When enabled, Hermes sends completed mid-turn assistant updates as separate chat messages. This is independent from tool_progress and does not require gateway streaming.

Privacy

privacy:
  redact_pii: false  # Strip PII from LLM context (gateway only)

When redact_pii is true, the gateway redacts personally identifiable information from the system prompt before sending it to the LLM on supported platforms:

Platform support: Redaction applies to WhatsApp, Signal, and Telegram. Discord and Slack are excluded because their mention systems (<@user_id>) require the real ID in the LLM context.

Hashes are deterministic — the same user always maps to the same hash, so the model can still distinguish between users in group chats. Routing and delivery use the original values internally.

Speech-to-Text (STT)

stt:
  provider: "local"            # "local" | "groq" | "openai"
  local:
    model: "base"              # tiny, base, small, medium, large-v3
  openai:
    model: "whisper-1"         # whisper-1 | gpt-4o-mini-transcribe | gpt-4o-transcribe
  # model: "whisper-1"         # Legacy fallback key still respected

Provider behavior:

• local uses faster-whisper running on your machine. Install it separately with pip install faster-whisper.
• groq uses Groq’s Whisper-compatible endpoint and reads GROQ_API_KEY.
• openai uses the OpenAI speech API and reads VOICE_TOOLS_OPENAI_KEY.

If the requested provider is unavailable, Hermes falls back automatically in this order: local → groq → openai.

Groq and OpenAI model overrides are environment-driven:

STT_GROQ_MODEL=whisper-large-v3-turbo
STT_OPENAI_MODEL=whisper-1
GROQ_BASE_URL=https://api.groq.com/openai/v1
STT_OPENAI_BASE_URL=https://api.openai.com/v1

Voice Mode (CLI)

voice:
  record_key: "ctrl+b"         # Push-to-talk key inside the CLI
  max_recording_seconds: 120    # Hard stop for long recordings
  auto_tts: false               # Enable spoken replies automatically when /voice on
  silence_threshold: 200        # RMS threshold for speech detection
  silence_duration: 3.0         # Seconds of silence before auto-stop

Use /voice on in the CLI to enable microphone mode, record_key to start/stop recording, and /voice tts to toggle spoken replies. See Voice Mode for end-to-end setup and platform-specific behavior.

Streaming

Stream tokens to the terminal or messaging platforms as they arrive, instead of waiting for the full response.

CLI Streaming

display:
  streaming: true         # Stream tokens to terminal in real-time
  show_reasoning: true    # Also stream reasoning/thinking tokens (optional)

When enabled, responses appear token-by-token inside a streaming box. Tool calls are still captured silently. If the provider doesn’t support streaming, it falls back to the normal display automatically.

Gateway Streaming (Telegram, Discord, Slack)

streaming:
  enabled: true           # Enable progressive message editing
  transport: edit         # "edit" (progressive message editing) or "off"
  edit_interval: 0.3      # Seconds between message edits
  buffer_threshold: 40    # Characters before forcing an edit flush
  cursor: " ▉"            # Cursor shown during streaming

When enabled, the bot sends a message on the first token, then progressively edits it as more tokens arrive. Platforms that don’t support message editing (Signal, Email, Home Assistant) are auto-detected on the first attempt — streaming is gracefully disabled for that session with no flood of messages.

For separate natural mid-turn assistant updates without progressive token editing, set display.interim_assistant_messages: true.

Overflow handling: If the streamed text exceeds the platform’s message length limit (~4096 chars), the current message is finalized and a new one starts automatically.

::note Streaming is disabled by default. Enable it in ~/.hermes/config.yaml to try the streaming UX.

::

Group Chat Session Isolation

Control whether shared chats keep one conversation per room or one conversation per participant:

group_sessions_per_user: true  # true = per-user isolation in groups/channels, false = one shared session per chat

• true is the default and recommended setting. In Discord channels, Telegram groups, Slack channels, and similar shared contexts, each sender gets their own session when the platform provides a user ID.
• false reverts to the old shared-room behavior. That can be useful if you explicitly want Hermes to treat a channel like one collaborative conversation, but it also means users share context, token costs, and interrupt state.
• Direct messages are unaffected. Hermes still keys DMs by chat/DM ID as usual.
• Threads stay isolated from their parent channel either way; with true, each participant also gets their own session inside the thread.

For the behavior details and examples, see Sessions and the Discord guide.

Unauthorized DM Behavior

Control what Hermes does when an unknown user sends a direct message:

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore

• pair is the default. Hermes denies access, but replies with a one-time pairing code in DMs.
• ignore silently drops unauthorized DMs.
• Platform sections override the global default, so you can keep pairing enabled broadly while making one platform quieter.

Quick Commands

Define custom commands that run shell commands without invoking the LLM — zero token usage, instant execution. Especially useful from messaging platforms (Telegram, Discord, etc.) for quick server checks or utility scripts.

quick_commands:
  status:
    type: exec
    command: systemctl status hermes-agent
  disk:
    type: exec
    command: df -h /
  update:
    type: exec
    command: cd ~/.hermes/hermes-agent && git pull && pip install -e .
  gpu:
    type: exec
    command: nvidia-smi --query-gpu=name,utilization.gpu,memory.used,memory.total --format=csv,noheader

Usage: type /status, /disk, /update, or /gpu in the CLI or any messaging platform. The command runs locally on the host and returns the output directly — no LLM call, no tokens consumed.

• 30-second timeout — long-running commands are killed with an error message
• Priority — quick commands are checked before skill commands, so you can override skill names
• Autocomplete — quick commands are resolved at dispatch time and are not shown in the built-in slash-command autocomplete tables
• Type — only exec is supported (runs a shell command); other types show an error
• Works everywhere — CLI, Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant

Human Delay

Simulate human-like response pacing in messaging platforms:

human_delay:
  mode: "off"                  # off | natural | custom
  min_ms: 800                  # Minimum delay (custom mode)
  max_ms: 2500                 # Maximum delay (custom mode)

Code Execution

Configure the sandboxed Python code execution tool:

code_execution:
  timeout: 300                 # Max execution time in seconds
  max_tool_calls: 50           # Max tool calls within code execution

Web Search Backends

The web_search, web_extract, and web_crawl tools support four backend providers. Configure the backend in config.yaml or via hermes tools:

web:
  backend: firecrawl    # firecrawl | parallel | tavily | exa

Backend selection: If web.backend is not set, the backend is auto-detected from available API keys. If only EXA_API_KEY is set, Exa is used. If only TAVILY_API_KEY is set, Tavily is used. If only PARALLEL_API_KEY is set, Parallel is used. Otherwise Firecrawl is the default.

Self-hosted Firecrawl: Set FIRECRAWL_API_URL to point at your own instance. When a custom URL is set, the API key becomes optional (set USE_DB_AUTHENTICATION=false on the server to disable auth).

Parallel search modes: Set PARALLEL_SEARCH_MODE to control search behavior — fast, one-shot, or agentic (default: agentic).

Browser

Configure browser automation behavior:

browser:
  inactivity_timeout: 120        # Seconds before auto-closing idle sessions
  command_timeout: 30             # Timeout in seconds for browser commands (screenshot, navigate, etc.)
  record_sessions: false         # Auto-record browser sessions as WebM videos to ~/.hermes/browser_recordings/
  camofox:
    managed_persistence: false   # When true, Camofox sessions persist cookies/logins across restarts

The browser toolset supports multiple providers. See the Browser feature page for details on Browserbase, Browser Use, and local Chrome CDP setup.

Timezone

Override the server-local timezone with an IANA timezone string. Affects timestamps in logs, cron scheduling, and system prompt time injection.

timezone: "America/New_York"   # IANA timezone (default: "" = server-local time)

Supported values: any IANA timezone identifier (e.g. America/New_York, Europe/London, Asia/Kolkata, UTC). Leave empty or omit for server-local time.

Discord

Configure Discord-specific behavior for the messaging gateway:

discord:
  require_mention: true          # Require @mention to respond in server channels
  free_response_channels: ""     # Comma-separated channel IDs where bot responds without @mention
  auto_thread: true              # Auto-create threads on @mention in channels

• require_mention — when true (default), the bot only responds in server channels when mentioned with @BotName. DMs always work without mention.
• free_response_channels — comma-separated list of channel IDs where the bot responds to every message without requiring a mention.
• auto_thread — when true (default), mentions in channels automatically create a thread for the conversation, keeping channels clean (similar to Slack threading).

Security

Pre-execution security scanning and secret redaction:

security:
  redact_secrets: true           # Redact API key patterns in tool output and logs
  tirith_enabled: true           # Enable Tirith security scanning for terminal commands
  tirith_path: "tirith"          # Path to tirith binary (default: "tirith" in $PATH)
  tirith_timeout: 5              # Seconds to wait for tirith scan before timing out
  tirith_fail_open: true         # Allow command execution if tirith is unavailable
  website_blocklist:             # See Website Blocklist section below
    enabled: false
    domains: []
    shared_files: []

• redact_secrets — automatically detects and redacts patterns that look like API keys, tokens, and passwords in tool output before it enters the conversation context and logs.
• tirith_enabled — when true, terminal commands are scanned by Tirith before execution to detect potentially dangerous operations.
• tirith_path — path to the tirith binary. Set this if tirith is installed in a non-standard location.
• tirith_timeout — maximum seconds to wait for a tirith scan. Commands proceed if the scan times out.
• tirith_fail_open — when true (default), commands are allowed to execute if tirith is unavailable or fails. Set to false to block commands when tirith cannot verify them.

Website Blocklist

Block specific domains from being accessed by the agent’s web and browser tools:

security:
  website_blocklist:
    enabled: false               # Enable URL blocking (default: false)
    domains:                     # List of blocked domain patterns
      - "*.internal.company.com"
      - "admin.example.com"
      - "*.local"
    shared_files:                # Load additional rules from external files
      - "/etc/hermes/blocked-sites.txt"

When enabled, any URL matching a blocked domain pattern is rejected before the web or browser tool executes. This applies to web_search, web_extract, browser_navigate, and any tool that accesses URLs.

Domain rules support:

• Exact domains: admin.example.com
• Wildcard subdomains: *.internal.company.com (blocks all subdomains)
• TLD wildcards: *.local

Shared files contain one domain rule per line (blank lines and # comments are ignored). Missing or unreadable files log a warning but don’t disable other web tools.

The policy is cached for 30 seconds, so config changes take effect quickly without restart.

Smart Approvals

Control how Hermes handles potentially dangerous commands:

approvals:
  mode: manual   # manual | smart | off

Smart mode is particularly useful for reducing approval fatigue — it lets the agent work more autonomously on safe operations while still catching genuinely destructive commands.

::warning Setting approvals.mode: off disables all safety checks for terminal commands. Only use this in trusted, sandboxed environments.

::

Checkpoints

Automatic filesystem snapshots before destructive file operations. See the Checkpoints & Rollback for details.

checkpoints:
  enabled: true                  # Enable automatic checkpoints (also: hermes --checkpoints)
  max_snapshots: 50              # Max checkpoints to keep per directory

Delegation

Configure subagent behavior for the delegate tool:

delegation:
  # model: "google/gemini-3-flash-preview"  # Override model (empty = inherit parent)
  # provider: "openrouter"                  # Override provider (empty = inherit parent)
  # base_url: "http://localhost:1234/v1"    # Direct OpenAI-compatible endpoint (takes precedence over provider)
  # api_key: "local-key"                    # API key for base_url (falls back to OPENAI_API_KEY)

Subagent provider:model override: By default, subagents inherit the parent agent’s provider and model. Set delegation.provider and delegation.model to route subagents to a different provider:model pair — e.g., use a cheap/fast model for narrowly-scoped subtasks while your primary agent runs an expensive reasoning model.

Direct endpoint override: If you want the obvious custom-endpoint path, set delegation.base_url, delegation.api_key, and delegation.model. That sends subagents directly to that OpenAI-compatible endpoint and takes precedence over delegation.provider. If delegation.api_key is omitted, Hermes falls back to OPENAI_API_KEY only.

The delegation provider uses the same credential resolution as CLI/gateway startup. All configured providers are supported: openrouter, nous, copilot, zai, kimi-coding, minimax, minimax-cn. When a provider is set, the system automatically resolves the correct base URL, API key, and API mode — no manual credential wiring needed.

Precedence: delegation.base_url in config → delegation.provider in config → parent provider (inherited). delegation.model in config → parent model (inherited). Setting just model without provider changes only the model name while keeping the parent’s credentials (useful for switching models within the same provider like OpenRouter).

Clarify

Configure the clarification prompt behavior:

clarify:
  timeout: 120                 # Seconds to wait for user clarification response

Context Files (SOUL.md, AGENTS.md)

Hermes uses two different context scopes:

• SOUL.md is the agent’s primary identity. It occupies slot #1 in the system prompt, completely replacing the built-in default identity. Edit it to fully customize who the agent is.
• If SOUL.md is missing, empty, or cannot be loaded, Hermes falls back to a built-in default identity.
• Project context files use a priority system — only ONE type is loaded (first match wins): .hermes.md → AGENTS.md → CLAUDE.md → .cursorrules. SOUL.md is always loaded independently.
• AGENTS.md is hierarchical: if subdirectories also have AGENTS.md, all are combined.
• Hermes automatically seeds a default SOUL.md if one does not already exist.
• All loaded context files are capped at 20,000 characters with smart truncation.

See also:

• Personality & SOUL.md
• Context Files

Working Directory

Override the working directory:

# In ~/.hermes/.env or ~/.hermes/config.yaml:
MESSAGING_CWD=/home/myuser/projects    # Gateway sessions
TERMINAL_CWD=/workspace                # All terminal sessions

Docker

sidebar_position: 7 title: “Docker” description: “Running Hermes Agent in Docker and using Docker as a terminal backend”

Hermes Agent — Docker

There are two distinct ways Docker intersects with Hermes Agent:

1. Running Hermes IN Docker — the agent itself runs inside a container (this page’s primary focus)
2. Docker as a terminal backend — the agent runs on your host but executes commands inside a Docker sandbox (see Configuration → terminal.backend)

This page covers option 1. The container stores all user data (config, API keys, sessions, skills, memories) in a single directory mounted from the host at /opt/data. The image itself is stateless and can be upgraded by pulling a new version without losing any configuration.

Quick start

If this is your first time running Hermes Agent, create a data directory on the host and start the container interactively to run the setup wizard:

mkdir -p ~/.hermes
docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent setup

This drops you into the setup wizard, which will prompt you for your API keys and write them to ~/.hermes/.env. You only need to do this once. It is highly recommended to set up a chat system for the gateway to work with at this point.

Running in gateway mode

Once configured, run the container in the background as a persistent gateway (Telegram, Discord, Slack, WhatsApp, etc.):

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

Running interactively (CLI chat)

To open an interactive chat session against a running data directory:

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent

Persistent volumes

The /opt/data volume is the single source of truth for all Hermes state. It maps to your host’s ~/.hermes/ directory and contains:

:::warning Never run two Hermes containers against the same data directory simultaneously — session files and memory stores are not designed for concurrent access.

::

Environment variable forwarding

API keys are read from /opt/data/.env inside the container. You can also pass environment variables directly:

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  -e ANTHROPIC_API_KEY="sk-ant-..." \
  -e OPENAI_API_KEY="sk-..." \
  nousresearch/hermes-agent

Direct -e flags override values from .env. This is useful for CI/CD or secrets-manager integrations where you don’t want keys on disk.

Docker Compose example

For persistent gateway deployment, a docker-compose.yaml is convenient:

version: "3.8"
services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    volumes:
      - ~/.hermes:/opt/data
    # Uncomment to forward specific env vars instead of using .env file:
    # environment:
    #   - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    #   - OPENAI_API_KEY=${OPENAI_API_KEY}
    #   - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: "2.0"

Start with docker compose up -d and view logs with docker compose logs -f hermes.

Resource limits

The Hermes container needs moderate resources. Recommended minimums:

Browser automation (Playwright/Chromium) is the most memory-hungry feature. If you don’t need browser tools, 1 GB is sufficient. With browser tools active, allocate at least 2 GB.

Set limits in Docker:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  --memory=4g --cpus=2 \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent gateway run

What the Dockerfile does

The official image is based on debian:13.4 and includes:

• Python 3 with all Hermes dependencies (pip install -e ".[all]")
• Node.js + npm (for browser automation and WhatsApp bridge)
• Playwright with Chromium (npx playwright install --with-deps chromium)
• ripgrep and ffmpeg as system utilities
• The WhatsApp bridge (scripts/whatsapp-bridge/)

The entrypoint script (docker/entrypoint.sh) bootstraps the data volume on first run:

• Creates the directory structure (sessions/, memories/, skills/, etc.)
• Copies .env.example → .env if no .env exists
• Copies default config.yaml if missing
• Copies default SOUL.md if missing
• Syncs bundled skills using a manifest-based approach (preserves user edits)
• Then runs hermes with whatever arguments you pass

Upgrading

Pull the latest image and recreate the container. Your data directory is untouched.

docker pull nousresearch/hermes-agent:latest
docker rm -f hermes
docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent gateway run

Or with Docker Compose:

docker compose pull
docker compose up -d

Skills and credential files

When using Docker as the execution environment (not the methods above, but when the agent runs commands inside a Docker sandbox), Hermes automatically bind-mounts the skills directory (~/.hermes/skills/) and any credential files declared by skills into the container as read-only volumes. This means skill scripts, templates, and references are available inside the sandbox without manual configuration.

The same syncing happens for SSH and Modal backends — skills and credential files are uploaded via rsync or the Modal mount API before each command.

Troubleshooting

Container exits immediately

Check logs: docker logs hermes. Common causes:

• Missing or invalid .env file — run interactively first to complete setup
• Port conflicts if running with exposed ports

“Permission denied” errors

The container runs as root by default. If your host ~/.hermes/ was created by a non-root user, permissions should work. If you get errors, ensure the data directory is writable:

chmod -R 755 ~/.hermes

Browser tools not working

Playwright needs shared memory. Add --shm-size=1g to your Docker run command:

docker run -d \
  --name hermes \
  --shm-size=1g \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent gateway run

Gateway not reconnecting after network issues

The --restart unless-stopped flag handles most transient failures. If the gateway is stuck, restart the container:

docker restart hermes

Checking container health

docker logs --tail 50 hermes          # Recent logs
docker exec hermes hermes version     # Verify version
docker stats hermes                    # Resource usage

CLI Interface

sidebar_position: 1 title: “CLI Interface” description: “Master the Hermes Agent terminal interface — commands, keybindings, personalities, and more”

CLI Interface

Hermes Agent’s CLI is a full terminal user interface (TUI) — not a web UI. It features multiline editing, slash-command autocomplete, conversation history, interrupt-and-redirect, and streaming tool output. Built for people who live in the terminal.

Running the CLI

# Start an interactive session (default)
hermes

# Single query mode (non-interactive)
hermes chat -q "Hello"

# With a specific model
hermes chat --model "anthropic/claude-sonnet-4"

# With a specific provider
hermes chat --provider nous        # Use Nous Portal
hermes chat --provider openrouter  # Force OpenRouter

# With specific toolsets
hermes chat --toolsets "web,terminal,skills"

# Start with one or more skills preloaded
hermes -s hermes-agent-dev,github-auth
hermes chat -s github-pr-workflow -q "open a draft PR"

# Resume previous sessions
hermes --continue             # Resume the most recent CLI session (-c)
hermes --resume <session_id>  # Resume a specific session by ID (-r)

# Verbose mode (debug output)
hermes chat --verbose

# Isolated git worktree (for running multiple agents in parallel)
hermes -w                         # Interactive mode in worktree
hermes -w -q "Fix issue #123"     # Single query in worktree

Interface Layout

The Hermes CLI banner, conversation stream, and fixed input prompt rendered as a stable docs figure instead of fragile text art.

The welcome banner shows your model, terminal backend, working directory, available tools, and installed skills at a glance.

Status Bar

A persistent status bar sits above the input area, updating in real time:

 ⚕ claude-sonnet-4-20250514 │ 12.4K/200K │ [██████░░░░] 6% │ $0.06 │ 15m

The bar adapts to terminal width — full layout at ≥ 76 columns, compact at 52–75, minimal (model + duration only) below 52.

Context color coding:

Use /usage for a detailed breakdown including per-category costs (input vs output tokens).

Session Resume Display

When resuming a previous session (hermes -c or hermes --resume <id>), a “Previous Conversation” panel appears between the banner and the input prompt, showing a compact recap of the conversation history. See Sessions — Conversation Recap on Resume for details and configuration.

Keybindings

Slash Commands

Type / to see the autocomplete dropdown. Hermes supports a large set of CLI slash commands, dynamic skill commands, and user-defined quick commands.

Common examples:

For the full built-in CLI and messaging lists, see Slash Commands Reference.

For setup, providers, silence tuning, and messaging/Discord voice usage, see Voice Mode.

::tip Commands are case-insensitive — /HELP works the same as /help. Installed skills also become slash commands automatically.

::

Quick Commands

You can define custom commands that run shell commands instantly without invoking the LLM. These work in both the CLI and messaging platforms (Telegram, Discord, etc.).

# ~/.hermes/config.yaml
quick_commands:
  status:
    type: exec
    command: systemctl status hermes-agent
  gpu:
    type: exec
    command: nvidia-smi --query-gpu=utilization.gpu,memory.used --format=csv,noheader

Then type /status or /gpu in any chat. See the Configuration guide for more examples.

Preloading Skills at Launch

If you already know which skills you want active for the session, pass them at launch time:

hermes -s hermes-agent-dev,github-auth
hermes chat -s github-pr-workflow -s github-auth

Hermes loads each named skill into the session prompt before the first turn. The same flag works in interactive mode and single-query mode.

Skill Slash Commands

Every installed skill in ~/.hermes/skills/ is automatically registered as a slash command. The skill name becomes the command:

/gif-search funny cats
/axolotl help me fine-tune Llama 3 on my dataset
/github-pr-workflow create a PR for the auth refactor

# Just the skill name loads it and lets the agent ask what you need:
/excalidraw

Personalities

Set a predefined personality to change the agent’s tone:

/personality pirate
/personality kawaii
/personality concise

Built-in personalities include: helpful, concise, technical, creative, teacher, kawaii, catgirl, pirate, shakespeare, surfer, noir, uwu, philosopher, hype.

You can also define custom personalities in ~/.hermes/config.yaml:

personalities:
  helpful: "You are a helpful, friendly AI assistant."
  kawaii: "You are a kawaii assistant! Use cute expressions..."
  pirate: "Arrr! Ye be talkin' to Captain Hermes..."
  # Add your own!

Multi-line Input

There are two ways to enter multi-line messages:

1. Alt+Enter or Ctrl+J — inserts a new line
2. Backslash continuation — end a line with \ to continue:

❯ Write a function that:\
  1. Takes a list of numbers\
  2. Returns the sum

:::info Pasting multi-line text is supported — use Alt+Enter or Ctrl+J to insert newlines, or simply paste content directly.

::

Interrupting the Agent

You can interrupt the agent at any point:

• Type a new message + Enter while the agent is working — it interrupts and processes your new instructions
• Ctrl+C — interrupt the current operation (press twice within 2s to force exit)
• In-progress terminal commands are killed immediately (SIGTERM, then SIGKILL after 1s)
• Multiple messages typed during interrupt are combined into one prompt

Busy Input Mode

The display.busy_input_mode config key controls what happens when you press Enter while the agent is working:

# ~/.hermes/config.yaml
display:
  busy_input_mode: "queue"   # or "interrupt" (default)

Queue mode is useful when you want to prepare follow-up messages without accidentally canceling in-flight work. Unknown values fall back to "interrupt".

Suspending to Background

On Unix systems, press Ctrl+Z to suspend Hermes to the background — just like any terminal process. The shell prints a confirmation:

Hermes Agent has been suspended. Run `fg` to bring Hermes Agent back.

Type fg in your shell to resume the session exactly where you left off. This is not supported on Windows.

Tool Progress Display

The CLI shows animated feedback as the agent works:

Thinking animation (during API calls):

  ◜ (｡•́︿•̀｡) pondering... (1.2s)
  ◠ (⊙_⊙) contemplating... (2.4s)
  ✧٩(ˊᗜˋ*)و✧ got it! (3.1s)

Tool execution feed:

  ┊ 💻 terminal `ls -la` (0.3s)
  ┊ 🔍 web_search (1.2s)
  ┊ 📄 web_extract (2.1s)

Cycle through display modes with /verbose: off → new → all → verbose. This command can also be enabled for messaging platforms — see configuration.

Tool Preview Length

The display.tool_preview_length config key controls the maximum number of characters shown in tool call preview lines (e.g. file paths, terminal commands). The default is 0, which means no limit — full paths and commands are shown.

# ~/.hermes/config.yaml
display:
  tool_preview_length: 80   # Truncate tool previews to 80 chars (0 = no limit)

This is useful on narrow terminals or when tool arguments contain very long file paths.

Session Management

Resuming Sessions

When you exit a CLI session, a resume command is printed:

Resume this session with:
  hermes --resume 20260225_143052_a1b2c3

Session:        20260225_143052_a1b2c3
Duration:       12m 34s
Messages:       28 (5 user, 18 tool calls)

Resume options:

hermes --continue                          # Resume the most recent CLI session
hermes -c                                  # Short form
hermes -c "my project"                     # Resume a named session (latest in lineage)
hermes --resume 20260225_143052_a1b2c3     # Resume a specific session by ID
hermes --resume "refactoring auth"         # Resume by title
hermes -r 20260225_143052_a1b2c3           # Short form

Resuming restores the full conversation history from SQLite. The agent sees all previous messages, tool calls, and responses — just as if you never left.

Use /title My Session Name inside a chat to name the current session, or hermes sessions rename <id> <title> from the command line. Use hermes sessions list to browse past sessions.

Session Storage

CLI sessions are stored in Hermes’s SQLite state database under ~/.hermes/state.db. The database keeps:

• session metadata (ID, title, timestamps, token counters)
• message history
• lineage across compressed/resumed sessions
• full-text search indexes used by session_search

Some messaging adapters also keep per-platform transcript files alongside the database, but the CLI itself resumes from the SQLite session store.

Context Compression

Long conversations are automatically summarized when approaching context limits:

# In ~/.hermes/config.yaml
compression:
  enabled: true
  threshold: 0.50    # Compress at 50% of context limit by default
  summary_model: "google/gemini-3-flash-preview"  # Model used for summarization

When compression triggers, middle turns are summarized while the first 3 and last 4 turns are always preserved.

Background Sessions

Run a prompt in a separate background session while continuing to use the CLI for other work:

/background Analyze the logs in /var/log and summarize any errors from today

Hermes immediately confirms the task and gives you back the prompt:

🔄 Background task #1 started: "Analyze the logs in /var/log and summarize..."
   Task ID: bg_143022_a1b2c3

How It Works

Each /background prompt spawns a completely separate agent session in a daemon thread:

• Isolated conversation — the background agent has no knowledge of your current session’s history. It receives only the prompt you provide.
• Same configuration — the background agent inherits your model, provider, toolsets, reasoning settings, and fallback model from the current session.
• Non-blocking — your foreground session stays fully interactive. You can chat, run commands, or even start more background tasks.
• Multiple tasks — you can run several background tasks simultaneously. Each gets a numbered ID.

Results

When a background task finishes, the result appears as a panel in your terminal:

╭─ ⚕ Hermes (background #1) ──────────────────────────────────╮
│ Found 3 errors in syslog from today:                         │
│ 1. OOM killer invoked at 03:22 — killed process nginx        │
│ 2. Disk I/O error on /dev/sda1 at 07:15                      │
│ 3. Failed SSH login attempts from 192.168.1.50 at 14:30      │
╰──────────────────────────────────────────────────────────────╯

If the task fails, you’ll see an error notification instead. If display.bell_on_complete is enabled in your config, the terminal bell rings when the task finishes.

Use Cases

• Long-running research — “/background research the latest developments in quantum error correction” while you work on code
• File processing — “/background analyze all Python files in this repo and list any security issues” while you continue a conversation
• Parallel investigations — start multiple background tasks to explore different angles simultaneously

:::info Background sessions do not appear in your main conversation history. They are standalone sessions with their own task ID (e.g., bg_143022_a1b2c3).

::

Quiet Mode

By default, the CLI runs in quiet mode which:

• Suppresses verbose logging from tools
• Enables kawaii-style animated feedback
• Keeps output clean and user-friendly

For debug output:

hermes chat --verbose

Sessions

sidebar_position: 7 title: “Sessions” description: “Session persistence, resume, search, management, and per-platform session tracking”

Sessions

Hermes Agent automatically saves every conversation as a session. Sessions enable conversation resume, cross-session search, and full conversation history management.

How Sessions Work

Every conversation — whether from the CLI, Telegram, Discord, Slack, WhatsApp, Signal, Matrix, or any other messaging platform — is stored as a session with full message history. Sessions are tracked in two complementary systems:

1. SQLite database (~/.hermes/state.db) — structured session metadata with FTS5 full-text search
2. JSONL transcripts (~/.hermes/sessions/) — raw conversation transcripts including tool calls (gateway)

The SQLite database stores:

• Session ID, source platform, user ID
• Session title (unique, human-readable name)
• Model name and configuration
• System prompt snapshot
• Full message history (role, content, tool calls, tool results)
• Token counts (input/output)
• Timestamps (started_at, ended_at)
• Parent session ID (for compression-triggered session splitting)

Session Sources

Each session is tagged with its source platform:

CLI Session Resume

Resume previous conversations from the CLI using --continue or --resume:

Continue Last Session

# Resume the most recent CLI session
hermes --continue
hermes -c

# Or with the chat subcommand
hermes chat --continue
hermes chat -c

This looks up the most recent cli session from the SQLite database and loads its full conversation history.

Resume by Name

If you’ve given a session a title (see Session Naming below), you can resume it by name:

# Resume a named session
hermes -c "my project"

# If there are lineage variants (my project, my project #2, my project #3),
# this automatically resumes the most recent one
hermes -c "my project"   # → resumes "my project #3"

Resume Specific Session

# Resume a specific session by ID
hermes --resume 20250305_091523_a1b2c3d4
hermes -r 20250305_091523_a1b2c3d4

# Resume by title
hermes --resume "refactoring auth"

# Or with the chat subcommand
hermes chat --resume 20250305_091523_a1b2c3d4

Session IDs are shown when you exit a CLI session, and can be found with hermes sessions list.

Conversation Recap on Resume

When you resume a session, Hermes displays a compact recap of the previous conversation in a styled panel before the input prompt:

Resume mode shows a compact recap panel with recent user and assistant turns before returning you to the live prompt.

The recap:

• Shows user messages (gold ●) and assistant responses (green ◆)
• Truncates long messages (300 chars for user, 200 chars / 3 lines for assistant)
• Collapses tool calls to a count with tool names (e.g., [3 tool calls: terminal, web_search])
• Hides system messages, tool results, and internal reasoning
• Caps at the last 10 exchanges with a “… N earlier messages …” indicator
• Uses dim styling to distinguish from the active conversation

To disable the recap and keep the minimal one-liner behavior, set in ~/.hermes/config.yaml:

display:
  resume_display: minimal   # default: full

:::tip Session IDs follow the format YYYYMMDD_HHMMSS_<8-char-hex>, e.g. 20250305_091523_a1b2c3d4. You can resume by ID or by title — both work with -c and -r.

::

Session Naming

Give sessions human-readable titles so you can find and resume them easily.

Auto-Generated Titles

Hermes automatically generates a short descriptive title (3–7 words) for each session after the first exchange. This runs in a background thread using a fast auxiliary model, so it adds no latency. You’ll see auto-generated titles when browsing sessions with hermes sessions list or hermes sessions browse.

Auto-titling only fires once per session and is skipped if you’ve already set a title manually.

Setting a Title Manually

Use the /title slash command inside any chat session (CLI or gateway):

/title my research project

The title is applied immediately. If the session hasn’t been created in the database yet (e.g., you run /title before sending your first message), it’s queued and applied once the session starts.

You can also rename existing sessions from the command line:

hermes sessions rename 20250305_091523_a1b2c3d4 "refactoring auth module"

Title Rules

• Unique — no two sessions can share the same title
• Max 100 characters — keeps listing output clean
• Sanitized — control characters, zero-width chars, and RTL overrides are stripped automatically
• Normal Unicode is fine — emoji, CJK, accented characters all work

Auto-Lineage on Compression

When a session’s context is compressed (manually via /compress or automatically), Hermes creates a new continuation session. If the original had a title, the new session automatically gets a numbered title:

"my project" → "my project #2" → "my project #3"

When you resume by name (hermes -c "my project"), it automatically picks the most recent session in the lineage.

/title in Messaging Platforms

The /title command works in all gateway platforms (Telegram, Discord, Slack, WhatsApp):

• /title My Research — set the session title
• /title — show the current title

Session Management Commands

Hermes provides a full set of session management commands via hermes sessions:

List Sessions

# List recent sessions (default: last 20)
hermes sessions list

# Filter by platform
hermes sessions list --source telegram

# Show more sessions
hermes sessions list --limit 50

When sessions have titles, the output shows titles, previews, and relative timestamps:

Title                  Preview                                  Last Active   ID
────────────────────────────────────────────────────────────────────────────────────────────────
refactoring auth       Help me refactor the auth module please   2h ago        20250305_091523_a
my project #3          Can you check the test failures?          yesterday     20250304_143022_e
—                      What's the weather in Las Vegas?          3d ago        20250303_101500_f

When no sessions have titles, a simpler format is used:

Preview                                            Last Active   Src    ID
──────────────────────────────────────────────────────────────────────────────────────
Help me refactor the auth module please             2h ago        cli    20250305_091523_a
What's the weather in Las Vegas?                    3d ago        tele   20250303_101500_f

Export Sessions

# Export all sessions to a JSONL file
hermes sessions export backup.jsonl

# Export sessions from a specific platform
hermes sessions export telegram-history.jsonl --source telegram

# Export a single session
hermes sessions export session.jsonl --session-id 20250305_091523_a1b2c3d4

Exported files contain one JSON object per line with full session metadata and all messages.

Delete a Session

# Delete a specific session (with confirmation)
hermes sessions delete 20250305_091523_a1b2c3d4

# Delete without confirmation
hermes sessions delete 20250305_091523_a1b2c3d4 --yes

Rename a Session

# Set or change a session's title
hermes sessions rename 20250305_091523_a1b2c3d4 "debugging auth flow"

# Multi-word titles don't need quotes in the CLI
hermes sessions rename 20250305_091523_a1b2c3d4 debugging auth flow

If the title is already in use by another session, an error is shown.

Prune Old Sessions

# Delete ended sessions older than 90 days (default)
hermes sessions prune

# Custom age threshold
hermes sessions prune --older-than 30

# Only prune sessions from a specific platform
hermes sessions prune --source telegram --older-than 60

# Skip confirmation
hermes sessions prune --older-than 30 --yes

:::info Pruning only deletes ended sessions (sessions that have been explicitly ended or auto-reset). Active sessions are never pruned.

::

Session Statistics

hermes sessions stats

Output:

Total sessions: 142
Total messages: 3847
  cli: 89 sessions
  telegram: 38 sessions
  discord: 15 sessions
Database size: 12.4 MB

For deeper analytics — token usage, cost estimates, tool breakdown, and activity patterns — use hermes insights.

Session Search Tool

The agent has a built-in session_search tool that performs full-text search across all past conversations using SQLite’s FTS5 engine.

How It Works

1. FTS5 searches matching messages ranked by relevance
2. Groups results by session, takes the top N unique sessions (default 3)
3. Loads each session’s conversation, truncates to ~100K chars centered on matches
4. Sends to a fast summarization model for focused summaries
5. Returns per-session summaries with metadata and surrounding context

FTS5 Query Syntax

The search supports standard FTS5 query syntax:

• Simple keywords: docker deployment
• Phrases: "exact phrase"
• Boolean: docker OR kubernetes, python NOT java
• Prefix: deploy*

When It’s Used

The agent is prompted to use session search automatically:

“When the user references something from a past conversation or you suspect relevant prior context exists, use session_search to recall it before asking them to repeat themselves.”

Per-Platform Session Tracking

Gateway Sessions

On messaging platforms, sessions are keyed by a deterministic session key built from the message source:

When Hermes cannot get a participant identifier for a shared chat, it falls back to one shared session for that room.

Shared vs Isolated Group Sessions

By default, Hermes uses group_sessions_per_user: true in config.yaml. That means:

• Alice and Bob can both talk to Hermes in the same Discord channel without sharing transcript history
• one user’s long tool-heavy task does not pollute another user’s context window
• interrupt handling also stays per-user because the running-agent key matches the isolated session key

If you want one shared “room brain” instead, set:

group_sessions_per_user: false

That reverts groups/channels to a single shared session per room, which preserves shared conversational context but also shares token costs, interrupt state, and context growth.

Session Reset Policies

Gateway sessions are automatically reset based on configurable policies:

• idle — reset after N minutes of inactivity
• daily — reset at a specific hour each day
• both — reset on whichever comes first (idle or daily)
• none — never auto-reset

Before a session is auto-reset, the agent is given a turn to save any important memories or skills from the conversation.

Sessions with active background processes are never auto-reset, regardless of policy.

Storage Locations