config_defaults.py 208 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550255125522553255425552556255725582559256025612562256325642565256625672568256925702571257225732574257525762577257825792580258125822583258425852586258725882589259025912592259325942595259625972598259926002601260226032604260526062607260826092610261126122613261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640264126422643264426452646264726482649265026512652265326542655265626572658265926602661266226632664266526662667266826692670267126722673267426752676267726782679268026812682268326842685268626872688268926902691269226932694269526962697269826992700270127022703270427052706270727082709271027112712271327142715271627172718271927202721272227232724272527262727272827292730273127322733273427352736273727382739274027412742274327442745274627472748274927502751275227532754275527562757275827592760276127622763276427652766276727682769277027712772277327742775277627772778277927802781278227832784278527862787278827892790279127922793279427952796279727982799280028012802280328042805280628072808280928102811281228132814281528162817281828192820282128222823282428252826282728282829283028312832283328342835283628372838283928402841284228432844284528462847284828492850285128522853285428552856285728582859286028612862286328642865286628672868286928702871287228732874287528762877287828792880288128822883288428852886288728882889289028912892289328942895289628972898289929002901290229032904290529062907290829092910291129122913291429152916291729182919292029212922292329242925292629272928292929302931293229332934293529362937293829392940294129422943294429452946294729482949295029512952295329542955295629572958295929602961296229632964296529662967296829692970297129722973297429752976297729782979298029812982298329842985298629872988298929902991299229932994299529962997299829993000300130023003300430053006300730083009301030113012301330143015301630173018301930203021302230233024302530263027302830293030303130323033303430353036303730383039304030413042304330443045304630473048304930503051305230533054305530563057305830593060306130623063306430653066306730683069307030713072307330743075307630773078307930803081308230833084308530863087308830893090309130923093309430953096309730983099310031013102310331043105310631073108310931103111311231133114311531163117
  1. """Default configuration data for Hermes Agent: DEFAULT_CONFIG and OPTIONAL_ENV_VARS.
  2. Pure-data leaf module — must not import from hermes_cli.config. Comments are the user-facing
  3. docs of config.yaml.
  4. """
  5. from hermes_cli.config_defaults_auxiliary import _aux
  6. #: Image every container terminal backend (docker/modal/daytona, the singularity plugin) uses unless the
  7. #: user pins one. LEGACY_SANDBOX_IMAGES are the plain defaults that preceded the desktop stack
  8. #: (the 3.14 pin shipped between the two without a migration); a saved config still holding one
  9. #: is the template copied, and the config migration unsets it, never a user's own pin.
  10. DEFAULT_SANDBOX_IMAGE = "nousresearch/hermes-sandbox:desktop"
  11. LEGACY_SANDBOX_IMAGES = ("nikolaik/python-nodejs:python3.11-nodejs20", "nikolaik/python-nodejs:python3.14-nodejs22")
  12. LEGACY_SANDBOX_IMAGE = LEGACY_SANDBOX_IMAGES[0]
  13. # Vercel Sandbox managed image (Vercel deprecated its `runtime` presets in Aug 2026).
  14. DEFAULT_VERCEL_IMAGE = "vercel/sandbox/universal:latest"
  15. LEGACY_VERCEL_RUNTIME = "node24" # the seeded pre-49 default, never a user choice
  16. DEFAULT_CONFIG = {
  17. "model": "",
  18. "providers": {},
  19. "fallback_providers": [],
  20. # min_switch_reset_seconds: opt-in (0 = off). When a rate-limited primary declares a reset
  21. # sooner than this many seconds, stay on it (the retry backoff rides out the window) instead
  22. # of switching the turn to a fallback model.
  23. "fallback": {"min_switch_reset_seconds": 0},
  24. "credential_pool_strategies": {},
  25. "toolsets": ["hermes-cli"],
  26. # journal_mode: SQLite journal mode for every Hermes DB. "wal" default; use "delete" on
  27. # weak-fsync/shared filesystems where WAL is not crash-safe (macOS virtiofs, NFS, SMB).
  28. "database": {
  29. "journal_mode": "wal",
  30. # WAL sizing pragmas (ints). None = SQLite defaults (autocheckpoint 1000 pages, no limit).
  31. "wal_autocheckpoint": None,
  32. "journal_size_limit": None,
  33. },
  34. # Server-process fd soft limit (clamped to the hard limit) + glibc arena cap; 0/false/null = off.
  35. "runtime": {"nofile_soft_limit": 4096, "malloc_arena_max": 4},
  36. # Global active chat session cap across CLI, TUI/dashboard, and messaging. None/0 = unbounded.
  37. "max_concurrent_sessions": None,
  38. # Soft LRU cap on in-memory TUI/desktop/dashboard sessions. Above it the gateway evicts the
  39. # least-recently-active DETACHED sessions (no live client); reopening re-resumes from disk.
  40. # 0/null disables.
  41. "max_live_sessions": 16,
  42. "session": {
  43. # Per-terminal `hermes -c`: each CLI session writes a breadcrumb under
  44. # $HERMES_HOME/terminal-sessions/<terminal-id>, so bare -c/--continue resumes THIS
  45. # terminal's session (tmux/kitty/wezterm pane, tty). false = resume globally most-recent.
  46. "terminal_continue": True,
  47. },
  48. # Where the TUI/desktop gateway stages session file attachments (uploads, pasted
  49. # text). "hermes-home" (default) keeps <profile home>/attachments — the dir
  50. # container backends bind-mount, so @file: refs resolve in the sandbox (#76577).
  51. # "workspace" opts into <session workspace>/.hermes/attachments: staging lands
  52. # inside the allowed ref root, so the same profile's agent can always read its
  53. # own attachments back (#110662). Read per profile from that profile's config;
  54. # a remote (ssh) workspace keeps the profile home dir either way.
  55. "attachments": {
  56. "storage": "hermes-home",
  57. },
  58. "agent": {
  59. # Turn cap. null = unlimited (default; caps caused silent mid-task truncation). Positive int
  60. # caps; "none"/"unlimited"/"inf"/0/-1 also mean unlimited (resolve_turn_limit).
  61. "max_turns": None,
  62. # Optional one-time model-visible checkpoint warning before a finite turn cap is exhausted.
  63. # null = off; set a ratio strictly between 0 and 1 (for example, 0.75).
  64. "budget_warning_ratio": None,
  65. # Wall-clock budget (seconds) per run. null = off. When set: one-time wrap-up notice at 80%
  66. # elapsed; implicit provider stale timeouts capped to remaining budget. CLI equivalent:
  67. # `hermes chat --run-budget N`.
  68. "run_budget_seconds": None,
  69. # Gateway inactivity timeout (seconds). Only fires when the agent is completely idle — not
  70. # while calling tools or receiving API responses. 0 = unlimited.
  71. "gateway_timeout": 1800,
  72. # Max seconds an alias routing key waits for the active turn holding the same session lease;
  73. # on expiry the message is rejected with a resend notice. Keep short: Telegram dispatches
  74. # sequentially, so a waiter delays unrelated topics. Non-positive -> 5s.
  75. "gateway_turn_lease_timeout": 5,
  76. # Per-session AIAgent cache in the gateway. Each entry keeps a warm prompt prefix AND the
  77. # full transcript: too small re-pays uncached prompts, too large fills the heap.
  78. "agent_cache": {
  79. "max_size": 128, # LRU entry cap
  80. "idle_ttl_secs": 3600, # evict agents idle this long
  81. # Anonymous-RSS budget (MB) above which LRU transcripts are shed (reloaded from disk
  82. # next turn). "auto" = derive from cgroup memory limit (or total RAM); number =
  83. # explicit; 0/off = disable the pass.
  84. "memory_high_mb": "auto",
  85. # Max sessions shed per pass (teardown bursts can't stall the gateway) and the number of
  86. # most-recently-used sessions the pass never touches.
  87. "max_evictions_per_pass": 16,
  88. "protect_recent": 8,
  89. },
  90. # Force-interrupt budget (seconds) once gateway stop()/drain has begun (SIGTERM, and the
  91. # final phase of in-band restart). 0 = interrupt immediately. Keep under systemd
  92. # TimeoutStopSec or risk SIGKILL mid-cleanup; for /restart prefer restart_after_turn_timeout
  93. # so turns finish BEFORE stop().
  94. "restart_drain_timeout": 0,
  95. # Floor under the stop()/drain wait (seconds) for cron jobs and api_server runs. Interrupted
  96. # chat turns resume on the next message, but an interrupted cron run is recorded as a
  97. # permanent failure and an interrupted /v1 run fails its waiting caller, so neither may
  98. # inherit restart_drain_timeout's 0 (#82161, #132989). Clamped to the shutdown-watchdog
  99. # leash minus teardown headroom (~50s unless TimeoutStopSec is raised). 0 = opt out.
  100. "cron_drain_timeout": 30,
  101. # In-band restart (/restart, SIGUSR1): refuse new work, then wait up to this many seconds
  102. # for in-flight agents/cron/api runs to finish before stop(). 0 = enter stop() at once. 30
  103. # min is a safety valve for wedged agents, not a target; raise for long unattended turns.
  104. # Default 30 min is a safety valve for wedged agents, not a target latency — an interactive `hermes
  105. # gateway restart` must never block for hours on a turn that wedged (#79133).
  106. "restart_after_turn_timeout": 1800,
  107. # Max seconds a submitted prompt waits for the deferred agent build (MCP discovery, model
  108. # metadata, skills scan) before failing visibly. The prompt is delivered as soon as the
  109. # build completes (progress notice past 30s), so this only fires on a hung build. Raise for
  110. # many slow/unreachable MCP servers.
  111. # See #63078.
  112. "build_wait_timeout": 600,
  113. # Hermes-level retry attempts for API errors (connection drops, timeouts, 5xx) wrapping the
  114. # whole call; the OpenAI SDK also retries transient errors (max_retries=2). Set 1 for fast
  115. # failover to fallback providers; raise to tolerate longer provider hiccups.
  116. "api_max_retries": 3,
  117. # Once api_max_retries AND the fallback chain are spent on a transient outage (5xx,
  118. # overloaded/529, connect/read timeouts) with nothing delivered yet, wait and retry this many
  119. # more cycles (jittered 15/30/60/60/60s; a provider Retry-After wins up to 120s) with a
  120. # visible "retrying automatically" countdown instead of ending the turn. Esc/interrupt stops
  121. # the wait; auth/format/billing/policy errors never enter. 0 disables.
  122. "auto_recovery_cycles": 5,
  123. # Seconds the Codex/Responses stream may keep reading after its terminal frame so the relay
  124. # finalizer can run. Relays that never close the SSE socket after response.completed would
  125. # otherwise wedge the turn until the idle watchdog discards the already-billed response
  126. # (#103864). 0 skips the drain. Well-behaved endpoints close immediately and never wait this long.
  127. "stream_drain_timeout": 2.0,
  128. # Empty-response retry guard. Empty retries re-send the full input at full price; this stops
  129. # re-billing deterministic empties (unsignaled refusals, zero output tokens) while failing
  130. # open on ambiguous evidence (missing usage, any tokens, model/provider change).
  131. "empty_response_guard": {
  132. "enabled": True, # False = legacy fixed 3 retries unconditionally
  133. # When one empty attempt's estimated input cost >= this USD, the streak's retry budget
  134. # drops from 3 to 1. Unknown pricing / missing usage leaves it untouched.
  135. "cost_threshold_usd": 0.25,
  136. },
  137. # Fast mode: "" / "normal" (off), "fast" (always), "auto" (first fast_auto_seconds of every
  138. # turn), "cold" (first turn of a session only).
  139. "service_tier": "",
  140. "fast_auto_seconds": 60,
  141. # Responses-only `text.verbosity` (never chat_completions): "" = not sent, or low | medium | high.
  142. "text_verbosity": "",
  143. "daybreak": False, # opt-in; only catalog-listed Codex models (agent/codex_service_tiers.py)
  144. # System-prompt guidance telling the model to call tools instead of describing actions.
  145. # "auto" = gpt/codex models; true/false = force for all models; or a list of model-name
  146. # substrings (e.g. ["gpt", "codex", "gemini", "qwen"]).
  147. "tool_use_enforcement": "auto",
  148. # Execution-discipline prompt block (tool persistence, tools for arithmetic/system facts,
  149. # read-back after external writes, count reconciliation, literal identifiers,
  150. # verification-gated completion). Chosen once per session by model name (byte-stable).
  151. # "auto" = gpt/codex/grok/deepseek/kimi/qwen/glm/minimax/mimo/mistral; true/false = force;
  152. # or a list of model-name substrings.
  153. "execution_guidance": "auto",
  154. # When the model narrates an action ("I'll go check the logs...") but emits no tool call,
  155. # inject a "continue now, execute the tools" nudge and loop (max 2 nudges/turn). Corrective
  156. # sibling of tool_use_enforcement. "auto" = codex_responses api_mode only; true = all
  157. # api_modes (fixes Gemini/Claude "stops after stating intent"); false = never; or a list of
  158. # model-name substrings.
  159. "intent_ack_continuation": "auto",
  160. # Anti-stall guards: (1) identical-call loop breaker appends a notice when the same tool is
  161. # called 3+ times with identical args AND results (never blocks; pollers like `process`
  162. # exempt); (2) continue-intent extension of empty-response recovery re-prompts once when the
  163. # model says it will continue but takes no action. False disables both.
  164. "stall_guards": True,
  165. # "Finish the job" prompt block for all models: don't stop at a stub, never fabricate output
  166. # when the real path is blocked. ~80 cached tokens. False disables.
  167. "task_completion_guidance": True,
  168. # Prompt block for all models steering independent tool calls (reads, searches, fetches,
  169. # read-only commands) into one batched turn; the runtime already runs them concurrently. ~70
  170. # cached tokens. False disables.
  171. "parallel_tool_call_guidance": True,
  172. # Toolchain probe: surfaces Python/pip/uv/PEP-668 state in the system prompt only when
  173. # something non-default is detected (no pip module, pip/python mismatch, PEP 668 without
  174. # uv); zero tokens when clean. Skipped for docker/modal/ssh backends (own probe).
  175. "environment_probe": True,
  176. # Bot Mode teammate-messaging protocol section (silent unless desktop Bot Mode manages it).
  177. "bot_mode_protocol": True,
  178. # Embedder-supplied text appended to the system prompt's environment-hints block, so a host
  179. # wrapping Hermes (sandbox runner, managed platform) can describe proxy/credential/ mount
  180. # layout without editing SOUL.md. Env HERMES_ENVIRONMENT_HINT overrides it.
  181. "environment_hint": "",
  182. # Coding posture: on interactive coding surfaces (CLI, TUI, desktop, ACP) in a code
  183. # workspace, add a coding brief + live git/workspace snapshot to the system prompt
  184. # (agent/coding_context.py). "auto" = prompt-only when interactive AND cwd is a code
  185. # workspace (toolsets untouched, messaging platforms unaffected); "focus" = auto + collapse
  186. # toolset to the lean coding set (+ enabled MCP servers) + demote non-coding skill
  187. # categories to names-only (explicit opt-in); "on" = force everywhere; "off" = disable.
  188. "coding_context": "auto",
  189. # Standing operator instructions (string or list) appended to the coding brief as an extra
  190. # stable system block — project-wide workflow rules, e.g. "Don't run tsc/lint until I
  191. # approve." Cache-safe: takes effect next session.
  192. "coding_instructions": "",
  193. # When verify-on-stop finds edits without fresh verification evidence, add guidance for
  194. # creative UI work (no broad tsc/lint/test before visual approval) and clean-diff
  195. # expectations. false = keep the evidence nudge terse.
  196. "verify_guidance": True,
  197. # Max consecutive `pre_verify` "continue" nudges per turn (hooks can't trap the loop).
  198. "max_verify_nudges": 3,
  199. # Verification closure: after code edits in a workspace, refuse a final answer until fresh
  200. # verification evidence exists or the agent explains why it can't check (bounded loop,
  201. # passive ledger). False (default) because the nudges proved more noise than signal; true =
  202. # force on everywhere; "auto" = on for interactive coding surfaces and programmatic callers,
  203. # off for messaging surfaces. Doc/markdown/skill-only edits never fire.
  204. "verify_on_stop": False,
  205. # Inactivity warning (seconds), once per run before gateway_timeout; no interrupt. 0 = off.
  206. "gateway_timeout_warning": 900,
  207. # Max seconds any surface (CLI, TUI/Desktop, messaging gateway) blocks an agent awaiting a
  208. # clarify-tool reply; then it unblocks with "[user did not respond within Xm]". 0 or less =
  209. # unlimited. Resolved by tools/clarify_gateway.py::resolve_clarify_timeout (a legacy
  210. # top-level ``clarify.timeout`` still wins when explicitly set).
  211. # 1h because users step away and a shorter value evicted the entry mid-think so a later
  212. # button tap hit a dead entry. Tradeoff: a higher value holds the gateway's running-agent
  213. # guard longer for a genuinely abandoned prompt — lower it to free the guard sooner. See #32762.
  214. "clarify_timeout": 3600,
  215. # "Still working" status interval (seconds); 0 = off. Lower = faster feedback, more noise;
  216. # 180 catches spinning weak-model runs before users /restart.
  217. "gateway_notify_interval": 180,
  218. # Session stall watchdog (seconds): RECOVERY notifier for an in-process AIAgent with an
  219. # adapter-queued follow-up while its activity clock is stale — NOT a general stall detector
  220. # (ignores startup restore, build sentinels, leases, debounce, other processes; scan cadence
  221. # per AIAgent). Notify-only: tells the user to try /new. Distinct from gateway_timeout
  222. # (kills the turn) and gateway_notify_interval. 0 = disable.
  223. # See #76354.
  224. "session_stall_timeout": 300,
  225. # Transcript-sanitiser heal escalation: after this many pre-send heal passes within a
  226. # 10-minute window, log one ERROR and queue a ONE-TIME out-of-band notice pointing at /debug
  227. # share or `hermes doctor` (status channel only; prompt cache untouched). 0 = no escalation
  228. # (per-window WARNINGs still fire).
  229. # See #96870.
  230. "sanitizer_heal_escalation_threshold": 3,
  231. # Seconds of continuous reconnect failure before a platform gets needs_attention flagged in
  232. # gateway status (`hermes status` / fleet monitoring). Retries never stop — a signal, not a
  233. # circuit breaker. 0 = disable.
  234. "reconnect_attention_after": 7200,
  235. # Freshness window (seconds) for the auto-continue note. After a crash/restart mid-run the
  236. # next user message gets "[System note: your previous turn was interrupted...]" prepended;
  237. # only when the last persisted transcript row is younger than this, so stale markers don't
  238. # revive an unrelated old task. Covers gateway_timeout (1800) plus slack. 0 = always inject.
  239. "gateway_auto_continue_freshness": 3600,
  240. # Max seconds the gateway waits for boot auto-resume turns before releasing the
  241. # startup-restore inbound gate (all inbound is QUEUED while shut, so one long resumed turn
  242. # would leave every channel unanswered). On timeout the gate opens and the resume keeps
  243. # running in the background; duplicate-agent protection is unaffected because the resume
  244. # slot is claimed synchronously first. 0 = wait forever.
  245. "gateway_startup_restore_drain_timeout": 30,
  246. # Max seconds the boot turn-machinery warm-up (run_agent import graph, tool schemas +
  247. # availability probes, context-file tier) may hold the inbound gate shut, so an early
  248. # message isn't served with a skeleton system prompt. On timeout the gate opens and warm-up
  249. # finishes in the background. 0 = disable warm-up (lazy init).
  250. "gateway_startup_warmup_timeout": 20,
  251. # Stale-stream ceiling (s) for local providers (Ollama, oMLX, llama-cpp) when the base stale
  252. # timeout is at its 180s default, so a wedged local server eventually trips the detector
  253. # instead of hanging forever. Env HERMES_LOCAL_STREAM_STALE_TIMEOUT overrides.
  254. "local_stream_stale_timeout": 900,
  255. "stream_max_lifetime": 0, # opt-in whole-stream cap in s, 0 = off (agent/stream_max_lifetime.py)
  256. # How user-attached images reach the main model (gateway, TUI, CLI /attach). "auto" = native
  257. # when the model reports supports_vision=True AND auxiliary.vision.provider is not
  258. # explicitly set, else text; "native" = always attach (non-vision models error at the
  259. # provider or get a last-chance text fallback); "text" = always pre-analyze with
  260. # vision_analyze and prepend the description. vision_analyze stays a tool regardless.
  261. "image_input_mode": "auto",
  262. "disabled_toolsets": [],
  263. # Model name (any reasonable spelling) -> effort level; overrides agent.reasoning_effort
  264. # when the current model matches. Edit in config.yaml (no CLI support: dots in keys).
  265. "reasoning_overrides": {},
  266. # Stored reasoning is replayed to every provider that can read it by default. This flag
  267. # only adds the must-echo " " pad on reasoning-less tool-call turns, which DeepSeek,
  268. # Kimi/Moonshot and Xiaomi MiMo require (auto-detected by provider name/host). Set
  269. # `reasoning_echo: true` on a `model:` or `fallback_providers:` entry for a custom gateway
  270. # proxying one of them. Strict providers (Mistral, Groq, Cerebras) never get the field.
  271. "reasoning_echo": False,
  272. # Turn liveness watchdog: a turn with no observable progress for `timeout_s` seconds is
  273. # logged, force-interrupted so the UI can retry, and its lease stops renewing so stale-turn
  274. # cleanup can reclaim the session even if the interrupt can't unwind a wedged frame.
  275. # timeout_s <= 0 disables; poll_s = sampling interval. Invalid values (NaN, Inf,
  276. # non-positive poll) warn and fall back to defaults. See agent/turn_liveness.py.
  277. "turn_liveness": {"timeout_s": 600.0, "poll_s": 15.0},
  278. },
  279. "terminal": {
  280. "backend": "local",
  281. "modal_mode": "auto",
  282. # Remote-backend connection-class failures (SSH host unreachable, Docker daemon down):
  283. # "warn" = structured degraded tool result with reason + retry hint; "fail" = raise error +
  284. # traceback.
  285. "degraded_mode": "warn",
  286. "cwd": ".", # Use current directory
  287. # Root for terminal session temp files (background logs/pid/exit files, code-exec
  288. # sandboxes). Empty = TMPDIR/TMP/TEMP if set, else HERMES_HOME/cache/terminal (auto-pruned
  289. # after 72h) — NOT tmpfs /tmp, which is RAM-capped and fills under load. Must be an existing
  290. # absolute POSIX path; user-set paths are never auto-pruned.
  291. "temp_dir": "",
  292. # CSS font-family for the desktop app's xterm.js terminal (e.g. "'CaskaydiaCoveNerdFont',
  293. # monospace"). Empty = built-in default ("'JetBrains Mono', 'Cascadia Code', 'SF Mono',
  294. # Menlo, Consolas, monospace"). Lets users use a Nerd Font without patching the app.
  295. "font_family": "",
  296. "timeout": 180,
  297. # Seconds between SIGTERM and escalated SIGKILL for host process trees (browser daemons). 0
  298. # = SIGTERM only.
  299. "daemon_term_grace_seconds": 2.0,
  300. # Max seconds a one-shot CLI run (-q/-Q/-z) lingers for tracked notify_on_complete
  301. # background processes to finish. The dying parent owns their stdout pipes, so exiting
  302. # immediately kills the delivery (e.g. Bot Mode handoff replies via message_agent /
  303. # bot_relay). Plain background processes without notify_on_complete are never waited on. 0
  304. # disables.
  305. "oneshot_completion_wait_seconds": 600.0,
  306. "process_wait_auto_notify": True, # 2 unchanged wait/poll -> notify_on_complete + stop; False = old polling
  307. # Env vars passed into sandboxed terminal/execute_code (plus skill-declared required_environment_variables).
  308. "env_passthrough": [],
  309. "client_env_passthrough": [], # Extra non-secret toolchain names a CLI/TUI client sends for its tools
  310. # Remote-backend sync-back refuses to extract a downloaded state archive larger than this
  311. # (bytes); raise it for a ~/.hermes tree that legitimately exceeds 2 GiB.
  312. "sync_back_max_bytes": 2 * 1024 * 1024 * 1024,
  313. # HOME for host tool subprocesses: "auto" = host keeps the real OS-user HOME, containers use
  314. # HERMES_HOME/home; "real" = force real HOME; "profile" = force HERMES_HOME/home when it
  315. # exists (strict per-profile isolation).
  316. "home_mode": "auto",
  317. # Extra files sourced in the login shell when building the per-session env snapshot — for
  318. # nvm/pyenv/asdf/PATH entries registered by files a bash login shell skips (~/.bashrc,
  319. # ~/.zshrc, ~/.zprofile). Supports ~ and ${VAR}; missing files skipped. When empty and the
  320. # shell is bash, ~/.profile, ~/.bash_profile, ~/.bashrc are auto-sourced in that order (see
  321. # auto_source_bashrc).
  322. "shell_init_files": [],
  323. # Source ~/.profile, ~/.bash_profile, ~/.bashrc in the snapshot login shell to capture PATH
  324. # additions, functions, and aliases that `bash -l -c` misses (bash skips bashrc when
  325. # non-interactive; Debian/Ubuntu ~/.bashrc short-circuits). ~/.profile and ~/.bash_profile
  326. # go first because n/nvm/asdf write PATH exports there without an interactivity guard. Turn
  327. # off if an rc file misbehaves when sourced non-interactively (exits on TTY check).
  328. "auto_source_bashrc": True,
  329. # The default sandbox for every container backend: the nikolaik/python-nodejs base
  330. # (Python 3.13 / Node 26) plus a display stack, so Bot Screen, computer_use and the
  331. # bot's browser run INSIDE the sandbox and the pane can watch them (see bot_desktop).
  332. "docker_image": DEFAULT_SANDBOX_IMAGE,
  333. "docker_forward_env": [],
  334. # Exact key-value env pairs set inside Docker containers (unlike docker_forward_env, which
  335. # reads host values) — useful under systemd without the user's shell env. Example:
  336. # {"SSH_AUTH_SOCK": "/run/user/1000/ssh-agent.sock"}
  337. "docker_env": {},
  338. "modal_image": DEFAULT_SANDBOX_IMAGE,
  339. "daytona_image": DEFAULT_SANDBOX_IMAGE,
  340. "vercel_image": DEFAULT_VERCEL_IMAGE, # vercel_sandbox backend only: a Vercel-managed or VCR image
  341. "vercel_runtime": "", # deprecated by Vercel; a legacy runtime pin (node24 | node22 | python3.13) overrides vercel_image
  342. # Container limits (docker, modal, daytona, vercel_sandbox, container plugin backends; not local/ssh).
  343. "container_cpu": 1,
  344. "container_memory": 5120, # MB (default 5GB)
  345. "container_disk": 51200, # MB (default 50GB)
  346. "container_persistent": True, # Persist filesystem across sessions
  347. # Docker volume mounts, "host_path:container_path" (docker -v syntax), e.g.
  348. # ["/home/user/.hermes/cache/documents:/output"]. For gateway MEDIA delivery, write to
  349. # /output/... inside Docker and emit the host-visible path in MEDIA:, not the container one.
  350. "docker_volumes": [],
  351. "docker_mount_cwd_to_workspace": False, # mount host cwd at /workspace (weakens isolation)
  352. "docker_network": True, # false = --network=none, no network access from commands
  353. "docker_extra_args": [], # Extra flags passed verbatim to docker run
  354. # /dev/shm size for the Docker sandbox. Docker's 64 MB default silently breaks
  355. # Chromium/Playwright and PyTorch DataLoader workers; tmpfs is lazily allocated so the
  356. # higher ceiling is free until used. "" or "0" = omit the flag (Docker default).
  357. "docker_shm_size": "1g",
  358. # Run the container as the host uid:gid (`--user`) so files written to bind mounts
  359. # (docker_volumes, persistent workspace, mounted cwd) are owned by you, not root. Off by
  360. # default for images whose entrypoints must start as root (e.g. the bundled Hermes image,
  361. # which drops to `hermes` via s6-setuidgid). When on, SETUID/SETGID caps are omitted.
  362. "docker_run_as_host_user": False,
  363. # Snap-packaged Docker under AppArmor (Ubuntu cloud images; LP#1908448) refuses to exec
  364. # anything under `--init` or `--security-opt no-new-privileges` ("operation not
  365. # permitted"). True drops those two flags; every other hardening stays. See #9730.
  366. "docker_snap_compat": False,
  367. # Trusted profiles sharing one Docker container identity; empty = per-profile boundary.
  368. "docker_shared_container_key": "",
  369. # SSH: carry exported env vars between commands (cwd always carries). false = every command
  370. # starts from the login env, profile functions included. Local: TERMINAL_LOCAL_PERSISTENT.
  371. "persistent_shell": True,
  372. },
  373. "web": {
  374. "backend": "", # shared fallback — applies to both search and extract
  375. "search_backend": "", # per-capability override for web_search (e.g. "searxng")
  376. "extract_backend": "", # per-capability override for web_extract (e.g. "native")
  377. # per-page char budget for web_extract; larger pages truncate, full text kept in cache/web
  378. "extract_char_limit": 15000,
  379. # Keyless free-tier ring: with NO web backend configured or keyed, web_search/web_extract
  380. # rotate round-robin across exa, parallel, firecrawl, keenable public free tiers, failing
  381. # over on rate limits. Never pre-empts a configured/keyed backend. false = disable.
  382. "keyless_fallback": True,
  383. # One-shot rescue: when the chosen/keyed backend fails a call, THAT call retries once on the
  384. # keyless ring; the next call tries the chosen backend again (no sticky failover). Off when
  385. # keyless_fallback is false.
  386. "keyless_rescue": True,
  387. # Per-vendor tier for vendors with both a keyless free endpoint and a keyed paid path (exa,
  388. # parallel, firecrawl, keenable; tavily is opt-in keyless via `hermes tools`, not a ring
  389. # member). Set by the `hermes tools` picker. "free" = always anonymous endpoint even with a
  390. # key; "paid" = always keyed (missing key = error; vendor excluded from the ring); unset =
  391. # keyed when the key is present, else the ring.
  392. "provider_tier": {},
  393. # TTL caching for web_search + web_extract: repeat searches (same query + provider) within
  394. # the TTL come from an in-process memo; repeat extracts from the cache/web store. Concurrent
  395. # identical searches coalesce into one vendor request. Only successes cached.
  396. "cache_enabled": True,
  397. "cache_ttl_minutes": 20,
  398. # Hosts always fetched live, never from the extract cache (staging deploys, tunnel URLs,
  399. # preview builds). Entries match exactly, as "*.wildcard", or as a domain suffix
  400. # ("mysite.dev" also covers "preview.mysite.dev"). localhost/private IPs always exempt.
  401. "cache_exempt_hosts": [],
  402. },
  403. "browser": {
  404. # REMOVAL NOTE: `backend` (built-in browser_* tools vs browser_exec), `snapshot_threshold`,
  405. # `record_sessions`, `allow_unsafe_evaluate` and `restrict_evaluate` left with the built-in
  406. # browser tools; browser_exec is the only core browser. Config v52 drops `backend` (an `off`
  407. # gets a one-time notice) and copies AGENT_BROWSER_* from .env to the keys below; other
  408. # user values stay untouched.
  409. "inactivity_timeout": 120,
  410. # Seconds a local Chromium launch may take to open its DevTools port; a launch always waits
  411. # at least 120 s (a cold first start unpacks the profile).
  412. "command_timeout": 30,
  413. # headed: visible Chromium window (local); skips per-turn cleanup, idle reaper still applies
  414. "headed": False,
  415. "allow_private_urls": False, # legacy security.allow_private_urls; local/sidecar Chromium ignore it
  416. # Local browser engine. "auto" = Chromium; "lightpanda" = `lightpanda serve` per session
  417. # (faster navigation, no screenshots); "chrome" is read as "auto". Ignored while a cloud
  418. # provider, cdp_url or use_real_profile is active.
  419. "engine": "auto",
  420. # Chromium binary for local sessions. "" = pm's chromium (`hermes pm install chromium`), the
  421. # Docker image's build, else a system chromium where pm builds none (Termux).
  422. "executable_path": "",
  423. # Persistent Chromium profile directory shared by local sessions; "" = a fresh throwaway
  424. # profile per session.
  425. "user_data_dir": "",
  426. "chromium_args": [], # extra Chromium flags for local sessions, e.g. ["--lang=de"]
  427. # Cloud provider: LAN/localhost URLs open in a local Chromium (ignores allow_private_urls; False refuses)
  428. "auto_local_for_private_urls": True,
  429. "cdp_url": "", # persistent CDP endpoint for attaching to an existing Chromium/Chrome
  430. # Consent to browse with the user's REAL logins locally: runs on a Hermes-managed SNAPSHOT
  431. # of the ACTIVE default-Chromium profile (Local State -> profile.last_used; cookies, logins,
  432. # prefs copied and re-synced per fresh session) driven by Hermes' packaged Chromium. The
  433. # snapshot dir sidesteps Chrome 136+'s default-profile debugging block and never contends
  434. # with the running browser. Turning off deletes ~/.hermes/browser-profile/ so credentials
  435. # don't outlive consent. Chromium-family only; a profile that can't be copied (Firefox default,
  436. # Windows browser holding its cookies) gives a fresh, signed-out browser plus a note saying why.
  437. # Also gates the browser_exec `local` arg (real-profile session under a cloud backend). Desktop Settings -> Browser.
  438. "use_real_profile": False,
  439. # Windows only: a running Chrome/Edge/Brave locks its cookie DB (the last snapshot is reused;
  440. # with none yet, a fresh browser runs). When on, the agent ASKS first; on approval it runs
  441. # `hermes browser close-profile` (kills that profile's browser tree, unsaved tabs lost) so a
  442. # new session can copy it; no auto-kill. No effect on macOS/Linux, where a running
  443. # browser only locks the password/autofill DBs, which are skipped (cookies still copy).
  444. "real_profile_autoclose": False,
  445. # Pin WHICH source profile directory is snapshotted for real-profile browsing (e.g. "Profile
  446. # 2"). Empty = browser's last-used profile, which on multi-profile machines can hand the
  447. # agent the wrong identity. A pin naming a missing directory never falls back to another
  448. # profile: the session gets a fresh browser without the user's logins.
  449. "real_profile_pin": "",
  450. # CDP supervisor: dialog + frame detection over a persistent WebSocket; active only with a
  451. # CDP-capable backend (Browserbase, or local Chrome via /browser connect). See
  452. # website/docs/developer-guide/browser-supervisor.md.
  453. "dialog_policy": "must_respond", # must_respond | auto_dismiss | auto_accept
  454. "dialog_timeout_s": 300, # safety auto-dismiss after N seconds under must_respond
  455. # Read by the `camofox` catalog plugin (Camofox left core). An empty free-form mapping, so
  456. # `hermes config set browser.camofox.<key>` is accepted and user values are never stripped.
  457. "camofox": {},
  458. },
  459. # Stale git worktree lifecycle (`hermes -w`, `/worktree new`, subagent isolation, Desktop). The
  460. # sweep runs at `hermes -w` startup and every 6h from the cron ticker over every repo Hermes made
  461. # a worktree in. Trees idle past their tier (hermes-*/subagent-* 24h, named 72h) that are clean
  462. # and merged are removed; dirty or unpushed ones are archived to refs/hermes/archive/<tree>
  463. # first (`hermes worktree restore <name>`). Live trees and Kanban t_<hex> trees are never touched.
  464. "worktrees": {
  465. "archive_dirty": True, # false = never remove a dirty/unpushed tree (the pre-archive behaviour)
  466. # Untracked files larger than this (MB) are not archived, so a tree holding one is kept.
  467. "archive_max_file_mb": 50,
  468. # The sweep deletes archive refs older than this many days. 0 keeps them forever.
  469. "archive_retention_days": 30,
  470. # Optional size budget (GB) for idle trees: past it the oldest idle trees are archived and
  471. # removed first. Live, young and Kanban trees are never counted or touched. 0 = off.
  472. "max_total_gb": 0,
  473. "install_state_retention_days": 14, # installs/<key> of a missing checkout, unused this long, goes; 0 = never
  474. },
  475. # Filesystem checkpoints: snapshot the working directory once per turn (on the first
  476. # write_file/patch call); restore with /rollback. Opt-in via `hermes chat --checkpoints` or
  477. # enabled=True (most users never use /rollback). Single shared shadow store with real pruning.
  478. "checkpoints": {
  479. "enabled": False,
  480. # Max checkpoints per working directory; enforced by ref rewrite + GC of older commits.
  481. "max_snapshots": 20,
  482. # Hard ceiling on total ~/.hermes/checkpoints/ size (MB); the oldest checkpoint per project
  483. # is dropped round-robin until under the cap. 0 disables.
  484. "max_total_size_mb": 500,
  485. # Skip files larger than this (MB) when staging (datasets, model weights). 0 = no filter.
  486. "max_file_size_mb": 10,
  487. # Background sweep (CLI helper thread / gateway housekeeping tick, at most once per
  488. # min_interval_hours; never on the startup path — its git gc can block for tens of seconds):
  489. # deletes projects whose last_touch is older than retention_days, GCs the shared store when
  490. # refs moved, enforces max_total_size_mb, deletes legacy-* archives older than retention_days.
  491. # It NEVER deletes orphans (workdir missing on
  492. # disk) — a missing workdir may just be an unmounted volume/VPN, and an unattended sweep
  493. # must not guess. Orphans: `hermes checkpoints prune` (`--keep-orphans` to skip).
  494. "auto_prune": True,
  495. "retention_days": 7,
  496. "min_interval_hours": 24,
  497. },
  498. # Hard cap (chars) for one auto-loaded context file (SOUL.md, AGENTS.md, CLAUDE.md, .hermes.md,
  499. # .cursorrules) before head/tail truncation. null = scale with the model's context window (floor
  500. # 20K, ceiling 500K); a positive int pins a fixed cap. Separate from read_file limits.
  501. "context_file_max_chars": None,
  502. # Seconds to wait for a single context file read before skipping it with a warning. Guards startup
  503. # against network-backed filesystems (iCloud Drive, OneDrive, NFS) that can block a cold read.
  504. "context_file_read_timeout": 5.0,
  505. # Max chars per read_file call; larger reads are rejected with offset+limit guidance. 100K chars
  506. # ≈ 25–35K tokens.
  507. "file_read_max_chars": 100_000,
  508. # Seconds the first agent build waits for background MCP discovery before snapshotting its tool
  509. # list. Returns the instant discovery completes (no MCP servers → ~0s); the bound only bites
  510. # when a server is still connecting. Turn-1 latency knob only: a server that misses it is picked
  511. # up by the between-turns refresh (agent/turn_context.py), so keep it small — a dead server adds
  512. # this much to first-response latency.
  513. "mcp_discovery_timeout": 1.5,
  514. # Same bound for single-query mode (``hermes -q/-z``). With only ONE turn there is no
  515. # between-turns refresh, so a server that misses the window is invisible for the whole session;
  516. # the larger bound lets slow cold-start servers (npx, uvx, remote HTTP) land. Reachable servers
  517. # still only wait their real handshake time.
  518. "mcp_single_query_discovery_timeout": 15.0,
  519. "mcp": { # MCP runtime behavior (distinct from mcp_servers: definitions and auxiliary.mcp).
  520. # Auto-reload MCP connections when config.yaml's mcp_servers changes (CLI watcher). Every
  521. # reload rebuilds the tool surface and INVALIDATES the provider prompt cache (next message
  522. # re-sends the full prefix) — costly on long-context models. When false the watcher still
  523. # detects the change and prints /reload-mcp guidance.
  524. "auto_reload_on_config_change": True,
  525. # Max MCP servers connected (and their stdio child trees spawned) at once per discovery
  526. # pass — at boot, on /reload-mcp and on the config watcher's reconcile. Unbounded, a config
  527. # with N servers spawns N process trees in the same instant (RAM/CPU spike, 429 fan-out on
  528. # multi-profile fleets). 0 = unlimited.
  529. "discovery_concurrency": 4,
  530. },
  531. # Tool-output truncation. max_bytes: terminal_tool output cap in chars (head+tail kept; 50_000 ≈
  532. # 12-15K tokens). max_lines: max `limit` one read_file call may request before clamping.
  533. # max_line_length: per-line cap in read_file's line-numbered view (chars).
  534. "tool_output": {"max_bytes": 50000, "max_lines": 2000, "max_line_length": 2000},
  535. # Tool loop guardrails nudge models that repeat failed/non-progressing tool calls. Soft warnings
  536. # are always on; hard stops are opt-in so interactive sessions keep flowing.
  537. "tool_loop_guardrails": {
  538. "warnings_enabled": True,
  539. "hard_stop_enabled": False,
  540. # Unattended gateway/cron platforms hard-stop by default (nobody can /stop a model that
  541. # ignores warnings); interactive cli/tui/desktop/acp stay warning-only.
  542. "non_interactive_hard_stop_enabled": True,
  543. "warn_after": {"exact_failure": 2, "same_tool_failure": 3, "idempotent_no_progress": 2},
  544. "hard_stop_after": {
  545. "exact_failure": 5, "same_tool_failure": 8, "idempotent_no_progress": 5
  546. },
  547. # Per-turn hard ceilings for runaway-prone tools; counters reset every turn, always on
  548. # regardless of the thresholds above. Dozens of searches/subagents in ONE turn is already
  549. # pathological, hence low defaults. 0 = unlimited.
  550. "loop_caps": {
  551. "max_web_searches": 50, # web_search calls per turn
  552. "max_subagents": 50, # subagents spawned per turn
  553. },
  554. },
  555. "compression": {
  556. "enabled": True,
  557. # checkpoint_required: fail closed before lossy compaction unless an active memory provider
  558. # confirms checkpoint API compatibility and completes the checkpoint.
  559. "checkpoint_required": False,
  560. # progress_notices: when True, routine compression progress statuses (compacting/
  561. # preflight/pre-API/idle/retry) reach chat gateways instead of being filtered as noise.
  562. # Failure notices and manual /compress feedback are always visible.
  563. "progress_notices": False,
  564. # threshold: compress when context usage exceeds this ratio. Models with windows below 512K
  565. # are floored at 0.75 (raise-only) so compaction doesn't fire with half the window free; set
  566. # above 0.75 to override the floor.
  567. "threshold": 0.50,
  568. # threshold_tokens: optional absolute token cap — when set, compression triggers at the
  569. # lower of the ratio threshold and this count. Clamped to the model's context length.
  570. # Off by default: no single count suits windows from 64K to 1M+, so the ratio decides.
  571. "threshold_tokens": None,
  572. # "progress_notices": False, # opt-in (#52995): when True, routine compression
  573. "target_ratio": 0.20, # fraction of threshold to preserve as recent tail
  574. # tail_mode: "lean" = clamped 2.5%-of-window tail (10K floor / 25K cap) plus chunked
  575. # digests, anchor index, verbatim user messages and session_search pointers in the summary
  576. # (~3x fewer retained tokens; a few extra summarizer calls at the boundary). "legacy" =
  577. # 0.20×threshold verbatim tail (100-240K tokens on big windows).
  578. "tail_mode": "lean",
  579. # protect_last_n: minimum recent messages kept uncompressed, honoured up to a small count
  580. # floor; the verbatim tail is otherwise token-bounded and never above 20% of the window.
  581. "protect_last_n": 20,
  582. # min_tail_user_messages: REAL (actionable) user messages guaranteed to survive in the tail.
  583. # 1 = single last-user anchor; raise (e.g. 3) when bulky tool outputs fill the tail budget.
  584. "min_tail_user_messages": 1,
  585. # max_attempts: retry rounds before a turn gives up with "max compression attempts reached".
  586. # Raise (e.g. 6) for tool-schema-heavy sessions. Validated >= 1, cap 10.
  587. "max_attempts": 3,
  588. # proactive_prune_tokens: opt-in trigger (tokens) for the deterministic no-LLM tool-result
  589. # prune, independent of `threshold` (which rarely fires on large windows, so old tool output
  590. # is re-sent every turn); e.g. 48000 reclaims early. 0 = off. Tail protected by
  591. # `protect_last_n`. Built-in compressor only. Each committed prune rewrites sent history and
  592. # breaks the prompt-cache prefix — the min_reclaim gate below keeps those breaks episodic.
  593. "proactive_prune_tokens": 0,
  594. # Prune's summarize pass only touches tool results larger than this (chars); clamped >= 200
  595. # so a generated summary can't be re-summarized.
  596. "proactive_prune_min_result_chars": 8000,
  597. # A prune only commits when it reclaims at least this many tokens, then waits for a
  598. # trigger-sized runway to regrow before rearming. 0 = no minimum-savings gate.
  599. "proactive_prune_min_reclaim_tokens": 4096,
  600. # micro_compact: opt-in — after each turn fold the oldest un-absorbed exchange into a
  601. # rolling summary, amortizing compression cost. Off by default because every pass rewrites
  602. # sent history and breaks the prompt-cache prefix EVERY turn; enable only if the amortized
  603. # stall beats the cached-prefix discount. See website/docs/developer-guide/micro-compaction.md.
  604. "micro_compact": False,
  605. # Cadence: run a pass every Nth completed turn (1 = one cache break per turn, 5 = a fifth of
  606. # the breaks). Clamped >= 1; ignored unless micro_compact is true.
  607. "micro_compact_every_n_turns": 1,
  608. # Once the rolling summary exceeds this many tokens, the next pass re-summarizes it.
  609. "micro_compact_defrag_threshold_tokens": 2000,
  610. # Gateway session-hygiene force-compress threshold, by message count.
  611. "hygiene_hard_message_limit": 5000,
  612. # Max seconds the gateway waits for pre-agent hygiene compression WITHOUT forward progress.
  613. # Inactivity budget: a slow model still streaming tokens extends the wait.
  614. "hygiene_timeout_seconds": 30,
  615. # Absolute cap on the hygiene wait even while tokens are moving (bounds a trickle stream).
  616. # Clamped >= hygiene_timeout_seconds.
  617. "hygiene_total_ceiling_seconds": 600,
  618. "hygiene_failure_cooldown_seconds": 300, # skip repeated failed hygiene attempts
  619. # Max seconds an ARRIVING user turn is held while a streaming hygiene summary finishes;
  620. # bounds user-visible latency (keep under chat idle timeouts, Telegram ~30s). On expiry the
  621. # turn proceeds uncompressed; the detached worker keeps its watermark-fenced commit, so the
  622. # summary is adopted at the next safe boundary.
  623. "hygiene_max_turn_hold_seconds": 10,
  624. # Inactivity budget for in-agent compress_context (loop, /compress, preflight); same
  625. # progress-aware semantics as hygiene_timeout_seconds. 0 = disable the owned wrapper
  626. # (callers passing commit_fence, e.g. gateway hygiene, never use it). Floored at the auxiliary
  627. # compression request timeout (auxiliary.compression.timeout, min 300s): the host never judges
  628. # silence before the summary request itself would time out.
  629. "context_timeout_seconds": 120,
  630. # Absolute cap on the *pre-commit* compress_context wait (summary/stream phase) even while
  631. # tokens move. Clamped >= context_timeout_seconds when that is > 0. A started SessionDB
  632. # commit is never abandoned: past the ceiling it is logged (WARNING, then ERROR) and
  633. # surfaced on the warning channel while the host keeps waiting.
  634. "context_total_ceiling_seconds": 600,
  635. # Non-system head messages always kept verbatim, in ADDITION to the (always protected)
  636. # system prompt. 0 = pin nothing but system prompt + summary + tail.
  637. "protect_first_n": 3,
  638. # When True, auto-compression whose summary fails (aux error / non-JSON / timeout) aborts
  639. # instead of dropping the middle with a "summary unavailable" placeholder; the session
  640. # freezes at its size until /compress (bypasses the cooldown) or /new.
  641. "abort_on_summary_failure": False,
  642. # (Historical key name.) When True, gpt-5.4/5.5/5.6 and gpt-6 Astra (any slug containing
  643. # "astra" without "900k") on the ChatGPT Codex OAuth route raise their compaction trigger to
  644. # 85%: Codex hard-caps them at a 272K window, so the global 50% would compact at ~136K. False = global `threshold`. Only that route; the same models via
  645. # OpenAI direct, OpenRouter or another relay keep the global value.
  646. "codex_gpt55_autoraise": True,
  647. # Show the one-time autoraise banner; False keeps the autoraise, hides the notice.
  648. "codex_gpt55_autoraise_notice": True,
  649. # Codex app-server thread compaction mode. The codex agent owns the thread context, so
  650. # Hermes' summarizer cannot shrink it. native = codex decides; hermes = Hermes' threshold
  651. # triggers thread/compact/start; off = never auto-trigger.
  652. "codex_app_server_auto": "native",
  653. # Opt in to OpenAI server-side compaction on the Responses API. Only gpt-5.6-family on
  654. # api.openai.com or the Codex backend; local compression stays as fallback.
  655. "codex_responses_native": False,
  656. # Absolute server compaction trigger (input tokens). None follows the local trigger with a
  657. # safety margin; explicit values only clamp downward so the server goes first.
  658. "codex_responses_compact_threshold": None,
  659. # in_place: compaction rewrites the message list and system prompt WITHOUT rotating the
  660. # session id (no parent_session_id chain, no `name #N` renumbering), avoiding the session-rotation
  661. # bug cluster. Pre-compaction turns are soft-archived under the same id (active=0, compacted=1) —
  662. # still session_search-able. False = legacy rotating-compaction path.
  663. "in_place": True,
  664. # Per-model threshold overrides: keys substring-match the model name (longest wins), values
  665. # replace the global `threshold`, e.g. {"glm-5.2": 0.40}. Prefix a key with "<provider>:" to
  666. # scope it to one route ({"openai-codex:astra": 0.85} leaves Astra on OpenRouter/Nous at the
  667. # global value). The <512K floor (0.75) still applies raise-only on top.
  668. "model_thresholds": {},
  669. # Opt-in idle compaction (0 = off): a session resuming after this many idle seconds compacts up
  670. # front, before the first reply. Time-based complement to `threshold`; skipped when already at/below
  671. # threshold × target_ratio; honors the same cooldown/anti-thrash/lock guards. Example: 1800 = 30 min.
  672. "idle_compact_after_seconds": 0,
  673. # Opt-in: write the next summary in the background near the trigger; compaction uses (or waits for) it if it still covers the same messages.
  674. "prepare_ahead": False,
  675. },
  676. # Anthropic prompt caching (Claude via OpenRouter or native API). cache_ttl: "5m" | "1h" | "auto"
  677. # (auto = 1h for human-paced sessions — cli/tui/desktop/messaging — and 5m for subagent, cron,
  678. # oneshot, webhook, kanban, api, tool, batch); other non-falsy values are ignored; falsy (false, null, "off",
  679. # "disabled", "no", "none") disables caching.
  680. "prompt_caching": {"cache_ttl": "5m"},
  681. # OpenRouter settings. response_cache: X-OpenRouter-Cache header — identical requests return
  682. # cached responses at zero billing; independent of Anthropic prompt caching. response_cache_ttl:
  683. # seconds (1-86400), only used when response_cache is on. min_coding_score (0.0-1.0):
  684. # pareto-code router knob, applied only when model.model is "openrouter/pareto-code"; higher =
  685. # stronger/pricier coders, 0.65 = mid-tier, "" = let OpenRouter pick the strongest. Docs:
  686. # openrouter.ai/docs/guides/routing/routers/pareto-router
  687. "openrouter": {"response_cache": True, "response_cache_ttl": 300, "min_coding_score": 0.65},
  688. "bedrock": { # AWS Bedrock; only used when model.provider is "bedrock".
  689. "region": "", # empty = AWS_REGION env var → us-east-1
  690. "discovery": {
  691. "enabled": True, # auto-discover models via ListFoundationModels
  692. "provider_filter": [], # restrict to these providers, e.g. ["anthropic", "amazon"]
  693. "refresh_interval": 3600, # cache discovery results (seconds)
  694. },
  695. # Bedrock Guardrails: create one in the console, then set ID and version.
  696. # https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html
  697. "guardrail": {
  698. "guardrail_identifier": "", # e.g. "abc123def456"
  699. "guardrail_version": "", # e.g. "1" or "DRAFT"
  700. "stream_processing_mode": "async", # "sync" | "async"
  701. "trace": "disabled", # "enabled" | "disabled" | "enabled_full"
  702. },
  703. },
  704. # Auxiliary model config — provider/model per side task. provider "auto" = auto-detect;
  705. # empty model = provider's default aux model; all tasks fall back to
  706. # openrouter:google/gemini-3-flash-preview when the configured provider is unavailable.
  707. # extra_body is forwarded verbatim as request body fields for that task, e.g. OpenRouter
  708. # routing prefs / Pareto Code floor:
  709. # auxiliary:
  710. # compression:
  711. # extra_body:
  712. # provider: {order: [anthropic, google], sort: throughput} # or price | latency
  713. # plugins: [{id: pareto-router, min_coding_score: 0.5}]
  714. # Each task is independent — main-agent provider_routing and openrouter.min_coding_score
  715. # do NOT propagate to aux calls by design.
  716. "auxiliary": {
  717. # Same-provider retries for a transient blip (reset/timeout/5xx/408) on ANY aux call before
  718. # falling back; clamped [0,6]. Matters for pinned calls (MoA advisors) where provider
  719. # fallback is not meaningful recovery.
  720. "transient_retries": 2,
  721. # When true, the auto-chain's OpenRouter step is skipped unless the fallback model ends in
  722. # ":free" — a PAID lane is never used for background aux traffic even with
  723. # OPENROUTER_API_KEY set.
  724. "free_only": False,
  725. # Override the auto-chain's OpenRouter fallback model (default google/gemini-3.6-flash,
  726. # PAID). Pair e.g. "nvidia/nemotron-3-ultra-550b-a55b:free" with free_only: true. A one-time
  727. # WARNING is logged whenever a non-":free" model is engaged.
  728. "openrouter_model": "",
  729. # Endpoints that reject NON-streaming chat (HTTP 400): aux calls are sent with stream=True
  730. # and aggregated. Case-insensitive URL substrings; some vendor endpoints are always
  731. # stream-only.
  732. "stream_only_base_urls": [],
  733. # Per-task blocks share one shape (_aux): provider "auto" = inherit the main model; base_url
  734. # overrides provider; api_key falls back to OPENAI_API_KEY; reasoning_effort:
  735. # none|minimal|low|medium|high|xhigh|max|ultra ("" = provider default); extra_body =
  736. # OpenAI-compatible request fields. Vision: download_timeout = image HTTP download (s).
  737. "vision": _aux(120, download_timeout=30),
  738. # web_extract, session_search, skills_hub: no aux LLM any more, leftover blocks are ignored.
  739. # Compression: raise timeout for local models. no_progress_timeout: seconds a streamed call
  740. # goes without a substantive chunk before it fails fast into retry/fallback; None = built-in
  741. # 60s default. Independent of "timeout" (the overall request budget). See #108104.
  742. "compression": _aux(120, no_progress_timeout=None),
  743. "approval": _aux(30), # classifier — a fast/cheap model is recommended
  744. # /review reviewer: a full subagent on the async delegation rail, credentials resolved like
  745. # delegation.provider pins. "auto" + "" = main agent's model. api_mode forces transport:
  746. # chat_completions | anthropic_messages | codex_responses.
  747. "review": {"provider": "auto", "model": "", "base_url": "", "api_key": "", "api_mode": ""},
  748. "mcp": _aux(30),
  749. # prefer_fast_model opts in to the provider fast tier; auto otherwise = main model.
  750. "title_generation": {
  751. "enabled": True,
  752. "model_upgrade_enabled": True, # False = keep the instant derived title, never call a model
  753. # session_search no longer uses an aux LLM (#27590); leftover auxiliary.session_search is ignored.
  754. "provider": "auto",
  755. "model": "",
  756. "prefer_fast_model": False,
  757. "base_url": "",
  758. "api_key": "",
  759. "timeout": 30,
  760. "extra_body": {},
  761. "reasoning_effort": "",
  762. "language": "",
  763. },
  764. "memory_query_rewrite": _aux(8, reasoning_effort=False),
  765. "tts_audio_tags": _aux(30),
  766. "voice_chat": {**_aux(120), "reasoning_effort": "none"}, # agent/voice_turn_route.py; off = lowest valid
  767. # Kanban: triage_specifier expands a Triage one-liner into a spec; kanban_decomposer a JSON graph.
  768. "triage_specifier": _aux(120),
  769. "kanban_decomposer": _aux(180),
  770. "profile_describer": _aux(60), # 1-2 sentence profile blurb; short, cheap
  771. "goal_judge": _aux(60), # /goal satisfaction + contract drafting; JSON calls
  772. "group_router": _aux(20), # Group Chat routing "auto": who answers; fast/cheap model OK
  773. # Curator skill-usage review can take minutes on reasoning models (umbrellas over hundreds
  774. # of skills); route cheaper via `hermes model` → auxiliary → Curator.
  775. "curator": _aux(600),
  776. "monitor": _aux(60), # important-mail 0-10 scorer; high-volume, small model fine
  777. # Post-turn self-improvement fork (save memory / patch skill). "auto" = main model replaying
  778. # the full conversation (warm cache); other models replay a compact digest (~3-5x cheaper).
  779. # enabled=false skips auto spawns (/refine still works). An explicit max_input_tokens caps
  780. # the SUM of replayed input tokens over the review loop (iterations capped at 16); the loop
  781. # stops before crossing it. When unset, the runtime derives a budget from the active model
  782. # context window. <= 0 = unlimited.
  783. # reasoning_effort is IGNORED while the review stays on the main model: the fork inherits the
  784. # conversation's reasoning config verbatim so its request bytes keep the parent's warm
  785. # prompt-cache prefix (#30532). Set provider/model below to route the review to another model
  786. # if you want a different effort level; a one-time warning says so when the key is set.
  787. "background_review": {"enabled": True, **_aux(120)},
  788. # No reasoning_effort on MoA blocks by design — configured PER SLOT in the preset
  789. # (moa.presets.<name>.reference_models[].reasoning_effort / aggregator.reasoning_effort).
  790. "moa_reference": _aux(900, reasoning_effort=False),
  791. "moa_aggregator": _aux(900, reasoning_effort=False),
  792. },
  793. "display": {
  794. "compact": False,
  795. "personality": "",
  796. "resume_display": "full",
  797. # Recap tuning for /resume and startup resume.
  798. "resume_exchanges": 10, # max user+assistant pairs to show
  799. "resume_max_user_chars": 300, # truncate user message text
  800. "resume_max_assistant_chars": 200, # truncate non-last assistant text
  801. "resume_max_assistant_lines": 3, # truncate non-last assistant lines
  802. # Skip tool-call-only assistant entries in the recap so it isn't dominated by `[2 tool
  803. # calls: ...]` lines; False shows them inline.
  804. "resume_skip_tool_only": True,
  805. "busy_input_mode": "interrupt", # interrupt | queue | steer
  806. # steer mode: false hides only the "Steered into current run" bubble; steering itself still
  807. # happens.
  808. "busy_steer_ack_enabled": True,
  809. # Classic CLI multiline beyond Alt+Enter: Ctrl+J newline, trailing backslash+Enter
  810. # continues, Shift+Enter reported distinctly. False restores the c-j submit fallback for
  811. # POSIX PTYs whose plain Enter arrives as LF.
  812. "cli_multiline_shortcuts": True,
  813. # `hermes`/`hermes chat` launches "cli" (prompt_toolkit REPL) | "tui" (Ink); --cli, --tui, HERMES_TUI=1 win.
  814. # cli_layout = the REPL's look: "modern" (glyph rows, status under the composer) | "classic" (boxed panels).
  815. "interface": "cli", "cli_layout": "modern",
  816. # Native TUI uses the terminal's primary buffer and scrollback instead of the custom
  817. # alternate-screen viewport. Flags win: `--native` / `--tui-native` and `--cli`.
  818. "tui_native": False,
  819. # `hermes --tui` auto-resumes the most recent human-facing session (like `hermes -c`).
  820. # HERMES_TUI_RESUME=<id> always wins.
  821. "tui_auto_resume_recent": False,
  822. # Desktop reopens the last chat/page on cold start (also in Settings → Appearance).
  823. "resume_last_session": True,
  824. # One-time TUI hint ("subagents working · /agents to watch live") on first delegation.
  825. "tui_agents_nudge": True,
  826. "bell_on_complete": False,
  827. "bell_on_prompt": False, # bell when a blocking prompt opens (clarify/approval/sudo)
  828. # Stream reasoning live before the response; otherwise thinking models show only a spinner
  829. # for tens of seconds.
  830. "show_reasoning": True,
  831. # Post-response "Reasoning" recap collapses to 10 lines; true prints it all (live streaming
  832. # is always full).
  833. "reasoning_full": False,
  834. # Background self-improvement notices in chat: "off" (review still runs) | "on" (generic "💾
  835. # Memory updated") | "verbose" (content preview). Per-platform via
  836. # display.platforms.<platform>.memory_notifications.
  837. "memory_notifications": "on",
  838. # Gateway notices when a terminal(background=true) process finishes: "concise" (one line;
  839. # failures append an output tail) | "all" (running updates + final raw output) | "result"
  840. # (final raw only) | "error" (raw only on non-zero exit) | "off".
  841. "background_process_notifications": "concise",
  842. "streaming": False,
  843. "timestamps": False, # message timestamps (CLI labels, TUI rows, desktop transcript)
  844. "timestamp_format": "%H:%M", # strftime format, e.g. "%b-%d %H:%M"
  845. "final_response_markdown": "strip", # render | strip | raw
  846. # Preserve recent classic-CLI output across Ctrl+L, /redraw and resize clears; disable if an
  847. # emulator misbehaves with replayed scrollback.
  848. "persistent_output": True,
  849. "persistent_output_max_lines": 200,
  850. # Also clear terminal scrollback on classic-CLI full redraw/resize recovery; enable when a
  851. # terminal/tmux stack stamps stale prompt chrome into scrollback.
  852. "cli_rebuild_scrollback_on_redraw": False,
  853. "persist_prompts": True, # one-line scrollback summary of resolved approval/clarify prompts
  854. "inline_diffs": True, # inline diff previews for write_file/patch/skill_manage
  855. "inline_images": "auto", # CLI/TUI transcript images (attachments, tool results): auto|kitty|iterm|unicode|off
  856. # Append a one-line advisory to the final response when a write_file/patch failed this turn
  857. # and was never superseded by a successful write to the same path (catches "half the
  858. # parallel patches failed, model claims success").
  859. "file_mutation_verifier": True,
  860. # Nous credits status-bar notices (usage bands, grant-spent, depleted/restored). False mutes
  861. # them; balance data and /usage keep working.
  862. "credits_notices": True,
  863. # Append a one-line explanation when a turn ends with no usable reply (empty after retries,
  864. # truncated stream, pending tool result, iteration/budget limit) instead of the bare
  865. # "(empty)" sentinel.
  866. "turn_completion_explainer": True,
  867. "show_cost": False, # $ cost in the status bar
  868. "battery": False, # battery read-out first in status bar; no-op w/o battery
  869. # Focus view (/focus): display-only. Pins tool_progress to "off", reports per-turn
  870. # hidden-line count, pins a "focus" status segment. focus_saved_tool_progress holds the mode
  871. # /focus off restores. Never affects what the model sees (focus_view.py).
  872. "focus_view": False,
  873. "focus_saved_tool_progress": "all",
  874. "skin": "default",
  875. # UI language for static messages (approval prompts, some gateway slash replies); not agent
  876. # responses/logs/tool outputs. en, zh, ja, de, es, fr, tr, uk; unknown → en.
  877. "language": "en",
  878. # TUI busy indicator: kaomoji | emoji | unicode (braille) | ascii. `/indicator <style>`.
  879. "tui_status_indicator": "kaomoji",
  880. # Seconds between idle prompt_toolkit redraws in the classic CLI; keeps wall-clock
  881. # status-bar read-outs ticking and the bottom chrome from going stale. 0 disables it if it
  882. # fights terminal auto-scroll in non-fullscreen mode.
  883. # See #45592.
  884. "cli_refresh_interval": 1.0,
  885. # Vi/vim keybindings in the CLI input composer (config-only, no slash command).
  886. # Off by default, preserving prompt_toolkit's standard emacs bindings.
  887. "vim_mode": False,
  888. "user_message_preview": { # CLI: submitted user-message lines echoed to scrollback
  889. "first_lines": 2,
  890. "last_lines": 2,
  891. },
  892. # Gateway: natural mid-turn assistant status messages. Desktop: keep mid-turn narration
  893. # between tool calls instead of collapsing to the final message.
  894. "interim_assistant_messages": True,
  895. # Engine warning/failure notifications stay visible unless an operator opts in.
  896. # Does not suppress task results, manual commands, or existing logs.
  897. "suppress_warning_notifications": False,
  898. # Codex Responses commentary channel: true delivers completed commentary as mid-turn interim
  899. # updates; false routes it to reasoning (visible only with show_reasoning).
  900. "show_commentary": True,
  901. "tool_progress_command": False, # enable /verbose command in messaging gateway
  902. # display.tool_progress_overrides is deprecated (use display.platforms); a user-set value is
  903. # still honored at runtime and folded into platforms by migration.
  904. "tool_preview_length": 0, # max chars for tool call previews (0 = no limit)
  905. # Human-phrased status labels for built-in tools ("Reading <file>") in CLI spinner and
  906. # gateway/desktop tool-progress; custom/plugin/MCP tools use the raw preview.
  907. "friendly_tool_labels": True,
  908. # CLI-only post-turn line: "⋯ 12.4s · edited 2 files +18 -3 · read 4 files · ran 3
  909. # commands". Never in quiet/non-interactive or gateway surfaces (own footer).
  910. "turn_summary": True,
  911. # CLI-only: cumulative turn output tokens on the live spinner ("· ↓ 1.2k tok").
  912. "spinner_token_flow": True,
  913. # Gateway tool-progress grouping where edits are supported: "accumulate" edits one bubble |
  914. # "separate" one message per tool (noisier). Needs tool_progress enabled. Per-platform:
  915. # display.platforms.<platform>.tool_progress_grouping.
  916. "tool_progress_grouping": "accumulate",
  917. # Custom long-running status phrases. Defaults: gateway/assets/status_phrases.yaml.
  918. # `path`/`paths` = HERMES_HOME-relative YAML files/dirs (or conventional status_phrases.yaml
  919. # / status_phrases/*.yaml). Keys: status, generic. mode: "append" (default) | "replace".
  920. # Per-platform: display.platforms.<platform>.status_phrases.
  921. "status_phrases": {},
  922. # Reasoning summary rendering: "code" (💭 fenced block) | "blockquote" ("> ") | "subtext"
  923. # ("-# " Discord small grey text; Discord's default). Per-platform via
  924. # display.platforms.<platform>.reasoning_style.
  925. "reasoning_style": "code",
  926. # Auto-delete EphemeralReply system notices ("✨ New session started!", …) after N seconds
  927. # where deletion is supported (Telegram; others ignore). Agent responses are never touched.
  928. # 0 = disabled.
  929. "ephemeral_system_ttl": 0,
  930. # Per-platform display/streaming overrides; unset keys fall through to the global. Telegram
  931. # has smooth native draft streaming (on); Discord/Slack only edit-based streaming, which
  932. # flickers (off). Gap-fillers only: explicit user values win, and the global
  933. # streaming.enabled master switch still gates everything.
  934. "platforms": {
  935. "telegram": {"streaming": True},
  936. "discord": {"streaming": False},
  937. "slack": {"streaming": False},
  938. # WeCom native streaming (msgtype "stream" via aibot_respond_msg).
  939. "wecom": {"streaming": True},
  940. },
  941. # Gateway runtime footer on the FINAL message, e.g. `model · 68% · ~/projects/hermes`.
  942. # Per-platform: display.platforms.<platform>.runtime_footer.
  943. "runtime_footer": {
  944. "enabled": False,
  945. # order shown; drop any to hide. Opt-in extras: latency, served_model (alias → the
  946. # deployment a routing proxy reported / Hermes' fallback route).
  947. "fields": ["model", "context_pct", "cwd"],
  948. },
  949. # CLI/TUI status bar fields. Non-empty = only listed fields show (built-in order kept,
  950. # config controls visibility not ordering); empty = default set. Available: model,
  951. # context_detail, context_pct, cache_hit, latency, tps, compressions, bg_tasks,
  952. # bg_processes, bg_subagents, goal, git_branch (⎇ current branch, opt-in only), duration,
  953. # prompt_elapsed, idle_since, focus, yolo,
  954. # stash, battery, title, total_tokens (session Σ, opt-in only). Narrow terminals still drop
  955. # context_detail/prompt_elapsed/idle_since.
  956. "status_bar": {
  957. "fields": [],
  958. },
  959. "copy_shortcut": "auto", # "auto" (platform default) | ctrl_c | ctrl_shift_c | disabled
  960. # Petdex animated mascot (github.com/crafter-station/petdex): cosmetic sprite across
  961. # CLI/TUI/desktop, managed with `hermes pets`. No effect on prompt caching.
  962. "pet": {
  963. "enabled": False,
  964. "slug": "", # active pet slug in get_hermes_home()/pets/; empty → first installed
  965. # auto (detect kitty/iTerm2/sixel, else unicode half-blocks) | kitty | iterm | sixel |
  966. # unicode | off
  967. "render_mode": "auto",
  968. # Size scalar relative to native 192×208 frames, shared by desktop canvas and CLI/TUI
  969. # column width. Half-block fallback clamps to a legibility floor.
  970. "scale": 0.33,
  971. "unicode_cols": 0, # Hard override for terminal column width; 0 = derive from scale.
  972. },
  973. },
  974. "webapp": {"enabled": False, "host": "127.0.0.1", "port": 9120, "public_url": ""}, # gateway/webapp_listener.py
  975. "dashboard": {
  976. # Visual theme: "default" | "midnight" | "ember" | "mono" | "cyberpunk" | "rose"
  977. "theme": "default",
  978. # Process-isolation rollout controls. Read via the raw config loader, so tui_gateway.server
  979. # also owns explicit defaults.
  980. "turn_isolation": False,
  981. "compute_host_heartbeat_secs": 15,
  982. "compute_host_respawn_max": 3,
  983. # Token/cost analytics surfaces are hidden by default: the numbers are a local LOWER-BOUND
  984. # estimate, not billing — only successful main-agent responses with a response.usage count;
  985. # auxiliary calls, retries, fallbacks and cache writes are missed, so the total can be
  986. # 10x-100x under the provider bill.
  987. "show_token_analytics": False,
  988. # IPs / bounded CIDRs of reverse proxies trusted to supply X-Forwarded-Proto/-For. Loopback
  989. # always trusted; wildcards and /0 rejected (spoofing guard).
  990. "trusted_proxies": [],
  991. # WebSocket keepalive (seconds), NON-loopback binds only: loopback always disables the
  992. # protocol ping so an event-loop stall never kills a healthy local connection.
  993. "ws_ping_interval": 20.0,
  994. "ws_ping_timeout": 20.0,
  995. # Grace (seconds) before a WS-orphaned gateway session is interrupted/reaped after its
  996. # client disconnects. 0 = park forever. Env: HERMES_TUI_WS_ORPHAN_REAP_GRACE_S.
  997. "ws_orphan_reap_grace_s": 20.0,
  998. # A detached RUNNING turn is only interrupted once its activity clock (API waits, stream
  999. # tokens, tool heartbeats) has been idle this many seconds; an active turn runs to
  1000. # completion. Default = agent.turn_liveness.timeout_s. 0 = interrupt at grace.
  1001. # See #100325, #98028.
  1002. "ws_orphan_activity_stale_s": 600.0,
  1003. # On gateway boot, close tui/desktop/subagent rows orphaned by a dead gateway (start AND
  1004. # newest message older than HERMES_TUI_SESSION_TTL_S, default 6h) with
  1005. # end_reason='startup_orphan_reap'; otherwise they stay phantom "active" forever.
  1006. # Messaging-gateway and live sessions are never touched; swept rows stay resumable.
  1007. # The ws-orphan grace timer above is in-process, so a gateway restart (update, crash, systemd)
  1008. # leaves disconnected sessions ``ended_at IS NULL`` forever — phantom "active" rows in /resume and
  1009. # dashboards. See #65194.
  1010. "startup_orphan_sweep": True,
  1011. # OAuth gate (engaged when --host is set and --insecure is not), read by the Nous Portal
  1012. # plugin. Env HERMES_DASHBOARD_OAUTH_CLIENT_ID / HERMES_DASHBOARD_PORTAL_URL win when
  1013. # non-empty. Empty client_id = no provider; empty portal_url = production.
  1014. "oauth": {
  1015. "client_id": "", # agent:{instance_id} — Portal provisions this
  1016. "portal_url": "",
  1017. },
  1018. # Username/password gate (dashboard_auth/basic plugin, no OAuth IDP). Active when username
  1019. # plus password_hash (preferred) or password (hashed in-memory) are set; empty username =
  1020. # no-op. Env HERMES_DASHBOARD_BASIC_AUTH_USERNAME / _PASSWORD_HASH / _PASSWORD / _SECRET /
  1021. # _TTL_SECONDS win when non-empty. secret signs session tokens; empty = random per-process
  1022. # key (sessions die on restart, no multi-worker) — set 32+ random bytes. Hash:
  1023. # plugins.dashboard_auth.basic.hash_password('PW').
  1024. "basic_auth": {
  1025. "username": "",
  1026. "password_hash": "", # scrypt$...
  1027. "password": "",
  1028. "secret": "",
  1029. "session_ttl_seconds": 0, # 0 → plugin default (12h)
  1030. },
  1031. "session_token_auth": {"enabled": True}, # session_token plugin: a provisioned HERMES_DASHBOARD_SESSION_TOKEN (literal or file:<path>) authorizes the gated dashboard; enabled: false opts out
  1032. # Drain-control token auth (dashboard_auth/drain plugin): the secret is NOT here (env
  1033. # HERMES_DASHBOARD_DRAIN_SECRET); no-op unless >=256-bit, weak secrets rejected (fail-closed).
  1034. "drain_auth": {"scope": "drain", "min_secret_chars": 43},
  1035. # Public URL (env HERMES_DASHBOARD_PUBLIC_URL): full authority (scheme + host + optional
  1036. # prefix, e.g. https://example.com/hermes) for the OAuth redirect_uri; its hostname is
  1037. # trusted by Host/Origin guards and engages the auth gate when non-loopback. For proxies
  1038. # that don't forward X-Forwarded-Host/-Proto/-Prefix; X-Forwarded-Prefix is then IGNORED on
  1039. # the OAuth path. Empty or malformed (no http(s):// + host, or quote/angle/whitespace chars)
  1040. # = reconstruct from headers.
  1041. "public_url": "",
  1042. },
  1043. "privacy": {
  1044. "redact_pii": False, # hash user IDs and strip phone numbers from LLM context
  1045. },
  1046. # Text-to-speech. Each provider accepts an optional `max_text_length:` override for the
  1047. # per-request input-character cap; omit to use the provider's documented limit (OpenAI 4096, xAI
  1048. # 15000, MiniMax 10000, ElevenLabs 5k-40k model-aware, Gemini 32000, Edge 5000, Mistral 4000,
  1049. # NeuTTS/KittenTTS 2000).
  1050. "tts": {
  1051. # "edge" (free) | "elevenlabs" (premium) | "openai" | "xai" | "minimax" | "mistral" |
  1052. # "gemini" | "deepinfra" | "neutts" (local) | "kittentts" (local) | "piper" (local)
  1053. "provider": "edge",
  1054. # Seconds a local engine (Piper, KittenTTS) stays loaded after the last speech toggle
  1055. # turns off, so a quick re-activation (wake word, voice-chat restart) skips the reload.
  1056. # 0 unloads immediately.
  1057. "keep_warm_seconds": 60,
  1058. "streaming": {
  1059. # Shortest first sentence (chars) spoken on its own by streaming TTS; shorter openers
  1060. # ride with the next sentence. 20 suits English; CJK voice setups use ~6.
  1061. "min_len": 20,
  1062. },
  1063. "edge": {
  1064. # Popular: AriaNeural, JennyNeural, AndrewNeural, BrianNeural, SoniaNeural
  1065. "voice": "en-US-AriaNeural",
  1066. },
  1067. "elevenlabs": {
  1068. "voice_id": "pNInz6obpgDQGcFmaJgB", # Adam
  1069. "model_id": "eleven_multilingual_v2",
  1070. },
  1071. "openai": {
  1072. "model": "gpt-4o-mini-tts",
  1073. # gpt-4o-mini-tts voices: alloy, ash, ballad, cedar, coral, echo, fable, marin, nova,
  1074. # onyx, sage, shimmer, verse
  1075. "voice": "alloy",
  1076. # Forwarded verbatim in the request body for OpenAI-compatible servers whose cloned
  1077. # voices demand it (400 consent_required otherwise); "" sends nothing.
  1078. "consent_attestation": "",
  1079. # Raw PCM rate for streaming playback. OpenAI emits 24 kHz; a compatible endpoint that
  1080. # reports its rate (X-Audio-Sample-Rate header) overrides this automatically.
  1081. "pcm_sample_rate": 24000,
  1082. },
  1083. "gemini": {
  1084. "model": "gemini-2.5-flash-preview-tts",
  1085. "voice": "Kore",
  1086. # Gemini 3.1: aux-model rewrite inserts [audio tags] into the TTS script only.
  1087. "audio_tags": False,
  1088. # Optional local text file with performance direction; may include a `{transcript}`
  1089. # placeholder, else the live transcript is appended.
  1090. "persona_prompt_file": "",
  1091. },
  1092. "xai": {
  1093. "voice_id": "eve", # or a custom voice ID (docs.x.ai custom voices)
  1094. "language": "en", # BCP-47 code ("en", "pt-BR") or "auto"
  1095. "speed": 1.0, # 0.7–1.5
  1096. "auto_speech_tags": False, # insert expressive audio tags via LLM rewrite
  1097. "optimize_streaming_latency": 0, # 0–2, trades quality for lower latency
  1098. "sample_rate": 24000, # 22050 / 24000 / 44100 / 48000
  1099. "bit_rate": 128000, # MP3 bitrate; only applies when codec=mp3
  1100. },
  1101. "mistral": {
  1102. "model": "voxtral-mini-tts-2603",
  1103. "voice_id": "c69964a6-ab8b-4f8a-9465-ec0925096ec8", # Paul - Neutral
  1104. },
  1105. "minimax": {"model": "speech-02-hd", "voice_id": "English_expressive_narrator"},
  1106. "kittentts": {
  1107. "model": "KittenML/kitten-tts-nano-0.8-int8", # nano 25MB; micro 41MB; mini 80MB
  1108. "voice": "Jasper",
  1109. },
  1110. "neutts": {
  1111. "ref_audio": "", # path to reference voice audio (empty = bundled default)
  1112. "ref_text": "", # path to reference voice transcript (empty = bundled default)
  1113. "model": "neuphonic/neutts-air-q4-gguf", # HuggingFace model repo
  1114. "device": "cpu", # cpu, cuda, or mps
  1115. },
  1116. "piper": {
  1117. # Voice name (downloaded on first use) or absolute path to a .onnx file; list:
  1118. # github.com/OHF-Voice/piper1-gpl/blob/main/docs/VOICES.md. Optional keys: voices_dir
  1119. # (~/.hermes/cache/piper-voices/), use_cuda, length_scale (2.0 = twice as slow),
  1120. # noise_scale, noise_w_scale, volume, normalize_audio.
  1121. "voice": "en_US-lessac-medium",
  1122. },
  1123. "deepinfra": {
  1124. "model": "", # empty = first tts-tagged model from the live catalog
  1125. "voice": "default",
  1126. # optional "base_url" key overrides DEEPINFRA_BASE_URL for TTS only
  1127. },
  1128. },
  1129. "stt": {
  1130. "enabled": True,
  1131. # Echo the raw transcript of gateway voice messages back as a 🎙️ message.
  1132. "echo_transcripts": True,
  1133. # No seeded "provider" (a stored value is an explicit pick; unset = autodetect): local | groq |
  1134. # openai | mistral | elevenlabs | deepinfra | xai. Global language hint unless a per-provider one
  1135. # overrides it; "en" because Whisper auto-detect misreads short clips; "" = auto; "es", ...
  1136. "language": "en",
  1137. "streaming": False, # live partial text while speaking (openai/xai/elevenlabs); failure = file path
  1138. # Pre-upload ffmpeg silence trim (local whisper uses VAD); failure = raw upload.
  1139. "cloud_trim_silence": True,
  1140. "cloud_trim_threshold_db": -40, # quieter than this counts as silence
  1141. "cloud_trim_keep_ms": 300, # how much of each pause survives (natural pacing)
  1142. "local": {
  1143. "model": "base", # tiny, base, small, medium, large-v3, turbo
  1144. "language": "", # blank = inherit stt.language; set "en", "es", ... to force
  1145. "initial_prompt": "",
  1146. # Anti-hallucination (faster-whisper decodes junk from silence). vad: Silero filter
  1147. # (false = raw audio, for music/ambient). A segment is dropped only if no_speech_prob
  1148. # ABOVE no_speech_prob_threshold AND avg_logprob BELOW logprob_threshold.
  1149. "vad": True,
  1150. "vad_min_silence_ms": 500, # min silence (ms) that splits speech chunks
  1151. "no_speech_prob_threshold": 0.6,
  1152. "logprob_threshold": -1.0,
  1153. "unload_after_idle_seconds": 0, # 0 = never; e.g. 300 frees the model after 5min
  1154. },
  1155. "groq": {
  1156. "model": "whisper-large-v3-turbo", # whisper-large-v3-turbo, whisper-large-v3
  1157. "language": "", # blank = inherit stt.language; set "en", "es", ... to force
  1158. },
  1159. "openai": {
  1160. # whisper-1, gpt-4o-mini-transcribe, gpt-4o-transcribe, gpt-transcribe
  1161. "model": "whisper-1",
  1162. "streaming_model": "gpt-live-transcribe", # stt.streaming; the one model with mid-utterance deltas
  1163. "language": "", # blank = inherit stt.language; set "en", "es", ... to force
  1164. "timeout": 60, # seconds; allow self-hosted backends time to cold-start
  1165. "max_retries": 1, # OpenAI SDK transport retries
  1166. },
  1167. "mistral": {
  1168. "model": "voxtral-mini-latest", # voxtral-mini-latest, voxtral-mini-2602
  1169. "language": "", # blank = inherit stt.language; set "en", "es", ... to force
  1170. },
  1171. "xai": {
  1172. "model": "", # "" = STT_XAI_MODEL or grok-voice-transcribe-2.0; or grok-voice-transcribe-1.0
  1173. "language": "", # blank = inherit stt.language; set "en", "es", ... to force
  1174. },
  1175. "elevenlabs": {
  1176. "model_id": "scribe_v2", # scribe_v2, scribe_v1
  1177. "language_code": "", # blank = inherit stt.language; set "eng", "spa", ... to force
  1178. "tag_audio_events": False,
  1179. "diarize": False,
  1180. },
  1181. "deepinfra": {
  1182. "model": "", # empty = first stt-tagged model from the live catalog
  1183. # optional "base_url" key overrides DEEPINFRA_BASE_URL for STT only
  1184. },
  1185. },
  1186. "voice": {
  1187. # How the Desktop voice conversation is wired:
  1188. # chained — STT → Hermes turn → TTS (the stt.* / tts.* providers below)
  1189. # gpt-live — one full-duplex voice model (OpenAI GPT-Live) owns the mic and speaker and
  1190. # DELEGATES every real request to Hermes (any model / provider you have
  1191. # selected); needs an OpenAI API key. $0.05/min voice layer billing.
  1192. "voice_chat_mode": "chained",
  1193. "gpt_live": {
  1194. "model": "gpt-live-1",
  1195. "voice": "marin", # marin | quartz | ripple | vesper | willow | stone | gleam | meridian | ...
  1196. # Extra sentences appended to the live model's conversation persona (tone, pacing, language).
  1197. "instructions": "",
  1198. # optional "api_key" / "base_url" keys override the OpenAI audio credentials for this mode only
  1199. },
  1200. "record_key": "ctrl+b",
  1201. "submit_mode": "direct", # TUI: direct submits immediately; draft = editable transcript
  1202. "max_recording_seconds": 120,
  1203. "auto_tts": False,
  1204. # Desktop remote clients call STT/TTS providers DIRECTLY (config + key fetched over
  1205. # authenticated REST at session start) instead of relaying via the gateway.
  1206. "client_direct": True,
  1207. "beep_enabled": True, # record start/stop beeps in CLI voice mode
  1208. "beep_volume": 0.3, # beep amplitude multiplier, 0.0-1.0
  1209. "thinking_sound": True, # ambient bubble sound while the agent works (volume = beep_volume)
  1210. "silence_threshold": 200, # RMS below this = silence (0-32767)
  1211. "silence_duration": 3.0, # seconds of silence before auto-stop
  1212. "barge_in": True, # interrupt the agent / stop TTS when the user starts talking
  1213. # Trip suppression after TTS onset (mic stays live the whole turn).
  1214. "barge_in_grace_seconds": 0.5,
  1215. # Speech trigger = quiet-room floor x this (floor calibrated BEFORE playback).
  1216. "barge_in_threshold_multiplier": 3.0,
  1217. # Saying EXACTLY one of these (case-insensitive, punctuation ignored) ends the voice chat
  1218. # instead of going to the agent. [] disables.
  1219. "stop_phrases": ["stop"],
  1220. },
  1221. # Native images (vision_analyze, browser screenshots, replayed user images) are re-sent on every later call.
  1222. "vision": {
  1223. # Byte budget for one embedded image (clamped 64 KiB..4 MiB). Raise it for dense phone
  1224. # screenshots of tables the model calls "unreadable" at 256 KB.
  1225. "embed_target_bytes": 256 * 1024,
  1226. # How often vision_analyze may embed the SAME image (region crops included) per session.
  1227. # null = 3 inside delegated subagents (they run unattended), unlimited for the main agent;
  1228. # an explicit number applies everywhere; 0 = unlimited.
  1229. "max_calls_per_image": None,
  1230. "replay_recent_images": 3, # newest user images re-sent on turns rebuilt from state.db; 0 = off
  1231. },
  1232. # "Hey Hermes" hands-free wake word: always-on, on-device hotword detection that starts a fresh
  1233. # voice session. Off by default; toggle with /wake.
  1234. "wake_word": {
  1235. "enabled": False,
  1236. "surface": "auto", # eligible surface: "auto" (first claimant) | "cli" | "tui" | "gui"
  1237. "input_device": None, # PortAudio input device index/name; null = process default
  1238. "capture": "auto", # auto | local | client (desktop streams mic via wake.feed)
  1239. # auto: first platform-supported engine (openwakeword, sherpa, porcupine).
  1240. # Explicit choices stay pinned. Porcupine needs PORCUPINE_ACCESS_KEY.
  1241. "provider": "auto",
  1242. # sherpa: this IS the detected phrase; other engines: cosmetic label (detection is keyed by
  1243. # the model/keyword below)
  1244. "phrase": "hey hermes",
  1245. "sensitivity": 0.6, # 0.0-1.0 threshold, consistent across engines (higher = stricter)
  1246. # openWakeWord/pyopen-wakeword only: consecutive over-threshold frames to fire (higher = fewer
  1247. # false triggers, more latency; 1 = single-frame)
  1248. "confirmation_frames": 3,
  1249. "start_new_session": True, # fresh session on wake vs. continue the current one (detached-spawn: ok — a config key)
  1250. # sherpa only: listen for every wake-enabled profile's phrase and route to it
  1251. "profile_routing": True,
  1252. "openwakeword": {
  1253. # "hey_hermes" | built-in openWakeWord name ("hey_jarvis", "alexa", ...) | path to a
  1254. # custom .tflite model
  1255. "model": "hey_hermes",
  1256. },
  1257. "sherpa": {
  1258. # sherpa-onnx KWS model dir; empty = auto-download the small English zipformer
  1259. "model_dir": "",
  1260. },
  1261. "porcupine": {
  1262. # built-in keyword ("jarvis", "computer", ...) or path to a custom .ppn
  1263. "keyword": "jarvis",
  1264. },
  1265. },
  1266. "human_delay": {"mode": "off", "min_ms": 800, "max_ms": 2500},
  1267. # Context engine — how the context window is managed near the token limit. "compressor" =
  1268. # built-in lossy summarization; or a plugin name (e.g. "lcm") installed in
  1269. # plugins/context_engine/<name>/ or ~/.hermes/plugins/.
  1270. "context": {
  1271. "engine": "compressor",
  1272. # Return freed glibc pages at agent/TUI cleanup boundaries (no-op elsewhere).
  1273. "memory_trim": {
  1274. "enabled": True,
  1275. "cooldown_seconds": 60.0,
  1276. "log_every_n": 1, # INFO-log every Nth periodic trim; force paths always log.
  1277. # Suppress INFO logs when the readable RSS delta is smaller; 0 = log all.
  1278. "info_log_min_delta_mb": 0.0,
  1279. },
  1280. },
  1281. "memory": { # Persistent memory — bounded curated memory injected into the system prompt
  1282. "memory_enabled": True,
  1283. "user_profile_enabled": True,
  1284. "prefetch_spill_enabled": False, # External recall opt-in to hooks.output_spill.
  1285. # Approval gate for memory writes on BOTH foreground turns and the background review fork.
  1286. # true = foreground writes prompt inline; background writes are staged (/memory
  1287. # pending|approve <id>|reject <id>). To disable memory: memory_enabled.
  1288. "write_approval": False,
  1289. "memory_char_limit": 2200, # ~800 tokens at 2.75 chars/token
  1290. "user_char_limit": 1375, # ~500 tokens at 2.75 chars/token
  1291. # Periodic built-in memory review; 0 when an external provider auto-extracts.
  1292. "nudge_interval": 10,
  1293. # One external provider: bundled (retaindb, byterover) or catalog-installed (honcho,
  1294. # hindsight, supermemory, mem0, openviking, holographic). Empty = built-in only.
  1295. "provider": "",
  1296. },
  1297. # Subagent delegation: `backend` = task-routing strategy ("default": keys below), `backends.<name>` = its settings.
  1298. "delegation": {
  1299. "backend": "default",
  1300. "backends": {},
  1301. "model": "", # e.g. "google/gemini-3-flash-preview" (empty = inherit parent)
  1302. "provider": "", # e.g. "openrouter" (empty = inherit parent provider + credentials)
  1303. # Fallback chain for delegated children (same entry format as the top-level list).
  1304. # For an unpinned child, null = inherit the parent chain; [] = disable fallback.
  1305. # A child pinned by provider, endpoint, or model gets no fallback unless this
  1306. # setting declares one explicitly.
  1307. "fallback_providers": None,
  1308. "base_url": "", # direct OpenAI-compatible endpoint for subagents
  1309. "api_key": "", # key for delegation.base_url (falls back to OPENAI_API_KEY)
  1310. # Wire protocol for delegation.base_url: "chat_completions" | "codex_responses" |
  1311. # "anthropic_messages". Empty = auto-detect from URL (e.g. /anthropic suffix); set
  1312. # explicitly for non-standard endpoints.
  1313. "api_mode": "",
  1314. # Per-child request settings on every delegation call (all resolution branches). Top-level
  1315. # keys = API kwargs (e.g. service_tier); "extra_body" sub-dict merges into extra_body, e.g.
  1316. # {"extra_body": {"provider": {"sort": "throughput"}}}. Explicit values win OVER
  1317. # runtime/parent overrides (extra_body deep-merged 1 level).
  1318. "request_overrides": {},
  1319. # compression_threshold_tokens: optional absolute cap on a subagent's compaction TRIGGER
  1320. # (not the request payload), applied as the lower of this and the child's ratio threshold.
  1321. # 0 (default) = no subagent-specific cap; children compact where the parent does — the lower
  1322. # of 0.50 x window and the global compression.threshold_tokens cap. A replay of a 1,393-agent
  1323. # run showed 200K-400K caps within 5% of each other in cost once cache prefixes are intact,
  1324. # and every compaction is a chance to lose detail, so the default stays off. A token count >= 16000 enables it;
  1325. # other values (true, "200k") are config errors: warned and ignored.
  1326. "compression_threshold_tokens": 0,
  1327. # When delegate_task narrows child toolsets, keep the parent's enabled MCP toolsets (so
  1328. # toolsets=["web"] doesn't strip MCP). false = strict intersection.
  1329. "inherit_mcp_toolsets": True,
  1330. # Per-subagent iteration cap (own budget, independent of the parent's).
  1331. "max_iterations": 250,
  1332. # Hard per-summary char ceiling on subagent results, layered on the dynamic budget (each
  1333. # summary is sized to the parent's remaining context headroom; trimmed text spills to
  1334. # ~/.hermes/cache/delegation/ with a head+tail window + read_file offset footer, nothing
  1335. # lost). 0 disables the ceiling; the dynamic budget still applies.
  1336. "max_summary_chars": 24000,
  1337. # Inactivity cap per child (seconds, floor 30) — time with NO progress, not total runtime. 0 = no cap:
  1338. # children fail only from real errors (API, tools, iteration budget). A progressing child (including one
  1339. # waiting on a multi-minute completion) restarts the window; a frozen one is caught.
  1340. "child_timeout_seconds": 0,
  1341. # Subagent effort: "ultra" | "max" | "xhigh" | "high" | "medium" | "low" | "minimal" | "none" (empty = inherit)
  1342. "reasoning_effort": "",
  1343. # Max parallel children per batch AND concurrent background units (async beyond it runs sync). Floor 1.
  1344. "max_concurrent_children": 10,
  1345. "prefix_stagger_seconds": 0, # max s siblings wait for the 1st child's 1st chunk (not a stagger); 0 = off
  1346. # Background fan-outs return as ONE message when the whole call finishes. true = each task
  1347. # (or `group`) returns on its own as it finishes — more new turns for the orchestrator.
  1348. "independent_completions": False,
  1349. "gateway_mode": "auto", # gateway: inline (join in the turn) | background | auto = inline where interim msgs are off
  1350. # Orchestrator role controls. Depth floored at 1, no ceiling; each level multiplies cost.
  1351. "max_spawn_depth": 1, # 1 = flat, 2 = orchestrator→leaf, 3+ = deeper
  1352. "orchestrator_enabled": True, # kill switch for role="orchestrator"
  1353. # Total subagents a finite one-shot run (hermes chat -q / --oneshot) may spawn; 0 = unlimited.
  1354. # Each child re-pays a cold system prompt and re-explores the repo, and one-shot spawns are mostly
  1355. # "review my own work" rather than parallel work (agent/oneshot_footprint.py).
  1356. "oneshot_max_children": 2,
  1357. # Subagent threads ALWAYS resolve approvals non-interactively (the parent TUI owns stdin;
  1358. # input() from a worker would deadlock). false = auto-deny, true = auto-approve "once"; both
  1359. # log a warning audit line. true only for trusted batch work.
  1360. "subagent_auto_approve": False,
  1361. # Subagent background processes (task_id "sa-...") route notify_on_complete / watch_pattern
  1362. # notifications to the PARENT; false suppresses them (the child's result is the
  1363. # deliverable). Async-delegation results are NEVER suppressed.
  1364. "surface_child_process_notifications": False,
  1365. },
  1366. # Ephemeral prefill messages file — JSON list of {role, content} dicts injected at the start of
  1367. # every API call for few-shot priming. Never saved to sessions/logs/trajectories.
  1368. "prefill_messages_file": "",
  1369. # Goals — persistent cross-turn /goal loop: after each turn an aux-model judge checks if the
  1370. # goal is satisfied, else a continuation prompt re-enters the session until done, budget
  1371. # exhausted, or paused. Judge failures fail OPEN; the budget is the backstop.
  1372. "goals": {
  1373. # Max continuation turns before auto-pause (/goal resume) — guards against judge false
  1374. # negatives and unbounded spend.
  1375. "max_turns": 20,
  1376. },
  1377. # Loops — /loop re-runs a prompt or slash command on a cadence in-session. Fixed interval fires
  1378. # on the user's clock; self-paced (no interval) starts at the floor and backs off exponentially
  1379. # while replies stop changing.
  1380. "loops": {
  1381. "min_interval_seconds": 30, # smallest fixed interval; tighter cadences raised to it
  1382. "max_ticks": 100, # auto-pause after this many wakeups unless --times set; 0 = unlimited
  1383. "self_paced_floor_seconds": 60, # Self-paced cadence bounds (seconds).
  1384. "self_paced_ceiling_seconds": 900,
  1385. },
  1386. # Mixture of Agents — named presets used by /moa. A preset is an execution mode around the main
  1387. # model, not a model itself: references + aggregator synthesize private guidance before each
  1388. # main-model iteration.
  1389. "moa": {
  1390. "default_preset": "default",
  1391. "active_preset": "",
  1392. # Write each MoA turn (reference + aggregator exact input/output/usage) as JSONL to
  1393. # <hermes_home>/moa-traces/<session_id>.jsonl (or trace_dir) for auditing.
  1394. "save_traces": False,
  1395. "trace_dir": "",
  1396. # PII/credential redaction of advisor outputs: "" off | "display" (UI reference blocks +
  1397. # traces only; aggregator sees raw) | "full" (also the aggregator prompt).
  1398. # Advisors can echo PII from the conversation (emails, formatted phone numbers) and credential
  1399. # shapes into reference blocks, traces, and the aggregator prompt. Modes ('' = off, the default):
  1400. # "display" — redact user-visible surfaces only (reference blocks shown in the UI + saved MoA trace
  1401. # records); the aggregator still sees raw advisor text. "full" — additionally redact the advisor
  1402. # text injected into the aggregator prompt (issue #59959).
  1403. "privacy_filter": "",
  1404. "presets": {
  1405. "default": {
  1406. "reference_models": [
  1407. {"provider": "openai-codex", "model": "gpt-5.5"},
  1408. {"provider": "openrouter", "model": "deepseek/deepseek-v4-pro"},
  1409. ],
  1410. "aggregator": {"provider": "openrouter", "model": "anthropic/claude-opus-4.8"},
  1411. "enabled": True,
  1412. }
  1413. },
  1414. },
  1415. # Skills — external skill directories shared across tools/agents. Paths are expanded (~, ${VAR})
  1416. # and resolved; read-only — creation goes to ~/.hermes/skills/ unless create_dir redirects it.
  1417. "skills": {
  1418. "external_dirs": [], # e.g. ["~/.agents/skills", "/shared/team-skills"]
  1419. # Where skill_manage-created skills go (empty = profile-local dir). When set, new skills
  1420. # land here AND agent-facing instructions name this path; expanded (~, ${VAR}), relative to
  1421. # HERMES_HOME, scanned alongside the local dir.
  1422. "create_dir": "",
  1423. # In a git checkout, <root>/.hermes/skills/ and <root>/.agents/skills/ load as the
  1424. # highest-precedence tier — ONLY if the root is in trusted_project_dirs. false = no scan, no
  1425. # untrusted-skills notice.
  1426. "project_discovery": True,
  1427. # Trusted project roots; managed by `hermes skills trust` / `untrust`.
  1428. "trusted_project_dirs": [],
  1429. # Skill names pinned as fully loaded in every new session (CLI, TUI, gateway, cron, API).
  1430. # Resolved once when the agent's prompt is first built; missing/disabled names warn and
  1431. # skip; HERMES_IGNORE_RULES suppresses the list like the other auto-injected context.
  1432. "auto_load": [],
  1433. # Substitute ${HERMES_SKILL_DIR} / ${HERMES_SESSION_ID} in SKILL.md content.
  1434. "template_vars": True,
  1435. # Pre-execute !`cmd` snippets in SKILL.md, inlining stdout (dates, git state...). Off:
  1436. # host-unapproved skill-author code; community hub installs never auto-execute (#63307).
  1437. "inline_shell": False,
  1438. "inline_shell_timeout": 10, # seconds per !`cmd` snippet
  1439. # Security-scan skills the agent writes via skill_manage. Off: the agent can run the same
  1440. # code via terminal() ungated, so it mostly blocks prose with risky keywords. On: a
  1441. # dangerous verdict is a tool error the agent can retry. Hub installs are always scanned.
  1442. "guard_agent_created": False,
  1443. # Advisory NVIDIA SkillEvaluator Tier 1 scan on `hermes skills install` (alongside the
  1444. # enforcing built-in guard), only if `skillevaluator` is on PATH (uv tool install
  1445. # "skillevaluator @ git+https://github.com/NVIDIA/SkillEvaluator.git"). Informational, never
  1446. # blocking; secrets-class findings shown red. No-op without it.
  1447. "tier1_advisory": True,
  1448. # Approval gate for skill_manage mutations on BOTH foreground turns and the background
  1449. # review fork. true = ALWAYS stage (SKILL.md too large for an inline prompt): /skills
  1450. # pending, /skills diff <id>, /skills approve|reject <id>.
  1451. "write_approval": False,
  1452. # Audit ledger: every skill mutation appends to ~/.hermes/skills/.curator_ledger.jsonl with
  1453. # before/after hashes (blobs under ~/.hermes/.curator_backups/blobs/); powers `hermes
  1454. # curator ledger` / `rollback <entry-id>`. Never a gate — failures can't block.
  1455. # See #79686.
  1456. "ledger": True,
  1457. # Size cap for that ledger: once the file grows past this, the next append rewrites it
  1458. # through the unchanged-file dedup and, if still over, drops the oldest entries (0 = keep
  1459. # the ledger append-only forever, the previous behaviour).
  1460. "ledger_max_bytes": 5 * 1024 * 1024,
  1461. },
  1462. # Curator — background maintenance of AGENT-CREATED skills (never hub-installed): marks
  1463. # long-unused skills stale, archives (never deletes) obsolete ones, optionally consolidates
  1464. # overlaps via a forked aux-model agent. Inactivity-triggered from session start, no cron
  1465. # daemon. `hermes curator status` shows the last run.
  1466. "curator": {
  1467. "enabled": True,
  1468. "interval_hours": 24 * 7, # hours between runs
  1469. "min_idle_hours": 2, # only run after the agent has been idle this long
  1470. "stale_after_days": 14, # mark "stale" after this many unused days
  1471. "archive_after_days": 30, # move to skills/.archive/ (recoverable) after this many
  1472. # LLM consolidation (umbrella-building) pass. OFF = deterministic inactivity prune only, no
  1473. # aux-model cost. `hermes curator run --consolidate` overrides once.
  1474. "consolidate": False,
  1475. # Also prune bundled built-ins (a suppression list stops `hermes update` restoring them);
  1476. # hub-installed skills are NEVER pruned. OFF by default: shipped skills vanishing from
  1477. # `skills_list` because nobody loaded them for 30 days surprised people (57 gone in one
  1478. # startup tick). true = built-ins age out like agent-created skills.
  1479. "prune_builtins": False,
  1480. # TTL purge of skills/.archive/: 0 = never; > 0 lets the explicit `hermes curator purge`
  1481. # delete older archived skills (never automatic; logged in the ledger).
  1482. "archive_ttl_days": 0,
  1483. # Before a consolidation pass (the only one that rewrites skill content in place), snapshot
  1484. # ~/.hermes/skills/ to ~/.hermes/skills/.curator_backups/<utc-iso>/skills.tar.gz (`hermes curator
  1485. # rollback`). The prune-only pass just moves directories into .archive/ and takes none.
  1486. "backup": {
  1487. "enabled": True,
  1488. "keep": 2, # retain last N regular snapshots
  1489. },
  1490. },
  1491. # Honcho memory plugin (plugin catalog) — ~/.honcho/config.json is the source of truth (apiKey,
  1492. # workspace, peerName, sessions, enabled); the plugin reads hermes-specific overrides from here.
  1493. "honcho": {},
  1494. # IANA timezone (e.g. "Asia/Kolkata", "America/New_York"). Empty = server-local time.
  1495. "timezone": "",
  1496. "slack": {
  1497. "require_mention": True, # require @mention to respond in channels
  1498. "free_response_channels": "", # comma-separated channel IDs answered without mention
  1499. "allowed_channels": "", # if set, ONLY respond in these channel IDs (whitelist)
  1500. "require_mention_channels": "", # channel IDs where @mention is ALWAYS required
  1501. # Ignore messages whose first token @mentions another user unless the bot is also mentioned.
  1502. # Env: SLACK_IGNORE_OTHER_USER_MENTIONS.
  1503. "ignore_other_user_mentions": False,
  1504. "thread_require_mention": False, # require @mention in thread replies too
  1505. "channel_prompts": {}, # per-channel ephemeral system prompts
  1506. },
  1507. "discord": {
  1508. "require_mention": True, # require @mention to respond in server channels
  1509. "free_response_channels": "", # comma-separated channel IDs answered without mention
  1510. "allowed_channels": "", # if set, ONLY respond in these channel IDs (whitelist)
  1511. "auto_thread": True, # auto-create threads on @mention in channels (like Slack)
  1512. # Free-response channels reply inline by default; true also gives each top-level
  1513. # message in them its own thread (still mention-free). Env: DISCORD_FREE_RESPONSE_AUTO_THREAD.
  1514. "free_response_auto_thread": False,
  1515. "thread_require_mention": False, # require @mention in threads too (multi-bot threads)
  1516. # Bot authors must type @thisbot to trigger a reply; Discord reply pings alone do not count.
  1517. # Set False only for trusted legacy relays. Humans are unaffected.
  1518. "bots_require_inline_mention": True,
  1519. # Prepend recent channel scrollback when triggered (recovers messages gated out by
  1520. # require_mention); limit = max messages scanned.
  1521. "history_backfill": True,
  1522. "history_backfill_limit": 50,
  1523. # Replay messages missed while offline, after reconnect/startup.
  1524. "missed_message_backfill": {
  1525. "enabled": False,
  1526. "channels": "", # comma-separated channel IDs; empty uses free_response_channels
  1527. "window_seconds": 21600, # only inspect messages from the last 6 hours
  1528. "limit": 100, # global cap on messages scanned per reconnect
  1529. "max_dispatches": 10, # cap on recovered messages dispatched per reconnect
  1530. "max_attempts": 3, # lifetime re-dispatch cap for one message, whatever its outcome
  1531. },
  1532. "reactions": True, # add 👀/✅/❌ reactions to messages during processing
  1533. # Gateway transport health probe: inspects the WebSocket's ready/open/heartbeat state (never
  1534. # REST) as proof events still arrive. Any value 0 disables it.
  1535. "websocket_liveness_interval_seconds": 15,
  1536. "websocket_liveness_failure_threshold": 2,
  1537. "websocket_heartbeat_ack_max_age_seconds": 60,
  1538. "websocket_max_latency_seconds": 30,
  1539. # Dispatch-side dimension: a socket that ACKs heartbeats but delivers no events for this
  1540. # long is treated as deaf. 4 h absorbs a quiet server overnight; 0 disables it.
  1541. "websocket_event_max_silence_seconds": 14400,
  1542. # per-channel ephemeral system prompts (forum parents apply to child threads)
  1543. "channel_prompts": {},
  1544. # Opt-in DM role auth: DISCORD_ALLOWED_ROLES normally authorizes guild messages only (DMs
  1545. # need DISCORD_ALLOWED_USERS). A guild ID here also authorizes DMs from that guild's members
  1546. # holding the allowed role. Unset / "" / 0 = off.
  1547. # See #12136.
  1548. "dm_role_auth_guild": "",
  1549. # discord / discord_admin tools: allowed actions (comma string or YAML list; empty = all,
  1550. # subject to bot intents; unknown names dropped with a warning): list_guilds, server_info,
  1551. # list_channels, channel_info, list_roles, member_info, search_members, fetch_messages,
  1552. # list_pins, pin_message, unpin_message, create_thread, add_role, remove_role.
  1553. "server_actions": "",
  1554. # DEPRECATED no-op (uploads are always cached; messaging auth is the gate). Kept so existing
  1555. # configs don't error. Env: DISCORD_ALLOW_ANY_ATTACHMENT.
  1556. "allow_any_attachment": False,
  1557. # Max bytes per cached attachment (held in memory while written); 0 = no cap. Env:
  1558. # DISCORD_MAX_ATTACHMENT_BYTES.
  1559. "max_attachment_bytes": 33554432,
  1560. # Mention allowed users on approval prompts so owners notice them in shared channels. Env:
  1561. # DISCORD_APPROVAL_MENTIONS.
  1562. "approval_mentions": False,
  1563. # Voice-channel inactivity timeout (seconds); 0 = stay until `/voice leave`.
  1564. "voice_channel_inactivity_timeout_seconds": 300,
  1565. # Minimum seconds before force-stopping a VC playback; the adapter probes clip duration and
  1566. # extends this floor so long TTS isn't cut off.
  1567. "voice_playback_timeout_seconds": 120,
  1568. # Voice-channel software mixer (plugins/platforms/discord/voice_mixer.py): ambient
  1569. # "thinking" bed, verbal acks and TTS OVERLAP (ambient ducked) vs stop-and-swap.
  1570. "voice_fx": {
  1571. "enabled": False, # master switch for the mixer subsystem
  1572. "ambient_enabled": True, # play the idle "thinking" bed while tools run
  1573. "ambient_path": "", # custom loop audio file; "" = synthesised pad
  1574. "ambient_gain": 0.18, # idle bed loudness, 0.0–1.0
  1575. "duck_gain": 0.06, # ambient loudness while speech plays
  1576. "speech_gain": 1.0, # TTS / ack loudness, 0.0–1.0
  1577. "ack_enabled": True, # speak a short phrase before the first tool call
  1578. "ack_phrases": [ # picked at random; [] disables phrases
  1579. "Let me look into that.",
  1580. "One moment.",
  1581. "Checking on that now.",
  1582. "Give me a sec.",
  1583. "On it.",
  1584. ],
  1585. },
  1586. },
  1587. "whatsapp": {
  1588. # reply_prefix: None = built-in "☤ *Hermes Agent*" header; "" disables; \n allowed.
  1589. },
  1590. "telegram": {
  1591. "reactions": False, # add 👀/✅/❌ reactions to messages during processing
  1592. # per-chat/topic ephemeral system prompts (topics inherit from parent group)
  1593. "channel_prompts": {},
  1594. "allowed_chats": "", # if set, ONLY respond in these group/supergroup chat IDs
  1595. "extra": {
  1596. # Bot API 10.1 native rich messages (tables/task lists/math). Off = legacy MarkdownV2,
  1597. # since rich messages are hard to copy as plain text.
  1598. "rich_messages": False,
  1599. # Experimental rich DM stream previews; off: Telegram Desktop/macOS overlays draft frames.
  1600. "rich_drafts": False,
  1601. # CJK stays on legacy MarkdownV2 (Telegram Desktop/macOS garbles rich CJK, #47653);
  1602. # set True on an unaffected client to get native rich tables for CJK.
  1603. "allow_cjk_rich_messages": False,
  1604. "dm_topic_auto_transfer": False, # /topic mode: root-DM message opens a fresh topic
  1605. },
  1606. },
  1607. "mattermost": {
  1608. "require_mention": True, # require @mention to respond in channels
  1609. "free_response_channels": "", # comma-separated channel IDs answered without mention
  1610. "allowed_channels": "", # if set, ONLY respond in these channel IDs (whitelist)
  1611. "channel_prompts": {}, # per-channel ephemeral system prompts
  1612. },
  1613. "matrix": {
  1614. "require_mention": True, # require @mention to respond in rooms
  1615. "free_response_rooms": "", # comma-separated room IDs answered without mention
  1616. "allowed_rooms": "", # if set, ONLY respond in these room IDs (whitelist)
  1617. },
  1618. # Approvals for dangerous commands.
  1619. # mode: manual (always prompt) | smart (aux LLM auto-approves low-risk) | off (= --yolo)
  1620. # cron_mode / single_query_mode / unattended_mode: deny | approve — what to do when a
  1621. # cron job, a -q session (HERMES_INTERACTIVE=1 but nobody to answer), or an unattended
  1622. # platform (webhook, msgraph_webhook, api_server; no /approve channel) hits one.
  1623. # deny blocks instantly so the agent finds another way instead of waiting out the
  1624. # timeout and failing closed.
  1625. # timeout: seconds before an unanswered prompt fails closed (CLI and gateway). 60s
  1626. # proved too tight for Telegram/Discord push notifications, hence 300.
  1627. "approvals": {
  1628. # single_query_mode — what to do when a single-query (-q) session hits a dangerous command. -q runs
  1629. # export HERMES_INTERACTIVE=1 (for interactive sudo prompts) but have NO user waiting to answer
  1630. # approval prompts — an unanswered prompt just waits the full timeout then fails closed, so the
  1631. # agent is forced to work around the block (often via execute_code). This setting makes that intent
  1632. # explicit: deny — block the command and let the agent find another way (default, safe; mirrors
  1633. # cron_mode deny) approve — auto-approve all dangerous commands in single-query mode These surfaces
  1634. # bind a session platform like chat gateways do, but have no send_exec_approval and no /approve
  1635. # channel — a pending approval there just blocks for the full timeout with nobody to answer (#37284,
  1636. # #87509): deny — block the command instantly and let the agent find another way (default, safe;
  1637. # mirrors cron_mode deny) approve — auto-approve all dangerous commands on unattended platforms
  1638. "mode": "smart",
  1639. "timeout": 300,
  1640. "discord_prompt_timeout": 300, # Discord buttons stay clickable (min 30 s, cap MAX_SAFE_TIMEOUT_S)
  1641. "cron_mode": "deny",
  1642. "single_query_mode": "deny",
  1643. "unattended_mode": "deny",
  1644. # Extra rules appended to the smart-approval guardian's SYSTEM prompt, e.g. "Always ESCALATE
  1645. # commands touching /etc".
  1646. "smart_policy": "",
  1647. # After this many consecutive guardian DENYs in a session, the deny message escalates to a
  1648. # hard-stop (report to user / ask for /approve). Approval resets; 0 off.
  1649. "denial_breaker_threshold": 3,
  1650. # Case-insensitive fnmatch globs against terminal commands; a match blocks even under --yolo
  1651. # / mode=off. Quote in YAML when starting with * or containing {}/!/: e.g. "git push
  1652. # --force*".
  1653. "deny": [],
  1654. # /reload-mcp confirms before rebuilding the MCP tool set (it invalidates the prompt cache,
  1655. # so the next message re-sends full input). "Always Approve" → false.
  1656. "mcp_reload_confirm": True,
  1657. # /clear, /new, /reset, /undo confirm before discarding state (Approve Once / Always Approve
  1658. # / Cancel via tools.slash_confirm; native buttons on Telegram/ Discord/Slack). "Always
  1659. # Approve" → false. HERMES_TUI_NO_CONFIRM=1 skips the TUI modal.
  1660. "destructive_slash_confirm": True,
  1661. },
  1662. # Permanently allowed dangerous command patterns (added via "always" approval).
  1663. "command_allowlist": [],
  1664. # User-defined quick commands that bypass the agent loop (type: exec only).
  1665. "quick_commands": {},
  1666. # Per-platform system-prompt hint overrides, keyed by platform name (whatsapp, slack, telegram,
  1667. # ...). Value: {"append": text} keeps the built-in hint and appends; {"replace": text}
  1668. # substitutes it; a bare string is shorthand for append. `replace` wins over `append` if both
  1669. # are given.
  1670. "platform_hints": {},
  1671. # Plugin system. `enabled`/`disabled` (`hermes plugins enable|disable`) and `disabled_by_update` (pm.plugin_eviction:
  1672. # plugins an update turned off, retried by later updates) are omitted so an empty default never clobbers a user's lists.
  1673. "plugins": {
  1674. # Deadline (seconds) for one plugin Git clone, fetch or checkout. Slow repositories may
  1675. # need more time; each network operation is capped at one hour.
  1676. "clone_timeout_seconds": 300,
  1677. # Wall-clock cap (seconds) for one in-process Python plugin hook callback; shell hooks keep
  1678. # their own per-entry `timeout`. 0 = no cap (sync call on agent thread). Max 600.
  1679. "hook_callback_timeout": 30,
  1680. # Deadline (seconds) for one plugin's import + register() at load. A plugin that overruns it is
  1681. # skipped with the reason "load timed out" and the rest keep loading; the stuck worker thread is
  1682. # abandoned. 0 = no deadline (load inline). Max 600.
  1683. "load_timeout_seconds": 10,
  1684. # Read-only plugin update-check cadence, hours (gateway tick; 0 disables). Applying stays
  1685. # explicit: `hermes plugins update <name>`, or auto_apply below (catalog and tracked git
  1686. # plugins, scan-gated by that same pipeline).
  1687. "auto_update_check_hours": 24,
  1688. # Opt-in unattended apply (`hermes plugins auto-update on`, Desktop's Plugins tab): catalog +
  1689. # tracked git plugins, same scan/consent pipeline as the manual update (never a widened pin).
  1690. "auto_apply": False,
  1691. # Where third-party Python plugins run. in_process: imported into Hermes (default).
  1692. # host: one plugin-host process per profile runs them and they reach Hermes only through
  1693. # ctx (a crashing or hanging plugin takes down its host, which restarts; Hermes keeps
  1694. # running). Bundled plugins stay in-process; `hermes plugins validate` says whether a
  1695. # plugin can run in the host.
  1696. "isolation": "in_process",
  1697. "host": {
  1698. # argv prefix the plugin host runs under, e.g. a sandbox runner. [] = plain subprocess.
  1699. "launcher": [],
  1700. },
  1701. },
  1702. # Shell-script hooks: event name (pre_tool_call, post_tool_call, pre_llm_call, subagent_stop,
  1703. # ...) -> list of {matcher, command, timeout}. First run of a new command prompts for consent;
  1704. # approvals persist in ~/.hermes/shell-hooks-allowlist.json. Schema + examples:
  1705. # website/docs/user-guide/features/hooks.md.
  1706. "hooks": {},
  1707. # Auto-accept shell-hook registrations without a TTY prompt (also --accept-hooks or
  1708. # HERMES_ACCEPT_HOOKS=1). Gateway/cron/non-interactive runs need one of these to pick up
  1709. # newly-added hooks.
  1710. "hooks_auto_accept": False,
  1711. # Custom personalities: {"name": "system prompt"} or {"name": {"description", "system_prompt",
  1712. # "tone", "style"}}.
  1713. "personalities": {},
  1714. "auth": { # Login policy (credentials themselves live in auth.json / .env).
  1715. # Borrow and refresh the Codex CLI (~/.codex/auth.json) and Claude Code (~/.claude/.credentials.json)
  1716. # logins automatically when Hermes has no usable login of its own. Their refresh tokens are single-use
  1717. # and rotate, so two programs on one login can log each other out; set false to make Hermes use only
  1718. # its own logins (`hermes auth add <provider>`). `hermes auth add openai-codex` still offers the import
  1719. # interactively.
  1720. "adopt_external_logins": True,
  1721. # How `hermes auth add openai-codex` / `hermes model` sign in to OpenAI Codex.
  1722. # "device_code" (default): open a URL, enter a code. "browser": authorization-code + PKCE on
  1723. # the loopback listener http://localhost:1455/auth/callback (the redirect OpenAI registered
  1724. # for the Codex client) — for organizations that disable the device-code grant. Falls back
  1725. # to device code when that port is busy. `hermes auth add openai-codex --browser` opts in
  1726. # for one login without changing this key.
  1727. "codex_login_flow": "device_code",
  1728. },
  1729. "security": { # Security: URL/private-network guards, redaction and approval presentation.
  1730. "allow_private_urls": False, # private IPs for web/vision/media + cloud/CDP browsers; not local/sidecar Chromium
  1731. # CIDR blocks a local TUN proxy answers DNS with (Mihomo/Clash fake-ip, Surge enhanced).
  1732. # Answers inside these blocks are the proxy's sentinels, not internal hosts, so the guard
  1733. # dials them instead of rejecting them as private. Empty = normal private-address verdict.
  1734. "fake_ip_ranges": [],
  1735. "redact_secrets": True,
  1736. # Persisted acknowledgement for unattended model overrides whose tier lets the vendor train
  1737. # on prompts. The startup guard still warns every run; cost guards are unaffected.
  1738. "allow_data_training_tiers_noninteractive": False,
  1739. # Human-approval presentation transport. "builtin" = CLI/TUI/gateway/ACP surfaces; a plugin
  1740. # transport is used only when named explicitly. Transport timeout/error/invalid response
  1741. # DENIES unless transport_fallback is "builtin". Presentation only: plugins cannot detect,
  1742. # suppress, or auto-approve commands outside a correlated human response.
  1743. "approval": {"transport": "builtin", "transport_fallback": "deny"},
  1744. # Writes to agent-instruction files (AGENTS.md/CLAUDE.md/SOUL.md/.cursorrules, project-local
  1745. # .hermes config) always need human approval, even under yolo. Extra patterns are fnmatch
  1746. # globs on the basename (e.g. "*.mdc").
  1747. "protected_instruction_files": True,
  1748. "protected_instruction_extra_patterns": [],
  1749. "website_blocklist": {"enabled": False, "domains": [], "shared_files": []},
  1750. # IDs of supply-chain advisories the user has read and acted on; acked ones stop the startup
  1751. # banner. Add via `hermes doctor --ack <id>`; remove by editing the list. Catalog:
  1752. # hermes_cli/security_advisories.py.
  1753. "acked_advisories": [],
  1754. # Lazy-install opt-in backend packages from PyPI when a backend that needs them is first
  1755. # enabled (e.g. `elevenlabs`). False = require explicit pip install for everything beyond
  1756. # the base set (restricted/audited/air-gapped environments).
  1757. "allow_lazy_installs": True,
  1758. },
  1759. "cron": {
  1760. "catch_up_missed": True, # False skips recurring misses beyond the local grace window.
  1761. # Let cron-spawned agents use the cronjob toolset (the "cron-librarian" pattern). Off by
  1762. # default: policy-denied in cron context to prevent unattended scheduling loops. Jobs
  1763. # created this way are user-owned in the same flat jobs table. Interactive toolsets
  1764. # (messaging/clarify) stay denied in cron regardless.
  1765. "allow_agent_scheduling": False,
  1766. # Pre-dispatch validation: before building any agent machinery, verify the provider API key
  1767. # resolves (unless a fallback chain exists), attached skills are ready, and delivery
  1768. # platforms are configured. Failure -> last_status=blocked_config, ONE alert, no LLM call.
  1769. # False = fail during the run instead.
  1770. "preflight": True,
  1771. # Default model for cron jobs (WHAT model runs). Fire-time resolution: per-job pin >
  1772. # cron.model > model.default (the main agent model). An unpinned job follows the main
  1773. # model on every run; cron.model decouples the whole fleet from chat. "" = fall through.
  1774. "model": "",
  1775. # Inference provider paired with cron.model (NOT the scheduler provider below). "" = resolve
  1776. # from global config.
  1777. "model_provider": "",
  1778. # Cron SCHEDULER provider (WHEN a due job fires). "" = built-in in-process 60s ticker. Name
  1779. # an installed provider (plugins/cron_providers/<name>/ or $HERMES_HOME/plugins/ <name>/),
  1780. # e.g. "chronos" (NAS-mediated managed cron for scale-to-zero). An unknown or unavailable
  1781. # provider falls back to the built-in so cron never loses its trigger.
  1782. "provider": "",
  1783. # Chronos settings; consulted only when provider == "chronos". All non-secret — the agent
  1784. # holds NO scheduler credentials (provision reuses the Nous Portal token).
  1785. "chronos": {
  1786. # NAS/portal base URL that arms/cancels one-shots and mints the inbound fire JWT (used
  1787. # as the expected issuer).
  1788. "portal_url": "https://portal.nousresearch.com",
  1789. # This agent's publicly reachable base URL; NAS POSTs {callback_url}/api/cron/fire. ""
  1790. # -> Chronos unavailable, resolver falls back to the built-in ticker.
  1791. "callback_url": "",
  1792. "expected_audience": "", # Expected JWT audience (e.g. "agent:{instance_id}").
  1793. # NAS JWKS URL for verifying the fire JWT signature. "" -> the fire endpoint refuses all
  1794. # tokens (never an unsigned decode).
  1795. "nas_jwks_url": "",
  1796. },
  1797. # Wrap delivered cron responses with a task-name header and "The agent cannot see this
  1798. # message" footer. False = clean output.
  1799. "wrap_response": True,
  1800. "delivery": { # Delivery behaviour for cron output sent through a live gateway adapter.
  1801. # Mark cron deliveries FINAL so the platform pushes them (Telegram's "important" mode
  1802. # otherwise sends with disable_notification=True and briefs look undelivered). False =
  1803. # silent, no-push deliveries.
  1804. "notify": True,
  1805. },
  1806. # Make cron deliveries CONTINUABLE (user can reply to a brief with it in context). False
  1807. # keeps deliveries isolated to the job's session; per-job `attach_to_session` overrides.
  1808. # Thread-capable platforms (Telegram topics, Discord/Slack threads) get a seeded thread per
  1809. # job via create_handoff_thread; DM-only platforms mirror the brief into the target DM
  1810. # session. Appended at a turn boundary via mirror_to_session, cached system prompt
  1811. # untouched. User-written bare platforms address home conversations, unlike `all`
  1812. # broadcast expansions, which do not gain mirror eligibility.
  1813. "mirror_delivery": False,
  1814. # Max due jobs run in parallel per tick. None/0 = unbounded (thread count only); 1 = serial.
  1815. # Env override: HERMES_CRON_MAX_PARALLEL.
  1816. "max_parallel_jobs": None,
  1817. # save_job_output keeps the N most recent .md files per job; 0 or negative disables pruning
  1818. # (for externally managed cleanup).
  1819. "output_retention": 50,
  1820. # Timeout (seconds) for a no-agent cron script. Env: HERMES_CRON_SCRIPT_TIMEOUT. Keep in
  1821. # sync with cron.scheduler._DEFAULT_SCRIPT_TIMEOUT.
  1822. "script_timeout_seconds": 3600,
  1823. # Timeout (seconds) for SessionDB() init inside cron jobs: state.db open/migrate has no
  1824. # timeout of its own against a wedged sqlite3.connect, and an unbounded hang wedges the
  1825. # job's dispatch guard forever. Env: HERMES_CRON_SESSION_DB_TIMEOUT. 0 = unlimited.
  1826. "session_db_timeout_seconds": 10,
  1827. # Timeout (seconds) per media attachment send during gateway delivery; large attachments
  1828. # (long TTS audio, big exports) need more than 30s. Env: HERMES_CRON_MEDIA_SEND_TIMEOUT.
  1829. # Keep in sync with cron.scheduler._DEFAULT_MEDIA_SEND_TIMEOUT.
  1830. "media_send_timeout_seconds": 300,
  1831. # Managed systemd gateway with no user session (containers, no linger): false runs
  1832. # cron jobs as a direct external subprocess (warns once; no cgroup isolation), true
  1833. # fails closed with the enable-linger remedy. Kanban always requires a scope.
  1834. "require_restart_safe_scope": False,
  1835. # A job failing with the SAME error alerts once, then stays silent for this many hours
  1836. # before one reminder ping (the run is still recorded; `hermes cron incidents` shows it).
  1837. # A green run or a different error alerts again immediately; `hermes cron incidents ack`
  1838. # silences a signature for good. 0 = re-alert on every failing run. Keep in sync with
  1839. # cron.scheduler.DEFAULT_FAILURE_REPEAT_ALERT_HOURS.
  1840. "failure_repeat_alert_hours": 6,
  1841. },
  1842. # Kanban multi-agent coordination. The dispatcher ticks every N seconds, reclaims stale claims,
  1843. # promotes dependency-satisfied todos to ready, and fires `hermes -p <assignee> chat -q ...` per
  1844. # claimable task. Run ONE dispatcher per profile; two on the same kanban.db race for claims.
  1845. "kanban": {
  1846. # Auto-subscribe the originating gateway/TUI session to completion + block events when
  1847. # kanban_create is called from a session with a persistent delivery channel. Disable for
  1848. # profiles that prefer explicit kanban_notify-subscribe calls per task.
  1849. "auto_subscribe_on_create": True,
  1850. # Poll and deliver Kanban subscriptions from this gateway. Disable on profiles that do
  1851. # not own notification subscriptions to avoid an idle five-second board probe.
  1852. "notify_in_gateway": True,
  1853. # Run the dispatcher inside the gateway process (~300µs per idle tick). False only if you
  1854. # run it as a separate unit or don't want the gateway spawning workers.
  1855. "dispatch_in_gateway": True,
  1856. # Auto-claim tasks in the review column and spawn the assigned profile with the bundled
  1857. # sdlc-review skill. Disable where every review is done manually from the dashboard.
  1858. "review_dispatch": True,
  1859. # Seconds between dispatcher ticks. Lower = snappier pickup; higher = less SQL pressure.
  1860. "dispatch_interval_seconds": 60,
  1861. # Auto-block after this many consecutive non-success attempts (spawn_failed, timed_out,
  1862. # crashed) for the same task/profile. Reassignment resets the streak.
  1863. "failure_limit": 2,
  1864. # Worker stdout/stderr log rotation at spawn time (2 MiB + one backup). Raise to keep more
  1865. # early failure evidence from long-running workers.
  1866. "worker_log_rotate_bytes": 2 * 1024 * 1024,
  1867. "worker_log_backup_count": 1,
  1868. # Profile for the root/orchestration task after Triage decomposition; "" = default profile.
  1869. # Does not control the decomposer LLM path (see auxiliary.kanban_decomposer).
  1870. "orchestrator_profile": "",
  1871. # Assignee when the orchestrator can't match one to an installed profile; "" = default
  1872. # profile. A task never ends up with assignee=None.
  1873. "default_assignee": "",
  1874. # Global cap: positive int = the HOST never has more than N tasks 'running' across all
  1875. # boards and both dispatch lanes. None = ~MemTotal / 512 MiB clamped to [2, 8]; where
  1876. # MemTotal is unreadable (macOS/Windows) None means no cap.
  1877. # Global concurrency cap (#33488): when set to a positive int, the HOST never has more than N tasks
  1878. # in 'running' at once — counted across every active board and across both the ready and review
  1879. # dispatch lanes (workers are OS processes sharing one machine's memory, so the cap bounds the
  1880. # machine, not each board; OOF-30). Unset (None) means "derive from system memory" (OOF-30/OOF-77):
  1881. # the dispatcher caps concurrency at roughly MemTotal / 512 MiB, clamped to [2, 8] — e.g. 2 workers
  1882. # on a 1 GiB VM. On hosts where total memory can't be read (macOS/Windows), unset falls back to no
  1883. # cap. Set an explicit value to override the derived default in either direction.
  1884. "max_in_progress": None,
  1885. # Per-profile cap: positive int = no single profile runs more than N workers even if the
  1886. # global caps allow; blocked tasks defer to the next tick. None = no per-profile cap. Useful
  1887. # when fan-out would saturate one profile's model/API quota/browser pool.
  1888. # Unset (None) means "no per-profile cap" — backward-compatible with existing installs. Useful for
  1889. # fan-out workflows that would otherwise saturate one profile's local model / API quota / browser
  1890. # pool while leaving other profiles idle. See #21582.
  1891. "max_in_progress_per_profile": None,
  1892. # Per-home claim allowlist for boards shared across Hermes homes (#110995): profile names
  1893. # this home's dispatcher may claim (list or comma-separated string). None = any existing
  1894. # profile is claimable. Set = fail-closed (an empty list claims nothing). Every home has a
  1895. # root profile named "default", so on a shared kanban.db every home can otherwise claim
  1896. # default-assigned cards.
  1897. "dispatch_profiles": None,
  1898. # Auto-run the decomposer on Triage tasks every tick. False = manual via `hermes kanban
  1899. # decompose <id>` or the dashboard's Decompose button.
  1900. "auto_decompose": True,
  1901. # Max triage tasks decomposed per tick, bounding the aux-LLM burst from a bulk load. Excess
  1902. # defers to the next tick.
  1903. "auto_decompose_per_tick": 3,
  1904. # Running tasks with no heartbeat (last_heartbeat_at) for this many seconds are reclaimed to
  1905. # ready on the next tick; a still-running local worker is terminated first. 0 = off.
  1906. "dispatch_stale_timeout_seconds": 14400,
  1907. # Each tick, requeue 'running' cards with broken claim bookkeeping (claim_lock or
  1908. # claim_expires NULL with a dead worker) that TTL/crash/stale recovery can't see. False
  1909. # keeps orphans frozen for manual forensics.
  1910. "reconcile_orphans": True,
  1911. # Notify subscriptions survive `done` (completion is reversible) and are removed on archive.
  1912. # On boards that never archive, the notifier GC purges subscriptions for tasks done with no
  1913. # activity for this many days so stale rows aren't scanned forever. 0 = off.
  1914. "done_sub_retention_days": 30,
  1915. },
  1916. # Bot Mode cross-connection relay (tools/bot_relay.py): envelopes queued by message_agent for
  1917. # agents on other connections wait in an on-disk outbox until the Desktop drains them.
  1918. "bot_mode": {
  1919. # Drain-time TTL (seconds): older envelopes are NOT delivered on drain; the sender gets an
  1920. # error reply (reason 'queued_expired') so a DM can't land hours late as a zombie. 0 = no
  1921. # drain-time expiry (the 6h stale-artifact sweep still applies).
  1922. "envelope_ttl_seconds": 900,
  1923. # How long a second delivery into a busy target profile queues behind the current turn
  1924. # before failing with a structured 'target_busy' error. Deliveries are serialized per
  1925. # profile with a cross-process file lock.
  1926. "turn_wait_seconds": 120,
  1927. },
  1928. "code_execution": { # execute_code settings (programmatic tool calls).
  1929. # project = run in the session cwd with the active venv/conda python so project deps and
  1930. # relative paths resolve. strict = isolated temp dir with hermes-agent's own python
  1931. # (sys.executable): max isolation, project deps/relative paths won't work. Env scrubbing
  1932. # (*_API_KEY, *_TOKEN, *_SECRET, ...) and the tool whitelist apply in both modes.
  1933. "mode": "project",
  1934. # Session kernels are always on locally (`kernel_mode` is ignored) and remotely
  1935. # (tools/code_kernel_remote.py; a backend that cannot spawn a kernel fails open to
  1936. # per-call). One kernel per (session owner, mode, interpreter, cwd, tool-set) keeps state
  1937. # across calls and turns; subagents get their own. Kernels die with the session, after
  1938. # kernel_idle_timeout idle seconds, or by LRU eviction past max_session_kernels. A
  1939. # timed-out/interrupted cell kills the kernel; env is frozen at spawn (reset=true after
  1940. # changing passthrough). Tool RPC authority (approval, session, allow-list, call budget) is
  1941. # rebound per cell — that runtime boundary is the cross-cell enforcement.
  1942. "kernel_idle_timeout": 1800,
  1943. "max_session_kernels": 4,
  1944. },
  1945. # Tool Search replaces deferred tools in the model-facing array with the
  1946. # tool_search / tool_describe / tool_call bridges and surfaces them on demand.
  1947. # Working-set core tools stay eager, while the explicit ``defer`` list below
  1948. # may include cold, event-triggered built-ins as well as plugin/MCP tools.
  1949. "tools": {
  1950. "tool_search": {
  1951. # Tiered: tier 0 (no deferred tools) = everything eager; tier 1 = bridge + a
  1952. # name+description manifest when it fits the budget (degrades to names-only); tier 2
  1953. # (over budget even names-only, e.g. ~3,300-tool APIs) = bare bridge + a
  1954. # one-line-per-server summary (name + tool count). "auto"|"on" = activate when at least
  1955. # one deferred tool exists ("auto" is an alias of "on" today, reserved for a future
  1956. # budget-gated mode; keep it the default so explicit "on"/"off" pins are unaffected).
  1957. # "off" = pass-through, no bridge.
  1958. "enabled": "auto",
  1959. # Listing budget as % of the model's context length; effective budget = min(this % of
  1960. # context, listing_max_tokens). Range 0..100.
  1961. "threshold_pct": 5,
  1962. # Hits per query when the model omits `limit`. Range 1..max_search_limit.
  1963. "search_default_limit": 5,
  1964. # Hard upper bound the model may request via `limit` (per query). Range 1..50.
  1965. "max_search_limit": 25,
  1966. # Catalog listing embedded in the bridge description (name + first sentence ≤60 chars,
  1967. # grouped by server/toolset). "auto" = include when it fits (falls back to names-only,
  1968. # then bare tier-2 bridge); "on" = same rendering, explicit intent; "off" = always the
  1969. # bare bridge.
  1970. "listing": "auto",
  1971. # Absolute cap on the embedded listing in tokens (chars/4), regardless of context size.
  1972. # Range 200..60000.
  1973. "listing_max_tokens": 4000,
  1974. # Tools replaced by the bridge by default. This list intentionally includes cold,
  1975. # event-triggered built-ins; an explicit list replaces it wholesale and [] keeps every
  1976. # tool eager. The runtime fallback in tools/tool_search.py derives from this value.
  1977. "defer": [
  1978. "computer_use", "session_search", "image_generate",
  1979. "todo_list", "process_manage", "cronjob_manage", "browser_vault",
  1980. # Desktop GUI surface (desktop_ui, project and catalog toolsets)
  1981. "drive_preview", "gui_tour", "desktop_preview", "annotate_preview", "manage_catalog",
  1982. "show_tip", "desktop_project", "close_terminal",
  1983. "set_theme", "read_terminal", "read_window_below", "focus_pane",
  1984. ],
  1985. },
  1986. # Remote connector discovery/lifecycle through the Nous tool gateway.
  1987. # The flag is the user's off switch; availability additionally requires
  1988. # the portal sign-in every managed tool gates on.
  1989. "connectors": {"enabled": True},
  1990. },
  1991. "logging": { # File logging to ~/.hermes/logs/: agent.log captures INFO+, errors.log WARNING+.
  1992. "level": "INFO", # minimum level for agent.log: DEBUG, INFO, WARNING
  1993. "max_size_mb": 5, # max size per log file before rotation
  1994. "backup_count": 3, # rotated backups to keep
  1995. },
  1996. # Remote model-catalog manifest: curated OpenRouter / Nous Portal model lists fetched from this
  1997. # URL (falls back to the in-repo snapshot on network failure), so picker lists update without a
  1998. # release. Default URL is served by the docs-site GitHub Pages deploy.
  1999. "model_catalog": {
  2000. "enabled": True,
  2001. "url": "https://hermes-agent.nousresearch.com/docs/api/model-catalog.json",
  2002. # Disk cache TTL in minutes. The gateway refreshes in the background on this cadence; the
  2003. # CLI refetches on the next /model or `hermes model` once the cache is older. Network
  2004. # failures silently use the stale cache. Legacy `ttl_hours` is honoured if set.
  2005. "ttl_minutes": 20,
  2006. # Per-provider override URLs for self-hosted curation lists using the same schema, e.g.
  2007. # providers: {openrouter: {url: https://example.com/my-curation.json}}.
  2008. "providers": {},
  2009. },
  2010. # Per-model metadata overrides. Fields: context_window, supports_tools,
  2011. # supports_vision, supports_reasoning, model_family. <provider>.<model_id> wins over
  2012. # models.dev/OpenRouter/hardcoded defaults for the fields it sets (chain order in
  2013. # agent/model_metadata.py). <provider>._default and top-level _default fill gaps ONLY for models
  2014. # the catalog does not know, so they never clamp known models. Unknown ids start from safe
  2015. # defaults (200K context, tools on) and get patched; supports_vision / supports_reasoning stay
  2016. # UNKNOWN (fail-open) unless the override sets them — a context_window-only entry must not turn
  2017. # into "text-only" and hide vision_analyze / reasoning controls (#112649). Provider keys: Hermes
  2018. # or models.dev id; model ids match case-insensitively. Example: {"custom:my-local-vllm":
  2019. # {"my-llava-model": {"context_window": 8192}}}
  2020. # Semantics: 1. NOTE: an explicit model.context_length (global) and a custom_providers per-model
  2021. # context_length are user settings at other layers and are consulted in the resolution chain order
  2022. # documented in agent/model_metadata.py. 2. See #84482, #8731.
  2023. "model_overrides": {},
  2024. # models.dev registry (context windows, capabilities, pricing, modalities): fetched on startup,
  2025. # served from cache, refreshed by a background daemon with ETag conditional GET. Override `url`
  2026. # to point at a mirror (e.g. behind a corporate proxy).
  2027. "models_dev": {
  2028. "url": "", # empty = default https://models.dev/api.json
  2029. },
  2030. "network": {
  2031. # Force IPv4. With broken/unreachable IPv6, Python tries AAAA first and hangs for the full
  2032. # TCP timeout before falling back. True skips IPv6 entirely.
  2033. "force_ipv4": False,
  2034. },
  2035. # Gateway monitoring: service health + redacted operational diagnostics exported over OTLP to an
  2036. # operator endpoint (OTEL Collector, DataDog, ...). Content-free by construction: no prompts,
  2037. # messages, tool args/results, session history, usage analytics, audit logs, or trajectories.
  2038. # Nothing is collected or sent until enabled with an endpoint.
  2039. "monitoring": {
  2040. # Stable install identifier on exported signals so operators can tell instances apart. "" =
  2041. # mint a fresh UUID on first use; clear it to rotate. Carries no account identity.
  2042. "install_id": "",
  2043. "gateway_health_export": { # Gateway health & diagnostics export.
  2044. "enabled": False,
  2045. "metrics_enabled": True,
  2046. "diagnostic_events_enabled": True,
  2047. "warning_error_events_enabled": True,
  2048. "export_interval_seconds": 60,
  2049. "logs_export_interval_seconds": 5,
  2050. "resource_attributes": {
  2051. "service.name": "hermes-gateway", "deployment.environment.name": "production"
  2052. },
  2053. },
  2054. # OTLP destination. headers_env maps header names to ENVIRONMENT VARIABLE NAMES (never
  2055. # secret values); values are read from the environment at export time.
  2056. "export": {"otlp": {"enabled": False, "endpoint": "", "headers_env": {}}},
  2057. },
  2058. # Native hosted-room Discussion ceilings, shared by all members per discussion.
  2059. # Positive integers only (no unlimited/0). Read from the root owner's config at service
  2060. # startup for all hosted rooms; restart the owning service after changing them.
  2061. "hosted_rooms": {
  2062. "discussion": {
  2063. "max_rounds": 3,
  2064. "max_messages": 10,
  2065. },
  2066. },
  2067. "gateway": { # Gateway settings (messaging platforms: Telegram, Discord, Slack, ...).
  2068. "unmanaged_idle_exit_seconds": 600, # client-auto-started gateway only; 0 disables
  2069. # Seconds a SIGTERM-interrupted agent unwinds before teardown (short: service stop budgets).
  2070. "signal_interrupt_grace_timeout": 1,
  2071. "service_install_choice": None, # null | install | decline; never authorizes ordinary launch installation.
  2072. # Durable delivery-obligation ledger: final responses are recorded in state.db around the
  2073. # platform send; a gateway that died between finalize and platform ACK redelivers on next
  2074. # boot (ambiguous cases carry a "recovered reply — may be a duplicate" marker;
  2075. # at-least-once). Disable to lose in-flight final responses on crash/restart.
  2076. "delivery_ledger": True,
  2077. # Seconds to wait for one platform to connect at startup/reconnect; raise on "discord
  2078. # connect timed out" loops (many slash commands to sync). 0/negative = wait forever. Bridged
  2079. # to HERMES_GATEWAY_PLATFORM_CONNECT_TIMEOUT, which wins if set explicitly.
  2080. # Seconds the gateway waits for a single messaging platform to finish connecting during startup (and
  2081. # on reconnect). Discord in particular can blow past the old fixed 30s when an account has many
  2082. # slash commands to sync (#19776: 90-173 skills → ~28-31s sync). Raise this if your gateway hits
  2083. # "discord connect timed out" / "Timeout waiting for connection to Discord" restart loops. ``0`` or
  2084. # negative disables the timeout entirely (wait indefinitely).
  2085. "platform_connect_timeout": 30,
  2086. # Event-loop liveness watchdog: a daemon thread probes the asyncio loop; after consecutive
  2087. # missed probes it dumps all-thread stacks and hard-exits with the service-restart code so
  2088. # systemd/launchd revives the process instead of leaving a wedged-but-alive zombie.
  2089. # Set to false to disable. See #69089.
  2090. "loop_watchdog": True,
  2091. # Watchdog tuning (defaults mirror gateway/shutdown_watchdog.py): probe_interval = seconds
  2092. # between probes; probe_timeout = seconds before an unprocessed probe counts as a miss;
  2093. # max_strikes = consecutive misses before hard-exit 75 (~90-120s of sustained loop block at
  2094. # the defaults).
  2095. "loop_watchdog_probe_interval_s": 30.0,
  2096. "loop_watchdog_probe_timeout_s": 10.0,
  2097. "loop_watchdog_max_strikes": 3,
  2098. # Allow all users without allowlists (security opt-in).
  2099. "allow_all_users": False,
  2100. # Bot-to-bot loop guard: max_events per window before a cooldown; max_hops bot messages per exchange.
  2101. "bot_loop_guard": {"enabled": True, "max_events": 20, "window_seconds": 300, "cooldown_seconds": 600, "max_hops": 4, "bot_replies_expect_reply": False},
  2102. # Startup-liveness watchdog: stdlib-only daemon thread armed at process entry that
  2103. # hard-exits 75 if the loop isn't live within the deadline. Armed before config loads, so
  2104. # run_gateway() bridges these to HERMES_STARTUP_WATCHDOG / HERMES_STARTUP_WATCHDOG_TIMEOUT_S
  2105. # and re-arms the live handle; explicit env wins.
  2106. "startup_watchdog": True,
  2107. "startup_watchdog_timeout_seconds": 300,
  2108. # Keep writing the legacy ~/.hermes/sessions/sessions.json mirror of the routing index
  2109. # (primary copy: state.db gateway_routing table). True for external tooling and downgrade
  2110. # safety; False stops producing the file.
  2111. "write_sessions_json": True,
  2112. # One gateway for every profile on this host: the DEFAULT profile's gateway also connects
  2113. # each named profile's bots (their own .env / config.yaml, per-profile secret scope) and
  2114. # stamps the profile into session keys. This is the ONLY supported topology — there is no
  2115. # `false` opt-out any more: an explicit `false` still parses (it is the runtime mode flag
  2116. # every scoped code path reads) but is warned about and IGNORED for process topology, and
  2117. # `hermes gateway migrate --multiplex` folds any per-profile fleet that is left.
  2118. # An UNSET key is a request, not a verdict: at boot the gateway runs the migration
  2119. # preflight and stays standalone (logging why) while a secondary still runs its own
  2120. # gateway or a blocker exists, then converges once that is resolved.
  2121. # TWO things DO change on a host that had pinned `false`, and neither is a process:
  2122. # • INGRESS — `/p/<profile>/` on the default listener goes 404 -> served
  2123. # (gateway/api_server.py::_resolve_request_profile, gateway/webhook.py). A host that
  2124. # opted out GAINS that HTTP surface; it is authenticated exactly like the default
  2125. # profile's, but it is new reachable surface, so audit any reverse proxy that assumed
  2126. # /p/ was dead.
  2127. # • SECRET SCOPE — eager multi-profile activation no longer consults the flag
  2128. # (tui_gateway/launch_profile_policy.py), so a host with a leftover servable profile
  2129. # dir flips eager=false/reads-open -> eager=true/fail-closed: an UNSCOPED `get_secret`
  2130. # now raises UnscopedSecretError, and a key that lives ONLY in the unit's
  2131. # `Environment=` (no .env) disappears from file-built scopes. A genuinely
  2132. # single-profile host never activates and is byte-identical.
  2133. # Two profiles configuring the same bot token cannot be served together — the duplicate
  2134. # adapter is parked; `hermes profile create --clone` therefore leaves messaging channels
  2135. # behind unless --clone-channels is passed.
  2136. "multiplex_profiles": True,
  2137. # May `hermes update` fold this install onto a multiplexed default gateway by itself?
  2138. # True (the default) keeps today's behaviour: a multi-profile install whose secondaries run
  2139. # their own gateways is migrated automatically after an update when nothing blocks it.
  2140. # Set to False to choose WHEN you converge, not whether: the fold is left to you to run by
  2141. # hand (it is not an opt-out from the one-gateway-per-host model, which has none). Only the
  2142. # AUTOMATIC path reads this: `hermes gateway migrate --multiplex` is explicit and proceeds.
  2143. "auto_multiplex_migration": True,
  2144. # Route inbound chats of the default profile's bots to another profile
  2145. # (gateway/profile_routing.py): [{profile, platform, chat_id|user_id|guild_id|...}].
  2146. # Most-specific match wins; only read by the multiplexing default gateway.
  2147. "profile_routes": [],
  2148. # Scale-to-zero idle TIMEOUT only. When an instance is opted in via the NAS "Labs" toggle
  2149. # (HERMES_SCALE_TO_ZERO env stamp) AND messaging is relay-only/absent AND a wakeUrl is
  2150. # registered, the relay transport goes dormant so the platform (e.g. Fly autostop) can
  2151. # suspend the machine; it wakes on the wakeUrl poke. Enablement is the Labs toggle, never a
  2152. # config key. 0/negative = default.
  2153. "scale_to_zero": {"idle_timeout_minutes": 2},
  2154. # Auto-resume restart-loop breaker. A supervisor-revived gateway auto-resumes the
  2155. # SIGTERM-interrupted session; if that turn keeps triggering the kill, boots no more than
  2156. # `max_gap_seconds` apart (floored by `window_seconds`) chain, and after `max_restarts`
  2157. # auto-resume is SKIPPED for that boot (inbound messages still served). Gap-based chaining
  2158. # also catches SLOW ~150s crash cycles. max_restarts=0 disables.
  2159. "restart_loop_guard": {"max_restarts": 3, "window_seconds": 60, "max_gap_seconds": 300},
  2160. # Respawn-storm circuit breaker (complements restart_loop_guard): counts (re)starts in a
  2161. # sliding window and sleeps an exponential backoff before booting so a crash-looping
  2162. # supervisor can't hammer the process. max_starts <= 0 disables. Env escape hatches:
  2163. # HERMES_GATEWAY_MAX_STARTS / HERMES_GATEWAY_START_WINDOW_S.
  2164. "respawn_storm": {"max_starts": 5, "window_seconds": 120},
  2165. # Prefix user messages IN THE MODEL'S CONTEXT with a timestamp (e.g. "[Tue 2026-04-28
  2166. # 13:40:53 CEST]") for temporal awareness. Persisted transcripts stay clean (timestamp is
  2167. # message metadata regardless), so enabling later surfaces past send-times too.
  2168. "message_timestamps": {"enabled": False},
  2169. # Max bytes of inbound image/audio/video the gateway buffers into RAM and caches to disk.
  2170. # Media is read fully into memory first, so unbounded uploads (Discord Nitro: 500 MB) or
  2171. # huge remote URLs can OOM-kill constrained deployments. Enforced in
  2172. # gateway/platforms/base.py for every adapter. 0 = no cap. Default 128 MiB.
  2173. "max_inbound_media_bytes": 134217728,
  2174. # Let adapters read HTTP_PROXY/HTTPS_PROXY/NO_PROXY/SSL_CERT_FILE from the environment and
  2175. # auto-detect generic/macOS system proxies. False when the gateway inherits a proxy it must
  2176. # not use (e.g. a scheduled task picking up a Clash/V2Ray HTTP_PROXY -> "Cannot connect to
  2177. # host 127.0.0.1:7890"). Per-platform vars (DISCORD_PROXY, TELEGRAM_PROXY, ...) are still
  2178. # honored.
  2179. "trust_env": True,
  2180. # Media delivery. False: any emitted file path is delivered natively unless under the
  2181. # credential/system denylist (/etc, /proc, ~/.ssh, ~/.aws, ~/.hermes/.env, auth.json). True:
  2182. # files must be under the Hermes cache, media_delivery_allow_dirs, or fresher than
  2183. # trust_recent_files_seconds — recommended for public-facing gateways so prompt injection
  2184. # can't exfiltrate host secrets. Bridged to HERMES_MEDIA_DELIVERY_STRICT.
  2185. "strict": False,
  2186. # Extra roots (project/scratch dirs, mounted shares) from which bare file paths may be
  2187. # uploaded; the Hermes cache is always trusted. List of absolute paths or one
  2188. # os.pathsep-separated string; tildes expanded. Bridged to HERMES_MEDIA_ALLOW_DIRS. Honored
  2189. # in both modes.
  2190. "media_delivery_allow_dirs": [],
  2191. # Trust files whose mtime is within trust_recent_files_seconds even outside the cache/
  2192. # allowlist (e.g. `pandoc -o /tmp/report.pdf`); system paths stay blocked. False =
  2193. # pure-allowlist mode. Bridged to HERMES_MEDIA_TRUST_RECENT_FILES. Only consulted when
  2194. # strict is true.
  2195. "trust_recent_files": True,
  2196. # Recency window in seconds; 600 covers a multi-tool turn. Bridged to
  2197. # HERMES_MEDIA_TRUST_RECENT_SECONDS. Only consulted when strict is true.
  2198. "trust_recent_files_seconds": 600,
  2199. "api_server": { # OpenAI-compatible API server platform (gateway/platforms/api_server.py).
  2200. # Max concurrent agent runs. Requests to /v1/chat/completions, /v1/responses, and
  2201. # /v1/runs beyond this get HTTP 429 + Retry-After, bounding CPU/memory/LLM-quota
  2202. # exhaustion from a request flood. 0 = no cap.
  2203. "max_concurrent_runs": 10,
  2204. # Cap (chars) on each tool output and tool-call argument string in the stored
  2205. # /v1/responses conversation history used for previous_response_id chaining. The
  2206. # stored history is cumulative, so a few large tool outputs can make one
  2207. # response_store.db write several hundred KB. 0 = store tool outputs verbatim
  2208. # (default: the capped text is what the model is replayed on the next turn).
  2209. "history_tool_output_max_chars": 0,
  2210. },
  2211. },
  2212. # Real-time token streaming to messaging platforms (gateway; restart after enabling). Off by
  2213. # default: costs extra edit/draft API calls per response.
  2214. "streaming": {
  2215. "enabled": False, # When false, each response is delivered as one final message.
  2216. # auto = native drafts where supported (Telegram DMs, Bot API 9.5+), edits elsewhere
  2217. # (Discord, Slack, Matrix, Telegram groups); draft = drafts with edit fallback; edit =
  2218. # progressive editMessageText only; off = disabled.
  2219. "transport": "auto",
  2220. # Minimum seconds between progressive edits (Telegram's ~1 edit/s flood envelope).
  2221. "edit_interval": 0.8,
  2222. # Flush the buffer once this many chars accumulate, so short replies feel instant.
  2223. "buffer_threshold": 24,
  2224. "cursor": " \u2589", # Cursor glyph appended to the in-progress message.
  2225. # Telegram only: when >0, if the preview was visible at least this many seconds the final
  2226. # edit is sent as a fresh message so the timestamp reflects completion.
  2227. "fresh_final_after_seconds": 0.0,
  2228. },
  2229. # Automatic cleanup of ~/.hermes/state.db, which otherwise grows without bound and slows FTS5
  2230. # inserts, /resume listing, and insights queries.
  2231. "sessions": {
  2232. # Prune ENDED sessions inactive for retention_days (activity = freshest of live activity /
  2233. # latest message / creation) about once per min_interval_hours at CLI/gateway/cron startup.
  2234. # Open, pinned, or mid-turn sessions are never deleted; stale automation sessions whose
  2235. # process died are *closed*, then get a full retention window before removal.
  2236. # Off by default (deleting history is opt-in). While the user's config.yaml has no
  2237. # auto_prune key, every surface asks once the disk holding state.db runs low
  2238. # (hermes_cli/prune_advisor.py); either answer writes the key and ends the question.
  2239. "auto_prune": False,
  2240. # Inactive days of ended-session history to keep (= `hermes sessions prune`).
  2241. "retention_days": 90,
  2242. # Auto-archive (soft-hide, never delete) sessions with no activity for auto_archive_days,
  2243. # once per min_interval_hours. Pinned sessions are exempt.
  2244. "auto_archive": False,
  2245. # Idle days before auto-archive hides a session (only when auto_archive is true).
  2246. "auto_archive_days": 3,
  2247. # List delegate_task subagent runs in session lists (desktop sidebar, dashboard, session.list),
  2248. # nested under their parent. Off by default: they are machinery, not conversations.
  2249. "show_subagents": False,
  2250. # VACUUM after a prune that deleted rows (SQLite never reclaims disk on DELETE, #54189). It blocks
  2251. # writes (~seconds per 100MB): only at startup, only when ≥1 session went AND freelist/page_count > 25%.
  2252. "vacuum_after_prune": True,
  2253. # Minimum days between VACUUM rewrites; pruning keeps its normal cadence.
  2254. "min_vacuum_interval_days": 30,
  2255. # Minimum hours between auto-maintenance runs (tracked in state.db state_meta, shared across
  2256. # processes).
  2257. "min_interval_hours": 24,
  2258. # Notice about the compact FTS layout (reclaims ~60%+ of state.db). OPT-IN: legacy indexes
  2259. # stay until `hermes sessions optimize-storage` runs, since the rebuild is disk-heavy on
  2260. # large DBs. advise = `hermes update` prints a one-line notice with reclaimable size when a
  2261. # legacy index is detected (a later layout change gets a rebuild notice without a size estimate);
  2262. # require = the same notices worded as REQUIRED (tooling may gate on it); off = none.
  2263. "fts_optimize_notice": "advise",
  2264. # CJK-bigram search index (messages_fts_cjk). When the extension is built
  2265. # (native/fts5_cjk/build.sh → ~/.hermes/lib/libfts5_cjk.so), 1-2 char CJK terms get exact
  2266. # index matches instead of LIKE scans. True = use when present (inert otherwise); False =
  2267. # never load/serve it. Bridged to HERMES_CJK_FTS.
  2268. "cjk_fts": True,
  2269. # Slow session-search threshold (ms): searches at/above it log one INFO line with the
  2270. # routing path (fts_cjk / fts5 / trigram / like_scan). 0 logs every search. Bridged to
  2271. # HERMES_SEARCH_SLOW_MS.
  2272. "search_slow_ms": 1000,
  2273. # Transcript guards (a runaway 100k+ row session can exhaust memory when materialized at
  2274. # once; 0 disables). Max active messages (across the compression lineage) for interactive
  2275. # resume.
  2276. "max_resume_messages": 20000,
  2277. # Max active messages per session for in-memory export (`hermes sessions export`); checked
  2278. # per session, so full-DB backups of small sessions work.
  2279. "max_export_messages": 20000,
  2280. # Seconds before a local session with no viewer is ended (resumable) once its turn settles; 0 = never; after a
  2281. # restart also >= 6h idle. Unset: dashboard.ws_orphan_reap_grace_s: 0 / startup_orphan_sweep: false opt out.
  2282. "orphan_end_grace_s": 300.0,
  2283. },
  2284. # First-touch onboarding hints (agent/onboarding.py), each latched under `seen` once shown.
  2285. "onboarding": {
  2286. "seen": {},
  2287. "profile_build": "ask", # first-ever message: ask = offer; off = plain intro only
  2288. # Desktop first run, root profile only (onboarding_run.py): None = fresh install; true = next launch; false = done
  2289. "run": None,
  2290. },
  2291. # Privacy-safe aggregate metrics in this profile's local telemetry dir. Collection (`enabled`)
  2292. # and upload to Nous (`send`) are separate keys that every consent surface sets together; see
  2293. # website/docs/developer-guide/relay-shared-metrics.md Appendix A for consent/retention.
  2294. "telemetry": {
  2295. "shared_metrics": {
  2296. "enabled": False,
  2297. # Requires `enabled` (`send` alone logs an error). A package is sent only if its whole
  2298. # period is inside a recorded consent window.
  2299. "send": False,
  2300. # Ingest endpoint (override for staging/local). Deliberately NOT env- overridable.
  2301. # Non-HTTPS refused unless the host is localhost.
  2302. "endpoint": "https://telemetry.nousresearch.com/v1/telemetry",
  2303. },
  2304. },
  2305. "doctor": {
  2306. # Per-probe timeout (seconds) for `hermes doctor --live` real-call probes.
  2307. "live_probe_timeout": 10,
  2308. },
  2309. "updates": {
  2310. # Passive version/banner checks only; explicit `hermes update --check` remains enabled.
  2311. "check": True,
  2312. # Pre-update backup. quick = snapshot small critical state (pairing JSONs, cron jobs,
  2313. # config.yaml, .env, auth.json, profile DBs) into <HERMES_HOME>/state-snapshots/, skipping
  2314. # files >1 GiB; restore via ``/snapshot``. full = quick PLUS a ``hermes backup`` zip in
  2315. # <HERMES_HOME>/backups/ (``hermes import`` restores; slow on large homes; ``--backup``
  2316. # forces once). off = none (``--no-backup`` forces once). Legacy booleans: true -> full,
  2317. # false -> off.
  2318. # Pre-update safety backup — ONE consolidated mechanism, three modes: Files over 1 GiB (e.g. a
  2319. # bloated state.db) are skipped with a warning so the snapshot stays fast. This is the #48200
  2320. # (wrong-path wipe) safety net.
  2321. "pre_update_backup": "quick",
  2322. # Full backup zips to retain (older pruned after each success; floored to 1 so the newest is
  2323. # always kept). The quick snapshot always keeps exactly 1.
  2324. "backup_keep": 5,
  2325. # Uncommitted source-tree changes during NON-interactive updates (desktop, gateway — no TTY;
  2326. # interactive updates always stash and ask). stash = stash, pull, restore on top (conflicts
  2327. # stay in a git stash). discard = stash and drop after the pull (stash-and-drop, not reset
  2328. # --hard + clean -fd, so ignored paths like node_modules/venv are never touched).
  2329. "non_interactive_local_changes": "stash",
  2330. # If the checkout is parked on a feature branch and the tree is clean, switch to the update
  2331. # target (commits stay on the branch; a loud notice names it) so non-interactive updates
  2332. # keep working. A DIRTY tree blocks the switch and the code update is SKIPPED with a loud
  2333. # warning. False = never auto-switch.
  2334. "auto_switch_parked_branch": True,
  2335. # Clean parked branch with unmerged commits: switch = move to the update target, commits
  2336. # stay on the branch (never conflicts). update_in_place = for a maintained custom branch:
  2337. # merge origin/<target> INTO it after leaving a pre-update-<stamp> tag; a conflict stops the
  2338. # update cleanly. `hermes update --switch-branch` overrides to switch for one run.
  2339. "parked_branch_strategy": "switch",
  2340. # Refresh an installed cua-driver during `hermes update` (best-effort, macOS only). Turn off
  2341. # e.g. on non-admin accounts where /Applications isn't writable.
  2342. "refresh_cua_driver": True,
  2343. },
  2344. # LSP diagnostics (pyright, gopls, rust-analyzer...) in the post-write lint check of
  2345. # write_file/patch. Runs only when the cwd or edited file is inside a git worktree; otherwise
  2346. # dormant and the in-process syntax check is the only tier.
  2347. "lsp": {
  2348. "enabled": True, # False disables the whole subsystem: no servers, no event loop, no cost.
  2349. # document = wait up to wait_timeout seconds for the current file's diagnostics; full = also
  2350. # request workspace-wide diagnostics (slower).
  2351. "wait_mode": "document",
  2352. "wait_timeout": 5.0,
  2353. # Budget for the FIRST request against a workspace whose server is not running yet (spawn +
  2354. # initialize + the server's initial program build; tsserver on a large project can need a
  2355. # minute). Once the client is up, wait_timeout applies again. 0 = same as wait_timeout.
  2356. "warmup_timeout": 0.0,
  2357. # After a server fails (spawn error or outer timeout) its (server, workspace root) pair is
  2358. # skipped. 0 = for the process lifetime (until `hermes lsp restart`); N = retried after N
  2359. # seconds, so one transient stall does not silence a workspace forever.
  2360. "broken_retry_seconds": 0.0,
  2361. # Workspace roots (glob patterns, ~ expanded; a bare path also matches everything under
  2362. # it) where no language server runs at all, e.g. one huge monorepo whose server cannot
  2363. # finish in budget, while every other workspace keeps its diagnostics. Must be a list —
  2364. # any other shape logs a warning and skips LSP for every workspace until fixed.
  2365. "exclude_roots": [],
  2366. # Directories (~ expanded; everything under an entry counts) whose projects a language
  2367. # server may load code from: the project's own .venv/venv interpreter, node_modules
  2368. # TypeScript SDK, svelte.config.js, build files (cargo, Gradle, mix, ...). The worktree of
  2369. # the launch dir or the session's workspace (hermes -w, a Desktop project, terminal.cwd) is
  2370. # always trusted; in any other checkout (a clone the agent made) only servers that run no
  2371. # project code start, pinned to Hermes-side tools, and the npx tsc / rustfmt lint fallbacks
  2372. # are skipped.
  2373. "trusted_workspaces": [],
  2374. # Missing server binaries: auto = install via npm/go/pip into <HERMES_HOME>/lsp/bin/ on
  2375. # first use; manual = only binaries on PATH; off = alias for manual.
  2376. "install_strategy": "auto",
  2377. # Node package manager for the npm-recipe servers: npm | pnpm | yarn. Installs still land in
  2378. # <HERMES_HOME>/lsp/node_modules; a configured manager that is not installed, or an unknown
  2379. # value, skips the install (no silent fallback to npm) so a pnpm/yarn supply-chain policy is
  2380. # never bypassed.
  2381. "package_manager": "npm",
  2382. # Idle seconds before a server is shut down (respawned on demand), so long- running
  2383. # processes don't accumulate stale children (hundreds of MB + pipe FDs each) across
  2384. # worktrees. 0 = keep servers for process lifetime.
  2385. "idle_timeout": 600.0,
  2386. # Per-server overrides keyed by registry server_id (pyright, gopls...): disabled: true;
  2387. # command: ["path/to/server", "--stdio"] (bypasses auto- install); env: {...};
  2388. # initialization_options: {...} (merged into LSP initializationOptions).
  2389. # A key that is NOT a built-in id declares a custom server (matched before the built-ins):
  2390. # command: ["my-ls", "--stdio"]; extensions: [".ext"]; optional root_markers: [...],
  2391. # language_id: "..." (didOpen languageId), description: "...". Manual install only.
  2392. "servers": {},
  2393. },
  2394. # X (Twitter) Search via xAI's x_search Responses tool. Registers when xAI creds exist
  2395. # (SuperGrok OAuth or XAI_API_KEY) AND the toolset is enabled in `hermes tools`.
  2396. "x_search": {
  2397. # xAI model for the Responses call; any Grok model with x_search access works.
  2398. "model": "grok-4.5",
  2399. # Reasoning effort for models that support it; null keeps the model default.
  2400. "reasoning_effort": None,
  2401. # Request timeout in seconds (minimum 30); complex queries can take 60-120s.
  2402. "timeout_seconds": 180,
  2403. # Retries on 5xx / ReadTimeout / ConnectionError (backoff 1.5x attempt s, cap 5s).
  2404. "retries": 2,
  2405. },
  2406. # External secret sources — pull credentials from secret managers at startup instead of storing
  2407. # them in ~/.hermes/.env.
  2408. # Browser credential vault: which login sources browser_vault may draw from. The local
  2409. # encrypted vault (`hermes vault add`, Desktop → Settings → Credential Vault) is always on.
  2410. # External password managers are unlocked per session with a masked master-password prompt;
  2411. # headless sessions (cron, webhook, API) never prompt and see them as locked.
  2412. "vault": {
  2413. "key_storage": "file", # NEW vault's key: file (0600 vault.key) | keychain (OS; file if none). See `hermes vault key`.
  2414. "onepassword": { # detected managers are login sources unless the user opts out (enabled: false)
  2415. "enabled": True, # `op` CLI: Login items with a website URL become fillable handles.
  2416. "account": "", # account shorthand for `op --account`; empty = default account.
  2417. "binary_path": "", # absolute path to op; empty = PATH.
  2418. # Env var holding a service-account token (headless auth, no unlock prompt). Unset = prompt.
  2419. "service_account_token_env": "OP_SERVICE_ACCOUNT_TOKEN",
  2420. },
  2421. "bitwarden": {
  2422. "enabled": True, # `bw` CLI (Password Manager, not Secrets Manager); run `bw login` once first.
  2423. "binary_path": "", # absolute path to bw; empty = PATH.
  2424. },
  2425. },
  2426. "secrets": {
  2427. # Optional ordering of enabled sources (e.g. [onepassword, bitwarden]); default registration
  2428. # order. Mapped sources (explicit VAR→ref) always beat bulk sources (BSM project dumps);
  2429. # first claim on a var wins, later ones warn. "sources": [],
  2430. "bitwarden": {
  2431. "enabled": False, # When false, BSM is never contacted and bws is never auto-installed.
  2432. # Env var holding the machine-account token — the one bootstrap secret; lives in
  2433. # ~/.hermes/.env (or the shell), never in config.yaml.
  2434. "access_token_env": "BWS_ACCESS_TOKEN",
  2435. "project_id": "", # UUID of the BSM project to sync from.
  2436. # Seconds to reuse a fresh disk/memory cache entry before contacting Bitwarden again. 0
  2437. # disables fresh-cache reuse.
  2438. "cache_ttl_seconds": 300,
  2439. # Last-good fallback for NETWORK/TIMEOUT outages: AES-GCM cache under ~/.hermes/cache/,
  2440. # reused up to max_stale_seconds. Auth failures never fall back.
  2441. "encrypted_cache": {"enabled": False, "max_stale_seconds": 0},
  2442. # BSM values overwrite existing env vars, so rotating in Bitwarden takes effect without
  2443. # clearing the matching .env line.
  2444. "override_existing": True,
  2445. # Auto-download bws into ~/.hermes/bin/ on first use; False = bws must be on PATH.
  2446. "auto_install": True,
  2447. # Passed to bws as BWS_SERVER_URL. Empty = US Cloud (bws default);
  2448. # https://vault.bitwarden.eu for EU; your own URL for self-hosted.
  2449. "server_url": "",
  2450. },
  2451. "onepassword": {
  2452. "enabled": False, # When false, the op CLI is never invoked.
  2453. "env": {}, # env-var name → op://vault/item/field; each resolved with one `op read`.
  2454. # Account shorthand / sign-in address for `op read --account`; empty = default.
  2455. "account": "",
  2456. # Env var holding a service-account token for headless auth (exported to op as
  2457. # OP_SERVICE_ACCOUNT_TOKEN). Unset = interactive/desktop op session.
  2458. "service_account_token_env": "OP_SERVICE_ACCOUNT_TOKEN",
  2459. # Absolute path to op, used verbatim (avoids trusting PATH). Empty = PATH.
  2460. "binary_path": "",
  2461. # Seconds to cache values in-process and on disk; 0 disables BOTH layers.
  2462. "cache_ttl_seconds": 300,
  2463. # Overwrite existing env vars so rotation takes effect; False lets .env win.
  2464. "override_existing": True,
  2465. },
  2466. },
  2467. # Paste collapse thresholds (TUI + CLI); 0 disables each. threshold: bracketed pastes with this
  2468. # many newlines collapse to a file reference. fallback: same test for terminals without
  2469. # bracketed paste, gated by chars/newlines-added heuristics. char_threshold: single-line pastes
  2470. # this long collapse too.
  2471. "paste_collapse_threshold": 5,
  2472. "paste_collapse_threshold_fallback": 5,
  2473. "paste_collapse_char_threshold": 2000,
  2474. # Bot Desktop: a headless Xfce screen per profile on the gateway host (Linux), streamed to Hermes
  2475. # Desktop where a human can watch, take over (logins, 2FA, CAPTCHAs) and hand back. `hermes computer-use screen`.
  2476. "bot_desktop": {
  2477. "geometry": "1440x900",
  2478. # Opt-in: start the screen automatically the first time computer_use needs a display on a headless
  2479. # host. Off by default so installing TigerVNC for other reasons never yields a screen nobody asked
  2480. # for; Hermes Desktop's Screen pane offers Start and this toggle.
  2481. "auto_start": False,
  2482. # Refuse to start below this much free memory (MB), measured on the host or its container cgroup,
  2483. # whichever is tighter. Xvnc + Xfce idle at ~220 MB and a takeover's browser adds 0.5-1 GB, so a
  2484. # screen with one page runs past 1 GB; the kernel OOM killer picks its victim by score, so on a
  2485. # small instance the loser is the dashboard or the gateway rather than the desktop. 0 disables the
  2486. # check.
  2487. "min_free_memory_mb": 1536,
  2488. # Stop a screen nobody has used (no computer_use action, browser spawn, viewer or takeover) for this
  2489. # long; it restarts on the next use. Idle Xvnc + Xfce hold ~220 MB, an abandoned browser far more.
  2490. # 0 keeps screens up until stopped.
  2491. "idle_stop_minutes": 30,
  2492. # Where the screen (and with it computer_use and the bot's browser) runs.
  2493. # auto follow the terminal backend: inside the docker / ssh / streaming plugin sandbox when one is
  2494. # configured, on the gateway host when terminal.backend is local. A sandbox backend that
  2495. # cannot host a screen (modal, daytona, vercel) REFUSES rather than quietly running the
  2496. # desktop on the host beside the sandbox you chose for the agent.
  2497. # terminal always inside the terminal backend (error when it cannot host one).
  2498. # gateway always on the gateway host, even with a sandbox terminal: the agent's screen, browser
  2499. # and computer_use then act OUTSIDE the terminal sandbox. Explicit opt-in.
  2500. # The sandbox image needs the desktop stack: nousresearch/hermes-sandbox:desktop.
  2501. "placement": "auto",
  2502. },
  2503. "computer_use": {
  2504. # cua-driver's upstream PostHog telemetry defaults ON; Hermes sets
  2505. # CUA_DRIVER_RS_TELEMETRY_ENABLED=0 in every child env unless this is true.
  2506. "cua_telemetry": False,
  2507. # Windows only: opt IN to the per-boot cua-driver-serve logon task. False (default)
  2508. # keeps the driver on-demand — Computer Use starts it per session, exactly as on
  2509. # macOS/Linux, and install/enable flows register no scheduled task (#97389). True
  2510. # registers (or repairs) the task at install time — needed to drive Windows over SSH,
  2511. # where Session 0 has no interactive desktop (see the computer-use guide).
  2512. "autostart": False,
  2513. "native_wayland": False,
  2514. # Cap driver screenshot longest edge (pixels) via set_config at session start; shrinks SOM
  2515. # multimodal payloads. 0 disables.
  2516. "max_image_dimension": 1456,
  2517. # capture_after mode: som = screenshot + overlays; ax = elements only, no PNG (faster);
  2518. # vision = pixels only.
  2519. "capture_after_mode": "som",
  2520. # Bound cua-driver's accessibility-tree WALK on every capture (get_window_state max_elements).
  2521. # _DEFAULT_MAX_ELEMENTS in tools/computer_use/tool.py caps the SURFACED element list at 100 and
  2522. # spills the rest to a cache file, so an unbounded walk pays for nodes the model never sees:
  2523. # measured on macOS (cua-driver 0.28.2, M-series) a 1,444-node Chrome window went 540 ms -> 83 ms
  2524. # and a 456-node Finder window 6.9 s -> 0.6 s at 200, with the returned elements a prefix of the
  2525. # unbounded walk. 0 = driver default (2,000 elements / depth 25) — the pre-fix behaviour.
  2526. # ~400 keeps the full first 100 visible elements on a pathological tree, at ~1.4 s on Finder;
  2527. # the walk's cost grows with the bound, so keep it in the low hundreds. This caps the nodes
  2528. # COLLECTED, not the walk's wall clock: a target whose AX surface exceeds the driver's own 20 s
  2529. # walk timeout still fails at every bound (measured; a depth bound does not help there either).
  2530. "ax_max_elements": 200,
  2531. # Disable cua-driver's cursor overlay, which can peg a core when idle (macOS redraw loop;
  2532. # Linux/WSL2 idle spin). None = auto (off on macOS + headless/ WSL2 Linux, on elsewhere);
  2533. # True = always disable; False = always enable.
  2534. # The overlay shows where agent actions land but can peg a core when idle (macOS vImage redraw loop
  2535. # #47032; Linux/WSL2 idle spin #28152). cua-driver ≥ 0.6.x supports --no-overlay; Hermes also calls
  2536. # set_agent_cursor_enabled(false) after start_session when this is on.
  2537. "no_overlay": None,
  2538. # standard = cua-driver's own approval boundary; bounded = no runtime prompts, anything
  2539. # outside capability_manifest fails closed. `unrestricted` is NOT accepted here: it stays on
  2540. # the per-session YOLO toggle so config can't bypass approvals.
  2541. "permission_mode": "standard",
  2542. # Path (~ ok) to the reviewed manifest for permission_mode bounded; passed as
  2543. # --capability-manifest. See cua.ai/docs/reference/cua-driver/permission-modes
  2544. "capability_manifest": "",
  2545. # macOS only: allow an UNSIGNED CuaDriver.app for the private-session daemon. False fails
  2546. # closed unless signed with the official com.trycua.driver identity. Only for local driver
  2547. # development from source.
  2548. "allow_unsigned_driver": False,
  2549. },
  2550. # Egress credential-injection proxy (iron-proxy) for remote terminal sandboxes (Docker today):
  2551. # the sandbox sees opaque tokens and iron-proxy swaps in real credentials at egress, so a
  2552. # compromised sandbox leaks only tokens that work behind the trusted proxy. Configure with
  2553. # `hermes egress setup`.
  2554. "proxy": {
  2555. "enabled": False, # When false, nothing starts, no docker mounts, no binary installs.
  2556. # Tunnel listener port; sandboxes get HTTPS_PROXY=http://<host>:<port>.
  2557. "tunnel_port": 9090,
  2558. # Auto-download the pinned binary into ~/.hermes/bin/; False = iron-proxy on PATH.
  2559. "auto_install": True,
  2560. # Upstream secret source: env = process env; bitwarden = refetch via `bws secret list` on
  2561. # each proxy restart (requires secrets.bitwarden.enabled).
  2562. "credential_source": "env",
  2563. # True: the Docker backend refuses to start a sandbox if the proxy is enabled but not
  2564. # running. False: fall back to direct outbound with real credentials.
  2565. "enforce_on_docker": True,
  2566. # With credential_source bitwarden, a missing BWS token/project_id or an empty fetch makes
  2567. # the daemon raise. True silently falls back to host env (useful mid-migration). A leftover
  2568. # fail_on_uncovered_providers key is ignored.
  2569. "allow_env_fallback": False,
  2570. # SSRF deny list. None/empty = loopback, link-local (incl. 169.254.169.254 metadata),
  2571. # RFC1918. Explicit [] opts out (only for hermetic loopback tests).
  2572. "upstream_deny_cidrs": None,
  2573. # Extra allowed upstream hosts beyond the bundled major-provider defaults; wildcards
  2574. # (`*.foo.com`) supported.
  2575. "extra_allowed_hosts": [],
  2576. },
  2577. "desktop": { # Hermes Desktop (Electron) launch options; only affect `hermes desktop`.
  2578. # CSS font-family for the app's chat and UI text (e.g. "OpenDyslexic"). Layered in front
  2579. # of the active theme's own sans stack so missing glyphs still fall through. Empty = the
  2580. # theme's face. The terminal pane is terminal.font_family.
  2581. "font_family": "",
  2582. # Git repo discovery for the Projects sidebar. Empty roots are a safe
  2583. # no-op; users must explicitly configure roots for filesystem scanning.
  2584. # Session-derived projects remain available.
  2585. "repo_scan_enabled": True,
  2586. "repo_scan_roots": [],
  2587. "repo_scan_exclude_paths": [],
  2588. # Extra Electron flags per launch, e.g. ["--ozone-platform=x11"] or GPU workarounds. List of
  2589. # strings; a single string is shell-split.
  2590. "electron_flags": [],
  2591. # V8 old-space ceiling (MB) for the renderer, applied as --js-flags=--max-old-space-size=N by
  2592. # the app itself (also for Start-menu / .desktop launches). 0 = Chromium's default limit.
  2593. # A ceiling turns a machine-wide freeze into a bounded renderer reload (#77311).
  2594. "renderer_max_old_space_mb": 0,
  2595. # Linux Ozone backend, bridged to ELECTRON_OZONE_PLATFORM_HINT (explicit env wins). auto =
  2596. # Chromium default; x11 = XWayland, for compositors that ignore always-on-top for Wayland
  2597. # clients (e.g. COSMIC) — also puts the HUD on the solid-window input path; wayland = force
  2598. # a native Wayland surface.
  2599. # See #84011.
  2600. "ozone_platform_hint": "auto",
  2601. # Bridged to HERMES_DESKTOP_DISABLE_GPU: auto = disable GPU only on remote displays
  2602. # (SSH/VNC/RDP); true = always software rendering (no-GPU VMs where the GPU path hangs);
  2603. # false = always keep GPU on.
  2604. "disable_gpu": "auto",
  2605. # Linux keychain for token storage (Chromium --password-store). auto = detect KWallet (KDE
  2606. # env) or any org.freedesktop.secrets provider via D-Bus;
  2607. # gnome-libsecret|kwallet|kwallet5|kwallet6|basic force one (basic = unencrypted). Bridged
  2608. # to HERMES_DESKTOP_PASSWORD_STORE; ignored off-Linux.
  2609. "password_store": "auto",
  2610. # Expose the renderer's accessibility tree to the OS (macOS/Windows) so dictation/IME tools
  2611. # that insert text via the accessibility APIs can reach the composer (#118271, #92607).
  2612. # False bridges to HERMES_DESKTOP_RENDERER_ACCESSIBILITY=0 and skips the tree (perf opt-out).
  2613. "renderer_accessibility": True,
  2614. # Linux: False preserves an existing custom XDG launcher entry; missing entries
  2615. # are still created. True keeps the generated entry current on each launch.
  2616. "manage_launcher_entry": True,
  2617. # macOS only: code-signing identity (login-keychain cert; self-signed works) to re-sign
  2618. # locally rebuilt apps so the Designated Requirement — and thus TCC grants — survives
  2619. # updates. Empty = default ad-hoc identifier-pinned signing.
  2620. "macos_signing_identity": "",
  2621. # Windows only: explicit ssh client for SSH connections, the -G config probe and SSH
  2622. # terminals, e.g. "C:\\Program Files\\Git\\usr\\bin\\ssh.exe" when the in-box OpenSSH is
  2623. # missing or broken. Empty = System32 OpenSSH, then Git for Windows' ssh.exe, then PATH.
  2624. # Read by the app before its first window; restart to apply. Ignored off-Windows.
  2625. "ssh_path": "",
  2626. # Auto-continue a turn killed by a crash: resuming re-submits the interrupted prompt if
  2627. # fresh; a stale one just shows the recovered partial transcript.
  2628. "auto_continue": {
  2629. "enabled": True,
  2630. # How recent the interruption must be to auto-continue (minutes).
  2631. "freshness_minutes": 15,
  2632. "max_attempts": 2, # Crash-loop breaker: max automatic re-runs of one interrupted turn.
  2633. },
  2634. },
  2635. "nous": {
  2636. # Upper bound (seconds) on the Nous auth keepalive tick, which derives from the
  2637. # server-issued credential lifetime (raising above it has no effect). 0 disables the
  2638. # keepalive thread.
  2639. "keepalive_interval_seconds": 900,
  2640. # anthropic_wire: which Portal route carries anthropic/* models. "chat" =
  2641. # /v1/chat/completions (default for now); "native" = /v1/messages, the Anthropic
  2642. # Messages wire (signed thinking passthrough, native cache_control scopes); "auto" =
  2643. # start on chat and, per session, switch to native from the first response when the
  2644. # Portal upstream serving the model is one where native is known clean. Native is the
  2645. # better wire but on the OpenRouter-served path it re-writes the previous turn's cache on
  2646. # 14-20% of consecutive calls in concurrent tool loops (measured 2026-09-06;
  2647. # NousResearch/api#227), so chat is the default until that is fixed.
  2648. "anthropic_wire": "chat",
  2649. # Nous free tier: with no other provider configured, Hermes sets up a free Nous identity on
  2650. # first use (inference on nous/welcome + connectors) and offers `/login` (terminal:
  2651. # `hermes auth upgrade`) to sign in. false turns the free tier off entirely: nothing is set
  2652. # up and nothing is used.
  2653. "guest": True,
  2654. },
  2655. # Google Vertex AI (Gemini). Auth is OAuth2 from a service-account JSON or ADC, NOT an API key;
  2656. # the credential path lives in .env (VERTEX_CREDENTIALS_PATH / GOOGLE_APPLICATION_CREDENTIALS).
  2657. # Bridged to VERTEX_PROJECT_ID / VERTEX_REGION.
  2658. "vertex": {
  2659. # GCP project ID. Empty → project_id from the service-account JSON (or ADC).
  2660. "project_id": "",
  2661. # "global" is required for Gemini 3.x preview models (regional endpoints silently 404); use
  2662. # e.g. "us-central1" only if your models are region-pinned.
  2663. "region": "global",
  2664. },
  2665. # Managed llama.cpp runtime (docs: user-guide/local-models): official binaries, one supervised
  2666. # llama-server in router mode. No context/VRAM knobs by design.
  2667. "local_runtime": {
  2668. # Off = detection-only (Hermes still finds an external llama-server you run).
  2669. "enabled": False,
  2670. # Engine versions and every dependent library are pinned by pm/lock.json.
  2671. # auto = CUDA on NVIDIA, Metal on macOS, Vulkan on other GPUs, else CPU. Explicit:
  2672. # cuda|metal|vulkan|hip|cpu.
  2673. "backend": "auto",
  2674. "models_max": 4, # Router process: how many models may be resident at once.
  2675. "port": 0, # Port for the managed server. 0 = pick a free port at spawn.
  2676. # Extra ports detection probes for an external llama-server (besides 8080).
  2677. "detect_ports": [],
  2678. },
  2679. "_config_version": 52, # Config schema version - bump this when adding new required fields
  2680. }
  2681. from hermes_cli.config_defaults_env import OptionalEnvVars, _base_url, _env, _msg, _prov, _setting, _skill, _tool
  2682. # Optional environment variables that enhance functionality. Feeds the dashboard keys page and setup
  2683. # checklists; category: provider|tool|skill|messaging|setting, advanced=True hides from checklists,
  2684. # tools=[...] lists the model tools the key unlocks. Provider entries: config_provider_env (on first read).
  2685. OPTIONAL_ENV_VARS = OptionalEnvVars({
  2686. # ── Provider (handled in provider selection, not shown in checklists) ──
  2687. "NOUS_BASE_URL": _base_url("Nous Portal"),
  2688. "HERMES_ANON_API_SECRET": _env(
  2689. "Shared secret for the Nous free-tier sign-up endpoints while they are in their gated "
  2690. "integration phase (not needed once the gate is removed)",
  2691. "Nous free-tier shared secret (leave empty unless given one)", password=True,
  2692. category="provider", advanced=True),
  2693. "OPENROUTER_API_KEY": _env("OpenRouter API key (for vision, web scraping helpers, and MoA)",
  2694. "OpenRouter API key", url="https://openrouter.ai/keys", password=True, tools=["vision_analyze"],
  2695. category="provider", advanced=True),
  2696. "GOOGLE_API_KEY": _prov("Google AI Studio API key (also recognized as GEMINI_API_KEY)",
  2697. "Google AI Studio API key", "https://aistudio.google.com/app/apikey"),
  2698. "GEMINI_API_KEY": _prov("Google AI Studio API key (alias for GOOGLE_API_KEY)", "Gemini API key",
  2699. "https://aistudio.google.com/app/apikey"),
  2700. "GEMINI_BASE_URL": _base_url("Google AI Studio", "Gemini"),
  2701. "VERTEX_CREDENTIALS_PATH": _prov(
  2702. "Path to a Google Cloud service account JSON for Vertex AI (Gemini). Vertex uses "
  2703. "OAuth2, not a static API key — this points at the credentials Hermes mints short-lived "
  2704. "tokens from. Falls back to GOOGLE_APPLICATION_CREDENTIALS, then to ADC (gcloud auth "
  2705. "application-default login). Set project/region under vertex: in config.yaml.",
  2706. "Vertex service account JSON path (leave empty to use ADC / "
  2707. "GOOGLE_APPLICATION_CREDENTIALS)", "https://cloud.google.com/iam/docs/keys-create-delete",
  2708. password=False),
  2709. "XAI_API_KEY": _prov("xAI API key", "xAI API key", "https://console.x.ai/"),
  2710. "XAI_BASE_URL": _base_url("xAI"),
  2711. "NVIDIA_API_KEY": _prov("NVIDIA NIM API key (build.nvidia.com or local NIM endpoint)",
  2712. "NVIDIA NIM API key", "https://build.nvidia.com/"),
  2713. "NVIDIA_BASE_URL": _prov(
  2714. "NVIDIA NIM base URL override (e.g. http://localhost:8000/v1 for local NIM)",
  2715. "NVIDIA NIM base URL (leave empty for default)", None, password=False),
  2716. "LM_API_KEY": _prov("LM Studio bearer token for auth-enabled local servers",
  2717. "LM Studio API key / bearer token", None),
  2718. "LM_BASE_URL": _base_url("LM Studio"),
  2719. "GLM_API_KEY": _prov("Z.AI / GLM API key (also recognized as ZAI_API_KEY / Z_AI_API_KEY)",
  2720. "Z.AI / GLM API key", "https://z.ai/"),
  2721. "ZAI_API_KEY": _prov("Z.AI API key (alias for GLM_API_KEY)", "Z.AI API key", "https://z.ai/"),
  2722. "Z_AI_API_KEY": _prov("Z.AI API key (alias for GLM_API_KEY)", "Z.AI API key", "https://z.ai/"),
  2723. "GLM_BASE_URL": _base_url("Z.AI / GLM"),
  2724. "KIMI_API_KEY": _prov("Kimi / Moonshot API key", "Kimi API key",
  2725. "https://platform.moonshot.cn/"),
  2726. "KIMI_BASE_URL": _base_url("Kimi / Moonshot", "Kimi"),
  2727. "KIMI_CN_API_KEY": _prov("Kimi / Moonshot China API key", "Kimi (China) API key",
  2728. "https://platform.moonshot.cn/"),
  2729. "STEPFUN_API_KEY": _prov("StepFun Step Plan API key", "StepFun Step Plan API key",
  2730. "https://platform.stepfun.com/"),
  2731. "STEPFUN_BASE_URL": _base_url("StepFun Step Plan"),
  2732. "ARCEEAI_API_KEY": _prov("Arcee AI API key", "Arcee AI API key", "https://chat.arcee.ai/"),
  2733. "ARCEE_BASE_URL": _base_url("Arcee AI", "Arcee"),
  2734. "GMI_API_KEY": _prov("GMI Cloud API key", "GMI Cloud API key", "https://www.gmicloud.ai/"),
  2735. "GMI_BASE_URL": _base_url("GMI Cloud"),
  2736. "ACTUAL_API_KEY": _prov("Actual Computer inference key (ac_...)",
  2737. "Actual Computer inference key", "https://actual.inc/user/keys"),
  2738. "FIREWORKS_API_KEY": _prov("Fireworks AI API key", "Fireworks AI API key",
  2739. "https://app.fireworks.ai/settings/users/api-keys"),
  2740. "MINIMAX_API_KEY": _prov("MiniMax API key (international)", "MiniMax API key",
  2741. "https://www.minimax.io/"),
  2742. "MINIMAX_BASE_URL": _base_url("MiniMax"),
  2743. "MINIMAX_CN_API_KEY": _prov("MiniMax API key (China endpoint)", "MiniMax (China) API key",
  2744. "https://www.minimaxi.com/"),
  2745. "MINIMAX_CN_BASE_URL": _base_url("MiniMax (China)"),
  2746. "DEEPSEEK_API_KEY": _prov("DeepSeek API key for direct DeepSeek access", "DeepSeek API Key",
  2747. "https://platform.deepseek.com/api_keys", advanced=False),
  2748. "DEEPSEEK_BASE_URL": _prov("Custom DeepSeek API base URL (advanced)", "DeepSeek Base URL", "",
  2749. password=False, advanced=False),
  2750. "DASHSCOPE_API_KEY": _prov("Alibaba Cloud DashScope API key (Qwen + multi-provider models)",
  2751. "DashScope API Key", "https://modelstudio.console.alibabacloud.com/", advanced=False),
  2752. "DASHSCOPE_BASE_URL": _prov(
  2753. "Custom DashScope base URL (default: coding-intl OpenAI-compat endpoint)",
  2754. "DashScope Base URL", "", password=False),
  2755. "HERMES_QWEN_BASE_URL": _prov(
  2756. "Qwen Portal base URL override (default: https://portal.qwen.ai/v1)",
  2757. "Qwen Portal base URL (leave empty for default)", None, password=False),
  2758. "OPENCODE_ZEN_API_KEY": _prov("OpenCode Zen API key (pay-as-you-go access to curated models)",
  2759. "OpenCode Zen API key", "https://opencode.ai/auth"),
  2760. "COMMANDCODE_API_KEY": _prov(
  2761. "CommandCode API key (GOAT/Pro/Max/Provider plans — 30+ models via one key)",
  2762. "CommandCode API key", "https://commandcode.ai/studio/"),
  2763. "OPENCODE_ZEN_BASE_URL": _base_url("OpenCode Zen"),
  2764. "OPENCODE_GO_API_KEY": _prov("OpenCode Go API key ($10/month subscription for open models)",
  2765. "OpenCode Go API key", "https://opencode.ai/auth"),
  2766. "OPENCODE_GO_BASE_URL": _base_url("OpenCode Go"),
  2767. "HF_TOKEN": _prov(
  2768. "Hugging Face token for Inference Providers (20+ open models via router.huggingface.co)",
  2769. "Hugging Face Token", "https://huggingface.co/settings/tokens", advanced=False),
  2770. "HF_BASE_URL": _base_url("Hugging Face Inference Providers", "HF"),
  2771. "OLLAMA_API_KEY": _prov("Ollama Cloud API key (ollama.com — cloud-hosted open models)",
  2772. "Ollama Cloud API key", "https://ollama.com/settings"),
  2773. "OLLAMA_BASE_URL": _prov("Ollama Cloud base URL override (default: https://ollama.com/v1)",
  2774. "Ollama base URL (leave empty for default)", None, password=False),
  2775. "XIAOMI_API_KEY": _prov(
  2776. "Xiaomi MiMo API key for MiMo models (mimo-v2.5-pro, mimo-v2.5, mimo-v2-pro, "
  2777. "mimo-v2-omni, mimo-v2-flash)", "Xiaomi MiMo API Key", "https://platform.xiaomimimo.com",
  2778. advanced=False),
  2779. "XIAOMI_BASE_URL": _prov(
  2780. "Xiaomi MiMo base URL override (default: https://api.xiaomimimo.com/v1)",
  2781. "Xiaomi base URL (leave empty for default)", None, password=False),
  2782. "UPSTAGE_API_KEY": _prov("Upstage API key for Solar LLM models", "Upstage API Key",
  2783. "https://console.upstage.ai/api-keys", advanced=False),
  2784. "UPSTAGE_BASE_URL": _prov("Upstage base URL override (default: https://api.upstage.ai/v1)",
  2785. "Upstage base URL (leave empty for default)", None, password=False),
  2786. "AWS_REGION": _prov("AWS region for Bedrock API calls (e.g. us-east-1, eu-central-1)",
  2787. "AWS Region", "https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-regions.html",
  2788. password=False),
  2789. "AWS_PROFILE": _prov("AWS named profile for Bedrock authentication (from ~/.aws/credentials)",
  2790. "AWS Profile", None, password=False),
  2791. "AZURE_FOUNDRY_API_KEY": _prov("Azure Foundry API key for custom Azure endpoints",
  2792. "Azure Foundry API Key", "https://ai.azure.com/", advanced=False),
  2793. "AZURE_FOUNDRY_BASE_URL": _prov(
  2794. "Azure Foundry base URL (set via 'hermes model' for endpoint-specific config)",
  2795. "Azure Foundry base URL", None, password=False),
  2796. # ── Tool API keys ──
  2797. "EXA_API_KEY": _tool("Exa API key for AI-native web search and contents", "Exa API key",
  2798. "https://exa.ai/", tools=["web_search", "web_extract"]),
  2799. "PARALLEL_API_KEY": _tool("Parallel API key for AI-native web search and extract",
  2800. "Parallel API key", "https://parallel.ai/", tools=["web_search", "web_extract"]),
  2801. "FIRECRAWL_API_KEY": _tool("Firecrawl API key for web search and scraping", "Firecrawl API key",
  2802. "https://firecrawl.dev/", tools=["web_search", "web_extract"]),
  2803. "FIRECRAWL_API_URL": _tool("Firecrawl API URL for self-hosted instances (optional)",
  2804. "Firecrawl API URL (leave empty for cloud)", None, password=False, advanced=True),
  2805. "FIRECRAWL_GATEWAY_URL": _tool(
  2806. "Exact Firecrawl tool-gateway origin override for Nous Subscribers only (optional)",
  2807. "Firecrawl gateway URL (leave empty to derive from domain)", None, password=False,
  2808. advanced=True),
  2809. "TOOL_GATEWAY_URL": _tool(
  2810. "Exact shared tool-gateway origin for on-origin vendors and media uploads (optional)",
  2811. "Shared tool-gateway URL (leave empty to derive from domain)", None,
  2812. password=False, advanced=True),
  2813. "CONNECTOR_GATEWAY_URL": _tool(
  2814. "Exact connector-gateway origin for the connectors API (optional)",
  2815. "Connector-gateway URL (leave empty to derive from domain)", None,
  2816. password=False, advanced=True),
  2817. "TOOL_GATEWAY_DOMAIN": _tool(
  2818. "Shared tool-gateway domain suffix for Nous Subscribers only, used to derive vendor "
  2819. "hosts, e.g. nousresearch.com -> firecrawl-gateway.nousresearch.com",
  2820. "Tool-gateway domain suffix", None, password=False, advanced=True),
  2821. "TOOL_GATEWAY_SCHEME": _tool(
  2822. "Shared tool-gateway URL scheme for Nous Subscribers only, used to derive vendor hosts "
  2823. "(`https` by default, set `http` for local gateway testing)", "Tool-gateway URL scheme",
  2824. None, password=False, advanced=True),
  2825. "TOOL_GATEWAY_USER_TOKEN": _tool(
  2826. "Explicit Nous Subscriber access token for tool-gateway requests (optional; otherwise "
  2827. "read from the Hermes auth store)", "Tool-gateway user token", None, advanced=True),
  2828. "TAVILY_API_KEY": _tool(
  2829. "Tavily API key for AI-native web search and extract (optional — keyless works when "
  2830. "Tavily is selected)", "Tavily API key", "https://app.tavily.com/home",
  2831. tools=["web_search", "web_extract"]),
  2832. "PERPLEXITY_API_KEY": _tool(
  2833. "Perplexity API key for the Search API web backend (ranked results + query-relevant page "
  2834. "snippets)", "Perplexity API key", "https://www.perplexity.ai/account/api",
  2835. tools=["web_search", "web_extract"]),
  2836. "KEENABLE_API_KEY": _tool(
  2837. "Keenable API key for fast independent-index web search and page fetch (optional — "
  2838. "keyless free tier works without it)", "Keenable API key", "https://keenable.ai",
  2839. tools=["web_search", "web_extract"]),
  2840. "SEARXNG_URL": _tool("URL of your SearXNG instance for free self-hosted web search",
  2841. "SearXNG URL (e.g. http://localhost:8080)", "https://searxng.github.io/searxng/",
  2842. tools=["web_search"], password=False),
  2843. "BRAVE_SEARCH_API_KEY": _tool(
  2844. "Brave Search API subscription token (free tier: 2,000 queries/mo)",
  2845. "Brave Search subscription token", "https://brave.com/search/api/", tools=["web_search"]),
  2846. "BROWSERBASE_API_KEY": _tool(
  2847. "Browserbase API key for cloud browser (optional — local browser works without this)",
  2848. "Browserbase API key", "https://browserbase.com/",
  2849. tools=["browser_exec"]),
  2850. "BROWSERBASE_PROJECT_ID": _tool(
  2851. "Browserbase project ID (optional — only needed for cloud browser)",
  2852. "Browserbase project ID", "https://browserbase.com/",
  2853. tools=["browser_exec"], password=False),
  2854. "BROWSER_USE_API_KEY": _tool(
  2855. "Browser Use API key for cloud browser (optional — local browser works without this)",
  2856. "Browser Use API key", "https://browser-use.com/",
  2857. tools=["browser_exec"]),
  2858. "FIRECRAWL_BROWSER_TTL": _tool(
  2859. "Firecrawl browser session TTL in seconds (optional, default 300)",
  2860. "Browser session TTL (seconds)", tools=["browser_exec"],
  2861. password=False),
  2862. "FAL_KEY": _tool("FAL API key for image and video generation", "FAL API key", "https://fal.ai/",
  2863. tools=["image_generate", "video_generate"]),
  2864. "KREA_API_KEY": _tool("Krea API key for Krea 3 and Krea 2 image generation",
  2865. "Krea API key", "https://www.krea.ai/settings/api-tokens", tools=["image_generate"]),
  2866. "VOICE_TOOLS_OPENAI_KEY": _tool(
  2867. "OpenAI API key for voice transcription (Whisper) and OpenAI TTS",
  2868. "OpenAI API Key (for Whisper STT + TTS)", "https://platform.openai.com/api-keys",
  2869. tools=["voice_transcription", "openai_tts"]),
  2870. "ELEVENLABS_API_KEY": _tool(
  2871. "ElevenLabs API key for premium text-to-speech voices and Scribe transcription",
  2872. "ElevenLabs API key", "https://elevenlabs.io/",
  2873. tools=["elevenlabs_tts", "voice_transcription"]),
  2874. "MISTRAL_API_KEY": _tool("Mistral API key for Voxtral TTS and transcription (STT)",
  2875. "Mistral API key", "https://console.mistral.ai/"),
  2876. "PORCUPINE_ACCESS_KEY": _tool(
  2877. "Picovoice access key for the Porcupine 'Hey Hermes' wake word engine (optional; "
  2878. "openWakeWord is the free default)", "Picovoice access key",
  2879. "https://console.picovoice.ai/"),
  2880. "GITHUB_TOKEN": _tool("GitHub token for Skills Hub (higher API rate limits, skill publish)",
  2881. "GitHub Token", "https://github.com/settings/tokens"),
  2882. # ── Bundled skills (opt-in) ── category="skill" (not "tool") so the sandbox env blocklist in
  2883. # tools/environments/local.py does NOT rewrite them; skills need them passed through to curl
  2884. # via tools/env_passthrough.py.
  2885. "NOTION_API_KEY": _skill("Notion integration token (used by the Teams meeting pipeline's Notion sink)",
  2886. "Notion API key", "https://www.notion.so/my-integrations"),
  2887. "LINEAR_API_KEY": _skill("Linear personal API key (used by the `linear` skill)",
  2888. "Linear API key", "https://linear.app/settings/account/security"),
  2889. "TENOR_API_KEY": _skill("Tenor API key for GIF search (used by the `gif-search` skill)",
  2890. "Tenor API key", "https://developers.google.com/tenor/guides/quickstart"),
  2891. # ── Honcho ──
  2892. "HONCHO_API_KEY": _tool("Honcho API key for AI-native persistent memory", "Honcho API key",
  2893. "https://app.honcho.dev", tools=["honcho_context"]),
  2894. "HONCHO_BASE_URL": _tool("Base URL for self-hosted Honcho instances (no API key needed)",
  2895. "Honcho base URL (e.g. http://localhost:8000)", password=None),
  2896. # ── Hindsight ──
  2897. "HINDSIGHT_API_KEY": _tool("Hindsight API key for graph-aware persistent memory",
  2898. "Hindsight API key", "https://hindsight.vectorize.io", tools=["hindsight_recall"]),
  2899. "HINDSIGHT_API_URL": _tool(
  2900. "Base URL for the Hindsight API (default: https://api.hindsight.vectorize.io)",
  2901. "Hindsight API URL", password=None, advanced=True),
  2902. # ── Supermemory ──
  2903. "SUPERMEMORY_API_KEY": _tool("Supermemory API key for conversation-scoped persistent memory",
  2904. "Supermemory API key", "https://supermemory.ai", tools=["supermemory_search"]),
  2905. # ── Mem0 ──
  2906. "MEM0_API_KEY": _tool("Mem0 Platform API key for semantic persistent memory", "Mem0 API key",
  2907. "https://app.mem0.ai", tools=["mem0_search"]),
  2908. # ── RetainDB ──
  2909. "RETAINDB_API_KEY": _tool("RetainDB API key for persistent memory", "RetainDB API key",
  2910. "https://retaindb.com", tools=["retaindb_search"]),
  2911. "RETAINDB_BASE_URL": _tool(
  2912. "Base URL for self-hosted RetainDB instances (default: https://api.retaindb.com)",
  2913. "RetainDB base URL", password=None, advanced=True),
  2914. # ── ByteRover ──
  2915. "BRV_API_KEY": _tool("ByteRover API key (optional, for cloud sync — local-first by default)",
  2916. "ByteRover API key", "https://app.byterover.dev", tools=["brv_query"]),
  2917. # ── OpenViking ──
  2918. "OPENVIKING_API_KEY": _tool("OpenViking API key (leave blank for local dev mode)",
  2919. "OpenViking API key", tools=["viking_search"]),
  2920. "OPENVIKING_ENDPOINT": _tool("OpenViking server URL (default: http://127.0.0.1:1933)",
  2921. "OpenViking endpoint", password=None, advanced=True),
  2922. # ── Messaging platforms ──
  2923. "TELEGRAM_BOT_TOKEN": _msg(
  2924. "Complete Telegram bot token created by @BotFather (numeric bot ID followed by a colon "
  2925. "and secret)", "Telegram bot token", "https://t.me/BotFather", password=True),
  2926. "TELEGRAM_ALLOWED_USERS": _msg(
  2927. "Optional comma-separated numeric Telegram user IDs allowed immediately; leave blank to "
  2928. "approve new users through DM pairing", "Allowed Telegram user IDs (comma-separated)",
  2929. "https://t.me/userinfobot"),
  2930. "TELEGRAM_PROXY": _msg(
  2931. "Proxy URL for Telegram connections (overrides HTTPS_PROXY). Supports http://, "
  2932. "https://, socks5://", "Telegram proxy URL (optional)"),
  2933. "DISCORD_BOT_TOKEN": _msg("Discord bot token from Developer Portal", "Discord bot token",
  2934. "https://discord.com/developers/applications", password=True),
  2935. "DISCORD_ALLOWED_USERS": _msg("Comma-separated Discord user IDs allowed to use the bot",
  2936. "Allowed Discord user IDs (comma-separated)", None),
  2937. "DISCORD_REPLY_TO_MODE": _msg(
  2938. "Discord reply threading mode: 'off' (no reply references), 'first' (reply on first "
  2939. "message only, default), 'all' (reply on every chunk)",
  2940. "Discord reply mode (off/first/all)", None),
  2941. "SLACK_BOT_TOKEN": _msg(
  2942. "Slack bot token (xoxb-). Get from OAuth & Permissions after installing your app. "
  2943. "Required scopes: chat:write, app_mentions:read, channels:history, groups:history, "
  2944. "im:history, im:read, im:write, mpim:history, mpim:read, users:read, files:read, "
  2945. "files:write", "Slack Bot Token (xoxb-...)", "https://api.slack.com/apps",
  2946. help=("In your Slack app, add the required bot scopes, install the app to the workspace, "
  2947. "then copy OAuth & Permissions > Bot User OAuth Token."), password=True),
  2948. "SLACK_APP_TOKEN": _msg(
  2949. "Slack app-level token (xapp-) for Socket Mode. Get from Basic Information → App-Level "
  2950. "Tokens. Also ensure Event Subscriptions include: message.im, message.channels, "
  2951. "message.groups, message.mpim, app_mention", "Slack App Token (xapp-...)",
  2952. "https://api.slack.com/apps",
  2953. help=("In your Slack app, enable Socket Mode, then create Basic Information > App-Level "
  2954. "Tokens with the connections:write scope."), password=True),
  2955. "SLACK_ALLOWED_USERS": _msg(
  2956. "Comma-separated Slack member IDs allowed to use Hermes, e.g. U01ABC2DEF3. Without "
  2957. "this, Slack may connect but deny messages by default.", "Allowed Slack member IDs",
  2958. "https://api.slack.com/apps",
  2959. help=("In Slack, open your profile, choose More or the three-dot menu, then Copy member "
  2960. "ID. Add multiple IDs comma-separated.")),
  2961. "MATTERMOST_URL": _msg("Mattermost server URL (e.g. https://mm.example.com)",
  2962. "Mattermost server URL", "https://mattermost.com/deploy/"),
  2963. "MATTERMOST_TOKEN": _msg("Mattermost bot token or personal access token",
  2964. "Mattermost bot token", None, password=True),
  2965. "MATTERMOST_ALLOWED_USERS": _msg("Comma-separated Mattermost user IDs allowed to use the bot",
  2966. "Allowed Mattermost user IDs (comma-separated)", None),
  2967. "MATTERMOST_REQUIRE_MENTION": _msg(
  2968. "Require @mention in Mattermost channels (default: true). Set to false to respond to "
  2969. "all messages.", "Require @mention in channels", None),
  2970. "MATTERMOST_FREE_RESPONSE_CHANNELS": _msg(
  2971. "Comma-separated Mattermost channel IDs where bot responds without @mention",
  2972. "Free-response channel IDs (comma-separated)", None),
  2973. "MATRIX_HOMESERVER": _msg("Matrix homeserver URL (e.g. https://matrix.example.org)",
  2974. "Matrix homeserver URL", "https://matrix.org/ecosystem/servers/"),
  2975. "MATRIX_ACCESS_TOKEN": _msg("Matrix access token (preferred over password login)",
  2976. "Matrix access token", None, password=True),
  2977. "MATRIX_USER_ID": _msg("Matrix user ID (e.g. @hermes:example.org)",
  2978. "Matrix user ID (@user:server)", None),
  2979. "MATRIX_ALLOWED_USERS": _msg(
  2980. "Comma-separated Matrix user IDs allowed to use the bot (@user:server format)",
  2981. "Allowed Matrix user IDs (comma-separated)", None),
  2982. "MATRIX_REQUIRE_MENTION": _msg(
  2983. "Require @mention in Matrix rooms (default: true). Set to false to respond to all "
  2984. "messages.", "Require @mention in rooms (true/false)", None, advanced=True),
  2985. "MATRIX_FREE_RESPONSE_ROOMS": _msg(
  2986. "Comma-separated Matrix room IDs where bot responds without @mention",
  2987. "Free-response room IDs (comma-separated)", None, advanced=True),
  2988. "MATRIX_AUTO_THREAD": _msg("Auto-create threads for messages in Matrix rooms (default: true)",
  2989. "Auto-create threads in rooms (true/false)", None, advanced=True),
  2990. "MATRIX_DM_AUTO_THREAD": _msg("Auto-create threads for DM messages in Matrix (default: false)",
  2991. "Auto-create threads in DMs (true/false)", None, advanced=True),
  2992. "MATRIX_DEVICE_ID": _msg(
  2993. "Stable Matrix device ID for E2EE persistence across restarts (e.g. HERMES_BOT)",
  2994. "Matrix device ID (stable across restarts)", None, advanced=True),
  2995. "MATRIX_RECOVERY_KEY": _msg(
  2996. "Matrix recovery key for cross-signing verification after device key rotation (from "
  2997. "Element: Settings → Security → Recovery Key)", "Matrix recovery key", None, password=True,
  2998. advanced=True),
  2999. "BLUEBUBBLES_SERVER_URL": _msg(
  3000. "BlueBubbles server URL for iMessage integration (e.g. http://192.168.1.10:1234)",
  3001. "BlueBubbles server URL", "https://bluebubbles.app/"),
  3002. "BLUEBUBBLES_PASSWORD": _msg(
  3003. "BlueBubbles server password (from BlueBubbles Server → Settings → API)",
  3004. "BlueBubbles server password", None, password=True),
  3005. "BLUEBUBBLES_ALLOWED_USERS": _msg(
  3006. "Comma-separated iMessage addresses (email or phone) allowed to use the bot",
  3007. "Allowed iMessage addresses (comma-separated)", None),
  3008. "BLUEBUBBLES_ALLOW_ALL_USERS": _msg("Allow all BlueBubbles users without allowlist",
  3009. "Allow All BlueBubbles Users", password=None),
  3010. "QQ_APP_ID": _msg("QQ Bot App ID from QQ Open Platform (q.qq.com)", "QQ App ID",
  3011. "https://q.qq.com", password=None),
  3012. "QQ_CLIENT_SECRET": _msg("QQ Bot Client Secret from QQ Open Platform", "QQ Client Secret",
  3013. password=True),
  3014. "QQ_ALLOWED_USERS": _msg("Comma-separated QQ user IDs allowed to use the bot",
  3015. "QQ Allowed Users", password=None),
  3016. "QQ_GROUP_ALLOWED_USERS": _msg("Comma-separated QQ group IDs allowed to interact with the bot",
  3017. "QQ Group Allowed Users", password=None),
  3018. "QQ_ALLOW_ALL_USERS": _msg("Allow all QQ users without an allowlist (true/false)",
  3019. "Allow All QQ Users", password=None),
  3020. "QQBOT_HOME_CHANNEL": _msg("Default QQ channel/group for cron delivery and notifications",
  3021. "QQ Home Channel", password=None),
  3022. "QQBOT_HOME_CHANNEL_NAME": _msg("Display name for the QQ home channel", "QQ Home Channel Name",
  3023. password=None),
  3024. "QQ_SANDBOX": _msg("Enable QQ sandbox mode for development testing (true/false)",
  3025. "QQ Sandbox Mode", password=None),
  3026. "IRC_SERVER": _msg("IRC server hostname (e.g. irc.libera.chat)", "IRC server", None),
  3027. "IRC_CHANNEL": _msg("IRC channel to join (e.g. #hermes)", "IRC channel", None),
  3028. "IRC_NICKNAME": _msg("Bot nickname on IRC (default: hermes-bot)", "IRC nickname", None),
  3029. "IRC_SERVER_PASSWORD": _msg("IRC server password (if required)", "IRC server password", None,
  3030. password=True, advanced=True),
  3031. "IRC_NICKSERV_PASSWORD": _msg("NickServ password for nick identification", "NickServ password",
  3032. None, password=True, advanced=True),
  3033. "GATEWAY_ALLOW_ALL_USERS": _msg(
  3034. "Allow all users to interact with messaging bots (true/false). Default: false.",
  3035. "Allow all users (true/false)", None, advanced=True),
  3036. "API_SERVER_ENABLED": _msg(
  3037. "Enable the OpenAI-compatible API server (true/false). Allows frontends like Open "
  3038. "WebUI, LobeChat, etc. to connect.", "Enable API server (true/false)", None, advanced=True),
  3039. "API_SERVER_KEY": _msg(
  3040. "Bearer token for API server authentication. Required whenever the API server is "
  3041. "enabled; server refuses to start without it.", "API server auth key", None, password=True,
  3042. advanced=True),
  3043. "API_SERVER_PORT": _msg("Port for the API server (default: 8642).", "API server port", None,
  3044. advanced=True),
  3045. "API_SERVER_HOST": _msg(
  3046. "Host/bind address for the API server (default: 127.0.0.1). API_SERVER_KEY is still "
  3047. "required even on loopback binds.", "API server host", None, advanced=True),
  3048. "API_SERVER_MODEL_NAME": _msg(
  3049. "Model name advertised on /v1/models. Defaults to the profile name (or 'hermes-agent' "
  3050. "for the default profile). Useful for multi-user setups with OpenWebUI.",
  3051. "API server model name", None, advanced=True),
  3052. "GATEWAY_PROXY_URL": _msg(
  3053. "URL of a remote Hermes API server to forward messages to (proxy mode). When set, the "
  3054. "gateway handles platform I/O only — all agent work is delegated to the remote server. "
  3055. "Use for Docker E2EE containers that relay to a host agent. Also configurable via "
  3056. "gateway.proxy_url in config.yaml.",
  3057. "Remote Hermes API server URL (e.g. http://192.168.1.100:8642)", None, advanced=True),
  3058. "GATEWAY_PROXY_KEY": _msg(
  3059. "Bearer token for authenticating with the remote Hermes API server (proxy mode). Must "
  3060. "match the API_SERVER_KEY on the remote host.", "Remote API server auth key", None,
  3061. password=True, advanced=True),
  3062. "WEBHOOK_ENABLED": _msg(
  3063. "Enable the webhook platform adapter for receiving events from GitHub, GitLab, etc.",
  3064. "Enable webhooks (true/false)", None),
  3065. "WEBHOOK_PORT": _msg("Port for the webhook HTTP server (default: 8644).", "Webhook port", None),
  3066. "WEBHOOK_SECRET": _msg(
  3067. "Global HMAC secret for webhook signature validation (overridable per route in "
  3068. "config.yaml).", "Webhook secret", None, password=True),
  3069. # ── Agent settings ── (MESSAGING_CWD is gone: use terminal.cwd in config.yaml, which the
  3070. # gateway bridges to TERMINAL_CWD.)
  3071. "SUDO_PASSWORD": _setting(
  3072. "Sudo password for terminal commands requiring root access; set to an explicit empty "
  3073. "string to try empty without prompting", "Sudo password", None, password=True),
  3074. # HERMES_TOOL_PROGRESS_MODE (deprecated; use display.tool_progress) is intentionally NOT listed:
  3075. # this dict feeds user-facing surfaces (dashboard keys page, setup checklists), so deprecated
  3076. # knobs stay in config._EXTRA_ENV_KEYS only. HERMES_TOOL_PROGRESS is unsupported.
  3077. "HERMES_PREFILL_MESSAGES_FILE": _setting(
  3078. "Path to JSON file with ephemeral prefill messages for few-shot priming",
  3079. "Prefill messages file path", None),
  3080. "HERMES_EPHEMERAL_SYSTEM_PROMPT": _setting(
  3081. "Ephemeral system prompt injected at API-call time (never persisted to sessions)",
  3082. "Ephemeral system prompt", None),
  3083. })