Settings reference — AiHummer Docs

This page lists every setting an operator can change on an AiHummer server. It is generated from the product’s own catalogue, so it matches your server exactly.

Set a value in the Web UI or with the command aihummer settings set KEY VALUE (Command line). The default column shows what the server uses until a value of your own is set.

[!NOTE] Secret values are never printed here, and vendor service keys are not listed at all — the product hides them from every list. A dash means an empty value or an explanation that is only shown in the Web UI.

API

Key	Name	Type	Default	Takes effect	What it does
`AIHUMMER_PERSONAL_API_KEYS`	Personal API keys for OpenAI-compat	`bool`	`1`	after restart	“off” disables personal-key authentication on the OpenAI-compatible endpoint. Any other value = enabled. Applied at startup/after restart.

Agent

Key	Name	Type	Default	Takes effect	What it does
`AIHUMMER_AGENT_ANNOUNCE_SLOW_TOOLS`	Agent: say what it is doing before long actions	`bool`	`1`	immediately	Before a long action (an image, deep research, a video, a task for a subagent) the agent briefly writes what it is doing, so the wait is not silent. Turn off if such messages get in the way.
`AIHUMMER_AGENT_COMPACT_AT_PCT`	Agent: compact history at, % of its budget	`int 50…99`	`85`	immediately	When a conversation’s history fills this share of its room in the model window, older messages are folded into a summary — in the background, after the reply; the turn does not wait. Lower — compaction more often, but the model remembers less word for word; higher — less often, but turns get heavier. 50–99; an agent can override it.
`AIHUMMER_AGENT_COMPACT_TO_PCT`	Agent: keep after compaction, % of the history budget	`int 10…90`	`50`	immediately	How much of the history’s room stays word for word after compaction; everything older goes into the summary. Must be below the compaction threshold: the gap between them is how many turns pass until the next compaction. 10–90; an agent can override it.
`AIHUMMER_AGENT_HISTORY_TURNS`	Agent: dialog turns kept word for word	`int 1…1000`	`30`	immediately	How many recent turns of a conversation the model sees word for word (up to 10 more until compaction is due). Older messages are summarized in the background; the conversation itself is never deleted. The model’s context window is respected automatically. 1–1000; an agent can override it.
`AIHUMMER_AGENT_MAX_ITERATIONS`	Agent: max tool steps per turn	`int 1…256`	`25`	immediately	How many times per turn an agent may call tools before answering. At the limit the turn does not fail: the agent reports what it did and what is left, and you can ask it to continue. Three identical calls in a row with the same result stop the turn earlier. 1–256; an agent can override it.
`AIHUMMER_AGENT_MEMORY_FLUSH`	Agent: save a memory note before compaction	`bool`	`1`	immediately	Before older messages are folded into a summary, the agent saves a short note about goals, decisions and open tasks to memory. Turn off to save the model call.
`AIHUMMER_AGENT_MEMORY_FLUSH_PROMPT`	Agent: what the memory note before compaction keeps	`text`	—	immediately	Your own task for the note before compaction: what to keep from the messages that go into the summary (for example, “only purchases, deadlines and agreements”). Empty — built-in: goals, decisions and open tasks. The protection cannot be turned off: the conversation text stays data, not instructions, and passwords and keys are never saved. Up to 4000 characters; an agent can have its own.
`AIHUMMER_AGENT_NEW_REMINDERS_MEMORY`	New agents: reminders and memory writes	`bool`	`1`	immediately	A new agent created by hand (setup wizard, Create agent, API) sets, changes and cancels its OWN reminders and schedules and writes facts to its own memory from the first turn, like the personal assistant template. Turn it off for one agent in its card (Capabilities). Library templates set their own choice, a copy keeps the original’s rights, agents created by another agent start without them; existing agents do not change. Applies to the next agent created.
`AIHUMMER_AGENT_PROMPT_PART_MAX_CHARS`	Agent: max characters per prompt part	`int 1000…1000000`	`20000`	immediately	How many characters the model gets from ONE part of the agent’s persona: a profile section, a prompt part or the main prompt. A longer part keeps its beginning (3/4) and end (1/4) with a note of how much was cut; this is shown in the conversation card and in the agent’s prompt composition. Name, addressing and persona constraints are never cut. 1000–1000000; an agent can override it.
`AIHUMMER_AGENT_PROMPT_TOTAL_MAX_CHARS`	Agent: max characters of the whole persona	`int 1000…2000000`	`60000`	immediately	Overall cap on the agent’s persona: all parts together. When it is exceeded, the longest parts give up space first and short ones stay whole. 1000–2000000; an agent can override it.
`AIHUMMER_AGENT_SELF_INTRO`	Agent: introduce itself	`enum: first_contact \\\| each_dialog \\\| never`	`first_contact`	immediately	“Once, when first meeting someone”: the agent briefly introduces itself in its very first conversation with a person, unless they want to get straight to the point; with someone it already knows it does not introduce itself again and answers a greeting naturally. “Never introduce itself”: the agent never names itself unprompted. “At the start of every new conversation”: the agent introduces itself briefly in every new conversation and after a long pause, without a summary of past matters. An agent can choose differently on its card (“Context and behaviour”).
`AIHUMMER_AGENT_SESSION_IDLE_RESET_MINUTES`	Agent: start the conversation afresh after silence (minutes)	`int 0…525600`	`360`	immediately	For “after silence” and “every day and after silence”: if a person writes after a silence longer than this, the agent starts the conversation afresh. Applies to agents that do not set their own value on their card. 0 — not by silence. 0–525600; 360 = 6 hours, 1440 = one day.
`AIHUMMER_AGENT_SESSION_INDEX_MAX_ENTRIES`	Agent: keep at most this many sessions in the list	`int 0…100000`	`0`	immediately	At most how many conversations the agent’s session list keeps; the quietest leave first, nothing is deleted. 0 — no limit. 0–100000. Applies to agents without their own value on their card.
`AIHUMMER_AGENT_SESSION_INDEX_PRUNE_DAYS`	Agent: remove from the session list after days of silence	`int 0…3650`	`0`	immediately	A conversation where the person has been silent longer than this leaves the agent’s session list; nothing is deleted, and a new message brings it back. 0 — keep. 0–3650. Applies to agents without their own value on their card.
`AIHUMMER_AGENT_SESSION_RESET_AT_HOUR`	Agent: hour of the daily fresh start	`int 0…23`	`4`	immediately	For the “every day” modes: a conversation that began before this hour starts afresh with the person’s next message. The hour follows the server time zone (the “Timezone” setting in System & settings). 0–23; 4 is at night, when almost no one writes.
`AIHUMMER_AGENT_SESSION_RESET_GROUP_IDLE_MINUTES`	Agent: start a group chat afresh after silence (minutes)	`int 0…525600`	`0`	immediately	For group chats in the “after silence” and “every day and after silence” modes: the minutes of silence after which a group chat starts afresh. 0 means as for personal chats. 0–525600.
`AIHUMMER_AGENT_SESSION_RESET_GROUP_MODE`	Agent: when a group chat starts afresh	`enum: inherit \\\| daily \\\| idle \\\| both \\\| none`	`inherit`	immediately	A separate rule for group chats (Telegram groups, VK conversations, MAX chats and others): as for personal chats, every day at the reset hour, after a silence, whichever comes first, or never. The reset hour is shared. Applies to agents without their own rule on their card.
`AIHUMMER_AGENT_SESSION_RESET_MODE`	Agent: when a conversation starts afresh	`enum: idle \\\| daily \\\| both \\\| none`	`idle`	immediately	When the agent starts a conversation afresh: every day at the reset hour (in the instance time zone), after a silence, whichever comes first, or never. Starting afresh, the agent writes a note about the past conversation to its memory, and its first turn gets the previous summary and the last messages; the messages stay in the archive and in search. Applies to agents without their own rule on their card; group chats can get a separate rule there.
`AIHUMMER_AGENT_SESSION_SCOPE`	Agent: where personal conversations go	`enum: chat \\\| per-channel-peer \\\| per-peer`	`chat`	immediately	Where an agent’s personal conversations go: a conversation for each chat of a channel; a conversation for each person in each channel; or one conversation per person across all channels (Telegram, the app and other personal chats of the same person join into one). Group chats always keep their own. Applies from the next message to agents without their own choice on their card.
`AIHUMMER_AGENT_SILENT_REPLY`	Agent: may stay silent	`enum: groups \\\| all \\\| off`	`groups`	immediately	In group chats the agent may stay silent when a message is not addressed to it or it has nothing to add; in private chats it always replies. You can allow silence in private chats too, or turn it off. A silent turn sends nothing, the conversation card marks it as “the agent stayed silent”, and the model does not see it in the history. Takes effect on the next turn.
`AIHUMMER_AGENT_SKILLS_PROMPT_MAX_CHARS`	Agent: max characters of the skill list in the prompt	`int 1000…200000`	`18000`	immediately	In every turn the model sees not the skill texts but their list: identifier, name and when to use it; the agent loads a skill’s instructions itself when a task fits. If the list is longer, descriptions go first, then the tail of the list — the agent finds the rest on request. 1000–200000.
`AIHUMMER_AGENT_STALE_GAP_HOURS`	Agent: pause after which past talk is history (hours)	`int 0…8760`	`12`	immediately	If a person writes after a pause longer than this, the agent gets a note: everything discussed before is history — it is not retold and old tasks are not resumed unless asked. Every message already carries its time and how long it has been since the previous one. 0 = no note. 0–8760.
`AIHUMMER_AGENT_TOOL_HISTORY_TURNS`	Agent: turns that keep tool results	`int 0…100`	`5`	immediately	For how many recent turns the model sees tool calls and their results in full (a result is kept up to 16 KB). Older turns keep the call and the beginning of the result. This way the agent remembers what it found and did instead of calling tools again. 0 = do not carry tool results into later turns. 0–100; an agent can override it.
`AIHUMMER_APPROVAL_TOOLS`	Tools needing approval	`multiselect`	—	immediately	Comma-separated list of tools whose calls require manual operator approval before they run. Blank = no approval is required. Takes effect immediately, no restart needed.
`AIHUMMER_SUBAGENT_MAX_DEPTH`	Subagent max depth	`int 0…10`	`2`	immediately	Maximum nesting depth of subagents (an agent launching an agent). Default 2 — protection against endless recursion.
`AIHUMMER_SUBAGENT_TIMEOUT_SEC`	Subagent timeout (seconds)	`int 0…86400`	`180`	immediately	Maximum time for a single subagent run, in seconds.
`AIHUMMER_TOOL_SEARCH`	Lazy tool loading	`bool`	`false`	immediately	Show the working core of tools directly and hide the rest of a large catalog behind a search tool that names every hidden tool. Pays off only for big catalogs (dozens of plugin, MCP or OpenAPI tools): below the size threshold every tool is shown directly, because an extra model call to find a tool costs more than the schemas. Takes effect on the next turn.
`AIHUMMER_TOOL_SEARCH_CORE`	Lazy tool loading: always-on tools	`multiselect`	`web_search,web_fetch,memory_search,memory_get,memory_store,search_history,search_knowledge,code_exec,process,filesystem_read,message,schedule_list,schedule_create,schedule_delete,generate_pairing_code`	immediately	Tools always shown directly in lazy mode. The default is the working core: web search, page fetch, memory, conversation history, knowledge base, code, files, messages, schedules and app pairing. Memory and knowledge-base search (memory_search, memory_get, search_knowledge) is always shown, whatever this list says. An empty list restores this core.
`AIHUMMER_TOOL_SEARCH_MIN_POOL_TOKENS`	Lazy tool loading: min size of hidden tools (tokens)	`int 0…1000000`	`4000`	immediately	Hide tools only when the schemas outside the core add up to at least this many tokens (about 4 characters each). Below it every tool is shown directly: one extra model call to find a tool costs more than showing the schemas.
`AIHUMMER_TOOL_SEARCH_THRESHOLD`	Lazy tool loading: min tools to defer	`int 0…1000`	`12`	immediately	Only defer when more than this many tools survive the agent’s profile filter.

