Hermes provider

Hermes Agent CLI — ACP dispatch, profiles, install, and CtrlNode agent type Hermes

Use Hermes when your project or agent type is Hermes. The Bridge provider id is hermes.

Hermes is an open agent stack with a CLI and optional messaging gateway. In CtrlNode, tasks run through the Bridge like other CLIs — primary path is hermes acp (Agent Client Protocol), with hermes chat as a fallback.

Install on the Bridge host

pip install "hermes-agent[acp]"

Confirm the CLI is on PATH:

hermes --version

On Windows, use the same Python environment you use for other agent tools, then restart the terminal before running ctrlnode.

CtrlNode setup

1. Project — set default agent type to Hermes (CLI badge in the project sidebar).
2. Team — create an agent with type Hermes.
3. Bridge — ensure ctrlnode is connected; CtrlNode sends sync_hermes_agents with your agent ids.

How dispatch works

Mode	Bridge behavior
ACP (default)	Spawns hermes acp; streams tool and message events to CtrlNode
CLI fallback	Set HERMES_USE_ACP=false → hermes chat -Q (stdout is task output only)

Task work mode still applies:

• OUTPUT ONLY — deliverables under this task’s folder in {BASE_PATH}/.ctrlnode/tasks/...
• WORK DIRECTORY — agent can read and change the project’s work directory (or Bridge workspace home if the project has no path set)

See Task work modes.

Where Hermes stores data

Location	What
~/.hermes/profiles/{agentId}/	Runtime Hermes profile (config.yaml, SOUL.md) — HERMES_HOME at spawn
{BASE_PATH}/.ctrlnode/agents/{agentId}/	Optional Bridge copy of AGENTS.md + .meta.json for SaaS file sync
{BASE_PATH}/.ctrlnode/.hermes-sessions/	CLI mode: persisted conversation ids

Other providers do not write under .ctrlnode/agents/. Codex uses .ctrlnode/.codex-agents/{agentId}/.

HERMES_HOME in .env is only an emergency global override of ~/.hermes.

Environment variables

Variable	Default	Description
HERMES_TIMEOUT_MINUTES	15	Max task duration
HERMES_USE_ACP	ACP enabled	false or 0 → CLI hermes chat only
HERMES_HOME	per-agent profile	Global override (rare)

Provider API keys follow Hermes documentation (configure in the Hermes profile or global Hermes config as required by your install).

hermes mcp serve

Not used for CtrlNode task dispatch. hermes mcp serve is for messaging gateways (Telegram, Discord, etc.), not for local dispatch_task from the Bridge.

Troubleshooting

Symptom	What to check
Agent not in sync	Reconnect Bridge; confirm agent type Hermes
hermes: command not found	Install hermes-agent[acp]; fix PATH; restart ctrlnode
Task hangs	ACP vs CLI — try HERMES_USE_ACP=false for debugging
Wrong working files	Task mode WORK DIRECTORY + project work directory set

Related

• Providers
• Bridge configuration
• Task work modes