# Hermes Agent Docker

> 仓库地址：https://github.com/xmbshwll/hermes-agent-docker
> 作者/组织：xmbshwll
> 成熟度：beta
> 分析日期：2026-04-15

## 一句话总结
一个最小化的 Hermes Agent Docker 容器化方案，使用官方安装脚本构建镜像，集成 mini-swe-agent，支持持久化状态管理。

## 项目定位与架构
hermes-agent-docker 提供了 Hermes Agent 最直接的 Docker 化方案——不添加额外服务，不做复杂编排，专注于容器隔离和状态持久化。

架构简洁：应用代码运行在容器的 `/home/agent/workspace`，配置和 session 数据持久化在 `/home/agent/.hermes`。首次启动时，若持久化目录为空，容器会从镜像预置的 Hermes 默认配置 seed 该目录。集成 mini-swe-agent 提供软件工程能力。

构建通过 `docker build` 完成，支持 `HERMES_REF` build argument 指定版本（默认 `main`，接受分支或 tag）。

## 关键技术特性
- **官方安装脚本**：使用 upstream install script 确保与官方一致
- **状态持久化**：mount `/home/agent/.hermes` volume 保留跨 session 数据
- **首次启动 seeding**：空目录自动从镜像默认配置初始化
- **版本控制**：`HERMES_REF` 参数支持指定分支或 tag
- **集成 mini-swe-agent**：开箱即用的软件工程工具链
- **诊断工具**：`hermes doctor` 命令用于故障排查

## 设计亮点与创新
"首次启动 seeding"机制解决了一个常见的 Docker 化问题——既需要 volume mount 持久化状态，又需要首次运行时有合理的默认配置。通过从镜像 seed 空目录，避免了用户手动初始化的步骤。

## 局限性与风险
功能极简——不含 reverse proxy、TLS、monitoring 等生产级组件。不 mount `/home/agent/.hermes` 时状态随容器销毁丢失。首次使用需要 `hermes setup` 或手动配置。无多架构预构建镜像（需本地 build）。

## 与生态系统的关联
是 Docker 化部署的最小基础方案。与 evey-setup（全栈）和 portainer-stack-hermes（Portainer 集成）相比，hermes-agent-docker 更适合需要自定义编排的高级用户。可作为更复杂部署方案的 base image。