Settings reference

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.0/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 | text | — | Список инструментов (через запятую), вызов которых требует ручного подтверждения оператором перед выполнением. Пусто = подтверждение не требуется. Применяется при старте/после рестарта. | | `AIHUMMER_SUBAGENT_MAX_DEPTH` | Subagent max depth | int | `2` | Максимальная глубина вложенности суб-агентов (агент, запускающий агента). По умолчанию 2 — защита от бесконечной рекурсии. Применяется при старте/после рестарта. | | `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 | text | — | 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 | text | `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 | text | `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) | text | — | Явный список имён инструментов, разрешённых внешним MCP-клиентам, через запятую. Пусто = не публиковать ни одного инструмента. Опасные host-level классы дополнительно запрещены встроенной политикой, даже если перечислены. Применяется при старте/после рестарта. | | `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_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_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_CODEX_URL` | STT codex-engine URL | text | — | Base of the OpenAI-compatible /v1/audio/transcriptions for the codex engine (transcription via the ChatGPT subscription). Blank = the Codex base. The bearer is taken from AIHUMMER_STT_API_KEY or AIHUMMER_CODEX_ACCESS_TOKEN. Applied at startup/after restart. | | `AIHUMMER_STT_ENGINE` | STT engine | enum: faster-whisper \\\| deepgram \\\| off | `faster-whisper` | Speech-recognition engine. faster-whisper = free local sidecar (default, ships out of the box, URL = AIHUMMER_STT_URL, no load on third-party APIs). deepgram = cloud Deepgram (fast, key AIHUMMER_DEEPGRAM_API_KEY, paid with a free tier). off = recognition disabled. (The Codex/ChatGPT subscription does NOT support audio transcription.) 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_STT_URL` | Speech-to-text (faster-whisper) URL | text | — | URL of the local faster-whisper sidecar (OpenAI-compatible /v1/audio/transcriptions). Blank = auto-default http://127.0.0.1:8001, which install.sh sets itself. 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 ships out of the box. 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_URL` | Text-to-speech (edge-tts) URL | text | — | URL of the local edge-tts sidecar (OpenAI-compatible /v1/audio/speech). Blank = auto-default http://127.0.0.1:8002, which install.sh sets itself. Applied at startup/after restart. | | `AIHUMMER_TTS_VOICE` | TTS voice (default de-DE-FlorianMultilingualNeural) | text | `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. | | `AIHUMMER_VIDEO_URL` | Video analysis (ffmpeg) URL | text | — | URL of the video-analysis sidecar. Blank = off. 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` | Требовать автоматическую регулировку усиления микрофона (WebRTC autoGainControl) в голосовом режиме. | | `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` | Требовать подавление шума на захвате микрофона (WebRTC noiseSuppression) в голосовом режиме. | | `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_EMBEDDER_URL` | Embedder URL (Ollama-compatible) | text | — | Real semantic embeddings. The installer provisions an Ollama sidecar and sets this automatically; UNSET = hash embedder (lexical only, weak recall). | | `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 | — | API-ключ Qdrant (если векторное хранилище требует авторизации). Нужен только при заданном Qdrant URL. Применяется при старте/после рестарта. | | `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. | ## 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. | | `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` | Включает инструмент выполнения кода (code_exec). По умолчанию выключен. Для изоляции задайте образ песочницы (Code-exec sandbox image) или явно разрешите выполнение на хосте. Применяется при старте/после рестарта. | | `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 | — | DSN базы данных для инструмента db_query (только чтение). Указывайте роль с минимальными правами (не owner/superuser) — запросы выполняются в RLS-скоупе арендатора. Пусто = инструмент выключен. Применяется при старте/после рестарта. | | `AIHUMMER_FS_ROOT` | Filesystem tool root | text | — | Корневой каталог, к которому ограничены инструменты чтения/записи файлов (песочница). Пусто = файловые инструменты выключены. Применяется при старте/после рестарта. | | `AIHUMMER_HTTP_ALLOWLIST` | http_request allowlist | text | — | Список хостов (через запятую), к которым инструмент http_request может обращаться. Пусто = разрешены все (кроме внутренних/приватных). Применяется при старте/после рестарта. | | `AIHUMMER_HTTP_AUTH_JSON` | http_request auth (JSON) | text | — | JSON-карта {хост: заголовки авторизации} для инструмента http_request, чтобы не хранить токены в промпте. Пусто = без авторизации. Применяется при старте/после рестарта. | | `AIHUMMER_MCP_SERVERS` | MCP servers (JSON) | text | — | JSON-описание внешних MCP-серверов, чьи инструменты подключаются к агенту. Пусто = нет внешних MCP. Применяется при старте/после рестарта. | | `AIHUMMER_WEBFETCH_ALLOWLIST` | web_fetch allowlist | text | — | Список доменов (через запятую), к которым инструмент web_fetch может обращаться. Пусто = разрешены все (кроме внутренних/приватных адресов). Применяется при старте/после рестарта. | ## 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: 138.