Environment Variables

AiHummer configuration splits into two strictly different groups:

Bootstrap (gateway.env) — what the gateway must know before it can read the database: the database DSN, listen addresses, static directories, the master key. Only these keys are read from the environment.
Settings catalog (database) — every other knob. These are stored in the database and set in the web admin UI (Management → Settings) or with aihummer settings set <KEY> <VALUE>. For these keys a gateway.env value is deliberately ignored — even if set, it has no effect.

Configuration model

gateway.env is bootstrap-only. Resolution order:

Settings-catalog key: database value → built-in default (the environment is ignored);
bootstrap key: environment variable only.

So the single source of truth for tunable knobs is the database (web admin UI / aihummer settings); the environment carries only what the process needs to start.

The config file for a host-native install lives at:

# /home/.aihummer/etc/gateway.env
AIHUMMER_DATABASE_URL=postgres://...
AIHUMMER_MASTER_KEY=base64-32-bytes

[!TIP] Do not put Settings-catalog knobs in gateway.env — it has no effect. Change them in the web admin UI (Management → Settings, it has search) or via aihummer settings set. Some changes (such as tool toggles and sub-agent depth) apply hot; others require a service restart.

Bootstrap (gateway.env)

The only keys the gateway actually reads from the environment.

Core & database

Variable	Purpose
`AIHUMMER_DATABASE_URL`	Required. Postgres DSN. Without it the gateway runs in health-only mode.
`AIHUMMER_DB_APP_URL`	Restricted-role DSN that activates Row-Level Security (set automatically for local installs).
`AIHUMMER_GATEWAY_ADDR`	Public listen address (default `:8780`) — all external traffic: API (`/v1/*`), pairing, WS/SSE, inbound webhooks, the app/pocket proxy and health probes.
`AIHUMMER_WEBUI_ADDR`	Private admin Web UI listen address (default `:8781`), served at the root path `/`; ideally bound to an internal-only interface. Set to `0` to disable.
`AIHUMMER_DEFAULT_WORKSPACE_ID`	Enables the inbound dispatcher and the widget’s default workspace.
`AIHUMMER_HOME_ROOT`	Install root (normally derived from the binary path); anchors the admin-ui/blob/installer directories and the key files.
`AIHUMMER_BLOB_DIR`	Enables the media/file service (blob storage directory). It also stores private (side-loaded) plugin artifacts under `blob:` refs that the deployer resolves.
`AIHUMMER_ADMIN_UI_DIR`	Serves the admin SPA at `/admin/`.
`AIHUMMER_WIDGET_DIR`	Serves the web widget at `/widget/`.

Secrets & infrastructure

Variable	Purpose
`AIHUMMER_MASTER_KEY`	base64-encoded 32 bytes; enables secrets-at-rest, the vault and BYOK.
`AIHUMMER_MEDIA_TOKEN_SECRET`	Keeps signed download URLs valid across restarts.
`AIHUMMER_NATS_URL`	Optional NATS bus for delivery.
`AIHUMMER_OTEL_ENDPOINT`	OTLP endpoint for traces/metrics push.
`AIHUMMER_DOWNLOAD_BASE_URL`	Base URL for release artifacts (self-update source).

[!WARNING] Observability is OTLP push only. AiHummer does not expose a Prometheus /metrics endpoint or /debug/pprof. Point AIHUMMER_OTEL_ENDPOINT at your collector instead.

Key-gated install channels (alfa/beta/dev) additionally read AIHUMMER_CHANNEL_KEY / AIHUMMER_RELEASE_TOKEN at install time.

Settings catalog (database — web admin UI or `aihummer settings`)

Every key below lives in the database. Set it in the web admin UI (Management → Settings) or like this:

aihummer settings set AIHUMMER_LLM_PROVIDER openai

A gateway.env value for such a key is ignored.

Security

