Configuration and data location

Data location

All telemetry state lives in a telemetry/ directory under your Hermes home:

~/.hermes/telemetry/
├── telemetry.db        SQLite database (WAL mode)
├── telemetry.log       plugin log: errors, debug output, one-time warnings
├── pricing.yaml        your price overrides plus auto-fetched prices
├── budget.yaml         your spend guardrails
├── enforcement_mode    sidecar written at startup so the dashboards know the mode (enforce or observe)
└── .pricing_refresh    sentinel: its modification time is the last pricing refresh

If pricing.yaml and budget.yaml do not exist, the plugin still works. It falls back to its built-in prices and runs with budgets disabled, and the setup wizard creates defaults on first load.

The database grows over time and nothing purges old rows automatically. See Known limitations.

Plugin setting

The plugin has one setting, mode, configured through Hermes:

plugins:
  entries:
    hermes-telemetry:
      settings:
        mode: enforce   # default; set to observe for telemetry-only

enforce keeps budget blocking active. observe records and reports without enforcing. The value is read when the plugin registers, so a change needs a restart of the Hermes process that owns the plugin. See Setup wizard.

Environment variables

Variable	Effect
HERMES_HOME	The Hermes home. Telemetry lives in $HERMES_HOME/telemetry/. Defaults to ~/.hermes.
HERMES_TELEMETRY_HOME	Opt-in shared telemetry root. Outranks HERMES_HOME for telemetry.db, budget.yaml, and pricing.yaml. See Profiles and shared home.
HERMES_TELEMETRY_NO_SETUP	Set to 1 to skip the first-load auto-setup.
HERMES_PYTHON	Python interpreter used by the hermes-telemetry launcher. Defaults to the interpreter Hermes uses.

Telemetry paths resolve with the precedence HERMES_TELEMETRY_HOME, then HERMES_HOME, then ~/.hermes.

Note

With HERMES_TELEMETRY_HOME set, the database, budget.yaml, pricing.yaml, and enforcement_mode move to the shared root. telemetry.log, the .pricing_refresh sentinel, and the setup wizard’s file lookups still use HERMES_HOME. Hermes’s own state.db and cron/ are never relocated.

File formats

• pricing.yaml: per-model prices, defaults, and metadata tags.
• budget.yaml: limits per scope, thresholds, and estimated-data handling.

For the full list of files and the database schema, see User config files and Database layer in the Internals section.