Configuración por variables de entorno¶

La configuración de Cortex HIVE sigue la convención 12-factor: variables de entorno con nombres genéricos por función (DATABASE_URL, REDIS_URL, MAIL_*), alineados con ecosistemas como Laravel, no prefijos de producto (CORTEX_*).

Copia .env.example a .env en la raíz del monorepo y carga con set -a && source .env && set +a.

Deprecación de `CORTEX_*`¶

Durante la transición, el runtime acepta variables CORTEX_* como alias deprecados si no existe la variable canónica. Se emite DeprecationWarning en desarrollo. Migra a los nombres de esta página.

Aplicación¶

Variable	Tipo	Default	Prod
`APP_ENV`	string	—	`production`
`APP_DEBUG`	bool	`false`	`false`

Base de datos¶

Variable	Tipo	Default	Prod
`DATABASE_URL`	string	`postgresql+asyncpg://cortex:cortex@localhost:5432/cortex`	Obligatorio
`PLATFORM_SETTINGS_URL`	string	vacío	Opcional (backend alternativo)

Redis¶

Variable	Tipo	Default	Prod
`REDIS_URL`	string	`redis://localhost:6379/0`	Recomendado
`REDIS_REQUIRED`	bool	`false`	Según política NFR

Autenticación¶

Variable	Tipo	Default	Prod
`AUTH_MODE`	string	`optional`	`required` en multi-tenant
`JWT_SECRET`	string	`dev-secret-change-in-production`	Obligatorio si `required`/`internal`
`OIDC_ISSUER`	string	vacío	Si `external`
`OIDC_AUDIENCE`	string	vacío	Si `external`
`OIDC_JWKS_URI`	string	vacío	Si `external`

Modos AUTH_MODE: optional | required | internal | external. Ver ADR 005.

API y rate limit¶

Variable	Tipo	Default	Prod
`API_PORT`	int	`8000`	Según orquestador
`RATE_LIMIT_ENABLED`	bool	`false`	`true` recomendado
`RATE_LIMIT_PER_MINUTE`	int	`120`	Ajustar por carga

Plugins (discovery)¶

Variable	Tipo	Default	Prod
`PLUGINS_ROOT`	string	vacío	Workspace dev; vacío en smoke pip
`PLUGIN_DIRS`	string	vacío	Sideload dev (`:` separador)
`PLUGIN_DEPS`	string	`strict`	`strict` en producción
`PLUGIN_STORAGE`	string	`memory`	`postgres` en despliegue

La activación de plugins es vía /control/plugins (state store PG). No usar CORTEX_ENABLED_PLUGINS ni CORTEX_ENABLED_PANELS.

Mail¶

Variable	Tipo	Default
`MAIL_ENABLED`	bool	`false`
`MAIL_HOST`	string	vacío
`MAIL_PORT`	int	`587`
`MAIL_USERNAME`	string	vacío
`MAIL_PASSWORD`	string	vacío
`MAIL_FROM`	string	vacío
`MAIL_USE_TLS`	bool	`true`

Uploads (S3)¶

Variable	Tipo	Default
`UPLOAD_BUCKET`	string	vacío
`UPLOAD_REGION`	string	`us-east-1`
`UPLOAD_PREFIX`	string	`cortex`
`UPLOAD_PUBLIC_BASE_URL`	string	vacío

Webhooks¶

Variable	Tipo	Default
`WEBHOOK_SECRET`	string	vacío

Firma HMAC en cabecera X-Cortex-Signature.

Dominio booking¶

Configuración de negocio del plugin booking (sin prefijo de plataforma):

Variable	Tipo	Default
`BOOKING_TIMEZONE`	string	`America/Bogota`
`BOOKING_OPEN_TIME`	string	`06:00`
`BOOKING_CLOSE_TIME`	string	`22:00`
`BOOKING_SLOT_MINUTES`	int	`30`
`BOOKING_ALLOW_OVERBOOKING`	bool	`false`

Integración ai-agents¶

Variable	Tipo	Default
`INTERNAL_API_URL`	string	`http://127.0.0.1:8000`
`AI_AGENTS_THREAD_TTL_MINUTES`	int	`10080`

Proveedores IA (credenciales)¶

Variable	Uso
`NVIDIA_KEY`	NVIDIA Build
`GEMINI_KEY`	Google AI Studio
`OPENAI_KEY`	OpenAI
`ANTHROPIC_KEY`	Anthropic

Skins¶

Variable	Tipo	Default
`SKINS_ROOT`	string	vacío