Key	Purpose
`AIHUMMER_APPROVAL_TOOLS`	Tools that require human-in-the-loop approval before they run.
`AIHUMMER_AIRGAPPED`	`1` blocks model-controlled public egress (air-gapped mode).
`AIHUMMER_AUDIT_RETENTION_DAYS`	Retention window for the admin audit log.
`AIHUMMER_INBOUND_SECRET`	HMAC shared secret for connector → gateway `/v1/inbound/*` calls.

Authentication & SSO

Key	Purpose
`AIHUMMER_OIDC_ISSUER`	Protects `/v1/admin/*`. Without it (and without LDAP/SAML) admin trusts dev headers — never expose such an instance.

LDAP/AD and SAML are configured alongside OIDC for enterprise sign-in; SCIM provides automatic user provisioning. See Webhooks, SCIM & pairing.

LLM & models

Key	Purpose
`AIHUMMER_LLM_PROVIDER`	Model provider to use.
`AIHUMMER_LLM_MODEL`	Model name.
`AIHUMMER_LLM_GATEWAY_URL`	Endpoint for an OpenAI-compatible LLM gateway.
`AIHUMMER_OPENAI_API_KEY`	API key for an OpenAI-compatible provider.
`AIHUMMER_SUBAGENT_MAX_DEPTH`	Maximum depth of spawned sub-agents.

[!NOTE] If no model is wired, the gateway falls back to a deterministic mock so the system still runs. No paid model API is ever required — free/local models and a Codex/ChatGPT-subscription transport are first-class.

Tools

Key	Purpose
`SEARXNG_URL`	Enables the `web_search` tool (SearXNG instance URL).
`CLOAKBROWSER_CDP_URL`	Enables the `browser`/`computer` tools (Chrome DevTools Protocol URL).
`AIHUMMER_FS_ROOT`	Enables `filesystem_read`, sandboxed under this root.
`AIHUMMER_DB_QUERY_DSN`	Enables `db_query` (read-only) against this DSN.
`AIHUMMER_CODE_EXEC`	Toggles the `code_exec` tool (off by default on shared hosts).

See the full Tools catalog for what each tool does.

Voice & sidecars

Key	Purpose
`AIHUMMER_STT_URL`	Speech-to-text sidecar URL (seeded by the installer).
`AIHUMMER_TTS_URL`	Text-to-speech sidecar URL (seeded by the installer).
`AIHUMMER_VIDEO_URL`	Video-understanding sidecar URL.

Sidecars are separate HTTP services; the gateway reaches them by URL.

Vectors & embeddings

Key	Purpose
`AIHUMMER_QDRANT_URL`	Real vector store (Qdrant). Absent → in-memory store.
`AIHUMMER_EMBEDDER_URL`	Real embedder service. Absent → hash embedder.

Updates

Key	Purpose
`AIHUMMER_UPDATE_CHANNEL`	Release channel to track.
`AIHUMMER_AUTO_UPDATE`	Update mode: `off`, `check` or `apply`.

Protocol surfaces (opt-in)

Key	Purpose
`AIHUMMER_MCP_PUBLISH`	`1` enables the outward MCP server at `POST /v1/mcp`.
`AIHUMMER_A2A_PUBLISH`	`1` enables the A2A surface (`/.well-known/agent.json`, `/a2a/message`).

Dev builds only

Variable	Purpose
`AIHUMMER_PLUGIN_PUBKEY`	An extra trusted public key (base64 ed25519) for verifying plugin signatures. Dev builds only — ignored in release builds (the registry key is pinned into the binary).
`AIHUMMER_PLUGIN_DEV_UNSIGNED`	`1` allows installing unsigned plugins. Dev builds only — ignored in release builds. Never on an externally reachable instance.

[!WARNING] In release builds the plugin trust root is baked into the binary and cannot be overridden by the environment or settings — this is an anti-tamper guarantee.

The trust model (official → pinned key, private → trust store, unsigned → blocked) is described in Install & updates.

Where to next

See which tools each key unlocks: Tools catalog.
Operate the instance day to day: CLI reference.