docker compose是快速部署hermes agent的首选方式，支持基础单节点、生产持久化、web ui集成、apple silicon适配及极空间nas专用等五种配置方案。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您需要在服务器或本地环境中快速部署 Hermes Agent，并希望借助声明式配置实现服务编排与环境一致性，则 Docker Compose 是首选方式。以下是多种可直接使用的 docker-compose.yml 编写方案，适配不同部署需求与运行约束。
一、基础单节点部署（推荐入门）
该配置适用于开发测试或轻量级生产场景，仅依赖官方镜像与最小化挂载，无需构建过程，启动即用。
1、创建 docker-compose.yml 文件，内容如下：
2、确保当前目录下存在 .env 文件，其中包含 HERMES_API_KEY 和 HERMES_MODEL_PROVIDER 变量定义。
3、执行 docker-compose up -d 启动服务。
4、访问 http://localhost:3000 验证 Web UI 是否响应。
二、带持久化数据卷的生产就绪配置
该配置显式声明命名卷用于隔离 Hermes Agent 的配置、技能与会话状态，避免容器重建导致数据丢失，符合生产环境数据可靠性要求。
1、在 volumes 区块中定义 hermes-data 卷，不使用主机路径绑定。
2、将 /root/.hermes 挂载至该命名卷，确保 skills/、environments/、agent/ 等子目录全部持久化。
3、为容器设置 restart: unless-stopped 与资源限制，防止异常退出或资源耗尽。
4、执行 docker-compose down && docker-compose up -d 以应用新卷策略。
三、集成 Web UI 的双服务组合部署
该配置同时启动 Hermes Agent 核心服务与独立 Web UI 前端，通过 Docker 内部网络通信，避免端口暴露冲突，适合需图形化交互的终端用户。
1、定义 hermes-agent 服务，监听内部端口 3000，不映射至宿主机。
2、定义 hermes-webui 服务，镜像为 ghcr.io/nesquena/hermes-webui:latest，映射宿主机端口 8787。
3、在 hermes-webui 的 environment 中设置 HERMES_AGENT_URL=http://hermes-agent:3000。
4、添加 depends_on 与健康检查，确保 Web UI 在 Agent 就绪后启动。
四、适配 Apple Silicon（M1/M2/M3）的跨架构兼容配置
该配置显式指定平台参数，规避 ARM64 架构下镜像拉取失败或运行时崩溃问题，确保在 macOS 上通过 Docker Desktop 正常运行。
1、在 hermes-agent 服务区块中添加 platform: linux/amd64 或 linux/arm64，根据目标芯片选择。
2、若使用 nousresearch/hermes-agent:latest 镜像，确认其多平台 manifest 已发布；否则改用带架构标签的版本，如 :latest-arm64。
3、禁用 build 指令，全程采用预编译镜像，避免本地构建失败。
4、启动前执行 docker system prune -a 清理旧镜像缓存，防止平台错配残留。
五、极空间 NAS 专用 Compose 配置（含面板支持）
该配置专为极空间设备优化，利用其新版 Docker 应用对 .env 文件与相对路径的支持能力，集成自定义管理面板并复用官方启动逻辑。
1、在 volumes 中挂载 ./panel/hermes-website 与 ./panel/scripts 到容器内对应路径。
2、使用 entrypoint 替代 command，调用自定义 entrypoint.sh 脚本启动面板与 Agent。
3、为面板单独开放端口 33333，与 Agent 的 3000 端口分离，便于权限管控。
4、在极空间 Docker 应用界面中勾选“启用 .env 文件”，并从本地导入已填写 API 密钥的 .env 文件。
