Variables d'environnement

Multica lit les variables d'environnement au démarrage du processus. Après en avoir modifié une, redémarrez le processus API, web ou daemon concerné. La commande docker compose restart de Docker Compose ne relit pas .env ; recréez les conteneurs avec up -d pour que les modifications prennent effet.

Cette page ne liste que la configuration liée au déploiement ; les variables de test et les variables internes aux exécutions n'y figurent pas. Il s'agit d'une référence organisée par thème — pour les étapes complètes de déploiement, consultez le démarrage rapide de l'auto-hébergement.

Configuration minimale pour la production

DATABASE_URL=postgres://user:password@postgres:5432/multica?sslmode=require
JWT_SECRET=<long-random-secret>
APP_ENV=production
FRONTEND_ORIGIN=https://multica.example.com
MULTICA_APP_URL=https://multica.example.com
MULTICA_PUBLIC_URL=https://api.multica.example.com

Vous devez aussi choisir un service d'e-mail ; sinon, les codes de vérification et les invitations sont uniquement écrits dans le journal du serveur.

API et base de données

Lorsque vous définissez un délai de maintien avant arrêt sur Kubernetes, terminationGracePeriodSeconds doit dépasser ce délai plus le temps nécessaire à l'arrêt proprement dit.

Les limites de connexions du primaire et du réplica sont indépendantes. Dimensionnez leur somme, sur l'ensemble des processus API, par rapport au plafond de connexions du cluster PostgreSQL. Par défaut, les connexions au réplica sont recyclées au bout de cinq minutes afin de revalider le mode lecture seule après une promotion. En cas d'échec de connexion au réplica, les requêtes basculent de façon transparente vers le primaire et un court disjoncteur passif s'ouvre ; aucune sonde de base de données en arrière-plan n'est ajoutée. L'application n'impose aucune limite de retard aux lectures sur le réplica : surveillez le retard de réplication au niveau de la base de données et gardez sur le primaire les lectures sensibles à la cohérence.

URL publiques et accès depuis le navigateur

Lorsque le frontend et l'API s'exécutent sur des hôtes différents et que le navigateur communique directement avec le domaine de l'API, vous devez définir COOKIE_DOMAIN — sinon le navigateur ne peut pas lire le cookie CSRF : toutes les requêtes d'écriture renvoient 403 CSRF validation failed, alors que les lectures fonctionnent normalement. Utilisez le domaine parent le plus restreint qui couvre les deux hôtes (.agent.example.com plutôt que .example.com). Il étend le cookie de session de connexion à tous les hôtes de ce domaine, ce qui n'est acceptable que si tous ces hôtes sont exploités par la même entité de confiance. Après l'avoir modifié, effacez les anciens cookies sur les deux hôtes et reconnectez-vous. Si vous suivez la configuration en origine unique du démarrage rapide de l'auto-hébergement (le navigateur ne visite que le domaine de l'application), laissez-le vide. N'utilisez pas d'adresse IP — les navigateurs ignorent les cookies dont le Domain est une adresse IP.

E-mail et connexion

Resend

SMTP

SMTP est prioritaire sur Resend dès que SMTP_HOST n'est pas vide.

Google OAuth

Périmètre des inscriptions

Pour l'ordre exact d'évaluation des listes d'autorisation, consultez Connexion et inscription.

Stockage des pièces jointes

Lorsque S3_BUCKET n'est pas défini, Multica utilise le disque local.

S3 ou stockage compatible

Utilisez ATTACHMENT_DOWNLOAD_MODE=proxy lorsque le point de terminaison — un MinIO interne, par exemple — n'est pas accessible depuis le navigateur.

Disque local

CloudFront

Redis et limitation de débit

Les déploiements situés derrière un proxy inverse doivent lister les plages d'adresses réelles de leurs proxys. Ne faites pas confiance à toutes les sources sans distinction, sinon les clients peuvent falsifier les IP transmises.

