Referencia de configuración

Cómo se carga la configuración#

El backend lee el entorno al arrancar y valida la combinación antes de abrir el puerto: si algo es incoherente, el proceso termina con un error que nombra la variable. El runtime lee sus variables cuando las usa. El frontend no lee nada en ejecución: sus valores quedan fijados al compilar.

• Booleanos: true, false, 1, 0 y el resto de valores que acepta strconv.ParseBool. Un valor inválido aborta el arranque.
• Enteros y duraciones: un valor ausente, no numérico o menor o igual que cero se sustituye por el valor por defecto. Las duraciones usan la sintaxis de Go (30s, 5m, 1h).
• Importes en USD: 0 es válido y desactiva el tope correspondiente; un valor negativo o no numérico deja el valor por defecto. La excepción es BUDGET_USD, que necesita un valor mayor que cero.
• Listas: valores separados por comas; se ignoran los espacios.

Servidor y base de datos#

Autenticación, CORS y proxy#

Con AUTH_ENABLED=false el backend funciona en modo demo: una organización fija y sin inicio de sesión. Con AUTH_ENABLED=true activa cuentas, JWT, RBAC y aislamiento por organización, y el org_id sale del token.

Con la autenticación activa, el arranque falla si JWT_SECRET tiene menos de 32 bytes, si falta DATABASE_URL o si ALLOWED_ORIGINS contiene *.

Presupuesto, costo y límites de ejecución#

Estas variables controlan el gasto y la concurrencia del orquestador. Las ventanas de contexto y los controles de calidad tienen más ajustes internos con valores por defecto razonables; esta tabla recoge los que conviene conocer.

Recompensas y monedas#

El sistema de monedas premia el trabajo completado. REWARDS_RULES acepta un JSON que se aplica encima de las reglas por defecto, así que basta con incluir los campos que quieras cambiar.

Si el JSON tiene un valor inválido, el backend lo registra en el log y usa las reglas por defecto completas: nunca aplica una economía a medias.

{
  "enabled": true,
  "base": { "S": 5, "M": 10, "L": 20, "XL": 40 },
  "default_complexity": "M",
  "first_try_bonus_pct": 50,
  "rework_pct": 50,
  "project_base": 20,
  "project_per_task": 2,
  "project_max": 100,
  "min_project_tasks": 2
}

Runtime: proveedores de modelo y claves#

El runtime admite cinco proveedores: deepseek, anthropic, openai, kimi y custom (un endpoint compatible con OpenAI, por ejemplo vLLM u Ollama). Un proveedor cuenta como configurado cuando su clave (y, para custom, su URL base) está en el entorno. Sin ningún proveedor configurado, o con SIMULATION=true, el runtime usa el motor simulado: respuestas guionadas, sin claves y sin costo.

Ante un error transitorio (timeout, límite de tasa, 5xx) reintenta en el mismo proveedor y después pasa al siguiente permitido. ALLOWED_PROVIDERS es el techo del operador: ningún dato llega a un proveedor excluido, ni siquiera como respaldo. Cada organización puede restringirlo más desde sus ajustes, nunca ampliarlo, y puede guardar su propia clave de proveedor, que gana a la del entorno.

Conexiones, sandbox, almacenamiento y push#

Sin CONNECTIONS_KEK no se puede guardar ninguna credencial real: la bóveda falla cerrada y solo funcionan las conexiones simuladas. La KEK es base64 de 32 bytes aleatorios; guárdala aparte de la base de datos, porque sin ella los secretos cifrados son irrecuperables.

El sandbox de código es opcional y necesita el servicio sandbox-runner, que recibe acceso al socket de Docker. Lee antes la página del modelo de seguridad.

openssl rand -base64 32

Límites de tasa#

Los límites de tasa están integrados en el backend y no tienen variables de ajuste: por ejemplo, 10 intentos de inicio de sesión cada 15 minutos y 120 comandos por minuto. Los de autenticación se guardan en Redis si hay REDIS_URL, y en memoria del proceso si no.

Lo que sí se configura es TRUSTED_PROXIES. Solo la cabecera X-Forwarded-For de esos proxies sirve para identificar al cliente. Detrás de Caddy, indica la red del proxy: sin ella, todos los clientes comparten la IP del proxy y el mismo contador.

Frontend: argumentos de build#

El frontend se compila con salida standalone. Las variables NEXT_PUBLIC_* se incorporan al compilar como argumentos del Dockerfile (ARG); cambiarlas exige reconstruir la imagen.

Dejarlas vacías da el comportamiento recomendado para un solo dominio: la API en la ruta relativa /api/v1 y el WebSocket derivado de window.location.

docker build \
  --build-arg NEXT_PUBLIC_API_URL=https://app.example.com/api/v1 \
  --build-arg NEXT_PUBLIC_WS_URL=wss://app.example.com/ws \
  -t aiworkforce-frontend ./frontend

Verificación de correo y cuentas de prueba#

Dos funciones opcionales de acceso, las dos requieren AUTH_ENABLED=true. La verificación de correo exige un SMTP que funcione: con EMAIL_VERIFICATION=true y sin SMTP válido el backend se niega a arrancar, de modo que un servidor a medio configurar no deja a nadie fuera.

Las cuentas de prueba permiten usar la app sin registrarse; cada una tiene su propia organización y deja de funcionar sola.