ObjectOSVariables d'environnement
Référence des variables d'environnement d'exécution d'ObjectOS.
Variables d'environnement
Utilisez les variables d'environnement pour la configuration au niveau du déploiement et les secrets. Utilisez les paramètres système pour la configuration applicative modifiable par le locataire ou l'utilisateur.
Nommage. Toutes les variables appartenant à ObjectStack utilisent le préfixe
OS_. Les noms sans préfixe antérieurs à la version 1.0 (PORT,AUTH_SECRET,OS_MULTI_TENANT, …) fonctionnent toujours mais émettent un avertissement de dépréciation unique. Préférez les noms canoniquesOS_*dans les nouveaux déploiements ; voir Alias hérités.
Cœur
| Variable | Requis | Description |
|---|---|---|
OS_PORT | Non | Port HTTP sur lequel le runtime écoute. Par défaut 3000. Alias hérité : PORT. |
OS_AUTH_SECRET | Oui pour l'authentification | Secret de base utilisé pour dériver les secrets d'authentification par projet. Alias hérité : AUTH_SECRET. |
Résolution des artefacts et des projets
| Variable | Requis | Description |
|---|---|---|
OS_ARTIFACT_FILE | Mode fichier | Chemin ou URL http(s):// vers un objectstack.json compilé. Lu par la configuration ObjectOS et transmis en tant que artifactPath à createStandaloneStack. Pointez-le vers une URL d'artefact publiée pour les déploiements connectés au cloud. |
OS_ARTIFACT_PATH | Alternative | Nom au niveau du framework pour le même chemin ou la même URL, pris en charge directement par @objectstack/runtime (CLI dev/start). Par défaut <cwd>/dist/objectstack.json. |
OS_PROJECT_ID | Optionnel | Alias hérité pour OS_ENVIRONMENT_ID, accepté par la configuration ObjectOS pour des raisons de rétrocompatibilité. Préférez OS_ENVIRONMENT_ID dans les nouveaux déploiements. |
OS_ENVIRONMENT_ID | Optionnel | Identifiant d'environnement pour le stack autonome (par défaut proj_local). Également utilisé pour dériver le secret d'authentification par projet. La configuration ObjectOS accepte aussi l'alias hérité OS_PROJECT_ID. |
OS_ORGANIZATION_ID | Optionnel | Identifiant d'organisation par défaut pour le mode adossé à un fichier (par défaut org_local). |
OS_MCP_SERVER_ENABLED | Non | Définissez-le à true pour exposer le serveur Model Context Protocol via Streamable HTTP sur /api/v1/mcp (8.0+). Désactivé par défaut : l'endpoint renvoie 404 jusqu'à activation, puis requiert un principal authentifié. |
OS_CLOUD_URL | Optionnel | URL de base du plan de contrôle pour le proxy du marketplace et l'installation locale de paquets. Définissez-le à off ou local pour désactiver les fonctionnalités du marketplace. N'est plus utilisé pour le routage par nom d'hôte du host-stack dans la distribution autonome. |
OS_MULTI_ORG_ENABLED | Non | Définissez-le à true pour activer le routage multi-locataire / le changement d'organisation (par défaut false). Alias hérité : OS_MULTI_TENANT. |
OS_RUNTIME_PORT | Dev uniquement | Port localhost utilisé pour construire les URL de rappel SSO de la plateforme lors du développement sur http://localhost:<port>. |
Rechargement à chaud de l'artefact. Le stack autonome recharge automatiquement l'artefact local hors production (piloté par
NODE_ENV) ; le drapeau expliciteOS_WATCH_ARTIFACT=1de 7.x n'est plus requis.
Cache
| Variable | Par défaut | Description |
|---|---|---|
OS_KERNEL_CACHE_SIZE | 32 | Nombre maximal de kernels de projet en cache. |
OS_KERNEL_TTL_MS | 900000 | TTL d'inactivité pour les kernels de projet. |
OS_ENV_CACHE_TTL_MS | 300000 | TTL du cache d'environnement/de noms d'hôte. |
OS_ARTIFACT_CACHE_TTL_MS | 300000 | TTL du cache des réponses d'artefacts. |
Authentification et origines de confiance
| Variable | Description |
|---|---|
AUTH_SECRET | Alias hérité pour OS_AUTH_SECRET. Toujours pris en charge dans cette version ; préférez OS_AUTH_SECRET. |
OS_TRUSTED_ORIGINS | Origines de confiance supplémentaires, séparées par des virgules. |
OS_ROOT_DOMAIN | Domaine racine utilisé pour faire confiance aux sous-domaines de projet dans les déploiements SSO de la plateforme. |
OS_PLATFORM_SSO | Définissez-le à false pour désactiver le câblage SSO de la plateforme. |
OS_RUNTIME_PORT | Aide au développement local pour les noms d'hôte de projet en localhost. |
Base de données
En mode connecté au cloud, le plan de contrôle renvoie la configuration de la base de données d'exécution par projet avec la réponse d'artefact. En mode adossé à un fichier, ObjectOS lit les déclarations de source de données depuis l'artefact. En dernier recours, le framework prend également en charge :
| Variable | Description |
|---|---|
OS_DATABASE_URL | URL de connexion (file:./db.sqlite, libsql://…, postgres://…, mongodb://…, memory://). Utilisée par le mode autonome et la CLI dev. |
OS_DATABASE_DRIVER | Remplace le pilote auto-détecté à partir de l'URL. |
OS_DATABASE_AUTH_TOKEN | Jeton d'authentification pour les pilotes managés tels que Turso/libSQL. |
OS_BUSINESS_DB_URL | Convention du wrapper ObjectOS pour l'URL de la base de données métier par projet. Résolvez-la vers OS_DATABASE_URL ou un remplacement de source de données d'exécution dans votre déploiement. |
OS_CACHE_DIR | Répertoire de cache local des artefacts et de l'exécution (par défaut /var/cache/objectos). |
OS_SKIP_SCHEMA_SYNC | Définissez-le à 1 pour ignorer la synchronisation DDL ObjectQL au démarrage. À utiliser lorsque le schéma est géré hors bande. |
Pour les déploiements clients ObjectOS, préférez une configuration d'exécution explicite du plan de contrôle ou une configuration de source de données d'artefact plutôt que de vous appuyer sur les valeurs par défaut locales au conteneur.
Observabilité
L'export des traces et des métriques est opt-in. L'exporteur a pour valeur par
défaut noop, de sorte qu'un déploiement n'émet rien tant que vous n'en
sélectionnez pas un — définir un endpoint seul ne fait rien.
| Variable | Par défaut | Description |
|---|---|---|
OS_OBS_EXPORTER | noop | Exporteur de télémétrie : noop | console | json | otlp. Utilisez console/json pour le débogage local, otlp pour un collecteur. |
OS_OTLP_ENDPOINT | — | URL racine OTLP/HTTP (par ex. https://otlp.grafana.net/otlp). Requise lorsque OS_OBS_EXPORTER=otlp ; si vide, le runtime avertit et retombe sur noop. |
OS_OTLP_HEADERS | — | En-têtes OTLP supplémentaires (par ex. authentification) sous forme de paires key=value séparées par des virgules. |
OS_OBS_SERVICE_NAME | — | Attribut de ressource service.name sur les spans/métriques émis. |
OS_OBS_DEPLOYMENT_ENV | production | Attribut de ressource deployment.environment. |
OS_OTLP_FLUSH_MS | — | Intervalle de vidage de l'exporteur OTLP, en millisecondes. |
Remplacements d'espace de noms des paramètres
Les paramètres système (les espaces de noms ai, email, feature_flags, …
modifiables par le locataire ou l'utilisateur) peuvent être épinglés au niveau du
déploiement avec une variable d'environnement nommée OS_<NAMESPACE>_<KEY> — en
majuscules, avec . et - remplacés par _. Par exemple ai.openai_base_url
→ OS_AI_OPENAI_BASE_URL, et feature_flags.ai_enabled
→ OS_FEATURE_FLAGS_AI_ENABLED. À partir de la 9.0, les alias sans préfixe ont
été supprimés — la forme préfixée par OS_ est la seule lue.
La connexion Google (configurable dans Setup → Authentication) lit également
GOOGLE_CLIENT_ID et GOOGLE_CLIENT_SECRET au niveau du déploiement.
Alias hérités
Ces noms antérieurs à la version 1.0 fonctionnent toujours dans cette version mais émettent un avertissement de dépréciation unique. Ils seront supprimés dans une future version majeure. Préférez le nom canonique.
| Canonique | Hérité |
|---|---|
OS_PORT | PORT |
OS_AUTH_SECRET | AUTH_SECRET |
OS_MULTI_ORG_ENABLED | OS_MULTI_TENANT |
OS_ENVIRONMENT_ID | OS_PROJECT_ID |