Les limites de débit d'authentification nécessitent REDIS_URL ; sans cette variable, le journal de démarrage indique que la limitation de débit d'authentification est désactivée. Les limites d'invitation fonctionnent quand même sans Redis, dans la mémoire locale du processus, et deviennent partagées entre les réplicas lorsque Redis est configuré. Si le Redis configuré devient temporairement indisponible, la limitation de débit d'authentification laisse passer les requêtes (fail open), tandis que la création d'invitations renvoie une erreur 503 réessayable au lieu d'envoyer des e-mails sans protection.

Intégrations externes

Sans GITHUB_APP_ID et la clé privée, les PR sont toujours liées, reflétées et déclenchent normalement le passage à done lors du merge, mais les cartes n'affichent ni statut CI ni possibilité de fusion, et l'entrée de dépôt « Choisir depuis GitHub » est désactivée.

Pour les étapes de configuration, consultez Intégration GitHub, Bot Lark, Bot Slack et Bot Telegram.

LLM côté serveur

Ce groupe configure la génération d'assistance côté serveur, comme les titres des conversations ; il ne s'agit pas des identifiants des outils de codage IA que les agents utilisent pour réaliser les exécutions.

MULTICA_LLM_MAX_RETRIES est la seule source de la politique de nouvelles tentatives. Laissez-la non définie pour la valeur par défaut de 2, définissez 0 pour envoyer exactement une requête par appel, ou une valeur de 1 à 5 pour plafonner les nouvelles tentatives à ce nombre. C'est un plafond, pas un quota : seuls les échecs réessayables le consomment, et un succès ou l'échéance propre de l'appelant peut mettre fin à l'appel plus tôt. Toute autre valeur — négative, non numérique ou supérieure à 5 — fait échouer le démarrage au lieu d'être corrigée silencieusement. Ce plafond est un budget de latence : le délai entre deux tentatives commence à 0,5 s et double jusqu'à un maximum de 8 s, si bien qu'un budget plus élevé dépasserait les échéances des appelants et transformerait un échec réessayable en expiration de délai. Les nouvelles tentatives couvrent les échecs de connexion et les codes HTTP 408, 409, 429 et 5xx ; toutes les autres réponses 4xx sont renvoyées telles quelles. Au démarrage, le serveur journalise la politique effective sous la forme llm retry policy, sans aucun identifiant dans la ligne.

Deux fonctionnalités utilisent cette couche, et chacune envoie du contenu de discussion au point de terminaison que vous configurez :

