Environment Variables — AiHummer Docs

AiHummer is configured through AIHUMMER_* environment variables (plus a few tool-specific ones such as SEARXNG_URL). This page is the catalog, grouped by area. Most variables are also editable from the web admin UI.

Configuration model

Every setting is resolved in a fixed order:

database value  →  environment variable  →  built-in default

That means a value saved in the admin UI (stored in the database) overrides the environment, which overrides the built-in default. Bootstrap variables — the ones the gateway needs before it can read the database, such as AIHUMMER_DATABASE_URL and AIHUMMER_MASTER_KEY — stay environment-only.

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] Tunable, non-bootstrap knobs are best changed in the web admin UI so they take effect without editing files. Some changes (such as tool toggles and sub-agent depth) apply hot; others require a service restart.

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`	Listen address (default `:8765`; the installer picks a free port).
`AIHUMMER_DEFAULT_WORKSPACE_ID`	Enables the inbound dispatcher and the widget’s default workspace.
`AIHUMMER_BLOB_DIR`	Enables the media/file service (blob storage directory).
`AIHUMMER_ADMIN_UI_DIR`	Serves the admin SPA at `/admin/`.
`AIHUMMER_WIDGET_DIR`	Serves the web widget at `/widget/`.

Security & vault

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_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.

Authentication & SSO

Variable	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.

Channels & inbound

Variable	Purpose
`AIHUMMER_INBOUND_SECRET`	HMAC shared secret for connector → gateway `/v1/inbound/*` calls.
`AIHUMMER_INBOUND_URL`	Connector-side: the gateway inbound URL a connector posts to.

LLM & models

Variable	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

Variable	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

Variable	Purpose
`AIHUMMER_STT_URL`	Speech-to-text sidecar URL (auto-set by the installer).
`AIHUMMER_TTS_URL`	Text-to-speech sidecar URL (auto-set by the installer).
`AIHUMMER_DIARIZE_URL`	Speaker-diarization sidecar URL.
`AIHUMMER_VOICECLONE_URL`	Voice-cloning sidecar URL.
`AIHUMMER_VIDEO_URL`	Video-understanding sidecar URL.

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

Vectors & embeddings

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

Bus & observability

Variable	Purpose
`AIHUMMER_NATS_URL`	Optional NATS bus for delivery.
`AIHUMMER_OTEL_ENDPOINT`	OTLP endpoint for traces/metrics push.

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

Updates

Variable	Purpose
`AIHUMMER_DOWNLOAD_BASE_URL`	Base URL for release artifacts (self-update source).
`AIHUMMER_UPDATE_CHANNEL`	Release channel to track.
`AIHUMMER_AUTO_UPDATE`	Update mode: `off`, `check` or `apply`.

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

Marketplace & plugins

Variable	Purpose
`AIHUMMER_BLOB_DIR`	Blob-store directory. Besides media/files, it stores private (side-loaded) plugin artifacts under `blob:` refs that the deployer resolves.
`AIHUMMER_PLUGIN_PUBKEY`	An extra trusted public key (base64 ed25519) for verifying plugin signatures — in addition to the registry key pinned in core.
`AIHUMMER_PLUGIN_DEV_UNSIGNED`	`1` allows installing unsigned plugins. Local development only — never on an externally reachable instance.

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

Protocol surfaces (opt-in)

Variable	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`).

Where to next

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