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
What it does
AIHUMMER_PERSONAL_API_KEYS
Personal API keys for OpenAI-compat
bool
1
“off” disables personal-key authentication on the OpenAI-compatible endpoint. Any other value = enabled. Applied at startup/after restart.
Agent
Key
Name
Type
Default
What it does
AIHUMMER_APPROVAL_TOOLS
Tools needing approval
multiselect
—
Comma-separated list of tools whose calls require manual operator approval before they run. Blank = no approval is required. Applied at startup/after restart.
AIHUMMER_SUBAGENT_MAX_DEPTH
Subagent max depth
int
2
Maximum nesting depth of subagents (an agent launching an agent). Default 2 — protection against endless recursion. Applied at startup/after restart.
AIHUMMER_SUBAGENT_TIMEOUT_SEC
Subagent timeout (seconds)
int
180
Maximum time for a single subagent run, in seconds. Applied at startup/after restart.
AIHUMMER_TOOL_SEARCH
Lazy tool loading (tool_search)
bool
false
Advertise only the core tools plus a search meta-tool and reveal the rest on demand. Speeds up turns and lowers cost when many tools are installed, with a small risk the model overlooks a rarely-used tool.
AIHUMMER_TOOL_SEARCH_CORE
Lazy tool loading: always-on tools
multiselect
—
Comma-separated tool names kept advertised up front even in lazy mode.
AIHUMMER_TOOL_SEARCH_THRESHOLD
Lazy tool loading: min tools to defer
int
12
Only defer when more than this many tools survive the agent’s profile filter.
Agent · Reasoning
Key
Name
Type
Default
What it does
AIHUMMER_AGENT_BEST_OF_N
Best-of-N samples (0/1=off, ≥2=on)
int
0
≥2 samples N candidates and judges the best. Costs N× generation.
AIHUMMER_AGENT_DEBATE_JUDGE_PROMPT
Debate: judge prompt (override)
text
—
Overrides the debate judge prompt (blank = built-in). Applied at startup/after restart.
AIHUMMER_AGENT_DEBATE_N
Debate panel size (0/1=off, ≥2=on)
int
0
≥2 runs a debate panel of N candidates + judge. Costs N× generation.
AIHUMMER_AGENT_DEBATE_PROMPT
Debate: candidate prompt (override)
text
—
Overrides the debate candidate prompt (blank = built-in). Applied at startup/after restart.
AIHUMMER_AGENT_DEBATE_ROUNDS
Debate: rounds
int
1
Number of debate rounds for the candidate panel. Applied at startup/after restart.
AIHUMMER_AGENT_JUDGE_PROMPT
Best-of-N judge prompt (override)
text
—
Overrides the best-of-N judge prompt (blank = built-in). Applied at startup/after restart.
AIHUMMER_AGENT_PLAN_PROMPT
Planner prompt (override)
text
—
Overrides the planner prompt (blank = built-in). Applied at startup/after restart.
AIHUMMER_AGENT_PLAN_STEPS
Planner-executor: max plan steps (0=off)
int
0
⟩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
Caps tool-calling iterations per plan step. 0 = built-in default (4).
AIHUMMER_AGENT_REFLECT
Self-critique pass
bool
0
Adds a reflection/self-critique pass before the final answer.
AIHUMMER_AGENT_REFLECT_PROMPT
Reflection prompt (override)
text
—
Overrides the self-critique prompt (blank = built-in). Applied at startup/after restart.
AIHUMMER_AGENT_SELF_HEAL
Self-heal tool-error retries (0=off)
int
0
⟩0 retries failed tool calls with a corrective hint, up to this bound.
Default reply language/locale hint, e.g. ru-RU. Persona/operator instructions override.
AIHUMMER_TIMEZONE
Timezone
text
UTC
IANA timezone for date injection, e.g. Europe/Moscow. Default UTC.
Channels
Key
Name
Type
Default
What it does
AIHUMMER_CONFIDENTIAL_PERSONA
Confidential web persona
bool
0
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. Applied at startup/after restart.
AIHUMMER_INBOUND_REQUIRE_BINDING
Reply only to provisioned users
bool
true
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
What it does
AIHUMMER_A2A_PUBLISH
Publish agent over Agent2Agent (A2A)
bool
0
Publish the agent as an A2A server (Agent Card + POST /a2a/message). Applied at startup/after restart.
AIHUMMER_MCP_EXPORT_TOOLS
MCP exported tools (comma-separated allowlist)
multiselect
—
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
Publish tools as an MCP server at POST /v1/mcp. Applied at startup/after restart.
Duration (e.g. 6h, 30m) for the background auto re-sync of every configured knowledge connector across all workspaces. Blank/0 = off. Re-sync is idempotent (replace by source, no duplicates). slack_export is excluded (its zip is uploaded manually). Applied at startup/after restart.
LLM
Key
Name
Type
Default
What it does
AIHUMMER_CASCADE_MIN_CHARS
Cascade: min chars to escalate
int
0
Request-length threshold (characters) at which the stronger cascade model kicks in. 0 = default. Applied at startup/after restart.
AIHUMMER_CASCADE_STRONG_MODEL
Cascade: stronger fallback model
text
—
Model to cascade to for long/complex requests (blank = off). Applied at startup/after restart.
AIHUMMER_CLAUDE_AUTH_URL
Claude subscription: consent page URL
text
—
The consent page that the operator opens. Empty is the default value. Lives on a DIFFERENT host than the token exchange.
AIHUMMER_CLAUDE_CLIENT_ID
Claude subscription: OAuth client id
text
—
Subscription Login Client ID Claude. Empty is the default value. Applicable immediately: the exchanger is assembled for each connection.
AIHUMMER_CLAUDE_MAX_TOKENS
Claude: max response tokens
int
16000
Response length limit (max_tokens) for wire Anthropic - both by subscription and by API key. The field for this wire is MANDATORY, there cannot be a zero. For generation 5 models, reflections are turned on by default and are counted towards the same budget: too low a value results in a break in mid-sentence or an empty answer. The value of the agent parameters (max_tokens) is more important than this. Apply on the fly: saving the settings reassembles the providers.
AIHUMMER_CLAUDE_REDIRECT_URI
Claude subscription: redirect URI
text
—
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: token exchange URL
text
—
Token exchange and renewal address. Empty is the default value. Does not match the address of the consent page.
AIHUMMER_CODEX_BASE_URL
Codex base URL
text
—
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
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
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
low
The model’s reasoning depth for chat turns when the agent’s parameters don’t set it. Valid gpt-5.5 values: none, low, medium, high, xhigh (NOT minimal — gpt-5.5 rejects it with HTTP 400). Higher = better quality but slower/more expensive. An invalid value is safely coerced to low. Applied on the fly (no restart).
AIHUMMER_LLM_CALL_TIMEOUT_S
Per-call timeout (seconds)
int
120
Time budget for a SINGLE model call (anti-stall: gpt-5.5 can ‘think’ indefinitely and hold the turn open). On expiry the call fails with ErrCallTimeout without retries. 0 = no limit. Applied on the fly (no restart).
AIHUMMER_LLM_GATEWAY_URL
LLM gateway URL
text
—
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
—
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_PROVIDER
LLM provider
text
—
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
Number of LLM request retries on a transient error. Applied at startup/after restart.
AIHUMMER_LLM_TEMPERATURE
Temperature
text
—
Sampling temperature (0..2) when the agent’s parameters don’t set it. Blank = don’t send. NOTE: the gpt-5.5 reasoning models (Codex) reject temperature — leave the field blank for them; set it only when using a non-reasoning backend. Applied on the fly (no restart).
AIHUMMER_LLM_TOP_P
Top-p (nucleus sampling)
text
—
Nucleus-sampling threshold (0..1) when the agent’s parameters don’t set it. Blank = don’t send. Like temperature, gpt-5.5 reasoning rejects it — set it only for non-reasoning backends. Applied on the fly (no 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
—
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
—
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
—
Model for complex requests (blank = band disabled). Applied at startup/after restart.
AIHUMMER_ROUTER_SIMPLE_MODEL
Router: model for simple turns
text
—
Model for simple requests (blank = band disabled). Applied at startup/after restart.
AIHUMMER_ROUTER_STANDARD_MODEL
Router: model for standard turns
text
—
Model for standard requests (blank = band disabled). Applied at startup/after restart.
Media
Key
Name
Type
Default
What it does
AIHUMMER_DEEPGRAM_API_KEY
Deepgram API key
text
—
Deepgram API key (STT engine = deepgram). Taken from here or from AIHUMMER_STT_API_KEY. Applied at startup/after restart.
AIHUMMER_DEEPGRAM_MODEL
Deepgram model
text
nova-2
Deepgram model (e.g. nova-2, nova-3, base). Depends on the project’s access for the key. Applied at startup/after restart.
Base of the /images API when working through an OpenAI key (blank = https://api.openai.com/v1). Applied at startup/after restart.
AIHUMMER_IMAGE_MODEL
Image-generation model
text
—
Model for image_generate (default gpt-image-2). Applied at startup/after restart.
AIHUMMER_MEDIA_MAX_UPLOAD_MB
Media max upload size (MB)
int
256
Maximum size of a single media upload (PUT /v1/media/{id}/content), in megabytes. Bounds disk writes via the public port (overflow protection). Default 256. Applied at startup/after restart.
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
Speech synthesis sidecar (edge-tts) installed
bool
0
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
—
Optional bearer if the STT sidecar requires one (install.sh may generate it). Applied at startup/after restart.
AIHUMMER_STT_ENGINE
STT engine
enum: faster-whisper \| deepgram \| off
faster-whisper
Speech-recognition engine. A normal installation starts with recognition off. faster-whisper = the local service installed from the signed add-on by the “Speech recognition sidecar” switch below; its URL is configured automatically. You can also point the URL field at a compatible external /v1/audio/transcriptions service. deepgram = Deepgram in the cloud and needs your own API key. off = recognition disabled. On a cloud plan the local-service URL is provider-managed, so customers use Deepgram with their own key. Applied at startup/after restart.
AIHUMMER_STT_LANGUAGE
STT language
text
—
Recognition language (BCP-47, e.g. ru/en). Used by the deepgram engine (nova-2 model). Blank = auto-detect / engine default. Applied at startup/after restart.
AIHUMMER_STT_MODEL
STT model
text
Systran/faster-whisper-small
faster-whisper model (e.g. small/medium/large-v3 or Systran/faster-whisper-⟨size⟩). Applied at startup/after restart.
AIHUMMER_TTS_API_KEY
TTS API key (edge-tts)
text
—
Bearer between the gateway and the edge-tts sidecar (install.sh generates it automatically). Applied at startup/after restart.
AIHUMMER_TTS_ENABLED
Text-to-speech enabled
bool
1
Enables speech synthesis (the tts tool + voice mode). The edge-tts sidecar itself is NOT part of the package — it is installed on demand from the «Speech synthesis sidecar (edge-tts) installed» switch above. Applied at startup/after restart.
AIHUMMER_TTS_MODEL
TTS model
text
—
Model name for the edge-tts service. Applied at startup/after restart.
Default edge-tts voice (multilingual, incl. Russian). Applied at startup/after restart.
AIHUMMER_VIDEO_API_KEY
Video analysis API key
text
—
Access key for the video-analysis sidecar (if required). Applied at startup/after restart.
Media · Voice
Key
Name
Type
Default
What it does
AIHUMMER_VOICE_AEC
Echo cancellation (AEC)
bool
1
Require echoCancellation on capture (WebRTC). Removes TTS echo into the microphone (Moltis #1129).
AIHUMMER_VOICE_AGC
Auto gain control
bool
1
Require automatic microphone gain control (WebRTC autoGainControl) in voice mode.
AIHUMMER_VOICE_BARGEIN_FRAMES
Barge-in frames
int
5
How many consecutive voiced frames (≈20ms) interrupt the bot’s playback.
AIHUMMER_VOICE_DUPLEX
Live full-duplex voice
bool
0
Enables live full-duplex mode (streaming + VAD + barge-in). Applied at startup/after restart.
AIHUMMER_VOICE_NOISE_SUPPRESSION
Noise suppression
bool
1
Require noise suppression on microphone capture (WebRTC noiseSuppression) in voice mode.
AIHUMMER_VOICE_VAD_THRESHOLD
VAD energy threshold (0..1)
text
0.02
Speech-energy threshold for VAD gating of capture; lower = more sensitive.
Memory
Key
Name
Type
Default
What it does
AIHUMMER_EMBEDDER_DIM
Embedder vector dim
int
768
Vector dimension — must match the model (multilingual-e5-base=768, bge-m3=1024).
AIHUMMER_EMBEDDER_KEEPALIVE
Embedder keep-alive
text
5m
keep_alive for the Ollama embedder (only when AIHUMMER_MEMORY_RETRIEVAL=embedding). Default 5m — an idle model is unloaded and a stuck idle ollama runner clears itself. -1 (keep forever) is NOT recommended: due to an ollama bug a stuck runner can peg a CPU core for days. The cold start after idling is offset by a warm-up at gateway startup. Applied at startup/after restart.
AIHUMMER_EMBEDDER_MODEL
Embedder model
text
yxchia/multilingual-e5-base
Ollama embedding model. Default multilingual-e5-base — multilingual (incl. Russian), 768-dim, light + fast on CPU (~1-2s/embed). e5 query/passage prefixes are applied automatically. For max quality on GPU hardware use bge-m3 (set DIM=1024). Must match AIHUMMER_EMBEDDER_DIM.
AIHUMMER_EMBEDDER_PASSAGE_PREFIX
Embedder passage prefix
text
—
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
—
Override the retrieval-query prefix (e5 models auto-use “query: “). Leave blank to auto-detect by model name.
AIHUMMER_MEMORY_CAPTURE
Memory capture mode
enum: auto \| review \| off
auto
auto = remember + recall automatically; review = remember as candidates needing manual approval; off = no capture.
AIHUMMER_MEMORY_CONTEXT_TIMEOUT
Memory hydration timeout
text
3s
Maximum wait for memory hydration at the start of a reply (query embedding + search). If the embedder is overloaded and misses the deadline, the reply proceeds WITHOUT the memory block instead of hanging. Go duration format (e.g. 2s, 1500ms). 0 = no limit. Applied at startup/after restart.
AIHUMMER_MEMORY_DREAM_INTERVAL
Dream pass interval
string
1h
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.
AIHUMMER_MEMORY_EXTRACT
LLM fact extraction
bool
1
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.
AIHUMMER_MEMORY_RETRIEVAL
Memory retrieval mode
enum: fulltext \| embedding
fulltext
How memory is searched. fulltext (default) = Postgres full-text search over fact text — NO embedder model, no sidecar, no CPU load (like the old einstein in AiHummer). embedding = semantic vector search via an embedder (AIHUMMER_EMBEDDER_URL/ollama) — more accurate by meaning, but loads the CPU and requires a sidecar. Applied at startup/after restart.
AIHUMMER_MEMORY_TOKEN
Remote memory service token
text
—
Service token to authorize with the Einstein Retrieval API (sent as Authorization: Bearer …). Needed only when AIHUMMER_MEMORY_URL is set. Blank = no authorization (only for dev installs with retrieval auth disabled).
AIHUMMER_MEMORY_URL
Remote memory URL (Einstein plugin)
text
—
URL of the standalone Einstein memory plugin (contract aihummer.memory.v1, e.g. http://127.0.0.1:8820). BLANK (default) = the in-process Go memory module. When set, turn-context hydration goes over HTTP to the plugin’s /context + /retrieval; on error/unavailability it softly falls back to the built-in module (no crashes). Applied at startup/after restart.
AIHUMMER_QDRANT_API_KEY
Qdrant API key
text
—
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
—
UNSET = in-memory store (vectors LOST on restart). Set for production durability.
AIHUMMER_RERANKER_URL
RAG reranker sidecar URL
text
—
HTTP URL of the cross-encoder sidecar for reranking hybrid search. Blank = reranking off. Applied at startup/after restart.
Moderation
Key
Name
Type
Default
What it does
AIHUMMER_MODERATION
Input moderation
bool
1
“off” disables the built-in guard against jailbreak/prompt-injection. Any other value = enabled. Applied at startup/after restart.
AIHUMMER_MODERATION_REFUSAL
Moderation refusal message
text
—
Refusal text returned when the moderator blocks a request (blank = built-in). Applied at startup/after restart.
Network
Key
Name
Type
Default
What it does
AIHUMMER_OUTBOUND_PROXY_CUSTOM_URL
Outbound proxy: custom address
text
—
Proxy URL such as https://user:password@host:port; used only in custom mode. Plain HTTP is allowed only for loopback because Proxy-Authorization would otherwise send the password in cleartext. Paths, query strings, and fragments are forbidden. The value is stored as a secret and never returned in plaintext.
AIHUMMER_OUTBOUND_PROXY_MODE
Outbound proxy for foreign model providers
enum: auto \| off \| custom
auto
auto (default) uses the provider configuration from installation; off never uses a proxy (for installations outside Russia); custom uses the address from the field below. OpenAI, Anthropic, Google, DeepSeek, and other foreign providers block Russian IP addresses, so they require a proxy in an allowed region. GigaChat, YandexGPT, and internal addresses always bypass the proxy. Applied immediately when saved.
AIHUMMER_RUSSIAN_TRUSTED_EXTRA_HOSTS
Hosts beyond .ru for the Russian Trusted roots
text
—
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).
Public access
Key
Name
Type
Default
What it does
AIHUMMER_PUBLIC_URL
Gateway public URL (Web UI + clients)
text
—
Proxy this host → the gateway port (AIHUMMER_GATEWAY_ADDR, default :8780). Used by the Web UI and the iOS/web clients.
AIHUMMER_WIDGET_ALLOWED_ORIGINS
Web widget: allowed site origins
text
—
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
—
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
—
Webhook mode only — proxy → the telegram-connector port (AIHUMMER_TELEGRAM_CONNECTOR_PORT, default 8091). Leave blank to use polling (no public URL needed).
SSO (LDAP/AD)
Key
Name
Type
Default
What it does
AIHUMMER_LDAP_BASE_DN
User search base DN
text
—
Search root, e.g. OU=Users,DC=corp,DC=example.
AIHUMMER_LDAP_BIND_DN
Service bind DN
text
—
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
—
Role granted when no group matches a mapping. Blank = no role.
AIHUMMER_LDAP_ENABLED
Enable LDAP/AD login
bool
0
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
—
Attribute on the user entry listing group DNs. Blank disables group→role mapping.
AIHUMMER_LDAP_ROLE_MAPPINGS
LDAP: Group→role mappings (JSON)
text
—
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
Disables directory certificate verification. Never enable in production.
AIHUMMER_LDAP_URL
Directory URL
text
—
e.g. ldaps://ad.corp.example:636 (TLS) or ldap://dc1.corp.example:389.
AIHUMMER_LDAP_USER_ATTR
Login attribute (default sAMAccountName)
text
—
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
—
Must contain %s for the login. AD: (sAMAccountName=%s); OpenLDAP: (uid=%s).
SSO (OIDC)
Key
Name
Type
Default
What it does
AIHUMMER_OIDC_AUDIENCE
OIDC audience
text
—
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.
JSON Web Key Set endpoint used to verify token signatures.
AIHUMMER_OIDC_TENANT_CLAIM
OIDC workspace claim
text
—
JWT claim carrying the workspace id (e.g. tenant_id / org).
SSO (SAML)
Key
Name
Type
Default
What it does
AIHUMMER_SAML_DEFAULT_ROLE
SAML: Default role (no group match)
text
—
Role granted when no asserted value maps. Blank = no role.
AIHUMMER_SAML_ENABLED
Enable SAML 2.0 SSO
bool
0
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
—
SP entity ID (defaults to ⟨root⟩/saml/metadata if blank).
AIHUMMER_SAML_IDP_METADATA
IdP metadata XML
text
—
Paste the IdP’s SAML metadata document (Okta/Azure AD/ADFS).
AIHUMMER_SAML_ROLE_ATTRIBUTE
Role/group attribute (default groups)
text
—
Assertion attribute carrying group/role values.
AIHUMMER_SAML_ROLE_MAPPINGS
SAML: Group→role mappings (JSON)
text
—
JSON object of asserted value → role, e.g. {“AdminGroup”:“admin”,“Ops”:“operator”}.
AIHUMMER_SAML_ROOT_URL
SP root URL
text
—
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
—
Public SP signing certificate (PEM). The matching private key goes in Secrets (scope saml, name sp_key).
Security
Key
Name
Type
Default
What it does
AIHUMMER_AIRGAPPED
Air-gapped mode
bool
0
Blocks model-driven egress to the public internet (internal or allowlisted hosts only). Applied at startup/after restart.
AIHUMMER_AUDIT_RETENTION_DAYS
Audit-log retention (days, 0=forever)
int
0
How many days to keep the audit log; older entries are deleted daily. 0/blank = keep forever. Applied at startup/after restart.
AIHUMMER_CODE_EXEC_ALLOW_HOST
Allow code_exec on the host (NO sandbox)
bool
0
⚠️ Allow code execution directly on the host with no sandbox. For a trusted homelab only. It is safer to set AIHUMMER_CODE_EXEC_SANDBOX_IMAGE. Applied at startup/after restart.
AIHUMMER_CORS_ORIGINS
Allowed CORS origins (comma)
text
—
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
—
Overrides the CSP header. Blank = a safe default. Applied at startup/after restart.
AIHUMMER_INBOUND_SECRET
Connector→gateway shared secret
text
—
Shared secret authenticating the connector→gateway hop (must match the value on the connector side). Blank = the inbound endpoint is UNAUTHENTICATED. Applied at startup/after restart.
AIHUMMER_OPENAI_COMPAT_KEY
OpenAI-compatible inbound: static API key
text
—
Static key OpenAI-compatible clients use to authenticate against the gateway’s built-in /v1 endpoint (P8 home gateway). Blank = static auth disabled (personal keys remain). Applied at startup/after restart.
AIHUMMER_OPENAI_COMPAT_WORKSPACE
OpenAI-compatible inbound: workspace id
text
—
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
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
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 reverse-proxy CIDRs (comma)
text
—
Comma-separated list of trusted reverse-proxy networks (CIDR, e.g. 10.0.0.0/8,192.168.0.0/16, or single IPs). Only for requests COMING from these addresses is the X-Forwarded-For header used to determine the client IP (audit, IP allowlist, anti-brute-force). Blank = trust ONLY the real peer address (XFF ignored, IP spoofing impossible). Applied on the fly.
Tools
Key
Name
Type
Default
What it does
AIHUMMER_CODE_EXEC
Enable code_exec
bool
0
Enables the code execution tool (code_exec); it is off by default. For isolation set a sandbox image, or explicitly allow execution on the host. Applied at startup/after restart.
AIHUMMER_CODE_EXEC_INTERPRETERS
Code-exec interpreters (JSON)
text
—
JSON object {language: path_to_binary}, e.g. {“python”:“/usr/bin/python3”}. Blank = auto-detect. Applied at startup/after restart.
AIHUMMER_CODE_EXEC_SANDBOX_IMAGE
Code-exec sandbox image
text
—
Container image for isolating code_exec (no network, read-only rootfs, limits). Blank = host-exec (trusted environment). Applied at startup/after restart.
AIHUMMER_DB_QUERY_DSN
db_query DSN (use a least-privilege, non-owner role — queries run RLS-scoped to the acting workspace)
text
—
Database DSN for the read-only db_query tool; use a least-privilege role, not owner or superuser, since queries run RLS-scoped to the workspace. Blank = the tool is off. Applied at startup/after restart.
AIHUMMER_FS_ROOT
Filesystem tool root
text
—
Root directory the file read/write tools are confined to (sandbox). Blank = file tools are off. Applied at startup/after restart.
AIHUMMER_HTTP_ALLOWLIST
http_request allowlist
text
—
Comma-separated list of hosts the http_request tool may reach. Blank = all are allowed, except internal and private addresses. Applied at startup/after restart.
AIHUMMER_HTTP_AUTH_JSON
http_request auth (JSON)
text
—
JSON map of host to authorization headers for the http_request tool, so tokens are not kept in the prompt. Blank = no authorization. Applied at startup/after restart.
AIHUMMER_MCP_SERVERS
MCP servers (JSON)
text
—
JSON description of the external MCP servers whose tools are attached to the agent. Blank = no external MCP. Applied at startup/after restart.
AIHUMMER_SIDECAR_CLOAKBROWSER
Browser sidecar (CloakBrowser) installed
bool
0
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 sidecar (SearXNG) installed
bool
0
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
web_fetch allowlist
text
—
Comma-separated list of domains the web_fetch tool may reach. Blank = all are allowed, except internal and private addresses. Applied at startup/after restart.
Web UI (separate port)
Key
Name
Type
Default
What it does
AIHUMMER_WEBUI_API_BASE
API base URL the Web UI calls
text
—
Absolute origin (e.g. https://api.example.com) the separately-hosted SPA targets for /v1/admin/* calls. Blank = fall back to the gateway public URL, then to the local gateway address. Must be reachable from the admin’s browser; the API must allow this Web UI’s origin via CORS (auto-added below).
AIHUMMER_WEBUI_ENABLED
Serve admin Web UI on its own port
bool
1
Enabled by default: the admin SPA is served at the ROOT of a separate listener (AIHUMMER_WEBUI_ADDR) that can be bound to an internal-only interface. The main gateway port keeps API + pairing + WS + SSE and does NOT serve /admin/. Set to 0 to disable the Web UI listener entirely.
AIHUMMER_WEBUI_ORIGIN
Web UI browser origin (CORS)
text
—
Browser Origin of the Web UI (e.g. https://admin.example.com), auto-added to the API CORS allowlist with credentials. Blank = derived from AIHUMMER_WEBUI_ADDR (http://host:port). Set this when the browser reaches the Web UI via a proxy/hostname different from the bind address.
Settings available to the operator: 146.
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](/en/v1.2/reference/cli/)). 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 | What it does |
| --- | --- | --- | --- | --- |
| `AIHUMMER_PERSONAL_API_KEYS` | Personal API keys for OpenAI-compat | bool | `1` | "off" disables personal-key authentication on the OpenAI-compatible endpoint. Any other value = enabled. Applied at startup/after restart. |
## Agent
| Key | Name | Type | Default | What it does |
| --- | --- | --- | --- | --- |
| `AIHUMMER_APPROVAL_TOOLS` | Tools needing approval | multiselect | — | Comma-separated list of tools whose calls require manual operator approval before they run. Blank = no approval is required. Applied at startup/after restart. |
| `AIHUMMER_SUBAGENT_MAX_DEPTH` | Subagent max depth | int | `2` | Maximum nesting depth of subagents (an agent launching an agent). Default 2 — protection against endless recursion. Applied at startup/after restart. |
| `AIHUMMER_SUBAGENT_TIMEOUT_SEC` | Subagent timeout (seconds) | int | `180` | Maximum time for a single subagent run, in seconds. Applied at startup/after restart. |
| `AIHUMMER_TOOL_SEARCH` | Lazy tool loading (tool_search) | bool | `false` | Advertise only the core tools plus a search meta-tool and reveal the rest on demand. Speeds up turns and lowers cost when many tools are installed, with a small risk the model overlooks a rarely-used tool. |
| `AIHUMMER_TOOL_SEARCH_CORE` | Lazy tool loading: always-on tools | multiselect | — | Comma-separated tool names kept advertised up front even in lazy mode. |
| `AIHUMMER_TOOL_SEARCH_THRESHOLD` | Lazy tool loading: min tools to defer | int | `12` | Only defer when more than this many tools survive the agent's profile filter. |
## Agent · Reasoning
| Key | Name | Type | Default | What it does |
| --- | --- | --- | --- | --- |
| `AIHUMMER_AGENT_BEST_OF_N` | Best-of-N samples (0/1=off, ≥2=on) | int | `0` | ≥2 samples N candidates and judges the best. Costs N× generation. |
| `AIHUMMER_AGENT_DEBATE_JUDGE_PROMPT` | Debate: judge prompt (override) | text | — | Overrides the debate judge prompt (blank = built-in). Applied at startup/after restart. |
| `AIHUMMER_AGENT_DEBATE_N` | Debate panel size (0/1=off, ≥2=on) | int | `0` | ≥2 runs a debate panel of N candidates + judge. Costs N× generation. |
| `AIHUMMER_AGENT_DEBATE_PROMPT` | Debate: candidate prompt (override) | text | — | Overrides the debate candidate prompt (blank = built-in). Applied at startup/after restart. |
| `AIHUMMER_AGENT_DEBATE_ROUNDS` | Debate: rounds | int | `1` | Number of debate rounds for the candidate panel. Applied at startup/after restart. |
| `AIHUMMER_AGENT_JUDGE_PROMPT` | Best-of-N judge prompt (override) | text | — | Overrides the best-of-N judge prompt (blank = built-in). Applied at startup/after restart. |
| `AIHUMMER_AGENT_PLAN_PROMPT` | Planner prompt (override) | text | — | Overrides the planner prompt (blank = built-in). Applied at startup/after restart. |
| `AIHUMMER_AGENT_PLAN_STEPS` | Planner-executor: max plan steps (0=off) | int | `0` | ⟩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` | Caps tool-calling iterations per plan step. 0 = built-in default (4). |
| `AIHUMMER_AGENT_REFLECT` | Self-critique pass | bool | `0` | Adds a reflection/self-critique pass before the final answer. |
| `AIHUMMER_AGENT_REFLECT_PROMPT` | Reflection prompt (override) | text | — | Overrides the self-critique prompt (blank = built-in). Applied at startup/after restart. |
| `AIHUMMER_AGENT_SELF_HEAL` | Self-heal tool-error retries (0=off) | int | `0` | ⟩0 retries failed tool calls with a corrective hint, up to this bound. |
## Agent · System prompt
| Key | Name | Type | Default | 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` | Default reply language/locale hint, e.g. ru-RU. Persona/operator instructions override. |
| `AIHUMMER_TIMEZONE` | Timezone | text | `UTC` | IANA timezone for date injection, e.g. Europe/Moscow. Default UTC. |
## Channels
| Key | Name | Type | Default | What it does |
| --- | --- | --- | --- | --- |
| `AIHUMMER_CONFIDENTIAL_PERSONA` | Confidential web persona | bool | `0` | 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. Applied at startup/after restart. |
| `AIHUMMER_INBOUND_REQUIRE_BINDING` | Reply only to provisioned users | bool | `true` | 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 | What it does |
| --- | --- | --- | --- | --- |
| `AIHUMMER_A2A_PUBLISH` | Publish agent over Agent2Agent (A2A) | bool | `0` | Publish the agent as an A2A server (Agent Card + POST /a2a/message). Applied at startup/after restart. |
| `AIHUMMER_MCP_EXPORT_TOOLS` | MCP exported tools (comma-separated allowlist) | multiselect | — | 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` | Publish tools as an MCP server at POST /v1/mcp. Applied at startup/after restart. |
## Knowledge connectors
| Key | Name | Type | Default | What it does |
| --- | --- | --- | --- | --- |
| `AIHUMMER_KB_SYNC_INTERVAL` | Scheduled connector re-sync interval (0/empty = off) | text | — | Duration (e.g. 6h, 30m) for the background auto re-sync of every configured knowledge connector across all workspaces. Blank/0 = off. Re-sync is idempotent (replace by source, no duplicates). slack_export is excluded (its zip is uploaded manually). Applied at startup/after restart. |
## LLM
| Key | Name | Type | Default | What it does |
| --- | --- | --- | --- | --- |
| `AIHUMMER_CASCADE_MIN_CHARS` | Cascade: min chars to escalate | int | `0` | Request-length threshold (characters) at which the stronger cascade model kicks in. 0 = default. Applied at startup/after restart. |
| `AIHUMMER_CASCADE_STRONG_MODEL` | Cascade: stronger fallback model | text | — | Model to cascade to for long/complex requests (blank = off). Applied at startup/after restart. |
| `AIHUMMER_CLAUDE_AUTH_URL` | Claude subscription: consent page URL | text | — | The consent page that the operator opens. Empty is the default value. Lives on a DIFFERENT host than the token exchange. |
| `AIHUMMER_CLAUDE_CLIENT_ID` | Claude subscription: OAuth client id | text | — | Subscription Login Client ID Claude. Empty is the default value. Applicable immediately: the exchanger is assembled for each connection. |
| `AIHUMMER_CLAUDE_MAX_TOKENS` | Claude: max response tokens | int | `16000` | Response length limit (max_tokens) for wire Anthropic - both by subscription and by API key. The field for this wire is MANDATORY, there cannot be a zero. For generation 5 models, reflections are turned on by default and are counted towards the same budget: too low a value results in a break in mid-sentence or an empty answer. The value of the agent parameters (max_tokens) is more important than this. Apply on the fly: saving the settings reassembles the providers. |
| `AIHUMMER_CLAUDE_REDIRECT_URI` | Claude subscription: redirect URI | text | — | 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: token exchange URL | text | — | Token exchange and renewal address. Empty is the default value. Does not match the address of the consent page. |
| `AIHUMMER_CODEX_BASE_URL` | Codex base URL | text | — | 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` | 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` | 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 | `low` | The model's reasoning depth for chat turns when the agent's parameters don't set it. Valid gpt-5.5 values: none, low, medium, high, xhigh (NOT minimal — gpt-5.5 rejects it with HTTP 400). Higher = better quality but slower/more expensive. An invalid value is safely coerced to low. Applied on the fly (no restart). |
| `AIHUMMER_LLM_CALL_TIMEOUT_S` | Per-call timeout (seconds) | int | `120` | Time budget for a SINGLE model call (anti-stall: gpt-5.5 can 'think' indefinitely and hold the turn open). On expiry the call fails with ErrCallTimeout without retries. 0 = no limit. Applied on the fly (no restart). |
| `AIHUMMER_LLM_GATEWAY_URL` | LLM gateway URL | text | — | 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 | — | 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_PROVIDER` | LLM provider | text | — | 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` | Number of LLM request retries on a transient error. Applied at startup/after restart. |
| `AIHUMMER_LLM_TEMPERATURE` | Temperature | text | — | Sampling temperature (0..2) when the agent's parameters don't set it. Blank = don't send. NOTE: the gpt-5.5 reasoning models (Codex) reject temperature — leave the field blank for them; set it only when using a non-reasoning backend. Applied on the fly (no restart). |
| `AIHUMMER_LLM_TOP_P` | Top-p (nucleus sampling) | text | — | Nucleus-sampling threshold (0..1) when the agent's parameters don't set it. Blank = don't send. Like temperature, gpt-5.5 reasoning rejects it — set it only for non-reasoning backends. Applied on the fly (no restart). |
| `AIHUMMER_OPENAI_API` | OpenAI API style (chat \| responses) | enum: \\\| chat \\\| responses | — | chat = /chat/completions, responses = /responses. Blank = auto/default. Applied at startup/after restart. |
| `AIHUMMER_OPENAI_API_KEY` | Native OpenAI API key (deployment default) | text | — | 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 | — | 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 | — | 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 | — | Model for complex requests (blank = band disabled). Applied at startup/after restart. |
| `AIHUMMER_ROUTER_SIMPLE_MODEL` | Router: model for simple turns | text | — | Model for simple requests (blank = band disabled). Applied at startup/after restart. |
| `AIHUMMER_ROUTER_STANDARD_MODEL` | Router: model for standard turns | text | — | Model for standard requests (blank = band disabled). Applied at startup/after restart. |
## Media
| Key | Name | Type | Default | What it does |
| --- | --- | --- | --- | --- |
| `AIHUMMER_DEEPGRAM_API_KEY` | Deepgram API key | text | — | Deepgram API key (STT engine = deepgram). Taken from here or from AIHUMMER_STT_API_KEY. Applied at startup/after restart. |
| `AIHUMMER_DEEPGRAM_MODEL` | Deepgram model | text | `nova-2` | Deepgram model (e.g. nova-2, nova-3, base). Depends on the project's access for the key. Applied at startup/after restart. |
| `AIHUMMER_DEEPGRAM_URL` | Deepgram base URL | text | — | Deepgram API base. Blank = https://api.deepgram.com. Applied at startup/after restart. |
| `AIHUMMER_IMAGE_BASE_URL` | Image API base URL (OpenAI fallback) | text | — | Base of the /images API when working through an OpenAI key (blank = https://api.openai.com/v1). Applied at startup/after restart. |
| `AIHUMMER_IMAGE_MODEL` | Image-generation model | text | — | Model for image_generate (default gpt-image-2). Applied at startup/after restart. |
| `AIHUMMER_MEDIA_MAX_UPLOAD_MB` | Media max upload size (MB) | int | `256` | Maximum size of a single media upload (PUT /v1/media/{id}/content), in megabytes. Bounds disk writes via the public port (overflow protection). Default 256. Applied at startup/after restart. |
| `AIHUMMER_SIDECAR_STT` | Speech recognition sidecar (faster-whisper) installed | bool | `0` | 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` | Speech synthesis sidecar (edge-tts) installed | bool | `0` | 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 | — | Optional bearer if the STT sidecar requires one (install.sh may generate it). Applied at startup/after restart. |
| `AIHUMMER_STT_ENGINE` | STT engine | enum: faster-whisper \\\| deepgram \\\| off | `faster-whisper` | Speech-recognition engine. A normal installation starts with recognition off. faster-whisper = the local service installed from the signed add-on by the “Speech recognition sidecar” switch below; its URL is configured automatically. You can also point the URL field at a compatible external /v1/audio/transcriptions service. deepgram = Deepgram in the cloud and needs your own API key. off = recognition disabled. On a cloud plan the local-service URL is provider-managed, so customers use Deepgram with their own key. Applied at startup/after restart. |
| `AIHUMMER_STT_LANGUAGE` | STT language | text | — | Recognition language (BCP-47, e.g. ru/en). Used by the deepgram engine (nova-2 model). Blank = auto-detect / engine default. Applied at startup/after restart. |
| `AIHUMMER_STT_MODEL` | STT model | text | `Systran/faster-whisper-small` | faster-whisper model (e.g. small/medium/large-v3 or Systran/faster-whisper-⟨size⟩). Applied at startup/after restart. |
| `AIHUMMER_TTS_API_KEY` | TTS API key (edge-tts) | text | — | Bearer between the gateway and the edge-tts sidecar (install.sh generates it automatically). Applied at startup/after restart. |
| `AIHUMMER_TTS_ENABLED` | Text-to-speech enabled | bool | `1` | Enables speech synthesis (the tts tool + voice mode). The edge-tts sidecar itself is NOT part of the package — it is installed on demand from the «Speech synthesis sidecar (edge-tts) installed» switch above. Applied at startup/after restart. |
| `AIHUMMER_TTS_MODEL` | TTS model | text | — | 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` | Default edge-tts voice (multilingual, incl. Russian). Applied at startup/after restart. |
| `AIHUMMER_VIDEO_API_KEY` | Video analysis API key | text | — | Access key for the video-analysis sidecar (if required). Applied at startup/after restart. |
## Media · Voice
| Key | Name | Type | Default | What it does |
| --- | --- | --- | --- | --- |
| `AIHUMMER_VOICE_AEC` | Echo cancellation (AEC) | bool | `1` | Require echoCancellation on capture (WebRTC). Removes TTS echo into the microphone (Moltis #1129). |
| `AIHUMMER_VOICE_AGC` | Auto gain control | bool | `1` | Require automatic microphone gain control (WebRTC autoGainControl) in voice mode. |
| `AIHUMMER_VOICE_BARGEIN_FRAMES` | Barge-in frames | int | `5` | How many consecutive voiced frames (≈20ms) interrupt the bot's playback. |
| `AIHUMMER_VOICE_DUPLEX` | Live full-duplex voice | bool | `0` | Enables live full-duplex mode (streaming + VAD + barge-in). Applied at startup/after restart. |
| `AIHUMMER_VOICE_NOISE_SUPPRESSION` | Noise suppression | bool | `1` | Require noise suppression on microphone capture (WebRTC noiseSuppression) in voice mode. |
| `AIHUMMER_VOICE_VAD_THRESHOLD` | VAD energy threshold (0..1) | text | `0.02` | Speech-energy threshold for VAD gating of capture; lower = more sensitive. |
## Memory
| Key | Name | Type | Default | What it does |
| --- | --- | --- | --- | --- |
| `AIHUMMER_EMBEDDER_DIM` | Embedder vector dim | int | `768` | Vector dimension — must match the model (multilingual-e5-base=768, bge-m3=1024). |
| `AIHUMMER_EMBEDDER_KEEPALIVE` | Embedder keep-alive | text | `5m` | keep_alive for the Ollama embedder (only when AIHUMMER_MEMORY_RETRIEVAL=embedding). Default 5m — an idle model is unloaded and a stuck idle ollama runner clears itself. -1 (keep forever) is NOT recommended: due to an ollama bug a stuck runner can peg a CPU core for days. The cold start after idling is offset by a warm-up at gateway startup. Applied at startup/after restart. |
| `AIHUMMER_EMBEDDER_MODEL` | Embedder model | text | `yxchia/multilingual-e5-base` | Ollama embedding model. Default multilingual-e5-base — multilingual (incl. Russian), 768-dim, light + fast on CPU (~1-2s/embed). e5 query/passage prefixes are applied automatically. For max quality on GPU hardware use bge-m3 (set DIM=1024). Must match AIHUMMER_EMBEDDER_DIM. |
| `AIHUMMER_EMBEDDER_PASSAGE_PREFIX` | Embedder passage prefix | text | — | 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 | — | Override the retrieval-query prefix (e5 models auto-use "query: "). Leave blank to auto-detect by model name. |
| `AIHUMMER_MEMORY_CAPTURE` | Memory capture mode | enum: auto \\\| review \\\| off | `auto` | auto = remember + recall automatically; review = remember as candidates needing manual approval; off = no capture. |
| `AIHUMMER_MEMORY_CONTEXT_TIMEOUT` | Memory hydration timeout | text | `3s` | Maximum wait for memory hydration at the start of a reply (query embedding + search). If the embedder is overloaded and misses the deadline, the reply proceeds WITHOUT the memory block instead of hanging. Go duration format (e.g. 2s, 1500ms). 0 = no limit. Applied at startup/after restart. |
| `AIHUMMER_MEMORY_DREAM_INTERVAL` | Dream pass interval | string | `1h` | 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. |
| `AIHUMMER_MEMORY_EXTRACT` | LLM fact extraction | bool | `1` | 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. |
| `AIHUMMER_MEMORY_RETRIEVAL` | Memory retrieval mode | enum: fulltext \\\| embedding | `fulltext` | How memory is searched. fulltext (default) = Postgres full-text search over fact text — NO embedder model, no sidecar, no CPU load (like the old einstein in AiHummer). embedding = semantic vector search via an embedder (AIHUMMER_EMBEDDER_URL/ollama) — more accurate by meaning, but loads the CPU and requires a sidecar. Applied at startup/after restart. |
| `AIHUMMER_MEMORY_TOKEN` | Remote memory service token | text | — | Service token to authorize with the Einstein Retrieval API (sent as Authorization: Bearer …). Needed only when AIHUMMER_MEMORY_URL is set. Blank = no authorization (only for dev installs with retrieval auth disabled). |
| `AIHUMMER_MEMORY_URL` | Remote memory URL (Einstein plugin) | text | — | URL of the standalone Einstein memory plugin (contract aihummer.memory.v1, e.g. http://127.0.0.1:8820). BLANK (default) = the in-process Go memory module. When set, turn-context hydration goes over HTTP to the plugin's /context + /retrieval; on error/unavailability it softly falls back to the built-in module (no crashes). Applied at startup/after restart. |
| `AIHUMMER_QDRANT_API_KEY` | Qdrant API key | text | — | 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 | — | UNSET = in-memory store (vectors LOST on restart). Set for production durability. |
| `AIHUMMER_RERANKER_URL` | RAG reranker sidecar URL | text | — | HTTP URL of the cross-encoder sidecar for reranking hybrid search. Blank = reranking off. Applied at startup/after restart. |
## Moderation
| Key | Name | Type | Default | What it does |
| --- | --- | --- | --- | --- |
| `AIHUMMER_MODERATION` | Input moderation | bool | `1` | "off" disables the built-in guard against jailbreak/prompt-injection. Any other value = enabled. Applied at startup/after restart. |
| `AIHUMMER_MODERATION_REFUSAL` | Moderation refusal message | text | — | Refusal text returned when the moderator blocks a request (blank = built-in). Applied at startup/after restart. |
## Network
| Key | Name | Type | Default | What it does |
| --- | --- | --- | --- | --- |
| `AIHUMMER_OUTBOUND_PROXY_CUSTOM_URL` | Outbound proxy: custom address | text | — | Proxy URL such as https://user:password@host:port; used only in `custom` mode. Plain HTTP is allowed only for loopback because Proxy-Authorization would otherwise send the password in cleartext. Paths, query strings, and fragments are forbidden. The value is stored as a secret and never returned in plaintext. |
| `AIHUMMER_OUTBOUND_PROXY_MODE` | Outbound proxy for foreign model providers | enum: auto \\\| off \\\| custom | `auto` | `auto` (default) uses the provider configuration from installation; `off` never uses a proxy (for installations outside Russia); `custom` uses the address from the field below. OpenAI, Anthropic, Google, DeepSeek, and other foreign providers block Russian IP addresses, so they require a proxy in an allowed region. GigaChat, YandexGPT, and internal addresses always bypass the proxy. Applied immediately when saved. |
| `AIHUMMER_RUSSIAN_TRUSTED_EXTRA_HOSTS` | Hosts beyond .ru for the Russian Trusted roots | text | — | 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). |
## Public access
| Key | Name | Type | Default | What it does |
| --- | --- | --- | --- | --- |
| `AIHUMMER_PUBLIC_URL` | Gateway public URL (Web UI + clients) | text | — | Proxy this host → the gateway port (AIHUMMER_GATEWAY_ADDR, default :8780). Used by the Web UI and the iOS/web clients. |
| `AIHUMMER_WIDGET_ALLOWED_ORIGINS` | Web widget: allowed site origins | text | — | 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 | — | 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 | — | Webhook mode only — proxy → the telegram-connector port (AIHUMMER_TELEGRAM_CONNECTOR_PORT, default 8091). Leave blank to use polling (no public URL needed). |
## SSO (LDAP/AD)
| Key | Name | Type | Default | What it does |
| --- | --- | --- | --- | --- |
| `AIHUMMER_LDAP_BASE_DN` | User search base DN | text | — | Search root, e.g. OU=Users,DC=corp,DC=example. |
| `AIHUMMER_LDAP_BIND_DN` | Service bind DN | text | — | 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 | — | Role granted when no group matches a mapping. Blank = no role. |
| `AIHUMMER_LDAP_ENABLED` | Enable LDAP/AD login | bool | `0` | 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 | — | Attribute on the user entry listing group DNs. Blank disables group→role mapping. |
| `AIHUMMER_LDAP_ROLE_MAPPINGS` | LDAP: Group→role mappings (JSON) | text | — | 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` | Disables directory certificate verification. Never enable in production. |
| `AIHUMMER_LDAP_URL` | Directory URL | text | — | e.g. ldaps://ad.corp.example:636 (TLS) or ldap://dc1.corp.example:389. |
| `AIHUMMER_LDAP_USER_ATTR` | Login attribute (default sAMAccountName) | text | — | 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 | — | Must contain %s for the login. AD: (sAMAccountName=%s); OpenLDAP: (uid=%s). |
## SSO (OIDC)
| Key | Name | Type | Default | What it does |
| --- | --- | --- | --- | --- |
| `AIHUMMER_OIDC_AUDIENCE` | OIDC audience | text | — | 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 | — | The IdP issuer (e.g. https://login.example.com). Enables OIDC JWT auth when set. |
| `AIHUMMER_OIDC_JWKS_URL` | OIDC JWKS URL | text | — | JSON Web Key Set endpoint used to verify token signatures. |
| `AIHUMMER_OIDC_TENANT_CLAIM` | OIDC workspace claim | text | — | JWT claim carrying the workspace id (e.g. tenant_id / org). |
## SSO (SAML)
| Key | Name | Type | Default | What it does |
| --- | --- | --- | --- | --- |
| `AIHUMMER_SAML_DEFAULT_ROLE` | SAML: Default role (no group match) | text | — | Role granted when no asserted value maps. Blank = no role. |
| `AIHUMMER_SAML_ENABLED` | Enable SAML 2.0 SSO | bool | `0` | 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 | — | SP entity ID (defaults to ⟨root⟩/saml/metadata if blank). |
| `AIHUMMER_SAML_IDP_METADATA` | IdP metadata XML | text | — | Paste the IdP's SAML metadata document (Okta/Azure AD/ADFS). |
| `AIHUMMER_SAML_ROLE_ATTRIBUTE` | Role/group attribute (default groups) | text | — | Assertion attribute carrying group/role values. |
| `AIHUMMER_SAML_ROLE_MAPPINGS` | SAML: Group→role mappings (JSON) | text | — | JSON object of asserted value → role, e.g. {"AdminGroup":"admin","Ops":"operator"}. |
| `AIHUMMER_SAML_ROOT_URL` | SP root URL | text | — | 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 | — | Public SP signing certificate (PEM). The matching private key goes in Secrets (scope saml, name sp_key). |
## Security
| Key | Name | Type | Default | What it does |
| --- | --- | --- | --- | --- |
| `AIHUMMER_AIRGAPPED` | Air-gapped mode | bool | `0` | Blocks model-driven egress to the public internet (internal or allowlisted hosts only). Applied at startup/after restart. |
| `AIHUMMER_AUDIT_RETENTION_DAYS` | Audit-log retention (days, 0=forever) | int | `0` | How many days to keep the audit log; older entries are deleted daily. 0/blank = keep forever. Applied at startup/after restart. |
| `AIHUMMER_CODE_EXEC_ALLOW_HOST` | Allow code_exec on the host (NO sandbox) | bool | `0` | ⚠️ Allow code execution directly on the host with no sandbox. For a trusted homelab only. It is safer to set AIHUMMER_CODE_EXEC_SANDBOX_IMAGE. Applied at startup/after restart. |
| `AIHUMMER_CORS_ORIGINS` | Allowed CORS origins (comma) | text | — | 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 | — | Overrides the CSP header. Blank = a safe default. Applied at startup/after restart. |
| `AIHUMMER_INBOUND_SECRET` | Connector→gateway shared secret | text | — | Shared secret authenticating the connector→gateway hop (must match the value on the connector side). Blank = the inbound endpoint is UNAUTHENTICATED. Applied at startup/after restart. |
| `AIHUMMER_OPENAI_COMPAT_KEY` | OpenAI-compatible inbound: static API key | text | — | Static key OpenAI-compatible clients use to authenticate against the gateway's built-in /v1 endpoint (P8 home gateway). Blank = static auth disabled (personal keys remain). Applied at startup/after restart. |
| `AIHUMMER_OPENAI_COMPAT_WORKSPACE` | OpenAI-compatible inbound: workspace id | text | — | 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` | 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` | 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 reverse-proxy CIDRs (comma) | text | — | Comma-separated list of trusted reverse-proxy networks (CIDR, e.g. 10.0.0.0/8,192.168.0.0/16, or single IPs). Only for requests COMING from these addresses is the X-Forwarded-For header used to determine the client IP (audit, IP allowlist, anti-brute-force). Blank = trust ONLY the real peer address (XFF ignored, IP spoofing impossible). Applied on the fly. |
## Tools
| Key | Name | Type | Default | What it does |
| --- | --- | --- | --- | --- |
| `AIHUMMER_CODE_EXEC` | Enable code_exec | bool | `0` | Enables the code execution tool (code_exec); it is off by default. For isolation set a sandbox image, or explicitly allow execution on the host. Applied at startup/after restart. |
| `AIHUMMER_CODE_EXEC_INTERPRETERS` | Code-exec interpreters (JSON) | text | — | JSON object {language: path_to_binary}, e.g. {"python":"/usr/bin/python3"}. Blank = auto-detect. Applied at startup/after restart. |
| `AIHUMMER_CODE_EXEC_SANDBOX_IMAGE` | Code-exec sandbox image | text | — | Container image for isolating code_exec (no network, read-only rootfs, limits). Blank = host-exec (trusted environment). Applied at startup/after restart. |
| `AIHUMMER_DB_QUERY_DSN` | db_query DSN (use a least-privilege, non-owner role — queries run RLS-scoped to the acting workspace) | text | — | Database DSN for the read-only db_query tool; use a least-privilege role, not owner or superuser, since queries run RLS-scoped to the workspace. Blank = the tool is off. Applied at startup/after restart. |
| `AIHUMMER_FS_ROOT` | Filesystem tool root | text | — | Root directory the file read/write tools are confined to (sandbox). Blank = file tools are off. Applied at startup/after restart. |
| `AIHUMMER_HTTP_ALLOWLIST` | http_request allowlist | text | — | Comma-separated list of hosts the http_request tool may reach. Blank = all are allowed, except internal and private addresses. Applied at startup/after restart. |
| `AIHUMMER_HTTP_AUTH_JSON` | http_request auth (JSON) | text | — | JSON map of host to authorization headers for the http_request tool, so tokens are not kept in the prompt. Blank = no authorization. Applied at startup/after restart. |
| `AIHUMMER_MCP_SERVERS` | MCP servers (JSON) | text | — | JSON description of the external MCP servers whose tools are attached to the agent. Blank = no external MCP. Applied at startup/after restart. |
| `AIHUMMER_SIDECAR_CLOAKBROWSER` | Browser sidecar (CloakBrowser) installed | bool | `0` | 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 sidecar (SearXNG) installed | bool | `0` | 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` | web_fetch allowlist | text | — | Comma-separated list of domains the web_fetch tool may reach. Blank = all are allowed, except internal and private addresses. Applied at startup/after restart. |
## Web UI (separate port)
| Key | Name | Type | Default | What it does |
| --- | --- | --- | --- | --- |
| `AIHUMMER_WEBUI_API_BASE` | API base URL the Web UI calls | text | — | Absolute origin (e.g. https://api.example.com) the separately-hosted SPA targets for /v1/admin/* calls. Blank = fall back to the gateway public URL, then to the local gateway address. Must be reachable from the admin's browser; the API must allow this Web UI's origin via CORS (auto-added below). |
| `AIHUMMER_WEBUI_ENABLED` | Serve admin Web UI on its own port | bool | `1` | Enabled by default: the admin SPA is served at the ROOT of a separate listener (AIHUMMER_WEBUI_ADDR) that can be bound to an internal-only interface. The main gateway port keeps API + pairing + WS + SSE and does NOT serve /admin/. Set to 0 to disable the Web UI listener entirely. |
| `AIHUMMER_WEBUI_ORIGIN` | Web UI browser origin (CORS) | text | — | Browser Origin of the Web UI (e.g. https://admin.example.com), auto-added to the API CORS allowlist with credentials. Blank = derived from AIHUMMER_WEBUI_ADDR (http://host:port). Set this when the browser reaches the Web UI via a proxy/hostname different from the bind address. |
Settings available to the operator: 146.
