| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550255125522553255425552556255725582559256025612562256325642565256625672568256925702571257225732574257525762577257825792580258125822583258425852586258725882589259025912592259325942595259625972598259926002601260226032604260526062607260826092610261126122613261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640264126422643264426452646264726482649265026512652265326542655265626572658265926602661266226632664266526662667266826692670267126722673267426752676267726782679268026812682268326842685268626872688268926902691269226932694269526962697269826992700270127022703270427052706270727082709271027112712271327142715271627172718271927202721272227232724272527262727272827292730273127322733273427352736273727382739274027412742274327442745274627472748274927502751275227532754275527562757275827592760276127622763276427652766276727682769277027712772277327742775277627772778277927802781278227832784278527862787278827892790279127922793279427952796279727982799280028012802280328042805280628072808280928102811281228132814281528162817281828192820282128222823282428252826282728282829283028312832283328342835283628372838283928402841284228432844284528462847284828492850285128522853285428552856285728582859286028612862286328642865286628672868286928702871287228732874287528762877287828792880288128822883288428852886288728882889289028912892289328942895289628972898289929002901290229032904290529062907290829092910291129122913291429152916291729182919292029212922292329242925292629272928292929302931293229332934293529362937293829392940294129422943294429452946294729482949295029512952295329542955295629572958295929602961296229632964296529662967296829692970297129722973297429752976297729782979298029812982298329842985298629872988298929902991299229932994299529962997299829993000300130023003300430053006300730083009301030113012301330143015301630173018301930203021302230233024302530263027302830293030303130323033303430353036303730383039304030413042304330443045304630473048304930503051305230533054305530563057305830593060306130623063306430653066306730683069307030713072307330743075307630773078307930803081308230833084308530863087308830893090309130923093309430953096309730983099310031013102310331043105310631073108310931103111311231133114311531163117 |
- """Default configuration data for Hermes Agent: DEFAULT_CONFIG and OPTIONAL_ENV_VARS.
- Pure-data leaf module — must not import from hermes_cli.config. Comments are the user-facing
- docs of config.yaml.
- """
- from hermes_cli.config_defaults_auxiliary import _aux
- #: Image every container terminal backend (docker/modal/daytona, the singularity plugin) uses unless the
- #: user pins one. LEGACY_SANDBOX_IMAGES are the plain defaults that preceded the desktop stack
- #: (the 3.14 pin shipped between the two without a migration); a saved config still holding one
- #: is the template copied, and the config migration unsets it, never a user's own pin.
- DEFAULT_SANDBOX_IMAGE = "nousresearch/hermes-sandbox:desktop"
- LEGACY_SANDBOX_IMAGES = ("nikolaik/python-nodejs:python3.11-nodejs20", "nikolaik/python-nodejs:python3.14-nodejs22")
- LEGACY_SANDBOX_IMAGE = LEGACY_SANDBOX_IMAGES[0]
- # Vercel Sandbox managed image (Vercel deprecated its `runtime` presets in Aug 2026).
- DEFAULT_VERCEL_IMAGE = "vercel/sandbox/universal:latest"
- LEGACY_VERCEL_RUNTIME = "node24" # the seeded pre-49 default, never a user choice
- DEFAULT_CONFIG = {
- "model": "",
- "providers": {},
- "fallback_providers": [],
- # min_switch_reset_seconds: opt-in (0 = off). When a rate-limited primary declares a reset
- # sooner than this many seconds, stay on it (the retry backoff rides out the window) instead
- # of switching the turn to a fallback model.
- "fallback": {"min_switch_reset_seconds": 0},
- "credential_pool_strategies": {},
- "toolsets": ["hermes-cli"],
- # journal_mode: SQLite journal mode for every Hermes DB. "wal" default; use "delete" on
- # weak-fsync/shared filesystems where WAL is not crash-safe (macOS virtiofs, NFS, SMB).
- "database": {
- "journal_mode": "wal",
- # WAL sizing pragmas (ints). None = SQLite defaults (autocheckpoint 1000 pages, no limit).
- "wal_autocheckpoint": None,
- "journal_size_limit": None,
- },
- # Server-process fd soft limit (clamped to the hard limit) + glibc arena cap; 0/false/null = off.
- "runtime": {"nofile_soft_limit": 4096, "malloc_arena_max": 4},
- # Global active chat session cap across CLI, TUI/dashboard, and messaging. None/0 = unbounded.
- "max_concurrent_sessions": None,
- # Soft LRU cap on in-memory TUI/desktop/dashboard sessions. Above it the gateway evicts the
- # least-recently-active DETACHED sessions (no live client); reopening re-resumes from disk.
- # 0/null disables.
- "max_live_sessions": 16,
- "session": {
- # Per-terminal `hermes -c`: each CLI session writes a breadcrumb under
- # $HERMES_HOME/terminal-sessions/<terminal-id>, so bare -c/--continue resumes THIS
- # terminal's session (tmux/kitty/wezterm pane, tty). false = resume globally most-recent.
- "terminal_continue": True,
- },
- # Where the TUI/desktop gateway stages session file attachments (uploads, pasted
- # text). "hermes-home" (default) keeps <profile home>/attachments — the dir
- # container backends bind-mount, so @file: refs resolve in the sandbox (#76577).
- # "workspace" opts into <session workspace>/.hermes/attachments: staging lands
- # inside the allowed ref root, so the same profile's agent can always read its
- # own attachments back (#110662). Read per profile from that profile's config;
- # a remote (ssh) workspace keeps the profile home dir either way.
- "attachments": {
- "storage": "hermes-home",
- },
- "agent": {
- # Turn cap. null = unlimited (default; caps caused silent mid-task truncation). Positive int
- # caps; "none"/"unlimited"/"inf"/0/-1 also mean unlimited (resolve_turn_limit).
- "max_turns": None,
- # Optional one-time model-visible checkpoint warning before a finite turn cap is exhausted.
- # null = off; set a ratio strictly between 0 and 1 (for example, 0.75).
- "budget_warning_ratio": None,
- # Wall-clock budget (seconds) per run. null = off. When set: one-time wrap-up notice at 80%
- # elapsed; implicit provider stale timeouts capped to remaining budget. CLI equivalent:
- # `hermes chat --run-budget N`.
- "run_budget_seconds": None,
- # Gateway inactivity timeout (seconds). Only fires when the agent is completely idle — not
- # while calling tools or receiving API responses. 0 = unlimited.
- "gateway_timeout": 1800,
- # Max seconds an alias routing key waits for the active turn holding the same session lease;
- # on expiry the message is rejected with a resend notice. Keep short: Telegram dispatches
- # sequentially, so a waiter delays unrelated topics. Non-positive -> 5s.
- "gateway_turn_lease_timeout": 5,
- # Per-session AIAgent cache in the gateway. Each entry keeps a warm prompt prefix AND the
- # full transcript: too small re-pays uncached prompts, too large fills the heap.
- "agent_cache": {
- "max_size": 128, # LRU entry cap
- "idle_ttl_secs": 3600, # evict agents idle this long
- # Anonymous-RSS budget (MB) above which LRU transcripts are shed (reloaded from disk
- # next turn). "auto" = derive from cgroup memory limit (or total RAM); number =
- # explicit; 0/off = disable the pass.
- "memory_high_mb": "auto",
- # Max sessions shed per pass (teardown bursts can't stall the gateway) and the number of
- # most-recently-used sessions the pass never touches.
- "max_evictions_per_pass": 16,
- "protect_recent": 8,
- },
- # Force-interrupt budget (seconds) once gateway stop()/drain has begun (SIGTERM, and the
- # final phase of in-band restart). 0 = interrupt immediately. Keep under systemd
- # TimeoutStopSec or risk SIGKILL mid-cleanup; for /restart prefer restart_after_turn_timeout
- # so turns finish BEFORE stop().
- "restart_drain_timeout": 0,
- # Floor under the stop()/drain wait (seconds) for cron jobs and api_server runs. Interrupted
- # chat turns resume on the next message, but an interrupted cron run is recorded as a
- # permanent failure and an interrupted /v1 run fails its waiting caller, so neither may
- # inherit restart_drain_timeout's 0 (#82161, #132989). Clamped to the shutdown-watchdog
- # leash minus teardown headroom (~50s unless TimeoutStopSec is raised). 0 = opt out.
- "cron_drain_timeout": 30,
- # In-band restart (/restart, SIGUSR1): refuse new work, then wait up to this many seconds
- # for in-flight agents/cron/api runs to finish before stop(). 0 = enter stop() at once. 30
- # min is a safety valve for wedged agents, not a target; raise for long unattended turns.
- # Default 30 min is a safety valve for wedged agents, not a target latency — an interactive `hermes
- # gateway restart` must never block for hours on a turn that wedged (#79133).
- "restart_after_turn_timeout": 1800,
- # Max seconds a submitted prompt waits for the deferred agent build (MCP discovery, model
- # metadata, skills scan) before failing visibly. The prompt is delivered as soon as the
- # build completes (progress notice past 30s), so this only fires on a hung build. Raise for
- # many slow/unreachable MCP servers.
- # See #63078.
- "build_wait_timeout": 600,
- # Hermes-level retry attempts for API errors (connection drops, timeouts, 5xx) wrapping the
- # whole call; the OpenAI SDK also retries transient errors (max_retries=2). Set 1 for fast
- # failover to fallback providers; raise to tolerate longer provider hiccups.
- "api_max_retries": 3,
- # Once api_max_retries AND the fallback chain are spent on a transient outage (5xx,
- # overloaded/529, connect/read timeouts) with nothing delivered yet, wait and retry this many
- # more cycles (jittered 15/30/60/60/60s; a provider Retry-After wins up to 120s) with a
- # visible "retrying automatically" countdown instead of ending the turn. Esc/interrupt stops
- # the wait; auth/format/billing/policy errors never enter. 0 disables.
- "auto_recovery_cycles": 5,
- # Seconds the Codex/Responses stream may keep reading after its terminal frame so the relay
- # finalizer can run. Relays that never close the SSE socket after response.completed would
- # otherwise wedge the turn until the idle watchdog discards the already-billed response
- # (#103864). 0 skips the drain. Well-behaved endpoints close immediately and never wait this long.
- "stream_drain_timeout": 2.0,
- # Empty-response retry guard. Empty retries re-send the full input at full price; this stops
- # re-billing deterministic empties (unsignaled refusals, zero output tokens) while failing
- # open on ambiguous evidence (missing usage, any tokens, model/provider change).
- "empty_response_guard": {
- "enabled": True, # False = legacy fixed 3 retries unconditionally
- # When one empty attempt's estimated input cost >= this USD, the streak's retry budget
- # drops from 3 to 1. Unknown pricing / missing usage leaves it untouched.
- "cost_threshold_usd": 0.25,
- },
- # Fast mode: "" / "normal" (off), "fast" (always), "auto" (first fast_auto_seconds of every
- # turn), "cold" (first turn of a session only).
- "service_tier": "",
- "fast_auto_seconds": 60,
- # Responses-only `text.verbosity` (never chat_completions): "" = not sent, or low | medium | high.
- "text_verbosity": "",
- "daybreak": False, # opt-in; only catalog-listed Codex models (agent/codex_service_tiers.py)
- # System-prompt guidance telling the model to call tools instead of describing actions.
- # "auto" = gpt/codex models; true/false = force for all models; or a list of model-name
- # substrings (e.g. ["gpt", "codex", "gemini", "qwen"]).
- "tool_use_enforcement": "auto",
- # Execution-discipline prompt block (tool persistence, tools for arithmetic/system facts,
- # read-back after external writes, count reconciliation, literal identifiers,
- # verification-gated completion). Chosen once per session by model name (byte-stable).
- # "auto" = gpt/codex/grok/deepseek/kimi/qwen/glm/minimax/mimo/mistral; true/false = force;
- # or a list of model-name substrings.
- "execution_guidance": "auto",
- # When the model narrates an action ("I'll go check the logs...") but emits no tool call,
- # inject a "continue now, execute the tools" nudge and loop (max 2 nudges/turn). Corrective
- # sibling of tool_use_enforcement. "auto" = codex_responses api_mode only; true = all
- # api_modes (fixes Gemini/Claude "stops after stating intent"); false = never; or a list of
- # model-name substrings.
- "intent_ack_continuation": "auto",
- # Anti-stall guards: (1) identical-call loop breaker appends a notice when the same tool is
- # called 3+ times with identical args AND results (never blocks; pollers like `process`
- # exempt); (2) continue-intent extension of empty-response recovery re-prompts once when the
- # model says it will continue but takes no action. False disables both.
- "stall_guards": True,
- # "Finish the job" prompt block for all models: don't stop at a stub, never fabricate output
- # when the real path is blocked. ~80 cached tokens. False disables.
- "task_completion_guidance": True,
- # Prompt block for all models steering independent tool calls (reads, searches, fetches,
- # read-only commands) into one batched turn; the runtime already runs them concurrently. ~70
- # cached tokens. False disables.
- "parallel_tool_call_guidance": True,
- # Toolchain probe: surfaces Python/pip/uv/PEP-668 state in the system prompt only when
- # something non-default is detected (no pip module, pip/python mismatch, PEP 668 without
- # uv); zero tokens when clean. Skipped for docker/modal/ssh backends (own probe).
- "environment_probe": True,
- # Bot Mode teammate-messaging protocol section (silent unless desktop Bot Mode manages it).
- "bot_mode_protocol": True,
- # Embedder-supplied text appended to the system prompt's environment-hints block, so a host
- # wrapping Hermes (sandbox runner, managed platform) can describe proxy/credential/ mount
- # layout without editing SOUL.md. Env HERMES_ENVIRONMENT_HINT overrides it.
- "environment_hint": "",
- # Coding posture: on interactive coding surfaces (CLI, TUI, desktop, ACP) in a code
- # workspace, add a coding brief + live git/workspace snapshot to the system prompt
- # (agent/coding_context.py). "auto" = prompt-only when interactive AND cwd is a code
- # workspace (toolsets untouched, messaging platforms unaffected); "focus" = auto + collapse
- # toolset to the lean coding set (+ enabled MCP servers) + demote non-coding skill
- # categories to names-only (explicit opt-in); "on" = force everywhere; "off" = disable.
- "coding_context": "auto",
- # Standing operator instructions (string or list) appended to the coding brief as an extra
- # stable system block — project-wide workflow rules, e.g. "Don't run tsc/lint until I
- # approve." Cache-safe: takes effect next session.
- "coding_instructions": "",
- # When verify-on-stop finds edits without fresh verification evidence, add guidance for
- # creative UI work (no broad tsc/lint/test before visual approval) and clean-diff
- # expectations. false = keep the evidence nudge terse.
- "verify_guidance": True,
- # Max consecutive `pre_verify` "continue" nudges per turn (hooks can't trap the loop).
- "max_verify_nudges": 3,
- # Verification closure: after code edits in a workspace, refuse a final answer until fresh
- # verification evidence exists or the agent explains why it can't check (bounded loop,
- # passive ledger). False (default) because the nudges proved more noise than signal; true =
- # force on everywhere; "auto" = on for interactive coding surfaces and programmatic callers,
- # off for messaging surfaces. Doc/markdown/skill-only edits never fire.
- "verify_on_stop": False,
- # Inactivity warning (seconds), once per run before gateway_timeout; no interrupt. 0 = off.
- "gateway_timeout_warning": 900,
- # Max seconds any surface (CLI, TUI/Desktop, messaging gateway) blocks an agent awaiting a
- # clarify-tool reply; then it unblocks with "[user did not respond within Xm]". 0 or less =
- # unlimited. Resolved by tools/clarify_gateway.py::resolve_clarify_timeout (a legacy
- # top-level ``clarify.timeout`` still wins when explicitly set).
- # 1h because users step away and a shorter value evicted the entry mid-think so a later
- # button tap hit a dead entry. Tradeoff: a higher value holds the gateway's running-agent
- # guard longer for a genuinely abandoned prompt — lower it to free the guard sooner. See #32762.
- "clarify_timeout": 3600,
- # "Still working" status interval (seconds); 0 = off. Lower = faster feedback, more noise;
- # 180 catches spinning weak-model runs before users /restart.
- "gateway_notify_interval": 180,
- # Session stall watchdog (seconds): RECOVERY notifier for an in-process AIAgent with an
- # adapter-queued follow-up while its activity clock is stale — NOT a general stall detector
- # (ignores startup restore, build sentinels, leases, debounce, other processes; scan cadence
- # per AIAgent). Notify-only: tells the user to try /new. Distinct from gateway_timeout
- # (kills the turn) and gateway_notify_interval. 0 = disable.
- # See #76354.
- "session_stall_timeout": 300,
- # Transcript-sanitiser heal escalation: after this many pre-send heal passes within a
- # 10-minute window, log one ERROR and queue a ONE-TIME out-of-band notice pointing at /debug
- # share or `hermes doctor` (status channel only; prompt cache untouched). 0 = no escalation
- # (per-window WARNINGs still fire).
- # See #96870.
- "sanitizer_heal_escalation_threshold": 3,
- # Seconds of continuous reconnect failure before a platform gets needs_attention flagged in
- # gateway status (`hermes status` / fleet monitoring). Retries never stop — a signal, not a
- # circuit breaker. 0 = disable.
- "reconnect_attention_after": 7200,
- # Freshness window (seconds) for the auto-continue note. After a crash/restart mid-run the
- # next user message gets "[System note: your previous turn was interrupted...]" prepended;
- # only when the last persisted transcript row is younger than this, so stale markers don't
- # revive an unrelated old task. Covers gateway_timeout (1800) plus slack. 0 = always inject.
- "gateway_auto_continue_freshness": 3600,
- # Max seconds the gateway waits for boot auto-resume turns before releasing the
- # startup-restore inbound gate (all inbound is QUEUED while shut, so one long resumed turn
- # would leave every channel unanswered). On timeout the gate opens and the resume keeps
- # running in the background; duplicate-agent protection is unaffected because the resume
- # slot is claimed synchronously first. 0 = wait forever.
- "gateway_startup_restore_drain_timeout": 30,
- # Max seconds the boot turn-machinery warm-up (run_agent import graph, tool schemas +
- # availability probes, context-file tier) may hold the inbound gate shut, so an early
- # message isn't served with a skeleton system prompt. On timeout the gate opens and warm-up
- # finishes in the background. 0 = disable warm-up (lazy init).
- "gateway_startup_warmup_timeout": 20,
- # Stale-stream ceiling (s) for local providers (Ollama, oMLX, llama-cpp) when the base stale
- # timeout is at its 180s default, so a wedged local server eventually trips the detector
- # instead of hanging forever. Env HERMES_LOCAL_STREAM_STALE_TIMEOUT overrides.
- "local_stream_stale_timeout": 900,
- "stream_max_lifetime": 0, # opt-in whole-stream cap in s, 0 = off (agent/stream_max_lifetime.py)
- # How user-attached images reach the main model (gateway, TUI, CLI /attach). "auto" = native
- # when the model reports supports_vision=True AND auxiliary.vision.provider is not
- # explicitly set, else text; "native" = always attach (non-vision models error at the
- # provider or get a last-chance text fallback); "text" = always pre-analyze with
- # vision_analyze and prepend the description. vision_analyze stays a tool regardless.
- "image_input_mode": "auto",
- "disabled_toolsets": [],
- # Model name (any reasonable spelling) -> effort level; overrides agent.reasoning_effort
- # when the current model matches. Edit in config.yaml (no CLI support: dots in keys).
- "reasoning_overrides": {},
- # Stored reasoning is replayed to every provider that can read it by default. This flag
- # only adds the must-echo " " pad on reasoning-less tool-call turns, which DeepSeek,
- # Kimi/Moonshot and Xiaomi MiMo require (auto-detected by provider name/host). Set
- # `reasoning_echo: true` on a `model:` or `fallback_providers:` entry for a custom gateway
- # proxying one of them. Strict providers (Mistral, Groq, Cerebras) never get the field.
- "reasoning_echo": False,
- # Turn liveness watchdog: a turn with no observable progress for `timeout_s` seconds is
- # logged, force-interrupted so the UI can retry, and its lease stops renewing so stale-turn
- # cleanup can reclaim the session even if the interrupt can't unwind a wedged frame.
- # timeout_s <= 0 disables; poll_s = sampling interval. Invalid values (NaN, Inf,
- # non-positive poll) warn and fall back to defaults. See agent/turn_liveness.py.
- "turn_liveness": {"timeout_s": 600.0, "poll_s": 15.0},
- },
- "terminal": {
- "backend": "local",
- "modal_mode": "auto",
- # Remote-backend connection-class failures (SSH host unreachable, Docker daemon down):
- # "warn" = structured degraded tool result with reason + retry hint; "fail" = raise error +
- # traceback.
- "degraded_mode": "warn",
- "cwd": ".", # Use current directory
- # Root for terminal session temp files (background logs/pid/exit files, code-exec
- # sandboxes). Empty = TMPDIR/TMP/TEMP if set, else HERMES_HOME/cache/terminal (auto-pruned
- # after 72h) — NOT tmpfs /tmp, which is RAM-capped and fills under load. Must be an existing
- # absolute POSIX path; user-set paths are never auto-pruned.
- "temp_dir": "",
- # CSS font-family for the desktop app's xterm.js terminal (e.g. "'CaskaydiaCoveNerdFont',
- # monospace"). Empty = built-in default ("'JetBrains Mono', 'Cascadia Code', 'SF Mono',
- # Menlo, Consolas, monospace"). Lets users use a Nerd Font without patching the app.
- "font_family": "",
- "timeout": 180,
- # Seconds between SIGTERM and escalated SIGKILL for host process trees (browser daemons). 0
- # = SIGTERM only.
- "daemon_term_grace_seconds": 2.0,
- # Max seconds a one-shot CLI run (-q/-Q/-z) lingers for tracked notify_on_complete
- # background processes to finish. The dying parent owns their stdout pipes, so exiting
- # immediately kills the delivery (e.g. Bot Mode handoff replies via message_agent /
- # bot_relay). Plain background processes without notify_on_complete are never waited on. 0
- # disables.
- "oneshot_completion_wait_seconds": 600.0,
- "process_wait_auto_notify": True, # 2 unchanged wait/poll -> notify_on_complete + stop; False = old polling
- # Env vars passed into sandboxed terminal/execute_code (plus skill-declared required_environment_variables).
- "env_passthrough": [],
- "client_env_passthrough": [], # Extra non-secret toolchain names a CLI/TUI client sends for its tools
- # Remote-backend sync-back refuses to extract a downloaded state archive larger than this
- # (bytes); raise it for a ~/.hermes tree that legitimately exceeds 2 GiB.
- "sync_back_max_bytes": 2 * 1024 * 1024 * 1024,
- # HOME for host tool subprocesses: "auto" = host keeps the real OS-user HOME, containers use
- # HERMES_HOME/home; "real" = force real HOME; "profile" = force HERMES_HOME/home when it
- # exists (strict per-profile isolation).
- "home_mode": "auto",
- # Extra files sourced in the login shell when building the per-session env snapshot — for
- # nvm/pyenv/asdf/PATH entries registered by files a bash login shell skips (~/.bashrc,
- # ~/.zshrc, ~/.zprofile). Supports ~ and ${VAR}; missing files skipped. When empty and the
- # shell is bash, ~/.profile, ~/.bash_profile, ~/.bashrc are auto-sourced in that order (see
- # auto_source_bashrc).
- "shell_init_files": [],
- # Source ~/.profile, ~/.bash_profile, ~/.bashrc in the snapshot login shell to capture PATH
- # additions, functions, and aliases that `bash -l -c` misses (bash skips bashrc when
- # non-interactive; Debian/Ubuntu ~/.bashrc short-circuits). ~/.profile and ~/.bash_profile
- # go first because n/nvm/asdf write PATH exports there without an interactivity guard. Turn
- # off if an rc file misbehaves when sourced non-interactively (exits on TTY check).
- "auto_source_bashrc": True,
- # The default sandbox for every container backend: the nikolaik/python-nodejs base
- # (Python 3.13 / Node 26) plus a display stack, so Bot Screen, computer_use and the
- # bot's browser run INSIDE the sandbox and the pane can watch them (see bot_desktop).
- "docker_image": DEFAULT_SANDBOX_IMAGE,
- "docker_forward_env": [],
- # Exact key-value env pairs set inside Docker containers (unlike docker_forward_env, which
- # reads host values) — useful under systemd without the user's shell env. Example:
- # {"SSH_AUTH_SOCK": "/run/user/1000/ssh-agent.sock"}
- "docker_env": {},
- "modal_image": DEFAULT_SANDBOX_IMAGE,
- "daytona_image": DEFAULT_SANDBOX_IMAGE,
- "vercel_image": DEFAULT_VERCEL_IMAGE, # vercel_sandbox backend only: a Vercel-managed or VCR image
- "vercel_runtime": "", # deprecated by Vercel; a legacy runtime pin (node24 | node22 | python3.13) overrides vercel_image
- # Container limits (docker, modal, daytona, vercel_sandbox, container plugin backends; not local/ssh).
- "container_cpu": 1,
- "container_memory": 5120, # MB (default 5GB)
- "container_disk": 51200, # MB (default 50GB)
- "container_persistent": True, # Persist filesystem across sessions
- # Docker volume mounts, "host_path:container_path" (docker -v syntax), e.g.
- # ["/home/user/.hermes/cache/documents:/output"]. For gateway MEDIA delivery, write to
- # /output/... inside Docker and emit the host-visible path in MEDIA:, not the container one.
- "docker_volumes": [],
- "docker_mount_cwd_to_workspace": False, # mount host cwd at /workspace (weakens isolation)
- "docker_network": True, # false = --network=none, no network access from commands
- "docker_extra_args": [], # Extra flags passed verbatim to docker run
- # /dev/shm size for the Docker sandbox. Docker's 64 MB default silently breaks
- # Chromium/Playwright and PyTorch DataLoader workers; tmpfs is lazily allocated so the
- # higher ceiling is free until used. "" or "0" = omit the flag (Docker default).
- "docker_shm_size": "1g",
- # Run the container as the host uid:gid (`--user`) so files written to bind mounts
- # (docker_volumes, persistent workspace, mounted cwd) are owned by you, not root. Off by
- # default for images whose entrypoints must start as root (e.g. the bundled Hermes image,
- # which drops to `hermes` via s6-setuidgid). When on, SETUID/SETGID caps are omitted.
- "docker_run_as_host_user": False,
- # Snap-packaged Docker under AppArmor (Ubuntu cloud images; LP#1908448) refuses to exec
- # anything under `--init` or `--security-opt no-new-privileges` ("operation not
- # permitted"). True drops those two flags; every other hardening stays. See #9730.
- "docker_snap_compat": False,
- # Trusted profiles sharing one Docker container identity; empty = per-profile boundary.
- "docker_shared_container_key": "",
- # SSH: carry exported env vars between commands (cwd always carries). false = every command
- # starts from the login env, profile functions included. Local: TERMINAL_LOCAL_PERSISTENT.
- "persistent_shell": True,
- },
- "web": {
- "backend": "", # shared fallback — applies to both search and extract
- "search_backend": "", # per-capability override for web_search (e.g. "searxng")
- "extract_backend": "", # per-capability override for web_extract (e.g. "native")
- # per-page char budget for web_extract; larger pages truncate, full text kept in cache/web
- "extract_char_limit": 15000,
- # Keyless free-tier ring: with NO web backend configured or keyed, web_search/web_extract
- # rotate round-robin across exa, parallel, firecrawl, keenable public free tiers, failing
- # over on rate limits. Never pre-empts a configured/keyed backend. false = disable.
- "keyless_fallback": True,
- # One-shot rescue: when the chosen/keyed backend fails a call, THAT call retries once on the
- # keyless ring; the next call tries the chosen backend again (no sticky failover). Off when
- # keyless_fallback is false.
- "keyless_rescue": True,
- # Per-vendor tier for vendors with both a keyless free endpoint and a keyed paid path (exa,
- # parallel, firecrawl, keenable; tavily is opt-in keyless via `hermes tools`, not a ring
- # member). Set by the `hermes tools` picker. "free" = always anonymous endpoint even with a
- # key; "paid" = always keyed (missing key = error; vendor excluded from the ring); unset =
- # keyed when the key is present, else the ring.
- "provider_tier": {},
- # TTL caching for web_search + web_extract: repeat searches (same query + provider) within
- # the TTL come from an in-process memo; repeat extracts from the cache/web store. Concurrent
- # identical searches coalesce into one vendor request. Only successes cached.
- "cache_enabled": True,
- "cache_ttl_minutes": 20,
- # Hosts always fetched live, never from the extract cache (staging deploys, tunnel URLs,
- # preview builds). Entries match exactly, as "*.wildcard", or as a domain suffix
- # ("mysite.dev" also covers "preview.mysite.dev"). localhost/private IPs always exempt.
- "cache_exempt_hosts": [],
- },
- "browser": {
- # REMOVAL NOTE: `backend` (built-in browser_* tools vs browser_exec), `snapshot_threshold`,
- # `record_sessions`, `allow_unsafe_evaluate` and `restrict_evaluate` left with the built-in
- # browser tools; browser_exec is the only core browser. Config v52 drops `backend` (an `off`
- # gets a one-time notice) and copies AGENT_BROWSER_* from .env to the keys below; other
- # user values stay untouched.
- "inactivity_timeout": 120,
- # Seconds a local Chromium launch may take to open its DevTools port; a launch always waits
- # at least 120 s (a cold first start unpacks the profile).
- "command_timeout": 30,
- # headed: visible Chromium window (local); skips per-turn cleanup, idle reaper still applies
- "headed": False,
- "allow_private_urls": False, # legacy security.allow_private_urls; local/sidecar Chromium ignore it
- # Local browser engine. "auto" = Chromium; "lightpanda" = `lightpanda serve` per session
- # (faster navigation, no screenshots); "chrome" is read as "auto". Ignored while a cloud
- # provider, cdp_url or use_real_profile is active.
- "engine": "auto",
- # Chromium binary for local sessions. "" = pm's chromium (`hermes pm install chromium`), the
- # Docker image's build, else a system chromium where pm builds none (Termux).
- "executable_path": "",
- # Persistent Chromium profile directory shared by local sessions; "" = a fresh throwaway
- # profile per session.
- "user_data_dir": "",
- "chromium_args": [], # extra Chromium flags for local sessions, e.g. ["--lang=de"]
- # Cloud provider: LAN/localhost URLs open in a local Chromium (ignores allow_private_urls; False refuses)
- "auto_local_for_private_urls": True,
- "cdp_url": "", # persistent CDP endpoint for attaching to an existing Chromium/Chrome
- # Consent to browse with the user's REAL logins locally: runs on a Hermes-managed SNAPSHOT
- # of the ACTIVE default-Chromium profile (Local State -> profile.last_used; cookies, logins,
- # prefs copied and re-synced per fresh session) driven by Hermes' packaged Chromium. The
- # snapshot dir sidesteps Chrome 136+'s default-profile debugging block and never contends
- # with the running browser. Turning off deletes ~/.hermes/browser-profile/ so credentials
- # don't outlive consent. Chromium-family only; a profile that can't be copied (Firefox default,
- # Windows browser holding its cookies) gives a fresh, signed-out browser plus a note saying why.
- # Also gates the browser_exec `local` arg (real-profile session under a cloud backend). Desktop Settings -> Browser.
- "use_real_profile": False,
- # Windows only: a running Chrome/Edge/Brave locks its cookie DB (the last snapshot is reused;
- # with none yet, a fresh browser runs). When on, the agent ASKS first; on approval it runs
- # `hermes browser close-profile` (kills that profile's browser tree, unsaved tabs lost) so a
- # new session can copy it; no auto-kill. No effect on macOS/Linux, where a running
- # browser only locks the password/autofill DBs, which are skipped (cookies still copy).
- "real_profile_autoclose": False,
- # Pin WHICH source profile directory is snapshotted for real-profile browsing (e.g. "Profile
- # 2"). Empty = browser's last-used profile, which on multi-profile machines can hand the
- # agent the wrong identity. A pin naming a missing directory never falls back to another
- # profile: the session gets a fresh browser without the user's logins.
- "real_profile_pin": "",
- # CDP supervisor: dialog + frame detection over a persistent WebSocket; active only with a
- # CDP-capable backend (Browserbase, or local Chrome via /browser connect). See
- # website/docs/developer-guide/browser-supervisor.md.
- "dialog_policy": "must_respond", # must_respond | auto_dismiss | auto_accept
- "dialog_timeout_s": 300, # safety auto-dismiss after N seconds under must_respond
- # Read by the `camofox` catalog plugin (Camofox left core). An empty free-form mapping, so
- # `hermes config set browser.camofox.<key>` is accepted and user values are never stripped.
- "camofox": {},
- },
- # Stale git worktree lifecycle (`hermes -w`, `/worktree new`, subagent isolation, Desktop). The
- # sweep runs at `hermes -w` startup and every 6h from the cron ticker over every repo Hermes made
- # a worktree in. Trees idle past their tier (hermes-*/subagent-* 24h, named 72h) that are clean
- # and merged are removed; dirty or unpushed ones are archived to refs/hermes/archive/<tree>
- # first (`hermes worktree restore <name>`). Live trees and Kanban t_<hex> trees are never touched.
- "worktrees": {
- "archive_dirty": True, # false = never remove a dirty/unpushed tree (the pre-archive behaviour)
- # Untracked files larger than this (MB) are not archived, so a tree holding one is kept.
- "archive_max_file_mb": 50,
- # The sweep deletes archive refs older than this many days. 0 keeps them forever.
- "archive_retention_days": 30,
- # Optional size budget (GB) for idle trees: past it the oldest idle trees are archived and
- # removed first. Live, young and Kanban trees are never counted or touched. 0 = off.
- "max_total_gb": 0,
- "install_state_retention_days": 14, # installs/<key> of a missing checkout, unused this long, goes; 0 = never
- },
- # Filesystem checkpoints: snapshot the working directory once per turn (on the first
- # write_file/patch call); restore with /rollback. Opt-in via `hermes chat --checkpoints` or
- # enabled=True (most users never use /rollback). Single shared shadow store with real pruning.
- "checkpoints": {
- "enabled": False,
- # Max checkpoints per working directory; enforced by ref rewrite + GC of older commits.
- "max_snapshots": 20,
- # Hard ceiling on total ~/.hermes/checkpoints/ size (MB); the oldest checkpoint per project
- # is dropped round-robin until under the cap. 0 disables.
- "max_total_size_mb": 500,
- # Skip files larger than this (MB) when staging (datasets, model weights). 0 = no filter.
- "max_file_size_mb": 10,
- # Background sweep (CLI helper thread / gateway housekeeping tick, at most once per
- # min_interval_hours; never on the startup path — its git gc can block for tens of seconds):
- # deletes projects whose last_touch is older than retention_days, GCs the shared store when
- # refs moved, enforces max_total_size_mb, deletes legacy-* archives older than retention_days.
- # It NEVER deletes orphans (workdir missing on
- # disk) — a missing workdir may just be an unmounted volume/VPN, and an unattended sweep
- # must not guess. Orphans: `hermes checkpoints prune` (`--keep-orphans` to skip).
- "auto_prune": True,
- "retention_days": 7,
- "min_interval_hours": 24,
- },
- # Hard cap (chars) for one auto-loaded context file (SOUL.md, AGENTS.md, CLAUDE.md, .hermes.md,
- # .cursorrules) before head/tail truncation. null = scale with the model's context window (floor
- # 20K, ceiling 500K); a positive int pins a fixed cap. Separate from read_file limits.
- "context_file_max_chars": None,
- # Seconds to wait for a single context file read before skipping it with a warning. Guards startup
- # against network-backed filesystems (iCloud Drive, OneDrive, NFS) that can block a cold read.
- "context_file_read_timeout": 5.0,
- # Max chars per read_file call; larger reads are rejected with offset+limit guidance. 100K chars
- # ≈ 25–35K tokens.
- "file_read_max_chars": 100_000,
- # Seconds the first agent build waits for background MCP discovery before snapshotting its tool
- # list. Returns the instant discovery completes (no MCP servers → ~0s); the bound only bites
- # when a server is still connecting. Turn-1 latency knob only: a server that misses it is picked
- # up by the between-turns refresh (agent/turn_context.py), so keep it small — a dead server adds
- # this much to first-response latency.
- "mcp_discovery_timeout": 1.5,
- # Same bound for single-query mode (``hermes -q/-z``). With only ONE turn there is no
- # between-turns refresh, so a server that misses the window is invisible for the whole session;
- # the larger bound lets slow cold-start servers (npx, uvx, remote HTTP) land. Reachable servers
- # still only wait their real handshake time.
- "mcp_single_query_discovery_timeout": 15.0,
- "mcp": { # MCP runtime behavior (distinct from mcp_servers: definitions and auxiliary.mcp).
- # Auto-reload MCP connections when config.yaml's mcp_servers changes (CLI watcher). Every
- # reload rebuilds the tool surface and INVALIDATES the provider prompt cache (next message
- # re-sends the full prefix) — costly on long-context models. When false the watcher still
- # detects the change and prints /reload-mcp guidance.
- "auto_reload_on_config_change": True,
- # Max MCP servers connected (and their stdio child trees spawned) at once per discovery
- # pass — at boot, on /reload-mcp and on the config watcher's reconcile. Unbounded, a config
- # with N servers spawns N process trees in the same instant (RAM/CPU spike, 429 fan-out on
- # multi-profile fleets). 0 = unlimited.
- "discovery_concurrency": 4,
- },
- # Tool-output truncation. max_bytes: terminal_tool output cap in chars (head+tail kept; 50_000 ≈
- # 12-15K tokens). max_lines: max `limit` one read_file call may request before clamping.
- # max_line_length: per-line cap in read_file's line-numbered view (chars).
- "tool_output": {"max_bytes": 50000, "max_lines": 2000, "max_line_length": 2000},
- # Tool loop guardrails nudge models that repeat failed/non-progressing tool calls. Soft warnings
- # are always on; hard stops are opt-in so interactive sessions keep flowing.
- "tool_loop_guardrails": {
- "warnings_enabled": True,
- "hard_stop_enabled": False,
- # Unattended gateway/cron platforms hard-stop by default (nobody can /stop a model that
- # ignores warnings); interactive cli/tui/desktop/acp stay warning-only.
- "non_interactive_hard_stop_enabled": True,
- "warn_after": {"exact_failure": 2, "same_tool_failure": 3, "idempotent_no_progress": 2},
- "hard_stop_after": {
- "exact_failure": 5, "same_tool_failure": 8, "idempotent_no_progress": 5
- },
- # Per-turn hard ceilings for runaway-prone tools; counters reset every turn, always on
- # regardless of the thresholds above. Dozens of searches/subagents in ONE turn is already
- # pathological, hence low defaults. 0 = unlimited.
- "loop_caps": {
- "max_web_searches": 50, # web_search calls per turn
- "max_subagents": 50, # subagents spawned per turn
- },
- },
- "compression": {
- "enabled": True,
- # checkpoint_required: fail closed before lossy compaction unless an active memory provider
- # confirms checkpoint API compatibility and completes the checkpoint.
- "checkpoint_required": False,
- # progress_notices: when True, routine compression progress statuses (compacting/
- # preflight/pre-API/idle/retry) reach chat gateways instead of being filtered as noise.
- # Failure notices and manual /compress feedback are always visible.
- "progress_notices": False,
- # threshold: compress when context usage exceeds this ratio. Models with windows below 512K
- # are floored at 0.75 (raise-only) so compaction doesn't fire with half the window free; set
- # above 0.75 to override the floor.
- "threshold": 0.50,
- # threshold_tokens: optional absolute token cap — when set, compression triggers at the
- # lower of the ratio threshold and this count. Clamped to the model's context length.
- # Off by default: no single count suits windows from 64K to 1M+, so the ratio decides.
- "threshold_tokens": None,
- # "progress_notices": False, # opt-in (#52995): when True, routine compression
- "target_ratio": 0.20, # fraction of threshold to preserve as recent tail
- # tail_mode: "lean" = clamped 2.5%-of-window tail (10K floor / 25K cap) plus chunked
- # digests, anchor index, verbatim user messages and session_search pointers in the summary
- # (~3x fewer retained tokens; a few extra summarizer calls at the boundary). "legacy" =
- # 0.20×threshold verbatim tail (100-240K tokens on big windows).
- "tail_mode": "lean",
- # protect_last_n: minimum recent messages kept uncompressed, honoured up to a small count
- # floor; the verbatim tail is otherwise token-bounded and never above 20% of the window.
- "protect_last_n": 20,
- # min_tail_user_messages: REAL (actionable) user messages guaranteed to survive in the tail.
- # 1 = single last-user anchor; raise (e.g. 3) when bulky tool outputs fill the tail budget.
- "min_tail_user_messages": 1,
- # max_attempts: retry rounds before a turn gives up with "max compression attempts reached".
- # Raise (e.g. 6) for tool-schema-heavy sessions. Validated >= 1, cap 10.
- "max_attempts": 3,
- # proactive_prune_tokens: opt-in trigger (tokens) for the deterministic no-LLM tool-result
- # prune, independent of `threshold` (which rarely fires on large windows, so old tool output
- # is re-sent every turn); e.g. 48000 reclaims early. 0 = off. Tail protected by
- # `protect_last_n`. Built-in compressor only. Each committed prune rewrites sent history and
- # breaks the prompt-cache prefix — the min_reclaim gate below keeps those breaks episodic.
- "proactive_prune_tokens": 0,
- # Prune's summarize pass only touches tool results larger than this (chars); clamped >= 200
- # so a generated summary can't be re-summarized.
- "proactive_prune_min_result_chars": 8000,
- # A prune only commits when it reclaims at least this many tokens, then waits for a
- # trigger-sized runway to regrow before rearming. 0 = no minimum-savings gate.
- "proactive_prune_min_reclaim_tokens": 4096,
- # micro_compact: opt-in — after each turn fold the oldest un-absorbed exchange into a
- # rolling summary, amortizing compression cost. Off by default because every pass rewrites
- # sent history and breaks the prompt-cache prefix EVERY turn; enable only if the amortized
- # stall beats the cached-prefix discount. See website/docs/developer-guide/micro-compaction.md.
- "micro_compact": False,
- # Cadence: run a pass every Nth completed turn (1 = one cache break per turn, 5 = a fifth of
- # the breaks). Clamped >= 1; ignored unless micro_compact is true.
- "micro_compact_every_n_turns": 1,
- # Once the rolling summary exceeds this many tokens, the next pass re-summarizes it.
- "micro_compact_defrag_threshold_tokens": 2000,
- # Gateway session-hygiene force-compress threshold, by message count.
- "hygiene_hard_message_limit": 5000,
- # Max seconds the gateway waits for pre-agent hygiene compression WITHOUT forward progress.
- # Inactivity budget: a slow model still streaming tokens extends the wait.
- "hygiene_timeout_seconds": 30,
- # Absolute cap on the hygiene wait even while tokens are moving (bounds a trickle stream).
- # Clamped >= hygiene_timeout_seconds.
- "hygiene_total_ceiling_seconds": 600,
- "hygiene_failure_cooldown_seconds": 300, # skip repeated failed hygiene attempts
- # Max seconds an ARRIVING user turn is held while a streaming hygiene summary finishes;
- # bounds user-visible latency (keep under chat idle timeouts, Telegram ~30s). On expiry the
- # turn proceeds uncompressed; the detached worker keeps its watermark-fenced commit, so the
- # summary is adopted at the next safe boundary.
- "hygiene_max_turn_hold_seconds": 10,
- # Inactivity budget for in-agent compress_context (loop, /compress, preflight); same
- # progress-aware semantics as hygiene_timeout_seconds. 0 = disable the owned wrapper
- # (callers passing commit_fence, e.g. gateway hygiene, never use it). Floored at the auxiliary
- # compression request timeout (auxiliary.compression.timeout, min 300s): the host never judges
- # silence before the summary request itself would time out.
- "context_timeout_seconds": 120,
- # Absolute cap on the *pre-commit* compress_context wait (summary/stream phase) even while
- # tokens move. Clamped >= context_timeout_seconds when that is > 0. A started SessionDB
- # commit is never abandoned: past the ceiling it is logged (WARNING, then ERROR) and
- # surfaced on the warning channel while the host keeps waiting.
- "context_total_ceiling_seconds": 600,
- # Non-system head messages always kept verbatim, in ADDITION to the (always protected)
- # system prompt. 0 = pin nothing but system prompt + summary + tail.
- "protect_first_n": 3,
- # When True, auto-compression whose summary fails (aux error / non-JSON / timeout) aborts
- # instead of dropping the middle with a "summary unavailable" placeholder; the session
- # freezes at its size until /compress (bypasses the cooldown) or /new.
- "abort_on_summary_failure": False,
- # (Historical key name.) When True, gpt-5.4/5.5/5.6 and gpt-6 Astra (any slug containing
- # "astra" without "900k") on the ChatGPT Codex OAuth route raise their compaction trigger to
- # 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
- # OpenAI direct, OpenRouter or another relay keep the global value.
- "codex_gpt55_autoraise": True,
- # Show the one-time autoraise banner; False keeps the autoraise, hides the notice.
- "codex_gpt55_autoraise_notice": True,
- # Codex app-server thread compaction mode. The codex agent owns the thread context, so
- # Hermes' summarizer cannot shrink it. native = codex decides; hermes = Hermes' threshold
- # triggers thread/compact/start; off = never auto-trigger.
- "codex_app_server_auto": "native",
- # Opt in to OpenAI server-side compaction on the Responses API. Only gpt-5.6-family on
- # api.openai.com or the Codex backend; local compression stays as fallback.
- "codex_responses_native": False,
- # Absolute server compaction trigger (input tokens). None follows the local trigger with a
- # safety margin; explicit values only clamp downward so the server goes first.
- "codex_responses_compact_threshold": None,
- # in_place: compaction rewrites the message list and system prompt WITHOUT rotating the
- # session id (no parent_session_id chain, no `name #N` renumbering), avoiding the session-rotation
- # bug cluster. Pre-compaction turns are soft-archived under the same id (active=0, compacted=1) —
- # still session_search-able. False = legacy rotating-compaction path.
- "in_place": True,
- # Per-model threshold overrides: keys substring-match the model name (longest wins), values
- # replace the global `threshold`, e.g. {"glm-5.2": 0.40}. Prefix a key with "<provider>:" to
- # scope it to one route ({"openai-codex:astra": 0.85} leaves Astra on OpenRouter/Nous at the
- # global value). The <512K floor (0.75) still applies raise-only on top.
- "model_thresholds": {},
- # Opt-in idle compaction (0 = off): a session resuming after this many idle seconds compacts up
- # front, before the first reply. Time-based complement to `threshold`; skipped when already at/below
- # threshold × target_ratio; honors the same cooldown/anti-thrash/lock guards. Example: 1800 = 30 min.
- "idle_compact_after_seconds": 0,
- # 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.
- "prepare_ahead": False,
- },
- # Anthropic prompt caching (Claude via OpenRouter or native API). cache_ttl: "5m" | "1h" | "auto"
- # (auto = 1h for human-paced sessions — cli/tui/desktop/messaging — and 5m for subagent, cron,
- # oneshot, webhook, kanban, api, tool, batch); other non-falsy values are ignored; falsy (false, null, "off",
- # "disabled", "no", "none") disables caching.
- "prompt_caching": {"cache_ttl": "5m"},
- # OpenRouter settings. response_cache: X-OpenRouter-Cache header — identical requests return
- # cached responses at zero billing; independent of Anthropic prompt caching. response_cache_ttl:
- # seconds (1-86400), only used when response_cache is on. min_coding_score (0.0-1.0):
- # pareto-code router knob, applied only when model.model is "openrouter/pareto-code"; higher =
- # stronger/pricier coders, 0.65 = mid-tier, "" = let OpenRouter pick the strongest. Docs:
- # openrouter.ai/docs/guides/routing/routers/pareto-router
- "openrouter": {"response_cache": True, "response_cache_ttl": 300, "min_coding_score": 0.65},
- "bedrock": { # AWS Bedrock; only used when model.provider is "bedrock".
- "region": "", # empty = AWS_REGION env var → us-east-1
- "discovery": {
- "enabled": True, # auto-discover models via ListFoundationModels
- "provider_filter": [], # restrict to these providers, e.g. ["anthropic", "amazon"]
- "refresh_interval": 3600, # cache discovery results (seconds)
- },
- # Bedrock Guardrails: create one in the console, then set ID and version.
- # https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html
- "guardrail": {
- "guardrail_identifier": "", # e.g. "abc123def456"
- "guardrail_version": "", # e.g. "1" or "DRAFT"
- "stream_processing_mode": "async", # "sync" | "async"
- "trace": "disabled", # "enabled" | "disabled" | "enabled_full"
- },
- },
- # Auxiliary model config — provider/model per side task. provider "auto" = auto-detect;
- # empty model = provider's default aux model; all tasks fall back to
- # openrouter:google/gemini-3-flash-preview when the configured provider is unavailable.
- # extra_body is forwarded verbatim as request body fields for that task, e.g. OpenRouter
- # routing prefs / Pareto Code floor:
- # auxiliary:
- # compression:
- # extra_body:
- # provider: {order: [anthropic, google], sort: throughput} # or price | latency
- # plugins: [{id: pareto-router, min_coding_score: 0.5}]
- # Each task is independent — main-agent provider_routing and openrouter.min_coding_score
- # do NOT propagate to aux calls by design.
- "auxiliary": {
- # Same-provider retries for a transient blip (reset/timeout/5xx/408) on ANY aux call before
- # falling back; clamped [0,6]. Matters for pinned calls (MoA advisors) where provider
- # fallback is not meaningful recovery.
- "transient_retries": 2,
- # When true, the auto-chain's OpenRouter step is skipped unless the fallback model ends in
- # ":free" — a PAID lane is never used for background aux traffic even with
- # OPENROUTER_API_KEY set.
- "free_only": False,
- # Override the auto-chain's OpenRouter fallback model (default google/gemini-3.6-flash,
- # PAID). Pair e.g. "nvidia/nemotron-3-ultra-550b-a55b:free" with free_only: true. A one-time
- # WARNING is logged whenever a non-":free" model is engaged.
- "openrouter_model": "",
- # Endpoints that reject NON-streaming chat (HTTP 400): aux calls are sent with stream=True
- # and aggregated. Case-insensitive URL substrings; some vendor endpoints are always
- # stream-only.
- "stream_only_base_urls": [],
- # Per-task blocks share one shape (_aux): provider "auto" = inherit the main model; base_url
- # overrides provider; api_key falls back to OPENAI_API_KEY; reasoning_effort:
- # none|minimal|low|medium|high|xhigh|max|ultra ("" = provider default); extra_body =
- # OpenAI-compatible request fields. Vision: download_timeout = image HTTP download (s).
- "vision": _aux(120, download_timeout=30),
- # web_extract, session_search, skills_hub: no aux LLM any more, leftover blocks are ignored.
- # Compression: raise timeout for local models. no_progress_timeout: seconds a streamed call
- # goes without a substantive chunk before it fails fast into retry/fallback; None = built-in
- # 60s default. Independent of "timeout" (the overall request budget). See #108104.
- "compression": _aux(120, no_progress_timeout=None),
- "approval": _aux(30), # classifier — a fast/cheap model is recommended
- # /review reviewer: a full subagent on the async delegation rail, credentials resolved like
- # delegation.provider pins. "auto" + "" = main agent's model. api_mode forces transport:
- # chat_completions | anthropic_messages | codex_responses.
- "review": {"provider": "auto", "model": "", "base_url": "", "api_key": "", "api_mode": ""},
- "mcp": _aux(30),
- # prefer_fast_model opts in to the provider fast tier; auto otherwise = main model.
- "title_generation": {
- "enabled": True,
- "model_upgrade_enabled": True, # False = keep the instant derived title, never call a model
- # session_search no longer uses an aux LLM (#27590); leftover auxiliary.session_search is ignored.
- "provider": "auto",
- "model": "",
- "prefer_fast_model": False,
- "base_url": "",
- "api_key": "",
- "timeout": 30,
- "extra_body": {},
- "reasoning_effort": "",
- "language": "",
- },
- "memory_query_rewrite": _aux(8, reasoning_effort=False),
- "tts_audio_tags": _aux(30),
- "voice_chat": {**_aux(120), "reasoning_effort": "none"}, # agent/voice_turn_route.py; off = lowest valid
- # Kanban: triage_specifier expands a Triage one-liner into a spec; kanban_decomposer a JSON graph.
- "triage_specifier": _aux(120),
- "kanban_decomposer": _aux(180),
- "profile_describer": _aux(60), # 1-2 sentence profile blurb; short, cheap
- "goal_judge": _aux(60), # /goal satisfaction + contract drafting; JSON calls
- "group_router": _aux(20), # Group Chat routing "auto": who answers; fast/cheap model OK
- # Curator skill-usage review can take minutes on reasoning models (umbrellas over hundreds
- # of skills); route cheaper via `hermes model` → auxiliary → Curator.
- "curator": _aux(600),
- "monitor": _aux(60), # important-mail 0-10 scorer; high-volume, small model fine
- # Post-turn self-improvement fork (save memory / patch skill). "auto" = main model replaying
- # the full conversation (warm cache); other models replay a compact digest (~3-5x cheaper).
- # enabled=false skips auto spawns (/refine still works). An explicit max_input_tokens caps
- # the SUM of replayed input tokens over the review loop (iterations capped at 16); the loop
- # stops before crossing it. When unset, the runtime derives a budget from the active model
- # context window. <= 0 = unlimited.
- # reasoning_effort is IGNORED while the review stays on the main model: the fork inherits the
- # conversation's reasoning config verbatim so its request bytes keep the parent's warm
- # prompt-cache prefix (#30532). Set provider/model below to route the review to another model
- # if you want a different effort level; a one-time warning says so when the key is set.
- "background_review": {"enabled": True, **_aux(120)},
- # No reasoning_effort on MoA blocks by design — configured PER SLOT in the preset
- # (moa.presets.<name>.reference_models[].reasoning_effort / aggregator.reasoning_effort).
- "moa_reference": _aux(900, reasoning_effort=False),
- "moa_aggregator": _aux(900, reasoning_effort=False),
- },
- "display": {
- "compact": False,
- "personality": "",
- "resume_display": "full",
- # Recap tuning for /resume and startup resume.
- "resume_exchanges": 10, # max user+assistant pairs to show
- "resume_max_user_chars": 300, # truncate user message text
- "resume_max_assistant_chars": 200, # truncate non-last assistant text
- "resume_max_assistant_lines": 3, # truncate non-last assistant lines
- # Skip tool-call-only assistant entries in the recap so it isn't dominated by `[2 tool
- # calls: ...]` lines; False shows them inline.
- "resume_skip_tool_only": True,
- "busy_input_mode": "interrupt", # interrupt | queue | steer
- # steer mode: false hides only the "Steered into current run" bubble; steering itself still
- # happens.
- "busy_steer_ack_enabled": True,
- # Classic CLI multiline beyond Alt+Enter: Ctrl+J newline, trailing backslash+Enter
- # continues, Shift+Enter reported distinctly. False restores the c-j submit fallback for
- # POSIX PTYs whose plain Enter arrives as LF.
- "cli_multiline_shortcuts": True,
- # `hermes`/`hermes chat` launches "cli" (prompt_toolkit REPL) | "tui" (Ink); --cli, --tui, HERMES_TUI=1 win.
- # cli_layout = the REPL's look: "modern" (glyph rows, status under the composer) | "classic" (boxed panels).
- "interface": "cli", "cli_layout": "modern",
- # Native TUI uses the terminal's primary buffer and scrollback instead of the custom
- # alternate-screen viewport. Flags win: `--native` / `--tui-native` and `--cli`.
- "tui_native": False,
- # `hermes --tui` auto-resumes the most recent human-facing session (like `hermes -c`).
- # HERMES_TUI_RESUME=<id> always wins.
- "tui_auto_resume_recent": False,
- # Desktop reopens the last chat/page on cold start (also in Settings → Appearance).
- "resume_last_session": True,
- # One-time TUI hint ("subagents working · /agents to watch live") on first delegation.
- "tui_agents_nudge": True,
- "bell_on_complete": False,
- "bell_on_prompt": False, # bell when a blocking prompt opens (clarify/approval/sudo)
- # Stream reasoning live before the response; otherwise thinking models show only a spinner
- # for tens of seconds.
- "show_reasoning": True,
- # Post-response "Reasoning" recap collapses to 10 lines; true prints it all (live streaming
- # is always full).
- "reasoning_full": False,
- # Background self-improvement notices in chat: "off" (review still runs) | "on" (generic "💾
- # Memory updated") | "verbose" (content preview). Per-platform via
- # display.platforms.<platform>.memory_notifications.
- "memory_notifications": "on",
- # Gateway notices when a terminal(background=true) process finishes: "concise" (one line;
- # failures append an output tail) | "all" (running updates + final raw output) | "result"
- # (final raw only) | "error" (raw only on non-zero exit) | "off".
- "background_process_notifications": "concise",
- "streaming": False,
- "timestamps": False, # message timestamps (CLI labels, TUI rows, desktop transcript)
- "timestamp_format": "%H:%M", # strftime format, e.g. "%b-%d %H:%M"
- "final_response_markdown": "strip", # render | strip | raw
- # Preserve recent classic-CLI output across Ctrl+L, /redraw and resize clears; disable if an
- # emulator misbehaves with replayed scrollback.
- "persistent_output": True,
- "persistent_output_max_lines": 200,
- # Also clear terminal scrollback on classic-CLI full redraw/resize recovery; enable when a
- # terminal/tmux stack stamps stale prompt chrome into scrollback.
- "cli_rebuild_scrollback_on_redraw": False,
- "persist_prompts": True, # one-line scrollback summary of resolved approval/clarify prompts
- "inline_diffs": True, # inline diff previews for write_file/patch/skill_manage
- "inline_images": "auto", # CLI/TUI transcript images (attachments, tool results): auto|kitty|iterm|unicode|off
- # Append a one-line advisory to the final response when a write_file/patch failed this turn
- # and was never superseded by a successful write to the same path (catches "half the
- # parallel patches failed, model claims success").
- "file_mutation_verifier": True,
- # Nous credits status-bar notices (usage bands, grant-spent, depleted/restored). False mutes
- # them; balance data and /usage keep working.
- "credits_notices": True,
- # Append a one-line explanation when a turn ends with no usable reply (empty after retries,
- # truncated stream, pending tool result, iteration/budget limit) instead of the bare
- # "(empty)" sentinel.
- "turn_completion_explainer": True,
- "show_cost": False, # $ cost in the status bar
- "battery": False, # battery read-out first in status bar; no-op w/o battery
- # Focus view (/focus): display-only. Pins tool_progress to "off", reports per-turn
- # hidden-line count, pins a "focus" status segment. focus_saved_tool_progress holds the mode
- # /focus off restores. Never affects what the model sees (focus_view.py).
- "focus_view": False,
- "focus_saved_tool_progress": "all",
- "skin": "default",
- # UI language for static messages (approval prompts, some gateway slash replies); not agent
- # responses/logs/tool outputs. en, zh, ja, de, es, fr, tr, uk; unknown → en.
- "language": "en",
- # TUI busy indicator: kaomoji | emoji | unicode (braille) | ascii. `/indicator <style>`.
- "tui_status_indicator": "kaomoji",
- # Seconds between idle prompt_toolkit redraws in the classic CLI; keeps wall-clock
- # status-bar read-outs ticking and the bottom chrome from going stale. 0 disables it if it
- # fights terminal auto-scroll in non-fullscreen mode.
- # See #45592.
- "cli_refresh_interval": 1.0,
- # Vi/vim keybindings in the CLI input composer (config-only, no slash command).
- # Off by default, preserving prompt_toolkit's standard emacs bindings.
- "vim_mode": False,
- "user_message_preview": { # CLI: submitted user-message lines echoed to scrollback
- "first_lines": 2,
- "last_lines": 2,
- },
- # Gateway: natural mid-turn assistant status messages. Desktop: keep mid-turn narration
- # between tool calls instead of collapsing to the final message.
- "interim_assistant_messages": True,
- # Engine warning/failure notifications stay visible unless an operator opts in.
- # Does not suppress task results, manual commands, or existing logs.
- "suppress_warning_notifications": False,
- # Codex Responses commentary channel: true delivers completed commentary as mid-turn interim
- # updates; false routes it to reasoning (visible only with show_reasoning).
- "show_commentary": True,
- "tool_progress_command": False, # enable /verbose command in messaging gateway
- # display.tool_progress_overrides is deprecated (use display.platforms); a user-set value is
- # still honored at runtime and folded into platforms by migration.
- "tool_preview_length": 0, # max chars for tool call previews (0 = no limit)
- # Human-phrased status labels for built-in tools ("Reading <file>") in CLI spinner and
- # gateway/desktop tool-progress; custom/plugin/MCP tools use the raw preview.
- "friendly_tool_labels": True,
- # CLI-only post-turn line: "⋯ 12.4s · edited 2 files +18 -3 · read 4 files · ran 3
- # commands". Never in quiet/non-interactive or gateway surfaces (own footer).
- "turn_summary": True,
- # CLI-only: cumulative turn output tokens on the live spinner ("· ↓ 1.2k tok").
- "spinner_token_flow": True,
- # Gateway tool-progress grouping where edits are supported: "accumulate" edits one bubble |
- # "separate" one message per tool (noisier). Needs tool_progress enabled. Per-platform:
- # display.platforms.<platform>.tool_progress_grouping.
- "tool_progress_grouping": "accumulate",
- # Custom long-running status phrases. Defaults: gateway/assets/status_phrases.yaml.
- # `path`/`paths` = HERMES_HOME-relative YAML files/dirs (or conventional status_phrases.yaml
- # / status_phrases/*.yaml). Keys: status, generic. mode: "append" (default) | "replace".
- # Per-platform: display.platforms.<platform>.status_phrases.
- "status_phrases": {},
- # Reasoning summary rendering: "code" (💭 fenced block) | "blockquote" ("> ") | "subtext"
- # ("-# " Discord small grey text; Discord's default). Per-platform via
- # display.platforms.<platform>.reasoning_style.
- "reasoning_style": "code",
- # Auto-delete EphemeralReply system notices ("✨ New session started!", …) after N seconds
- # where deletion is supported (Telegram; others ignore). Agent responses are never touched.
- # 0 = disabled.
- "ephemeral_system_ttl": 0,
- # Per-platform display/streaming overrides; unset keys fall through to the global. Telegram
- # has smooth native draft streaming (on); Discord/Slack only edit-based streaming, which
- # flickers (off). Gap-fillers only: explicit user values win, and the global
- # streaming.enabled master switch still gates everything.
- "platforms": {
- "telegram": {"streaming": True},
- "discord": {"streaming": False},
- "slack": {"streaming": False},
- # WeCom native streaming (msgtype "stream" via aibot_respond_msg).
- "wecom": {"streaming": True},
- },
- # Gateway runtime footer on the FINAL message, e.g. `model · 68% · ~/projects/hermes`.
- # Per-platform: display.platforms.<platform>.runtime_footer.
- "runtime_footer": {
- "enabled": False,
- # order shown; drop any to hide. Opt-in extras: latency, served_model (alias → the
- # deployment a routing proxy reported / Hermes' fallback route).
- "fields": ["model", "context_pct", "cwd"],
- },
- # CLI/TUI status bar fields. Non-empty = only listed fields show (built-in order kept,
- # config controls visibility not ordering); empty = default set. Available: model,
- # context_detail, context_pct, cache_hit, latency, tps, compressions, bg_tasks,
- # bg_processes, bg_subagents, goal, git_branch (⎇ current branch, opt-in only), duration,
- # prompt_elapsed, idle_since, focus, yolo,
- # stash, battery, title, total_tokens (session Σ, opt-in only). Narrow terminals still drop
- # context_detail/prompt_elapsed/idle_since.
- "status_bar": {
- "fields": [],
- },
- "copy_shortcut": "auto", # "auto" (platform default) | ctrl_c | ctrl_shift_c | disabled
- # Petdex animated mascot (github.com/crafter-station/petdex): cosmetic sprite across
- # CLI/TUI/desktop, managed with `hermes pets`. No effect on prompt caching.
- "pet": {
- "enabled": False,
- "slug": "", # active pet slug in get_hermes_home()/pets/; empty → first installed
- # auto (detect kitty/iTerm2/sixel, else unicode half-blocks) | kitty | iterm | sixel |
- # unicode | off
- "render_mode": "auto",
- # Size scalar relative to native 192×208 frames, shared by desktop canvas and CLI/TUI
- # column width. Half-block fallback clamps to a legibility floor.
- "scale": 0.33,
- "unicode_cols": 0, # Hard override for terminal column width; 0 = derive from scale.
- },
- },
- "webapp": {"enabled": False, "host": "127.0.0.1", "port": 9120, "public_url": ""}, # gateway/webapp_listener.py
- "dashboard": {
- # Visual theme: "default" | "midnight" | "ember" | "mono" | "cyberpunk" | "rose"
- "theme": "default",
- # Process-isolation rollout controls. Read via the raw config loader, so tui_gateway.server
- # also owns explicit defaults.
- "turn_isolation": False,
- "compute_host_heartbeat_secs": 15,
- "compute_host_respawn_max": 3,
- # Token/cost analytics surfaces are hidden by default: the numbers are a local LOWER-BOUND
- # estimate, not billing — only successful main-agent responses with a response.usage count;
- # auxiliary calls, retries, fallbacks and cache writes are missed, so the total can be
- # 10x-100x under the provider bill.
- "show_token_analytics": False,
- # IPs / bounded CIDRs of reverse proxies trusted to supply X-Forwarded-Proto/-For. Loopback
- # always trusted; wildcards and /0 rejected (spoofing guard).
- "trusted_proxies": [],
- # WebSocket keepalive (seconds), NON-loopback binds only: loopback always disables the
- # protocol ping so an event-loop stall never kills a healthy local connection.
- "ws_ping_interval": 20.0,
- "ws_ping_timeout": 20.0,
- # Grace (seconds) before a WS-orphaned gateway session is interrupted/reaped after its
- # client disconnects. 0 = park forever. Env: HERMES_TUI_WS_ORPHAN_REAP_GRACE_S.
- "ws_orphan_reap_grace_s": 20.0,
- # A detached RUNNING turn is only interrupted once its activity clock (API waits, stream
- # tokens, tool heartbeats) has been idle this many seconds; an active turn runs to
- # completion. Default = agent.turn_liveness.timeout_s. 0 = interrupt at grace.
- # See #100325, #98028.
- "ws_orphan_activity_stale_s": 600.0,
- # On gateway boot, close tui/desktop/subagent rows orphaned by a dead gateway (start AND
- # newest message older than HERMES_TUI_SESSION_TTL_S, default 6h) with
- # end_reason='startup_orphan_reap'; otherwise they stay phantom "active" forever.
- # Messaging-gateway and live sessions are never touched; swept rows stay resumable.
- # The ws-orphan grace timer above is in-process, so a gateway restart (update, crash, systemd)
- # leaves disconnected sessions ``ended_at IS NULL`` forever — phantom "active" rows in /resume and
- # dashboards. See #65194.
- "startup_orphan_sweep": True,
- # OAuth gate (engaged when --host is set and --insecure is not), read by the Nous Portal
- # plugin. Env HERMES_DASHBOARD_OAUTH_CLIENT_ID / HERMES_DASHBOARD_PORTAL_URL win when
- # non-empty. Empty client_id = no provider; empty portal_url = production.
- "oauth": {
- "client_id": "", # agent:{instance_id} — Portal provisions this
- "portal_url": "",
- },
- # Username/password gate (dashboard_auth/basic plugin, no OAuth IDP). Active when username
- # plus password_hash (preferred) or password (hashed in-memory) are set; empty username =
- # no-op. Env HERMES_DASHBOARD_BASIC_AUTH_USERNAME / _PASSWORD_HASH / _PASSWORD / _SECRET /
- # _TTL_SECONDS win when non-empty. secret signs session tokens; empty = random per-process
- # key (sessions die on restart, no multi-worker) — set 32+ random bytes. Hash:
- # plugins.dashboard_auth.basic.hash_password('PW').
- "basic_auth": {
- "username": "",
- "password_hash": "", # scrypt$...
- "password": "",
- "secret": "",
- "session_ttl_seconds": 0, # 0 → plugin default (12h)
- },
- "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
- # Drain-control token auth (dashboard_auth/drain plugin): the secret is NOT here (env
- # HERMES_DASHBOARD_DRAIN_SECRET); no-op unless >=256-bit, weak secrets rejected (fail-closed).
- "drain_auth": {"scope": "drain", "min_secret_chars": 43},
- # Public URL (env HERMES_DASHBOARD_PUBLIC_URL): full authority (scheme + host + optional
- # prefix, e.g. https://example.com/hermes) for the OAuth redirect_uri; its hostname is
- # trusted by Host/Origin guards and engages the auth gate when non-loopback. For proxies
- # that don't forward X-Forwarded-Host/-Proto/-Prefix; X-Forwarded-Prefix is then IGNORED on
- # the OAuth path. Empty or malformed (no http(s):// + host, or quote/angle/whitespace chars)
- # = reconstruct from headers.
- "public_url": "",
- },
- "privacy": {
- "redact_pii": False, # hash user IDs and strip phone numbers from LLM context
- },
- # Text-to-speech. Each provider accepts an optional `max_text_length:` override for the
- # per-request input-character cap; omit to use the provider's documented limit (OpenAI 4096, xAI
- # 15000, MiniMax 10000, ElevenLabs 5k-40k model-aware, Gemini 32000, Edge 5000, Mistral 4000,
- # NeuTTS/KittenTTS 2000).
- "tts": {
- # "edge" (free) | "elevenlabs" (premium) | "openai" | "xai" | "minimax" | "mistral" |
- # "gemini" | "deepinfra" | "neutts" (local) | "kittentts" (local) | "piper" (local)
- "provider": "edge",
- # Seconds a local engine (Piper, KittenTTS) stays loaded after the last speech toggle
- # turns off, so a quick re-activation (wake word, voice-chat restart) skips the reload.
- # 0 unloads immediately.
- "keep_warm_seconds": 60,
- "streaming": {
- # Shortest first sentence (chars) spoken on its own by streaming TTS; shorter openers
- # ride with the next sentence. 20 suits English; CJK voice setups use ~6.
- "min_len": 20,
- },
- "edge": {
- # Popular: AriaNeural, JennyNeural, AndrewNeural, BrianNeural, SoniaNeural
- "voice": "en-US-AriaNeural",
- },
- "elevenlabs": {
- "voice_id": "pNInz6obpgDQGcFmaJgB", # Adam
- "model_id": "eleven_multilingual_v2",
- },
- "openai": {
- "model": "gpt-4o-mini-tts",
- # gpt-4o-mini-tts voices: alloy, ash, ballad, cedar, coral, echo, fable, marin, nova,
- # onyx, sage, shimmer, verse
- "voice": "alloy",
- # Forwarded verbatim in the request body for OpenAI-compatible servers whose cloned
- # voices demand it (400 consent_required otherwise); "" sends nothing.
- "consent_attestation": "",
- # Raw PCM rate for streaming playback. OpenAI emits 24 kHz; a compatible endpoint that
- # reports its rate (X-Audio-Sample-Rate header) overrides this automatically.
- "pcm_sample_rate": 24000,
- },
- "gemini": {
- "model": "gemini-2.5-flash-preview-tts",
- "voice": "Kore",
- # Gemini 3.1: aux-model rewrite inserts [audio tags] into the TTS script only.
- "audio_tags": False,
- # Optional local text file with performance direction; may include a `{transcript}`
- # placeholder, else the live transcript is appended.
- "persona_prompt_file": "",
- },
- "xai": {
- "voice_id": "eve", # or a custom voice ID (docs.x.ai custom voices)
- "language": "en", # BCP-47 code ("en", "pt-BR") or "auto"
- "speed": 1.0, # 0.7–1.5
- "auto_speech_tags": False, # insert expressive audio tags via LLM rewrite
- "optimize_streaming_latency": 0, # 0–2, trades quality for lower latency
- "sample_rate": 24000, # 22050 / 24000 / 44100 / 48000
- "bit_rate": 128000, # MP3 bitrate; only applies when codec=mp3
- },
- "mistral": {
- "model": "voxtral-mini-tts-2603",
- "voice_id": "c69964a6-ab8b-4f8a-9465-ec0925096ec8", # Paul - Neutral
- },
- "minimax": {"model": "speech-02-hd", "voice_id": "English_expressive_narrator"},
- "kittentts": {
- "model": "KittenML/kitten-tts-nano-0.8-int8", # nano 25MB; micro 41MB; mini 80MB
- "voice": "Jasper",
- },
- "neutts": {
- "ref_audio": "", # path to reference voice audio (empty = bundled default)
- "ref_text": "", # path to reference voice transcript (empty = bundled default)
- "model": "neuphonic/neutts-air-q4-gguf", # HuggingFace model repo
- "device": "cpu", # cpu, cuda, or mps
- },
- "piper": {
- # Voice name (downloaded on first use) or absolute path to a .onnx file; list:
- # github.com/OHF-Voice/piper1-gpl/blob/main/docs/VOICES.md. Optional keys: voices_dir
- # (~/.hermes/cache/piper-voices/), use_cuda, length_scale (2.0 = twice as slow),
- # noise_scale, noise_w_scale, volume, normalize_audio.
- "voice": "en_US-lessac-medium",
- },
- "deepinfra": {
- "model": "", # empty = first tts-tagged model from the live catalog
- "voice": "default",
- # optional "base_url" key overrides DEEPINFRA_BASE_URL for TTS only
- },
- },
- "stt": {
- "enabled": True,
- # Echo the raw transcript of gateway voice messages back as a 🎙️ message.
- "echo_transcripts": True,
- # No seeded "provider" (a stored value is an explicit pick; unset = autodetect): local | groq |
- # openai | mistral | elevenlabs | deepinfra | xai. Global language hint unless a per-provider one
- # overrides it; "en" because Whisper auto-detect misreads short clips; "" = auto; "es", ...
- "language": "en",
- "streaming": False, # live partial text while speaking (openai/xai/elevenlabs); failure = file path
- # Pre-upload ffmpeg silence trim (local whisper uses VAD); failure = raw upload.
- "cloud_trim_silence": True,
- "cloud_trim_threshold_db": -40, # quieter than this counts as silence
- "cloud_trim_keep_ms": 300, # how much of each pause survives (natural pacing)
- "local": {
- "model": "base", # tiny, base, small, medium, large-v3, turbo
- "language": "", # blank = inherit stt.language; set "en", "es", ... to force
- "initial_prompt": "",
- # Anti-hallucination (faster-whisper decodes junk from silence). vad: Silero filter
- # (false = raw audio, for music/ambient). A segment is dropped only if no_speech_prob
- # ABOVE no_speech_prob_threshold AND avg_logprob BELOW logprob_threshold.
- "vad": True,
- "vad_min_silence_ms": 500, # min silence (ms) that splits speech chunks
- "no_speech_prob_threshold": 0.6,
- "logprob_threshold": -1.0,
- "unload_after_idle_seconds": 0, # 0 = never; e.g. 300 frees the model after 5min
- },
- "groq": {
- "model": "whisper-large-v3-turbo", # whisper-large-v3-turbo, whisper-large-v3
- "language": "", # blank = inherit stt.language; set "en", "es", ... to force
- },
- "openai": {
- # whisper-1, gpt-4o-mini-transcribe, gpt-4o-transcribe, gpt-transcribe
- "model": "whisper-1",
- "streaming_model": "gpt-live-transcribe", # stt.streaming; the one model with mid-utterance deltas
- "language": "", # blank = inherit stt.language; set "en", "es", ... to force
- "timeout": 60, # seconds; allow self-hosted backends time to cold-start
- "max_retries": 1, # OpenAI SDK transport retries
- },
- "mistral": {
- "model": "voxtral-mini-latest", # voxtral-mini-latest, voxtral-mini-2602
- "language": "", # blank = inherit stt.language; set "en", "es", ... to force
- },
- "xai": {
- "model": "", # "" = STT_XAI_MODEL or grok-voice-transcribe-2.0; or grok-voice-transcribe-1.0
- "language": "", # blank = inherit stt.language; set "en", "es", ... to force
- },
- "elevenlabs": {
- "model_id": "scribe_v2", # scribe_v2, scribe_v1
- "language_code": "", # blank = inherit stt.language; set "eng", "spa", ... to force
- "tag_audio_events": False,
- "diarize": False,
- },
- "deepinfra": {
- "model": "", # empty = first stt-tagged model from the live catalog
- # optional "base_url" key overrides DEEPINFRA_BASE_URL for STT only
- },
- },
- "voice": {
- # How the Desktop voice conversation is wired:
- # chained — STT → Hermes turn → TTS (the stt.* / tts.* providers below)
- # gpt-live — one full-duplex voice model (OpenAI GPT-Live) owns the mic and speaker and
- # DELEGATES every real request to Hermes (any model / provider you have
- # selected); needs an OpenAI API key. $0.05/min voice layer billing.
- "voice_chat_mode": "chained",
- "gpt_live": {
- "model": "gpt-live-1",
- "voice": "marin", # marin | quartz | ripple | vesper | willow | stone | gleam | meridian | ...
- # Extra sentences appended to the live model's conversation persona (tone, pacing, language).
- "instructions": "",
- # optional "api_key" / "base_url" keys override the OpenAI audio credentials for this mode only
- },
- "record_key": "ctrl+b",
- "submit_mode": "direct", # TUI: direct submits immediately; draft = editable transcript
- "max_recording_seconds": 120,
- "auto_tts": False,
- # Desktop remote clients call STT/TTS providers DIRECTLY (config + key fetched over
- # authenticated REST at session start) instead of relaying via the gateway.
- "client_direct": True,
- "beep_enabled": True, # record start/stop beeps in CLI voice mode
- "beep_volume": 0.3, # beep amplitude multiplier, 0.0-1.0
- "thinking_sound": True, # ambient bubble sound while the agent works (volume = beep_volume)
- "silence_threshold": 200, # RMS below this = silence (0-32767)
- "silence_duration": 3.0, # seconds of silence before auto-stop
- "barge_in": True, # interrupt the agent / stop TTS when the user starts talking
- # Trip suppression after TTS onset (mic stays live the whole turn).
- "barge_in_grace_seconds": 0.5,
- # Speech trigger = quiet-room floor x this (floor calibrated BEFORE playback).
- "barge_in_threshold_multiplier": 3.0,
- # Saying EXACTLY one of these (case-insensitive, punctuation ignored) ends the voice chat
- # instead of going to the agent. [] disables.
- "stop_phrases": ["stop"],
- },
- # Native images (vision_analyze, browser screenshots, replayed user images) are re-sent on every later call.
- "vision": {
- # Byte budget for one embedded image (clamped 64 KiB..4 MiB). Raise it for dense phone
- # screenshots of tables the model calls "unreadable" at 256 KB.
- "embed_target_bytes": 256 * 1024,
- # How often vision_analyze may embed the SAME image (region crops included) per session.
- # null = 3 inside delegated subagents (they run unattended), unlimited for the main agent;
- # an explicit number applies everywhere; 0 = unlimited.
- "max_calls_per_image": None,
- "replay_recent_images": 3, # newest user images re-sent on turns rebuilt from state.db; 0 = off
- },
- # "Hey Hermes" hands-free wake word: always-on, on-device hotword detection that starts a fresh
- # voice session. Off by default; toggle with /wake.
- "wake_word": {
- "enabled": False,
- "surface": "auto", # eligible surface: "auto" (first claimant) | "cli" | "tui" | "gui"
- "input_device": None, # PortAudio input device index/name; null = process default
- "capture": "auto", # auto | local | client (desktop streams mic via wake.feed)
- # auto: first platform-supported engine (openwakeword, sherpa, porcupine).
- # Explicit choices stay pinned. Porcupine needs PORCUPINE_ACCESS_KEY.
- "provider": "auto",
- # sherpa: this IS the detected phrase; other engines: cosmetic label (detection is keyed by
- # the model/keyword below)
- "phrase": "hey hermes",
- "sensitivity": 0.6, # 0.0-1.0 threshold, consistent across engines (higher = stricter)
- # openWakeWord/pyopen-wakeword only: consecutive over-threshold frames to fire (higher = fewer
- # false triggers, more latency; 1 = single-frame)
- "confirmation_frames": 3,
- "start_new_session": True, # fresh session on wake vs. continue the current one (detached-spawn: ok — a config key)
- # sherpa only: listen for every wake-enabled profile's phrase and route to it
- "profile_routing": True,
- "openwakeword": {
- # "hey_hermes" | built-in openWakeWord name ("hey_jarvis", "alexa", ...) | path to a
- # custom .tflite model
- "model": "hey_hermes",
- },
- "sherpa": {
- # sherpa-onnx KWS model dir; empty = auto-download the small English zipformer
- "model_dir": "",
- },
- "porcupine": {
- # built-in keyword ("jarvis", "computer", ...) or path to a custom .ppn
- "keyword": "jarvis",
- },
- },
- "human_delay": {"mode": "off", "min_ms": 800, "max_ms": 2500},
- # Context engine — how the context window is managed near the token limit. "compressor" =
- # built-in lossy summarization; or a plugin name (e.g. "lcm") installed in
- # plugins/context_engine/<name>/ or ~/.hermes/plugins/.
- "context": {
- "engine": "compressor",
- # Return freed glibc pages at agent/TUI cleanup boundaries (no-op elsewhere).
- "memory_trim": {
- "enabled": True,
- "cooldown_seconds": 60.0,
- "log_every_n": 1, # INFO-log every Nth periodic trim; force paths always log.
- # Suppress INFO logs when the readable RSS delta is smaller; 0 = log all.
- "info_log_min_delta_mb": 0.0,
- },
- },
- "memory": { # Persistent memory — bounded curated memory injected into the system prompt
- "memory_enabled": True,
- "user_profile_enabled": True,
- "prefetch_spill_enabled": False, # External recall opt-in to hooks.output_spill.
- # Approval gate for memory writes on BOTH foreground turns and the background review fork.
- # true = foreground writes prompt inline; background writes are staged (/memory
- # pending|approve <id>|reject <id>). To disable memory: memory_enabled.
- "write_approval": False,
- "memory_char_limit": 2200, # ~800 tokens at 2.75 chars/token
- "user_char_limit": 1375, # ~500 tokens at 2.75 chars/token
- # Periodic built-in memory review; 0 when an external provider auto-extracts.
- "nudge_interval": 10,
- # One external provider: bundled (retaindb, byterover) or catalog-installed (honcho,
- # hindsight, supermemory, mem0, openviking, holographic). Empty = built-in only.
- "provider": "",
- },
- # Subagent delegation: `backend` = task-routing strategy ("default": keys below), `backends.<name>` = its settings.
- "delegation": {
- "backend": "default",
- "backends": {},
- "model": "", # e.g. "google/gemini-3-flash-preview" (empty = inherit parent)
- "provider": "", # e.g. "openrouter" (empty = inherit parent provider + credentials)
- # Fallback chain for delegated children (same entry format as the top-level list).
- # For an unpinned child, null = inherit the parent chain; [] = disable fallback.
- # A child pinned by provider, endpoint, or model gets no fallback unless this
- # setting declares one explicitly.
- "fallback_providers": None,
- "base_url": "", # direct OpenAI-compatible endpoint for subagents
- "api_key": "", # key for delegation.base_url (falls back to OPENAI_API_KEY)
- # Wire protocol for delegation.base_url: "chat_completions" | "codex_responses" |
- # "anthropic_messages". Empty = auto-detect from URL (e.g. /anthropic suffix); set
- # explicitly for non-standard endpoints.
- "api_mode": "",
- # Per-child request settings on every delegation call (all resolution branches). Top-level
- # keys = API kwargs (e.g. service_tier); "extra_body" sub-dict merges into extra_body, e.g.
- # {"extra_body": {"provider": {"sort": "throughput"}}}. Explicit values win OVER
- # runtime/parent overrides (extra_body deep-merged 1 level).
- "request_overrides": {},
- # compression_threshold_tokens: optional absolute cap on a subagent's compaction TRIGGER
- # (not the request payload), applied as the lower of this and the child's ratio threshold.
- # 0 (default) = no subagent-specific cap; children compact where the parent does — the lower
- # of 0.50 x window and the global compression.threshold_tokens cap. A replay of a 1,393-agent
- # run showed 200K-400K caps within 5% of each other in cost once cache prefixes are intact,
- # and every compaction is a chance to lose detail, so the default stays off. A token count >= 16000 enables it;
- # other values (true, "200k") are config errors: warned and ignored.
- "compression_threshold_tokens": 0,
- # When delegate_task narrows child toolsets, keep the parent's enabled MCP toolsets (so
- # toolsets=["web"] doesn't strip MCP). false = strict intersection.
- "inherit_mcp_toolsets": True,
- # Per-subagent iteration cap (own budget, independent of the parent's).
- "max_iterations": 250,
- # Hard per-summary char ceiling on subagent results, layered on the dynamic budget (each
- # summary is sized to the parent's remaining context headroom; trimmed text spills to
- # ~/.hermes/cache/delegation/ with a head+tail window + read_file offset footer, nothing
- # lost). 0 disables the ceiling; the dynamic budget still applies.
- "max_summary_chars": 24000,
- # Inactivity cap per child (seconds, floor 30) — time with NO progress, not total runtime. 0 = no cap:
- # children fail only from real errors (API, tools, iteration budget). A progressing child (including one
- # waiting on a multi-minute completion) restarts the window; a frozen one is caught.
- "child_timeout_seconds": 0,
- # Subagent effort: "ultra" | "max" | "xhigh" | "high" | "medium" | "low" | "minimal" | "none" (empty = inherit)
- "reasoning_effort": "",
- # Max parallel children per batch AND concurrent background units (async beyond it runs sync). Floor 1.
- "max_concurrent_children": 10,
- "prefix_stagger_seconds": 0, # max s siblings wait for the 1st child's 1st chunk (not a stagger); 0 = off
- # Background fan-outs return as ONE message when the whole call finishes. true = each task
- # (or `group`) returns on its own as it finishes — more new turns for the orchestrator.
- "independent_completions": False,
- "gateway_mode": "auto", # gateway: inline (join in the turn) | background | auto = inline where interim msgs are off
- # Orchestrator role controls. Depth floored at 1, no ceiling; each level multiplies cost.
- "max_spawn_depth": 1, # 1 = flat, 2 = orchestrator→leaf, 3+ = deeper
- "orchestrator_enabled": True, # kill switch for role="orchestrator"
- # Total subagents a finite one-shot run (hermes chat -q / --oneshot) may spawn; 0 = unlimited.
- # Each child re-pays a cold system prompt and re-explores the repo, and one-shot spawns are mostly
- # "review my own work" rather than parallel work (agent/oneshot_footprint.py).
- "oneshot_max_children": 2,
- # Subagent threads ALWAYS resolve approvals non-interactively (the parent TUI owns stdin;
- # input() from a worker would deadlock). false = auto-deny, true = auto-approve "once"; both
- # log a warning audit line. true only for trusted batch work.
- "subagent_auto_approve": False,
- # Subagent background processes (task_id "sa-...") route notify_on_complete / watch_pattern
- # notifications to the PARENT; false suppresses them (the child's result is the
- # deliverable). Async-delegation results are NEVER suppressed.
- "surface_child_process_notifications": False,
- },
- # Ephemeral prefill messages file — JSON list of {role, content} dicts injected at the start of
- # every API call for few-shot priming. Never saved to sessions/logs/trajectories.
- "prefill_messages_file": "",
- # Goals — persistent cross-turn /goal loop: after each turn an aux-model judge checks if the
- # goal is satisfied, else a continuation prompt re-enters the session until done, budget
- # exhausted, or paused. Judge failures fail OPEN; the budget is the backstop.
- "goals": {
- # Max continuation turns before auto-pause (/goal resume) — guards against judge false
- # negatives and unbounded spend.
- "max_turns": 20,
- },
- # Loops — /loop re-runs a prompt or slash command on a cadence in-session. Fixed interval fires
- # on the user's clock; self-paced (no interval) starts at the floor and backs off exponentially
- # while replies stop changing.
- "loops": {
- "min_interval_seconds": 30, # smallest fixed interval; tighter cadences raised to it
- "max_ticks": 100, # auto-pause after this many wakeups unless --times set; 0 = unlimited
- "self_paced_floor_seconds": 60, # Self-paced cadence bounds (seconds).
- "self_paced_ceiling_seconds": 900,
- },
- # Mixture of Agents — named presets used by /moa. A preset is an execution mode around the main
- # model, not a model itself: references + aggregator synthesize private guidance before each
- # main-model iteration.
- "moa": {
- "default_preset": "default",
- "active_preset": "",
- # Write each MoA turn (reference + aggregator exact input/output/usage) as JSONL to
- # <hermes_home>/moa-traces/<session_id>.jsonl (or trace_dir) for auditing.
- "save_traces": False,
- "trace_dir": "",
- # PII/credential redaction of advisor outputs: "" off | "display" (UI reference blocks +
- # traces only; aggregator sees raw) | "full" (also the aggregator prompt).
- # Advisors can echo PII from the conversation (emails, formatted phone numbers) and credential
- # shapes into reference blocks, traces, and the aggregator prompt. Modes ('' = off, the default):
- # "display" — redact user-visible surfaces only (reference blocks shown in the UI + saved MoA trace
- # records); the aggregator still sees raw advisor text. "full" — additionally redact the advisor
- # text injected into the aggregator prompt (issue #59959).
- "privacy_filter": "",
- "presets": {
- "default": {
- "reference_models": [
- {"provider": "openai-codex", "model": "gpt-5.5"},
- {"provider": "openrouter", "model": "deepseek/deepseek-v4-pro"},
- ],
- "aggregator": {"provider": "openrouter", "model": "anthropic/claude-opus-4.8"},
- "enabled": True,
- }
- },
- },
- # Skills — external skill directories shared across tools/agents. Paths are expanded (~, ${VAR})
- # and resolved; read-only — creation goes to ~/.hermes/skills/ unless create_dir redirects it.
- "skills": {
- "external_dirs": [], # e.g. ["~/.agents/skills", "/shared/team-skills"]
- # Where skill_manage-created skills go (empty = profile-local dir). When set, new skills
- # land here AND agent-facing instructions name this path; expanded (~, ${VAR}), relative to
- # HERMES_HOME, scanned alongside the local dir.
- "create_dir": "",
- # In a git checkout, <root>/.hermes/skills/ and <root>/.agents/skills/ load as the
- # highest-precedence tier — ONLY if the root is in trusted_project_dirs. false = no scan, no
- # untrusted-skills notice.
- "project_discovery": True,
- # Trusted project roots; managed by `hermes skills trust` / `untrust`.
- "trusted_project_dirs": [],
- # Skill names pinned as fully loaded in every new session (CLI, TUI, gateway, cron, API).
- # Resolved once when the agent's prompt is first built; missing/disabled names warn and
- # skip; HERMES_IGNORE_RULES suppresses the list like the other auto-injected context.
- "auto_load": [],
- # Substitute ${HERMES_SKILL_DIR} / ${HERMES_SESSION_ID} in SKILL.md content.
- "template_vars": True,
- # Pre-execute !`cmd` snippets in SKILL.md, inlining stdout (dates, git state...). Off:
- # host-unapproved skill-author code; community hub installs never auto-execute (#63307).
- "inline_shell": False,
- "inline_shell_timeout": 10, # seconds per !`cmd` snippet
- # Security-scan skills the agent writes via skill_manage. Off: the agent can run the same
- # code via terminal() ungated, so it mostly blocks prose with risky keywords. On: a
- # dangerous verdict is a tool error the agent can retry. Hub installs are always scanned.
- "guard_agent_created": False,
- # Advisory NVIDIA SkillEvaluator Tier 1 scan on `hermes skills install` (alongside the
- # enforcing built-in guard), only if `skillevaluator` is on PATH (uv tool install
- # "skillevaluator @ git+https://github.com/NVIDIA/SkillEvaluator.git"). Informational, never
- # blocking; secrets-class findings shown red. No-op without it.
- "tier1_advisory": True,
- # Approval gate for skill_manage mutations on BOTH foreground turns and the background
- # review fork. true = ALWAYS stage (SKILL.md too large for an inline prompt): /skills
- # pending, /skills diff <id>, /skills approve|reject <id>.
- "write_approval": False,
- # Audit ledger: every skill mutation appends to ~/.hermes/skills/.curator_ledger.jsonl with
- # before/after hashes (blobs under ~/.hermes/.curator_backups/blobs/); powers `hermes
- # curator ledger` / `rollback <entry-id>`. Never a gate — failures can't block.
- # See #79686.
- "ledger": True,
- # Size cap for that ledger: once the file grows past this, the next append rewrites it
- # through the unchanged-file dedup and, if still over, drops the oldest entries (0 = keep
- # the ledger append-only forever, the previous behaviour).
- "ledger_max_bytes": 5 * 1024 * 1024,
- },
- # Curator — background maintenance of AGENT-CREATED skills (never hub-installed): marks
- # long-unused skills stale, archives (never deletes) obsolete ones, optionally consolidates
- # overlaps via a forked aux-model agent. Inactivity-triggered from session start, no cron
- # daemon. `hermes curator status` shows the last run.
- "curator": {
- "enabled": True,
- "interval_hours": 24 * 7, # hours between runs
- "min_idle_hours": 2, # only run after the agent has been idle this long
- "stale_after_days": 14, # mark "stale" after this many unused days
- "archive_after_days": 30, # move to skills/.archive/ (recoverable) after this many
- # LLM consolidation (umbrella-building) pass. OFF = deterministic inactivity prune only, no
- # aux-model cost. `hermes curator run --consolidate` overrides once.
- "consolidate": False,
- # Also prune bundled built-ins (a suppression list stops `hermes update` restoring them);
- # hub-installed skills are NEVER pruned. OFF by default: shipped skills vanishing from
- # `skills_list` because nobody loaded them for 30 days surprised people (57 gone in one
- # startup tick). true = built-ins age out like agent-created skills.
- "prune_builtins": False,
- # TTL purge of skills/.archive/: 0 = never; > 0 lets the explicit `hermes curator purge`
- # delete older archived skills (never automatic; logged in the ledger).
- "archive_ttl_days": 0,
- # Before a consolidation pass (the only one that rewrites skill content in place), snapshot
- # ~/.hermes/skills/ to ~/.hermes/skills/.curator_backups/<utc-iso>/skills.tar.gz (`hermes curator
- # rollback`). The prune-only pass just moves directories into .archive/ and takes none.
- "backup": {
- "enabled": True,
- "keep": 2, # retain last N regular snapshots
- },
- },
- # Honcho memory plugin (plugin catalog) — ~/.honcho/config.json is the source of truth (apiKey,
- # workspace, peerName, sessions, enabled); the plugin reads hermes-specific overrides from here.
- "honcho": {},
- # IANA timezone (e.g. "Asia/Kolkata", "America/New_York"). Empty = server-local time.
- "timezone": "",
- "slack": {
- "require_mention": True, # require @mention to respond in channels
- "free_response_channels": "", # comma-separated channel IDs answered without mention
- "allowed_channels": "", # if set, ONLY respond in these channel IDs (whitelist)
- "require_mention_channels": "", # channel IDs where @mention is ALWAYS required
- # Ignore messages whose first token @mentions another user unless the bot is also mentioned.
- # Env: SLACK_IGNORE_OTHER_USER_MENTIONS.
- "ignore_other_user_mentions": False,
- "thread_require_mention": False, # require @mention in thread replies too
- "channel_prompts": {}, # per-channel ephemeral system prompts
- },
- "discord": {
- "require_mention": True, # require @mention to respond in server channels
- "free_response_channels": "", # comma-separated channel IDs answered without mention
- "allowed_channels": "", # if set, ONLY respond in these channel IDs (whitelist)
- "auto_thread": True, # auto-create threads on @mention in channels (like Slack)
- # Free-response channels reply inline by default; true also gives each top-level
- # message in them its own thread (still mention-free). Env: DISCORD_FREE_RESPONSE_AUTO_THREAD.
- "free_response_auto_thread": False,
- "thread_require_mention": False, # require @mention in threads too (multi-bot threads)
- # Bot authors must type @thisbot to trigger a reply; Discord reply pings alone do not count.
- # Set False only for trusted legacy relays. Humans are unaffected.
- "bots_require_inline_mention": True,
- # Prepend recent channel scrollback when triggered (recovers messages gated out by
- # require_mention); limit = max messages scanned.
- "history_backfill": True,
- "history_backfill_limit": 50,
- # Replay messages missed while offline, after reconnect/startup.
- "missed_message_backfill": {
- "enabled": False,
- "channels": "", # comma-separated channel IDs; empty uses free_response_channels
- "window_seconds": 21600, # only inspect messages from the last 6 hours
- "limit": 100, # global cap on messages scanned per reconnect
- "max_dispatches": 10, # cap on recovered messages dispatched per reconnect
- "max_attempts": 3, # lifetime re-dispatch cap for one message, whatever its outcome
- },
- "reactions": True, # add 👀/✅/❌ reactions to messages during processing
- # Gateway transport health probe: inspects the WebSocket's ready/open/heartbeat state (never
- # REST) as proof events still arrive. Any value 0 disables it.
- "websocket_liveness_interval_seconds": 15,
- "websocket_liveness_failure_threshold": 2,
- "websocket_heartbeat_ack_max_age_seconds": 60,
- "websocket_max_latency_seconds": 30,
- # Dispatch-side dimension: a socket that ACKs heartbeats but delivers no events for this
- # long is treated as deaf. 4 h absorbs a quiet server overnight; 0 disables it.
- "websocket_event_max_silence_seconds": 14400,
- # per-channel ephemeral system prompts (forum parents apply to child threads)
- "channel_prompts": {},
- # Opt-in DM role auth: DISCORD_ALLOWED_ROLES normally authorizes guild messages only (DMs
- # need DISCORD_ALLOWED_USERS). A guild ID here also authorizes DMs from that guild's members
- # holding the allowed role. Unset / "" / 0 = off.
- # See #12136.
- "dm_role_auth_guild": "",
- # discord / discord_admin tools: allowed actions (comma string or YAML list; empty = all,
- # subject to bot intents; unknown names dropped with a warning): list_guilds, server_info,
- # list_channels, channel_info, list_roles, member_info, search_members, fetch_messages,
- # list_pins, pin_message, unpin_message, create_thread, add_role, remove_role.
- "server_actions": "",
- # DEPRECATED no-op (uploads are always cached; messaging auth is the gate). Kept so existing
- # configs don't error. Env: DISCORD_ALLOW_ANY_ATTACHMENT.
- "allow_any_attachment": False,
- # Max bytes per cached attachment (held in memory while written); 0 = no cap. Env:
- # DISCORD_MAX_ATTACHMENT_BYTES.
- "max_attachment_bytes": 33554432,
- # Mention allowed users on approval prompts so owners notice them in shared channels. Env:
- # DISCORD_APPROVAL_MENTIONS.
- "approval_mentions": False,
- # Voice-channel inactivity timeout (seconds); 0 = stay until `/voice leave`.
- "voice_channel_inactivity_timeout_seconds": 300,
- # Minimum seconds before force-stopping a VC playback; the adapter probes clip duration and
- # extends this floor so long TTS isn't cut off.
- "voice_playback_timeout_seconds": 120,
- # Voice-channel software mixer (plugins/platforms/discord/voice_mixer.py): ambient
- # "thinking" bed, verbal acks and TTS OVERLAP (ambient ducked) vs stop-and-swap.
- "voice_fx": {
- "enabled": False, # master switch for the mixer subsystem
- "ambient_enabled": True, # play the idle "thinking" bed while tools run
- "ambient_path": "", # custom loop audio file; "" = synthesised pad
- "ambient_gain": 0.18, # idle bed loudness, 0.0–1.0
- "duck_gain": 0.06, # ambient loudness while speech plays
- "speech_gain": 1.0, # TTS / ack loudness, 0.0–1.0
- "ack_enabled": True, # speak a short phrase before the first tool call
- "ack_phrases": [ # picked at random; [] disables phrases
- "Let me look into that.",
- "One moment.",
- "Checking on that now.",
- "Give me a sec.",
- "On it.",
- ],
- },
- },
- "whatsapp": {
- # reply_prefix: None = built-in "☤ *Hermes Agent*" header; "" disables; \n allowed.
- },
- "telegram": {
- "reactions": False, # add 👀/✅/❌ reactions to messages during processing
- # per-chat/topic ephemeral system prompts (topics inherit from parent group)
- "channel_prompts": {},
- "allowed_chats": "", # if set, ONLY respond in these group/supergroup chat IDs
- "extra": {
- # Bot API 10.1 native rich messages (tables/task lists/math). Off = legacy MarkdownV2,
- # since rich messages are hard to copy as plain text.
- "rich_messages": False,
- # Experimental rich DM stream previews; off: Telegram Desktop/macOS overlays draft frames.
- "rich_drafts": False,
- # CJK stays on legacy MarkdownV2 (Telegram Desktop/macOS garbles rich CJK, #47653);
- # set True on an unaffected client to get native rich tables for CJK.
- "allow_cjk_rich_messages": False,
- "dm_topic_auto_transfer": False, # /topic mode: root-DM message opens a fresh topic
- },
- },
- "mattermost": {
- "require_mention": True, # require @mention to respond in channels
- "free_response_channels": "", # comma-separated channel IDs answered without mention
- "allowed_channels": "", # if set, ONLY respond in these channel IDs (whitelist)
- "channel_prompts": {}, # per-channel ephemeral system prompts
- },
- "matrix": {
- "require_mention": True, # require @mention to respond in rooms
- "free_response_rooms": "", # comma-separated room IDs answered without mention
- "allowed_rooms": "", # if set, ONLY respond in these room IDs (whitelist)
- },
- # Approvals for dangerous commands.
- # mode: manual (always prompt) | smart (aux LLM auto-approves low-risk) | off (= --yolo)
- # cron_mode / single_query_mode / unattended_mode: deny | approve — what to do when a
- # cron job, a -q session (HERMES_INTERACTIVE=1 but nobody to answer), or an unattended
- # platform (webhook, msgraph_webhook, api_server; no /approve channel) hits one.
- # deny blocks instantly so the agent finds another way instead of waiting out the
- # timeout and failing closed.
- # timeout: seconds before an unanswered prompt fails closed (CLI and gateway). 60s
- # proved too tight for Telegram/Discord push notifications, hence 300.
- "approvals": {
- # single_query_mode — what to do when a single-query (-q) session hits a dangerous command. -q runs
- # export HERMES_INTERACTIVE=1 (for interactive sudo prompts) but have NO user waiting to answer
- # approval prompts — an unanswered prompt just waits the full timeout then fails closed, so the
- # agent is forced to work around the block (often via execute_code). This setting makes that intent
- # explicit: deny — block the command and let the agent find another way (default, safe; mirrors
- # cron_mode deny) approve — auto-approve all dangerous commands in single-query mode These surfaces
- # bind a session platform like chat gateways do, but have no send_exec_approval and no /approve
- # channel — a pending approval there just blocks for the full timeout with nobody to answer (#37284,
- # #87509): deny — block the command instantly and let the agent find another way (default, safe;
- # mirrors cron_mode deny) approve — auto-approve all dangerous commands on unattended platforms
- "mode": "smart",
- "timeout": 300,
- "discord_prompt_timeout": 300, # Discord buttons stay clickable (min 30 s, cap MAX_SAFE_TIMEOUT_S)
- "cron_mode": "deny",
- "single_query_mode": "deny",
- "unattended_mode": "deny",
- # Extra rules appended to the smart-approval guardian's SYSTEM prompt, e.g. "Always ESCALATE
- # commands touching /etc".
- "smart_policy": "",
- # After this many consecutive guardian DENYs in a session, the deny message escalates to a
- # hard-stop (report to user / ask for /approve). Approval resets; 0 off.
- "denial_breaker_threshold": 3,
- # Case-insensitive fnmatch globs against terminal commands; a match blocks even under --yolo
- # / mode=off. Quote in YAML when starting with * or containing {}/!/: e.g. "git push
- # --force*".
- "deny": [],
- # /reload-mcp confirms before rebuilding the MCP tool set (it invalidates the prompt cache,
- # so the next message re-sends full input). "Always Approve" → false.
- "mcp_reload_confirm": True,
- # /clear, /new, /reset, /undo confirm before discarding state (Approve Once / Always Approve
- # / Cancel via tools.slash_confirm; native buttons on Telegram/ Discord/Slack). "Always
- # Approve" → false. HERMES_TUI_NO_CONFIRM=1 skips the TUI modal.
- "destructive_slash_confirm": True,
- },
- # Permanently allowed dangerous command patterns (added via "always" approval).
- "command_allowlist": [],
- # User-defined quick commands that bypass the agent loop (type: exec only).
- "quick_commands": {},
- # Per-platform system-prompt hint overrides, keyed by platform name (whatsapp, slack, telegram,
- # ...). Value: {"append": text} keeps the built-in hint and appends; {"replace": text}
- # substitutes it; a bare string is shorthand for append. `replace` wins over `append` if both
- # are given.
- "platform_hints": {},
- # Plugin system. `enabled`/`disabled` (`hermes plugins enable|disable`) and `disabled_by_update` (pm.plugin_eviction:
- # plugins an update turned off, retried by later updates) are omitted so an empty default never clobbers a user's lists.
- "plugins": {
- # Deadline (seconds) for one plugin Git clone, fetch or checkout. Slow repositories may
- # need more time; each network operation is capped at one hour.
- "clone_timeout_seconds": 300,
- # Wall-clock cap (seconds) for one in-process Python plugin hook callback; shell hooks keep
- # their own per-entry `timeout`. 0 = no cap (sync call on agent thread). Max 600.
- "hook_callback_timeout": 30,
- # Deadline (seconds) for one plugin's import + register() at load. A plugin that overruns it is
- # skipped with the reason "load timed out" and the rest keep loading; the stuck worker thread is
- # abandoned. 0 = no deadline (load inline). Max 600.
- "load_timeout_seconds": 10,
- # Read-only plugin update-check cadence, hours (gateway tick; 0 disables). Applying stays
- # explicit: `hermes plugins update <name>`, or auto_apply below (catalog and tracked git
- # plugins, scan-gated by that same pipeline).
- "auto_update_check_hours": 24,
- # Opt-in unattended apply (`hermes plugins auto-update on`, Desktop's Plugins tab): catalog +
- # tracked git plugins, same scan/consent pipeline as the manual update (never a widened pin).
- "auto_apply": False,
- # Where third-party Python plugins run. in_process: imported into Hermes (default).
- # host: one plugin-host process per profile runs them and they reach Hermes only through
- # ctx (a crashing or hanging plugin takes down its host, which restarts; Hermes keeps
- # running). Bundled plugins stay in-process; `hermes plugins validate` says whether a
- # plugin can run in the host.
- "isolation": "in_process",
- "host": {
- # argv prefix the plugin host runs under, e.g. a sandbox runner. [] = plain subprocess.
- "launcher": [],
- },
- },
- # Shell-script hooks: event name (pre_tool_call, post_tool_call, pre_llm_call, subagent_stop,
- # ...) -> list of {matcher, command, timeout}. First run of a new command prompts for consent;
- # approvals persist in ~/.hermes/shell-hooks-allowlist.json. Schema + examples:
- # website/docs/user-guide/features/hooks.md.
- "hooks": {},
- # Auto-accept shell-hook registrations without a TTY prompt (also --accept-hooks or
- # HERMES_ACCEPT_HOOKS=1). Gateway/cron/non-interactive runs need one of these to pick up
- # newly-added hooks.
- "hooks_auto_accept": False,
- # Custom personalities: {"name": "system prompt"} or {"name": {"description", "system_prompt",
- # "tone", "style"}}.
- "personalities": {},
- "auth": { # Login policy (credentials themselves live in auth.json / .env).
- # Borrow and refresh the Codex CLI (~/.codex/auth.json) and Claude Code (~/.claude/.credentials.json)
- # logins automatically when Hermes has no usable login of its own. Their refresh tokens are single-use
- # and rotate, so two programs on one login can log each other out; set false to make Hermes use only
- # its own logins (`hermes auth add <provider>`). `hermes auth add openai-codex` still offers the import
- # interactively.
- "adopt_external_logins": True,
- # How `hermes auth add openai-codex` / `hermes model` sign in to OpenAI Codex.
- # "device_code" (default): open a URL, enter a code. "browser": authorization-code + PKCE on
- # the loopback listener http://localhost:1455/auth/callback (the redirect OpenAI registered
- # for the Codex client) — for organizations that disable the device-code grant. Falls back
- # to device code when that port is busy. `hermes auth add openai-codex --browser` opts in
- # for one login without changing this key.
- "codex_login_flow": "device_code",
- },
- "security": { # Security: URL/private-network guards, redaction and approval presentation.
- "allow_private_urls": False, # private IPs for web/vision/media + cloud/CDP browsers; not local/sidecar Chromium
- # CIDR blocks a local TUN proxy answers DNS with (Mihomo/Clash fake-ip, Surge enhanced).
- # Answers inside these blocks are the proxy's sentinels, not internal hosts, so the guard
- # dials them instead of rejecting them as private. Empty = normal private-address verdict.
- "fake_ip_ranges": [],
- "redact_secrets": True,
- # Persisted acknowledgement for unattended model overrides whose tier lets the vendor train
- # on prompts. The startup guard still warns every run; cost guards are unaffected.
- "allow_data_training_tiers_noninteractive": False,
- # Human-approval presentation transport. "builtin" = CLI/TUI/gateway/ACP surfaces; a plugin
- # transport is used only when named explicitly. Transport timeout/error/invalid response
- # DENIES unless transport_fallback is "builtin". Presentation only: plugins cannot detect,
- # suppress, or auto-approve commands outside a correlated human response.
- "approval": {"transport": "builtin", "transport_fallback": "deny"},
- # Writes to agent-instruction files (AGENTS.md/CLAUDE.md/SOUL.md/.cursorrules, project-local
- # .hermes config) always need human approval, even under yolo. Extra patterns are fnmatch
- # globs on the basename (e.g. "*.mdc").
- "protected_instruction_files": True,
- "protected_instruction_extra_patterns": [],
- "website_blocklist": {"enabled": False, "domains": [], "shared_files": []},
- # IDs of supply-chain advisories the user has read and acted on; acked ones stop the startup
- # banner. Add via `hermes doctor --ack <id>`; remove by editing the list. Catalog:
- # hermes_cli/security_advisories.py.
- "acked_advisories": [],
- # Lazy-install opt-in backend packages from PyPI when a backend that needs them is first
- # enabled (e.g. `elevenlabs`). False = require explicit pip install for everything beyond
- # the base set (restricted/audited/air-gapped environments).
- "allow_lazy_installs": True,
- },
- "cron": {
- "catch_up_missed": True, # False skips recurring misses beyond the local grace window.
- # Let cron-spawned agents use the cronjob toolset (the "cron-librarian" pattern). Off by
- # default: policy-denied in cron context to prevent unattended scheduling loops. Jobs
- # created this way are user-owned in the same flat jobs table. Interactive toolsets
- # (messaging/clarify) stay denied in cron regardless.
- "allow_agent_scheduling": False,
- # Pre-dispatch validation: before building any agent machinery, verify the provider API key
- # resolves (unless a fallback chain exists), attached skills are ready, and delivery
- # platforms are configured. Failure -> last_status=blocked_config, ONE alert, no LLM call.
- # False = fail during the run instead.
- "preflight": True,
- # Default model for cron jobs (WHAT model runs). Fire-time resolution: per-job pin >
- # cron.model > model.default (the main agent model). An unpinned job follows the main
- # model on every run; cron.model decouples the whole fleet from chat. "" = fall through.
- "model": "",
- # Inference provider paired with cron.model (NOT the scheduler provider below). "" = resolve
- # from global config.
- "model_provider": "",
- # Cron SCHEDULER provider (WHEN a due job fires). "" = built-in in-process 60s ticker. Name
- # an installed provider (plugins/cron_providers/<name>/ or $HERMES_HOME/plugins/ <name>/),
- # e.g. "chronos" (NAS-mediated managed cron for scale-to-zero). An unknown or unavailable
- # provider falls back to the built-in so cron never loses its trigger.
- "provider": "",
- # Chronos settings; consulted only when provider == "chronos". All non-secret — the agent
- # holds NO scheduler credentials (provision reuses the Nous Portal token).
- "chronos": {
- # NAS/portal base URL that arms/cancels one-shots and mints the inbound fire JWT (used
- # as the expected issuer).
- "portal_url": "https://portal.nousresearch.com",
- # This agent's publicly reachable base URL; NAS POSTs {callback_url}/api/cron/fire. ""
- # -> Chronos unavailable, resolver falls back to the built-in ticker.
- "callback_url": "",
- "expected_audience": "", # Expected JWT audience (e.g. "agent:{instance_id}").
- # NAS JWKS URL for verifying the fire JWT signature. "" -> the fire endpoint refuses all
- # tokens (never an unsigned decode).
- "nas_jwks_url": "",
- },
- # Wrap delivered cron responses with a task-name header and "The agent cannot see this
- # message" footer. False = clean output.
- "wrap_response": True,
- "delivery": { # Delivery behaviour for cron output sent through a live gateway adapter.
- # Mark cron deliveries FINAL so the platform pushes them (Telegram's "important" mode
- # otherwise sends with disable_notification=True and briefs look undelivered). False =
- # silent, no-push deliveries.
- "notify": True,
- },
- # Make cron deliveries CONTINUABLE (user can reply to a brief with it in context). False
- # keeps deliveries isolated to the job's session; per-job `attach_to_session` overrides.
- # Thread-capable platforms (Telegram topics, Discord/Slack threads) get a seeded thread per
- # job via create_handoff_thread; DM-only platforms mirror the brief into the target DM
- # session. Appended at a turn boundary via mirror_to_session, cached system prompt
- # untouched. User-written bare platforms address home conversations, unlike `all`
- # broadcast expansions, which do not gain mirror eligibility.
- "mirror_delivery": False,
- # Max due jobs run in parallel per tick. None/0 = unbounded (thread count only); 1 = serial.
- # Env override: HERMES_CRON_MAX_PARALLEL.
- "max_parallel_jobs": None,
- # save_job_output keeps the N most recent .md files per job; 0 or negative disables pruning
- # (for externally managed cleanup).
- "output_retention": 50,
- # Timeout (seconds) for a no-agent cron script. Env: HERMES_CRON_SCRIPT_TIMEOUT. Keep in
- # sync with cron.scheduler._DEFAULT_SCRIPT_TIMEOUT.
- "script_timeout_seconds": 3600,
- # Timeout (seconds) for SessionDB() init inside cron jobs: state.db open/migrate has no
- # timeout of its own against a wedged sqlite3.connect, and an unbounded hang wedges the
- # job's dispatch guard forever. Env: HERMES_CRON_SESSION_DB_TIMEOUT. 0 = unlimited.
- "session_db_timeout_seconds": 10,
- # Timeout (seconds) per media attachment send during gateway delivery; large attachments
- # (long TTS audio, big exports) need more than 30s. Env: HERMES_CRON_MEDIA_SEND_TIMEOUT.
- # Keep in sync with cron.scheduler._DEFAULT_MEDIA_SEND_TIMEOUT.
- "media_send_timeout_seconds": 300,
- # Managed systemd gateway with no user session (containers, no linger): false runs
- # cron jobs as a direct external subprocess (warns once; no cgroup isolation), true
- # fails closed with the enable-linger remedy. Kanban always requires a scope.
- "require_restart_safe_scope": False,
- # A job failing with the SAME error alerts once, then stays silent for this many hours
- # before one reminder ping (the run is still recorded; `hermes cron incidents` shows it).
- # A green run or a different error alerts again immediately; `hermes cron incidents ack`
- # silences a signature for good. 0 = re-alert on every failing run. Keep in sync with
- # cron.scheduler.DEFAULT_FAILURE_REPEAT_ALERT_HOURS.
- "failure_repeat_alert_hours": 6,
- },
- # Kanban multi-agent coordination. The dispatcher ticks every N seconds, reclaims stale claims,
- # promotes dependency-satisfied todos to ready, and fires `hermes -p <assignee> chat -q ...` per
- # claimable task. Run ONE dispatcher per profile; two on the same kanban.db race for claims.
- "kanban": {
- # Auto-subscribe the originating gateway/TUI session to completion + block events when
- # kanban_create is called from a session with a persistent delivery channel. Disable for
- # profiles that prefer explicit kanban_notify-subscribe calls per task.
- "auto_subscribe_on_create": True,
- # Poll and deliver Kanban subscriptions from this gateway. Disable on profiles that do
- # not own notification subscriptions to avoid an idle five-second board probe.
- "notify_in_gateway": True,
- # Run the dispatcher inside the gateway process (~300µs per idle tick). False only if you
- # run it as a separate unit or don't want the gateway spawning workers.
- "dispatch_in_gateway": True,
- # Auto-claim tasks in the review column and spawn the assigned profile with the bundled
- # sdlc-review skill. Disable where every review is done manually from the dashboard.
- "review_dispatch": True,
- # Seconds between dispatcher ticks. Lower = snappier pickup; higher = less SQL pressure.
- "dispatch_interval_seconds": 60,
- # Auto-block after this many consecutive non-success attempts (spawn_failed, timed_out,
- # crashed) for the same task/profile. Reassignment resets the streak.
- "failure_limit": 2,
- # Worker stdout/stderr log rotation at spawn time (2 MiB + one backup). Raise to keep more
- # early failure evidence from long-running workers.
- "worker_log_rotate_bytes": 2 * 1024 * 1024,
- "worker_log_backup_count": 1,
- # Profile for the root/orchestration task after Triage decomposition; "" = default profile.
- # Does not control the decomposer LLM path (see auxiliary.kanban_decomposer).
- "orchestrator_profile": "",
- # Assignee when the orchestrator can't match one to an installed profile; "" = default
- # profile. A task never ends up with assignee=None.
- "default_assignee": "",
- # Global cap: positive int = the HOST never has more than N tasks 'running' across all
- # boards and both dispatch lanes. None = ~MemTotal / 512 MiB clamped to [2, 8]; where
- # MemTotal is unreadable (macOS/Windows) None means no cap.
- # Global concurrency cap (#33488): when set to a positive int, the HOST never has more than N tasks
- # in 'running' at once — counted across every active board and across both the ready and review
- # dispatch lanes (workers are OS processes sharing one machine's memory, so the cap bounds the
- # machine, not each board; OOF-30). Unset (None) means "derive from system memory" (OOF-30/OOF-77):
- # the dispatcher caps concurrency at roughly MemTotal / 512 MiB, clamped to [2, 8] — e.g. 2 workers
- # on a 1 GiB VM. On hosts where total memory can't be read (macOS/Windows), unset falls back to no
- # cap. Set an explicit value to override the derived default in either direction.
- "max_in_progress": None,
- # Per-profile cap: positive int = no single profile runs more than N workers even if the
- # global caps allow; blocked tasks defer to the next tick. None = no per-profile cap. Useful
- # when fan-out would saturate one profile's model/API quota/browser pool.
- # Unset (None) means "no per-profile cap" — backward-compatible with existing installs. Useful for
- # fan-out workflows that would otherwise saturate one profile's local model / API quota / browser
- # pool while leaving other profiles idle. See #21582.
- "max_in_progress_per_profile": None,
- # Per-home claim allowlist for boards shared across Hermes homes (#110995): profile names
- # this home's dispatcher may claim (list or comma-separated string). None = any existing
- # profile is claimable. Set = fail-closed (an empty list claims nothing). Every home has a
- # root profile named "default", so on a shared kanban.db every home can otherwise claim
- # default-assigned cards.
- "dispatch_profiles": None,
- # Auto-run the decomposer on Triage tasks every tick. False = manual via `hermes kanban
- # decompose <id>` or the dashboard's Decompose button.
- "auto_decompose": True,
- # Max triage tasks decomposed per tick, bounding the aux-LLM burst from a bulk load. Excess
- # defers to the next tick.
- "auto_decompose_per_tick": 3,
- # Running tasks with no heartbeat (last_heartbeat_at) for this many seconds are reclaimed to
- # ready on the next tick; a still-running local worker is terminated first. 0 = off.
- "dispatch_stale_timeout_seconds": 14400,
- # Each tick, requeue 'running' cards with broken claim bookkeeping (claim_lock or
- # claim_expires NULL with a dead worker) that TTL/crash/stale recovery can't see. False
- # keeps orphans frozen for manual forensics.
- "reconcile_orphans": True,
- # Notify subscriptions survive `done` (completion is reversible) and are removed on archive.
- # On boards that never archive, the notifier GC purges subscriptions for tasks done with no
- # activity for this many days so stale rows aren't scanned forever. 0 = off.
- "done_sub_retention_days": 30,
- },
- # Bot Mode cross-connection relay (tools/bot_relay.py): envelopes queued by message_agent for
- # agents on other connections wait in an on-disk outbox until the Desktop drains them.
- "bot_mode": {
- # Drain-time TTL (seconds): older envelopes are NOT delivered on drain; the sender gets an
- # error reply (reason 'queued_expired') so a DM can't land hours late as a zombie. 0 = no
- # drain-time expiry (the 6h stale-artifact sweep still applies).
- "envelope_ttl_seconds": 900,
- # How long a second delivery into a busy target profile queues behind the current turn
- # before failing with a structured 'target_busy' error. Deliveries are serialized per
- # profile with a cross-process file lock.
- "turn_wait_seconds": 120,
- },
- "code_execution": { # execute_code settings (programmatic tool calls).
- # project = run in the session cwd with the active venv/conda python so project deps and
- # relative paths resolve. strict = isolated temp dir with hermes-agent's own python
- # (sys.executable): max isolation, project deps/relative paths won't work. Env scrubbing
- # (*_API_KEY, *_TOKEN, *_SECRET, ...) and the tool whitelist apply in both modes.
- "mode": "project",
- # Session kernels are always on locally (`kernel_mode` is ignored) and remotely
- # (tools/code_kernel_remote.py; a backend that cannot spawn a kernel fails open to
- # per-call). One kernel per (session owner, mode, interpreter, cwd, tool-set) keeps state
- # across calls and turns; subagents get their own. Kernels die with the session, after
- # kernel_idle_timeout idle seconds, or by LRU eviction past max_session_kernels. A
- # timed-out/interrupted cell kills the kernel; env is frozen at spawn (reset=true after
- # changing passthrough). Tool RPC authority (approval, session, allow-list, call budget) is
- # rebound per cell — that runtime boundary is the cross-cell enforcement.
- "kernel_idle_timeout": 1800,
- "max_session_kernels": 4,
- },
- # Tool Search replaces deferred tools in the model-facing array with the
- # tool_search / tool_describe / tool_call bridges and surfaces them on demand.
- # Working-set core tools stay eager, while the explicit ``defer`` list below
- # may include cold, event-triggered built-ins as well as plugin/MCP tools.
- "tools": {
- "tool_search": {
- # Tiered: tier 0 (no deferred tools) = everything eager; tier 1 = bridge + a
- # name+description manifest when it fits the budget (degrades to names-only); tier 2
- # (over budget even names-only, e.g. ~3,300-tool APIs) = bare bridge + a
- # one-line-per-server summary (name + tool count). "auto"|"on" = activate when at least
- # one deferred tool exists ("auto" is an alias of "on" today, reserved for a future
- # budget-gated mode; keep it the default so explicit "on"/"off" pins are unaffected).
- # "off" = pass-through, no bridge.
- "enabled": "auto",
- # Listing budget as % of the model's context length; effective budget = min(this % of
- # context, listing_max_tokens). Range 0..100.
- "threshold_pct": 5,
- # Hits per query when the model omits `limit`. Range 1..max_search_limit.
- "search_default_limit": 5,
- # Hard upper bound the model may request via `limit` (per query). Range 1..50.
- "max_search_limit": 25,
- # Catalog listing embedded in the bridge description (name + first sentence ≤60 chars,
- # grouped by server/toolset). "auto" = include when it fits (falls back to names-only,
- # then bare tier-2 bridge); "on" = same rendering, explicit intent; "off" = always the
- # bare bridge.
- "listing": "auto",
- # Absolute cap on the embedded listing in tokens (chars/4), regardless of context size.
- # Range 200..60000.
- "listing_max_tokens": 4000,
- # Tools replaced by the bridge by default. This list intentionally includes cold,
- # event-triggered built-ins; an explicit list replaces it wholesale and [] keeps every
- # tool eager. The runtime fallback in tools/tool_search.py derives from this value.
- "defer": [
- "computer_use", "session_search", "image_generate",
- "todo_list", "process_manage", "cronjob_manage", "browser_vault",
- # Desktop GUI surface (desktop_ui, project and catalog toolsets)
- "drive_preview", "gui_tour", "desktop_preview", "annotate_preview", "manage_catalog",
- "show_tip", "desktop_project", "close_terminal",
- "set_theme", "read_terminal", "read_window_below", "focus_pane",
- ],
- },
- # Remote connector discovery/lifecycle through the Nous tool gateway.
- # The flag is the user's off switch; availability additionally requires
- # the portal sign-in every managed tool gates on.
- "connectors": {"enabled": True},
- },
- "logging": { # File logging to ~/.hermes/logs/: agent.log captures INFO+, errors.log WARNING+.
- "level": "INFO", # minimum level for agent.log: DEBUG, INFO, WARNING
- "max_size_mb": 5, # max size per log file before rotation
- "backup_count": 3, # rotated backups to keep
- },
- # Remote model-catalog manifest: curated OpenRouter / Nous Portal model lists fetched from this
- # URL (falls back to the in-repo snapshot on network failure), so picker lists update without a
- # release. Default URL is served by the docs-site GitHub Pages deploy.
- "model_catalog": {
- "enabled": True,
- "url": "https://hermes-agent.nousresearch.com/docs/api/model-catalog.json",
- # Disk cache TTL in minutes. The gateway refreshes in the background on this cadence; the
- # CLI refetches on the next /model or `hermes model` once the cache is older. Network
- # failures silently use the stale cache. Legacy `ttl_hours` is honoured if set.
- "ttl_minutes": 20,
- # Per-provider override URLs for self-hosted curation lists using the same schema, e.g.
- # providers: {openrouter: {url: https://example.com/my-curation.json}}.
- "providers": {},
- },
- # Per-model metadata overrides. Fields: context_window, supports_tools,
- # supports_vision, supports_reasoning, model_family. <provider>.<model_id> wins over
- # models.dev/OpenRouter/hardcoded defaults for the fields it sets (chain order in
- # agent/model_metadata.py). <provider>._default and top-level _default fill gaps ONLY for models
- # the catalog does not know, so they never clamp known models. Unknown ids start from safe
- # defaults (200K context, tools on) and get patched; supports_vision / supports_reasoning stay
- # UNKNOWN (fail-open) unless the override sets them — a context_window-only entry must not turn
- # into "text-only" and hide vision_analyze / reasoning controls (#112649). Provider keys: Hermes
- # or models.dev id; model ids match case-insensitively. Example: {"custom:my-local-vllm":
- # {"my-llava-model": {"context_window": 8192}}}
- # Semantics: 1. NOTE: an explicit model.context_length (global) and a custom_providers per-model
- # context_length are user settings at other layers and are consulted in the resolution chain order
- # documented in agent/model_metadata.py. 2. See #84482, #8731.
- "model_overrides": {},
- # models.dev registry (context windows, capabilities, pricing, modalities): fetched on startup,
- # served from cache, refreshed by a background daemon with ETag conditional GET. Override `url`
- # to point at a mirror (e.g. behind a corporate proxy).
- "models_dev": {
- "url": "", # empty = default https://models.dev/api.json
- },
- "network": {
- # Force IPv4. With broken/unreachable IPv6, Python tries AAAA first and hangs for the full
- # TCP timeout before falling back. True skips IPv6 entirely.
- "force_ipv4": False,
- },
- # Gateway monitoring: service health + redacted operational diagnostics exported over OTLP to an
- # operator endpoint (OTEL Collector, DataDog, ...). Content-free by construction: no prompts,
- # messages, tool args/results, session history, usage analytics, audit logs, or trajectories.
- # Nothing is collected or sent until enabled with an endpoint.
- "monitoring": {
- # Stable install identifier on exported signals so operators can tell instances apart. "" =
- # mint a fresh UUID on first use; clear it to rotate. Carries no account identity.
- "install_id": "",
- "gateway_health_export": { # Gateway health & diagnostics export.
- "enabled": False,
- "metrics_enabled": True,
- "diagnostic_events_enabled": True,
- "warning_error_events_enabled": True,
- "export_interval_seconds": 60,
- "logs_export_interval_seconds": 5,
- "resource_attributes": {
- "service.name": "hermes-gateway", "deployment.environment.name": "production"
- },
- },
- # OTLP destination. headers_env maps header names to ENVIRONMENT VARIABLE NAMES (never
- # secret values); values are read from the environment at export time.
- "export": {"otlp": {"enabled": False, "endpoint": "", "headers_env": {}}},
- },
- # Native hosted-room Discussion ceilings, shared by all members per discussion.
- # Positive integers only (no unlimited/0). Read from the root owner's config at service
- # startup for all hosted rooms; restart the owning service after changing them.
- "hosted_rooms": {
- "discussion": {
- "max_rounds": 3,
- "max_messages": 10,
- },
- },
- "gateway": { # Gateway settings (messaging platforms: Telegram, Discord, Slack, ...).
- "unmanaged_idle_exit_seconds": 600, # client-auto-started gateway only; 0 disables
- # Seconds a SIGTERM-interrupted agent unwinds before teardown (short: service stop budgets).
- "signal_interrupt_grace_timeout": 1,
- "service_install_choice": None, # null | install | decline; never authorizes ordinary launch installation.
- # Durable delivery-obligation ledger: final responses are recorded in state.db around the
- # platform send; a gateway that died between finalize and platform ACK redelivers on next
- # boot (ambiguous cases carry a "recovered reply — may be a duplicate" marker;
- # at-least-once). Disable to lose in-flight final responses on crash/restart.
- "delivery_ledger": True,
- # Seconds to wait for one platform to connect at startup/reconnect; raise on "discord
- # connect timed out" loops (many slash commands to sync). 0/negative = wait forever. Bridged
- # to HERMES_GATEWAY_PLATFORM_CONNECT_TIMEOUT, which wins if set explicitly.
- # Seconds the gateway waits for a single messaging platform to finish connecting during startup (and
- # on reconnect). Discord in particular can blow past the old fixed 30s when an account has many
- # slash commands to sync (#19776: 90-173 skills → ~28-31s sync). Raise this if your gateway hits
- # "discord connect timed out" / "Timeout waiting for connection to Discord" restart loops. ``0`` or
- # negative disables the timeout entirely (wait indefinitely).
- "platform_connect_timeout": 30,
- # Event-loop liveness watchdog: a daemon thread probes the asyncio loop; after consecutive
- # missed probes it dumps all-thread stacks and hard-exits with the service-restart code so
- # systemd/launchd revives the process instead of leaving a wedged-but-alive zombie.
- # Set to false to disable. See #69089.
- "loop_watchdog": True,
- # Watchdog tuning (defaults mirror gateway/shutdown_watchdog.py): probe_interval = seconds
- # between probes; probe_timeout = seconds before an unprocessed probe counts as a miss;
- # max_strikes = consecutive misses before hard-exit 75 (~90-120s of sustained loop block at
- # the defaults).
- "loop_watchdog_probe_interval_s": 30.0,
- "loop_watchdog_probe_timeout_s": 10.0,
- "loop_watchdog_max_strikes": 3,
- # Allow all users without allowlists (security opt-in).
- "allow_all_users": False,
- # Bot-to-bot loop guard: max_events per window before a cooldown; max_hops bot messages per exchange.
- "bot_loop_guard": {"enabled": True, "max_events": 20, "window_seconds": 300, "cooldown_seconds": 600, "max_hops": 4, "bot_replies_expect_reply": False},
- # Startup-liveness watchdog: stdlib-only daemon thread armed at process entry that
- # hard-exits 75 if the loop isn't live within the deadline. Armed before config loads, so
- # run_gateway() bridges these to HERMES_STARTUP_WATCHDOG / HERMES_STARTUP_WATCHDOG_TIMEOUT_S
- # and re-arms the live handle; explicit env wins.
- "startup_watchdog": True,
- "startup_watchdog_timeout_seconds": 300,
- # Keep writing the legacy ~/.hermes/sessions/sessions.json mirror of the routing index
- # (primary copy: state.db gateway_routing table). True for external tooling and downgrade
- # safety; False stops producing the file.
- "write_sessions_json": True,
- # One gateway for every profile on this host: the DEFAULT profile's gateway also connects
- # each named profile's bots (their own .env / config.yaml, per-profile secret scope) and
- # stamps the profile into session keys. This is the ONLY supported topology — there is no
- # `false` opt-out any more: an explicit `false` still parses (it is the runtime mode flag
- # every scoped code path reads) but is warned about and IGNORED for process topology, and
- # `hermes gateway migrate --multiplex` folds any per-profile fleet that is left.
- # An UNSET key is a request, not a verdict: at boot the gateway runs the migration
- # preflight and stays standalone (logging why) while a secondary still runs its own
- # gateway or a blocker exists, then converges once that is resolved.
- # TWO things DO change on a host that had pinned `false`, and neither is a process:
- # • INGRESS — `/p/<profile>/` on the default listener goes 404 -> served
- # (gateway/api_server.py::_resolve_request_profile, gateway/webhook.py). A host that
- # opted out GAINS that HTTP surface; it is authenticated exactly like the default
- # profile's, but it is new reachable surface, so audit any reverse proxy that assumed
- # /p/ was dead.
- # • SECRET SCOPE — eager multi-profile activation no longer consults the flag
- # (tui_gateway/launch_profile_policy.py), so a host with a leftover servable profile
- # dir flips eager=false/reads-open -> eager=true/fail-closed: an UNSCOPED `get_secret`
- # now raises UnscopedSecretError, and a key that lives ONLY in the unit's
- # `Environment=` (no .env) disappears from file-built scopes. A genuinely
- # single-profile host never activates and is byte-identical.
- # Two profiles configuring the same bot token cannot be served together — the duplicate
- # adapter is parked; `hermes profile create --clone` therefore leaves messaging channels
- # behind unless --clone-channels is passed.
- "multiplex_profiles": True,
- # May `hermes update` fold this install onto a multiplexed default gateway by itself?
- # True (the default) keeps today's behaviour: a multi-profile install whose secondaries run
- # their own gateways is migrated automatically after an update when nothing blocks it.
- # Set to False to choose WHEN you converge, not whether: the fold is left to you to run by
- # hand (it is not an opt-out from the one-gateway-per-host model, which has none). Only the
- # AUTOMATIC path reads this: `hermes gateway migrate --multiplex` is explicit and proceeds.
- "auto_multiplex_migration": True,
- # Route inbound chats of the default profile's bots to another profile
- # (gateway/profile_routing.py): [{profile, platform, chat_id|user_id|guild_id|...}].
- # Most-specific match wins; only read by the multiplexing default gateway.
- "profile_routes": [],
- # Scale-to-zero idle TIMEOUT only. When an instance is opted in via the NAS "Labs" toggle
- # (HERMES_SCALE_TO_ZERO env stamp) AND messaging is relay-only/absent AND a wakeUrl is
- # registered, the relay transport goes dormant so the platform (e.g. Fly autostop) can
- # suspend the machine; it wakes on the wakeUrl poke. Enablement is the Labs toggle, never a
- # config key. 0/negative = default.
- "scale_to_zero": {"idle_timeout_minutes": 2},
- # Auto-resume restart-loop breaker. A supervisor-revived gateway auto-resumes the
- # SIGTERM-interrupted session; if that turn keeps triggering the kill, boots no more than
- # `max_gap_seconds` apart (floored by `window_seconds`) chain, and after `max_restarts`
- # auto-resume is SKIPPED for that boot (inbound messages still served). Gap-based chaining
- # also catches SLOW ~150s crash cycles. max_restarts=0 disables.
- "restart_loop_guard": {"max_restarts": 3, "window_seconds": 60, "max_gap_seconds": 300},
- # Respawn-storm circuit breaker (complements restart_loop_guard): counts (re)starts in a
- # sliding window and sleeps an exponential backoff before booting so a crash-looping
- # supervisor can't hammer the process. max_starts <= 0 disables. Env escape hatches:
- # HERMES_GATEWAY_MAX_STARTS / HERMES_GATEWAY_START_WINDOW_S.
- "respawn_storm": {"max_starts": 5, "window_seconds": 120},
- # Prefix user messages IN THE MODEL'S CONTEXT with a timestamp (e.g. "[Tue 2026-04-28
- # 13:40:53 CEST]") for temporal awareness. Persisted transcripts stay clean (timestamp is
- # message metadata regardless), so enabling later surfaces past send-times too.
- "message_timestamps": {"enabled": False},
- # Max bytes of inbound image/audio/video the gateway buffers into RAM and caches to disk.
- # Media is read fully into memory first, so unbounded uploads (Discord Nitro: 500 MB) or
- # huge remote URLs can OOM-kill constrained deployments. Enforced in
- # gateway/platforms/base.py for every adapter. 0 = no cap. Default 128 MiB.
- "max_inbound_media_bytes": 134217728,
- # Let adapters read HTTP_PROXY/HTTPS_PROXY/NO_PROXY/SSL_CERT_FILE from the environment and
- # auto-detect generic/macOS system proxies. False when the gateway inherits a proxy it must
- # not use (e.g. a scheduled task picking up a Clash/V2Ray HTTP_PROXY -> "Cannot connect to
- # host 127.0.0.1:7890"). Per-platform vars (DISCORD_PROXY, TELEGRAM_PROXY, ...) are still
- # honored.
- "trust_env": True,
- # Media delivery. False: any emitted file path is delivered natively unless under the
- # credential/system denylist (/etc, /proc, ~/.ssh, ~/.aws, ~/.hermes/.env, auth.json). True:
- # files must be under the Hermes cache, media_delivery_allow_dirs, or fresher than
- # trust_recent_files_seconds — recommended for public-facing gateways so prompt injection
- # can't exfiltrate host secrets. Bridged to HERMES_MEDIA_DELIVERY_STRICT.
- "strict": False,
- # Extra roots (project/scratch dirs, mounted shares) from which bare file paths may be
- # uploaded; the Hermes cache is always trusted. List of absolute paths or one
- # os.pathsep-separated string; tildes expanded. Bridged to HERMES_MEDIA_ALLOW_DIRS. Honored
- # in both modes.
- "media_delivery_allow_dirs": [],
- # Trust files whose mtime is within trust_recent_files_seconds even outside the cache/
- # allowlist (e.g. `pandoc -o /tmp/report.pdf`); system paths stay blocked. False =
- # pure-allowlist mode. Bridged to HERMES_MEDIA_TRUST_RECENT_FILES. Only consulted when
- # strict is true.
- "trust_recent_files": True,
- # Recency window in seconds; 600 covers a multi-tool turn. Bridged to
- # HERMES_MEDIA_TRUST_RECENT_SECONDS. Only consulted when strict is true.
- "trust_recent_files_seconds": 600,
- "api_server": { # OpenAI-compatible API server platform (gateway/platforms/api_server.py).
- # Max concurrent agent runs. Requests to /v1/chat/completions, /v1/responses, and
- # /v1/runs beyond this get HTTP 429 + Retry-After, bounding CPU/memory/LLM-quota
- # exhaustion from a request flood. 0 = no cap.
- "max_concurrent_runs": 10,
- # Cap (chars) on each tool output and tool-call argument string in the stored
- # /v1/responses conversation history used for previous_response_id chaining. The
- # stored history is cumulative, so a few large tool outputs can make one
- # response_store.db write several hundred KB. 0 = store tool outputs verbatim
- # (default: the capped text is what the model is replayed on the next turn).
- "history_tool_output_max_chars": 0,
- },
- },
- # Real-time token streaming to messaging platforms (gateway; restart after enabling). Off by
- # default: costs extra edit/draft API calls per response.
- "streaming": {
- "enabled": False, # When false, each response is delivered as one final message.
- # auto = native drafts where supported (Telegram DMs, Bot API 9.5+), edits elsewhere
- # (Discord, Slack, Matrix, Telegram groups); draft = drafts with edit fallback; edit =
- # progressive editMessageText only; off = disabled.
- "transport": "auto",
- # Minimum seconds between progressive edits (Telegram's ~1 edit/s flood envelope).
- "edit_interval": 0.8,
- # Flush the buffer once this many chars accumulate, so short replies feel instant.
- "buffer_threshold": 24,
- "cursor": " \u2589", # Cursor glyph appended to the in-progress message.
- # Telegram only: when >0, if the preview was visible at least this many seconds the final
- # edit is sent as a fresh message so the timestamp reflects completion.
- "fresh_final_after_seconds": 0.0,
- },
- # Automatic cleanup of ~/.hermes/state.db, which otherwise grows without bound and slows FTS5
- # inserts, /resume listing, and insights queries.
- "sessions": {
- # Prune ENDED sessions inactive for retention_days (activity = freshest of live activity /
- # latest message / creation) about once per min_interval_hours at CLI/gateway/cron startup.
- # Open, pinned, or mid-turn sessions are never deleted; stale automation sessions whose
- # process died are *closed*, then get a full retention window before removal.
- # Off by default (deleting history is opt-in). While the user's config.yaml has no
- # auto_prune key, every surface asks once the disk holding state.db runs low
- # (hermes_cli/prune_advisor.py); either answer writes the key and ends the question.
- "auto_prune": False,
- # Inactive days of ended-session history to keep (= `hermes sessions prune`).
- "retention_days": 90,
- # Auto-archive (soft-hide, never delete) sessions with no activity for auto_archive_days,
- # once per min_interval_hours. Pinned sessions are exempt.
- "auto_archive": False,
- # Idle days before auto-archive hides a session (only when auto_archive is true).
- "auto_archive_days": 3,
- # List delegate_task subagent runs in session lists (desktop sidebar, dashboard, session.list),
- # nested under their parent. Off by default: they are machinery, not conversations.
- "show_subagents": False,
- # VACUUM after a prune that deleted rows (SQLite never reclaims disk on DELETE, #54189). It blocks
- # writes (~seconds per 100MB): only at startup, only when ≥1 session went AND freelist/page_count > 25%.
- "vacuum_after_prune": True,
- # Minimum days between VACUUM rewrites; pruning keeps its normal cadence.
- "min_vacuum_interval_days": 30,
- # Minimum hours between auto-maintenance runs (tracked in state.db state_meta, shared across
- # processes).
- "min_interval_hours": 24,
- # Notice about the compact FTS layout (reclaims ~60%+ of state.db). OPT-IN: legacy indexes
- # stay until `hermes sessions optimize-storage` runs, since the rebuild is disk-heavy on
- # large DBs. advise = `hermes update` prints a one-line notice with reclaimable size when a
- # legacy index is detected (a later layout change gets a rebuild notice without a size estimate);
- # require = the same notices worded as REQUIRED (tooling may gate on it); off = none.
- "fts_optimize_notice": "advise",
- # CJK-bigram search index (messages_fts_cjk). When the extension is built
- # (native/fts5_cjk/build.sh → ~/.hermes/lib/libfts5_cjk.so), 1-2 char CJK terms get exact
- # index matches instead of LIKE scans. True = use when present (inert otherwise); False =
- # never load/serve it. Bridged to HERMES_CJK_FTS.
- "cjk_fts": True,
- # Slow session-search threshold (ms): searches at/above it log one INFO line with the
- # routing path (fts_cjk / fts5 / trigram / like_scan). 0 logs every search. Bridged to
- # HERMES_SEARCH_SLOW_MS.
- "search_slow_ms": 1000,
- # Transcript guards (a runaway 100k+ row session can exhaust memory when materialized at
- # once; 0 disables). Max active messages (across the compression lineage) for interactive
- # resume.
- "max_resume_messages": 20000,
- # Max active messages per session for in-memory export (`hermes sessions export`); checked
- # per session, so full-DB backups of small sessions work.
- "max_export_messages": 20000,
- # Seconds before a local session with no viewer is ended (resumable) once its turn settles; 0 = never; after a
- # restart also >= 6h idle. Unset: dashboard.ws_orphan_reap_grace_s: 0 / startup_orphan_sweep: false opt out.
- "orphan_end_grace_s": 300.0,
- },
- # First-touch onboarding hints (agent/onboarding.py), each latched under `seen` once shown.
- "onboarding": {
- "seen": {},
- "profile_build": "ask", # first-ever message: ask = offer; off = plain intro only
- # Desktop first run, root profile only (onboarding_run.py): None = fresh install; true = next launch; false = done
- "run": None,
- },
- # Privacy-safe aggregate metrics in this profile's local telemetry dir. Collection (`enabled`)
- # and upload to Nous (`send`) are separate keys that every consent surface sets together; see
- # website/docs/developer-guide/relay-shared-metrics.md Appendix A for consent/retention.
- "telemetry": {
- "shared_metrics": {
- "enabled": False,
- # Requires `enabled` (`send` alone logs an error). A package is sent only if its whole
- # period is inside a recorded consent window.
- "send": False,
- # Ingest endpoint (override for staging/local). Deliberately NOT env- overridable.
- # Non-HTTPS refused unless the host is localhost.
- "endpoint": "https://telemetry.nousresearch.com/v1/telemetry",
- },
- },
- "doctor": {
- # Per-probe timeout (seconds) for `hermes doctor --live` real-call probes.
- "live_probe_timeout": 10,
- },
- "updates": {
- # Passive version/banner checks only; explicit `hermes update --check` remains enabled.
- "check": True,
- # Pre-update backup. quick = snapshot small critical state (pairing JSONs, cron jobs,
- # config.yaml, .env, auth.json, profile DBs) into <HERMES_HOME>/state-snapshots/, skipping
- # files >1 GiB; restore via ``/snapshot``. full = quick PLUS a ``hermes backup`` zip in
- # <HERMES_HOME>/backups/ (``hermes import`` restores; slow on large homes; ``--backup``
- # forces once). off = none (``--no-backup`` forces once). Legacy booleans: true -> full,
- # false -> off.
- # Pre-update safety backup — ONE consolidated mechanism, three modes: Files over 1 GiB (e.g. a
- # bloated state.db) are skipped with a warning so the snapshot stays fast. This is the #48200
- # (wrong-path wipe) safety net.
- "pre_update_backup": "quick",
- # Full backup zips to retain (older pruned after each success; floored to 1 so the newest is
- # always kept). The quick snapshot always keeps exactly 1.
- "backup_keep": 5,
- # Uncommitted source-tree changes during NON-interactive updates (desktop, gateway — no TTY;
- # interactive updates always stash and ask). stash = stash, pull, restore on top (conflicts
- # stay in a git stash). discard = stash and drop after the pull (stash-and-drop, not reset
- # --hard + clean -fd, so ignored paths like node_modules/venv are never touched).
- "non_interactive_local_changes": "stash",
- # If the checkout is parked on a feature branch and the tree is clean, switch to the update
- # target (commits stay on the branch; a loud notice names it) so non-interactive updates
- # keep working. A DIRTY tree blocks the switch and the code update is SKIPPED with a loud
- # warning. False = never auto-switch.
- "auto_switch_parked_branch": True,
- # Clean parked branch with unmerged commits: switch = move to the update target, commits
- # stay on the branch (never conflicts). update_in_place = for a maintained custom branch:
- # merge origin/<target> INTO it after leaving a pre-update-<stamp> tag; a conflict stops the
- # update cleanly. `hermes update --switch-branch` overrides to switch for one run.
- "parked_branch_strategy": "switch",
- # Refresh an installed cua-driver during `hermes update` (best-effort, macOS only). Turn off
- # e.g. on non-admin accounts where /Applications isn't writable.
- "refresh_cua_driver": True,
- },
- # LSP diagnostics (pyright, gopls, rust-analyzer...) in the post-write lint check of
- # write_file/patch. Runs only when the cwd or edited file is inside a git worktree; otherwise
- # dormant and the in-process syntax check is the only tier.
- "lsp": {
- "enabled": True, # False disables the whole subsystem: no servers, no event loop, no cost.
- # document = wait up to wait_timeout seconds for the current file's diagnostics; full = also
- # request workspace-wide diagnostics (slower).
- "wait_mode": "document",
- "wait_timeout": 5.0,
- # Budget for the FIRST request against a workspace whose server is not running yet (spawn +
- # initialize + the server's initial program build; tsserver on a large project can need a
- # minute). Once the client is up, wait_timeout applies again. 0 = same as wait_timeout.
- "warmup_timeout": 0.0,
- # After a server fails (spawn error or outer timeout) its (server, workspace root) pair is
- # skipped. 0 = for the process lifetime (until `hermes lsp restart`); N = retried after N
- # seconds, so one transient stall does not silence a workspace forever.
- "broken_retry_seconds": 0.0,
- # Workspace roots (glob patterns, ~ expanded; a bare path also matches everything under
- # it) where no language server runs at all, e.g. one huge monorepo whose server cannot
- # finish in budget, while every other workspace keeps its diagnostics. Must be a list —
- # any other shape logs a warning and skips LSP for every workspace until fixed.
- "exclude_roots": [],
- # Directories (~ expanded; everything under an entry counts) whose projects a language
- # server may load code from: the project's own .venv/venv interpreter, node_modules
- # TypeScript SDK, svelte.config.js, build files (cargo, Gradle, mix, ...). The worktree of
- # the launch dir or the session's workspace (hermes -w, a Desktop project, terminal.cwd) is
- # always trusted; in any other checkout (a clone the agent made) only servers that run no
- # project code start, pinned to Hermes-side tools, and the npx tsc / rustfmt lint fallbacks
- # are skipped.
- "trusted_workspaces": [],
- # Missing server binaries: auto = install via npm/go/pip into <HERMES_HOME>/lsp/bin/ on
- # first use; manual = only binaries on PATH; off = alias for manual.
- "install_strategy": "auto",
- # Node package manager for the npm-recipe servers: npm | pnpm | yarn. Installs still land in
- # <HERMES_HOME>/lsp/node_modules; a configured manager that is not installed, or an unknown
- # value, skips the install (no silent fallback to npm) so a pnpm/yarn supply-chain policy is
- # never bypassed.
- "package_manager": "npm",
- # Idle seconds before a server is shut down (respawned on demand), so long- running
- # processes don't accumulate stale children (hundreds of MB + pipe FDs each) across
- # worktrees. 0 = keep servers for process lifetime.
- "idle_timeout": 600.0,
- # Per-server overrides keyed by registry server_id (pyright, gopls...): disabled: true;
- # command: ["path/to/server", "--stdio"] (bypasses auto- install); env: {...};
- # initialization_options: {...} (merged into LSP initializationOptions).
- # A key that is NOT a built-in id declares a custom server (matched before the built-ins):
- # command: ["my-ls", "--stdio"]; extensions: [".ext"]; optional root_markers: [...],
- # language_id: "..." (didOpen languageId), description: "...". Manual install only.
- "servers": {},
- },
- # X (Twitter) Search via xAI's x_search Responses tool. Registers when xAI creds exist
- # (SuperGrok OAuth or XAI_API_KEY) AND the toolset is enabled in `hermes tools`.
- "x_search": {
- # xAI model for the Responses call; any Grok model with x_search access works.
- "model": "grok-4.5",
- # Reasoning effort for models that support it; null keeps the model default.
- "reasoning_effort": None,
- # Request timeout in seconds (minimum 30); complex queries can take 60-120s.
- "timeout_seconds": 180,
- # Retries on 5xx / ReadTimeout / ConnectionError (backoff 1.5x attempt s, cap 5s).
- "retries": 2,
- },
- # External secret sources — pull credentials from secret managers at startup instead of storing
- # them in ~/.hermes/.env.
- # Browser credential vault: which login sources browser_vault may draw from. The local
- # encrypted vault (`hermes vault add`, Desktop → Settings → Credential Vault) is always on.
- # External password managers are unlocked per session with a masked master-password prompt;
- # headless sessions (cron, webhook, API) never prompt and see them as locked.
- "vault": {
- "key_storage": "file", # NEW vault's key: file (0600 vault.key) | keychain (OS; file if none). See `hermes vault key`.
- "onepassword": { # detected managers are login sources unless the user opts out (enabled: false)
- "enabled": True, # `op` CLI: Login items with a website URL become fillable handles.
- "account": "", # account shorthand for `op --account`; empty = default account.
- "binary_path": "", # absolute path to op; empty = PATH.
- # Env var holding a service-account token (headless auth, no unlock prompt). Unset = prompt.
- "service_account_token_env": "OP_SERVICE_ACCOUNT_TOKEN",
- },
- "bitwarden": {
- "enabled": True, # `bw` CLI (Password Manager, not Secrets Manager); run `bw login` once first.
- "binary_path": "", # absolute path to bw; empty = PATH.
- },
- },
- "secrets": {
- # Optional ordering of enabled sources (e.g. [onepassword, bitwarden]); default registration
- # order. Mapped sources (explicit VAR→ref) always beat bulk sources (BSM project dumps);
- # first claim on a var wins, later ones warn. "sources": [],
- "bitwarden": {
- "enabled": False, # When false, BSM is never contacted and bws is never auto-installed.
- # Env var holding the machine-account token — the one bootstrap secret; lives in
- # ~/.hermes/.env (or the shell), never in config.yaml.
- "access_token_env": "BWS_ACCESS_TOKEN",
- "project_id": "", # UUID of the BSM project to sync from.
- # Seconds to reuse a fresh disk/memory cache entry before contacting Bitwarden again. 0
- # disables fresh-cache reuse.
- "cache_ttl_seconds": 300,
- # Last-good fallback for NETWORK/TIMEOUT outages: AES-GCM cache under ~/.hermes/cache/,
- # reused up to max_stale_seconds. Auth failures never fall back.
- "encrypted_cache": {"enabled": False, "max_stale_seconds": 0},
- # BSM values overwrite existing env vars, so rotating in Bitwarden takes effect without
- # clearing the matching .env line.
- "override_existing": True,
- # Auto-download bws into ~/.hermes/bin/ on first use; False = bws must be on PATH.
- "auto_install": True,
- # Passed to bws as BWS_SERVER_URL. Empty = US Cloud (bws default);
- # https://vault.bitwarden.eu for EU; your own URL for self-hosted.
- "server_url": "",
- },
- "onepassword": {
- "enabled": False, # When false, the op CLI is never invoked.
- "env": {}, # env-var name → op://vault/item/field; each resolved with one `op read`.
- # Account shorthand / sign-in address for `op read --account`; empty = default.
- "account": "",
- # Env var holding a service-account token for headless auth (exported to op as
- # OP_SERVICE_ACCOUNT_TOKEN). Unset = interactive/desktop op session.
- "service_account_token_env": "OP_SERVICE_ACCOUNT_TOKEN",
- # Absolute path to op, used verbatim (avoids trusting PATH). Empty = PATH.
- "binary_path": "",
- # Seconds to cache values in-process and on disk; 0 disables BOTH layers.
- "cache_ttl_seconds": 300,
- # Overwrite existing env vars so rotation takes effect; False lets .env win.
- "override_existing": True,
- },
- },
- # Paste collapse thresholds (TUI + CLI); 0 disables each. threshold: bracketed pastes with this
- # many newlines collapse to a file reference. fallback: same test for terminals without
- # bracketed paste, gated by chars/newlines-added heuristics. char_threshold: single-line pastes
- # this long collapse too.
- "paste_collapse_threshold": 5,
- "paste_collapse_threshold_fallback": 5,
- "paste_collapse_char_threshold": 2000,
- # Bot Desktop: a headless Xfce screen per profile on the gateway host (Linux), streamed to Hermes
- # Desktop where a human can watch, take over (logins, 2FA, CAPTCHAs) and hand back. `hermes computer-use screen`.
- "bot_desktop": {
- "geometry": "1440x900",
- # Opt-in: start the screen automatically the first time computer_use needs a display on a headless
- # host. Off by default so installing TigerVNC for other reasons never yields a screen nobody asked
- # for; Hermes Desktop's Screen pane offers Start and this toggle.
- "auto_start": False,
- # Refuse to start below this much free memory (MB), measured on the host or its container cgroup,
- # whichever is tighter. Xvnc + Xfce idle at ~220 MB and a takeover's browser adds 0.5-1 GB, so a
- # screen with one page runs past 1 GB; the kernel OOM killer picks its victim by score, so on a
- # small instance the loser is the dashboard or the gateway rather than the desktop. 0 disables the
- # check.
- "min_free_memory_mb": 1536,
- # Stop a screen nobody has used (no computer_use action, browser spawn, viewer or takeover) for this
- # long; it restarts on the next use. Idle Xvnc + Xfce hold ~220 MB, an abandoned browser far more.
- # 0 keeps screens up until stopped.
- "idle_stop_minutes": 30,
- # Where the screen (and with it computer_use and the bot's browser) runs.
- # auto follow the terminal backend: inside the docker / ssh / streaming plugin sandbox when one is
- # configured, on the gateway host when terminal.backend is local. A sandbox backend that
- # cannot host a screen (modal, daytona, vercel) REFUSES rather than quietly running the
- # desktop on the host beside the sandbox you chose for the agent.
- # terminal always inside the terminal backend (error when it cannot host one).
- # gateway always on the gateway host, even with a sandbox terminal: the agent's screen, browser
- # and computer_use then act OUTSIDE the terminal sandbox. Explicit opt-in.
- # The sandbox image needs the desktop stack: nousresearch/hermes-sandbox:desktop.
- "placement": "auto",
- },
- "computer_use": {
- # cua-driver's upstream PostHog telemetry defaults ON; Hermes sets
- # CUA_DRIVER_RS_TELEMETRY_ENABLED=0 in every child env unless this is true.
- "cua_telemetry": False,
- # Windows only: opt IN to the per-boot cua-driver-serve logon task. False (default)
- # keeps the driver on-demand — Computer Use starts it per session, exactly as on
- # macOS/Linux, and install/enable flows register no scheduled task (#97389). True
- # registers (or repairs) the task at install time — needed to drive Windows over SSH,
- # where Session 0 has no interactive desktop (see the computer-use guide).
- "autostart": False,
- "native_wayland": False,
- # Cap driver screenshot longest edge (pixels) via set_config at session start; shrinks SOM
- # multimodal payloads. 0 disables.
- "max_image_dimension": 1456,
- # capture_after mode: som = screenshot + overlays; ax = elements only, no PNG (faster);
- # vision = pixels only.
- "capture_after_mode": "som",
- # Bound cua-driver's accessibility-tree WALK on every capture (get_window_state max_elements).
- # _DEFAULT_MAX_ELEMENTS in tools/computer_use/tool.py caps the SURFACED element list at 100 and
- # spills the rest to a cache file, so an unbounded walk pays for nodes the model never sees:
- # measured on macOS (cua-driver 0.28.2, M-series) a 1,444-node Chrome window went 540 ms -> 83 ms
- # and a 456-node Finder window 6.9 s -> 0.6 s at 200, with the returned elements a prefix of the
- # unbounded walk. 0 = driver default (2,000 elements / depth 25) — the pre-fix behaviour.
- # ~400 keeps the full first 100 visible elements on a pathological tree, at ~1.4 s on Finder;
- # the walk's cost grows with the bound, so keep it in the low hundreds. This caps the nodes
- # COLLECTED, not the walk's wall clock: a target whose AX surface exceeds the driver's own 20 s
- # walk timeout still fails at every bound (measured; a depth bound does not help there either).
- "ax_max_elements": 200,
- # Disable cua-driver's cursor overlay, which can peg a core when idle (macOS redraw loop;
- # Linux/WSL2 idle spin). None = auto (off on macOS + headless/ WSL2 Linux, on elsewhere);
- # True = always disable; False = always enable.
- # The overlay shows where agent actions land but can peg a core when idle (macOS vImage redraw loop
- # #47032; Linux/WSL2 idle spin #28152). cua-driver ≥ 0.6.x supports --no-overlay; Hermes also calls
- # set_agent_cursor_enabled(false) after start_session when this is on.
- "no_overlay": None,
- # standard = cua-driver's own approval boundary; bounded = no runtime prompts, anything
- # outside capability_manifest fails closed. `unrestricted` is NOT accepted here: it stays on
- # the per-session YOLO toggle so config can't bypass approvals.
- "permission_mode": "standard",
- # Path (~ ok) to the reviewed manifest for permission_mode bounded; passed as
- # --capability-manifest. See cua.ai/docs/reference/cua-driver/permission-modes
- "capability_manifest": "",
- # macOS only: allow an UNSIGNED CuaDriver.app for the private-session daemon. False fails
- # closed unless signed with the official com.trycua.driver identity. Only for local driver
- # development from source.
- "allow_unsigned_driver": False,
- },
- # Egress credential-injection proxy (iron-proxy) for remote terminal sandboxes (Docker today):
- # the sandbox sees opaque tokens and iron-proxy swaps in real credentials at egress, so a
- # compromised sandbox leaks only tokens that work behind the trusted proxy. Configure with
- # `hermes egress setup`.
- "proxy": {
- "enabled": False, # When false, nothing starts, no docker mounts, no binary installs.
- # Tunnel listener port; sandboxes get HTTPS_PROXY=http://<host>:<port>.
- "tunnel_port": 9090,
- # Auto-download the pinned binary into ~/.hermes/bin/; False = iron-proxy on PATH.
- "auto_install": True,
- # Upstream secret source: env = process env; bitwarden = refetch via `bws secret list` on
- # each proxy restart (requires secrets.bitwarden.enabled).
- "credential_source": "env",
- # True: the Docker backend refuses to start a sandbox if the proxy is enabled but not
- # running. False: fall back to direct outbound with real credentials.
- "enforce_on_docker": True,
- # With credential_source bitwarden, a missing BWS token/project_id or an empty fetch makes
- # the daemon raise. True silently falls back to host env (useful mid-migration). A leftover
- # fail_on_uncovered_providers key is ignored.
- "allow_env_fallback": False,
- # SSRF deny list. None/empty = loopback, link-local (incl. 169.254.169.254 metadata),
- # RFC1918. Explicit [] opts out (only for hermetic loopback tests).
- "upstream_deny_cidrs": None,
- # Extra allowed upstream hosts beyond the bundled major-provider defaults; wildcards
- # (`*.foo.com`) supported.
- "extra_allowed_hosts": [],
- },
- "desktop": { # Hermes Desktop (Electron) launch options; only affect `hermes desktop`.
- # CSS font-family for the app's chat and UI text (e.g. "OpenDyslexic"). Layered in front
- # of the active theme's own sans stack so missing glyphs still fall through. Empty = the
- # theme's face. The terminal pane is terminal.font_family.
- "font_family": "",
- # Git repo discovery for the Projects sidebar. Empty roots are a safe
- # no-op; users must explicitly configure roots for filesystem scanning.
- # Session-derived projects remain available.
- "repo_scan_enabled": True,
- "repo_scan_roots": [],
- "repo_scan_exclude_paths": [],
- # Extra Electron flags per launch, e.g. ["--ozone-platform=x11"] or GPU workarounds. List of
- # strings; a single string is shell-split.
- "electron_flags": [],
- # V8 old-space ceiling (MB) for the renderer, applied as --js-flags=--max-old-space-size=N by
- # the app itself (also for Start-menu / .desktop launches). 0 = Chromium's default limit.
- # A ceiling turns a machine-wide freeze into a bounded renderer reload (#77311).
- "renderer_max_old_space_mb": 0,
- # Linux Ozone backend, bridged to ELECTRON_OZONE_PLATFORM_HINT (explicit env wins). auto =
- # Chromium default; x11 = XWayland, for compositors that ignore always-on-top for Wayland
- # clients (e.g. COSMIC) — also puts the HUD on the solid-window input path; wayland = force
- # a native Wayland surface.
- # See #84011.
- "ozone_platform_hint": "auto",
- # Bridged to HERMES_DESKTOP_DISABLE_GPU: auto = disable GPU only on remote displays
- # (SSH/VNC/RDP); true = always software rendering (no-GPU VMs where the GPU path hangs);
- # false = always keep GPU on.
- "disable_gpu": "auto",
- # Linux keychain for token storage (Chromium --password-store). auto = detect KWallet (KDE
- # env) or any org.freedesktop.secrets provider via D-Bus;
- # gnome-libsecret|kwallet|kwallet5|kwallet6|basic force one (basic = unencrypted). Bridged
- # to HERMES_DESKTOP_PASSWORD_STORE; ignored off-Linux.
- "password_store": "auto",
- # Expose the renderer's accessibility tree to the OS (macOS/Windows) so dictation/IME tools
- # that insert text via the accessibility APIs can reach the composer (#118271, #92607).
- # False bridges to HERMES_DESKTOP_RENDERER_ACCESSIBILITY=0 and skips the tree (perf opt-out).
- "renderer_accessibility": True,
- # Linux: False preserves an existing custom XDG launcher entry; missing entries
- # are still created. True keeps the generated entry current on each launch.
- "manage_launcher_entry": True,
- # macOS only: code-signing identity (login-keychain cert; self-signed works) to re-sign
- # locally rebuilt apps so the Designated Requirement — and thus TCC grants — survives
- # updates. Empty = default ad-hoc identifier-pinned signing.
- "macos_signing_identity": "",
- # Windows only: explicit ssh client for SSH connections, the -G config probe and SSH
- # terminals, e.g. "C:\\Program Files\\Git\\usr\\bin\\ssh.exe" when the in-box OpenSSH is
- # missing or broken. Empty = System32 OpenSSH, then Git for Windows' ssh.exe, then PATH.
- # Read by the app before its first window; restart to apply. Ignored off-Windows.
- "ssh_path": "",
- # Auto-continue a turn killed by a crash: resuming re-submits the interrupted prompt if
- # fresh; a stale one just shows the recovered partial transcript.
- "auto_continue": {
- "enabled": True,
- # How recent the interruption must be to auto-continue (minutes).
- "freshness_minutes": 15,
- "max_attempts": 2, # Crash-loop breaker: max automatic re-runs of one interrupted turn.
- },
- },
- "nous": {
- # Upper bound (seconds) on the Nous auth keepalive tick, which derives from the
- # server-issued credential lifetime (raising above it has no effect). 0 disables the
- # keepalive thread.
- "keepalive_interval_seconds": 900,
- # anthropic_wire: which Portal route carries anthropic/* models. "chat" =
- # /v1/chat/completions (default for now); "native" = /v1/messages, the Anthropic
- # Messages wire (signed thinking passthrough, native cache_control scopes); "auto" =
- # start on chat and, per session, switch to native from the first response when the
- # Portal upstream serving the model is one where native is known clean. Native is the
- # better wire but on the OpenRouter-served path it re-writes the previous turn's cache on
- # 14-20% of consecutive calls in concurrent tool loops (measured 2026-09-06;
- # NousResearch/api#227), so chat is the default until that is fixed.
- "anthropic_wire": "chat",
- # Nous free tier: with no other provider configured, Hermes sets up a free Nous identity on
- # first use (inference on nous/welcome + connectors) and offers `/login` (terminal:
- # `hermes auth upgrade`) to sign in. false turns the free tier off entirely: nothing is set
- # up and nothing is used.
- "guest": True,
- },
- # Google Vertex AI (Gemini). Auth is OAuth2 from a service-account JSON or ADC, NOT an API key;
- # the credential path lives in .env (VERTEX_CREDENTIALS_PATH / GOOGLE_APPLICATION_CREDENTIALS).
- # Bridged to VERTEX_PROJECT_ID / VERTEX_REGION.
- "vertex": {
- # GCP project ID. Empty → project_id from the service-account JSON (or ADC).
- "project_id": "",
- # "global" is required for Gemini 3.x preview models (regional endpoints silently 404); use
- # e.g. "us-central1" only if your models are region-pinned.
- "region": "global",
- },
- # Managed llama.cpp runtime (docs: user-guide/local-models): official binaries, one supervised
- # llama-server in router mode. No context/VRAM knobs by design.
- "local_runtime": {
- # Off = detection-only (Hermes still finds an external llama-server you run).
- "enabled": False,
- # Engine versions and every dependent library are pinned by pm/lock.json.
- # auto = CUDA on NVIDIA, Metal on macOS, Vulkan on other GPUs, else CPU. Explicit:
- # cuda|metal|vulkan|hip|cpu.
- "backend": "auto",
- "models_max": 4, # Router process: how many models may be resident at once.
- "port": 0, # Port for the managed server. 0 = pick a free port at spawn.
- # Extra ports detection probes for an external llama-server (besides 8080).
- "detect_ports": [],
- },
- "_config_version": 52, # Config schema version - bump this when adding new required fields
- }
- from hermes_cli.config_defaults_env import OptionalEnvVars, _base_url, _env, _msg, _prov, _setting, _skill, _tool
- # Optional environment variables that enhance functionality. Feeds the dashboard keys page and setup
- # checklists; category: provider|tool|skill|messaging|setting, advanced=True hides from checklists,
- # tools=[...] lists the model tools the key unlocks. Provider entries: config_provider_env (on first read).
- OPTIONAL_ENV_VARS = OptionalEnvVars({
- # ── Provider (handled in provider selection, not shown in checklists) ──
- "NOUS_BASE_URL": _base_url("Nous Portal"),
- "HERMES_ANON_API_SECRET": _env(
- "Shared secret for the Nous free-tier sign-up endpoints while they are in their gated "
- "integration phase (not needed once the gate is removed)",
- "Nous free-tier shared secret (leave empty unless given one)", password=True,
- category="provider", advanced=True),
- "OPENROUTER_API_KEY": _env("OpenRouter API key (for vision, web scraping helpers, and MoA)",
- "OpenRouter API key", url="https://openrouter.ai/keys", password=True, tools=["vision_analyze"],
- category="provider", advanced=True),
- "GOOGLE_API_KEY": _prov("Google AI Studio API key (also recognized as GEMINI_API_KEY)",
- "Google AI Studio API key", "https://aistudio.google.com/app/apikey"),
- "GEMINI_API_KEY": _prov("Google AI Studio API key (alias for GOOGLE_API_KEY)", "Gemini API key",
- "https://aistudio.google.com/app/apikey"),
- "GEMINI_BASE_URL": _base_url("Google AI Studio", "Gemini"),
- "VERTEX_CREDENTIALS_PATH": _prov(
- "Path to a Google Cloud service account JSON for Vertex AI (Gemini). Vertex uses "
- "OAuth2, not a static API key — this points at the credentials Hermes mints short-lived "
- "tokens from. Falls back to GOOGLE_APPLICATION_CREDENTIALS, then to ADC (gcloud auth "
- "application-default login). Set project/region under vertex: in config.yaml.",
- "Vertex service account JSON path (leave empty to use ADC / "
- "GOOGLE_APPLICATION_CREDENTIALS)", "https://cloud.google.com/iam/docs/keys-create-delete",
- password=False),
- "XAI_API_KEY": _prov("xAI API key", "xAI API key", "https://console.x.ai/"),
- "XAI_BASE_URL": _base_url("xAI"),
- "NVIDIA_API_KEY": _prov("NVIDIA NIM API key (build.nvidia.com or local NIM endpoint)",
- "NVIDIA NIM API key", "https://build.nvidia.com/"),
- "NVIDIA_BASE_URL": _prov(
- "NVIDIA NIM base URL override (e.g. http://localhost:8000/v1 for local NIM)",
- "NVIDIA NIM base URL (leave empty for default)", None, password=False),
- "LM_API_KEY": _prov("LM Studio bearer token for auth-enabled local servers",
- "LM Studio API key / bearer token", None),
- "LM_BASE_URL": _base_url("LM Studio"),
- "GLM_API_KEY": _prov("Z.AI / GLM API key (also recognized as ZAI_API_KEY / Z_AI_API_KEY)",
- "Z.AI / GLM API key", "https://z.ai/"),
- "ZAI_API_KEY": _prov("Z.AI API key (alias for GLM_API_KEY)", "Z.AI API key", "https://z.ai/"),
- "Z_AI_API_KEY": _prov("Z.AI API key (alias for GLM_API_KEY)", "Z.AI API key", "https://z.ai/"),
- "GLM_BASE_URL": _base_url("Z.AI / GLM"),
- "KIMI_API_KEY": _prov("Kimi / Moonshot API key", "Kimi API key",
- "https://platform.moonshot.cn/"),
- "KIMI_BASE_URL": _base_url("Kimi / Moonshot", "Kimi"),
- "KIMI_CN_API_KEY": _prov("Kimi / Moonshot China API key", "Kimi (China) API key",
- "https://platform.moonshot.cn/"),
- "STEPFUN_API_KEY": _prov("StepFun Step Plan API key", "StepFun Step Plan API key",
- "https://platform.stepfun.com/"),
- "STEPFUN_BASE_URL": _base_url("StepFun Step Plan"),
- "ARCEEAI_API_KEY": _prov("Arcee AI API key", "Arcee AI API key", "https://chat.arcee.ai/"),
- "ARCEE_BASE_URL": _base_url("Arcee AI", "Arcee"),
- "GMI_API_KEY": _prov("GMI Cloud API key", "GMI Cloud API key", "https://www.gmicloud.ai/"),
- "GMI_BASE_URL": _base_url("GMI Cloud"),
- "ACTUAL_API_KEY": _prov("Actual Computer inference key (ac_...)",
- "Actual Computer inference key", "https://actual.inc/user/keys"),
- "FIREWORKS_API_KEY": _prov("Fireworks AI API key", "Fireworks AI API key",
- "https://app.fireworks.ai/settings/users/api-keys"),
- "MINIMAX_API_KEY": _prov("MiniMax API key (international)", "MiniMax API key",
- "https://www.minimax.io/"),
- "MINIMAX_BASE_URL": _base_url("MiniMax"),
- "MINIMAX_CN_API_KEY": _prov("MiniMax API key (China endpoint)", "MiniMax (China) API key",
- "https://www.minimaxi.com/"),
- "MINIMAX_CN_BASE_URL": _base_url("MiniMax (China)"),
- "DEEPSEEK_API_KEY": _prov("DeepSeek API key for direct DeepSeek access", "DeepSeek API Key",
- "https://platform.deepseek.com/api_keys", advanced=False),
- "DEEPSEEK_BASE_URL": _prov("Custom DeepSeek API base URL (advanced)", "DeepSeek Base URL", "",
- password=False, advanced=False),
- "DASHSCOPE_API_KEY": _prov("Alibaba Cloud DashScope API key (Qwen + multi-provider models)",
- "DashScope API Key", "https://modelstudio.console.alibabacloud.com/", advanced=False),
- "DASHSCOPE_BASE_URL": _prov(
- "Custom DashScope base URL (default: coding-intl OpenAI-compat endpoint)",
- "DashScope Base URL", "", password=False),
- "HERMES_QWEN_BASE_URL": _prov(
- "Qwen Portal base URL override (default: https://portal.qwen.ai/v1)",
- "Qwen Portal base URL (leave empty for default)", None, password=False),
- "OPENCODE_ZEN_API_KEY": _prov("OpenCode Zen API key (pay-as-you-go access to curated models)",
- "OpenCode Zen API key", "https://opencode.ai/auth"),
- "COMMANDCODE_API_KEY": _prov(
- "CommandCode API key (GOAT/Pro/Max/Provider plans — 30+ models via one key)",
- "CommandCode API key", "https://commandcode.ai/studio/"),
- "OPENCODE_ZEN_BASE_URL": _base_url("OpenCode Zen"),
- "OPENCODE_GO_API_KEY": _prov("OpenCode Go API key ($10/month subscription for open models)",
- "OpenCode Go API key", "https://opencode.ai/auth"),
- "OPENCODE_GO_BASE_URL": _base_url("OpenCode Go"),
- "HF_TOKEN": _prov(
- "Hugging Face token for Inference Providers (20+ open models via router.huggingface.co)",
- "Hugging Face Token", "https://huggingface.co/settings/tokens", advanced=False),
- "HF_BASE_URL": _base_url("Hugging Face Inference Providers", "HF"),
- "OLLAMA_API_KEY": _prov("Ollama Cloud API key (ollama.com — cloud-hosted open models)",
- "Ollama Cloud API key", "https://ollama.com/settings"),
- "OLLAMA_BASE_URL": _prov("Ollama Cloud base URL override (default: https://ollama.com/v1)",
- "Ollama base URL (leave empty for default)", None, password=False),
- "XIAOMI_API_KEY": _prov(
- "Xiaomi MiMo API key for MiMo models (mimo-v2.5-pro, mimo-v2.5, mimo-v2-pro, "
- "mimo-v2-omni, mimo-v2-flash)", "Xiaomi MiMo API Key", "https://platform.xiaomimimo.com",
- advanced=False),
- "XIAOMI_BASE_URL": _prov(
- "Xiaomi MiMo base URL override (default: https://api.xiaomimimo.com/v1)",
- "Xiaomi base URL (leave empty for default)", None, password=False),
- "UPSTAGE_API_KEY": _prov("Upstage API key for Solar LLM models", "Upstage API Key",
- "https://console.upstage.ai/api-keys", advanced=False),
- "UPSTAGE_BASE_URL": _prov("Upstage base URL override (default: https://api.upstage.ai/v1)",
- "Upstage base URL (leave empty for default)", None, password=False),
- "AWS_REGION": _prov("AWS region for Bedrock API calls (e.g. us-east-1, eu-central-1)",
- "AWS Region", "https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-regions.html",
- password=False),
- "AWS_PROFILE": _prov("AWS named profile for Bedrock authentication (from ~/.aws/credentials)",
- "AWS Profile", None, password=False),
- "AZURE_FOUNDRY_API_KEY": _prov("Azure Foundry API key for custom Azure endpoints",
- "Azure Foundry API Key", "https://ai.azure.com/", advanced=False),
- "AZURE_FOUNDRY_BASE_URL": _prov(
- "Azure Foundry base URL (set via 'hermes model' for endpoint-specific config)",
- "Azure Foundry base URL", None, password=False),
- # ── Tool API keys ──
- "EXA_API_KEY": _tool("Exa API key for AI-native web search and contents", "Exa API key",
- "https://exa.ai/", tools=["web_search", "web_extract"]),
- "PARALLEL_API_KEY": _tool("Parallel API key for AI-native web search and extract",
- "Parallel API key", "https://parallel.ai/", tools=["web_search", "web_extract"]),
- "FIRECRAWL_API_KEY": _tool("Firecrawl API key for web search and scraping", "Firecrawl API key",
- "https://firecrawl.dev/", tools=["web_search", "web_extract"]),
- "FIRECRAWL_API_URL": _tool("Firecrawl API URL for self-hosted instances (optional)",
- "Firecrawl API URL (leave empty for cloud)", None, password=False, advanced=True),
- "FIRECRAWL_GATEWAY_URL": _tool(
- "Exact Firecrawl tool-gateway origin override for Nous Subscribers only (optional)",
- "Firecrawl gateway URL (leave empty to derive from domain)", None, password=False,
- advanced=True),
- "TOOL_GATEWAY_URL": _tool(
- "Exact shared tool-gateway origin for on-origin vendors and media uploads (optional)",
- "Shared tool-gateway URL (leave empty to derive from domain)", None,
- password=False, advanced=True),
- "CONNECTOR_GATEWAY_URL": _tool(
- "Exact connector-gateway origin for the connectors API (optional)",
- "Connector-gateway URL (leave empty to derive from domain)", None,
- password=False, advanced=True),
- "TOOL_GATEWAY_DOMAIN": _tool(
- "Shared tool-gateway domain suffix for Nous Subscribers only, used to derive vendor "
- "hosts, e.g. nousresearch.com -> firecrawl-gateway.nousresearch.com",
- "Tool-gateway domain suffix", None, password=False, advanced=True),
- "TOOL_GATEWAY_SCHEME": _tool(
- "Shared tool-gateway URL scheme for Nous Subscribers only, used to derive vendor hosts "
- "(`https` by default, set `http` for local gateway testing)", "Tool-gateway URL scheme",
- None, password=False, advanced=True),
- "TOOL_GATEWAY_USER_TOKEN": _tool(
- "Explicit Nous Subscriber access token for tool-gateway requests (optional; otherwise "
- "read from the Hermes auth store)", "Tool-gateway user token", None, advanced=True),
- "TAVILY_API_KEY": _tool(
- "Tavily API key for AI-native web search and extract (optional — keyless works when "
- "Tavily is selected)", "Tavily API key", "https://app.tavily.com/home",
- tools=["web_search", "web_extract"]),
- "PERPLEXITY_API_KEY": _tool(
- "Perplexity API key for the Search API web backend (ranked results + query-relevant page "
- "snippets)", "Perplexity API key", "https://www.perplexity.ai/account/api",
- tools=["web_search", "web_extract"]),
- "KEENABLE_API_KEY": _tool(
- "Keenable API key for fast independent-index web search and page fetch (optional — "
- "keyless free tier works without it)", "Keenable API key", "https://keenable.ai",
- tools=["web_search", "web_extract"]),
- "SEARXNG_URL": _tool("URL of your SearXNG instance for free self-hosted web search",
- "SearXNG URL (e.g. http://localhost:8080)", "https://searxng.github.io/searxng/",
- tools=["web_search"], password=False),
- "BRAVE_SEARCH_API_KEY": _tool(
- "Brave Search API subscription token (free tier: 2,000 queries/mo)",
- "Brave Search subscription token", "https://brave.com/search/api/", tools=["web_search"]),
- "BROWSERBASE_API_KEY": _tool(
- "Browserbase API key for cloud browser (optional — local browser works without this)",
- "Browserbase API key", "https://browserbase.com/",
- tools=["browser_exec"]),
- "BROWSERBASE_PROJECT_ID": _tool(
- "Browserbase project ID (optional — only needed for cloud browser)",
- "Browserbase project ID", "https://browserbase.com/",
- tools=["browser_exec"], password=False),
- "BROWSER_USE_API_KEY": _tool(
- "Browser Use API key for cloud browser (optional — local browser works without this)",
- "Browser Use API key", "https://browser-use.com/",
- tools=["browser_exec"]),
- "FIRECRAWL_BROWSER_TTL": _tool(
- "Firecrawl browser session TTL in seconds (optional, default 300)",
- "Browser session TTL (seconds)", tools=["browser_exec"],
- password=False),
- "FAL_KEY": _tool("FAL API key for image and video generation", "FAL API key", "https://fal.ai/",
- tools=["image_generate", "video_generate"]),
- "KREA_API_KEY": _tool("Krea API key for Krea 3 and Krea 2 image generation",
- "Krea API key", "https://www.krea.ai/settings/api-tokens", tools=["image_generate"]),
- "VOICE_TOOLS_OPENAI_KEY": _tool(
- "OpenAI API key for voice transcription (Whisper) and OpenAI TTS",
- "OpenAI API Key (for Whisper STT + TTS)", "https://platform.openai.com/api-keys",
- tools=["voice_transcription", "openai_tts"]),
- "ELEVENLABS_API_KEY": _tool(
- "ElevenLabs API key for premium text-to-speech voices and Scribe transcription",
- "ElevenLabs API key", "https://elevenlabs.io/",
- tools=["elevenlabs_tts", "voice_transcription"]),
- "MISTRAL_API_KEY": _tool("Mistral API key for Voxtral TTS and transcription (STT)",
- "Mistral API key", "https://console.mistral.ai/"),
- "PORCUPINE_ACCESS_KEY": _tool(
- "Picovoice access key for the Porcupine 'Hey Hermes' wake word engine (optional; "
- "openWakeWord is the free default)", "Picovoice access key",
- "https://console.picovoice.ai/"),
- "GITHUB_TOKEN": _tool("GitHub token for Skills Hub (higher API rate limits, skill publish)",
- "GitHub Token", "https://github.com/settings/tokens"),
- # ── Bundled skills (opt-in) ── category="skill" (not "tool") so the sandbox env blocklist in
- # tools/environments/local.py does NOT rewrite them; skills need them passed through to curl
- # via tools/env_passthrough.py.
- "NOTION_API_KEY": _skill("Notion integration token (used by the Teams meeting pipeline's Notion sink)",
- "Notion API key", "https://www.notion.so/my-integrations"),
- "LINEAR_API_KEY": _skill("Linear personal API key (used by the `linear` skill)",
- "Linear API key", "https://linear.app/settings/account/security"),
- "TENOR_API_KEY": _skill("Tenor API key for GIF search (used by the `gif-search` skill)",
- "Tenor API key", "https://developers.google.com/tenor/guides/quickstart"),
- # ── Honcho ──
- "HONCHO_API_KEY": _tool("Honcho API key for AI-native persistent memory", "Honcho API key",
- "https://app.honcho.dev", tools=["honcho_context"]),
- "HONCHO_BASE_URL": _tool("Base URL for self-hosted Honcho instances (no API key needed)",
- "Honcho base URL (e.g. http://localhost:8000)", password=None),
- # ── Hindsight ──
- "HINDSIGHT_API_KEY": _tool("Hindsight API key for graph-aware persistent memory",
- "Hindsight API key", "https://hindsight.vectorize.io", tools=["hindsight_recall"]),
- "HINDSIGHT_API_URL": _tool(
- "Base URL for the Hindsight API (default: https://api.hindsight.vectorize.io)",
- "Hindsight API URL", password=None, advanced=True),
- # ── Supermemory ──
- "SUPERMEMORY_API_KEY": _tool("Supermemory API key for conversation-scoped persistent memory",
- "Supermemory API key", "https://supermemory.ai", tools=["supermemory_search"]),
- # ── Mem0 ──
- "MEM0_API_KEY": _tool("Mem0 Platform API key for semantic persistent memory", "Mem0 API key",
- "https://app.mem0.ai", tools=["mem0_search"]),
- # ── RetainDB ──
- "RETAINDB_API_KEY": _tool("RetainDB API key for persistent memory", "RetainDB API key",
- "https://retaindb.com", tools=["retaindb_search"]),
- "RETAINDB_BASE_URL": _tool(
- "Base URL for self-hosted RetainDB instances (default: https://api.retaindb.com)",
- "RetainDB base URL", password=None, advanced=True),
- # ── ByteRover ──
- "BRV_API_KEY": _tool("ByteRover API key (optional, for cloud sync — local-first by default)",
- "ByteRover API key", "https://app.byterover.dev", tools=["brv_query"]),
- # ── OpenViking ──
- "OPENVIKING_API_KEY": _tool("OpenViking API key (leave blank for local dev mode)",
- "OpenViking API key", tools=["viking_search"]),
- "OPENVIKING_ENDPOINT": _tool("OpenViking server URL (default: http://127.0.0.1:1933)",
- "OpenViking endpoint", password=None, advanced=True),
- # ── Messaging platforms ──
- "TELEGRAM_BOT_TOKEN": _msg(
- "Complete Telegram bot token created by @BotFather (numeric bot ID followed by a colon "
- "and secret)", "Telegram bot token", "https://t.me/BotFather", password=True),
- "TELEGRAM_ALLOWED_USERS": _msg(
- "Optional comma-separated numeric Telegram user IDs allowed immediately; leave blank to "
- "approve new users through DM pairing", "Allowed Telegram user IDs (comma-separated)",
- "https://t.me/userinfobot"),
- "TELEGRAM_PROXY": _msg(
- "Proxy URL for Telegram connections (overrides HTTPS_PROXY). Supports http://, "
- "https://, socks5://", "Telegram proxy URL (optional)"),
- "DISCORD_BOT_TOKEN": _msg("Discord bot token from Developer Portal", "Discord bot token",
- "https://discord.com/developers/applications", password=True),
- "DISCORD_ALLOWED_USERS": _msg("Comma-separated Discord user IDs allowed to use the bot",
- "Allowed Discord user IDs (comma-separated)", None),
- "DISCORD_REPLY_TO_MODE": _msg(
- "Discord reply threading mode: 'off' (no reply references), 'first' (reply on first "
- "message only, default), 'all' (reply on every chunk)",
- "Discord reply mode (off/first/all)", None),
- "SLACK_BOT_TOKEN": _msg(
- "Slack bot token (xoxb-). Get from OAuth & Permissions after installing your app. "
- "Required scopes: chat:write, app_mentions:read, channels:history, groups:history, "
- "im:history, im:read, im:write, mpim:history, mpim:read, users:read, files:read, "
- "files:write", "Slack Bot Token (xoxb-...)", "https://api.slack.com/apps",
- help=("In your Slack app, add the required bot scopes, install the app to the workspace, "
- "then copy OAuth & Permissions > Bot User OAuth Token."), password=True),
- "SLACK_APP_TOKEN": _msg(
- "Slack app-level token (xapp-) for Socket Mode. Get from Basic Information → App-Level "
- "Tokens. Also ensure Event Subscriptions include: message.im, message.channels, "
- "message.groups, message.mpim, app_mention", "Slack App Token (xapp-...)",
- "https://api.slack.com/apps",
- help=("In your Slack app, enable Socket Mode, then create Basic Information > App-Level "
- "Tokens with the connections:write scope."), password=True),
- "SLACK_ALLOWED_USERS": _msg(
- "Comma-separated Slack member IDs allowed to use Hermes, e.g. U01ABC2DEF3. Without "
- "this, Slack may connect but deny messages by default.", "Allowed Slack member IDs",
- "https://api.slack.com/apps",
- help=("In Slack, open your profile, choose More or the three-dot menu, then Copy member "
- "ID. Add multiple IDs comma-separated.")),
- "MATTERMOST_URL": _msg("Mattermost server URL (e.g. https://mm.example.com)",
- "Mattermost server URL", "https://mattermost.com/deploy/"),
- "MATTERMOST_TOKEN": _msg("Mattermost bot token or personal access token",
- "Mattermost bot token", None, password=True),
- "MATTERMOST_ALLOWED_USERS": _msg("Comma-separated Mattermost user IDs allowed to use the bot",
- "Allowed Mattermost user IDs (comma-separated)", None),
- "MATTERMOST_REQUIRE_MENTION": _msg(
- "Require @mention in Mattermost channels (default: true). Set to false to respond to "
- "all messages.", "Require @mention in channels", None),
- "MATTERMOST_FREE_RESPONSE_CHANNELS": _msg(
- "Comma-separated Mattermost channel IDs where bot responds without @mention",
- "Free-response channel IDs (comma-separated)", None),
- "MATRIX_HOMESERVER": _msg("Matrix homeserver URL (e.g. https://matrix.example.org)",
- "Matrix homeserver URL", "https://matrix.org/ecosystem/servers/"),
- "MATRIX_ACCESS_TOKEN": _msg("Matrix access token (preferred over password login)",
- "Matrix access token", None, password=True),
- "MATRIX_USER_ID": _msg("Matrix user ID (e.g. @hermes:example.org)",
- "Matrix user ID (@user:server)", None),
- "MATRIX_ALLOWED_USERS": _msg(
- "Comma-separated Matrix user IDs allowed to use the bot (@user:server format)",
- "Allowed Matrix user IDs (comma-separated)", None),
- "MATRIX_REQUIRE_MENTION": _msg(
- "Require @mention in Matrix rooms (default: true). Set to false to respond to all "
- "messages.", "Require @mention in rooms (true/false)", None, advanced=True),
- "MATRIX_FREE_RESPONSE_ROOMS": _msg(
- "Comma-separated Matrix room IDs where bot responds without @mention",
- "Free-response room IDs (comma-separated)", None, advanced=True),
- "MATRIX_AUTO_THREAD": _msg("Auto-create threads for messages in Matrix rooms (default: true)",
- "Auto-create threads in rooms (true/false)", None, advanced=True),
- "MATRIX_DM_AUTO_THREAD": _msg("Auto-create threads for DM messages in Matrix (default: false)",
- "Auto-create threads in DMs (true/false)", None, advanced=True),
- "MATRIX_DEVICE_ID": _msg(
- "Stable Matrix device ID for E2EE persistence across restarts (e.g. HERMES_BOT)",
- "Matrix device ID (stable across restarts)", None, advanced=True),
- "MATRIX_RECOVERY_KEY": _msg(
- "Matrix recovery key for cross-signing verification after device key rotation (from "
- "Element: Settings → Security → Recovery Key)", "Matrix recovery key", None, password=True,
- advanced=True),
- "BLUEBUBBLES_SERVER_URL": _msg(
- "BlueBubbles server URL for iMessage integration (e.g. http://192.168.1.10:1234)",
- "BlueBubbles server URL", "https://bluebubbles.app/"),
- "BLUEBUBBLES_PASSWORD": _msg(
- "BlueBubbles server password (from BlueBubbles Server → Settings → API)",
- "BlueBubbles server password", None, password=True),
- "BLUEBUBBLES_ALLOWED_USERS": _msg(
- "Comma-separated iMessage addresses (email or phone) allowed to use the bot",
- "Allowed iMessage addresses (comma-separated)", None),
- "BLUEBUBBLES_ALLOW_ALL_USERS": _msg("Allow all BlueBubbles users without allowlist",
- "Allow All BlueBubbles Users", password=None),
- "QQ_APP_ID": _msg("QQ Bot App ID from QQ Open Platform (q.qq.com)", "QQ App ID",
- "https://q.qq.com", password=None),
- "QQ_CLIENT_SECRET": _msg("QQ Bot Client Secret from QQ Open Platform", "QQ Client Secret",
- password=True),
- "QQ_ALLOWED_USERS": _msg("Comma-separated QQ user IDs allowed to use the bot",
- "QQ Allowed Users", password=None),
- "QQ_GROUP_ALLOWED_USERS": _msg("Comma-separated QQ group IDs allowed to interact with the bot",
- "QQ Group Allowed Users", password=None),
- "QQ_ALLOW_ALL_USERS": _msg("Allow all QQ users without an allowlist (true/false)",
- "Allow All QQ Users", password=None),
- "QQBOT_HOME_CHANNEL": _msg("Default QQ channel/group for cron delivery and notifications",
- "QQ Home Channel", password=None),
- "QQBOT_HOME_CHANNEL_NAME": _msg("Display name for the QQ home channel", "QQ Home Channel Name",
- password=None),
- "QQ_SANDBOX": _msg("Enable QQ sandbox mode for development testing (true/false)",
- "QQ Sandbox Mode", password=None),
- "IRC_SERVER": _msg("IRC server hostname (e.g. irc.libera.chat)", "IRC server", None),
- "IRC_CHANNEL": _msg("IRC channel to join (e.g. #hermes)", "IRC channel", None),
- "IRC_NICKNAME": _msg("Bot nickname on IRC (default: hermes-bot)", "IRC nickname", None),
- "IRC_SERVER_PASSWORD": _msg("IRC server password (if required)", "IRC server password", None,
- password=True, advanced=True),
- "IRC_NICKSERV_PASSWORD": _msg("NickServ password for nick identification", "NickServ password",
- None, password=True, advanced=True),
- "GATEWAY_ALLOW_ALL_USERS": _msg(
- "Allow all users to interact with messaging bots (true/false). Default: false.",
- "Allow all users (true/false)", None, advanced=True),
- "API_SERVER_ENABLED": _msg(
- "Enable the OpenAI-compatible API server (true/false). Allows frontends like Open "
- "WebUI, LobeChat, etc. to connect.", "Enable API server (true/false)", None, advanced=True),
- "API_SERVER_KEY": _msg(
- "Bearer token for API server authentication. Required whenever the API server is "
- "enabled; server refuses to start without it.", "API server auth key", None, password=True,
- advanced=True),
- "API_SERVER_PORT": _msg("Port for the API server (default: 8642).", "API server port", None,
- advanced=True),
- "API_SERVER_HOST": _msg(
- "Host/bind address for the API server (default: 127.0.0.1). API_SERVER_KEY is still "
- "required even on loopback binds.", "API server host", None, advanced=True),
- "API_SERVER_MODEL_NAME": _msg(
- "Model name advertised on /v1/models. Defaults to the profile name (or 'hermes-agent' "
- "for the default profile). Useful for multi-user setups with OpenWebUI.",
- "API server model name", None, advanced=True),
- "GATEWAY_PROXY_URL": _msg(
- "URL of a remote Hermes API server to forward messages to (proxy mode). When set, the "
- "gateway handles platform I/O only — all agent work is delegated to the remote server. "
- "Use for Docker E2EE containers that relay to a host agent. Also configurable via "
- "gateway.proxy_url in config.yaml.",
- "Remote Hermes API server URL (e.g. http://192.168.1.100:8642)", None, advanced=True),
- "GATEWAY_PROXY_KEY": _msg(
- "Bearer token for authenticating with the remote Hermes API server (proxy mode). Must "
- "match the API_SERVER_KEY on the remote host.", "Remote API server auth key", None,
- password=True, advanced=True),
- "WEBHOOK_ENABLED": _msg(
- "Enable the webhook platform adapter for receiving events from GitHub, GitLab, etc.",
- "Enable webhooks (true/false)", None),
- "WEBHOOK_PORT": _msg("Port for the webhook HTTP server (default: 8644).", "Webhook port", None),
- "WEBHOOK_SECRET": _msg(
- "Global HMAC secret for webhook signature validation (overridable per route in "
- "config.yaml).", "Webhook secret", None, password=True),
- # ── Agent settings ── (MESSAGING_CWD is gone: use terminal.cwd in config.yaml, which the
- # gateway bridges to TERMINAL_CWD.)
- "SUDO_PASSWORD": _setting(
- "Sudo password for terminal commands requiring root access; set to an explicit empty "
- "string to try empty without prompting", "Sudo password", None, password=True),
- # HERMES_TOOL_PROGRESS_MODE (deprecated; use display.tool_progress) is intentionally NOT listed:
- # this dict feeds user-facing surfaces (dashboard keys page, setup checklists), so deprecated
- # knobs stay in config._EXTRA_ENV_KEYS only. HERMES_TOOL_PROGRESS is unsupported.
- "HERMES_PREFILL_MESSAGES_FILE": _setting(
- "Path to JSON file with ephemeral prefill messages for few-shot priming",
- "Prefill messages file path", None),
- "HERMES_EPHEMERAL_SYSTEM_PROMPT": _setting(
- "Ephemeral system prompt injected at API-call time (never persisted to sessions)",
- "Ephemeral system prompt", None),
- })
|