AiHummer
English▾
Log in
v1.0.x▾
v1.0.xstable
{ }Swagger
Getting started/Configuration

Configuration

v1.0.x · updated 2026-07-07

AiHummer is configured through a settings catalog, not a pile of environment variables. gateway.env is bootstrap-only: the database DSN, listen addresses/ports, the master key and the like. Every other key lives in the database and is changed from the web admin UI at runtime or with the aihummer settings CLI. The guiding rule is simple: everything tunable is configurable in the Web UI — not env-only, and not hardcoded.

The resolution order

Every catalog setting is resolved the same way, first match wins:

  1. Database — a value set through the admin UI or aihummer settings set.
  2. Default — the built-in default shipped with the release.

The environment is deliberately not part of this chain: for catalog keys an AIHUMMER_* variable in gateway.env is ignored, even if set. That gives every setting exactly one source of truth — the database — so a UI value can never be silently shadowed by a forgotten line in an env file.

[!NOTE] To change behaviour in production you do not edit config files — you change the setting in the admin UI (Management → Settings, a searchable page) or run aihummer settings set <KEY> <VALUE> (get / list to read), and it takes effect for that workspace. The installer itself seeds initial catalog values into the database via aihummer settings set.

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 Public listen address (default :8780) — API, pairing, WS/SSE, inbound and the app/pocket proxy.
AIHUMMER_WEBUI_ADDR Private admin Web UI listen address (default :8781), served at root /; set to 0 to disable.
AIHUMMER_BLOB_DIR Filesystem path of the blob/media directory — needed at boot.
AIHUMMER_OIDC_ISSUER Protects /v1/admin/* before the UI is trusted.

Ops wiring such as the telemetry OTLP endpoint falls into the same bootstrap category. Anything not on this short list is a catalog key: it lives in the database, and env is ignored for it.

[!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:

~/.aihummer/etc/gateway.env

Edit this file for bootstrap values only, then restart the gateway service to apply changes:

# ~/.aihummer/etc/gateway.env (excerpt)
AIHUMMER_DATABASE_URL=postgres://user:pass@localhost:5432/aihummer
AIHUMMER_MASTER_KEY=base64-32-bytes...
AIHUMMER_GATEWAY_ADDR=:8780
AIHUMMER_WEBUI_ADDR=:8781
AIHUMMER_OIDC_ISSUER=https://idp.example/realms/main
systemctl restart aihummer-gateway

Everything beyond these bootstrap keys — agents, tools, memory mode, reasoning strategies, budgets, guardrails and the rest — is managed from the admin UI’s settings (or via aihummer settings), not from this file: env is ignored for those keys.

Wiring optional capabilities

Many features are off until you point them at a backing service. All of these keys are catalog settings (they live in the DB): set them in the admin UI (Management → Settings) or with the CLI; putting them in gateway.env does nothing — env is ignored for them. For sidecars installed from the bundle (STT/TTS etc.) the installer seeds the values into the database itself.

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

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

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

# Real vector store + embedder (example URLs; the embedder is installed with
# --with-embedder, otherwise memory uses the lexical fallback)
aihummer settings set AIHUMMER_QDRANT_URL http://localhost:6333
aihummer settings set 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.

Notifications

The admin UI’s “Notifications” page (under “Control”) is the instance’s inbox of events (admin sign-in, update available/applied, sidecar going down or recovering, and so on) with filters by category, severity and unread. Next to it sits a category × delivery-channel matrix: for each event category you enable the webui, email, telegram and push channels. Web UI notices are delivered locally; Telegram is linked with the “Link Telegram” button (deep link), email activates once the support address is verified, and push arrives in the mobile app. Critical events cannot be muted on the webui channel.

Where to next