Configuration

/home/.aihummer/etc/gateway.env

# /home/.aihummer/etc/gateway.env (excerpt)
AIHUMMER_DATABASE_URL=postgres://user:pass@localhost:5432/aihummer
AIHUMMER_MASTER_KEY=base64-32-bytes...
AIHUMMER_GATEWAY_ADDR=:8765
AIHUMMER_OIDC_ISSUER=https://idp.example/realms/main

systemctl restart aihummer-gateway

# Wire a real model (absent → deterministic mock)
AIHUMMER_LLM_PROVIDER=openai
AIHUMMER_LLM_MODEL=gpt-4o-mini
AIHUMMER_LLM_GATEWAY_URL=https://api.openai.com/v1

# Enable tools by pointing at their backends
SEARXNG_URL=http://localhost:8888
CLOAKBROWSER_CDP_URL=http://localhost:9222

# Voice sidecars (STT/TTS auto-set by the installer)
AIHUMMER_STT_URL=http://localhost:8001
AIHUMMER_TTS_URL=http://localhost:8002

# Real vector store + embedder (else in-memory + hash embedder)
AIHUMMER_QDRANT_URL=http://localhost:6333
AIHUMMER_EMBEDDER_URL=http://localhost:8080

AiHummer is configured through a **settings catalog**, not a pile of environment variables. Each setting has a defined resolution order, most keys can be changed from the web admin UI at runtime, and only a small set of bootstrap variables must stay in the environment. The guiding rule is simple: **everything tunable is configurable in the Web UI** — not env-only, and not hardcoded. ## The resolution order Every setting in the catalog is resolved in the same order, first match wins: 1. **Database** — a value set through the admin UI (stored per workspace). 2. **Environment** — the corresponding `AIHUMMER_*` variable. 3. **Default** — the built-in default shipped with the release. This means an admin-UI value **overrides** the environment at runtime, and the environment overrides the built-in default. You can ship a sane baseline in the environment and then tune behaviour live from the UI without redeploying. > [!NOTE] > Because the database layer sits above the environment, you do not edit config > files to change most behaviour in production — you change it in the admin UI and > it takes effect for that workspace. ## Hot vs restart-required How a changed setting takes effect depends on the key: | Behaviour | Examples | When it applies | |---|---|---| | **Hot** | tool enablement, sub-agent max depth | Re-read at runtime, no restart | | **Restart-required** | listen address, wiring of certain services | Applied on the next gateway restart | Hot keys are re-read live, so toggling a tool or adjusting `subagent-depth` takes effect on the next turn. Some structural keys only take effect after a restart; the admin UI flags which is which. ## Bootstrap variables stay env-only A few variables must be present in the environment because they are needed before the settings catalog (and the database it reads from) exists. These **bootstrap** variables are env-only and are not surfaced in the admin UI: | Variable | Why it is bootstrap | |---|---| | `AIHUMMER_DATABASE_URL` | The DB must exist before any DB-backed setting can be read. | | `AIHUMMER_DB_APP_URL` | Restricted role DSN that activates RLS. | | `AIHUMMER_MASTER_KEY` | base64-32 bytes; unlocks secrets-at-rest / vault / BYOK. | | `AIHUMMER_GATEWAY_ADDR` | Listen address (default `:8765`). | | `AIHUMMER_OIDC_ISSUER` | Protects `/v1/admin/*` before the UI is trusted. | > [!WARNING] > Keep `AIHUMMER_MASTER_KEY` safe and backed up **separately** from your database > backup. It decrypts the credential vault; lose it and the encrypted secrets > cannot be recovered. ## The config file For host-native installs, the bootstrap environment lives in a single file that the systemd unit loads: ```text /home/.aihummer/etc/gateway.env ``` Edit this file for bootstrap and baseline values, then restart the gateway service to apply changes: ```ini # /home/.aihummer/etc/gateway.env (excerpt) AIHUMMER_DATABASE_URL=postgres://user:pass@localhost:5432/aihummer AIHUMMER_MASTER_KEY=base64-32-bytes... AIHUMMER_GATEWAY_ADDR=:8765 AIHUMMER_OIDC_ISSUER=https://idp.example/realms/main ``` ```bash systemctl restart aihummer-gateway ``` Everything beyond these bootstrap/baseline keys — agents, tools, memory mode, reasoning strategies, budgets, guardrails and the rest — is meant to be managed from the admin UI's settings rather than this file. ## Wiring optional capabilities Many features are off until you point them at a backing service. These are typically set once in `gateway.env` (or overridden in the UI where applicable): ```ini # Wire a real model (absent → deterministic mock) AIHUMMER_LLM_PROVIDER=openai AIHUMMER_LLM_MODEL=gpt-4o-mini AIHUMMER_LLM_GATEWAY_URL=https://api.openai.com/v1 # Enable tools by pointing at their backends SEARXNG_URL=http://localhost:8888 CLOAKBROWSER_CDP_URL=http://localhost:9222 # Voice sidecars (STT/TTS auto-set by the installer) AIHUMMER_STT_URL=http://localhost:8001 AIHUMMER_TTS_URL=http://localhost:8002 # Real vector store + embedder (else in-memory + hash embedder) AIHUMMER_QDRANT_URL=http://localhost:6333 AIHUMMER_EMBEDDER_URL=http://localhost:8080 ``` > [!TIP] > A real model is never required. Without `AIHUMMER_LLM_*` wired, replies come > from a deterministic mock; AiHummer also runs on free/local OpenAI-compatible > endpoints and a Codex/ChatGPT-subscription transport, with optional BYOK. ## Where to next - Lock down the admin login: [First login](/en/v1.0/getting-started/first-login). - See where files live: [Installation](/en/v1.0/getting-started/installation). - Check the prerequisites: [Requirements](/en/v1.0/getting-started/requirements).