ObjectOSVariables de entorno
Referencia de variables de entorno del entorno de ejecución de ObjectOS.
Variables de entorno
Use variables de entorno para la configuración a nivel de despliegue y los secretos. Use la configuración del sistema para la configuración de la aplicación editable por inquilino/usuario.
Nomenclatura. Todas las variables propiedad de ObjectStack usan el prefijo
OS_. Los nombres sin prefijo anteriores a 1.0 (PORT,AUTH_SECRET,OS_MULTI_TENANT, …) siguen funcionando, pero emiten una advertencia de obsolescencia de una sola vez. Prefiera los nombres canónicosOS_*en los nuevos despliegues; consulte Alias heredados.
Núcleo
| Variable | Obligatoria | Descripción |
|---|---|---|
OS_PORT | No | Puerto HTTP en el que escucha el entorno de ejecución. Por defecto es 3000. Alias heredado: PORT. |
OS_AUTH_SECRET | Sí para auth | Secreto base utilizado para derivar los secretos de autenticación por proyecto. Alias heredado: AUTH_SECRET. |
Resolución de artefactos y proyectos
| Variable | Obligatoria | Descripción |
|---|---|---|
OS_ARTIFACT_FILE | Modo archivo | Ruta o URL http(s):// a un objectstack.json compilado. Leído por la configuración de ObjectOS y pasado como artifactPath a createStandaloneStack. Apúntelo a una URL de artefacto publicada en la nube para despliegues conectados a la nube. |
OS_ARTIFACT_PATH | Alternativa | Nombre a nivel de framework para la misma ruta o URL, reconocido directamente por @objectstack/runtime (CLI dev/start). Por defecto <cwd>/dist/objectstack.json. |
OS_PROJECT_ID | Opcional | Alias heredado de OS_ENVIRONMENT_ID, aceptado por la configuración de ObjectOS por compatibilidad con versiones anteriores. Prefiera OS_ENVIRONMENT_ID en los nuevos despliegues. |
OS_ENVIRONMENT_ID | Opcional | Id de entorno para el stack independiente (por defecto proj_local). También se usa para derivar el secreto de autenticación por proyecto. La configuración de ObjectOS también acepta el alias heredado OS_PROJECT_ID. |
OS_ORGANIZATION_ID | Opcional | Id de organización por defecto para el modo respaldado por archivo (por defecto org_local). |
OS_MCP_SERVER_ENABLED | No | Establézcalo en true para exponer el servidor Model Context Protocol sobre Streamable HTTP en /api/v1/mcp (8.0+). Desactivado por defecto: el endpoint devuelve 404 hasta que se habilita y, una vez activo, requiere un principal autenticado. |
OS_CLOUD_URL | Opcional | URL base del plano de control para el proxy del marketplace y la instalación local de paquetes. Establézcalo en off o local para deshabilitar las funciones del marketplace. Ya no se usa para el enrutamiento por nombre de host del host-stack en la distribución independiente. |
OS_MULTI_ORG_ENABLED | No | Establézcalo en true para habilitar el enrutamiento multiinquilino / cambio de organización (por defecto false). Alias heredado: OS_MULTI_TENANT. |
OS_RUNTIME_PORT | Solo desarrollo | Puerto de localhost utilizado para construir las URL de callback de SSO de plataforma al desarrollar en http://localhost:<port>. |
Recarga en caliente del artefacto. El stack independiente recarga el artefacto local automáticamente fuera de producción (controlado por
NODE_ENV); el indicador explícitoOS_WATCH_ARTIFACT=1de 7.x ya no es necesario.
Caché
| Variable | Por defecto | Descripción |
|---|---|---|
OS_KERNEL_CACHE_SIZE | 32 | Máximo de kernels de proyecto en caché. |
OS_KERNEL_TTL_MS | 900000 | TTL de inactividad para los kernels de proyecto. |
OS_ENV_CACHE_TTL_MS | 300000 | TTL de la caché de entorno/nombre de host. |
OS_ARTIFACT_CACHE_TTL_MS | 300000 | TTL de la caché de respuestas de artefactos. |
Autenticación y orígenes de confianza
| Variable | Descripción |
|---|---|
AUTH_SECRET | Alias heredado de OS_AUTH_SECRET. Aún reconocido en esta versión; prefiera OS_AUTH_SECRET. |
OS_TRUSTED_ORIGINS | Orígenes de confianza adicionales separados por comas. |
OS_ROOT_DOMAIN | Dominio raíz utilizado para confiar en los subdominios de proyecto en despliegues de SSO de plataforma. |
OS_PLATFORM_SSO | Establézcalo en false para desactivar el cableado del SSO de plataforma. |
OS_RUNTIME_PORT | Ayudante de desarrollo local para los nombres de host de proyecto en localhost. |
Base de datos
En el modo conectado a la nube, el plano de control devuelve la configuración de la base de datos del entorno de ejecución por proyecto junto con la respuesta del artefacto. En el modo respaldado por archivo, ObjectOS lee las declaraciones de origen de datos del artefacto. Como último recurso, el framework también reconoce:
| Variable | Descripción |
|---|---|
OS_DATABASE_URL | URL de conexión (file:./db.sqlite, libsql://…, postgres://…, mongodb://…, memory://). Utilizada por el modo independiente y la CLI dev. |
OS_DATABASE_DRIVER | Anula el controlador detectado automáticamente a partir de la URL. |
OS_DATABASE_AUTH_TOKEN | Token de autenticación para controladores gestionados como Turso/libSQL. |
OS_BUSINESS_DB_URL | Convención del envoltorio de ObjectOS para la URL de la base de datos de negocio por proyecto. Resuélvala a OS_DATABASE_URL o a una anulación de origen de datos del entorno de ejecución en su despliegue. |
OS_CACHE_DIR | Directorio local de caché de artefactos y del entorno de ejecución (por defecto /var/cache/objectos). |
OS_SKIP_SCHEMA_SYNC | Establézcalo en 1 para omitir la sincronización de DDL de ObjectQL en el arranque. Úselo cuando el esquema se gestiona de forma externa. |
Para los despliegues de clientes de ObjectOS, prefiera la configuración explícita del entorno de ejecución del plano de control o la configuración de origen de datos del artefacto en lugar de depender de los valores por defecto locales del contenedor.
Observabilidad
La exportación de trazas y métricas es opcional. El exportador es noop por
defecto, por lo que un despliegue no emite nada hasta que seleccione uno:
establecer únicamente un endpoint no hace nada.
| Variable | Por defecto | Descripción |
|---|---|---|
OS_OBS_EXPORTER | noop | Exportador de telemetría: noop | console | json | otlp. Use console/json para depuración local y otlp para un collector. |
OS_OTLP_ENDPOINT | — | URL raíz de OTLP/HTTP (p. ej. https://otlp.grafana.net/otlp). Obligatoria cuando OS_OBS_EXPORTER=otlp; si está vacía, el entorno de ejecución advierte y vuelve a noop. |
OS_OTLP_HEADERS | — | Cabeceras OTLP adicionales (p. ej. autenticación) como pares key=value separados por comas. |
OS_OBS_SERVICE_NAME | — | Atributo de recurso service.name en las trazas/métricas emitidas. |
OS_OBS_DEPLOYMENT_ENV | production | Atributo de recurso deployment.environment. |
OS_OTLP_FLUSH_MS | — | Intervalo de vaciado del exportador OTLP, en milisegundos. |
Anulaciones de espacios de nombres de configuración
La configuración del sistema (los espacios de nombres ai, email,
feature_flags, … editables por inquilino/usuario) puede fijarse a nivel de
despliegue con una variable de entorno llamada OS_<NAMESPACE>_<KEY> —en
mayúsculas, con . y - reemplazados por _. Por ejemplo,
ai.openai_base_url → OS_AI_OPENAI_BASE_URL, y
feature_flags.ai_enabled → OS_FEATURE_FLAGS_AI_ENABLED. A partir de 9.0 se
eliminaron los alias sin prefijo: la forma con prefijo OS_ es la única que se
lee.
El inicio de sesión con Google (configurable en Setup → Authentication)
también lee GOOGLE_CLIENT_ID y GOOGLE_CLIENT_SECRET a nivel de despliegue.
Alias heredados
Estos nombres anteriores a 1.0 siguen funcionando en esta versión, pero emiten una advertencia de obsolescencia de una sola vez. Se eliminarán en una versión mayor futura. Prefiera el nombre canónico.
| Canónico | Heredado |
|---|---|
OS_PORT | PORT |
OS_AUTH_SECRET | AUTH_SECRET |
OS_MULTI_ORG_ENABLED | OS_MULTI_TENANT |
OS_ENVIRONMENT_ID | OS_PROJECT_ID |