cli-config.yaml.example 129 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429243024312432243324342435243624372438
  1. # Hermes Agent CLI Configuration
  2. # Copy settings from this example into ~/.hermes/config.yaml, or use
  3. # `hermes config set <section.key> <value>` to update the active profile.
  4. # This file configures CLI behavior; only documented secret environment
  5. # variables in .env take precedence over their corresponding settings.
  6. # Schema version of this file. The installers copy it to seed config.yaml, and
  7. # `hermes update` uses it to know which one-time migrations the file already
  8. # has. Hermes manages it: do not copy it into another config.
  9. _config_version: 52
  10. # =============================================================================
  11. # Database Configuration
  12. # =============================================================================
  13. # WAL is the normal default. Hermes automatically falls back to DELETE when
  14. # SQLite reports that WAL is incompatible with the filesystem. Set this to
  15. # "delete" explicitly for deployments whose backing filesystem is not WAL
  16. # crash-safe, such as Linux containers bind-mounted through macOS virtiofs,
  17. # NFS, or SMB. Hermes will not live-downgrade a database already open in WAL.
  18. database:
  19. journal_mode: "wal" # Supported values: "wal", "delete"
  20. # Optional WAL sizing pragmas (integers). Unset = SQLite defaults.
  21. # wal_autocheckpoint: 1000 # pages between automatic checkpoints
  22. # journal_size_limit: 67108864 # cap the WAL/journal file size in bytes
  23. #
  24. # Durability level for every state.db connection: OFF, NORMAL, FULL, EXTRA
  25. # (or 0-3). Unset leaves SQLite's default, which is baked in at compile time
  26. # (SQLITE_DEFAULT_WAL_SYNCHRONOUS) and therefore differs between the bundled
  27. # interpreter, a distro python3 and a Homebrew one. Set it if you need to
  28. # know which one you are running rather than infer it. On macOS this is a
  29. # floor, not a pin: values below FULL are refused because Darwin's fsync()
  30. # does not guarantee write ordering, while EXTRA is honored normally.
  31. # synchronous: FULL
  32. # =============================================================================
  33. # Runtime Limits
  34. # =============================================================================
  35. # Long-running Hermes server processes raise their RLIMIT_NOFILE soft limit to
  36. # this value when the operating system permits it. The value is clamped to the
  37. # hard limit and never lowers an already higher soft limit. Set to 0, false, or
  38. # null to disable the adjustment. Default: 4096.
  39. #
  40. # malloc_arena_max caps glibc malloc arenas in the gateway / `hermes serve`
  41. # process (Linux/glibc only; child commands keep glibc's default). An explicit
  42. # MALLOC_ARENA_MAX (exported or in .env) wins. 0, false, or null = glibc default
  43. # (8 per CPU core). Default: 4.
  44. runtime:
  45. nofile_soft_limit: 4096
  46. malloc_arena_max: 4
  47. # =============================================================================
  48. # Attachments
  49. # =============================================================================
  50. # Where the TUI/Desktop gateway stages session file attachments (file uploads and
  51. # pasted text). Read per profile: a session bound to profile X follows X's own
  52. # config.yaml, so each agent's attachments stay with its workspace.
  53. # hermes-home (default) <profile home>/attachments — the directory container
  54. # backends bind-mount, so @file: refs resolve inside the sandbox.
  55. # workspace <session workspace>/.hermes/attachments — staging lands inside
  56. # the allowed reference root, so the profile's agent can always
  57. # read its own attachments back. A remote (ssh) workspace keeps
  58. # the profile home directory either way.
  59. attachments:
  60. storage: "hermes-home"
  61. # =============================================================================
  62. # Plugin Installation
  63. # =============================================================================
  64. plugins:
  65. # Deadline for each Git clone, fetch or checkout during plugin install. Default: 300
  66. # seconds. Subdirectory installs download only that folder.
  67. # Raise this for large repositories or slow connections. Maximum: 3600.
  68. clone_timeout_seconds: 300
  69. # =============================================================================
  70. # Model Configuration
  71. # =============================================================================
  72. model:
  73. # Default model to use (can be overridden with --model flag)
  74. # Both "default" and "model" work as the key name here.
  75. default: "anthropic/claude-opus-4.6"
  76. # Inference provider selection:
  77. # "auto" - Auto-detect from credentials (default)
  78. # "openrouter" - OpenRouter (requires: OPENROUTER_API_KEY or OPENAI_API_KEY)
  79. # "nous" - Nous Portal OAuth (requires: hermes auth add nous)
  80. # "nous-api" - Nous Portal API key (requires: NOUS_API_KEY)
  81. # "anthropic" - Direct Anthropic API (requires: ANTHROPIC_API_KEY)
  82. # "openai-codex" - OpenAI Codex (requires: hermes auth)
  83. # "gemini" - Use Google AI Studio direct (requires: GOOGLE_API_KEY or GEMINI_API_KEY)
  84. # "zai" - Use z.ai / ZhipuAI GLM models (requires: GLM_API_KEY)
  85. # "kimi-coding" - Kimi / Moonshot AI (requires: KIMI_API_KEY)
  86. # "minimax" - MiniMax global (requires: MINIMAX_API_KEY)
  87. # "minimax-cn" - MiniMax China (requires: MINIMAX_CN_API_KEY)
  88. # "huggingface" - Hugging Face Inference (requires: HF_TOKEN)
  89. # "nvidia" - NVIDIA NIM / build.nvidia.com (requires: NVIDIA_API_KEY)
  90. # "xiaomi" - Xiaomi MiMo (requires: XIAOMI_API_KEY)
  91. # "arcee" - Arcee AI Trinity models (requires: ARCEEAI_API_KEY)
  92. # "ollama-cloud" - Ollama Cloud (requires: OLLAMA_API_KEY — https://ollama.com/settings)
  93. # "deepinfra" - DeepInfra (requires: DEEPINFRA_API_KEY)
  94. # "kilocode" - KiloCode gateway (requires: KILOCODE_API_KEY)
  95. # "ai-gateway" - Vercel AI Gateway (requires: AI_GATEWAY_API_KEY)
  96. # "azure-foundry" - Microsoft Foundry / Azure OpenAI (API key or Entra ID)
  97. # "lmstudio" - LM Studio local server (optional: LM_API_KEY, defaults to http://127.0.0.1:1234/v1)
  98. #
  99. # Local servers (LM Studio, Ollama, vLLM, llama.cpp):
  100. # "custom" - Any other OpenAI-compatible endpoint. Set base_url below.
  101. # Aliases: "ollama", "vllm", "llamacpp" all map to "custom".
  102. # LM Studio is first-class and uses provider: "lmstudio".
  103. # It works with both no-auth and auth-enabled server modes.
  104. #
  105. # Can also be overridden for a single invocation with the --provider flag.
  106. provider: "auto"
  107. # API configuration (falls back to OPENROUTER_API_KEY env var)
  108. # api_key: "your-key-here" # Uncomment to set here instead of .env
  109. base_url: "https://openrouter.ai/api/v1"
  110. # Stream API responses from the provider (default: true). The agent core
  111. # prefers streaming for every turn — subagents included — for liveness
  112. # health-checking. Set false to force non-streaming requests for the whole
  113. # session (persists across mid-session model switches). Escape hatch for
  114. # self-hosted OpenAI-compatible servers whose streaming tool-call path is
  115. # broken (e.g. vLLM with --tool-call-parser qwen3_xml + a reasoning parser
  116. # can leak tool calls into plain text instead of returning tool_calls —
  117. # #72901). Orthogonal to display.streaming, which controls token rendering
  118. # only.
  119. # streaming: true
  120. # Azure Foundry keyless auth example:
  121. # provider: "azure-foundry"
  122. # base_url: "https://<resource>.openai.azure.com/openai/v1"
  123. # auth_mode: "entra_id" # DefaultAzureCredential: az login, managed identity, workload identity, etc.
  124. # default: "gpt-4o" # Deployment/model name
  125. # entra:
  126. # scope: "https://ai.azure.com/.default" # Optional; this is the default.
  127. # ── Token limits — two settings, easy to confuse ──────────────────────────
  128. #
  129. # context_length: TOTAL context window (input + output tokens combined).
  130. # Controls when Hermes compresses history and validates requests.
  131. # Leave unset — Hermes auto-detects the correct value from the provider.
  132. # Set manually only when auto-detection is wrong (e.g. a local server with
  133. # a custom num_ctx, or a proxy that doesn't expose /v1/models).
  134. #
  135. # context_length: 131072
  136. #
  137. # ollama_num_ctx: Ollama only — the num_ctx sent on every chat request.
  138. # Hermes auto-detects the model's window and sends it (Ollama otherwise
  139. # defaults to 2048); context_length, if set, caps the detected value.
  140. # An explicit ollama_num_ctx is sent as-is (never capped) — set it to
  141. # pin VRAM use.
  142. #
  143. # ollama_num_ctx: 32768
  144. #
  145. # Output-token limits are provider-owned, not user configuration. Native
  146. # protocols requiring a limit receive an internal value from Hermes.
  147. # ── Custom request headers (optional) ─────────────────────────────────────
  148. #
  149. # default_headers: extra HTTP headers sent on every request to an
  150. # OpenAI-compatible endpoint. User values take precedence over the
  151. # provider/SDK defaults, so this is the supported way to override the
  152. # OpenAI Python SDK's identifying headers (User-Agent: OpenAI/Python ...,
  153. # X-Stainless-*) when a custom provider sits behind a gateway/WAF that
  154. # rejects them — e.g. an upstream that returns "502 Upstream access
  155. # forbidden" for the SDK default User-Agent but accepts a plain one.
  156. # Applies on the OpenAI wire only (not native Anthropic / Bedrock).
  157. #
  158. # default_headers:
  159. # User-Agent: "curl/8.7.1"
  160. #
  161. # extra_headers: accepted as an alias of default_headers (merged, with
  162. # extra_headers winning when both are set) — matches the per-provider
  163. # extra_headers key below.
  164. #
  165. # Per-provider variant: named providers / custom_providers entries accept an
  166. # extra_headers dict scoped to that endpoint only — for reverse proxies,
  167. # gateways, or custom auth (e.g. Cloudflare Access service tokens).
  168. # Merged onto SDK/provider defaults with the entry's values winning.
  169. # Header values are treated as secrets and are never logged.
  170. #
  171. # providers:
  172. # my-proxy:
  173. # base_url: "https://llm.internal.example.com/v1"
  174. # key_env: "MY_PROXY_API_KEY"
  175. # extra_headers:
  176. # CF-Access-Client-Id: "xxxx.access"
  177. # CF-Access-Client-Secret: "${CF_ACCESS_SECRET}"
  178. # X-Client-Name: "hermes-agent"
  179. #
  180. # session_affinity_header: NAME of a header that carries Hermes' conversation
  181. # id on every request to that provider (all api_modes + auxiliary calls). Off
  182. # unless set. For session-aware proxies that otherwise treat each agent-loop
  183. # request as a new conversation and replay the whole history upstream.
  184. #
  185. # providers:
  186. # my-proxy:
  187. # base_url: "http://127.0.0.1:4000/v1"
  188. # session_affinity_header: x-litellm-session-id
  189. # providers:
  190. # meta:
  191. # base_url: https://api.meta.ai/v1
  192. # api_key: ${MODEL_API_KEY}
  193. # # api_mode auto-detected as codex_responses for api.meta.ai; no need to set
  194. # # (the bundled meta-ai provider covers this — a named custom provider is
  195. # # only needed for a non-default Meta-compatible endpoint)
  196. # Fast/priority tier behind an OpenAI-compatible gateway or proxy: agent.service_tier
  197. # (`/fast`) only reaches first-party endpoints; ask a gateway for its own tier via
  198. # extra_body, which is merged into every request routed to that provider.
  199. # providers:
  200. # my-gateway:
  201. # base_url: https://gateway.example.com/v1
  202. # api_key: ${MY_GATEWAY_KEY}
  203. # extra_body:
  204. # service_tier: priority # whatever tier value your gateway documents
  205. # providers:
  206. # router:
  207. # base_url: https://api.router.com/v1
  208. # api_key: ${RAMP_ROUTER_API_KEY}
  209. # # api_mode auto-detected as codex_responses for api.router.com — the
  210. # # Responses API is Router's native wire (chat/completions is only a
  211. # # compatibility shim). The bundled router provider covers this; a named
  212. # # custom provider is only needed for a non-default Router-compatible
  213. # # endpoint.
  214. # Command-minted credentials (optional): key_cmd
  215. # ------------------------------------------------------------------
  216. # Enterprise gateways often issue SHORT-LIVED bearers (SSO/OIDC brokers, cloud
  217. # IAM, internal auth proxies) rather than static API keys, so a value copied
  218. # into .env via `key_env` is stale within the hour and every later request 401s.
  219. # `key_cmd` names a command that PRINTS a token instead: Hermes runs it per
  220. # request (cached until shortly before expiry), so long sessions keep working
  221. # with no restart.
  222. #
  223. # Contract: print ONLY the token on stdout, either bare or as JSON with an
  224. # "access_token" field ("expires_in" is honoured). Same shape as OAuth 2.0
  225. # token endpoints, Claude Code's `apiKeyHelper`, `gcloud auth
  226. # print-access-token`, and `aws ecr get-login-password`.
  227. #
  228. # Precedence: an explicit --api-key still wins; otherwise key_cmd is preferred
  229. # over inline api_key / key_env on that entry.
  230. #
  231. # Applies to the main agent turn and to auxiliary tasks (title generation,
  232. # context compression, vision, embedding) alike.
  233. #
  234. # Not to be confused with `secrets.command`, which is a different mechanism:
  235. # that one runs a helper ONCE at startup to populate env vars for many secrets
  236. # at the process level. Use it for a vault or keychain helper that hands back a
  237. # KEY=VALUE blob. Use `key_cmd` when ONE provider needs a credential refreshed
  238. # DURING a session, because a startup-time env var cannot be re-minted after it
  239. # expires.
  240. #
  241. # providers:
  242. # my-gateway:
  243. # base_url: "https://gateway.internal.example.com/v1"
  244. # api_mode: chat_completions
  245. # key_cmd: "my-auth-cli print-token --profile prod"
  246. #
  247. # Worked example — an AI gateway that routes by model family, so one entry per
  248. # wire format shares the same credential helper:
  249. #
  250. # providers:
  251. # dbx: # OpenAI-compatible (MLflow) route
  252. # base_url: "https://<workspace>.cloud.databricks.com/ai-gateway/mlflow/v1"
  253. # api_mode: chat_completions
  254. # model: databricks-claude-sonnet-4-6
  255. # key_cmd: "databricks auth token -p MY-PROFILE"
  256. # dbx-gpt: # OpenAI Responses route
  257. # base_url: "https://<workspace>.cloud.databricks.com/ai-gateway/openai/v1"
  258. # api_mode: codex_responses
  259. # model: databricks-gpt-5-5
  260. # key_cmd: "databricks auth token -p MY-PROFILE"
  261. # dbx-claude: # Anthropic Messages route
  262. # base_url: "https://<workspace>.cloud.databricks.com/ai-gateway/anthropic"
  263. # api_mode: anthropic_messages
  264. # model: databricks-claude-fable-5
  265. # key_cmd: "databricks auth token -p MY-PROFILE"
  266. # Named provider overrides (optional)
  267. # Use this for per-provider request timeouts, non-stream stale timeouts,
  268. # and per-model exceptions.
  269. # Applies to the primary turn client on every api_mode (OpenAI-wire, native
  270. # Anthropic, and Anthropic-compatible providers), the fallback chain, and
  271. # client rebuilds during credential rotation. For OpenAI-wire chat
  272. # completions (streaming and non-streaming) the configured value is also
  273. # used as the per-request ``timeout=`` kwarg so it wins over the legacy
  274. # HERMES_API_TIMEOUT env var (which still applies when no config is set).
  275. # ``stale_timeout_seconds`` controls the non-streaming stale-call detector and
  276. # wins over the legacy HERMES_API_CALL_STALE_TIMEOUT env var. Leaving these
  277. # unset keeps the legacy defaults (HERMES_API_TIMEOUT=1800s,
  278. # HERMES_API_CALL_STALE_TIMEOUT=90s, native Anthropic 900s). The
  279. # implicit non-stream stale detector is auto-disabled for local endpoints
  280. # and can scale upward for very large contexts.
  281. #
  282. # AWS Bedrock (providers.bedrock): the resolved value is the socket read
  283. # timeout of the boto3 Converse client and of the AnthropicBedrock SDK
  284. # client, chosen per request for the active model. Connect stays fixed
  285. # (botocore 60s / SDK 10s); unset keeps botocore's 60s read on Converse.
  286. #
  287. # providers:
  288. # ollama-local:
  289. # request_timeout_seconds: 300 # Longer timeout for local cold-starts
  290. # stale_timeout_seconds: 900 # Explicitly re-enable stale detection on local endpoints
  291. # anthropic:
  292. # request_timeout_seconds: 30 # Fast-fail cloud requests
  293. # models:
  294. # claude-opus-4.6:
  295. # timeout_seconds: 600 # Longer timeout for extended-thinking Opus calls
  296. # openai-codex:
  297. # models:
  298. # gpt-5.4:
  299. # stale_timeout_seconds: 1800 # Longer non-stream stale timeout for slow large-context turns
  300. # =============================================================================
  301. # Unified Timeouts (operation deadlines)
  302. # =============================================================================
  303. # One place to override Hermes's internal operation deadlines (seconds).
  304. # Keys are dotted paths resolved by agent/deadline.py:resolve_timeout().
  305. # Precedence: this section > legacy HERMES_* env var (back-compat) > built-in
  306. # default. 0 or a negative value disables the bound (unbounded); very large
  307. # values are clamped to a platform-safe maximum automatically.
  308. #
  309. # Currently resolved keys (more paths migrate here over time — see issue #85125):
  310. #
  311. # timeouts:
  312. # tools:
  313. # concurrent_batch: 420 # Deadline for a parallel tool-call batch
  314. # # (legacy env: HERMES_CONCURRENT_TOOL_TIMEOUT_S)
  315. # sequential_call: 420 # Deadline for one sequentially-executed tool call.
  316. # # Defaults to concurrent_batch's value so the two
  317. # # executor paths stay in sync; human waits
  318. # # (approval prompts, clarify) never count against it.
  319. # =============================================================================
  320. # OpenRouter Provider Routing (only applies when using OpenRouter)
  321. # =============================================================================
  322. # Control how requests are routed across providers on OpenRouter.
  323. # See: https://openrouter.ai/docs/guides/routing/provider-selection
  324. #
  325. # provider_routing:
  326. # # Sort strategy: "price" (default), "throughput", or "latency"
  327. # # Append :nitro to model name for a shortcut to throughput sorting.
  328. # sort: "throughput"
  329. #
  330. # # Only allow these providers (provider slugs from OpenRouter)
  331. # # only: ["anthropic", "google"]
  332. #
  333. # # Skip these providers entirely
  334. # # ignore: ["deepinfra", "fireworks"]
  335. #
  336. # # Try providers in this order (overrides default load balancing)
  337. # # order: ["anthropic", "google", "together"]
  338. #
  339. # # Require providers to support all parameters in your request
  340. # # require_parameters: true
  341. #
  342. # # Data policy: "allow" (default) or "deny" to exclude providers that may store data
  343. # # data_collection: "deny"
  344. #
  345. # # Per-model overrides: same keys, applied only when the agent is on that model
  346. # # (spelling-tolerant match; unset keys fall through to the flat values above).
  347. # # models:
  348. # # "openai/gpt-6-astra":
  349. # # only: ["openai"]
  350. # # "anthropic/claude-fable-5.1":
  351. # # only: ["anthropic"]
  352. # =============================================================================
  353. # OpenRouter Response Caching (only applies when using OpenRouter)
  354. # =============================================================================
  355. # Cache identical API responses at the OpenRouter edge for free instant replays.
  356. # When enabled, identical requests (same model, messages, parameters) return
  357. # cached responses with zero billing. Separate from Anthropic prompt caching.
  358. # See: https://openrouter.ai/docs/guides/features/response-caching
  359. #
  360. # openrouter:
  361. # response_cache: true # Enable response caching (default: true)
  362. # response_cache_ttl: 300 # Cache TTL in seconds, 1-86400 (default: 300)
  363. # =============================================================================
  364. # Git Worktree Isolation
  365. # =============================================================================
  366. # When enabled, each CLI session creates an isolated git worktree so multiple
  367. # agents can work on the same repo concurrently without file collisions.
  368. # Equivalent to always passing --worktree / -w on the command line.
  369. #
  370. # worktree: true # Always create a worktree when in a git repo
  371. # worktree: false # Default — only create when -w flag is passed
  372. #
  373. # By default a new worktree branches from the freshly-fetched remote tip
  374. # (the current branch's upstream, else the remote's default branch) so it
  375. # starts current with the project instead of from the local clone's
  376. # (possibly stale) HEAD. Set worktree_sync: false to branch from local HEAD
  377. # instead — useful when offline or when you deliberately want the clone's
  378. # exact current state as the base.
  379. #
  380. # worktree_sync: true # Default — branch from the fetched remote tip
  381. # worktree_sync: false # Branch from local HEAD (offline / pinned base)
  382. # Stale worktree sweep (startup of `hermes -w` + every 6h from the cron ticker, over
  383. # every repo Hermes created a worktree in). Idle dirty/unpushed trees are archived to
  384. # refs/hermes/archive/<tree> and removed; `hermes worktree restore <name>` brings one back.
  385. # worktrees:
  386. # archive_dirty: true # false = never remove dirty/unpushed trees (old behaviour)
  387. # archive_max_file_mb: 50 # untracked files above this are not archived; their tree is kept
  388. # archive_retention_days: 30 # archive refs older than this are deleted (0 = keep)
  389. # max_total_gb: 0 # optional budget for idle trees; oldest evicted first
  390. # =============================================================================
  391. # Kanban Review Dispatch
  392. # =============================================================================
  393. # First-class review tasks are dispatched automatically by default. The worker
  394. # is spawned with the bundled sdlc-review skill and can approve, request changes
  395. # back to the original implementer, or escalate a genuine external blocker.
  396. # Disable this only when every review is performed manually from the dashboard.
  397. kanban:
  398. review_dispatch: true
  399. # =============================================================================
  400. # Terminal Tool Configuration
  401. # =============================================================================
  402. # Choose ONE of the following terminal configurations by uncommenting it.
  403. # The terminal tool executes commands in the specified environment.
  404. # -----------------------------------------------------------------------------
  405. # OPTION 1: Local execution (default)
  406. # Commands run directly on your machine in the current directory
  407. # -----------------------------------------------------------------------------
  408. # Working directory behavior:
  409. # - CLI (`hermes` command): Uses "." (current directory where you run hermes)
  410. # - Gateway/messaging/cron: Uses terminal.cwd here; legacy .env cwd values are deprecated
  411. cron:
  412. catch_up_missed: true # False skips past-grace recurring misses after planned downtime.
  413. terminal:
  414. backend: "local"
  415. cwd: "." # For local backend: "." = current directory. Ignored for remote backends unless a backend documents otherwise.
  416. # Desktop xterm font. Install the font locally; Nerd Fonts render Powerlevel10k glyphs.
  417. # font_family: "MesloLGS NF" # Also accepts a CSS stack; blank uses bundled JetBrains Mono.
  418. timeout: 180
  419. # HOME policy for tool subprocesses:
  420. # auto - default: host uses your real HOME; containers use HERMES_HOME/home
  421. # real - force your real OS-user HOME
  422. # profile - force HERMES_HOME/home for strict per-profile CLI config isolation
  423. home_mode: "auto"
  424. docker_mount_cwd_to_workspace: false # SECURITY: off by default. Opt in to mount the launch cwd into Docker /workspace.
  425. lifetime_seconds: 300
  426. # Two process_manage wait/poll calls in a row with no new output on a running background process
  427. # turn on notify_on_complete for it and tell the agent to stop checking; false = poll as before.
  428. process_wait_auto_notify: true
  429. # A `hermes` / `hermes --tui` session's local tools (terminal, background processes, execute_code)
  430. # start with the launching shell's toolchain: PATH, an activated venv and CONDA_* / NODE_* / NVM_* /
  431. # PYENV_* (plus GOPATH, GOROOT, CARGO_HOME, RUSTUP_HOME, JAVA_HOME), for that session only, when
  432. # the client runs on the gateway's host (a remote client's session keeps the gateway's toolchain).
  433. # As in the classic CLI, the venv reaches `terminal` through PATH (`which python`): VIRTUAL_ENV and
  434. # CONDA_PREFIX themselves are unset there; execute_code sees them.
  435. # A toolchain name the client did not export is unset for its session's tools (PATH excepted).
  436. # List more non-secret names here (default: none); names execute_code treats as credentials (…TOKEN,
  437. # …KEY, …SECRET, …PASSWORD, …AUTH, …DSN, …WEBHOOK, …CREDS, …BEARER, …COOKIE) and HERMES_* names
  438. # are never sent: pass secrets with `env_passthrough` instead.
  439. client_env_passthrough: [] # e.g. ["GEM_HOME", "POETRY_HOME"]
  440. # sudo_password: "hunter2" # Optional: pipe a sudo password via sudo -S. SECURITY WARNING: plaintext.
  441. # sudo_password: "" # Explicit empty password: try empty and never open the interactive sudo prompt.
  442. # -----------------------------------------------------------------------------
  443. # OPTION 2: SSH remote execution
  444. # Commands run on a remote server - agent code stays local (sandboxed)
  445. # Great for: keeping agent isolated from its own code, using powerful remote hardware
  446. # -----------------------------------------------------------------------------
  447. # terminal:
  448. # backend: "ssh"
  449. # cwd: "/home/myuser/project" # Path on the REMOTE server
  450. # timeout: 180
  451. # lifetime_seconds: 300
  452. # ssh_host: "my-server.example.com"
  453. # ssh_user: "myuser"
  454. # ssh_port: 22
  455. # ssh_key: "~/.ssh/id_rsa" # Optional - uses ssh-agent if not specified
  456. # -----------------------------------------------------------------------------
  457. # OPTION 3: Docker container
  458. # Commands run in an isolated Docker container
  459. # Great for: reproducible environments, testing, isolation
  460. # -----------------------------------------------------------------------------
  461. # terminal:
  462. # backend: "docker"
  463. # cwd: "/workspace" # Path INSIDE the container (default: /)
  464. # timeout: 180
  465. # lifetime_seconds: 300
  466. # docker_image: "nousresearch/hermes-sandbox:desktop"
  467. # docker_mount_cwd_to_workspace: true # Explicit opt-in: mount your launch cwd into /workspace
  468. # # Optional: run the container as your host user's uid:gid so files written
  469. # # into bind-mounted dirs are owned by you, not root. Drops SETUID/SETGID
  470. # # caps too since no gosu privilege drop is needed. Leave off if your
  471. # # chosen docker_image expects to start as root.
  472. # docker_run_as_host_user: true
  473. # # Optional: explicitly forward selected env vars into Docker.
  474. # # These values come from your current shell first, then ~/.hermes/.env.
  475. # # Warning: anything forwarded here is visible to commands run in the container.
  476. # docker_forward_env:
  477. # - "GITHUB_TOKEN"
  478. # - "NPM_TOKEN"
  479. # # Optional: extra flags passed verbatim to docker run (appended after security defaults).
  480. # # Useful for adding capabilities (e.g. apt installs needing SETUID) or custom options.
  481. # # Example: add a Linux capability not included by default
  482. # # docker_extra_args:
  483. # # - "--cap-add"
  484. # # - "SETUID"
  485. # -----------------------------------------------------------------------------
  486. # OPTION 4: Singularity/Apptainer container (the official `singularity` plugin)
  487. # Commands run in a Singularity container (common in HPC environments)
  488. # Great for: HPC clusters, shared compute environments
  489. # Install it first: hermes plugins install singularity
  490. # -----------------------------------------------------------------------------
  491. # terminal:
  492. # backend: "singularity"
  493. # cwd: "/workspace" # Path INSIDE the container (default: /root)
  494. # timeout: 180
  495. # lifetime_seconds: 300
  496. # singularity_image: "docker://nousresearch/hermes-sandbox:desktop"
  497. # -----------------------------------------------------------------------------
  498. # OPTION 5: Modal cloud execution
  499. # Commands run on Modal's cloud infrastructure
  500. # Great for: GPU access, scalable compute, serverless execution
  501. # -----------------------------------------------------------------------------
  502. # terminal:
  503. # backend: "modal"
  504. # cwd: "/workspace" # Path INSIDE the sandbox (default: /root)
  505. # timeout: 180
  506. # lifetime_seconds: 300
  507. # modal_image: "nousresearch/hermes-sandbox:desktop"
  508. # -----------------------------------------------------------------------------
  509. # OPTION 6: Daytona cloud execution
  510. # Commands run in Daytona cloud sandboxes
  511. # Great for: Cloud dev environments, persistent workspaces, team collaboration
  512. # Requires: pip install daytona, DAYTONA_API_KEY env var
  513. # -----------------------------------------------------------------------------
  514. # terminal:
  515. # backend: "daytona"
  516. # cwd: "~"
  517. # timeout: 180
  518. # lifetime_seconds: 300
  519. # daytona_image: "nousresearch/hermes-sandbox:desktop"
  520. # container_disk: 10240 # Daytona max is 10GB per sandbox
  521. #
  522. # --- Container resource limits (docker, modal, daytona, container plugin backends -- ignored for local/ssh) ---
  523. # These settings apply to all container backends. They control the resources
  524. # allocated to the sandbox and whether its filesystem persists across sessions.
  525. container_cpu: 1 # CPU cores
  526. container_memory: 5120 # Memory in MB (5120 = 5GB)
  527. container_disk: 51200 # Disk in MB (51200 = 50GB)
  528. container_persistent: true # Persist filesystem across sessions (false = ephemeral)
  529. # -----------------------------------------------------------------------------
  530. # SUDO SUPPORT (works with ALL backends above)
  531. # -----------------------------------------------------------------------------
  532. # Add sudo_password to any terminal config above to enable sudo commands.
  533. # The password is piped via `sudo -S`. Works with local, ssh, docker, etc.
  534. #
  535. # SECURITY WARNING: Password stored in plaintext!
  536. #
  537. # INTERACTIVE PROMPT: If sudo_password is unset and the CLI is running,
  538. # you'll be prompted to enter your password when sudo is needed:
  539. # - 45-second timeout (auto-skips if no input)
  540. # - Press Enter to skip (command fails gracefully)
  541. # - Password is hidden while typing
  542. # - Password is cached for the session
  543. #
  544. # EMPTY PASSWORDS: Setting sudo_password to an explicit empty string is different
  545. # from leaving it unset. Hermes will try an empty password via `sudo -S` and
  546. # will not open the interactive prompt. This is useful for passwordless sudo,
  547. # Touch ID sudo setups, and environments where prompting is just noise.
  548. #
  549. # ALTERNATIVES:
  550. # - SSH backend: Configure passwordless sudo on the remote server
  551. # - Containers: Run as root inside the container (no sudo needed)
  552. # - Local: Configure /etc/sudoers for specific commands
  553. #
  554. # Example (add to your terminal section):
  555. # sudo_password: "your-password-here"
  556. # =============================================================================
  557. # Security
  558. # =============================================================================
  559. # security:
  560. # # Private/internal addresses (localhost, 192.168.x.x, CGNAT) for web_extract,
  561. # # vision/media URL fetches and cloud/CDP browsers. The local Chromium and the
  562. # # hybrid sidecar (browser.auto_local_for_private_urls) are not covered.
  563. # # Cloud-metadata endpoints stay blocked even when true.
  564. # allow_private_urls: false
  565. # approval:
  566. # transport: builtin # Or an explicitly enabled plugin transport name
  567. # transport_fallback: deny # Set builtin to opt into fallback on transport failure
  568. # # Agent writes to instruction files that steer the agent itself
  569. # # (AGENTS.md, CLAUDE.md, SOUL.md, ...) always ask for human approval,
  570. # # even under --yolo, and are refused when nobody can answer. Set false to
  571. # # disable the gate; add fnmatch patterns on the basename to protect more files.
  572. # protected_instruction_files: true
  573. # protected_instruction_extra_patterns: []
  574. # =============================================================================
  575. # LSP Diagnostics (post-write lint for write_file / patch)
  576. # =============================================================================
  577. # lsp:
  578. # enabled: true
  579. # # Language servers only load code a project ships (its .venv interpreter,
  580. # # node_modules TypeScript, svelte.config.js, cargo/Gradle/mix build files)
  581. # # in the git worktree of the directory you launched Hermes in or opened
  582. # # the session in (hermes -w, a Desktop project, terminal.cwd), or under a
  583. # # directory listed here. In other checkouts, such as a repository the agent
  584. # # cloned, only servers that run no project code start (pinned to
  585. # # Hermes-side tools) and the npx tsc / rustfmt lint fallbacks are skipped.
  586. # trusted_workspaces:
  587. # - ~/code/my-app
  588. # =============================================================================
  589. # Browser Tool Configuration
  590. # =============================================================================
  591. browser:
  592. # Inactivity timeout in seconds - browser sessions are automatically closed
  593. # after this period of no activity between agent loops (default: 120 = 2 minutes)
  594. inactivity_timeout: 120
  595. # Local Chromium for browser_exec. Empty executable_path = pm's chromium
  596. # (`hermes pm install chromium`), the Docker image's build, or a system
  597. # chromium where pm builds none (Termux). user_data_dir keeps one persistent
  598. # profile for every local session (empty = a throwaway profile per session).
  599. # executable_path: ""
  600. # user_data_dir: ""
  601. # chromium_args: ["--lang=de"]
  602. # With a cloud provider (Browserbase, Browser Use, ...), LAN/localhost URLs
  603. # open in a local Chromium sidecar on this host instead. The sidecar ignores
  604. # security.allow_private_urls (like the plain local Chromium, it reaches what
  605. # the terminal reaches); set false to refuse private URLs instead.
  606. # auto_local_for_private_urls: true
  607. # =============================================================================
  608. # Tool Loop Guardrails
  609. # =============================================================================
  610. # Soft warnings are enabled by default. They append guidance to repeated failed
  611. # or non-progressing tool results but still let the tool execute. Hard stops stay
  612. # opt-in for interactive CLI/TUI/Desktop/ACP sessions, but default on for unattended
  613. # gateway/cron sessions where nobody is present to interrupt a model that
  614. # ignores loop warnings.
  615. tool_loop_guardrails:
  616. warnings_enabled: true
  617. hard_stop_enabled: false
  618. non_interactive_hard_stop_enabled: true
  619. warn_after:
  620. exact_failure: 2
  621. same_tool_failure: 3
  622. idempotent_no_progress: 2
  623. hard_stop_after:
  624. exact_failure: 5
  625. same_tool_failure: 8
  626. idempotent_no_progress: 5
  627. # =============================================================================
  628. # Context Compression (Auto-shrinks long conversations)
  629. # =============================================================================
  630. # When conversation approaches model's context limit, middle turns are
  631. # automatically summarized to free up space while preserving important context.
  632. #
  633. # HOW IT WORKS:
  634. # 1. Tracks actual token usage from API responses (not estimates)
  635. # 2. When prompt_tokens >= threshold% of model's context_length, triggers compression
  636. # 3. Protects first 3 turns (system prompt, initial request, first response)
  637. # 4. Protects last N turns (default 20 messages = ~10 full turns of recent context)
  638. # 5. Summarizes middle turns using a fast/cheap model
  639. # 6. Inserts summary as a user message, continues conversation seamlessly
  640. #
  641. # Post-compression tail budget is target_ratio × threshold × context_length:
  642. # 200K context, threshold 0.50, ratio 0.20 → 20K tokens of recent tail preserved
  643. # 1M context, threshold 0.50, ratio 0.20 → 100K tokens of recent tail preserved
  644. #
  645. compression:
  646. # Enable automatic context compression (default: true)
  647. # Set to false if you prefer to manage context manually or want errors on overflow
  648. enabled: true
  649. # Fail closed before lossy compaction unless an active memory provider that
  650. # implements the pre-compress checkpoint contract (API v2) confirms its
  651. # durable checkpoint (default: false). With this on and no checkpoint, the
  652. # compaction attempt errors with BLOCKED_MISSING_PREREQUISITE and the
  653. # uncompressed transcript is preserved for a later retry. The gate binds to
  654. # every compaction authority: server-side native compaction
  655. # (codex_responses_native) is suppressed while armed, post-turn
  656. # micro-compaction is forced off (no checkpoint hook in its path), and the
  657. # codex_app_server API mode is refused at agent init (the codex agent
  658. # compacts its own thread — no checkpoint can be guaranteed there). Only
  659. # enable it with a checkpoint-capable provider configured — see
  660. # website/docs/developer-guide/memory-provider-plugin.md
  661. # ("Pre-Compress Checkpoints").
  662. checkpoint_required: false
  663. # Opt-in compression progress notices on chat platforms (default: false).
  664. # By design, routine automatic compression is SILENT on human-facing chat
  665. # gateways (Telegram, Discord, Slack, ...) — it happens in the background
  666. # with server-side logging only. Set true to also deliver the routine
  667. # progress statuses (compacting started, preflight/pre-API compression,
  668. # idle compaction, retry progress, and the compaction-complete notice) to
  669. # chat platforms. Unrelated operational noise (auxiliary model failures,
  670. # provider retry chatter) stays suppressed either way, and compression
  671. # FAILURE notices + manual /compress feedback are always visible
  672. # regardless of this setting. (#52995)
  673. progress_notices: false
  674. # Trigger compression at this % of model's context limit (default: 0.50 = 50%)
  675. # Lower values = more aggressive compression, higher values = compress later
  676. # Models with context windows below 512K are floored at 0.75 (raise-only) so
  677. # compaction doesn't fire with half the window still free; set above 0.75 to override.
  678. threshold: 0.50
  679. # Per-model threshold overrides: keys are substring-matched against the model
  680. # name (longest match wins). Useful when some models need different compaction
  681. # points — e.g. a 1M-context model can compress later (0.30) while a 128K
  682. # model needs to compress earlier (0.60). The small-context floor (75% for
  683. # <512K models) still applies on top of per-model overrides.
  684. # model_thresholds:
  685. # "glm-5.2": 0.40
  686. # "claude-sonnet": 0.35
  687. # "gpt-5": 0.30
  688. # Optional absolute token cap for the compression trigger (default: null = disabled).
  689. # When set, compression fires at the LOWER of the ratio-based threshold and this
  690. # absolute token count. Clamped to the model's context length at apply-time, so a
  691. # cap above the window is a no-op. Survives model switches and fallback activations.
  692. # threshold_tokens: 200000
  693. # Existing Codex gpt-5.5 behavior: raise Hermes' compaction trigger to 85%
  694. # for the ChatGPT Codex OAuth route. Set false to opt back down to threshold.
  695. codex_gpt55_autoraise: true
  696. # Fraction of the threshold to preserve as recent tail (default: 0.20 = 20%)
  697. # e.g. 20% of 50% threshold = 10% of total context kept as recent messages.
  698. # Summary output is separately capped at 12K tokens (Gemini output limit).
  699. # Range: 0.10 - 0.80
  700. target_ratio: 0.20
  701. # Number of most-recent messages to always preserve (default: 20 ≈ 10 full turns)
  702. # Higher values keep more recent conversation intact at the cost of more aggressive
  703. # compression of older turns.
  704. protect_last_n: 20
  705. # Minimum number of REAL (actionable) user messages guaranteed to survive in
  706. # the uncompressed tail (default: 1 = the existing single last-user anchor,
  707. # behavior-preserving). Raise to e.g. 3 to keep the last 3 real user turns
  708. # verbatim even when bulky tool outputs fill the tail token budget — blank
  709. # platform echoes, compaction handoffs, and synthetic continuation rows never
  710. # count toward N. The tail can exceed the token budget when this pulls the
  711. # cut back; the guarantee wins over the budget by design.
  712. min_tail_user_messages: 1
  713. # Compression retry rounds before a turn gives up with "max compression
  714. # attempts reached" (default: 3, same as the previous hardcoded value).
  715. # Raise (e.g. 6) for tool-schema-heavy sessions where 3 rounds cannot bring
  716. # the request estimate under the threshold. Validated >= 1, hard cap 10.
  717. max_attempts: 3
  718. # Codex app-server (codex CLI runtime) thread-compaction mode. The codex
  719. # agent owns the real thread context on this runtime, so Hermes' summarizer
  720. # cannot shrink it — compaction goes through the app server instead.
  721. # native = let Codex decide when to compact its own thread (default)
  722. # hermes = let Hermes threshold trigger Codex thread/compact/start
  723. # off = Hermes will not auto-trigger compaction; Codex may still compact natively
  724. codex_app_server_auto: native
  725. # Native OpenAI Responses server-side compaction (default: false). When true,
  726. # gpt-5.6-family models on the DIRECT OpenAI API (api.openai.com) or a ChatGPT
  727. # Codex subscription, plus gpt-6-astra (and its -900k alias) on official Codex OAuth, compact
  728. # server-side: OpenAI prunes older context into an
  729. # encrypted checkpoint that Hermes replays on later turns. No other provider,
  730. # route, or model is affected. Hermes' local compression stays armed as the
  731. # fallback and still handles every non-eligible session.
  732. codex_responses_native: false
  733. # Optional absolute server compaction trigger in input tokens. The default
  734. # null value follows the resolved local compression trigger with an 8192 token
  735. # safety margin. For example, a local trigger of 765000 selects 756808.
  736. # A positive integer stays absolute and only clamps downward when needed so
  737. # the server compacts first. Invalid values use this automatic behavior. If
  738. # the local trigger is unavailable, automatic mode uses 200000.
  739. codex_responses_compact_threshold: null
  740. # Number of non-system messages to protect at the head of the transcript, in
  741. # ADDITION to the system prompt (which is always implicitly protected).
  742. # Head messages are NEVER summarized — they survive every compression
  743. # indefinitely. This gives stable early context for short/medium sessions,
  744. # but in long-running sessions that rely on rolling compaction the pinned
  745. # opening turns may not match how you want the session framed over time.
  746. # Set to 0 to preserve ONLY the system prompt (plus the rolling summary
  747. # and recent tail) — the cleanest configuration for long-running sessions.
  748. # Default 3 preserves the system prompt plus the first three non-system
  749. # head messages, matching the pre-feature behaviour.
  750. protect_first_n: 3
  751. # Idle compaction (default: 0 = disabled). When > 0, a session that resumes
  752. # after at least this many seconds of inactivity compacts its accumulated
  753. # history up front, before the first reply, so a long-lived thread you come
  754. # back to later doesn't re-read its full stale context on every turn.
  755. # Time-based, so it complements (does not replace) the size-based `threshold`
  756. # above. It is skipped when the context is already small (at or below the
  757. # post-compression target = threshold × target_ratio), so it never wastes a
  758. # summarization on a short idle thread. Example: 1800 = compact after 30 min idle.
  759. idle_compact_after_seconds: 0
  760. # Gateway session-hygiene turn-hold budget (default: 10). Max seconds an
  761. # arriving user turn is held while a still-streaming hygiene summary
  762. # finishes. Distinct from hygiene_timeout_seconds (compressor inactivity
  763. # budget): this bounds user-visible latency so chat transports (Telegram
  764. # ~30s) do not drop a silent connection. On expiry the turn proceeds
  765. # uncompressed; the detached worker keeps its commit admission (when the
  766. # commit is watermark-fenced) and the summary is adopted at the next safe
  767. # boundary. Thinking-model summarizers often need longer than 10s to emit
  768. # the first content token — raise to 300 (or >= your summarizer's real
  769. # time-to-first-content) only if you want THIS turn to wait for the
  770. # compression instead of adopting it one turn late.
  771. hygiene_max_turn_hold_seconds: 10
  772. # Proactive tool-result prune (default: 0 = disabled). Opt-in token trigger
  773. # for a deterministic, no-LLM prune of OLD tool-result payloads, run
  774. # independently of `threshold` above. On large-window models (512K/1M) the
  775. # ratio threshold rarely fires, so bulky tool outputs (terminal dumps, file
  776. # reads, web extracts) ride along in history and get re-billed every turn.
  777. # When re-sent history exceeds this many tokens, the prune dedupes identical
  778. # results, summarizes older oversized ones, and truncates large tool-call
  779. # arguments — protecting the most recent `protect_last_n` messages and never
  780. # calling the model. Try 48000 to enable. Built-in compressor engine only;
  781. # other context engines inherit a safe no-op.
  782. # NOTE: a committed prune rewrites already-sent history, which invalidates
  783. # the provider's prompt-cache prefix — the min_reclaim gate below keeps
  784. # those cache breaks episodic (like a compression boundary) instead of
  785. # per-turn.
  786. proactive_prune_tokens: 0
  787. # The prune's summarize pass only touches tool results larger than this many
  788. # characters (clamped to >= 200 so a generated summary can't be
  789. # re-summarized). Default 8000.
  790. proactive_prune_min_result_chars: 8000
  791. # A proactive prune only COMMITS when it reclaims at least this many tokens
  792. # (measured on the pruned output). This is the prompt-cache hysteresis gate:
  793. # one meaningful, amortized cache break per batch of stale tool output
  794. # instead of a tiny break on every tool iteration. 0 = commit any non-zero
  795. # prune. Default 4096.
  796. proactive_prune_min_reclaim_tokens: 4096
  797. # To pin a specific model/provider for compression summaries, use the
  798. # auxiliary section below (auxiliary.compression.provider / model).
  799. # =============================================================================
  800. # Tool-result budget (optional)
  801. # =============================================================================
  802. # Controls when a large tool result is spilled to disk (full output saved to
  803. # $HERMES_HOME/cache/spillover, preview + path kept in context). MCP tool
  804. # results (tools named mcp_*) spill at a tighter 50,000-char threshold than
  805. # the generic 100K default: MCP servers routinely return un-paginated 20-50K
  806. # payloads that bloat context and slow every subsequent turn. Nothing is
  807. # lost — the full result is on disk and readable with read_file.
  808. #
  809. # tool_budget:
  810. # mcp_result_size_chars: 50000 # per-result spillover threshold for mcp_* tools
  811. # =============================================================================
  812. # Anthropic prompt caching TTL
  813. # =============================================================================
  814. # When prompt caching is active (Claude via OpenRouter or native Anthropic),
  815. # Anthropic supports two TTL tiers for cached prefixes: "5m" (default) and
  816. # "1h". Other values are ignored and "5m" is used.
  817. #
  818. prompt_caching:
  819. cache_ttl: "5m" # use "1h" for long sessions with pauses between turns
  820. # =============================================================================
  821. # Auxiliary Models (Advanced — Experimental)
  822. # =============================================================================
  823. # Hermes uses lightweight "auxiliary" models for side tasks: image analysis,
  824. # browser screenshot analysis, web page summarization, TTS audio-tag insertion,
  825. # and context compression.
  826. #
  827. # By default these use Gemini Flash via OpenRouter or Nous Portal and are
  828. # auto-detected from your credentials. You do NOT need to change anything
  829. # here for normal usage.
  830. #
  831. # WARNING: Overriding these with providers other than OpenRouter or Nous Portal
  832. # is EXPERIMENTAL and may not work. Not all models/providers support vision,
  833. # produce usable summaries, or accept the same API format. Change at your own
  834. # risk — if things break, reset to "auto" / empty values.
  835. #
  836. # Each task has its own provider + model pair so you can mix providers.
  837. # For example: OpenRouter for vision (needs multimodal), but your main
  838. # local endpoint for compression (just needs text).
  839. #
  840. # Provider options:
  841. # "auto" - Best available: OpenRouter → Nous Portal → main endpoint (default)
  842. # "openrouter" - Force OpenRouter (requires OPENROUTER_API_KEY)
  843. # "nous" - Force Nous Portal (requires: hermes auth add nous)
  844. # "gemini" - Force Google AI Studio direct (requires: GOOGLE_API_KEY or GEMINI_API_KEY)
  845. # "ollama-cloud" - Ollama Cloud (requires: OLLAMA_API_KEY)
  846. # "codex" - Force Codex OAuth (requires: hermes model → Codex).
  847. # Uses gpt-5.3-codex which supports vision.
  848. # "main" - Use your custom endpoint (OPENAI_BASE_URL + OPENAI_API_KEY).
  849. # Works with OpenAI API, local models, or any OpenAI-compatible
  850. # endpoint. Also falls back to Codex OAuth and API-key providers.
  851. #
  852. # Model: leave empty to use the provider's default. When empty, OpenRouter
  853. # uses "google/gemini-3-flash-preview" and Nous uses "gemini-3-flash".
  854. # Other providers pick a sensible default automatically.
  855. #
  856. # Native vision embeds (vision_analyze / browser screenshots when the MAIN model
  857. # is vision-capable) ride conversation history and are re-sent on every later
  858. # API call, so both knobs below bound recurring cost:
  859. #
  860. # vision:
  861. # # Byte budget for one embedded image (clamped 64 KiB..4 MiB). Raise it for
  862. # # dense phone screenshots of tables that read as "unreadable" at 256 KB.
  863. # embed_target_bytes: 262144
  864. # # How often vision_analyze may embed the SAME image (region crops included)
  865. # # per session. Unset = 3 inside delegated subagents, unlimited for the main
  866. # # agent; a number applies everywhere; 0 = unlimited.
  867. # max_calls_per_image: 3
  868. # # Newest user images re-sent on turns rebuilt from the session DB (API server,
  869. # # --resume) when the model takes images natively; 0 = off. Older images drop
  870. # # in whole batches of this size, so the cached prefix changes once per batch.
  871. # replay_recent_images: 3
  872. #
  873. # auxiliary:
  874. # # Image analysis: vision_analyze tool + browser screenshots
  875. # vision:
  876. # provider: "auto"
  877. # model: "" # e.g. "google/gemini-2.5-flash", "openai/gpt-4o"
  878. # timeout: 30 # LLM API call timeout (seconds)
  879. # download_timeout: 30 # Image HTTP download timeout (seconds)
  880. # # Increase for slow connections or self-hosted image servers
  881. # reasoning_effort: "" # Per-task thinking level: none, minimal, low, medium,
  882. # # high, xhigh, max, ultra. Empty = provider default.
  883. # # Works on every auxiliary task block (vision,
  884. # # web_extract, compression, title_generation, curator,
  885. # # background_review, moa_reference, ...). Example: run
  886. # # compression at "low" and vision at "none" to cut
  887. # # side-task latency/cost on reasoning models.
  888. #
  889. # # Web page scraping / summarization + browser page text extraction
  890. # web_extract:
  891. # provider: "auto"
  892. # model: ""
  893. # reasoning_effort: "low"
  894. #
  895. # # Gemini 3.1 TTS hidden audio-tag insertion
  896. # tts_audio_tags:
  897. # provider: "auto" # empty model = your main chat model
  898. # model: ""
  899. # timeout: 30
  900. #
  901. # # Automatic session title generation after the first exchange
  902. # title_generation:
  903. # enabled: true # set false to disable auto-title generation
  904. # model_upgrade_enabled: true # set false to keep the instant derived title and skip the model call
  905. # provider: "auto"
  906. # model: ""
  907. # timeout: 30
  908. # language: "" # empty = match the user's language; or e.g. "English"
  909. #
  910. # # Session search — summarizes matching past sessions
  911. # session_search:
  912. # provider: "auto"
  913. # model: ""
  914. # timeout: 30
  915. # max_concurrency: 3 # Limit parallel summaries to reduce request-burst 429s
  916. # extra_body: {} # Provider-specific OpenAI-compatible request fields
  917. # # Example for providers that support request-body
  918. # # reasoning controls:
  919. # # extra_body:
  920. # # enable_thinking: false
  921. # # Some vLLM/Qwen deployments expect this nested:
  922. # # extra_body:
  923. # # chat_template_kwargs:
  924. # # enable_thinking: false
  925. #
  926. # # Auto-generated short session titles after the first exchange.
  927. # # Each active Discord/Telegram channel can spawn a background title
  928. # # call. Cap concurrency to keep retries during provider incidents
  929. # # from amplifying the request burst. Leave unset for legacy behavior
  930. # # (unlimited).
  931. # title_generation:
  932. # provider: "auto"
  933. # model: ""
  934. # # max_concurrency: 2 # Optional: cap simultaneous title calls
  935. #
  936. # # Context compression — summarizes long sessions to shrink the prompt.
  937. # # Heavy and often hits the slowest provider chain. Setting a small
  938. # # cap prevents many sessions from compressing simultaneously during
  939. # # provider degradation. Leave unset for legacy behavior (unlimited).
  940. # compression:
  941. # provider: "auto"
  942. # model: ""
  943. # # max_concurrency: 2 # Optional: cap simultaneous compression calls
  944. # # no_progress_timeout: 60 # Codex/Responses-only: seconds a stream may go without a
  945. # # substantive event before it fails fast (default: 60).
  946. # # Independent of "timeout" above (the overall request
  947. # # budget) — raising "timeout" alone does not widen this
  948. # # window. Each substantive event re-arms it; a slow but
  949. # # progressing reasoning/summary stream is not affected.
  950. #
  951. # # Post-turn memory/skill self-improvement review fork. Runs after a turn
  952. # # when the nudge intervals fire; writes skills/memories in a daemon thread.
  953. # # Usage is recorded under session_model_usage task='background_review'.
  954. # background_review:
  955. # enabled: true # false = skip automatic forks (/refine still works)
  956. # provider: "auto" # or pin a cheaper model (see memory.md)
  957. # model: ""
  958. # =============================================================================
  959. # Persistent Memory
  960. # =============================================================================
  961. # Bounded curated memory injected into the system prompt every session.
  962. # Two stores: MEMORY.md (agent's notes) and USER.md (user profile).
  963. # Character limits keep the memory small and focused. The agent manages
  964. # pruning -- when at the limit, it must consolidate or replace entries.
  965. # Disabled by default in batch_runner.
  966. #
  967. memory:
  968. # Agent's personal notes: environment facts, conventions, things learned
  969. memory_enabled: true
  970. # User profile: preferences, communication style, expectations
  971. user_profile_enabled: true
  972. # External prefetch only: opt in to head/tail previews using hooks.output_spill.
  973. # Defaults to keeping the full provider-ranked recall. Restart to apply changes.
  974. prefetch_spill_enabled: false
  975. # Character limits (~2.75 chars per token, model-independent)
  976. memory_char_limit: 2200 # ~800 tokens
  977. user_char_limit: 1375 # ~500 tokens
  978. # Periodic memory nudge: remind the agent to consider saving memories
  979. # every N user turns. Set to 0 to disable. Only active when memory is enabled.
  980. nudge_interval: 10 # Nudge every 10 user turns (0 = disabled)
  981. # =============================================================================
  982. # Session Continuity (Messaging Platforms)
  983. # =============================================================================
  984. # Conversations persist across inactivity and daily boundaries. Use /new or
  985. # /reset explicitly; context compression manages long conversations.
  986. # Maximum number of simultaneously active chat sessions across CLI, TUI,
  987. # dashboard chat, and messaging gateway. Set to null, 0, or omit to allow
  988. # unlimited concurrent sessions. When the limit is reached, new sessions get a
  989. # clean error while existing active sessions keep their normal behavior. This
  990. # top-level key takes precedence over gateway.max_concurrent_sessions. The cap
  991. # is a best-effort single-host/profile runtime guard; Hermes fails open if the
  992. # local runtime lease registry cannot be read or locked.
  993. max_concurrent_sessions: null
  994. # When true, group/channel chats use one session per participant when the platform
  995. # provides a user ID. This is the secure default and prevents users in the same
  996. # room from sharing context, interrupts, and token costs. Set false only if you
  997. # explicitly want one shared "room brain" per group/channel.
  998. group_sessions_per_user: true
  999. # =============================================================================
  1000. # Native Hosted-Room Discussion Limits
  1001. # =============================================================================
  1002. # Shared ceilings per discussion across all members, applied to all native hosted
  1003. # rooms (not Desktop renderer/mirrored rooms). Positive integers only: no 0,
  1004. # unlimited, null, booleans, strings, or floats; an invalid value is logged and
  1005. # the defaults apply. Omitted keys keep these defaults.
  1006. # Set in the root owner's config.yaml beside shared-state.db, not a member's
  1007. # profile config. Read once at startup; refresh every server process sharing the
  1008. # room database to apply (not just the service the client connects to).
  1009. # For a larger discussion budget, use max_rounds: 6 and max_messages: 30.
  1010. hosted_rooms:
  1011. discussion:
  1012. max_rounds: 3
  1013. max_messages: 10 # Total visible bot replies, not per member
  1014. # =============================================================================
  1015. # Session Storage Retention (state.db)
  1016. # =============================================================================
  1017. # ~/.hermes/state.db keeps every session, message, and tool call, plus the
  1018. # FTS5 search indexes. Auto-pruning is OFF by default; when enabled, at
  1019. # CLI/gateway/cron startup (at most once per min_interval_hours) Hermes deletes
  1020. # ENDED sessions whose last activity is older than retention_days. While
  1021. # auto_prune is unset, Hermes asks once when the disk holding state.db runs
  1022. # low (/autoprune on|off|later answers it). Open, pinned, and in-progress sessions are never
  1023. # deleted. Stale automation sessions (cron/kanban/subagent/one-shot CLI) whose
  1024. # process died without closing them are first *closed*, then aged through a
  1025. # further full retention window before removal.
  1026. #
  1027. # After a prune that removed rows, VACUUM reclaims disk space only when both
  1028. # the time throttle (min_vacuum_interval_days) has elapsed AND more than 25%
  1029. # of the file's pages are reclaimable — a dense database never pays for a full
  1030. # rewrite to reclaim a few MB.
  1031. #
  1032. # A CLI/TUI/Desktop session left with no viewer (a killed terminal, a dropped
  1033. # connection, a gateway restart) is ended by the gateway orphan_end_grace_s
  1034. # seconds later, once its running turn settles. It stays resumable, and a viewer
  1035. # that comes back within the grace keeps it open. 0 never ends it. After a
  1036. # restart it also waits out the rest of 6h since the session's last activity.
  1037. # It replaces dashboard.ws_orphan_reap_grace_s / startup_orphan_sweep for these
  1038. # sessions; while it is unset, their opt-outs (0 / false) still turn it off.
  1039. #
  1040. # Uncomment to change the defaults shown; auto_prune: true bounds the file,
  1041. # auto_prune: false keeps every ended session and silences the low-disk prompt.
  1042. # sessions:
  1043. # auto_prune: false
  1044. # retention_days: 90
  1045. # vacuum_after_prune: true
  1046. # min_vacuum_interval_days: 30
  1047. # min_interval_hours: 24
  1048. # orphan_end_grace_s: 300
  1049. # Optional direct endpoint for autonomous Bot Mode rooms spanning gateways.
  1050. # Leave unset for the safe default: Desktop coordinates cross-gateway rooms and
  1051. # same-gateway rooms can still continue on their own. Set this only to the
  1052. # public HTTPS base URL that another trusted Hermes gateway can reach. The API
  1053. # server key authorizes the initial invitation; scoped grants are signed by a
  1054. # separate installation-private secret and survive API-key rotation. Disbanding
  1055. # a Group Chat revokes its known peer routes; API-key rotation alone does not.
  1056. # Network access should still be limited to the peer gateways (for example with
  1057. # your VPN or firewall).
  1058. # Plain HTTP is accepted only for loopback testing; every reachable peer URL
  1059. # must use HTTPS.
  1060. #
  1061. # gateway:
  1062. # room_link_url: "https://hermes.example.net"
  1063. #
  1064. # The equivalent environment override is HERMES_ROOM_LINK_URL. After changing
  1065. # it, restart the gateway and reopen New Group Chat > Advanced; Hermes will
  1066. # re-check the selected gateways automatically.
  1067. # Startup sweep of session rows orphaned by a dead gateway process.
  1068. # The normal disconnect cleanup runs on an in-process grace timer, so a
  1069. # gateway restart (update, crash, systemd) leaves those rows permanently
  1070. # "active". On every gateway boot — stdio TUI *and* the desktop/dashboard
  1071. # WS sidecar — tui/desktop/subagent rows whose start time AND newest
  1072. # message are both older than the session TTL (HERMES_TUI_SESSION_TTL_S,
  1073. # default 6h) are closed with end_reason "startup_orphan_reap".
  1074. # Messaging-platform sessions (Telegram, Discord, ...) are never touched;
  1075. # live in-memory sessions are excluded; swept sessions stay resumable.
  1076. #
  1077. # dashboard:
  1078. # startup_orphan_sweep: true
  1079. # ─────────────────────────────────────────────────────────────────────────────
  1080. # API Server — per-client model routing
  1081. # ─────────────────────────────────────────────────────────────────────────────
  1082. # Route different API clients to different models/providers on a single
  1083. # Hermes deployment. Clients choose a backend by sending a specific string
  1084. # as the OpenAI ``model`` field. Unmapped model values fall back to the
  1085. # global model configured in the ``model:`` section above, and an explicit
  1086. # session /model override always wins over a route.
  1087. #
  1088. # Configure via the ``platforms.api_server.extra.model_routes`` gateway
  1089. # config block:
  1090. #
  1091. # platforms:
  1092. # api_server:
  1093. # enabled: true
  1094. # extra:
  1095. # key: "your-api-server-secret"
  1096. # model_routes:
  1097. # # Xiaozhi clients send model="minimax-m2" → routed to MiniMax via OpenRouter
  1098. # minimax-m2:
  1099. # model: "minimax/minimax-m1"
  1100. # provider: "openrouter" # optional — overrides global provider
  1101. # # api_key: "sk-..." # optional — per-route UPSTREAM provider
  1102. # # key (NOT caller auth; never logged)
  1103. # # base_url: "https://..." # optional — per-route base URL
  1104. # # GPT clients keep their own alias
  1105. # gpt-5:
  1106. # model: "openai/gpt-5"
  1107. # provider: "openrouter"
  1108. #
  1109. # Configured aliases are automatically listed by GET /v1/models so clients
  1110. # can discover them without manual coordination. Caller authentication is
  1111. # unchanged: every request still authenticates with the global API server
  1112. # key (``extra.key`` / API_SERVER_KEY).
  1113. # ─────────────────────────────────────────────────────────────────────────────
  1114. # Gateway Streaming
  1115. # ─────────────────────────────────────────────────────────────────────────────
  1116. # Stream tokens to messaging platforms in real-time. The bot sends a message
  1117. # on first token, then progressively edits it as more tokens arrive.
  1118. # Disabled by default — enable to try the streaming UX on Telegram/Discord/Slack.
  1119. # For Telegram, partial edits are sent as plain text and only the final edit uses MarkdownV2.
  1120. streaming:
  1121. enabled: false
  1122. # transport: edit # "edit" = progressive editMessageText
  1123. # edit_interval: 0.3 # seconds between message edits
  1124. # buffer_threshold: 40 # chars before forcing an edit flush
  1125. # cursor: " ▉" # cursor shown during streaming
  1126. # =============================================================================
  1127. # Skills Configuration
  1128. # =============================================================================
  1129. # Skills are reusable procedures the agent can load and follow. The agent can
  1130. # also create new skills after completing complex tasks.
  1131. #
  1132. skills:
  1133. # Nudge the agent to create skills after complex tasks.
  1134. # Every N tool-calling iterations, remind the model to consider saving a skill.
  1135. # Set to 0 to disable.
  1136. creation_nudge_interval: 15
  1137. # External skill directories — share skills across tools/agents without
  1138. # copying them into ~/.hermes/skills/. Each path is expanded (~ and ${VAR})
  1139. # and resolved to an absolute path. External dirs are read-only: skill
  1140. # creation always writes to ~/.hermes/skills/. Local skills take precedence
  1141. # when names collide.
  1142. # external_dirs:
  1143. # - ~/.agents/skills
  1144. # - /home/shared/team-skills
  1145. # =============================================================================
  1146. # Agent Behavior
  1147. # =============================================================================
  1148. agent:
  1149. # Maximum tool-calling iterations per conversation (default: 500)
  1150. # Higher = more room for complex tasks, but costs more tokens
  1151. # Recommended: 20-30 for focused tasks, 50-100 for open exploration
  1152. max_turns: 500
  1153. # Inactivity timeout for gateway agent runs (seconds, 0 = unlimited).
  1154. # The agent can run indefinitely when actively calling tools or receiving
  1155. # API responses. Only fires after the agent has been idle for this duration.
  1156. # gateway_timeout: 1800
  1157. # Maximum time an alias routing key waits for an active turn holding the same
  1158. # resolved session lease. On expiry Hermes rejects this inbound message and
  1159. # asks the user to resend rather than running it without serialization.
  1160. # Non-positive values fall back to the 5-second default.
  1161. # gateway_turn_lease_timeout: 5
  1162. # Staged warning: send a warning before escalating to full timeout.
  1163. # Fires once per run when inactivity reaches this threshold (seconds).
  1164. # Set to 0 to disable the warning.
  1165. # gateway_timeout_warning: 900
  1166. # Session stall watchdog (seconds). When a busy session has a pending
  1167. # inbound follow-up and the agent activity clock is idle this long, the
  1168. # gateway logs a WARNING and notifies the user to try /new. Does not kill
  1169. # the turn (see gateway_timeout). 0 = disable. Default 300.
  1170. # session_stall_timeout: 300
  1171. # Transcript-sanitiser repeated-heal escalation (#96870). The pre-send
  1172. # sanitiser silently repairs empty non-final turns on the wire copy; after
  1173. # this many heal passes within a 10-minute session window Hermes logs one
  1174. # ERROR (with session id + heal pattern) and sends a ONE-TIME out-of-band
  1175. # notice to the user suggesting /debug share or `hermes doctor`. The notice
  1176. # goes through the status channel only — conversation context and prompt
  1177. # caching are untouched. Set 0 to disable escalation (per-window WARNINGs
  1178. # still fire). Default 3.
  1179. # sanitizer_heal_escalation_threshold: 3
  1180. # Related in-agent compression timeouts (they live under the top-level
  1181. # compression: block, shown here for discoverability next to the stall
  1182. # watchdog they complement — a hung compression is a common stall cause):
  1183. # compression:
  1184. # context_timeout_seconds: 120 # inactivity budget for in-agent
  1185. # # compress_context (0 = disable)
  1186. # context_total_ceiling_seconds: 600 # absolute cap on the pre-commit
  1187. # # wait even while tokens stream
  1188. # Graceful drain timeout for gateway stop/restart (seconds).
  1189. # Default 0 = no drain: a restart interrupts in-flight agents immediately,
  1190. # cleans up, and exits. Set a positive value only if you want a grace
  1191. # window on /restart, and keep it well under systemd's TimeoutStopSec.
  1192. # restart_drain_timeout: 0
  1193. # Floor under the same drain for cron jobs and api_server (/v1) runs
  1194. # (seconds). Default 30.
  1195. # restart_drain_timeout above is written for chat turns, which are cheap to
  1196. # interrupt: the user is told the gateway is restarting and the session
  1197. # resumes on their next message. A cron run has no such safety net — it is
  1198. # recorded in jobs.json as a permanent failure, nobody is waiting on it, and
  1199. # a recurring job simply skips to its next schedule. So in-flight cron work
  1200. # gets its own grace window instead of inheriting the 0 above, and so do
  1201. # api_server (/v1) runs: an interrupted /v1 run fails its waiting caller.
  1202. # Clamped at runtime to the shutdown-watchdog leash (restart_drain_timeout
  1203. # + 60s) minus teardown headroom, so values past ~50s need a matching
  1204. # TimeoutStopSec bump to take effect. Set 0 to opt out and drain cron and
  1205. # /v1 runs on restart_drain_timeout like before.
  1206. # cron_drain_timeout: 30
  1207. # In-band restart wait (seconds) for active turns to finish BEFORE stop()
  1208. # begins. /restart and SIGUSR1 refuse new work, then wait up to this cap for
  1209. # in-flight agent, cron and API runs to complete so the requesting turn is
  1210. # not cut off by restart_drain_timeout. 0 = enter stop()/drain immediately.
  1211. # Excluded from the wait: wedged runs, and cron runs already handed to a
  1212. # worker in its own restart-safe systemd scope (they outlive the restart).
  1213. # The default (30 min) is a safety valve for wedged agents, not a target
  1214. # latency; raise it for long unattended turns. Env: HERMES_RESTART_AFTER_TURN_TIMEOUT.
  1215. # restart_after_turn_timeout: 1800
  1216. # Upper bound (seconds) a submitted prompt waits for the deferred agent
  1217. # build (MCP discovery, model metadata, skills scan) before failing with a
  1218. # visible error. The wait is patient — the message is delivered as soon as
  1219. # the build completes, and a progress notice is shown past 30s — so this cap
  1220. # only fires on a genuinely hung build. Raise it for deployments with many
  1221. # slow or unreachable MCP servers. Default 600.
  1222. # build_wait_timeout: 600
  1223. # Max app-level retry attempts for API errors (connection drops, provider
  1224. # timeouts, 5xx, etc.) before the agent surfaces the failure. Lower this
  1225. # to 1 if you use fallback providers and want fast failover on flaky
  1226. # primaries (default 3). The OpenAI SDK does its own low-level retries
  1227. # underneath this wrapper — this is the Hermes-level loop.
  1228. # api_max_retries: 3
  1229. # Once api_max_retries AND the fallback chain are spent on a transient outage
  1230. # (5xx, overloaded/529, connect/read timeouts) and nothing has been delivered
  1231. # yet, Hermes waits and retries this many more cycles (jittered 15/30/60/60/60s;
  1232. # a provider Retry-After wins, up to 120s) showing "Provider temporarily
  1233. # unavailable — retrying automatically in Ns (cycle k/5); press Esc to stop"
  1234. # instead of ending the turn. Auth/format/billing/policy errors never enter.
  1235. # Set 0 to disable (default 5).
  1236. # auto_recovery_cycles: 5
  1237. # After the agent edits code without fresh passing verification, nudge it to
  1238. # verify before finishing. Off by default (false). Set true to force it on
  1239. # everywhere, or "auto" for the surface-aware mode: on for interactive
  1240. # coding surfaces (CLI, TUI, desktop) and programmatic callers, off on
  1241. # conversational messaging surfaces (Telegram, Discord, etc.) where the
  1242. # verification summary would reach a human as chat noise. The
  1243. # HERMES_VERIFY_ON_STOP env var (1/0) takes precedence.
  1244. # verify_on_stop: false
  1245. # Standing operator instructions for the coding posture (when Hermes is in a
  1246. # code workspace). Appended to the coding brief as an extra system block, so
  1247. # you can pin project-wide workflow rules without editing the shipped brief.
  1248. # Accepts a string or a list of strings. Takes effect next session.
  1249. # coding_instructions:
  1250. # - "For UI work, don't run tsc/lint until I approve the look."
  1251. # - "Clean the diff before you commit and push."
  1252. # When verify-on-stop finds edited code without fresh verification evidence,
  1253. # append guidance for creative UI work (avoid broad tsc/lint/test before visual
  1254. # approval) and clean-diff expectations. Set false to keep that nudge terse.
  1255. # verify_guidance: true
  1256. # A `pre_verify` hook (plugin or shell, see Event Hooks docs) can keep the
  1257. # agent going one more turn to verify/clean before finishing. This caps how
  1258. # many times one turn may be nudged to continue, so a hook can't trap the loop.
  1259. # Default 3.
  1260. # max_verify_nudges: 3
  1261. # Enable verbose logging
  1262. verbose: false
  1263. # Reasoning effort level (OpenRouter and Nous Portal)
  1264. # Controls how much "thinking" the model does before responding.
  1265. # Options: "xhigh" (max), "high", "medium", "low", "minimal", "none" (disable)
  1266. # Providers with bespoke thinking tiers (a relay serving fast/thinking): use the
  1267. # dict form and the level is sent verbatim. Bare strings stay strict (typo guard).
  1268. # reasoning_effort:
  1269. # enabled: true
  1270. # effort: thinking
  1271. reasoning_effort: "medium"
  1272. # Per-model reasoning effort overrides (optional dict)
  1273. # Key: any sensible model spelling works (exact, dots↔dashes interchangeable,
  1274. # provider prefix optional). First match wins.
  1275. # Value: reasoning effort level (same options as reasoning_effort, dict form included)
  1276. # Override the global reasoning_effort for that specific model.
  1277. # NOTE: no `hermes config set` support for this key -- edit YAML directly.
  1278. # reasoning_overrides:
  1279. # "openrouter/anthropic/claude-opus-4.5": "xhigh"
  1280. # "openai/gpt-5": "low"
  1281. # "claude-opus-4.6": "high" # bare model name also works
  1282. # "deepseek/deepseek-v4-pro": "xhigh" # dots and dashes are interchangeable
  1283. reasoning_overrides: {}
  1284. # Fast mode (OpenAI Priority Processing / xAI Grok 4.6 / Anthropic Fast Mode
  1285. # on Opus 4.8+). Premium pricing; only sent to first-party endpoints.
  1286. # "" / "normal" - off (default)
  1287. # "fast" - every request
  1288. # "auto" - only the first fast_auto_seconds of every turn
  1289. # "cold" - that window on the first turn of a session only
  1290. # Also: /fast normal|fast|auto|cold [--global]
  1291. service_tier: ""
  1292. fast_auto_seconds: 60
  1293. # OpenAI Daybreak (Trusted Access for Cyber) on the ChatGPT/Codex
  1294. # subscription. Sent only on models your account's Codex catalog lists for
  1295. # it; Desktop shows the switch on those models. Grants no access itself.
  1296. daybreak: false
  1297. # Custom personalities (use with /personality command).
  1298. # Built-ins (helpful, concise, technical, creative, teacher, kawaii, catgirl,
  1299. # pirate, shakespeare, surfer, noir, uwu, philosopher, hype) are always
  1300. # available on every surface — defined once in hermes_cli/personality.py.
  1301. # Entries here ADD new personalities or OVERRIDE a built-in by name.
  1302. # The active selection is stored in display.personality (never here, and
  1303. # never in agent.system_prompt — that field is your manual system prompt).
  1304. personalities: {}
  1305. # mentor: "You are a supportive mentor. Guide, don't lecture."
  1306. # reviewer:
  1307. # system_prompt: "You are a meticulous code reviewer."
  1308. # tone: "direct"
  1309. # style: "terse"
  1310. # =============================================================================
  1311. # Gateway Lifecycle
  1312. # =============================================================================
  1313. gateway:
  1314. # Post-interrupt grace for running agents during an unexpected SIGTERM.
  1315. # Adapter, bridge, and database teardown starts after this many seconds even
  1316. # if an agent has not unwound. Keep it below the service-manager stop budget.
  1317. # signal_interrupt_grace_timeout: 1
  1318. # Let platform adapters honor HTTP_PROXY / HTTPS_PROXY / NO_PROXY (and
  1319. # SSL_CERT_FILE) from the process environment, plus macOS system-proxy
  1320. # auto-detection. Set to false when the gateway inherits a proxy it must not
  1321. # use (e.g. a Windows Scheduled Task picking up a local Clash/V2Ray proxy that
  1322. # isn't running). Explicit per-platform vars like DISCORD_PROXY still apply.
  1323. # trust_env: true
  1324. # =============================================================================
  1325. # Toolsets
  1326. # =============================================================================
  1327. # Control which tools the agent has access to.
  1328. # Use `hermes tools` to interactively enable/disable tools per platform.
  1329. # =============================================================================
  1330. # Platform Toolsets (per-platform tool configuration)
  1331. # =============================================================================
  1332. # Override which toolsets are available on each platform.
  1333. # If a platform isn't listed here, its built-in default is used.
  1334. #
  1335. # You can use EITHER:
  1336. # - A preset like "hermes-cli" or "hermes-telegram" (curated tool set)
  1337. # - A list of individual toolsets to compose your own (see list below)
  1338. #
  1339. # Supported platform keys: cli, telegram, discord, whatsapp, slack, qqbot, teams, google_chat
  1340. #
  1341. # Examples:
  1342. #
  1343. # # Use presets (same as defaults):
  1344. # platform_toolsets:
  1345. # cli: [hermes-cli]
  1346. # telegram: [hermes-telegram]
  1347. #
  1348. # # Custom: give Telegram only web + terminal + file + planning:
  1349. # platform_toolsets:
  1350. # telegram: [web, terminal, file, todo]
  1351. #
  1352. # # Custom: CLI without browser or image gen:
  1353. # platform_toolsets:
  1354. # cli: [web, terminal, file, skills, todo, tts, cronjob]
  1355. #
  1356. # # Restrictive: Discord gets read-only tools only:
  1357. # platform_toolsets:
  1358. # discord: [web, vision, skills, todo]
  1359. #
  1360. # If not set, defaults are:
  1361. # cli: hermes-cli (everything + cronjob management)
  1362. # telegram: hermes-telegram (terminal, file, web, vision, image, tts, browser, skills, todo, cronjob, messaging)
  1363. # discord: hermes-discord (same as telegram)
  1364. # whatsapp: hermes-whatsapp (same as telegram)
  1365. # slack: hermes-slack (same as telegram)
  1366. # signal: hermes-signal (same as telegram)
  1367. # qqbot: hermes-qqbot (same as telegram)
  1368. # teams: hermes-teams (same as telegram)
  1369. # google_chat: hermes-google_chat (same as telegram)
  1370. #
  1371. platform_toolsets:
  1372. cli: [hermes-cli]
  1373. telegram: [hermes-telegram]
  1374. discord: [hermes-discord]
  1375. whatsapp: [hermes-whatsapp]
  1376. slack: [hermes-slack]
  1377. signal: [hermes-signal]
  1378. qqbot: [hermes-qqbot]
  1379. yuanbao: [hermes-yuanbao]
  1380. # Plugin platforms (teams, google_chat, ...) need no row: they default to hermes-<platform> once loaded.
  1381. # =============================================================================
  1382. # Gateway Platform Settings
  1383. # =============================================================================
  1384. # Optional per-platform messaging settings.
  1385. # Platform-specific knobs live under `extra`.
  1386. #
  1387. # platforms:
  1388. # telegram:
  1389. # reply_to_mode: "first" # off | first | all
  1390. # # guest_mode lets explicit @mentions from non-allowlisted groups through.
  1391. # # Default false; ordinary messages, replies, and regex wake words stay blocked.
  1392. # guest_mode: false
  1393. # # allowed_chats: ["-1001234567890"]
  1394. # extra:
  1395. # drop_pending_on_cold_boot: true # Drop Telegram's queued updates on a cold boot (default). Set false on hosts that power off, so messages sent while offline are delivered on the next start; watcher reconnects always preserve them
  1396. # disable_link_previews: false # Set true to suppress Telegram URL previews in bot messages
  1397. # rich_messages: false # Bot API 10.1 rich messages (tables/task lists/details/math); default false for copyable legacy MarkdownV2, set true to opt in
  1398. # rich_drafts: false # Experimental rich draft previews during Telegram DM streaming; default false because Telegram Desktop/macOS can visually overlay draft frames
  1399. # allow_cjk_rich_messages: false # Keep CJK content on the safe MarkdownV2 path unless an unaffected client explicitly opts in to native rich rendering
  1400. # command_menu:
  1401. # # Telegram allows up to 100 BotCommands; Hermes defaults to 60 so
  1402. # # all built-in commands plus common skill commands stay visible
  1403. # # while remaining under Telegram's payload-size limit. Clamped 1..100.
  1404. # max_commands: 60
  1405. # # prepend = user priority first, then Hermes defaults
  1406. # # append = Hermes defaults first, then user priority
  1407. # # replace = only the list below defines priority
  1408. # priority_mode: prepend
  1409. # # Priority is applied across core + plugin + skill commands before
  1410. # # the cap, so a listed skill command always keeps a menu slot.
  1411. # priority:
  1412. # - my_plugin_command
  1413. # - my-important-skill
  1414. # matrix:
  1415. # channel_overrides:
  1416. # "!exampleTeamRoom:example.org":
  1417. # # Successful explicit NO_REPLY/[SILENT] finals stay silent, even when addressed.
  1418. # # Omitted/null/false keeps the current reply policy; failures remain visible.
  1419. # # Restart the gateway after changing room overrides.
  1420. # allow_silence: true
  1421. # slack:
  1422. # extra:
  1423. # # Render live tool calls as Slack-native plan/task cards. This explicit
  1424. # # opt-in works even though Slack text tool_progress defaults to off.
  1425. # native_task_cards: false
  1426. # # Slack user IDs whose Web-API posts (user token, e.g. your own
  1427. # # dashboard/mobile front-end) count as human instead of being dropped
  1428. # # as app traffic. Narrower than allow_bots: all. Users only — never apps.
  1429. # api_human_users: ["U0AAAAAAA", "U0BBBBBBB"]
  1430. # # Suppress automatic link-preview cards without removing clickable links.
  1431. # # Omit either key to preserve Slack's default for that preview type.
  1432. # unfurl_links: false
  1433. # unfurl_media: false
  1434. # webhook:
  1435. # extra:
  1436. # # Route scripts default to a 30 second timeout. Scripts must live under
  1437. # # the active profile's scripts directory and receive webhook JSON on stdin.
  1438. # script_timeout_seconds: 30
  1439. # # Public HTTPS origin in front of this listener; MCP servers with
  1440. # # `events: true` POST event deliveries to <public_url>/webhooks/<route>.
  1441. # public_url: "https://hermes.example.com"
  1442. #
  1443. # Discord-specific settings (config.yaml top-level, not under platforms:):
  1444. #
  1445. # discord:
  1446. # require_mention: true # Require @mention in server channels (default: true)
  1447. # bots_require_inline_mention: true # Bot authors must type a literal @mention (default: true)
  1448. # auto_thread: true # Auto-create thread on @mention (default: true)
  1449. # free_response_auto_thread: false # Free-response channels also auto-thread (default: reply inline)
  1450. # free_response_channels: "" # Channel IDs where no mention is needed
  1451. # reactions: true # Show processing reactions (default: true)
  1452. # history_backfill: true # Recover missed channel messages on mention (default: true)
  1453. # history_backfill_limit: 50 # Max messages to scan backwards (default: 50)
  1454. # ─────────────────────────────────────────────────────────────────────────────
  1455. # Available toolsets (use these names in platform_toolsets or the toolsets list)
  1456. #
  1457. # Run `hermes chat --list-toolsets` to see all toolsets and their tools.
  1458. # Run `hermes chat --list-tools` to see every individual tool with descriptions.
  1459. # ─────────────────────────────────────────────────────────────────────────────
  1460. #
  1461. # INDIVIDUAL TOOLSETS (compose your own):
  1462. # web - web_search, web_extract
  1463. # search - web_search only (no scraping)
  1464. # terminal - terminal, process
  1465. # file - read_file, write_file, patch, search
  1466. # browser - browser_exec, browser_cdp, browser_dialog, browser_vault
  1467. # (local Chromium, or a cloud browser with its API key)
  1468. # vision - vision_analyze (requires OPENROUTER_API_KEY)
  1469. # image_gen - image_generate (requires FAL_KEY)
  1470. # skills - skills_list, skill_view
  1471. # skills_hub - skill_hub (search/install/manage from online registries — user-driven only)
  1472. # todo - todo (in-memory task planning, no deps)
  1473. # tts - text_to_speech (Edge TTS free, or ELEVENLABS/OPENAI/MINIMAX/MISTRAL key)
  1474. # cronjob - cronjob (create/list/update/pause/resume/run/remove scheduled tasks)
  1475. #
  1476. # PRESETS (curated bundles):
  1477. # hermes-cli - All of the above except send_message
  1478. # hermes-telegram - terminal, file, web, vision, image_gen, tts, browser,
  1479. # skills, todo, cronjob, send_message
  1480. # hermes-discord - Same as hermes-telegram
  1481. # hermes-whatsapp - Same as hermes-telegram
  1482. # hermes-slack - Same as hermes-telegram
  1483. #
  1484. # COMPOSITE:
  1485. # debugging - terminal + web + file
  1486. # safe - web + vision (no terminal access)
  1487. # all - Everything available
  1488. #
  1489. # web - Web search and content extraction (web_search, web_extract)
  1490. # search - Web search only, no scraping (web_search)
  1491. # terminal - Command execution and process management (terminal, process)
  1492. # file - File operations: read, write, patch, search
  1493. # browser - Browser automation over CDP (browser_exec drives a real Chromium)
  1494. # vision - Image analysis (vision_analyze)
  1495. # image_gen - Image generation with FLUX (image_generate)
  1496. # skills - Load skill documents (skills_list, skill_view)
  1497. # todo - Task planning and tracking for multi-step work
  1498. # memory - Persistent memory across sessions (personal notes + user profile)
  1499. # session_search - Search and recall past conversations (FTS5 + Gemini Flash summarization)
  1500. # tts - Text-to-speech (Edge TTS free, ElevenLabs, OpenAI, MiniMax, Mistral)
  1501. # cronjob - Schedule and manage automated tasks (CLI-only)
  1502. #
  1503. # Composite toolsets:
  1504. # debugging - terminal + web + file (for troubleshooting)
  1505. # safe - web + vision (no terminal access)
  1506. # NOTE: The top-level "toolsets" key is deprecated and ignored.
  1507. # Tool configuration is managed per-platform via platform_toolsets above.
  1508. # Use `hermes tools` to configure interactively, or edit platform_toolsets directly.
  1509. #
  1510. # CLI override: hermes chat --toolsets terminal,web,file
  1511. # =============================================================================
  1512. # MCP (Model Context Protocol) Servers
  1513. # =============================================================================
  1514. # Connect to external MCP servers to add tools from the MCP ecosystem.
  1515. # Each server's tools are automatically discovered and registered.
  1516. # See website/docs/user-guide/features/mcp.md for full documentation.
  1517. #
  1518. # Stdio servers (spawn a subprocess):
  1519. # command: the executable to run
  1520. # args: command-line arguments
  1521. # env: environment variables (only these + safe defaults passed to subprocess)
  1522. #
  1523. # HTTP servers (connect to a URL):
  1524. # url: the MCP server endpoint
  1525. # headers: HTTP headers (e.g., for authentication)
  1526. #
  1527. # Optional per-server settings:
  1528. # timeout: tool call timeout in seconds (default: 120)
  1529. # connect_timeout: initial connection timeout (default: 60)
  1530. # keepalive_interval: liveness ping cadence in seconds (floored at 5s).
  1531. # HTTP servers default to 180s; lower it below the server's session TTL for
  1532. # servers that expire idle sessions quickly (e.g. Unreal Engine editor MCP,
  1533. # ~15s), otherwise idle tool calls hit an expired session and pay a slow
  1534. # reconnect. Stdio servers disable keepalive by default; set this explicitly
  1535. # to opt a stdio server in.
  1536. # lazy: register the server's tools from the on-disk schema cache at startup
  1537. # and only spawn/connect it on the first tool call (default: false). Saves
  1538. # one child process per server in processes that rarely call tools. Needs
  1539. # one prior live connect to populate the cache; a missing or stale cache
  1540. # entry falls back to the normal eager connect. The banner and the TUI show
  1541. # such a server as "lazy" with its cached tool count until it is first used.
  1542. #
  1543. # mcp_servers:
  1544. # time:
  1545. # command: uvx
  1546. # args: ["mcp-server-time"]
  1547. # filesystem:
  1548. # command: npx
  1549. # args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
  1550. # notion:
  1551. # url: https://mcp.notion.com/mcp
  1552. # github:
  1553. # command: npx
  1554. # args: ["-y", "@modelcontextprotocol/server-github"]
  1555. # env:
  1556. # GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."
  1557. #
  1558. # Sampling (server-initiated LLM requests) — enabled by default.
  1559. # Per-server config under the 'sampling' key:
  1560. # analysis:
  1561. # command: npx
  1562. # args: ["-y", "analysis-server"]
  1563. # sampling:
  1564. # enabled: true # default: true
  1565. # model: "gemini-3-flash" # override model (optional)
  1566. # max_tokens_cap: 4096 # max tokens per request
  1567. # timeout: 30 # LLM call timeout (seconds)
  1568. # max_rpm: 10 # max requests per minute
  1569. # allowed_models: [] # model whitelist (empty = all)
  1570. # max_tool_rounds: 5 # tool loop limit (0 = disable)
  1571. # expose_client_tools: false # advertise extended sampling.tools capability
  1572. # log_level: "info" # audit verbosity
  1573. #
  1574. # MCP events (experimental, webhook delivery) — opt-in per server. Adds the
  1575. # list_event_types / subscribe_event / unsubscribe_event tools; needs
  1576. # platforms.webhook.extra.public_url and a running gateway:
  1577. # feeds:
  1578. # url: https://feeds.example.com/mcp
  1579. # events: true
  1580. # =============================================================================
  1581. # Text-to-Speech
  1582. # =============================================================================
  1583. # TTS defaults to Edge TTS unless changed in ~/.hermes/config.yaml.
  1584. # Gemini TTS supports persona/director prompt files, and Gemini 3.1 Flash TTS
  1585. # can use a hidden auxiliary rewrite pass to insert expressive square-bracket
  1586. # audio tags into the TTS script without showing tags in chat.
  1587. #
  1588. # tts:
  1589. # provider: "gemini"
  1590. # speed: 1.0 # global speed multiplier (provider-specific overrides this)
  1591. # # Per-platform audio upload limits. Built-in defaults: discord 10 MiB,
  1592. # # telegram 50 MiB, everything else 10 MiB, each with safety_ratio 0.85
  1593. # # (the fraction of max_file_bytes actually targeted). Override per platform:
  1594. # delivery_profiles:
  1595. # telegram:
  1596. # max_file_bytes: 52428800
  1597. # safety_ratio: 0.85
  1598. # gemini:
  1599. # model: "gemini-3.1-flash-tts-preview"
  1600. # voice: "Kore"
  1601. # audio_tags: false
  1602. # persona_prompt_file: "" # e.g. ~/.hermes/tts/radio-host.md
  1603. # xai:
  1604. # voice_id: "eve" # built-in or custom voice ID from xAI Console
  1605. # language: "en" # BCP-47 code ("en", "pt-BR") or "auto"
  1606. # speed: 1.0 # 0.7-1.5 playback speed
  1607. # auto_speech_tags: false # insert expressive audio tags via LLM rewrite
  1608. # text_normalization: false # normalize numbers/abbreviations/symbols
  1609. # optimize_streaming_latency: 0 # 0-2, trades quality for lower latency
  1610. # sample_rate: 24000 # 22050 / 24000 / 44100 / 48000
  1611. # bit_rate: 128000 # MP3 bitrate (codec=mp3 only)
  1612. # =============================================================================
  1613. # Voice Transcription (Speech-to-Text)
  1614. # =============================================================================
  1615. # Automatically transcribe voice messages on messaging platforms.
  1616. # Providers: local (free, faster-whisper) | groq (free tier) | openai (Whisper API) | mistral (Voxtral Transcribe)
  1617. # Set the corresponding API key in .env: GROQ_API_KEY, OPENAI_API_KEY, or MISTRAL_API_KEY.
  1618. stt:
  1619. enabled: true
  1620. # provider: "local" # auto-detected if omitted
  1621. # --- Cloud pre-upload silence trim (groq/openai/mistral/xai/elevenlabs/deepinfra) ---
  1622. # Local whisper gets Silero VAD; cloud endpoints otherwise receive raw audio —
  1623. # silence inflates upload time, per-audio-minute billing, and hallucination risk.
  1624. # Collapses pauses with ffmpeg client-side; clips under 12s skip the trim, and
  1625. # on any failure the original uploads untouched.
  1626. # cloud_trim_silence: true # set false to always upload the original audio
  1627. # cloud_trim_threshold_db: -40 # audio quieter than this counts as silence
  1628. # cloud_trim_keep_ms: 300 # how much of each pause survives (keeps natural pacing)
  1629. # Optional static transcription prompt: vocabulary/context hints for
  1630. # prompt-capable backends. Composition is deterministic: this config value
  1631. # is the base, then `pre_transcription` hooks run in registration order with
  1632. # last-writer-wins semantics per field.
  1633. #
  1634. # Privacy: the final prompt is sent to the configured STT provider alongside
  1635. # the audio. Do not include secrets or session context you would not send to
  1636. # that provider.
  1637. #
  1638. # Length / truncation contract: Whisper-family backends (local, openai,
  1639. # groq, deepinfra) only use the final ~224 prompt tokens, so Hermes
  1640. # truncates longer prompts client-side (keeping the tail) with a WARNING
  1641. # log — never an error. Other backends own their own validation.
  1642. #
  1643. # Provider behavior:
  1644. # local (faster-whisper) -> `initial_prompt`, forwarded unchanged
  1645. # openai / groq -> `prompt`, forwarded unchanged
  1646. # mistral -> `prompt`, forwarded unchanged
  1647. # deepinfra -> OpenAI-compatible `prompt`, unchanged
  1648. # local_command/xai/
  1649. # elevenlabs -> unsupported; DEBUG log, then continue
  1650. # plugin providers -> `prompt` in `**extra`; plugin owns limits
  1651. # prompt: "Hermes, Teknium, Nous Research, kanban"
  1652. local:
  1653. model: "base" # tiny | base | small | medium | large-v3 | turbo
  1654. # language: "" # blank = inherit stt.language; set "en", "es", "fr", etc. to force
  1655. # initial_prompt: "" # Optional faster-whisper prompt, e.g. bias Chinese output to simplified Chinese
  1656. # --- Anti-hallucination hardening (whisper decodes junk from silence without these) ---
  1657. # vad: true # Silero VAD filter (default on) — silence never reaches whisper.
  1658. # # Set false to restore raw behavior (e.g. transcribing music/ambient audio).
  1659. # vad_min_silence_ms: 500 # min silence (ms) that splits speech chunks when vad is on
  1660. # no_speech_prob_threshold: 0.6 # drop a segment only if no_speech_prob > this...
  1661. # logprob_threshold: -1.0 # ...AND avg_logprob < this (both must hit — quiet real speech survives)
  1662. # unload_after_idle_seconds: 0 # 0=never unload (default); e.g. 300 releases the model after 5min idle (frees VRAM on GPU; next voice message reloads it)
  1663. language: "en" # Global hint; a nonempty provider language wins. Blank falls back to HERMES_LOCAL_STT_LANGUAGE, then auto-detect.
  1664. # groq:
  1665. # model: "whisper-large-v3-turbo"
  1666. # language: "" # blank inherits stt.language, then HERMES_LOCAL_STT_LANGUAGE
  1667. openai:
  1668. model: "whisper-1" # whisper-1 | gpt-4o-mini-transcribe | gpt-4o-transcribe | gpt-transcribe
  1669. language: "" # blank = inherit stt.language; set "en", "es", "fr", etc. to force
  1670. timeout: 60 # request timeout in seconds; increase for self-hosted model cold starts
  1671. max_retries: 1 # OpenAI SDK transport retries; set 0 to disable
  1672. # mistral:
  1673. # model: "voxtral-mini-latest" # voxtral-mini-latest | voxtral-mini-2602
  1674. # xai:
  1675. # # Sent as the multipart ``model`` field. Hermes uses 2.0 by default;
  1676. # # pin 1.0 only if a rollback is needed.
  1677. # model: "grok-voice-transcribe-2.0" # or grok-voice-transcribe-1.0
  1678. # # language: "" # blank = stt.language > HERMES_LOCAL_STT_LANGUAGE > auto-detect
  1679. # deepinfra:
  1680. # # Model id is discovered live from the DeepInfra catalog filtered
  1681. # # by the `stt` surface tag — leave `model` blank to take the first
  1682. # # live result. Pin only when you need a specific Whisper variant.
  1683. # model: ""
  1684. # Custom command providers (stt.providers.<name>: type: command) can
  1685. # normalize browser WebM/Opus and other input formats to 16 kHz mono m4a
  1686. # before substituting {input_path}. This is opt-in so CLIs that already
  1687. # accept arbitrary containers (e.g. whisper.cpp) remain unchanged.
  1688. # providers:
  1689. # custom-asr:
  1690. # type: "command"
  1691. # command: "custom-asr --input {input_path} --output {output_path}"
  1692. # normalize: true # requires ffmpeg; default false
  1693. # Text-to-speech. Only the deepinfra block is documented here — the
  1694. # remaining providers (edge, openai, xai, minimax, mistral, gemini,
  1695. # elevenlabs, neutts, kittentts, piper) inherit sensible defaults from
  1696. # DEFAULT_CONFIG in hermes_cli/config.py.
  1697. # tts:
  1698. # provider: "deepinfra"
  1699. # deepinfra:
  1700. # # Model id is discovered live from the DeepInfra catalog filtered
  1701. # # by the `tts` surface tag — leave `model` blank to take the first
  1702. # # live result.
  1703. # model: ""
  1704. # voice: "default"
  1705. # "Hey Hermes" hands-free wake word (off by default; toggle with /wake).
  1706. # Full engine/provider options inherit from DEFAULT_CONFIG in
  1707. # hermes_cli/config_defaults.py — only capture placement is documented here.
  1708. # wake_word:
  1709. # enabled: false
  1710. # capture: "auto" # auto | local | client
  1711. # # auto: backend PortAudio mic when one exists; a remote
  1712. # # desktop on a mic-less (headless/VPS) backend
  1713. # # streams its own mic via the wake.feed RPC.
  1714. # # local: always the backend mic (wake_word.input_device).
  1715. # # client: always desktop-streamed PCM (detection stays
  1716. # # on the backend).
  1717. # Image generation. Each provider plugin reads its own ``image_gen.<name>``
  1718. # block; deepinfra discovers models live from
  1719. # api.deepinfra.com/v1/openai/models filtered by the ``image-gen`` tag —
  1720. # no model id is hardcoded, so retired models disappear automatically.
  1721. # image_gen:
  1722. # provider: "deepinfra"
  1723. # deepinfra:
  1724. # # Leave `model` blank for the first live `image-gen`-tagged result.
  1725. # model: ""
  1726. # =============================================================================
  1727. # Response Pacing (Messaging Platforms)
  1728. # =============================================================================
  1729. # Add human-like delays between message chunks.
  1730. # human_delay:
  1731. # mode: "off" # "off" | "natural" | "custom"
  1732. # min_ms: 800 # Min delay (custom mode only)
  1733. # max_ms: 2500 # Max delay (custom mode only)
  1734. # =============================================================================
  1735. # Session Logging
  1736. # =============================================================================
  1737. # Session trajectories are automatically saved to logs/ directory.
  1738. # Each session creates: logs/session_YYYYMMDD_HHMMSS_UUID.json
  1739. #
  1740. # The session ID is displayed in the welcome banner for easy reference.
  1741. # Logs contain full conversation history in trajectory format:
  1742. # - System prompt, user messages, assistant responses
  1743. # - Tool calls with inputs/outputs
  1744. # - Timestamps for debugging
  1745. #
  1746. # No configuration needed - logging is always enabled.
  1747. # To disable, you would need to modify the source code.
  1748. # =============================================================================
  1749. # Code Execution Sandbox (Programmatic Tool Calling)
  1750. # =============================================================================
  1751. # The execute_code tool runs Python scripts that call Hermes tools via RPC.
  1752. # Intermediate tool results stay out of the LLM's context window.
  1753. code_execution:
  1754. timeout: 300 # Max seconds per script before kill (default: 300 = 5 min)
  1755. max_tool_calls: 50 # Max RPC tool calls per execution (default: 50)
  1756. # Local execution uses a persistent session kernel: variables, imports, and
  1757. # loaded data survive across execute_code calls in one conversation, so
  1758. # multi-step data work stops re-loading its inputs every call. Pass
  1759. # reset=true on a call to discard state; a timed-out/interrupted cell kills
  1760. # the kernel (next call starts fresh). Remote terminal backends currently
  1761. # run per-call (remote kernel host is tracked follow-up work). Security
  1762. # scrubbing, tool whitelist, and output redaction are identical either way.
  1763. # kernel_idle_timeout: 1800 # Reap kernels idle longer than this (seconds)
  1764. # max_session_kernels: 4 # Process-wide LRU cap on live kernels
  1765. # =============================================================================
  1766. # Subagent Delegation
  1767. # =============================================================================
  1768. # The delegate_task tool spawns child agents with isolated context.
  1769. # Supports single tasks and batch mode (default 3 parallel, configurable).
  1770. delegation:
  1771. # backend: "default" # Strategy routing each delegate_task task: "default" = the keys below,
  1772. # else the parent's route. model_map / profile_routes come from the
  1773. # advanced-delegation plugin; a backend that is missing, disabled or
  1774. # unavailable fails closed (tool error naming it; /delegation default or
  1775. # `hermes config set delegation.backend default` restores the default).
  1776. # backends: # Each plugin backend's own settings, keyed by its backend name.
  1777. # model_map: # backend: model_map (advanced-delegation)
  1778. # options:
  1779. # - name: fast
  1780. # description: "Cheap and quick; lookups, summaries, simple edits."
  1781. # provider: "openrouter"
  1782. # model: "google/gemini-3-flash-preview"
  1783. # - name: deep
  1784. # description: "Slow and careful; hard debugging and design work."
  1785. # provider: "anthropic"
  1786. # model: "claude-opus-5"
  1787. # reasoning_effort: "high"
  1788. # service_tier: "fast" # optional: that task is refused when the route has no such tier
  1789. # # fallback_providers: [...] # optional; absent = delegation.fallback_providers, [] = none
  1790. # default: fast # optional: option for tasks that set none
  1791. # profile_routes: # backend: profile_routes (advanced-delegation). A listed
  1792. # profiles: # profile's subagents use ITS credentials, pool, SOUL.md and terminal policy.
  1793. # - name: coder
  1794. # description: "Writes and refactors code; runs tests."
  1795. max_iterations: 250 # Max tool-calling turns per child (default: 250)
  1796. # max_concurrent_children: 10 # Max parallel child agents per batch (default: 10, floor: 1, no ceiling).
  1797. # WARNING: values above 10 multiply API cost linearly.
  1798. # max_spawn_depth: 1 # Delegation tree depth cap (range: 1-3, default: 1 = flat).
  1799. # Raise to 2 to allow workers to spawn their own subagents.
  1800. # Requires role="orchestrator" on intermediate agents.
  1801. # orchestrator_enabled: true # Kill switch for role="orchestrator" children (default: true).
  1802. # subagent_auto_approve: false # When a subagent hits a dangerous-command approval prompt, auto-deny (default: false)
  1803. # or auto-approve "once" (true) instead of blocking on stdin.
  1804. # The parent TUI owns stdin, so blocking would deadlock; non-interactive resolution is required.
  1805. # Both choices emit a logger.warning audit line. Flip to true only for cron/batch pipelines.
  1806. # inherit_mcp_toolsets: true # When explicit child toolsets are narrowed, also keep the parent's MCP toolsets (default: true). Set false for strict intersection.
  1807. # model: "google/gemini-3-flash-preview" # Override model for subagents (empty = inherit parent)
  1808. # provider: "openrouter" # Override provider for subagents (empty = inherit parent)
  1809. # # Resolves full credentials (base_url, api_key) automatically.
  1810. # # Supported: openrouter, nous, zai, kimi-coding, minimax
  1811. # # Cost tip: keep the parent on a frontier model and pin
  1812. # # delegation.model to an inexpensive one — children carry the
  1813. # # vast majority of tokens, so this is where spend is cut while
  1814. # # planning quality stays with the frontier parent.
  1815. # fallback_providers: # Fallback chain for delegated children (same entry format as the
  1816. # - provider: "openrouter" # top-level list). Pinned children use only a declared child chain;
  1817. # model: "deepseek/deepseek-chat" # unpinned children inherit when unset. [] disables fallback (#65038).
  1818. # =============================================================================
  1819. # Honcho Integration (Cross-Session User Modeling)
  1820. # =============================================================================
  1821. # AI-native persistent memory via Honcho (https://honcho.dev/).
  1822. # Builds a deeper understanding of the user across sessions and tools.
  1823. # Runs alongside USER.md — additive, not a replacement.
  1824. #
  1825. # Requires: hermes plugins install honcho (Plastic Labs' plugin from the catalog)
  1826. # Config: ~/.honcho/config.json (shared with Claude Code, Cursor, etc.)
  1827. # API key: HONCHO_API_KEY in ~/.hermes/.env or ~/.honcho/config.json
  1828. #
  1829. # Hermes-specific overrides (optional — most config comes from ~/.honcho/config.json):
  1830. # honcho: {}
  1831. # =============================================================================
  1832. # Display
  1833. # =============================================================================
  1834. display:
  1835. # Use compact banner mode (hides the ASCII-art banner, shows a single line).
  1836. # true: Compact single-line banner
  1837. # false: Full ASCII banner with tool/skill summary (default)
  1838. compact: false
  1839. # Tool progress display level (CLI, gateway, and the TUI/Desktop tool feed)
  1840. # off: Silent — no tool activity shown, just the final response
  1841. # new: Show a tool indicator only when the tool changes (skip repeats)
  1842. # all: Show every tool call with a short preview (default)
  1843. # verbose: Full args, results, and debug logs (same as /verbose)
  1844. # log: Silent in chat; append every tool call to ~/.hermes/logs/tool_calls.log (gateway only)
  1845. # Toggle at runtime with /verbose in the CLI
  1846. # Independent of show_reasoning: hiding reasoning never hides tool rows.
  1847. # Answer-only (just the final response) is show_reasoning: false plus
  1848. # tool_progress: off.
  1849. # tool_progress: all
  1850. # tool_progress, interim_assistant_messages, long_running_notifications,
  1851. # busy_ack_detail and show_reasoning are left unset here on purpose: a value
  1852. # set under display: applies to EVERY messaging platform and replaces its
  1853. # built-in default. To change one platform, set it under
  1854. # display.platforms.<platform> instead.
  1855. #
  1856. # Per-platform defaults can be quieter than the CLI. Telegram
  1857. # tunes for mobile: tool_progress and busy_ack_detail default off (no
  1858. # per-tool breadcrumb stream, no "iteration 21/60" debug detail in busy
  1859. # acks or heartbeats), but interim_assistant_messages and
  1860. # long_running_notifications STAY ON so the user has real signal between
  1861. # turn start and final answer (mid-turn assistant commentary + a single
  1862. # edit-in-place "⏳ Working — N min" heartbeat). Override under
  1863. # display.platforms.telegram.
  1864. # Auto-cleanup of temporary progress bubbles after the final response lands.
  1865. # On platforms that support message deletion (currently Telegram), this
  1866. # removes the tool-progress bubble, "⏳ Still working..." notices, and
  1867. # context-pressure status messages once the final reply has been delivered —
  1868. # keeping long-running turns visible live, then tidy afterward. Failed runs
  1869. # leave the bubbles in place as breadcrumbs. Off by default.
  1870. # Per-platform override: display.platforms.telegram.cleanup_progress
  1871. # true: Delete tracked progress/status bubbles on successful turn
  1872. # false: Leave everything in place (default)
  1873. # Example:
  1874. # display:
  1875. # platforms:
  1876. # telegram:
  1877. # cleanup_progress: true
  1878. cleanup_progress: false
  1879. # Natural mid-turn assistant updates.
  1880. # On gateway platforms, when true, completed assistant status messages are
  1881. # sent as separate chat messages. On the Desktop app, when true, mid-turn
  1882. # assistant narration streamed between tool calls is kept in the transcript
  1883. # instead of the bubble collapsing to only the final message on completion.
  1884. # Independent of tool_progress and gateway streaming.
  1885. # true: Keep/send mid-turn assistant updates (default; off on platforms
  1886. # that cannot edit messages)
  1887. # false: Only keep/send the final response
  1888. # interim_assistant_messages: true
  1889. # Opt-in: hide automatic warning/diagnostic notifications (compression, retry
  1890. # and fallback notices, credit/subagent failure lines, inactivity and watchdog
  1891. # stalls, media-delivery fallbacks, cron failure alerts) on this surface.
  1892. # Requested results, approvals, clarifications and command outcomes are never
  1893. # hidden, and nothing is removed from the logs. Per-platform override under
  1894. # display.platforms.<platform>.suppress_warning_notifications.
  1895. suppress_warning_notifications: false
  1896. # Gateway-only long-running status heartbeats.
  1897. # When false, the platform does not receive periodic "⏳ Working — N min"
  1898. # notifications even if agent.gateway_notify_interval is non-zero. The
  1899. # heartbeat edits a single message in place (where the adapter supports
  1900. # editing) instead of posting a new bubble each interval.
  1901. # Default: true, including Telegram (silent agents are worse than a single
  1902. # edit-in-place heartbeat); false on Slack and on platforms that cannot edit.
  1903. # long_running_notifications: true
  1904. # Include detailed iteration/tool/status context in busy acknowledgments
  1905. # and long-running heartbeats. When true, busy acks show "iteration 21/60,
  1906. # terminal, 10 min" and the heartbeat shows "⏳ Working — 12 min,
  1907. # iteration 21/60, terminal". When false (Telegram, Slack and no-edit
  1908. # platform default), both stay terse: "Interrupting current task" and
  1909. # "⏳ Working — 12 min, terminal".
  1910. # busy_ack_detail: true
  1911. # What Enter does when Hermes is already busy (CLI and gateway platforms).
  1912. # interrupt: Interrupt the current run and redirect Hermes (default)
  1913. # queue: Queue your message for the next turn
  1914. # steer: Inject your message mid-run via /steer, arriving at the agent
  1915. # after the next tool call — no interrupt, no role violation.
  1916. # Falls back to 'queue' if the agent isn't running yet or if
  1917. # images are attached (steer only carries text).
  1918. # Ctrl+C (or /stop in gateway) always interrupts regardless of this setting.
  1919. # Toggle at runtime with /busy <interrupt|queue|steer>.
  1920. busy_input_mode: interrupt
  1921. # Background process notifications (gateway/messaging only).
  1922. # Controls how chatty the process watcher is when you use
  1923. # terminal(background=true, notify_on_complete=true) from Telegram/Discord/etc.
  1924. # concise: One-line status message on completion; failures include a short
  1925. # output tail (default)
  1926. # off: No watcher messages at all
  1927. # result: Only the final raw-output completion message
  1928. # error: Only the final raw-output message when exit code != 0
  1929. # all: Running output updates + final raw-output message
  1930. background_process_notifications: concise
  1931. # Play terminal bell when agent finishes a response.
  1932. # Useful for long-running tasks — your terminal will ding when the agent is done.
  1933. # Works over SSH. Most terminals can be configured to flash the taskbar or play a sound.
  1934. # true: Ring the terminal bell on each response
  1935. # false: Silent (default)
  1936. bell_on_complete: false
  1937. # Play terminal bell when a blocking prompt opens and waits on you:
  1938. # clarify questions, dangerous-command approvals, sudo password, secret
  1939. # capture. Same mechanism as bell_on_complete (\a) — works over SSH.
  1940. # true: Ring whenever the agent is waiting for your input
  1941. # false: Silent (default)
  1942. bell_on_prompt: false
  1943. # Show model reasoning/thinking before each response.
  1944. # When enabled, a dim box shows the model's thought process above the response.
  1945. # Toggle at runtime with /reasoning show or /reasoning hide.
  1946. # true: Show the reasoning box (CLI default)
  1947. # false: Hide reasoning (messaging platform default)
  1948. # show_reasoning: true
  1949. # Stream tokens to the terminal as they arrive instead of waiting for the
  1950. # full response. The response box opens on first token and text appears
  1951. # line-by-line. Tool calls are still captured silently.
  1952. # true: Stream tokens as they arrive (default)
  1953. # false: Wait for the full response before rendering
  1954. streaming: true
  1955. # Show [HH:MM] timestamps on user input and assistant response labels.
  1956. # timestamps: false
  1957. # ───────────────────────────────────────────────────────────────────────────
  1958. # Skin / Theme
  1959. # ───────────────────────────────────────────────────────────────────────────
  1960. # Customize CLI visual appearance — banner colors, spinner faces, tool prefix,
  1961. # response box label, and branding text. Change at runtime with /skin <name>.
  1962. #
  1963. # Built-in skins:
  1964. # default — Classic Hermes gold/kawaii
  1965. # ares — Crimson/bronze war-god theme with spinner wings
  1966. # mono — Clean grayscale monochrome
  1967. # slate — Cool blue developer-focused
  1968. # daylight — Bright light-mode theme
  1969. # warm-lightmode — Warm paper-tone light-mode theme
  1970. # poseidon — Sea-green/teal Olympian theme
  1971. # sisyphus — Earthy stone-and-moss theme
  1972. # charizard — Fiery orange dragon theme
  1973. #
  1974. # Custom skins: drop a YAML file in ~/.hermes/skins/<name>.yaml
  1975. # Schema (all fields optional, missing values inherit from default):
  1976. #
  1977. # name: my-theme
  1978. # description: Short description
  1979. # colors:
  1980. # banner_border: "#HEX" # Panel border
  1981. # banner_title: "#HEX" # Panel title
  1982. # banner_accent: "#HEX" # Section headers (Available Tools, etc.)
  1983. # banner_dim: "#HEX" # Dim/muted text
  1984. # banner_text: "#HEX" # Body text (tool names, skill names)
  1985. # ui_accent: "#HEX" # UI accent color
  1986. # response_border: "#HEX" # Response box border color
  1987. # spinner:
  1988. # waiting_faces: ["(⚔)", "(⛨)"] # Faces shown while waiting
  1989. # thinking_faces: ["(⚔)", "(⌁)"] # Faces shown while thinking
  1990. # thinking_verbs: ["forging", "plotting"] # Verbs for spinner messages
  1991. # wings: # Optional left/right spinner decorations
  1992. # - ["⟪⚔", "⚔⟫"]
  1993. # - ["⟪▲", "▲⟫"]
  1994. # branding:
  1995. # agent_name: "My Agent" # Banner title and branding
  1996. # welcome: "Welcome message" # Shown at CLI startup
  1997. # response_label: " ⚔ Agent " # Response box header label
  1998. # prompt_symbol: "⚔" # Prompt symbol (bare token; renderers add trailing space)
  1999. # tool_prefix: "╎" # Tool output line prefix (default: ┊)
  2000. #
  2001. skin: default
  2002. # =============================================================================
  2003. # Model Aliases — short names for /model command
  2004. # =============================================================================
  2005. # Map short aliases to exact (model, provider, base_url) tuples.
  2006. # Used by /model tab completion and resolve_alias().
  2007. # Aliases are checked BEFORE the models.dev catalog, so they can route
  2008. # to endpoints not in the catalog (e.g. Ollama Cloud, local servers).
  2009. #
  2010. # An alias pointing at its own endpoint can carry that endpoint's
  2011. # credential with `api_key` (a literal, or a "${VAR}" reference) or
  2012. # `key_env` (an env var name). `api_key` wins if both are set. When
  2013. # neither is set the key is resolved from the alias HOST — never from
  2014. # whatever provider was active before the switch, which would send that
  2015. # provider's secret to an unrelated third party.
  2016. #
  2017. # model_aliases:
  2018. # opus:
  2019. # model: claude-opus-4-6
  2020. # provider: anthropic
  2021. # qwen:
  2022. # model: "qwen3.5:397b"
  2023. # provider: custom
  2024. # base_url: "https://ollama.com/v1"
  2025. # glm:
  2026. # model: glm-4.7
  2027. # provider: custom
  2028. # base_url: "https://ollama.com/v1"
  2029. # theta:
  2030. # model: theta-1
  2031. # provider: custom
  2032. # base_url: "https://theta.example.com/v1"
  2033. # key_env: THETA_API_KEY # or: api_key: "${THETA_API_KEY}"
  2034. # =============================================================================
  2035. # Privacy
  2036. # =============================================================================
  2037. # privacy:
  2038. # # Redact PII from the LLM context prompt.
  2039. # # When true, phone numbers are stripped and user/chat IDs are replaced
  2040. # # with deterministic hashes before being sent to the model.
  2041. # # Names and usernames are NOT affected (user-chosen, publicly visible).
  2042. # # Routing/delivery still uses the original values internally.
  2043. # redact_pii: false
  2044. # =============================================================================
  2045. # Shell-script hooks
  2046. # =============================================================================
  2047. # Register shell scripts as plugin-hook callbacks. Each entry is executed as
  2048. # a subprocess (shell=False, shlex.split) with a JSON payload on stdin. On
  2049. # stdout the script may return JSON that either blocks the tool call or
  2050. # injects context into the next LLM call.
  2051. #
  2052. # Valid events (mirror hermes_cli.plugins.VALID_HOOKS):
  2053. # pre_tool_call, post_tool_call, pre_llm_call, post_llm_call,
  2054. # pre_api_request, post_api_request, on_session_start, on_session_end,
  2055. # on_session_finalize, on_session_reset, subagent_stop
  2056. #
  2057. # First-use consent: each (event, command) pair prompts once on a TTY, then
  2058. # is persisted to ~/.hermes/shell-hooks-allowlist.json. Non-interactive
  2059. # runs (gateway, cron) need --accept-hooks, HERMES_ACCEPT_HOOKS=1, or the
  2060. # hooks_auto_accept key below.
  2061. #
  2062. # See website/docs/user-guide/features/hooks.md for the full JSON wire
  2063. # protocol and worked examples.
  2064. #
  2065. # hooks:
  2066. # pre_tool_call:
  2067. # - matcher: "terminal"
  2068. # command: "~/.hermes/agent-hooks/block-rm-rf.sh"
  2069. # timeout: 10
  2070. # post_tool_call:
  2071. # - matcher: "write_file|patch"
  2072. # command: "~/.hermes/agent-hooks/auto-format.sh"
  2073. # pre_llm_call:
  2074. # - command: "~/.hermes/agent-hooks/inject-cwd-context.sh"
  2075. # subagent_stop:
  2076. # - command: "~/.hermes/agent-hooks/log-orchestration.sh"
  2077. #
  2078. # hooks_auto_accept: false
  2079. # =============================================================================
  2080. # Telemetry
  2081. # =============================================================================
  2082. # Shared metrics are disabled by default. When enabled, Hermes writes only
  2083. # allowlisted aggregate counters and immutable JSON
  2084. # packages under $HERMES_HOME/telemetry/shared_metrics.
  2085. # Packages include a random profile-scoped ID that stays stable until this
  2086. # directory is deleted. It is not derived from hardware, account, or host data.
  2087. # Successfully exported local history is retained for 30 days; pending deltas
  2088. # are retained until they can be exported.
  2089. # This profile-owned choice is not overridden by managed-scope configuration.
  2090. #
  2091. # Nothing is uploaded unless you also set `send: true`. That is a separate
  2092. # opt-in and requires `enabled`; it never turns collection on by itself.
  2093. # When sending is on:
  2094. # * only packages whose entire collection period falls within one
  2095. # continuous recorded consent window are ever sent. Consent windows open
  2096. # when you enable sending and close when you disable it, so data
  2097. # collected before you opted in — or during any gap between opt-ins —
  2098. # stays on this machine;
  2099. # * each package carries the profile-scoped ID as-is. It is a random UUID
  2100. # with no hardware, account, or host-derived content, and deleting the
  2101. # shared-metrics directory resets it.
  2102. # See docs/observability/relay-shared-metrics.md (Appendix A) for the full
  2103. # consent, identity, retention, and deletion decisions.
  2104. telemetry:
  2105. shared_metrics:
  2106. enabled: false
  2107. send: false
  2108. # endpoint: https://telemetry.nousresearch.com/v1/telemetry
  2109. # =============================================================================
  2110. # Login Policy (credentials themselves live in auth.json / .env)
  2111. # =============================================================================
  2112. auth:
  2113. # Borrow and refresh the Codex CLI (~/.codex/auth.json) and Claude Code logins when Hermes has
  2114. # no usable login of its own. Their refresh tokens are single-use, so two programs on one login
  2115. # can log each other out; set false to make Hermes use only its own logins.
  2116. adopt_external_logins: true
  2117. # How `hermes auth add openai-codex` / `hermes model` sign in to OpenAI Codex.
  2118. # device_code (default) — open a URL and enter a code.
  2119. # browser — authorization-code + PKCE on http://localhost:1455/auth/callback (the redirect
  2120. # OpenAI registered for the Codex client) for organizations that disable the
  2121. # device-code grant; falls back to device code when that port is busy.
  2122. # `hermes auth add openai-codex --browser` opts in for a single login without changing this.
  2123. codex_login_flow: device_code
  2124. # =============================================================================
  2125. # Update Behavior
  2126. # =============================================================================
  2127. updates:
  2128. # Disable passive CLI/banner update checks with `hermes config set updates.check false`.
  2129. # Explicit `hermes update --check` and `hermes update` remain available.
  2130. check: true
  2131. # Create a full HERMES_HOME zip before every `hermes update`.
  2132. # Backups land in ~/.hermes/backups/ and can be restored with `hermes import`.
  2133. # Off by default because large homes can add minutes to every update.
  2134. pre_update_backup: false
  2135. # Number of pre-update backup zips to retain.
  2136. backup_keep: 5
  2137. # What non-interactive updates do with local source edits in the Hermes repo.
  2138. # Interactive terminal updates always prompt before restoring the autostash.
  2139. #
  2140. # stash - auto-stash before pull, then auto-restore after success (default)
  2141. # discard - drop the update-created stash after success; use only on managed
  2142. # installs where local source edits should not persist
  2143. non_interactive_local_changes: "stash"
  2144. # =============================================================================
  2145. # Web Dashboard
  2146. # =============================================================================
  2147. # OAuth gate configuration for `hermes dashboard --host <non-loopback>`.
  2148. # The bundled Nous Portal plugin reads these on startup; settings here are
  2149. # the canonical surface. Each can be overridden by an environment variable:
  2150. #
  2151. # dashboard.oauth.client_id <- HERMES_DASHBOARD_OAUTH_CLIENT_ID
  2152. # dashboard.oauth.portal_url <- HERMES_DASHBOARD_PORTAL_URL
  2153. # dashboard.public_url <- HERMES_DASHBOARD_PUBLIC_URL
  2154. #
  2155. # Env wins when set to a non-empty value. This is what Fly.io's platform-
  2156. # secret injection uses to push per-deploy client_ids without needing to
  2157. # bake a config.yaml into the image. Empty env values are treated as unset
  2158. # so a provisioned-but-not-populated secret can't shadow a valid entry here.
  2159. #
  2160. # Local dev / on-prem deploys should typically set these via config.yaml
  2161. # (the ~/.hermes/.env file is reserved for API keys and secrets).
  2162. #
  2163. # dashboard:
  2164. # oauth:
  2165. # client_id: "" # agent:{instance_id}; Portal provisions this at deploy
  2166. # portal_url: "" # blank → default https://portal.nousresearch.com
  2167. #
  2168. # # Force the absolute base URL the OAuth callback (and any other public
  2169. # # URL the dashboard hands to external systems) is built from. Set this
  2170. # # for deploys behind reverse proxies that don't reliably forward
  2171. # # X-Forwarded-Host / X-Forwarded-Proto / X-Forwarded-Prefix (manual
  2172. # # nginx setups, on-prem ingresses, custom-domain Fly deploys without
  2173. # # full proxy header chains).
  2174. # #
  2175. # # When set, the value is the complete authority: scheme + host +
  2176. # # optional path prefix (e.g. "https://example.com/hermes"). The OAuth
  2177. # # callback URL becomes "<public_url>/auth/callback" — X-Forwarded-Prefix
  2178. # # is IGNORED on this code path because the operator has explicitly
  2179. # # declared the public URL and we no longer need to guess.
  2180. # #
  2181. # # Leave empty to use the existing proxy-header reconstruction (the
  2182. # # default — works on Fly.io out of the box).
  2183. # #
  2184. # # public_url: "https://example.com/hermes"
  2185. # #
  2186. # # Reverse proxies connecting from another container or host are not
  2187. # # trusted by default. Add only the proxy's exact IP address, or a bounded
  2188. # # CIDR for a dedicated proxy network, so X-Forwarded-Proto and
  2189. # # X-Forwarded-For can be honored. Loopback is always trusted. Wildcards
  2190. # # and /0 networks are rejected.
  2191. # #
  2192. # # trusted_proxies:
  2193. # # - "172.20.0.5"
  2194. # # # - "172.20.0.0/24" # dedicated network, if the IP is dynamic
  2195. #
  2196. # -----------------------------------------------------------------------------
  2197. # Self-hosted OIDC dashboard auth (generic OpenID Connect — Authentik,
  2198. # Keycloak, Zitadel, Authelia, Auth0, Okta, Google, …). Use this INSTEAD of the
  2199. # nous block above when gating the dashboard with your own identity provider.
  2200. # Each setting can be overridden by an environment variable:
  2201. #
  2202. # dashboard.oauth.self_hosted.issuer <- HERMES_DASHBOARD_OIDC_ISSUER
  2203. # dashboard.oauth.self_hosted.client_id <- HERMES_DASHBOARD_OIDC_CLIENT_ID
  2204. # dashboard.oauth.self_hosted.scopes <- HERMES_DASHBOARD_OIDC_SCOPES
  2205. # dashboard.oauth.self_hosted.client_secret <- HERMES_DASHBOARD_OIDC_CLIENT_SECRET
  2206. #
  2207. # dashboard:
  2208. # oauth:
  2209. # provider: self-hosted
  2210. # self_hosted:
  2211. # issuer: "https://auth.example.com/application/o/hermes/" # required
  2212. # client_id: "hermes-dashboard" # required
  2213. # scopes: "openid profile email" # optional
  2214. #
  2215. # # OPTIONAL — set ONLY if your IDP registered the client as
  2216. # # *confidential* (Authentik / Keycloak often default to this). When
  2217. # # set, Hermes authenticates the client at the token endpoint
  2218. # # (client_secret_basic or client_secret_post, auto-selected from the
  2219. # # IDP's discovery doc) IN ADDITION to PKCE. Leave unset for a public
  2220. # # (PKCE-only) client — the common case.
  2221. # #
  2222. # # This is a CREDENTIAL: prefer setting HERMES_DASHBOARD_OIDC_CLIENT_SECRET
  2223. # # in ~/.hermes/.env over putting it here in config.yaml.
  2224. # # client_secret: ""
  2225. # =============================================================================
  2226. # External secret sources
  2227. # =============================================================================
  2228. # Pull provider credentials from external secret managers at process startup
  2229. # instead of storing them in ~/.hermes/.env. Only the manager's bootstrap
  2230. # credential (e.g. BWS_ACCESS_TOKEN / OP_SERVICE_ACCOUNT_TOKEN) lives in .env
  2231. # (or your shell / desktop session); everything else rotates centrally.
  2232. # Failures never block startup — Hermes warns once and continues with
  2233. # whatever .env already had.
  2234. #
  2235. # Multiple sources can be enabled at once:
  2236. # - "mapped" sources (explicit VAR -> ref bindings, e.g. 1Password's env:
  2237. # map) beat "bulk" sources (whole-project dumps like Bitwarden BSM)
  2238. # - within a shape, the first source to claim a var wins; later claims
  2239. # are skipped with a startup warning (never a silent clobber)
  2240. # - a source's override_existing lets it beat .env/shell values, but
  2241. # never another secret source's claim
  2242. # Docs: https://hermes-agent.nousresearch.com/docs/user-guide/secrets/
  2243. #
  2244. # secrets:
  2245. # # Optional explicit ordering of enabled sources.
  2246. # # sources: [onepassword, bitwarden]
  2247. #
  2248. # # ---- Bitwarden Secrets Manager (bws CLI) --------------------------------
  2249. # bitwarden:
  2250. # enabled: false
  2251. # access_token_env: BWS_ACCESS_TOKEN # bootstrap token, sourced from .env
  2252. # project_id: "" # UUID of the BSM project to sync
  2253. # server_url: "" # "" = US Cloud; EU/self-hosted URL otherwise
  2254. # cache_ttl_seconds: 300 # 0 disables fresh caching
  2255. # encrypted_cache: # optional encrypted stale fallback
  2256. # enabled: false
  2257. # max_stale_seconds: 0 # 0 disables stale fallback
  2258. # override_existing: true # BSM values win over existing env
  2259. # auto_install: true # lazy-download bws into ~/.hermes/bin
  2260. #
  2261. # # ---- 1Password (op CLI) -------------------------------------------------
  2262. # onepassword:
  2263. # enabled: false
  2264. # # Map env-var names to op:// secret references. Each is resolved with a
  2265. # # single `op read` at startup.
  2266. # env:
  2267. # OPENAI_API_KEY: "op://Private/OpenAI/api key"
  2268. # ANTHROPIC_API_KEY: "op://Private/Anthropic/credential"
  2269. # account: "" # op --account shorthand; "" = default
  2270. # service_account_token_env: OP_SERVICE_ACCOUNT_TOKEN # headless auth; unset = desktop session
  2271. # binary_path: "" # "" = resolve op via PATH; else absolute path
  2272. # cache_ttl_seconds: 300 # 0 disables BOTH cache layers
  2273. # override_existing: true # resolved values win over existing env
  2274. #
  2275. # # ---- Command helper (any CLI vault) --------------------------------------
  2276. # # Run a user-configured helper that prints KEY=VALUE lines on stdout —
  2277. # # works with any secret store that has a CLI: keepassxc-cli, secret-tool,
  2278. # # pass, gpg, or a script that cats a tmpfs env file. Composes with the
  2279. # # sources above (enable any combination). POSIX-only (needs /bin/sh).
  2280. # # The helper must be fast and NON-interactive (hard timeout, 1 MiB cap);
  2281. # # its stderr is discarded so diagnostics can't leak secret material.
  2282. # command:
  2283. # enabled: false
  2284. # command: "cat /run/user/1000/hermes-secrets.env"
  2285. # helper_timeout_seconds: 3
  2286. # override_existing: false # .env/shell win by default
  2287. # # This runs ONCE per process at startup, so it cannot replace a credential
  2288. # # that expires mid-session. For a single provider whose token needs
  2289. # # re-minting during a session, use `providers.<name>.key_cmd` instead.