Agent · Reasoning

Key	Name	Type	Default	Takes effect	What it does
`AIHUMMER_AGENT_BEST_OF_N`	Best of N: number of candidates	`int 0…8`	`0`	immediately	The agent prepares this many answer candidates and keeps the best one. 0 or 1 — off, 2 or more — on. Each candidate costs as much as a separate reply.
`AIHUMMER_AGENT_DEBATE_JUDGE_PROMPT`	Debate: judge prompt (override)	`text`	—	immediately	Overrides the debate judge prompt (blank = built-in).
`AIHUMMER_AGENT_DEBATE_N`	Debate: number of answer candidates	`int 0…8`	`0`	immediately	The agent prepares this many answer candidates, compares them and returns the best. 0 or 1 — off, 2 or more — on. Each candidate costs as much as a separate reply.
`AIHUMMER_AGENT_DEBATE_PROMPT`	Debate: candidate prompt (override)	`text`	—	immediately	Overrides the debate candidate prompt (blank = built-in).
`AIHUMMER_AGENT_DEBATE_ROUNDS`	Debate: rounds	`int 1…10`	`1`	immediately	Number of debate rounds for the candidate panel.
`AIHUMMER_AGENT_JUDGE_PROMPT`	Best-of-N judge prompt (override)	`text`	—	immediately	Overrides the best-of-N judge prompt (blank = built-in).
`AIHUMMER_AGENT_PLAN_PROMPT`	Planner prompt (override)	`text`	—	immediately	Overrides the planner prompt (blank = built-in).
`AIHUMMER_AGENT_PLAN_STEPS`	Planner-executor: max plan steps (0=off)	`int 0…32`	`0`	immediately	⟩0 runs a separate planner→executor→synthesis pass (good for complex multi-step tasks). 0 disables. Typical 4–8.
`AIHUMMER_AGENT_PLAN_STEP_ITERS`	Planner: tool iterations per step (0=default)	`int 0…64`	`0`	immediately	Caps tool-calling iterations per plan step. 0 = built-in default (4).
`AIHUMMER_AGENT_REFLECT`	Self-critique pass	`bool`	`0`	immediately	Adds a reflection/self-critique pass before the final answer.
`AIHUMMER_AGENT_REFLECT_PROMPT`	Reflection prompt (override)	`text`	—	immediately	Overrides the self-critique prompt (blank = built-in).
`AIHUMMER_AGENT_SELF_HEAL`	Self-heal tool-error retries (0=off)	`int 0…10`	`0`	immediately	⟩0 retries failed tool calls with a corrective hint, up to this bound.

Agent · System prompt

Key	Name	Type	Default	Takes effect	What it does
`AIHUMMER_LOCALE`	Default locale	`enum: ru-RU \\\| en-US \\\| az-AZ \\\| hy-AM \\\| be-BY \\\| kk-KZ \\\| ky-KG \\\| tg-TJ \\\| tk-TM \\\| uz-UZ \\\| ka-GE \\\| ro-RO \\\| es-ES \\\| zh-CN \\\| fr-FR \\\| de-DE \\\| hi-IN \\\| pl-PL \\\| lt-LT \\\| lv-LV \\\| et-EE \\\| fi-FI \\\| sv-SE \\\| no-NO \\\| da-DK \\\| tr-TR \\\| mn-MN`	`ru-RU`	immediately	Default reply language/locale hint, e.g. ru-RU. Persona/operator instructions override.
`AIHUMMER_TIMEZONE`	Timezone	`text`	`UTC`	immediately	IANA timezone for the agent’s current date and for schedules without their own timezone, e.g. Europe/Moscow. Default UTC.

Channels

Key	Name	Type	Default	Takes effect	What it does
`AIHUMMER_CHANNEL_FAILURE_NOTICE`	Tell the person when a reply fails	`enum: always \\\| once \\\| off`	`always`	immediately	What a person in a channel (Telegram and others) gets when the agent could not answer: «Every time» — a short message in their language; «At most once every 4 hours» — one message per conversation within 4 hours; «Do not tell» — nothing. The message has no error codes or provider names; you see the details in Sessions and notifications.
`AIHUMMER_CHANNEL_FAILURE_TEXT_BLOCKED`	Failure message: the instance is suspended	`text`	—	immediately	Leave empty to send the built-in message in the person’s own language. Your text is sent as written, in the language you write it in; {ref} inserts the reply’s code, by which you find the turn in Sessions. Applies immediately.
`AIHUMMER_CHANNEL_FAILURE_TEXT_BUDGET`	Failure message: the owner’s budget is used up	`text`	—	immediately	Leave empty to send the built-in message in the person’s own language. Your text is sent as written, in the language you write it in; {ref} inserts the reply’s code, by which you find the turn in Sessions. Applies immediately.
`AIHUMMER_CHANNEL_FAILURE_TEXT_BUSY`	Failure message: the gateway is overloaded	`text`	—	immediately	Leave empty to send the built-in message in the person’s own language. Your text is sent as written, in the language you write it in; {ref} inserts the reply’s code, by which you find the turn in Sessions. Applies immediately.
`AIHUMMER_CHANNEL_FAILURE_TEXT_CONFIG`	Failure message: the model connection needs the owner	`text`	—	immediately	Leave empty to send the built-in message in the person’s own language. Your text is sent as written, in the language you write it in; {ref} inserts the reply’s code, by which you find the turn in Sessions. Applies immediately.
`AIHUMMER_CHANNEL_FAILURE_TEXT_FAILED`	Failure message: any other failure	`text`	—	immediately	Leave empty to send the built-in message in the person’s own language. Your text is sent as written, in the language you write it in; {ref} inserts the reply’s code, by which you find the turn in Sessions. Applies immediately.
`AIHUMMER_CHANNEL_FAILURE_TEXT_QUOTA`	Failure message: the model’s usage limit is used up	`text`	—	immediately	Leave empty to send the built-in message in the person’s own language. Your text is sent as written, in the language you write it in; {ref} inserts the reply’s code, by which you find the turn in Sessions. Applies immediately.
`AIHUMMER_CHANNEL_FAILURE_TEXT_STEP_LIMIT`	Failure message: the task did not fit into one reply	`text`	—	immediately	Leave empty to send the built-in message in the person’s own language. Your text is sent as written, in the language you write it in; {ref} inserts the reply’s code, by which you find the turn in Sessions. Applies immediately.
`AIHUMMER_CHANNEL_FAILURE_TEXT_TOO_LONG`	Failure message: the conversation is too long for the model	`text`	—	immediately	Leave empty to send the built-in message in the person’s own language. Your text is sent as written, in the language you write it in; {ref} inserts the reply’s code, by which you find the turn in Sessions. Applies immediately.
`AIHUMMER_CHANNEL_FAILURE_TEXT_UNAVAILABLE`	Failure message: the model is temporarily unavailable	`text`	—	immediately	Leave empty to send the built-in message in the person’s own language. Your text is sent as written, in the language you write it in; {ref} inserts the reply’s code, by which you find the turn in Sessions. Applies immediately.
`AIHUMMER_CONFIDENTIAL_PERSONA`	Confidential web persona	`bool`	`0`	immediately	When on, the web-chat agent won’t disclose or persist its persona/identity details and keeps replies to the task at hand — use it for anonymous or privacy-sensitive web deployments. Takes effect immediately, no restart needed.
`AIHUMMER_INBOUND_COALESCE_MS`	Message batching window (ms)	`int`	`500`	immediately	Several messages one person sends in a row to the same chat (short messages, a photo album, a quick correction) get ONE reply if the pause between them is shorter than this window. Messages that arrive while a reply is being prepared are answered right after it, never in parallel. Default 500 ms; 0 = no waiting between separate messages; a photo album is still gathered (pauses up to 3 s, at most 20 s) so it gets one reply. Batching works in Telegram; Slack, WhatsApp, VK, email and other connectors that wait for a reply to each message (and integrations via /v1/inbound/generic) get a reply to every message — still one at a time, in order. Applies immediately.
`AIHUMMER_INBOUND_EDIT_MODE`	When a person edits an answered message	`enum: correct \\\| history`	`correct`	immediately	correct — the bot answers once more, knowing it is a correction (“was / now”); history — the edit only fixes the conversation history, no new reply (handy for typos). An edit of a message the bot has not answered yet always just replaces its text. Works where the channel reports edits (Telegram). Applies immediately.
`AIHUMMER_INBOUND_QUEUE_MODE`	Messages written while the agent is working	`enum: steer \\\| collect \\\| followup`	`steer`	immediately	What happens to a message the same person sends while the agent is still working on a reply (searching, running tools): steer (default) — the agent sees it before its next step and takes it into account in the same reply; collect — it is answered with the next reply. followup — each such message gets its own reply, one after another. Photos, files, replies to a message and forwards always wait for the next reply. Applies immediately.
`AIHUMMER_INBOUND_REQUIRE_BINDING`	Reply only to provisioned users	`bool`	`true`	immediately	true = the bot ignores any channel sender that is NOT a provisioned AiHummer user (a user with a role binding) — random chat members and guest invocations get no reply. false (default) = reply to everyone.

