Hermes

Before you begin

• Install the OpenLLM CLI. See Install.
• Install Hermes so that hermes is on your PATH. If it is missing, openllm hermes prints the official installer, https://hermes-agent.nousresearch.com/install.sh.
• Have at least one model available. See Providers.

Set up with openllm hermes

openllm hermes

With no arguments, this opens the Hermes TUI. Every other argument goes to Hermes unchanged, except OpenLLM's verbs install, uninstall, status, and the --no-persist flag. For a one-shot prompt, run openllm hermes -z "…".

At launch, OpenLLM picks a gateway: your local daemon at http://127.0.0.1:8787 if it answers, otherwise https://www.openllm.sh. For the session, it sets HERMES_HOME to ~/.openllm/run/hermes/<pid>/, a directory that links to everything in your real ~/.hermes. In it, OpenLLM writes a config.yaml that merges your active profile's config with:

• an openllm provider with api set to <gateway>/v1, transport: chat_completions, and the key read from OPENLLM_API_KEY;
• model.default: ultra with provider: custom:openllm;
• the openllm MCP server.

OPENAI_API_KEY and OPENAI_BASE_URL are removed from the Hermes environment. The directory is deleted when Hermes exits.

Make it sticky

To route Hermes through OpenLLM outside the TUI too, for example its gateway or scheduled jobs, install a profile:

openllm hermes install

This:

1. Creates the profile ~/.hermes/profiles/openllm (or openllm-gateway if openllm already exists), copying config.yaml, .env, SOUL.md, and skills/ from your active profile.
2. Merges the OpenLLM settings into that profile's config.yaml and writes OPENLLM_API_KEY to its .env.
3. Makes it the active profile and restarts the Hermes gateway.

After that, openllm hermes and plain hermes both use the profile. Your default ~/.hermes/config.yaml is never edited. The gateway URL is fixed when you install; run openllm hermes install again after you start or stop the daemon. To skip the profile for one launch, add --no-persist.

Choose models

The default model is ultra. The provider also declares plus and lite. To switch, use /model in Hermes. To change what the aliases resolve to, edit the chains in Configuration. See Routing and fallback.

Who pays for a request

The model that serves the request decides. A subscription hop runs on your own login through the daemon on one of your devices. An API-key hop bills your provider account. Included openllm/ models count against your plan's allowance. See Providers and Plans and limits.

Check that it works

openllm hermes -z "Reply with OK"
openllm hermes status

status prints one JSON line; "installed": true means the sticky profile is wired. Open Overview in the app to see the request.

Common problems

For anything else, see Troubleshooting.

Remove it

If you only used openllm hermes, there is nothing to remove. After openllm hermes install, run:

openllm hermes uninstall

This restores the profile that was active before, deletes the openllm profile if OpenLLM created it, and restarts the Hermes gateway.

Last updated on