7e7871875c
Stacked follow-up on the v2.0.0 rewrite. The merged v2.0.0 template
had three latent issues that only surfaced during local E2E testing:
1) sudo → gosu (python:3.11-slim ships neither; only gosu was in
the Dockerfile). start.sh was calling sudo which would have
broken every container boot.
2) PATH pointed at /home/agent/.hermes/bin which doesn't exist —
install.sh symlinks ~/.local/bin/hermes. Installer is also
interactive by default; needs --skip-setup to run in docker build.
3) start.sh wrote ~/.hermes/cli-config.yaml but hermes-agent reads
~/.hermes/config.yaml. cli-config.yaml.example is just a starter
file — install.sh copies it to config.yaml on first boot. Without
our overwrite the template inherited the example default
(anthropic/claude-opus-4.6 + provider: auto) instead of the
workspace's chosen model. We now rewrite config.yaml every boot
from HERMES_DEFAULT_MODEL + HERMES_INFERENCE_PROVIDER env.
Also:
- Added xz-utils + build-essential to the image (hermes installer
extracts a Node 22 .tar.xz and some Python deps in .[all] build
from source).
- Forward every provider key hermes-agent knows about, not just
the 6 from v2.0.0. All ~22 providers documented in the official
website/docs/integrations/providers.md are now wired:
HERMES_API_KEY, NOUS_API_KEY, OPENROUTER_API_KEY, OPENAI_API_KEY,
ANTHROPIC_API_KEY, GEMINI_API_KEY, GOOGLE_API_KEY, DEEPSEEK_API_KEY,
GLM_API_KEY, KIMI_API_KEY, KIMI_CN_API_KEY, MINIMAX_API_KEY,
MINIMAX_CN_API_KEY, DASHSCOPE_API_KEY, XIAOMI_API_KEY,
ARCEEAI_API_KEY, NVIDIA_API_KEY, OLLAMA_API_KEY, HF_TOKEN,
AI_GATEWAY_API_KEY, KILOCODE_API_KEY, OPENCODE_ZEN_API_KEY,
OPENCODE_GO_API_KEY, COPILOT_GITHUB_TOKEN, GH_TOKEN
- config.yaml models[] list expanded to 30+ entries covering every
provider family (Hermes 3/4, Anthropic direct, OpenAI via
OpenRouter, Gemini direct, DeepSeek, GLM, Kimi, MiniMax global+CN,
Qwen/DashScope, Xiaomi MiMo, Arcee Trinity, NVIDIA NIM, Ollama
Cloud, Hugging Face catch-all, Vercel AI Gateway, OpenCode Zen+Go,
Kilo Code, OpenRouter catch-all, custom/local).
- top-level required_env: [] — hermes supports too many providers
for a single hardcoded requirement; per-model required_env in
the canvas Config tab drives the real UX. hermes-agent itself
errors loud at request time if zero providers are configured.
- HERMES_CUSTOM_BASE_URL / HERMES_CUSTOM_API_KEY env support in
start.sh — lets operators point hermes at OpenAI direct, LM Studio,
LiteLLM, any OpenAI-compat endpoint without exec-ing into the
container.
- HERMES_INFERENCE_PROVIDER env — forces a specific provider,
overriding hermes' auto-detection (which routes OPENAI_API_KEY
to openai-codex OAuth path → 401 Missing Authentication header).
- docs/CONFIGURATION.md rewritten with the full provider matrix,
OAuth flow, forcing a provider, auxiliary model, persistence
layout, and the common routing gotchas surfaced during testing.
- docs/ARCHITECTURE.md adds "Provider routing (how keys become
inference)" section.
Proved end-to-end on local Docker:
[start.sh] hermes gateway ready on :8642 (pid 22)
Uvicorn running on http://0.0.0.0:8000
→ A2A message/send "Respond with HERMES BRIDGE WORKING END TO END"
← HERMES BRIDGE WORKING END TO END — (via OpenAI Responses API)
→ "Run uname -a && whoami && pwd using your terminal tool"
← Linux 094f72... aarch64 GNU/Linux / agent / /home/agent
(real tool call — not chat response)
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
||
|---|---|---|
| .github/workflows | ||
| .molecule-ci/scripts | ||
| docs | ||
| runbooks | ||
| __init__.py | ||
| .gitignore | ||
| adapter.py | ||
| CLAUDE.md | ||
| config.yaml | ||
| Dockerfile | ||
| executor.py | ||
| known-issues.md | ||
| README.md | ||
| requirements.txt | ||
| start.sh | ||
template-hermes
Molecule AI workspace template that runs the real Nous Research hermes-agent behind an A2A bridge.
What's actually in the container
- hermes-agent — installed via the upstream
scripts/install.sh. Runs as useragent, state lives in~/.hermes. Gateway boots with the OpenAI-compatible API server platform enabled on127.0.0.1:8642(internal only). - molecule_runtime — our A2A server + bridge adapter. Listens on
:8000and forwards every incoming message to the local hermes-agent gateway. The rest of the platform (canvas, plugins, skills installer) sees the same A2A contract as any other runtime.
This template was rewritten in v2.0.0 — the previous version was a thin
OpenAI-compat provider shim that shared the hermes name with the real
project but had none of its agent capabilities (skills, memory, tools,
self-improvement loop, multi-platform gateway). See
docs/PLANNING.md for the full rewrite
rationale.
Usage
In Molecule AI canvas
Select this template when creating a new workspace — the canvas
Runtime dropdown resolves hermes to workspace-template:hermes
via molecule-monorepo/workspace-server/internal/provisioner/provisioner.go.
From a URL (community install)
github://Molecule-AI/template-hermes
Required environment
At least one provider key must be set, matching whichever model you select in the Config tab. hermes-agent picks the right one by prefix — you do not pick the provider yourself.
| Env var | Used for |
|---|---|
HERMES_API_KEY |
Nous Portal (Hermes 3/4 direct) |
OPENROUTER_API_KEY |
Anything via OpenRouter (200+ models) |
ANTHROPIC_API_KEY |
Claude direct (native SDK inside hermes-agent) |
OPENAI_API_KEY |
GPT direct |
GEMINI_API_KEY |
Gemini direct (native SDK inside hermes-agent) |
MINIMAX_API_KEY |
MiniMax direct |
Set these as workspace-level secrets (POST /settings/secrets) — see
molecule-monorepo/docs/runbooks/saas-secrets.md for the canonical
flow.
Persisting skills and memory
hermes-agent writes to ~/.hermes (/home/agent/.hermes in the
container). Mount this path as a persistent volume if you want skills,
memory, and cron schedules to survive workspace restarts — the
platform's default Docker named volume does this automatically as long
as the workspace isn't re-provisioned from scratch.
Files
| File | Purpose |
|---|---|
Dockerfile |
Builds the image (hermes-agent + molecule_runtime) |
start.sh |
Boots hermes gateway, waits for :8642, exec's runtime |
adapter.py |
HermesAgentAdapter(BaseAdapter) — just a factory |
executor.py |
HermesAgentProxyExecutor — A2A → hermes HTTP bridge |
config.yaml |
Template metadata + model list for the Config tab |
requirements.txt |
Python deps for the bridge (molecule_runtime + httpx) |
docs/PLANNING.md |
Rewrite plan + rationale + phase breakdown |
docs/ARCHITECTURE.md |
How the bridge works, port map, failure modes |
docs/MIGRATION.md |
Upgrade path from v1.x (the old adapter shim) |
docs/CONFIGURATION.md |
How to pick a model, rotate keys, tune hermes-agent |
Schema version
template_schema_version: 1 — compatible with Molecule AI platform v1.x.
License
Business Source License 1.1 — © Molecule AI. hermes-agent itself is
MIT-licensed by Nous Research and installed from its upstream repo at
build time.