• Titre automatique des discussions — le premier message de l'utilisateur dans une nouvelle session de discussion, envoyé tel quel. Les pièces jointes ne sont jamais incluses.
• Questions de suivi (les boutons de suggestion sous la réponse d'un agent) — la fin de la conversation : jusqu'à 6 messages, la réponse à laquelle les questions font suite étant tronquée à 3 000 caractères et chaque message plus ancien à 800.

Lorsque la clé d'API et l'URL de base sont toutes deux vides, cette couche est désactivée et n'effectue aucune requête en amont — aucune des deux fonctionnalités ci-dessus n'envoie quoi que ce soit. C'est la configuration prise en charge lorsque votre politique n'autorise pas cette couche à envoyer du contenu de discussion hors du déploiement : les sessions de discussion conservent le titre que le client dérive du premier message, les boutons de questions de suivi n'apparaissent pas, et tout le reste fonctionne normalement.

Configuration du daemon

Les variables ci-dessous sont lues sur l'ordinateur qui exécute vos agents, et non dans le conteneur de l'API.

Pour le contexte interne que le daemon injecte dans les exécutions des agents, consultez Environnement des exécutions.

Chaque outil de codage IA accepte MULTICA_<PROVIDER>_PATH et MULTICA_<PROVIDER>_MODEL pour remplacer le chemin de la commande et le modèle par défaut. QwenPaw et MiniMax Code n'ont pas de variable de modèle, car Multica ne leur envoie jamais de modèle ; la variable de chemin de MiniMax Code est MULTICA_MCODE_PATH — consultez Comparaison des outils de codage IA. DeepSeek Harness prend en charge MULTICA_DSH_PATH et MULTICA_DSH_MODEL (un ID de modèle du catalogue dsh, par exemple deepseek-official/deepseek-chat). DeepSeek Harness accepte en outre MULTICA_DSH_PROFILE_BUNDLE : une liste de bundles, séparés par des virgules, à installer dans son profil multica lorsque ce profil est absent, essayés dans l'ordre, chaque entrée étant une spécification npm, un répertoire ou une archive tarball empaquetée. Elle n'est pas définie par défaut, et c'est ce profil qui fournit le protocole --stdio que pilote Multica : si la variable n'est pas définie, l'installation DSH reste intacte et le daemon signale le profil manquant au lieu d'enregistrer un runtime inutilisable. Le bridge de Multica n'est pas encore publié sur un registre npm public ; le choix d'une valeur est donc traité dans Installer un runtime d'agent. Ce que vous définissez est installé dans le répertoire DSH de chaque hôte de daemon sans autre confirmation : considérez donc ce choix comme une décision relative à la chaîne d'approvisionnement. L'installation qu'active MULTICA_DSH_PROFILE_BUNDLE est volontairement limitée : elle s'exécute au plus une fois par durée de vie du daemon, uniquement lorsque la sonde signale que le profil est réellement absent, et un échec est journalisé avec la sortie du gestionnaire de paquets lui-même et n'est retenté qu'après un redémarrage du daemon. Une sonde qui expire, ou qui répond avec une version de protocole que ce daemon ne pilote pas, est signalée et ne donne jamais lieu à une installation par-dessus — le daemon n'écrase pas un profil présent à dessein. Pour diagnostiquer, recherchez DSH runtime profile dans le journal du daemon ; pour annuler une installation, supprimez $DSH_HOME/profiles/multica (par défaut ~/.dsh/profiles/multica). MULTICA_DSH_PLUGIN_PATH remplace le répertoire à partir duquel l'installation résout pnpm. DSH Desktop conserve le pnpm vers lequel dsh plugin redirige dans son propre répertoire de commandes du runtime, sous macOS comme sous Windows, et le daemon le trouve et l'ajoute automatiquement en tête — y compris dans l'arborescence versionnée qu'utilise une version plus récente de Desktop. Cette variable n'est donc nécessaire que pour une installation que le daemon ne parvient pas à trouver, ou pour que l'installation utilise votre propre pnpm. La définir remplace entièrement la recherche : si le répertoire n'existe pas, l'installation se rabat sur le pnpm présent dans le PATH du daemon plutôt que sur celui fourni. Linux n'a pas de DSH Desktop ; l'installation y utilise donc toujours le PATH. Dim prend en charge MULTICA_DIM_PATH et MULTICA_DIM_MODEL (un ID de modèle du catalogue dim). ZeroClaw prend en charge MULTICA_ZEROCLAW_PATH mais n'a pas de variable de modèle ; c'est son profil d'agent qui détermine le choix du modèle. Les arguments par défaut à l'échelle de la machine via MULTICA_<PROVIDER>_ARGS sont actuellement pris en charge pour cinq outils : Claude Code, Codex, CodeBuddy, Qwen Code et QwenPaw. Les variables sont MULTICA_CLAUDE_ARGS, MULTICA_CODEX_ARGS, MULTICA_CODEBUDDY_ARGS, MULTICA_QWEN_ARGS et MULTICA_QWENPAW_ARGS. Par exemple :

MULTICA_CLAUDE_PATH=/opt/bin/claude
MULTICA_CLAUDE_ARGS=--max-turns 40

Le nettoyage vérifié des processus d'arrière-plan de Cursor nécessite Linux 6.9 ou une version ultérieure (pidfd de groupe de processus), la prise en charge par le noyau macOS des requêtes d'identité de processus et de l'envoi de signaux par audit token, ou un Job Object imbriqué correctement attribué sous Windows. Sous macOS, chaque processus reçoit ses signaux au moyen d'une version de PID vérifiée par le noyau ; aucune adhésion à un groupe de la même session n'est nécessaire. Ces API macOS sont privées et vérifiées au moment de la capture. Un lancement qui ne peut pas être revendiqué renvoie son résultat d'outil d'origine et utilise le watchdog d'inactivité ordinaire, y compris lorsque le watchdog d'outil vaut 0. Le travail déjà revendiqué reste en cours si le nettoyage ne peut pas être confirmé. Avec un watchdog d'outil à 0, cette limite n'existe pas du tout : le travail d'arrière-plan revendiqué maintient l'exécution en cours aussi longtemps qu'il vit, si bien que l'exécution n'est bornée que par MULTICA_AGENT_TIMEOUT, qui vaut 0 par défaut.

Les processus d'arrière-plan de Cursor qui appartiennent à l'exécution sont aussi arrêtés lorsque celle-ci se termine normalement : un serveur d'arrière-plan lancé par cette exécution ne survit donc pas intentionnellement à la finalisation. macOS peut reconnaître des enfants tardifs grâce aux identités de parent d'origine conservées, mais ne peut pas prouver une chaîne dont les processus intermédiaires ont disparu avant d'être observés. De tels processus, le travail qui quitte le groupe suivi, ou des erreurs persistantes d'appartenance ou d'envoi de signaux peuvent laisser du travail d'arrière-plan derrière eux. Un nettoyage non confirmé est journalisé et n'ouvre jamais la fenêtre de récupération réservée aux nettoyages réussis ; les processus inconnus ne sont pas tués sur la seule base de leur PID numérique ou de leur groupe de processus.

L'ordre de priorité est : option de ligne de commande → variable d'environnement → ~/.multica/config.json → valeur par défaut intégrée. Pour le comportement du watchdog, consultez Daemon et runtimes.

Rendre persistante la configuration du daemon

Les paramètres courants côté daemon peuvent aussi être écrits dans ~/.multica/config.json au lieu de dépendre des variables d'environnement du shell ; les profils nommés conservent les leurs dans ~/.multica/profiles/<name>/config.json :

multica config set poll_interval 10s
multica config show

Clés prises en charge :

Quelques règles concernant les valeurs :

• Les clés de durée acceptent des durées Go positives (comme 10s, 2h) ; 0s et les valeurs négatives sont refusées. La seule exception est agent_timeout : 0s est valide et désactive explicitement la limite de durée des exécutions.
• Passer une chaîne vide efface une valeur persistée et revient à la variable d'environnement ou à la valeur par défaut intégrée, par exemple multica config set poll_interval "".
• max_concurrent_tasks exige un entier positif ou nul.
• Les valeurs relatives de workspaces_root sont converties en chemins absolus lors de l'enregistrement.

Observabilité et analytique

La télémétrie propre à Multica pour les instances auto-hébergées envoie un instantané par jour UTC, au niveau du déploiement, au point de terminaison fixe et non configurable https://telemetry.multica.ai/v1/telemetry/events. Il contient la version officielle publiée ; les nombres, regroupés par tranches, d'espaces de travail, de membres humains distincts, d'agents actifs et de daemons actifs sur 24 heures ; ainsi que le nombre agrégé d'exécutions des 24 heures précédentes. Il n'inclut jamais de noms, d'adresses ou de domaines e-mail, d'adresses IP, d'identifiants métier, de détails sur les hôtes ou les appareils, de dépôts, de modèles ou de plugins, de prompts ou de sorties, de commentaires ou de discussions, de chemins, de données de tokens ou de coûts, d'identifiants de connexion, d'erreurs, de piles d'appels ni de journaux. Il sert uniquement à comprendre l'adoption des versions auto-hébergées, les tranches de taille des déploiements et l'usage agrégé — et non à la facturation, aux licences, à l'authentification ou aux décisions de sécurité.

DO_NOT_TRACK et ANALYTICS_DISABLED sont indépendantes. La première contrôle cet instantané anonyme propre à Multica ; la seconde contrôle l'intégration facultative avec PostHog.

Étapes suivantes

• Connexion et inscription — méthodes de connexion et restrictions d'inscription.
• Dépannage — diagnostic des problèmes de déploiement à partir des symptômes.
• Daemon et runtimes — les équivalents côté daemon de cette configuration.