Integrations

Key	Name	Type	Default	Takes effect	What it does
`AIHUMMER_A2A_PUBLISH`	Publish agent over Agent2Agent (A2A)	`bool`	`0`	after restart	Publish the agent as an A2A server (Agent Card + POST /a2a/message). Applied at startup/after restart.
`AIHUMMER_MCP_EXPORT_TOOLS`	Tools opened to external assistants	`multiselect`	—	after restart	An explicit list of tool names allowed for external MCP clients, separated by commas. Empty = do not publish any tools. Dangerous host-level classes are additionally prohibited by the built-in policy, even if listed. Applies at start/after restart.
`AIHUMMER_MCP_PUBLISH`	Publish tools over MCP	`bool`	`0`	after restart	Lets external assistants (e.g. Claude Desktop) use your agents’ tools. Which tools to open is chosen in the neighbouring setting: while that list is empty, none are opened.
`AIHUMMER_MODULE_CPU_QUOTA`	Plugin CPU limit (per plugin)	`text`	`75%`	immediately	How much processor time each plugin may use (systemd CPUQuota): 75% is three quarters of one core, 150% is one and a half cores. A plugin gets the new value on its next install, update or settings save; running plugins keep the previous limit until then.
`AIHUMMER_MODULE_MEMORY_MAX`	Plugin memory limit (per plugin)	`text`	`512M`	immediately	How much memory each plugin may use (systemd MemoryMax): a size such as 512M, 1G or 2048M (at least 64M), or infinity for no limit. The system stops a plugin that exceeds it. A plugin gets the new value on its next install, update or settings save; running plugins keep the previous limit until then.

Knowledge connectors

Key	Name	Type	Default	Takes effect	What it does
`AIHUMMER_KB_SYNC_INTERVAL`	How often to refresh the knowledge base from sources	`text`	—	immediately	How often the server pulls changes from connected knowledge-base sources on its own. For example: 30m — every 30 minutes, 6h — every 6 hours. Blank or 0 — manual only. Reloading never creates duplicates. A Slack export is uploaded by hand.

LLM

