How-To Series · 9: Locking It Down

Remote Config

Serve every profile's config from one central config plane instead of config.yaml, with layered settings and keys administrators can lock.

After this videoYou can switch a Hermes agent to the config plane, sign it in, and know what behaves differently once config.yaml is gone.

Remote config mode replaces config.yaml with the config plane. The plane builds each profile's config in layers: global, tenant, group, owner and agent settings, with the profile's own settings applied last, and administrators can lock a key at an upper level so the agent cannot change it. It is built for fleet deployments such as Hermes Cloud; a single machine with one user should keep config.yaml. You turn it on in the environment, ~/.hermes/.env or the managed /etc/hermes/.env (which wins), never in config.yaml, by setting HERMES_CONFIG_BACKEND=remote and HERMES_CONFIG_INSTANCE_ID. The agent authenticates as itself: the Nous access token in auth.json on Hermes Cloud, or an OAuth2 client-credentials token on-prem. Startup fetches config and fails closed after about 30 seconds of retries, there is no local file or cache, and each process polls for changes every 5 minutes. Writes such as hermes config set and /model send only the changed keys to the profile's own level, locked keys are refused, and secret-shaped keys accept only a ${VAR} reference. Commands that copy or edit config.yaml are refused, /etc/hermes/config.yaml is ignored, and hermes doctor reports the plane instead of the file.

About these resources. Every command and setting in this video comes from the Remote Config doc. For machine-wide admin locks without a config plane, see the Managed Scope episode below.

New words here · Plain English

one sentence each · full glossary
Remote configA mode where a Hermes profile gets its settings from a central config plane instead of a local config.yaml file. It is meant for fleets of agents, not a single personal machine.
Config planeThe central service that serves each agent's config. It layers settings from global down to the profile and lets administrators lock keys.
Locked keyA setting an administrator pins at an upper level of the config plane. The agent cannot change it, and Hermes tells you which level locks it.
Fail closedIf the config plane cannot be reached at startup, Hermes exits with an error instead of falling back to a local file or default settings.

Sources · What this video distills

1 docs page · every command below traces to it
Primary guide
Remote Config
Read ↗

Commands shown · Copy and paste

each shows the source doc it came from
.env: use the config plane instead of config.yaml (also set HERMES_CONFIG_INSTANCE_ID)from source ↗
HERMES_CONFIG_BACKEND=remote
Secret-shaped keys take a ${VAR} reference, never the secretfrom source ↗
hermes config set model.api_key '${OPENROUTER_API_KEY}'
Reports the plane URL, profile, version, locks and last fetchfrom source ↗
hermes doctor

Going deeper · Related Hermes docs

further reading · not sources of facts shown above

Next in the series · Episodes that build on this