Hermes 引擎容器化

引擎镜像：veyra/veyra-os/engine-hermes:0.19.0-veyra.3（tag 唯一真相为 engines/hermes/VERSION，独立语义化版本 <上游版本>-veyra.<修订号>，不随平台版本号变化）。

容器构建

• 基础镜像: python:3.11-slim（构建期基础镜像经本仓 registry 分发，见 engines/hermes/Dockerfile）
• 运行时: hermes-agent pip 包（vendored wheel，engines/hermes/vendor/）
• 入口: entrypoint.sh — 自动配置 provider、启动 API server

entrypoint.sh 流程

1. 写入 ~/.hermes/.env (API_SERVER_ENABLED, API_SERVER_KEY 等)
2. 如果 PROVIDER_NAME 有值, 写入 ~/.hermes/config.yaml
3. 透传 OPENAI_API_KEY / ANTHROPIC_API_KEY / DEEPSEEK_API_KEY 等变量
4. 如果 HERMES_PROFILE != "default", 创建该 profile
5. 配置模型 provider/default/base_url/api_key
6. 启动: hermes -p <profile> gateway run

注意：不创建 "default" profile（它是 Hermes 内置的，无需创建）。

Provider 配置

引擎 Pod 的模型环境变量由 manager 部署时按实例的模型配置派生（worker/_common.py::build_engine_envs）：Hermes 走平台模型网关，注入 LITELLM_BASE_URL / LITELLM_API_KEY（per-instance key）/ LITELLM_MODEL；未配置模型时引擎启动后无模型可用。入口脚本据此写入引擎自身的 provider 配置。

环境变量

变量	用途	来源
LITELLM_BASE_URL	平台模型网关地址	平台注入
LITELLM_API_KEY	per-instance 模型 Key	平台注入
LITELLM_MODEL	默认模型名	平台注入
HERMES_PROFILE	Profile 名称	默认 "default"
API_SERVER_KEY	引擎 API Key	K8s secret
API_SERVER_ENABLED	启用 API Server	固定 "true"
API_SERVER_HOST	监听地址	固定 "0.0.0.0"
API_SERVER_PORT	监听端口	固定 8642
GATEWAY_ALLOW_ALL_USERS	允许所有用户	固定 "true"

K8sManager 创建 Pod 时的 env 注入

K8sManager 在 create_agent_engine() 中设置的环境变量：

V1EnvVar(name="AGENT_ID", value=agent_id),
V1EnvVar(name="API_SERVER_KEY", value_from=secretRef("api-server-key")),
V1EnvVar(name="API_SERVER_ENABLED", value="true"),
V1EnvVar(name="API_SERVER_HOST", value="0.0.0.0"),
V1EnvVar(name="API_SERVER_PORT", value="8642"),
V1EnvVar(name="GATEWAY_ALLOW_ALL_USERS", value="true"),
# + build_engine_envs() 派生的模型变量（LITELLM_*）与沙箱/多路复用等开关变量

引擎 API

Hermes Agent API Server 暴露 OpenAI 兼容接口：

端点	说明
POST /v1/chat/completions	聊天补全（支持 stream=true SSE）
GET /v1/models	模型列表
GET /health	健康检查

Gateway 集成注意事项

• Gateway 转发请求前必须去掉 Origin 和 Referer 头，否则引擎会返回 403
• 引擎 API 通过 Authorization: Bearer {API_SERVER_KEY} 认证
• 引擎 Pod 命名规范：engine-hermes-{agent_id[:8]}

注意事项

• Hermes Agent 使用 profile 隔离多实例配置
• 本地已安装桌面版 Hermes，所有容器化运行必须在 colima/k3s 中进行

命令沙箱（OpenSandbox）

智能体实例可在表单中启用「命令沙箱」：启用后，hermes terminal 工具的命令不再直接跑在引擎 Pod 内，而是提交到独立的 OpenSandbox 沙箱（K8s 原生沙箱服务）执行。

行为语义

• 粒度：实例内每位终端用户（profile）一个沙箱；同一用户跨会话共享（pip 安装的包、生成的文件延续）
• 生命周期：沙箱跨回合常驻，空闲超过实例配置的时长后自动回收；回收前命令产物自动同步回实例数据卷，跨会话可继续访问
• 文件互通：执行前引擎侧文件（凭据、技能等）自动推送到沙箱；执行产物按需取回 —— 用户视角文件工具与终端命令操作同一份文件
• 隔离边界：沙箱是独立 Pod（数据面 opensandbox ns），与引擎 Pod 资源互不占用；实例之间、用户之间沙箱互相隔离
• 运行镜像：实例可二选一 —— 「Python 3.11（数据与文档）」（平台默认，已预置绘图、PDF、PPT、Word、Excel 相关库与中文字体，无需联网安装）或「Python 3.11 slim」（无预置三方包，体积更小）。镜像留空即用平台默认

配置链路

实例 runtime_config.sandbox 段（enabled / image / cpu_millicores / memory_mb / disk_mb / lifetime_seconds）→ manager 部署时经 sandbox_engine_envs 注入引擎 Pod env（TERMINAL_ENV=opensandbox + OPENSANDBOX_*）→ 引擎镜像内置的 OpenSandbox 后端读取。沙箱 API key 经 veyraos-secret（secretKeyRef）透传，manager 不落库。

沙箱服务本体部署见 deploy/k8s/infra/opensandbox.yaml（部署指南「命令沙箱」节）。

引擎镜像固化

引擎镜像在 pip 安装 hermes-agent（vendored wheel，engines/hermes/vendor/）后追加两步：安装 tools/environments/opensandbox.py（OpenSandbox 执行后端）+ patch_terminal.py 给 terminal_tool 打 5 处补丁（后端注册）。补丁带锚点断言，hermes 升版导致锚点漂移时构建显式失败（engines/hermes/tests/test_patch_terminal.py 同步守护）。