> ## 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.

# 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

```bash theme={null}
pip install "hermes-agent[acp]"
```

Confirm the CLI is on `PATH`:

```bash theme={null}
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](/tasks/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/providers)
* [Bridge configuration](/bridge/configuration)
* [Task work modes](/tasks/task-work-modes)