Key	Name	Type	Default	Takes effect	What it does
`AIHUMMER_AUX_FALLBACK_MODELS`	Service tasks: fallback models	`list`	—	immediately	Comma-separated models tried in order when the service-task model fails (quota, outage). The main model is always tried last so a summary is not lost. Every switch is logged. Applies immediately.
`AIHUMMER_AUX_MODEL`	Model for service tasks (summaries, notes, titles)	`text`	—	immediately	Model for background service tasks: folding old history into a summary, the memory note before compaction, conversation titles, fact extraction, search query rephrasing and translation. Empty = automatic: a cheaper model from the same provider (Claude → claude-haiku-4-5, Codex → gpt-…-luna/mini); if there is none, the main model. “main” = always the main model. Applies immediately.
`AIHUMMER_CASCADE_MIN_CHARS`	Cascade: min chars to escalate	`int`	`0`	immediately	Request-length threshold (characters) at which the stronger cascade model kicks in. 0 = default.
`AIHUMMER_CASCADE_STRONG_MODEL`	Cascade: stronger fallback model	`text`	—	immediately	Model to cascade to for long/complex requests (blank = off).
`AIHUMMER_CLAUDE_AUTH_URL`	Claude subscription: sign-in page address	`text`	—	immediately	The page where you allow the Claude subscription to be connected. Blank — the standard address; change it only if support asks you to.
`AIHUMMER_CLAUDE_CLIENT_ID`	Claude subscription: OAuth client id	`text`	—	immediately	The app identifier for signing in with a Claude subscription. Blank — the standard one; change it only if support asks you to.
`AIHUMMER_CLAUDE_EFFORT`	Claude: thinking depth	`enum: low \\\| medium \\\| high \\\| xhigh \\\| max`	`medium`	immediately	How deeply Claude models think before answering when the agent does not set it. Higher is more accurate on hard tasks but slower and uses more quota; lower is faster and cheaper. A model that does not know the chosen level gets the nearest lower one; Haiku 4.5 and older models do not support thinking. The depth set on the agent takes precedence. Takes effect from the next turn.
`AIHUMMER_CLAUDE_MAX_TOKENS`	Claude: maximum reply length (tokens)	`int`	`16000`	immediately	How many tokens one Claude reply may take — both via subscription and via key. The model’s thinking counts toward the same limit: too small a value cuts the reply mid-sentence or gives an empty reply. If an agent has its own reply length set, that one applies.
`AIHUMMER_CLAUDE_REDIRECT_URI`	Claude subscription: redirect URI	`text`	—	immediately	Return address registered with the supplier. Must match what is configured on its side, otherwise the code exchange is rejected.
`AIHUMMER_CLAUDE_TOKEN_URL`	Claude subscription: access address	`text`	—	immediately	The address where the server obtains and renews access to the Claude subscription. Blank — the standard address; change it only if support asks you to.
`AIHUMMER_CODEX_BASE_URL`	Codex base URL	`text`	—	partly after restart	Base of the Codex (ChatGPT subscription) transport. Applied at startup/after restart.
`AIHUMMER_CODEX_MAX_OUTPUT_TOKENS`	Max output tokens (0 = no cap)	`int`	`0`	immediately	The max_output_tokens cap for a chat turn. 0 = no cap. On reasoning models the reasoning tokens also count against this budget, so too small a value yields an empty ‘incomplete: max_output_tokens’ reply. Applied on the fly (no restart).
`AIHUMMER_CODEX_MODEL`	Model id (Codex / gpt-5.5 transport)	`text`	`gpt-5.5`	partly after restart	Model id of the primary Codex/ChatGPT transport (e.g. gpt-5.5, gpt-5.5-codex). Applied at startup/after restart.
`AIHUMMER_CODEX_REASONING_EFFORT`	Reasoning effort	`enum: none \\\| low \\\| medium \\\| high \\\| xhigh`	`medium`	immediately	How deeply the ChatGPT (Codex) model thinks before answering when the agent does not set it. Default — «Medium». Higher is more accurate but slower and more expensive.
`AIHUMMER_LLM_CALL_TIMEOUT_S`	Per-call timeout (seconds)	`int`	`120`	immediately	How many seconds to wait for the model to answer one request. If the model stays silent longer, the request is dropped and the reply moves to the next model in the list. For Claude the pause in the response stream is counted, not the whole answer: a long reply that keeps coming is not cut off. 0 — no limit.
`AIHUMMER_LLM_FALLBACK_MODELS`	Fallback models (all agents)	`text`	`auto`	immediately	Who answers when the main model and the other providers fail (usage limit reached, outage, too many requests). auto — each provider’s cheaper model as the last resort (Claude: claude-haiku-4-5, Codex: gpt-…-luna/mini); a comma-separated list — your own order, each model goes to providers of its vendor; off — no fallback models. An agent’s own fallback model takes precedence. Applies immediately.
`AIHUMMER_LLM_GATEWAY_URL`	LLM gateway URL	`text`	—	partly after restart	Base URL of the OpenAI-compatible model endpoint the agent calls (your local llama.cpp/vLLM/Ollama server or a hosted gateway). Leave blank to use the provider’s default endpoint.
`AIHUMMER_LLM_MODEL`	LLM model	`text`	—	partly after restart	The model name/id sent to the provider on every turn (the model your endpoint serves). Must match a model the endpoint actually exposes.
`AIHUMMER_LLM_PAUSE_AUTH_MIN`	Provider pause after rejected credentials, min	`int`	`10`	immediately	How many minutes not to ask a provider that rejected the credentials. Each repeat doubles the pause, up to six times the first one. A successful connection test or the “Resume now” button brings the provider back at once. Applies from the next failure.
`AIHUMMER_LLM_PAUSE_MODEL_MIN`	Pause of a model the provider does not serve, min	`int`	`60`	immediately	How many minutes not to offer a provider a model it said it does not serve; its other models are asked as usual. Applies from the next failure.
`AIHUMMER_LLM_PAUSE_QUOTA_MIN`	Provider pause after a usage limit, min	`int`	`300`	immediately	How many minutes not to ask the model (or the whole account, when the account’s limit is used up — Codex, an OpenAI key, payment) once its usage limit is reached and the provider named no reset time. Each repeat doubles the pause, up to a day. A time named by the provider wins. Applies from the next failure.
`AIHUMMER_LLM_PAUSE_SHORT_S`	Provider pause after an outage, s	`int`	`30`	immediately	How many seconds not to ask a provider after an outage, a dropped connection or “too many requests”. A second failure in a row doubles the pause; the third and later ones make it ten times longer. If the provider names its own time, that time is used. Applies from the next failure.
`AIHUMMER_LLM_PROVIDER`	LLM provider	`text`	—	partly after restart	Which model backend to use (an OpenAI-compatible endpoint or the Codex/ChatGPT-subscription transport). Decides how requests are sent and authenticated.
`AIHUMMER_LLM_RETRIES`	LLM retries on transient error	`int`	`3`	immediately	Number of LLM request retries on a transient error.
`AIHUMMER_LLM_TEMPERATURE`	Temperature	`text`	—	immediately	How varied the model’s replies are (0–2) when the agent does not set it: lower is more precise and predictable, higher is livelier. Blank — the model decides. Reasoning models (ChatGPT/Codex, Claude generation 5) do not accept it — leave the field blank for them.
`AIHUMMER_LLM_TOP_P`	Top-p (nucleus sampling)	`text`	—	immediately	Another way to make replies more varied (0–1) when the agent does not set it. Blank — the model decides. Usually you set only one: either temperature or this; reasoning models do not accept it.
`AIHUMMER_MODEL_GUARD_INTERVAL_MIN`	Agent model check: interval, min	`int`	`60`	immediately	How often to recheck that each agent’s model is served by an enabled provider. The agent’s model is never changed: while nobody serves it, replies come from the first model in the answer order that is not paused, and one notification names the agents — plus another when their model is back. The check always runs when the gateway starts; 0 only turns off the repeats. A new interval takes effect within a minute.
`AIHUMMER_OPENAI_API`	OpenAI API style (chat \| responses)	`enum: \\\| chat \\\| responses`	—	partly after restart	chat = /chat/completions, responses = /responses. Blank = auto/default. Applied at startup/after restart.
`AIHUMMER_OPENAI_API_KEY`	Native OpenAI API key (deployment default)	`text`	—	partly after restart	Your OpenAI account key for the native OpenAI loop (if you use OpenAI as the default provider). Not to be confused with per-workspace BYOK on the Models page. Applied at startup/after restart.
`AIHUMMER_OPENAI_BASE_URL`	Native OpenAI base URL	`text`	—	after restart	Base of the OpenAI-compatible API (e.g. https://api.openai.com/v1). Applied at startup/after restart.
`AIHUMMER_OPENAI_MODEL`	Native OpenAI model	`text`	—	after restart	Model for the native OpenAI loop (when AIHUMMER_OPENAI_API_KEY is set). Applied at startup/after restart.
`AIHUMMER_ROUTER_COMPLEX_MODEL`	Router: model for complex turns	`text`	—	immediately	Model for complex requests of an agent that has no model of its own (blank = tier off). Applies from the next turn.
`AIHUMMER_ROUTER_SIMPLE_MODEL`	Router: model for simple turns	`text`	—	immediately	Model for simple requests of an agent that has no model of its own (blank = tier off). Applies from the next turn.
`AIHUMMER_ROUTER_STANDARD_MODEL`	Router: model for standard turns	`text`	—	immediately	Model for ordinary requests of an agent that has no model of its own (blank = tier off). Applies from the next turn.
`AIHUMMER_SUBSCRIPTION_QUOTA_REFRESH_MIN`	Subscription quotas: refresh period, min	`int`	`15`	immediately	How often the panel asks ChatGPT (Codex) for subscription quota windows: at most once per period, not more often than every 5 minutes, and only while the quotas are open; in between the saved copy is shown. Claude is never asked: its limits are our estimate. Takes effect the next time the quotas are opened.

Media

Key	Name	Type	Default	Takes effect	What it does
`AIHUMMER_DEEPGRAM_API_KEY`	Deepgram API key	`text`	—	immediately	The Deepgram service key — needed if Deepgram recognises voice messages. If blank, the shared speech-recognition key from the neighbouring setting is used. Takes effect immediately.
`AIHUMMER_DEEPGRAM_DETECT_LANGUAGE`	Deepgram language detection	`bool`	`0`	immediately	Detect the audio language instead of sending a fixed STT language. Applies immediately.
`AIHUMMER_DEEPGRAM_MODEL`	Deepgram model	`text`	`nova-2`	immediately	Deepgram model (e.g. nova-2, nova-3, base). Depends on the project’s access for the key. Applies immediately.
`AIHUMMER_DEEPGRAM_PUNCTUATE`	Deepgram punctuation	`bool`	`1`	immediately	Add punctuation and capitalization to transcripts. Applies immediately.
`AIHUMMER_DEEPGRAM_SMART_FORMAT`	Deepgram smart formatting	`bool`	`1`	immediately	Format recognized numbers, dates and other entities. Applies immediately.
`AIHUMMER_DEEPGRAM_URL`	Deepgram base URL	`text`	—	immediately	Deepgram API base. Blank = https://api.deepgram.com. Applies immediately.
`AIHUMMER_IMAGE_BASE_URL`	Image API base URL (OpenAI fallback)	`text`	—	immediately	Base of the /images API when working through an OpenAI key (blank = https://api.openai.com/v1).
`AIHUMMER_IMAGE_MODEL`	Image-generation model	`text`	—	immediately	Model for image_generate (default gpt-image-2).
`AIHUMMER_MEDIA_MAX_UPLOAD_MB`	Media max upload size (MB)	`int`	`256`	immediately	The largest file (photo, voice message, video) that can be uploaded at once, in megabytes. Protects the server disk from filling up. Default 256. Takes effect immediately.
`AIHUMMER_SIDECAR_STT`	Speech recognition on this server (faster-whisper)	`bool`	`0`	immediately	Local speech recognition (faster-whisper). It is not part of the core bundle: enable downloads the signed add-on published with every release (~620 MiB across supported Python versions), installs the service and configures its URL automatically. Cloud plan: recognition is configured by the provider.
`AIHUMMER_SIDECAR_TTS`	Voice replies (edge-tts)	`bool`	`0`	immediately	Speech synthesis (edge-tts, voices Microsoft Edge). NOT included in the package: enabling downloads the signed add-on (~26 MiB) and installs the service on the host. The synthesis itself goes online for votes - “offline” here refers to installing the package, not working.
`AIHUMMER_STT_API_KEY`	STT API key (optional)	`text`	—	immediately	Access key for the speech recognition service, if it requires one. For a service on this server the installer sets it — no need to change it. Takes effect immediately.
`AIHUMMER_STT_ENGINE`	STT engine	`enum: auto \\\| faster-whisper \\\| deepgram \\\| codex \\\| off`	`auto`	immediately	How voice messages are transcribed. Auto (default): Deepgram if its key is set, otherwise the local service if it is installed (the signed add-on, switch above), otherwise nothing — and the bot honestly tells the sender it cannot listen yet. faster-whisper: the local service or a compatible external /v1/audio/transcriptions. deepgram: Deepgram cloud with your key. codex: the connected ChatGPT subscription (Models → Connect ChatGPT), uses its quota. off: do not transcribe. Applies immediately.
`AIHUMMER_STT_LANGUAGE`	STT language	`text`	—	immediately	Recognition language (BCP-47, e.g. ru/en). Used by the deepgram engine (nova-2 model). Blank = auto-detect / engine default. Applies immediately.
`AIHUMMER_STT_MODEL`	STT model	`text`	`Systran/faster-whisper-small`	immediately	faster-whisper model (e.g. small/medium/large-v3 or Systran/faster-whisper-⟨size⟩). Applies immediately.
`AIHUMMER_TTS_API_KEY`	TTS API key (edge-tts)	`text`	—	partly after restart	Access key for the voice service. Set automatically during installation — no need to change it.
`AIHUMMER_TTS_ENABLED`	Text-to-speech enabled	`bool`	`1`	partly after restart	Lets the agent reply by voice. This needs the voice service — install it in the Additional services section above.
`AIHUMMER_TTS_MODEL`	TTS model	`text`	—	partly after restart	Model name for the edge-tts service. Applied at startup/after restart.
`AIHUMMER_TTS_VOICE`	TTS voice	enum: de-DE-FlorianMultilingualNeural \\\| de-DE-SeraphinaMultilingualNeural \\\| en-US-AndrewMultilingualNeural \\\| en-US-AvaMultilingualNeural \\\| en-US-BrianMultilingualNeural \\\| en-US-EmmaMultilingualNeural \\\| fr-FR-RemyMultilingualNeural \\\| fr-FR-VivienneMultilingualNeural \\\| ru-RU-SvetlanaNeural \\\| ru-RU-DmitryNeural \\\| en-US-JennyNeural \\\| en-US-GuyNeural \\\| en-GB-SoniaNeural \\\| de-DE-KatjaNeural \\\| fr-FR-DeniseNeural \\\| es-ES-ElviraNeural \\\| tr-TR-EmelNeural \\\| pl-PL-ZofiaNeural \\\| zh-CN-XiaoxiaoNeural	`de-DE-FlorianMultilingualNeural`	partly after restart	Default edge-tts voice (multilingual, incl. Russian). Applied at startup/after restart.
`AIHUMMER_VIDEO_API_KEY`	Video analysis API key	`text`	—	immediately	Access key for the video analysis service, if it requires one. Blank — the service is used without a key.

Media · Voice

Key	Name	Type	Default	Takes effect	What it does
`AIHUMMER_TTS_AUTO_REPLY`	Automatic voice replies	`enum: off \\\| always \\\| inbound \\\| tagged`	`inbound`	immediately	Speak completed replies: off, always, in response to incoming audio, or when explicitly tagged by the agent. A conversation can override this setting.
`AIHUMMER_TTS_MAX_CHARS`	Spoken reply character limit	`int`	`0`	immediately	0 keeps the full reply; 100–10000 limits the spoken text. The complete reply stays in history.
`AIHUMMER_TTS_SUMMARIZE`	Summarize long spoken replies	`bool`	`1`	immediately	Summarize long replies for audio. If summarization is unavailable, speak a bounded excerpt from the beginning.
`AIHUMMER_VOICE_AEC`	Echo cancellation (AEC)	`bool`	`1`	immediately	Removes echo: the agent’s own voice from the speaker does not get back into the microphone and does not interrupt the conversation. Turn it off only if the voice sounds distorted in a headset.
`AIHUMMER_VOICE_AGC`	Auto gain control	`bool`	`1`	immediately	Require automatic microphone gain control (WebRTC autoGainControl) in voice mode.
`AIHUMMER_VOICE_BARGEIN_FRAMES`	Interrupting the agent: how long to speak	`int`	`5`	immediately	How long you need to speak (in 20 ms frames) for the agent to stop talking and listen. Default 5 — about 0.1 seconds.
`AIHUMMER_VOICE_DUPLEX`	Live full-duplex voice	`bool`	`0`	immediately	Enables live full-duplex mode (streaming + VAD + barge-in). Applies immediately.
`AIHUMMER_VOICE_NOISE_SUPPRESSION`	Noise suppression	`bool`	`1`	immediately	Require noise suppression on microphone capture (WebRTC noiseSuppression) in voice mode.
`AIHUMMER_VOICE_VAD_THRESHOLD`	Voice sensitivity (0–1)	`text`	`0.02`	immediately	How loud a sound must be to count as speech. Lower — more sensitive: the agent hears quiet speech, but also background noise. Default 0.02.

Memory

Key	Name	Type	Default	Takes effect	What it does
`AIHUMMER_EMBEDDER_DIM`	Meaning-search model dimension	`int`	`768`	after restart	Vector dimension — must match the model (multilingual-e5-base=768, bge-m3=1024).
`AIHUMMER_EMBEDDER_KEEPALIVE`	Embedder keep-alive	`text`	`5m`	after restart	How long the meaning-search model stays loaded after the last request (only in «By meaning» mode). Default 5m — 5 minutes: then the model is unloaded and frees memory and CPU. Keeping it forever (-1) is not recommended: a stuck model can occupy a CPU core for days. Format: 30s, 5m, 1h.
`AIHUMMER_EMBEDDER_MODEL`	Meaning-search model	`text`	`yxchia/multilingual-e5-base`	after restart	The model that lets memory be searched by meaning. Default multilingual-e5-base understands Russian, is light and runs fast on an ordinary CPU. For better quality on a GPU use bge-m3, but then set the neighbouring dimension setting to 1024: the number must match the model.
`AIHUMMER_EMBEDDER_PASSAGE_PREFIX`	Embedder passage prefix	`text`	—	after restart	Override the stored-document prefix (e5 models auto-use “passage: “). Leave blank to auto-detect by model name.
`AIHUMMER_EMBEDDER_QUERY_PREFIX`	Embedder query prefix	`text`	—	after restart	Override the retrieval-query prefix (e5 models auto-use “query: “). Leave blank to auto-detect by model name.
`AIHUMMER_EMBEDDER_THREADS`	Embedder CPU threads	`int 0…256`	`0`	after restart	How many processor threads the meaning-search model takes per request. 0 — automatic: half of the server’s threads, but at least 2. Without a limit, recomputing knowledge-base vectors on a weak server took the whole processor for hours and slowed agents’ replies. More — faster recomputation but heavier load.
`AIHUMMER_MEMORY_AGENT_WRITES`	Facts the agent saves itself	`enum: strangers \\\| immediate \\\| review`	`strangers`	immediately	What happens to what the agent remembers on its own — for example on a “remember this” request. «Straight into memory; from strangers — for review» (default) — straight into memory when the owner or the agent’s trusted people said it; from anyone else — for review. «Straight into memory» — the agent finds it right away. «For review» — first into the Memory → review queue; it reaches replies only after you approve it. The agent card (Memory → Settings) can set its own mode.
`AIHUMMER_MEMORY_AUTOREPAIR`	Automatic memory repair	`bool`	`1`	immediately	After the self-check, repair memory: merge duplicates, close contradictions that have an explicit winner (confirmed by a person, a later event date, a stronger source), re-check against their sources the facts marked confirmed that no person confirmed (unconfirmed ones go to review, nothing is deleted). Anything disputed only goes to the review queue. Every fix is logged with an Undo button; if memory finds facts worse after the pass, the pass rolls itself back and you get a notification. Takes effect immediately, no restart needed.
`AIHUMMER_MEMORY_CAPTURE`	Memory capture mode	`enum: auto \\\| review \\\| off`	`review`	immediately	What to do with facts the agent notices in the conversation after each reply. «For review» puts them in the Memory → review queue: they reach replies only after you approve them. «Straight into memory» skips review: faster, but noisier. «Do not save» extracts nothing from conversations. What the agent remembers on request is set separately.
`AIHUMMER_MEMORY_CONTEXT_TIMEOUT`	Memory hydration timeout	`text`	`3s`	immediately	How long the agent waits for relevant memories before it starts replying. If the search is too slow, the agent replies without them instead of hanging. For example: 2s — 2 seconds, 1500ms — 1.5 seconds. 0 — wait as long as needed.
`AIHUMMER_MEMORY_DIARY_BOOT`	Agent diary at the start of a session	`bool`	`1`	immediately	Keep the agent’s diary for today and yesterday in view on every turn of a session on any channel: notes from earlier sessions, the nightly summary and the agent’s own entries. Only the entries about the current interlocutor and the shared ones (yours, uploaded) are shown — one client never sees another’s. At most ~6000 characters; the agent reads the rest itself (memory_get). Takes effect immediately, no restart needed.
`AIHUMMER_MEMORY_DIARY_HOUR`	Nightly summary hour	`int`	`3`	immediately	After which hour (0–23, instance timezone) the summary of the past day is written. Default 3 — at night, when the day’s conversations are over. Takes effect immediately, no restart needed.
`AIHUMMER_MEMORY_DIARY_NIGHTLY`	Nightly day summary in the agent diary	`bool`	`1`	immediately	Once a day, write a summary of the past day into the agent’s diary — separately for each person it talked to (all of that person’s channels together): what was asked and done, agreements, tasks with dates. One call to the service-task model per agent and person, at most 3 per pass every 10 minutes; missed days (e.g. while the gateway was down) are caught up to a week back. Conversations with “don’t remember” are skipped. Not written while memory capture is off. The result of the last pass is shown in the agent card → Memory → Diary. Takes effect immediately, no restart needed.
`AIHUMMER_MEMORY_DREAM_INTERVAL`	Dream pass interval	`string`	`1h`	immediately	How often the self-maintaining dream pass scans reviewed claims for contradictions across all scopes (Go duration, e.g. 30m/1h/6h). Set 0 to disable. Takes effect immediately, no restart needed.
`AIHUMMER_MEMORY_EXTRACT`	LLM fact extraction	`bool`	`1`	immediately	Extract normalized subject/predicate/object facts via the LLM (default ON) instead of storing raw sentence fragments — required for the graph/contradiction/dream machinery to fire. Adds one LLM call per captured message; set off to save the call. Takes effect immediately, no restart needed.
`AIHUMMER_MEMORY_MEANING_TIMEOUT`	Meaning search time limit	`text`	`4s`	immediately	How long a search in memory and in the knowledge base waits for the search by meaning. If the meaning model is busy (for example, computing vectors after an import) and does not answer in time, the agent immediately gets what was found by words, with a note, instead of waiting tens of seconds. For example: 4s — 4 seconds, 1500ms — 1.5 seconds. 0 — wait as long as needed. Takes effect immediately, no restart needed.
`AIHUMMER_MEMORY_QUALITY_CHECK`	Daily memory self-check	`bool`	`1`	immediately	Once a day memory asks itself test questions about its confirmed facts (up to 60 facts, the same questions every day) and questions that have no answer, runs them through memory search and automatic recall and measures recall, precision, MRR and false recalls. The result and the daily chart are under Memory → Memory quality. Questions for new facts are written once by the service model (the one that extracts facts from conversations; without it — by a template); the results stay on the instance. Takes effect immediately, no restart needed.
`AIHUMMER_MEMORY_RECALL`	Automatic memory recall	`enum: strong \\\| always \\\| off`	`strong`	immediately	Whether memory found for a message is added to the reply automatically. «Only strong matches» — a fact must share at least two important words with the message; greetings and “ok” pull in nothing. «Everything similar» — anything that matched at all, plus linked records: noisier. «Do not add» — the agent searches memory itself when it sees fit.
`AIHUMMER_MEMORY_RECALL_MAX`	Facts recalled per reply	`int`	`5`	immediately	The maximum number of memory facts added to one reply (default 5). Rephrasings of the same fact count as one. Takes effect immediately, no restart needed.
`AIHUMMER_MEMORY_RECALL_MIN_SCORE`	Minimum match for automatic recall, %	`int`	`10`	immediately	What share of the message’s meaningful words (weighted by rarity) a fact must cover to be added automatically, in percent. Default 10 — tuned on real conversations. Higher = rarer and more precise, lower = more often and noisier. 0 = no threshold: two matching meaningful words are enough. Does not affect the explicit memory_search. Takes effect immediately, no restart needed.
`AIHUMMER_MEMORY_RECALL_MIN_SIMILARITY`	Minimum meaning similarity for automatic recall, %	`int`	`86`	immediately	Only for memory search by meaning (embedder): how close in meaning to the message a fact must be to be added automatically, as a similarity percentage. Default 86 — tuned for the multilingual-e5-base model on real memory: below it, unrelated facts get added to almost every message. Other models (for example bge-m3) measure similarity differently — pick a value with “Ask memory” in the agent card. 0 = no threshold. Does not affect the explicit memory_search. Takes effect immediately, no restart needed.
`AIHUMMER_MEMORY_RETRIEVAL`	Memory retrieval mode	`enum: fulltext \\\| embedding`	`fulltext`	after restart	How the agent looks things up in memory. «By words» is plain text search: works right away and does not load the server. «By meaning» finds things close in meaning, even worded differently, but needs the meaning-search model (Additional services section) and noticeable CPU load.
`AIHUMMER_QDRANT_API_KEY`	Qdrant API key	`text`	—	after restart	Qdrant API key, if the vector store requires authorization. Needed only when a Qdrant address is set. Applied at startup/after restart.
`AIHUMMER_QDRANT_URL`	Qdrant URL (durable vector store)	`text`	—	after restart	Address of the Qdrant store used for meaning search. Blank — search data is kept in memory and lost when the server restarts; set an address for permanent use.
`AIHUMMER_RAG_QUERY_EXPANSION`	Rephrase knowledge-base queries with the model	`bool`	`0`	immediately	Before searching the knowledge base, ask the service-task model for 3 rephrasings of the query and search with all of them. Sometimes finds more, but it is an extra model call on EVERY search (quota and latency); if the model fails, only the original wording is searched and the failure is shown in the log and in the search result. Off by default: words are found by full-text search anyway. Takes effect immediately, no restart needed.
`AIHUMMER_RERANKER_URL`	RAG reranker sidecar URL	`text`	—	after restart	HTTP URL of the cross-encoder sidecar for reranking hybrid search. Blank = reranking off. Applied at startup/after restart.

Moderation

Key	Name	Type	Default	Takes effect	What it does
`AIHUMMER_MODERATION`	Input moderation	`bool`	`1`	immediately	“off” disables the built-in guard against jailbreak/prompt-injection. Any other value = enabled. Takes effect immediately, no restart needed.
`AIHUMMER_MODERATION_REFUSAL`	Moderation refusal message	`text`	—	immediately	Refusal text returned when the moderator blocks a request (blank = built-in). Takes effect immediately, no restart needed.

Network

Key	Name	Type	Default	Takes effect	What it does
`AIHUMMER_OUTBOUND_PROXY_CUSTOM_URL`	Outbound proxy: custom address	`text`	—	immediately	HTTPS proxy URL; HTTP is allowed only on loopback, without path, query or fragment. Save the address before choosing custom. Masked in the API; stored in application settings.
`AIHUMMER_OUTBOUND_PROXY_MODE`	Outbound proxy for foreign model providers	`enum: auto \\\| off \\\| custom`	`auto`	immediately	How the server reaches foreign model providers. «As the provider sets» — as configured in the provider’s account; «Direct, no proxy» — no intermediaries; «Through your own proxy» — via the address you saved below. Whether it works depends on each provider’s rules.
`AIHUMMER_RUSSIAN_TRUSTED_EXTRA_HOSTS`	Hosts beyond .ru for the Russian Trusted roots	`list`	—	after restart	List of hosts, separated by commas, that are allowed to be checked by the Russian Trusted CA roots (Ministry of Digital Development) OVER Russian domains (.ru).

Performance

Key	Name	Type	Default	Takes effect	What it does
`AIHUMMER_CHANNEL_TURN_QUEUE_WAIT_SEC`	Queue wait: channel message (seconds)	`int 10…1200`	`600`	immediately	How long a channel message (Telegram and others) waits for a free slot when every turn slot is busy. If it doesn’t get one in time, the person is told the server is busy and can write again. The wait counts toward the 30-minute turn limit. 10–1200. Applies immediately.
`AIHUMMER_MAX_ACTIVE_TURNS`	Agent turns running at once (whole server)	`int 1…512`	`32`	immediately	How many agent turns (channel and web chat replies, schedules) the server runs at once. The rest wait in a queue for as long as the “Queue wait” settings below allow, and the person sees “server busy, queued”. Higher means less waiting but more memory, database connections and simultaneous model requests. Half of this number limits simultaneous auxiliary model calls (memory extraction, summaries). 1–512. Applies immediately.
`AIHUMMER_SYNC_INBOUND_QUEUE_WAIT_SEC`	Queue wait: synchronous integration call (seconds)	`int 1…120`	`10`	immediately	How long a call from an integration that waits for the reply in the same request waits for a free slot when every turn slot is busy. If it doesn’t get one, the integration receives “server busy” with advice to retry after the same number of seconds; a retry with the same message number does not store the message twice. 1–120. Applies immediately.
`AIHUMMER_WEB_TURN_QUEUE_WAIT_SEC`	Queue wait: web chat message (seconds)	`int 10…1200`	`180`	immediately	How long a web chat message waits for a free slot when every turn slot is busy. Meanwhile the chat shows “server busy, queued”; if it doesn’t get one in time, the reply is refused with a “Retry” button that stays in the history even after a page reload. 10–1200. Applies immediately.

Public access

Key	Name	Type	Default	Takes effect	What it does
`AIHUMMER_PUBLIC_URL`	Server public address	`text`	—	partly after restart	The address where the panel and apps open from the internet, e.g. https://ai.example.com. Route it through your proxy (nginx, Caddy) to the server port — 8780 by default.
`AIHUMMER_WIDGET_ALLOWED_ORIGINS`	Web widget: allowed site origins	`list`	—	immediately	Comma-separated browser origins allowed to embed the web chat widget, e.g. https://example.com,https://www.example.com. Scheme and port must match exactly. Blank = no external site may use the widget. A `*` entry is deliberately ignored because it would let any page on the internet spend this instance’s budget.
`POCKET_AGENT_GATEWAY_BASE_URL`	Pocket-agent gateway public URL	`text`	—	immediately	Proxy → the pocket-agent gateway port (POCKET_AGENT_PORT, default 8080). The remote agent dials this via a one-time ticket.
`TELEGRAM_PUBLIC_URL`	Telegram webhook public URL	`text`	—	immediately	Webhook mode only — proxy → the telegram-connector port (default 8091). Leave blank to use polling (no public URL needed).

SSO (LDAP/AD)

Key	Name	Type	Default	Takes effect	What it does
`AIHUMMER_LDAP_BASE_DN`	User search base DN	`text`	—	after restart	Search root, e.g. OU=Users,DC=corp,DC=example.
`AIHUMMER_LDAP_BIND_DN`	Service bind DN	`text`	—	after restart	Account used for the initial search bind, e.g. CN=svc-aihummer,OU=Service,DC=corp,DC=example. Blank = anonymous search.
`AIHUMMER_LDAP_DEFAULT_ROLE`	LDAP: Default role (no group match)	`text`	—	after restart	Role granted when no group matches a mapping. Blank = no role.
`AIHUMMER_LDAP_ENABLED`	Enable LDAP/AD login	`bool`	`0`	after restart	When on, admin logins fall back to the directory. The bind password lives in Secrets (scope ldap, name bind_password).
`AIHUMMER_LDAP_GROUP_ATTR`	Group attribute (default memberOf)	`text`	—	after restart	Attribute on the user entry listing group DNs. Blank disables group→role mapping.
`AIHUMMER_LDAP_ROLE_MAPPINGS`	LDAP: Group→role mappings (JSON)	`text`	—	after restart	JSON object of group DN (or bare CN) → role, e.g. {“CN=Admins,OU=Groups,DC=corp,DC=example”:“admin”,“Operators”:“operator”}.
`AIHUMMER_LDAP_SKIP_TLS_VERIFY`	Skip TLS verification (lab only, 1/0)	`bool`	`0`	after restart	Disables directory certificate verification. Never enable in production.
`AIHUMMER_LDAP_URL`	Directory URL	`text`	—	after restart	e.g. ldaps://ad.corp.example:636 (TLS) or ldap://dc1.corp.example:389.
`AIHUMMER_LDAP_USER_ATTR`	Login attribute (default sAMAccountName)	`text`	—	after restart	The LDAP/Active Directory attribute matched against the login the user types (default sAMAccountName; uid for OpenLDAP, userPrincipalName for UPN-style logins).
`AIHUMMER_LDAP_USER_FILTER`	User search filter	`text`	—	after restart	Must contain %s for the login. AD: (sAMAccountName=%s); OpenLDAP: (uid=%s).

SSO (OIDC)

Key	Name	Type	Default	Takes effect	What it does
`AIHUMMER_OIDC_AUDIENCE`	OIDC audience	`text`	—	after restart	Expected `aud` claim — set this to THIS resource’s audience to reject tokens minted for another relying party. The `aud` claim is now REQUIRED on every token by default (a token with no aud is rejected); when this is set, aud must also contain it. Strongly recommended in production.
`AIHUMMER_OIDC_ISSUER`	OIDC issuer URL	`text`	—	after restart	The IdP issuer (e.g. https://login.example.com). Enables OIDC JWT auth when set.
`AIHUMMER_OIDC_JWKS_URL`	OIDC JWKS URL	`text`	—	after restart	JSON Web Key Set endpoint used to verify token signatures.
`AIHUMMER_OIDC_TENANT_CLAIM`	OIDC workspace claim	`text`	—	after restart	JWT claim carrying the workspace id (e.g. tenant_id / org).

SSO (SAML)

Key	Name	Type	Default	Takes effect	What it does
`AIHUMMER_SAML_DEFAULT_ROLE`	SAML: Default role (no group match)	`text`	—	after restart	Role granted when no asserted value maps. Blank = no role.
`AIHUMMER_SAML_ENABLED`	Enable SAML 2.0 SSO	`bool`	`0`	after restart	Exposes /saml/metadata, /saml/acs, /saml/login. SP private key lives in Secrets (scope saml, name sp_key).
`AIHUMMER_SAML_ENTITY_ID`	SP entity ID	`text`	—	after restart	SP entity ID (defaults to ⟨root⟩/saml/metadata if blank).
`AIHUMMER_SAML_IDP_METADATA`	IdP metadata XML	`text`	—	after restart	Paste the IdP’s SAML metadata document (Okta/Azure AD/ADFS).
`AIHUMMER_SAML_ROLE_ATTRIBUTE`	Role/group attribute (default groups)	`text`	—	after restart	Assertion attribute carrying group/role values.
`AIHUMMER_SAML_ROLE_MAPPINGS`	SAML: Group→role mappings (JSON)	`text`	—	after restart	JSON object of asserted value → role, e.g. {“AdminGroup”:“admin”,“Ops”:“operator”}.
`AIHUMMER_SAML_ROOT_URL`	SP root URL	`text`	—	after restart	Externally reachable base URL of this gateway, e.g. https://app.example.com. ACS = ⟨root⟩/saml/acs.
`AIHUMMER_SAML_SP_CERT`	SP certificate (PEM)	`text`	—	after restart	Public SP signing certificate (PEM). The matching private key goes in Secrets (scope saml, name sp_key).

Schedules

Key	Name	Type	Default	Takes effect	What it does
`AIHUMMER_SCHEDULE_AGENT_MAX_ACTIVE`	Agent: active schedules limit	`int`	`20`	immediately	How many active schedules one agent may have when it creates or turns on a schedule by itself (its schedule tools). Schedules created in the panel count toward it, but the panel is never refused. At the limit the agent is told to pause or delete one first. Applies immediately.
`AIHUMMER_SCHEDULE_AGENT_MAX_FIRES_PER_DAY`	Agent: schedule runs per day	`int`	`288`	immediately	How many times per day (UTC) all schedules of one agent may run in total, including schedules created in the panel and manual runs. Runs above the limit are skipped and shown in the run log. Applies immediately.
`AIHUMMER_SCHEDULE_AGENT_MIN_INTERVAL_MINUTES`	Agent: minimum schedule interval, minutes	`int`	`5`	immediately	The shortest gap between two runs of a repeating schedule that an agent creates or changes by itself. A more frequent schedule is refused. Schedules created in the panel are not limited by it. Applies immediately.
`AIHUMMER_SCHEDULE_COMMANDS`	Commands on the server in schedules	`bool`	`0`	immediately	Lets a schedule run a program on this server — a collector, a report, a backup check. Off by default. Only commands from «Allowed commands» run, exactly as listed; there is no shell. The output goes to the agent or straight to a chat, and every run is in the schedule’s run log. Applies immediately.
`AIHUMMER_SCHEDULE_COMMANDS_ALLOWLIST`	Allowed commands	`argvlist`	—	immediately	The exact commands a schedule may run: the program (a name such as df or a full path) and its arguments. A schedule runs only a command that matches an entry exactly, arguments included. Removing a command stops the schedules that use it, and their runs say why. Applies immediately.
`AIHUMMER_SCHEDULE_COMMANDS_MAX_OUTPUT_KB`	Schedule command output limit, KB	`int 1…1024`	`64`	immediately	How much of a command’s output (1–1024 KB) is kept in the run log and passed on to the agent or chat; the rest is cut off, and the run log says so. Applies immediately.
`AIHUMMER_SCHEDULE_COMMANDS_SANDBOX`	Run schedule commands in the OS sandbox	`bool`	`1`	immediately	On: a command runs in the OS sandbox, like code execution — the installation’s secrets and SSH keys are hidden, and it writes only to its own temporary folder. Without the sandbox (bubblewrap) on the server the command does not run, and the run log says why. Off: it runs with the gateway’s rights. Applies immediately.
`AIHUMMER_SCHEDULE_FAILURE_ADMIN`	Report failed tasks to the administrator	`bool`	`1`	immediately	When a scheduled task fails or cannot start, put a notification with its name, the reason and where to fix it into the admin panel’s notification bell, and send the same to the owners’ own channel chats (at most once every 6 hours per task). This comes on top of the message to the task’s recipient. Off: the administrator learns about failures only from the run log. Applies immediately.
`AIHUMMER_SCHEDULE_FAILURE_NOTIFY`	Report failed tasks to the recipient	`bool`	`1`	immediately	When a scheduled task fails, send a short message to the same recipient (after the first failure, at most once every 6 hours). Off: failures stay only in the run log. A task can turn this off for itself in its form. Applies immediately.

Security

Key	Name	Type	Default	Takes effect	What it does
`AIHUMMER_AIRGAPPED`	Isolated mode (no internet)	`bool`	`0`	immediately	Stops agents from going to the internet: web search, page fetching and requests reach only internal addresses and those on the allowlists. Turn it on for closed networks without outside access.
`AIHUMMER_AUDIT_RETENTION_DAYS`	How many days to keep the audit log	`int`	`0`	after restart	Audit log and settings change history entries older than this are deleted once a day. 0 or blank — keep forever.
`AIHUMMER_CORS_ORIGINS`	Allowed CORS origins	`list`	—	after restart	Comma-separated list of allowed Origins. Blank = CORS not allowed (same-origin only). Applied at startup/after restart.
`AIHUMMER_CSP`	Content-Security-Policy header (override)	`text`	—	after restart	Overrides the CSP header. Blank = a safe default. Applied at startup/after restart.
`AIHUMMER_INBOUND_SECRET`	Channel plugins’ key to the server	`text`	—	after restart	Connected channels (Telegram, VK and others) use it to prove that messages really come from them. Set automatically during installation — no need to change it. If it is blank, the server refuses every channel until a key is set.
`AIHUMMER_OPENAI_COMPAT_KEY`	OpenAI-compatible inbound: static API key	`text`	—	after restart	A shared key for programs that connect to the server as an OpenAI-compatible service. Blank — the shared key is off; programs can connect with personal keys from the API keys page.
`AIHUMMER_OPENAI_COMPAT_WORKSPACE`	OpenAI-compatible inbound: workspace id	`text`	—	after restart	Workspace id that static OpenAI-compatible authentication maps to. Blank = AIHUMMER_DEFAULT_WORKSPACE_ID. Applied at startup/after restart.
`AIHUMMER_REQUIRE_2FA`	Require 2FA for operators	`bool`	`0`	immediately	Require a second factor (TOTP/passkey) for operators. When on, operators without 2FA are prompted to set it up immediately at login (without blocking, so the owner is never locked out). Applied immediately.
`AIHUMMER_REQUIRE_SECURE`	Accept only secure (HTTPS/WSS) connections	`bool`	`0`	after restart	When on, plain HTTP requests are redirected to HTTPS (for GET/HEAD) or rejected (403); localhost access is always allowed so the operator is never fenced out. Honors X-Forwarded-Proto from a TLS-terminating reverse proxy. Applied at startup/after restart.
`AIHUMMER_TRUSTED_PROXIES`	Trusted proxies	`list`	—	immediately	If a proxy (nginx, Caddy, load balancer) sits in front of the server, enter its address or network, comma-separated, e.g. 10.0.0.0/8. Then the audit log, IP allowlist and password-guessing protection see the visitor’s real address. Blank — only the direct connection address counts, and it cannot be spoofed.

Tools

Key	Name	Type	Default	Takes effect	What it does
`AIHUMMER_BROWSER_ALLOWED_HOSTNAMES`	Browser: private hostname exceptions	`list`	—	immediately	Exact comma-separated hostnames, without wildcards, URLs or ports. Additive private exceptions for self-hosted native CDP; separate from web_fetch.
`AIHUMMER_BROWSER_ALLOW_PRIVATE_NETWORK`	Browser: allow private network	`bool`	—	immediately	Blank keeps the previous policy; explicit true or false enables checked native CDP. Private access is self-hosted only. Loopback, link-local and metadata stay blocked.
`AIHUMMER_BROWSER_PROFILE_SOCKET`	Browser profile control socket	`text`	—	immediately	Optional. Leave empty and the gateway finds the browser service’s managed-profiles.sock at the standard install location. Logged-in browser profiles are created on Connections → Browser profiles. Not a URL and not a source profile path.
`AIHUMMER_CODE_EXEC`	Code execution by the agent	`enum: off \\\| host \\\| sandbox`	`off`	immediately	The agent’s code execution tool (code_exec). «Off» is the default. «On this server»: commands run on the gateway’s server; the OS sandbox (bubblewrap) hides the installation’s secrets, but an agent in «No restrictions» mode sees SSH keys and can write outside its folder — for a trusted server only. «Only in a sandbox»: always in the OS sandbox — secrets and keys are hidden, writes go only to the agent’s folder; without bubblewrap (or a container image) this mode cannot be saved. What each agent may run is set on the agent: Agents → profile → Tools.
`AIHUMMER_CODE_EXEC_INTERPRETERS`	Code-exec interpreters (JSON)	`text`	—	immediately	JSON object {language: path_to_binary}, e.g. {“python”:“/usr/bin/python3”}. Blank = auto-detect.
`AIHUMMER_CODE_EXEC_NET_PORTS`	Network ports open to agent code	`list`	`53,80,443`	immediately	TCP ports that agent code in the OS sandbox (code execution and schedule commands) may connect to, separated by commas. By default 53, 80 and 443: DNS and websites. Other services of this server and its local network (the database, the admin panel, the browser, adb, local models, Home Assistant) stay closed to agent code. A listed port is open on every address, this server included, so add only what code needs, such as 22 for SSH. Write any to lift the limit. Agents in «No restrictions» mode are not limited. Needs Linux 6.7 or newer; without it the limit does not apply, and Agents → Tools says so. Applies immediately.
`AIHUMMER_CODE_EXEC_READ_DIRS`	Folders open to agent code (read-only)	`list`	—	immediately	Folders on this server that agent code may read: code execution and schedule commands in the OS sandbox. Separate with commas or put one per line, for example ~/reports. You can also name a single file, such as ~/scripts/report.py. What you open here is visible to the code of every agent, so open only what that code needs. Empty by default: in the sandbox, code sees only its agent’s own folder and the system folders; the home folder of the gateway’s user, the installation’s data, other agents’ folders, keys and command history stay hidden. The root, the whole home folder, the installation’s data and places with keys cannot be opened. Code cannot write to these folders. Applies immediately.
`AIHUMMER_CODE_EXEC_SANDBOX_IMAGE`	Code-exec sandbox image	`text`	—	immediately	Optional, only for «Only in a sandbox»: a Docker container image instead of the OS sandbox (no network, read-only root, limits); needs Docker on the server. Blank = the OS sandbox (bubblewrap).
`AIHUMMER_CODE_EXEC_TIMEOUT_SECONDS`	Code execution time limit (seconds)	`int`	`1800`	immediately	How long one agent command may run, background ones included: 10 seconds to 24 hours. On a host with per-agent workspace folders, a command that has not answered within 30 seconds is not cut off but moves to the background, where the agent checks it with the process tool. Without agent folders or in a container there is no background and a call is capped at 10 minutes. The agent can ask for a shorter limit, never a longer one.
`AIHUMMER_DB_QUERY_DSN`	Database connection for the database-query tool	`text`	—	immediately	Connection string for a database the agent may read (read-only), e.g. postgres://reader:password@host/db. Use a user with minimal rights — not the database owner. Blank — the tool is off.
`AIHUMMER_FS_ROOT`	Filesystem tool root	`text`	—	immediately	The folder within which the agent reads this server’s files (filesystem_read; agents cannot write files). Blank = the whole server with the gateway user’s rights, except its secrets: installation settings (gateway.env), SSH/GPG keys and process environments. Enter a folder to narrow access.
`AIHUMMER_HTTP_ALLOWLIST`	Addresses for the agent’s HTTP requests	`list`	—	immediately	Comma-separated list of hosts the http_request tool may reach. Blank = all are allowed, except internal and private addresses.
`AIHUMMER_HTTP_AUTH_JSON`	http_request auth (JSON)	`text`	—	immediately	JSON map of host to authorization headers for the http_request tool, so tokens are not kept in the prompt. Blank = no authorization.
`AIHUMMER_MCP_SERVERS`	MCP servers (JSON)	`text`	—	immediately	JSON description of the external MCP servers whose tools are attached to the agent. Blank = no external MCP.
`AIHUMMER_PROJECT_STUDIOS_PUBLIC_NETWORK`	Project studios: public network	`bool`	`false`	immediately	Allow public HTTP(S) for chosen providers and explicit model downloads. Private, localhost and metadata addresses remain blocked. Air-gap overrides this setting. Applies immediately.
`AIHUMMER_SIDECAR_CLOAKBROWSER`	Browser for the agent (CloakBrowser)	`bool`	`0`	immediately	Anti-detect browser (CloakBrowser, browser/computer tools). What is NOT included in the delivery package: the inclusion downloads the signed add-on (~477 MiB, of which Chromium ~207 MiB) and installs the service on the host. The heaviest of sidecars - enable only if the agent needs to open websites.
`AIHUMMER_SIDECAR_SEARXNG`	Web search (SearXNG)	`bool`	`0`	immediately	Web search (SearXNG, web_search tool). NOT included in the package: turning on downloads the signed add-on (~154 MiB) and installs the service on the host, turning off stops it and frees up space. Installation occurs in the background and takes a few minutes; the state here shows what is actually on the server.
`AIHUMMER_WEBFETCH_ALLOWLIST`	Sites the agent may open	`list`	—	immediately	Comma-separated list of domains the web_fetch tool may reach. Blank = all are allowed, except internal and private addresses.
`AIHUMMER_WEB_SEARCH_LANGUAGE`	Web search: default result language	`text`	`auto`	immediately	Language of results when the agent doesn’t specify one: a code such as ru, en or de, or auto to detect it from the query (fits almost always). The agent can still pick another language for a particular search.
`AIHUMMER_WEB_SEARCH_RESULTS`	Web search: results per search	`int`	`5`	immediately	How many results a search returns when the agent doesn’t ask for a number: 1 to 10. More results give a fuller answer but a longer context.
`AIHUMMER_WEB_SEARCH_SOURCE`	Web search source	`enum: auto \\\| searxng \\\| provider`	`auto`	immediately	Where the agent searches the internet (the web_search tool). auto — SearXNG if it is installed, otherwise the model provider’s built-in search. searxng — SearXNG only: without it there is no search. provider — the provider’s built-in search where available, SearXNG for other models. Built-in search exists for Codex (ChatGPT subscription) and OpenAI (api.openai.com); GigaChat, YandexGPT and other OpenAI-compatible models have none — without SearXNG, agents on those models do not search. Claude (api.anthropic.com and the Claude subscription) uses Anthropic’s built-in search; if the account refuses it, the gateway writes that to the log and offers the agent SearXNG only. Which agents may search is set on the agent card, as before. Takes effect from the next turn.
`AIHUMMER_WEB_SEARCH_TIMEOUT_SECONDS`	Web search timeout (seconds)	`int`	`30`	immediately	1–600 seconds per search. A shorter task deadline still applies.

Updates

Key	Name	Type	Default	Takes effect	What it does
`AIHUMMER_RESTART_APPLY`	Apply settings that need a restart	`enum: quiet \\\| manual`	`quiet`	immediately	quiet (default) — saved settings that take effect only when the gateway starts again apply by themselves: the gateway restarts at the next quiet moment, when agents are idle and people have been silent for at least the quiet window. manual — only the “waiting for a restart” mark and the button. A restart takes a few seconds; conversations and tasks are not lost. Takes effect immediately.
`AIHUMMER_RESTART_QUIET_MINUTES`	Quiet moment: minutes of silence before an automatic restart	`int 0…1440`	`10`	immediately	How many minutes people must be silent (and agents idle) before the gateway restarts by itself to apply saved settings. 0 — as soon as agents finish their current work. 0–1440. Takes effect immediately.

Web UI (separate port)

Key	Name	Type	Default	Takes effect	What it does
`AIHUMMER_WEBUI_API_BASE`	Server address for a separately hosted panel	`text`	—	after restart	Needed only if the panel is opened from a different address than the server itself. Enter the address where the browser can reach the server, e.g. https://api.example.com. Blank — the server public address is used, or the local one if none is set.
`AIHUMMER_WEBUI_ENABLED`	Panel on a separate port	`bool`	`1`	after restart	On — the panel opens on a separate internal port that you can close off from the internet, and the public port serves only apps and channels. Turn it off to make the panel unavailable entirely.
`AIHUMMER_WEBUI_ORIGIN`	Address the panel is opened at	`text`	—	after restart	Fill in if the panel is opened through a proxy or by a name different from its port address, e.g. https://admin.example.com. The server will let a browser from that address talk to it. Blank — the panel port address is used.

Settings available to the operator: 237.