La configuration AiHummer se divise en deux groupes strictement différents:
Bootstrap (gateway.env) — ce que la passerelle doit savoir avant il peut
lire la base de données : le DSN de la base de données, les adresses d’écoute, les répertoires statiques,
la clé principale. Seules ces clés sont lues depuis l’environnement.
Catalogue des paramètres (base de données) — tous les autres boutons. Ceux-ci sont rangés dans le
base de données et définie dans l’interface d’administration web (Gestion → Paramètres) ou avec
aihummer settings set <KEY> <VALUE>. Pour ces
clés a gateway.env valeur est délibérément ignoré — même si défini, il a
aucun effet.
Modèle de configuration
gateway.env est bootstrap seulement. Ordre de résolution :
Clé du catalogue des paramètres: database value → built-in default
(l’environnement est ignoré);
clé de démarrage: environment variable only.
Ainsi, la source unique de vérité pour les réglages réglables est la base de données (interface d’administration Web / aihummer settings); l’environnement ne contient que ce dont le processus a besoin pour démarrer.
Le fichier de configuration pour une installation native sur l’hôte se trouve à :
[!TIP]
Ne mettez pas les boutons du catalogue des paramètres gateway.env — cela n’a aucun effet. Changer
eux dans l’interface d’administration web (Gestion → Paramètres, elle a une recherche) ou via
aihummer settings set. Certains changements (comme les basculements d’outils et les sous-agents
profondeur) appliquer chaud ; d’autres nécessitent un redémarrage du service.
Bootstrap (gateway.env)
Les seules clés que la passerelle lit réellement à partir de l’environnement.
Noyau et base de données
Variable
But
AIHUMMER_DATABASE_URL
Requis. DSN Postgres. Sans lui, la passerelle fonctionne en mode santé seulement.
AIHUMMER_DB_APP_URL
DSN à rôle restreint qui active la sécurité au niveau des lignes (défini automatiquement pour les installations locales).
AIHUMMER_GATEWAY_ADDR
Adresse d’écoute publique (par défaut :8780) — tout le trafic externe : API (/v1/*), appariement, WS/SSE, webhooks entrants, le proxy app/pocket et les sondes de santé.
AIHUMMER_WEBUI_ADDR
Adresse d’écoute de l’interface Web d’administration privée (par défaut :8781), servi à la racine du chemin /; idéalement lié à une interface interne uniquement. Définir sur 0 désactiver.
AIHUMMER_DEFAULT_WORKSPACE_ID
Sélectionne l’espace de travail par défaut pour les intégrations entrantes configurées.
AIHUMMER_HOME_ROOT
Installe la racine (normalement dérivée du chemin binaire) ; ancre les répertoires admin-ui/blob/installer et les fichiers clés.
AIHUMMER_BLOB_DIR
Active le service média/fichier (répertoire de stockage de blobs). Il stocke également artefacts de plugin privés (chargés latéralement) sous blob: références que le déployeur résout.
AIHUMMER_ADMIN_UI_DIR
Desservir le SPA admin à /admin/.
Secrets et infrastructure
Variable
But
AIHUMMER_MASTER_KEY
32 octets encodés en base64 ; active les secrets au repos, le coffre-fort et BYOK.
AIHUMMER_MEDIA_TOKEN_SECRET
Maintient les URL de téléchargement signées valides après les redémarrages.
AIHUMMER_OTEL_ENDPOINT
Point de terminaison OTLP pour la transmission de traces/métriques.
AIHUMMER_DOWNLOAD_BASE_URL
URL de base pour les artefacts de version (source de mise à jour automatique).
[!WARNING]
L’observabilité est OTLP push uniquement. AiHummer fait pas exposer un Prométhée
/metrics point de terminaison ou /debug/pprof. Point AIHUMMER_OTEL_ENDPOINT à votre
collectionneur à la place.
Catalogue des paramètres (base de données — interface web d’administration ou aihummer settings)
Chaque clé ci-dessous se trouve dans la base de données. Configurez-la dans l’interface d’administration Web (Gestion → Paramètres) ou comme ceci :
aihummer settings set AIHUMMER_LLM_PROVIDER openai
A gateway.env la valeur pour une telle clé est ignoré.
Sécurité
Clé
But
AIHUMMER_APPROVAL_TOOLS
Outils qui nécessitent l’approbation humaine avant de s’exécuter.
AIHUMMER_AIRGAPPED
1 bloque la sortie publique contrôlée par le modèle (mode isolé).
AIHUMMER_AUDIT_RETENTION_DAYS
Fenêtre de rétention pour le journal d’audit administrateur.
AIHUMMER_INBOUND_SECRET
Secret partagé HMAC pour connecteur → passerelle /v1/inbound/* appels.
Authentification et SSO
Clé
But
AIHUMMER_OIDC_ISSUER
Protège /v1/admin/*. Sans cela (et sans LDAP/SAML), l’administrateur fait confiance aux en-têtes de développement — ne jamais exposer une telle instance.
LDAP/AD et SAML sont configurés aux côtés de OIDC pour la connexion d’entreprise ; SCIM fournit l’approvisionnement automatique des utilisateurs. Voir Webhooks, SCIM et jumelage.
LLM et modèles
Clé
But
AIHUMMER_LLM_PROVIDER
Fournisseur de modèle à utiliser.
AIHUMMER_LLM_MODEL
Nom du modèle.
AIHUMMER_LLM_GATEWAY_URL
URL de base d’une passerelle/point de terminaison LLM compatible OpenAI (le AIHUMMER_LLM_* chemin ; distinct de l’origine AIHUMMER_OPENAI_BASE_URL). Voir BYOK et fournisseurs.
AIHUMMER_OPENAI_API_KEY
Clé API pour un fournisseur compatible OpenAI.
AIHUMMER_SUBAGENT_MAX_DEPTH
Profondeur maximale des sous-agents générés.
[!NOTE]
Si aucun modèle n’est câblé, la passerelle revient à un simulation déterministe alors le
le système fonctionne toujours. Aucun API de modèle payant n’est jamais requis — des modèles gratuits/locaux et un
Le transport de l’abonnement Codex/ChatGPT est de première classe.
Outils
Clé
But
AIHUMMER_FS_ROOT
Permet filesystem_read, isolé sous cette racine.
AIHUMMER_DB_QUERY_DSN
Permet db_query (lecture seule) contre ce DSN.
AIHUMMER_CODE_EXEC
Bascule le code_exec outil (désactivé par défaut sur les hébergements partagés).
AIHUMMER_BROWSER_PROFILE_SOCKET
Chemin vers le socket privé managed-profiles.sock du service de navigateur ; vide — les profils persistants de computer sont désactivés.
AIHUMMER_BROWSER_PROFILE_BINDINGS
Tableau JSON de liaisons explicites de profils de navigateur persistants (profile_id, tenant_id, user_id, agent_ids, conversation_ids).
La recherche web et le navigateur sont gérés par l’installateur : ils sont
installés d’origine, se désactivent avec --no-search / --no-browser et se
pointent vers une instance existante avec --external-search=URL /
--external-browser=URL — il n’existe aucun réglage opérateur pour eux.
URL de l’interface audio-texte (initialisée par l’installateur).
AIHUMMER_TTS_URL
URL du module complémentaire de synthèse vocale (alimenté par l’installateur).
AIHUMMER_VIDEO_URL
URL secondaire pour la compréhension vidéo.
AIHUMMER_TTS_AUTO_REPLY
Quand une réponse terminée est lue : off, always, inbound (par défaut), tagged.
AIHUMMER_TTS_MAX_CHARS
Limite du texte lu : 0 — la réponse entière, sinon 100–10000 caractères.
AIHUMMER_TTS_SUMMARIZE
Raccourcir une réponse longue pour la lecture (activé par défaut).
Les sidecars sont des services HTTP séparés ; la passerelle y accède par URL.
Vecteurs et embeddings
Clé
But
AIHUMMER_QDRANT_URL
Véritable magasin de vecteurs (Qdrant). Absent → magasin en mémoire.
AIHUMMER_EMBEDDER_URL
Service d’intégration réel. Absent → intégrateur de hachage.
Surfaces de protocole (optionnelles)
Clé
But
AIHUMMER_MCP_PUBLISH
Exactement 1 ouvre le serveur MCP externe sur POST /v1/mcp. À lui seul, il n’exporte aucun outil.
AIHUMMER_MCP_EXPORT_TOOLS
Noms exacts des outils, séparés par des virgules, que verra le client MCP. Vide (valeur par défaut) = ZÉRO outil exporté.
AIHUMMER_A2A_PUBLISH
1 active la surface A2A (/.well-known/agent.json, /a2a/message).
Construction développeur uniquement
Variable
But
AIHUMMER_PLUGIN_PUBKEY
Une clé publique fiable supplémentaire (ed25519 en base64) pour vérifier les signatures des plugins. Uniquement pour les builds de développement — ignoré dans les builds de production (la clé de registre est épinglée dans le binaire).
AIHUMMER_PLUGIN_DEV_UNSIGNED
1 permet d’installer non signé extensions. Uniquement pour les versions de développement — ignoré dans les versions finales. Jamais sur une instance accessible de l’extérieur.
[!WARNING]
Dans les versions de production, la racine de confiance du plugin est intégré dans le binaire et
ne peut pas être modifié par l’environnement ou les paramètres — il s’agit d’une protection contre la falsification
garantie.
Le modèle de confiance (officiel → clé épinglée, privé → magasin de confiance, non signé → bloqué) est décrit dans Installation et mises à jour.
La configuration AiHummer se divise en **deux groupes strictement différents**:
1. **Bootstrap (`gateway.env`)** — ce que la passerelle doit savoir **avant** il peut
lire la base de données : le DSN de la base de données, les adresses d'écoute, les répertoires statiques,
la clé principale. Seules ces clés sont lues depuis l'environnement.
2. **Catalogue des paramètres (base de données)** — tous les autres boutons. Ceux-ci sont rangés dans le
base de données et définie dans l'interface d'administration web (**Gestion → Paramètres**) ou avec
[`aihummer settings set <KEY> <VALUE>`](/fr/v1.0/reference/cli). Pour ces
clés a `gateway.env` valeur est **délibérément ignoré** — même si défini, il a
aucun effet.
## Modèle de configuration
`gateway.env` est **bootstrap seulement**. Ordre de résolution :
- **Clé du catalogue des paramètres**: `database value → built-in default`
(l'environnement est ignoré);
- **clé de démarrage**: `environment variable only`.
Ainsi, la source unique de vérité pour les réglages réglables est la base de données (interface d'administration Web / `aihummer settings`); l'environnement ne contient que ce dont le processus a besoin pour démarrer.
Le fichier de configuration pour une installation native sur l'hôte se trouve à :
```ini
# /home/.aihummer/etc/gateway.env
AIHUMMER_DATABASE_URL=postgres://...
AIHUMMER_MASTER_KEY=base64-32-bytes
```
> [!TIP]
> Ne mettez pas les boutons du catalogue des paramètres `gateway.env` — cela n'a aucun effet. Changer
> eux dans l'interface d'administration web (Gestion → Paramètres, elle a une recherche) ou via
> `aihummer settings set`. Certains changements (comme les basculements d'outils et les sous-agents
> profondeur) appliquer chaud ; d'autres nécessitent un redémarrage du service.
## Bootstrap (gateway.env)
Les seules clés que la passerelle lit réellement à partir de l'environnement.
### Noyau et base de données
| Variable | But |
|---|---|
| `AIHUMMER_DATABASE_URL` | **Requis.** DSN Postgres. Sans lui, la passerelle fonctionne en mode santé seulement. |
| `AIHUMMER_DB_APP_URL` | DSN à rôle restreint qui active la sécurité au niveau des lignes (défini automatiquement pour les installations locales). |
| `AIHUMMER_GATEWAY_ADDR` | Adresse d'écoute publique (par défaut `:8780`) — tout le trafic externe : API (`/v1/*`), appariement, WS/SSE, webhooks entrants, le proxy app/pocket et les sondes de santé. |
| `AIHUMMER_WEBUI_ADDR` | Adresse d'écoute de l'interface Web d'administration privée (par défaut `:8781`), servi à la racine du chemin `/`; idéalement lié à une interface interne uniquement. Définir sur `0` désactiver. |
| `AIHUMMER_DEFAULT_WORKSPACE_ID` | Sélectionne l'espace de travail par défaut pour les intégrations entrantes configurées. |
| `AIHUMMER_HOME_ROOT` | Installe la racine (normalement dérivée du chemin binaire) ; ancre les répertoires admin-ui/blob/installer et les fichiers clés. |
| `AIHUMMER_BLOB_DIR` | Active le service média/fichier (répertoire de stockage de blobs). Il stocke également **artefacts de plugin privés (chargés latéralement)** sous `blob:` références que le déployeur résout. |
| `AIHUMMER_ADMIN_UI_DIR` | Desservir le SPA admin à `/admin/`. |
### Secrets et infrastructure
| Variable | But |
|---|---|
| `AIHUMMER_MASTER_KEY` | 32 octets encodés en base64 ; active les secrets au repos, le coffre-fort et BYOK. |
| `AIHUMMER_MEDIA_TOKEN_SECRET` | Maintient les URL de téléchargement signées valides après les redémarrages. |
| `AIHUMMER_OTEL_ENDPOINT` | Point de terminaison OTLP pour la transmission de traces/métriques. |
| `AIHUMMER_DOWNLOAD_BASE_URL` | URL de base pour les artefacts de version (source de mise à jour automatique). |
> [!WARNING]
> L'observabilité est **OTLP push uniquement**. AiHummer fait **pas** exposer un Prométhée
> `/metrics` point de terminaison ou `/debug/pprof`. Point `AIHUMMER_OTEL_ENDPOINT` à votre
> collectionneur à la place.
## Catalogue des paramètres (base de données — interface web d’administration ou `aihummer settings`)
Chaque clé ci-dessous se trouve dans la base de données. Configurez-la dans l'interface d'administration Web (**Gestion → Paramètres**) ou comme ceci :
```bash
aihummer settings set AIHUMMER_LLM_PROVIDER openai
```
A `gateway.env` la valeur pour une telle clé est **ignoré**.
### Sécurité
| Clé | But |
|---|---|
| `AIHUMMER_APPROVAL_TOOLS` | Outils qui nécessitent l'approbation humaine avant de s'exécuter. |
| `AIHUMMER_AIRGAPPED` | `1` bloque la sortie publique contrôlée par le modèle (mode isolé). |
| `AIHUMMER_AUDIT_RETENTION_DAYS` | Fenêtre de rétention pour le journal d'audit administrateur. |
| `AIHUMMER_INBOUND_SECRET` | Secret partagé HMAC pour connecteur → passerelle `/v1/inbound/*` appels. |
### Authentification et SSO
| Clé | But |
|---|---|
| `AIHUMMER_OIDC_ISSUER` | Protège `/v1/admin/*`. Sans cela (et sans LDAP/SAML), l'administrateur fait confiance aux en-têtes de développement — ne jamais exposer une telle instance. |
LDAP/AD et SAML sont configurés aux côtés de OIDC pour la connexion d'entreprise ; SCIM fournit l'approvisionnement automatique des utilisateurs. Voir [Webhooks, SCIM et jumelage](/fr/v1.0/api/webhooks-scim-pairing).
### LLM et modèles
| Clé | But |
|---|---|
| `AIHUMMER_LLM_PROVIDER` | Fournisseur de modèle à utiliser. |
| `AIHUMMER_LLM_MODEL` | Nom du modèle. |
| `AIHUMMER_LLM_GATEWAY_URL` | URL de base d'une passerelle/point de terminaison LLM compatible OpenAI (le `AIHUMMER_LLM_*` chemin ; distinct de l'origine `AIHUMMER_OPENAI_BASE_URL`). Voir [BYOK et fournisseurs](/fr/v1.0/access/byok-providers). |
| `AIHUMMER_OPENAI_API_KEY` | Clé API pour un fournisseur compatible OpenAI. |
| `AIHUMMER_SUBAGENT_MAX_DEPTH` | Profondeur maximale des sous-agents générés. |
> [!NOTE]
> Si aucun modèle n'est câblé, la passerelle revient à un **simulation déterministe** alors le
> le système fonctionne toujours. Aucun API de modèle payant n'est jamais requis — des modèles gratuits/locaux et un
> Le transport de l'abonnement Codex/ChatGPT est de première classe.
### Outils
| Clé | But |
|---|---|
| `AIHUMMER_FS_ROOT` | Permet `filesystem_read`, isolé sous cette racine. |
| `AIHUMMER_DB_QUERY_DSN` | Permet `db_query` (lecture seule) contre ce DSN. |
| `AIHUMMER_CODE_EXEC` | Bascule le `code_exec` outil (désactivé par défaut sur les hébergements partagés). |
| `AIHUMMER_BROWSER_PROFILE_SOCKET` | Chemin vers le socket privé `managed-profiles.sock` du service de navigateur ; vide — les profils persistants de `computer` sont désactivés. |
| `AIHUMMER_BROWSER_PROFILE_BINDINGS` | Tableau JSON de liaisons explicites de profils de navigateur persistants (`profile_id`, `tenant_id`, `user_id`, `agent_ids`, `conversation_ids`). |
La recherche web et le navigateur sont gérés par l'installateur : ils sont
installés d'origine, se désactivent avec `--no-search` / `--no-browser` et se
pointent vers une instance existante avec `--external-search=URL` /
`--external-browser=URL` — il n'existe aucun réglage opérateur pour eux.
Voir le plein [Catalogue d'outils](/fr/v1.0/reference/tools-catalog) pour ce que fait chaque outil.
### Voix et side-cars
| Clé | But |
|---|---|
| `AIHUMMER_STT_URL` | URL de l'interface audio-texte (initialisée par l'installateur). |
| `AIHUMMER_TTS_URL` | URL du module complémentaire de synthèse vocale (alimenté par l'installateur). |
| `AIHUMMER_VIDEO_URL` | URL secondaire pour la compréhension vidéo. |
| `AIHUMMER_TTS_AUTO_REPLY` | Quand une réponse terminée est lue : `off`, `always`, `inbound` (par défaut), `tagged`. |
| `AIHUMMER_TTS_MAX_CHARS` | Limite du texte lu : `0` — la réponse entière, sinon `100`–`10000` caractères. |
| `AIHUMMER_TTS_SUMMARIZE` | Raccourcir une réponse longue pour la lecture (activé par défaut). |
Les sidecars sont des services HTTP séparés ; la passerelle y accède par URL.
### Vecteurs et embeddings
| Clé | But |
|---|---|
| `AIHUMMER_QDRANT_URL` | Véritable magasin de vecteurs (Qdrant). Absent → magasin en mémoire. |
| `AIHUMMER_EMBEDDER_URL` | Service d'intégration réel. Absent → intégrateur de hachage. |
### Surfaces de protocole (optionnelles)
| Clé | But |
|---|---|
| `AIHUMMER_MCP_PUBLISH` | Exactement `1` ouvre le serveur MCP externe sur `POST /v1/mcp`. À lui seul, il n'exporte aucun outil. |
| `AIHUMMER_MCP_EXPORT_TOOLS` | Noms exacts des outils, séparés par des virgules, que verra le client MCP. Vide (valeur par défaut) = ZÉRO outil exporté. |
| `AIHUMMER_A2A_PUBLISH` | `1` active la surface A2A (`/.well-known/agent.json`, `/a2a/message`). |
## Construction développeur uniquement
| Variable | But |
|---|---|
| `AIHUMMER_PLUGIN_PUBKEY` | Une clé publique fiable supplémentaire (ed25519 en base64) pour vérifier les signatures des plugins. **Uniquement pour les builds de développement — ignoré dans les builds de production** (la clé de registre est épinglée dans le binaire). |
| `AIHUMMER_PLUGIN_DEV_UNSIGNED` | `1` permet d'installer **non signé** extensions. **Uniquement pour les versions de développement — ignoré dans les versions finales.** Jamais sur une instance accessible de l'extérieur. |
> [!WARNING]
> Dans les versions de production, la racine de confiance du plugin est **intégré dans le binaire** et
> ne peut pas être modifié par l'environnement ou les paramètres — il s'agit d'une protection contre la falsification
> garantie.
Le modèle de confiance (officiel → clé épinglée, privé → magasin de confiance, non signé → bloqué) est décrit dans [Installation et mises à jour](/fr/v1.0/marketplace/install-updates#trust-model-and-the-pinned-key).
## Où aller ensuite
- Voyez quels outils chaque clé déverrouille : [Catalogue d'outils](/fr/v1.0/reference/tools-catalog).
- Exploiter l'instance au quotidien : [Référence CLI](/fr/v1.0/reference/cli).
