Documentation Index
Fetch the complete documentation index at: https://docs.ctrlnode.ai/llms.txt
Use this file to discover all available pages before exploring further.
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]"
PATH:
On Windows, use the same Python environment you use for other agent tools, then restart the terminal before running ctrlnode.
CtrlNode setup
- Project — set default agent type to Hermes (CLI badge in the project sidebar).
- Team — create an agent with type Hermes.
- 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) |
- 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 |
.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) |
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 |
