Variables de entorno

Esta página enumera las variables destinadas a operadores que leen actualmente el backend, frontend y scripts de mantenimiento de Libre WebUI. Se omiten deliberadamente los indicadores internos exclusivos de pruebas.

Servidor backend

Variable	Predeterminado	Finalidad
`NODE_ENV`	`development`	Modo de ejecución
`PORT`	`3001` en desarrollo, `8080` en producción	Puerto HTTP del backend
`TRUST_PROXY`	sin definir (`0` en Helm)	Número exacto de saltos de proxy inverso de confianza para derivar la dirección del cliente
`CORS_ORIGIN`	orígenes locales de desarrollo	Orígenes permitidos del navegador, separados por comas
`SERVE_FRONTEND`	sin definir	Servir el frontend compilado desde el backend cuando sea `true`
`DOCKER_ENV`	sin definir	Activar comportamiento orientado a Docker cuando sea `true`
`DATA_DIR`	`backend/data`; `~/.libre-webui` en el CLI empaquetado	Directorio de datos persistentes
`PLATFORM_PREFLIGHT_TMP_DIR`	`backend/temp/preflight`; caché del usuario en el CLI	Espacio temporal para una copia privada de inspección DB/WAL; dimensiona para la base y su WAL
`PLUGIN_UPLOAD_TEMP_DIR`	`libre-webui-plugin-uploads` en el temporal del SO	Espacio temporal para subidas de plugins en curso
`PLUGINS_DIR`	`$DATA_DIR/plugins`	Directorio escribible de plugins instalados o personalizados
`BASE_URL`	`http://localhost:3001`	URL base para devoluciones OAuth predeterminadas
`LOG_LEVEL`	`info` (`warn` en pruebas)	Nivel de registro del backend
`LOG_FORMAT`	`text`	`json` activa registros estructurados de una línea con marcas, correlación y censura
`OTEL_EXPORTER_OTLP_ENDPOINT`	sin definir	Exportación opcional de telemetría JSON OTLP/HTTP; sin valor no sale telemetría
`OTEL_EXPORTER_OTLP_HEADERS`	sin definir	Cabeceras `key=value` al colector OTLP, separadas por comas (por ejemplo, autenticación)
`OTEL_SERVICE_NAME`	`libre-webui`	Atributo de recurso `service.name` en la telemetría exportada
`WEBUI_HOST`	bucle invertido; `0.0.0.0` en Docker	Dirección de escucha HTTP
`OPEN_BROWSER`	`true` al servir el frontend	Define `false` para impedir que se abra el navegador
`FULL_DOCUMENT_CONTEXT_MAX_TOKENS`	`32000`	Límite de tokens del modo de documento completo por chat (1000-2000000)
`GALLERY_RETENTION_DAYS`	sin definir (conservar siempre)	Eliminar mediante el programador medios de la galería más antiguos que estos días
`RECOVERY_DRILL_INTERVAL_HOURS`	sin definir (simulacros desactivados)	Ejecutar automáticamente un simulacro verificado cada N horas (perfil solo)
`RECOVERY_DRILL_HISTORY`	`60`	Entradas de historial de simulacros conservadas

Los inicios desde el código fuente anclan los valores relativos DATA_DIR, PLUGINS_DIR y PLATFORM_PREFLIGHT_TMP_DIR al directorio del backend, con independencia del directorio de la shell. Sin DATA_DIR —o con DATA_DIR=./data— los comandos desde la raíz y el backend usan backend/data. Por compatibilidad, una configuración existente DATA_DIR=./backend/data sigue seleccionando backend/backend/data; cámbiala solo durante una copia y migración deliberadas con el servicio detenido. Un perfil sin valor también usa el directorio histórico si es el único almacén. Si ambos contienen estado y no se elige uno, el inicio falla de forma segura en vez de adivinar, copiar o combinar.

Los lanzadores npx, npm global y Homebrew conservan los datos en ~/.libre-webui. Un DATA_DIR relativo explícito se resuelve desde el directorio del invocador y se convierte en absoluto antes de iniciar. Un PLUGINS_DIR relativo sigue la misma regla; si falta, los plugins permanecen en $DATA_DIR/plugins. El espacio de inspección usa una caché escribible fuera de los datos: ~/Library/Caches/libre-webui en macOS, %LOCALAPPDATA%\libre-webui en Windows o ${XDG_CACHE_HOME:-~/.cache}/libre-webui en otros sistemas. El servicio Homebrew fija el mismo directorio personal y usa var/libre-webui/preflight. Define PLATFORM_PREFLIGHT_TMP_DIR si la caché no admite la base más WAL. Docker y Helm usan /app/backend/data y /app/backend/temp/preflight con montajes separados.

Base de la plataforma

El perfil solo utiliza SQLite, blobs locales cifrados, vectores integrados cifrados, coordinación local y un trabajador duradero integrado. team utiliza PostgreSQL, blobs privados compatibles con S3, PGVector, Redis y un trabajador externo. La configuración de equipo falla de forma segura: todas las dependencias compartidas deben elegirse juntas.

Variable	Predeterminado	Finalidad
`LIBRE_PLATFORM_MODE`	`solo`	Seleccionar el perfil coherente `solo` o `team`
`DATABASE_BACKEND`	`sqlite`	Seleccionar `sqlite` o `postgres`
`DATABASE_URL`	sin definir	URL de PostgreSQL, obligatoria con `postgres`
`DATABASE_SSL_MODE`	`verify-full`	Política TLS: `disable`, `require` o `verify-full` con comprobación del host
`POSTGRES_MIGRATION_MODE`	`apply`	Ejecutar migraciones bajo bloqueo de líder, o `validate` para comprobar el esquema en lectura
`POSTGRES_POOL_MAX`	`10`	Conexiones máximas por proceso de aplicación o trabajador (1-100)
`POSTGRES_CONNECT_TIMEOUT_MS`	`5000`	Tiempo de conexión PostgreSQL (1-60000 ms)
`POSTGRES_IDLE_TIMEOUT_MS`	`30000`	Tiempo de inactividad de conexión (1-600000 ms)
`POSTGRES_STATEMENT_TIMEOUT_MS`	`30000`	Tiempo de sentencia PostgreSQL (1-600000 ms)
`POSTGRES_MIGRATION_LOCK_TIMEOUT_MS`	`60000`	Espera del bloqueo de migración (1-600000 ms)
`BLOB_STORE_BACKEND`	`local`	Seleccionar almacenamiento `local` cifrado o `s3` privado
`VECTOR_STORE_BACKEND`	`embedded` con SQLite	Seleccionar vectores `embedded` cifrados o `pgvector`
`COORDINATION_BACKEND`	`local` en solo; `redis` en team	Seleccionar coordinación local o Redis
`REDIS_URL`	sin definir	URL `redis:` o `rediss:`, obligatoria con Redis
`REDIS_KEY_PREFIX`	`libre`	Espacio de nombres de 1-64 caracteres para claves de coordinación
`REDIS_CONNECT_TIMEOUT_MS`	`5000`	Espera inicial de Redis, máximo 60 segundos
`JOB_WORKER_MODE`	`embedded` en solo; `external` en team	Ejecutar controladores en la aplicación o trabajador compartido
`RESOURCE_LEASE_TTL_MS`	`30000`	TTL del arrendamiento de recursos (5000-300000; el inicio falla fuera del intervalo)
`JOB_WORKER_CONCURRENCY`	`4`	Trabajos duraderos simultáneos por trabajador (1-32)
`CHAT_STREAM_EVENT_RETENTION_HOURS`	`24`	Horas de conservación de fragmentos de chat antes del barrido
`PLATFORM_EVENT_RETENTION_DAYS`	`30`	Días de conservación de eventos duraderos
`PLATFORM_JOB_RETENTION_DAYS`	`30`	Días de conservación de trabajos terminados no vitales
`LIBRE_SKIP_STARTUP_INTEGRITY_SCAN`	sin definir	`1` omite el análisis profundo de cifrado heredado en el siguiente inicio (salida de emergencia; normalmente en caché)
`STORAGE_ENCRYPTION_KEYS`	sin definir	Mapa JSON secreto; debe incluir `legacy` que coincida con `ENCRYPTION_KEY`
`STORAGE_ENCRYPTION_ACTIVE_KEY_ID`	sin definir	ID de clave para nuevas escrituras de blobs locales y vectores integrados
`BLOB_QUOTA_BYTES_PER_USER`	`10737418240`	Máximo persistente de bytes de blob sin cifrar por propietario
`BLOB_QUOTA_RESERVATION_TTL_MS`	`3600000`	Vida de una reserva abandonada (mínimo 60000 ms)
`S3_BUCKET`	sin definir	Bucket privado compatible con S3, obligatorio con `s3`
`S3_REGION`	sin definir	Región S3, obligatoria con `s3`
`S3_ENDPOINT`	predeterminado del proveedor	Endpoint HTTP(S) absoluto opcional para MinIO u otro servicio compatible
`S3_ACCESS_KEY_ID`	cadena de credenciales del SDK	Clave de acceso S3 explícita opcional
`S3_SECRET_ACCESS_KEY`	cadena de credenciales del SDK	Obligatoria al definir una clave explícita
`S3_SESSION_TOKEN`	sin definir	Token opcional que acompaña credenciales explícitas
`S3_FORCE_PATH_STYLE`	`false`	Define `true` para servicios que requieren direccionamiento por ruta
`S3_BLOB_PREFIX`	`libre/blobs`	Prefijo opaco de claves del bucket propiedad de Libre

Sin mapa de claves versionado, los adaptadores usan ENCRYPTION_KEY como ID legacy; si tampoco existe, leen ${DATA_DIR}/.encryption_key sin generarlo ni modificarlo. La configuración y el archivo deben coincidir. Si se introduce un mapa con una clave antigua, consérvala bajo legacy hasta reescribir o volver a envolver y verificar todos los objetos y vectores. Conflictos, permisos inseguros, enlaces simbólicos y claves ausentes fallan de forma segura.

Redis coordina; no es persistencia canónica. Elegirlo solo no hace seguros SQLite, archivos locales u otro estado de proceso entre réplicas. En team, límites HTTP, conexiones Chat/WebSocket, trabajos STT/TTS/audio, importaciones y terminales de Work utilizan admisión compartida mediante Redis. Las capacidades se aplican a todas las réplicas. Los fallos de admisión o renovación devuelven 503 o abortan; Libre nunca recurre a un contador local. Consulta Base de la plataforma.

Compose team y Helm transmiten todos los selectores y ajustes a aplicación y trabajador. En Helm, los no secretos están bajo env; define secrets.redisUrl, secrets.databaseUrl y secrets.storageEncryptionKeys para conexiones y claves. Los pools son por proceso: reserva al menos (replicaCount + worker.replicaCount) * POSTGRES_POOL_MAX conexiones más margen. Mantén DATABASE_SSL_MODE=verify-full para PostgreSQL remoto; solo Compose team selecciona disable porque su escucha está aislada. Helm team exige secrets.jwtSecret estable compartido por todos los Pods; sin él cada proceso generaría material local. S3 recibe claves opacas y texto cifrado; las URL no se almacenan en metadatos.

Los archivos integrados de solo y team conservan ajustes de pool y esperas, espera de Redis, cuotas de blobs, selectores y direccionamiento S3 en configuración protegida, firmada y cifrada. Una restauración limpia puede publicar los valores necesarios sin ponerlos en metadatos sin cifrar.

Los pares aplicación/trabajador reciben los mismos OLLAMA_BASE_URL, OLLAMA_TIMEOUT, OLLAMA_LONG_OPERATION_TIMEOUT y OLLAMA_MAX_CONTEXT. Las llamadas de embeddings, chats duraderos y Work se ejecutan en el trabajador, así que no deben divergir. Ambos puntos de entrada analizan los tres valores numéricos como enteros positivos completos en base 10 antes de crear o conectar estado. Valores como 300000ms, notación exponencial/hexadecimal, fuera de rango o una espera larga menor fallan al iniciar.

Helm restringe TRUST_PROXY a un entero de 0 a 16 y solo lo envía a Pods HTTP. Mantén 0 para tráfico directo; define el recuento fijo exacto para la cadena y nunca true. Un valor incorrecto agrupa clientes o confía en una dirección proporcionada por ellos.

PostgreSQL exige compatibilidad exacta. App y trabajador usan Recreate; drena y termina todos los Pods antiguos antes de actualizar y deja que un proceso migre bajo el bloqueo asesor. No mezcles binarios ni prometas una actualización sin interrupción. Revertir significa restaurar el archivo verificado anterior en destinos limpios antes de iniciar el binario antiguo.

Una aplicación team activa exige worker.replicaCount >= 1; Helm rechaza una aplicación viva sin trabajador. Pon aplicación y trabajador a cero para suspensión completa. Aplicación a cero y trabajador positivo es modo deliberado de drenaje/recuperación y sigue consumiendo la cola sin servir web.

Auxiliar de copias privadas

Estas variables configuran deploy/private/libre-webui-backup y las lee el script de mantenimiento, no la aplicación:

Variable	Predeterminado	Finalidad
`LIBRE_WEBUI_STACK_DIR`	`/opt/libre-webui`	Directorio del archivo Compose privado
`LIBRE_WEBUI_BACKUP_DIR`	`/var/backups/libre-webui`	Directorio protegido de copias y bloqueo
`LIBRE_WEBUI_BACKUP_RETENTION_DAYS`	`14`	Edad de eliminación de copias completadas
`LIBRE_WEBUI_CONTAINER_NAME`	`libre-webui`	Contenedor desplegado que inspeccionar
`LIBRE_WEBUI_BACKUP_KEY_DIR`	`/etc/libre-webui/backup-keys`	Directorio de claves de cifrado y firma
`LIBRE_WEBUI_RESTORE_IMAGE`	obligatorio para restaurar	ID o resumen inmutable revisado de imagen Libre
`LIBRE_WEBUI_RESTORE_CONFIG_DIR`	ruta por volumen bajo `/etc/libre-webui/restored`	Directorio nuevo para la configuración recuperada

La unidad systemd carga anulaciones del archivo opcional /etc/libre-webui/backup.env, propiedad de root. Ponlo en modo 0600. Allí se pueden definir directorios, retención, contenedor y claves. El aislamiento de la unidad solo permite escribir bajo el directorio predeterminado. Un LIBRE_WEBUI_BACKUP_DIR personalizado requiere añadir exactamente ese directorio precreado a ReadWritePaths= en una anulación; consulta Despliegue remoto privado.

Autenticación y seguridad

Variable	Predeterminado	Finalidad
`ENABLE_SIGNUP`	`false`	Permitir registro tras el primer administrador local
`JWT_SECRET`	generado/reserva en desarrollo	Secreto de firma JWT; definir expresamente en producción
`JWT_EXPIRES_IN`	`7d`	Vida del token de sesión
`ENCRYPTION_KEY`	generada automáticamente	Clave hexadecimal de 64 caracteres
`DEBUG_ENCRYPTION`	sin definir	Registrar depuración del cifrado
`TURNSTILE_SITE_KEY`	sin definir	Clave de sitio Cloudflare Turnstile
`TURNSTILE_SECRET_KEY`	sin definir	Clave secreta de verificación
`TURNSTILE_EXPECTED_HOSTNAME`	host de `BASE_URL`	Host exigido en la respuesta de Cloudflare
`MFA_REQUIRED_MODE`	sin definir (interruptor, `optional`)	Fijar política de dos factores a `optional` o `required`
`WEBAUTHN_RP_ID`	host de la solicitud	ID fijo de parte dependiente para llaves tras varios hosts
`VAPID_PUBLIC_KEY`	generada y almacenada cifrada	Fijar clave pública Web Push VAPID (punto P-256 base64url)
`VAPID_PRIVATE_KEY`	generada y almacenada cifrada	Fijar clave privada Web Push VAPID (escalar base64url)
`VAPID_SUBJECT`	`mailto:admin@localhost`	Contacto en autorizaciones Web Push firmadas

Turnstile solo se activa con ambas claves.

ENABLE_SIGNUP=false sigue permitiendo el primer administrador de una base vacía y bloquea las cuentas posteriores. Protege una ruta de arranque remota con una frontera de identidad externa antes del primer inicio.

Cada JWT está ligado a una sesión del servidor (afirmación sid), por lo que cerrar o revocar desde Ajustes → Sesiones invalida el token en todas las réplicas y cierra WebSockets. La retención de auditoría es configurable:

Variable	Predeterminado	Finalidad
`AUDIT_RETENTION_DAYS`	`180`	Días de retención del registro de seguridad

Inicio de sesión único OIDC genérico

Puede usarse cualquier proveedor OpenID Connect con documento de descubrimiento. El flujo utiliza PKCE (S256), estado CSRF y un nonce verificado dentro del token ID con firma comprobada. Las identidades se vinculan mediante la afirmación estable sub.

Variable	Predeterminado	Finalidad
`OIDC_ISSUER_URL`	sin definir	URL del emisor; descubrimiento en `<issuer>/.well-known/openid-configuration`
`OIDC_CLIENT_ID`	sin definir	ID de cliente OAuth registrado
`OIDC_CLIENT_SECRET`	sin definir	Secreto de cliente OAuth
`OIDC_DISPLAY_NAME`	`Single Sign-On`	Etiqueta del botón de inicio
`OIDC_SCOPES`	`openid profile email`	Ámbitos solicitados
`OIDC_CALLBACK_URL`	`BASE_URL` + ruta de devolución OIDC	URI de redirección registrado
`OIDC_ALLOWED_EMAIL_DOMAINS`	sin definir	Lista por comas; exige correo verificado en uno de los dominios
`OIDC_GROUP_CLAIM`	`groups`	Afirmación del token que contiene grupos
`OIDC_ADMIN_GROUPS`	sin definir	Lista por comas; el rol admin sigue la pertenencia en cada inicio
`OIDC_SYNC_GROUPS`	`false`	`true` reconcilia grupos de Libre con la afirmación en cada inicio

OIDC solo se activa si están presentes la URL del emisor, el ID y el secreto. Un correo ya usado por una cuenta local no vinculada se rechaza en vez de combinarse, y la creación sigue respetando ENABLE_SIGNUP.

La admisión WebSocket de Chat se puede ajustar sin debilitar la autenticación:

Variable	Predeterminado	Finalidad
`CHAT_WS_MAX_PAYLOAD_BYTES`	10 MiB	Tamaño máximo aceptado de mensaje WebSocket
`CHAT_WS_MAX_MESSAGES_PER_MINUTE`	`120`	Tope de mensajes por conexión
`CHAT_WS_MAX_ACTIVE_GENERATIONS_PER_USER`	`4`	Generaciones de proveedor permitidas por cuenta
`CHAT_WS_MAX_CONNECTIONS_PER_USER`	`5`	Sockets autenticados simultáneos por cuenta
`WEBSOCKET_TICKET_TTL_MS`	`30000`	Vida del ticket Chat/Work de un uso, máximo 60 segundos

El navegador canjea Authorization por un ticket opaco y solo pone ese valor breve en la URL de WebSocket. Los tickets son de un uso, ligados al protocolo y sesión y guardados como hashes, evitando tokens duraderos en registros del proxy. Con CORS_ORIGIN o BASE_URL, el Origin debe coincidir. Define al menos uno para acceso remoto; sin ambos el filtro es permisivo por compatibilidad local. Las actualizaciones sin origen se admiten para Electron y otros clientes, pero exigen ticket y las mismas comprobaciones de cuenta, Work y tarea. Trata el ticket como frontera y limita el acceso con TLS, cortafuegos y proxy.

OAuth

Variable	Finalidad
`GITHUB_CLIENT_ID`	ID de cliente OAuth de GitHub
`GITHUB_CLIENT_SECRET`	Secreto OAuth de GitHub
`GITHUB_CALLBACK_URL`	Anulación de devolución de GitHub
`HUGGINGFACE_CLIENT_ID`	ID de cliente OAuth de Hugging Face
`HUGGINGFACE_CLIENT_SECRET`	Secreto OAuth de Hugging Face
`HUGGINGFACE_CALLBACK_URL`	Anulación de devolución de Hugging Face

Sin URL de devolución, Libre WebUI las construye desde BASE_URL.

Ollama

Variable	Predeterminado	Finalidad
`OLLAMA_BASE_URL`	`http://localhost:11434`	URL base de la API Ollama
`OLLAMA_TIMEOUT`	`300000`	Espera de solicitud normal (1,000-3,600,000 ms)
`OLLAMA_LONG_OPERATION_TIMEOUT`	`900000`	Espera larga (1,000-3,600,000 ms y no menor que `OLLAMA_TIMEOUT`)
`OLLAMA_MAX_CONTEXT`	`32768`	Contexto máximo adoptado automáticamente (128-2,097,152 tokens)

Búsqueda web

Variable	Predeterminado	Finalidad
`SEARXNG_URL`	sin definir	Endpoint SearXNG predeterminado; un administrador aún debe activarlo en Ajustes > Búsqueda

Libre Claw

Variable	Predeterminado	Finalidad
`LIBRE_CLAW_BASE_URL`	`http://127.0.0.1:8766`	URL opcional del daemon Libre Claw
`LIBRE_CLAW_TIMEOUT_MS`	`30000`	Espera HTTP de Libre Claw

Entorno de Work

Estas variables configuran Work en el equipo o clúster que ejecuta el backend. Docker es predeterminado; Helm elige Kubernetes con work.enabled=true.

Variable	Predeterminado	Finalidad
`WORK_RUNTIME_IMAGE`	`node:22.22-bookworm@sha256:2d178f2785b96dfbf62a416ca2e40f50e30150b4ff3320d706f0d96e90600eb3`	Imagen fijada para entornos de Work
`WORK_DOCKER_COMMAND`	`docker`	CLI Docker disponible al proceso
`WORK_COMMAND_TIMEOUT_MS`	`120000`	Espera predeterminada; una herramienta puede pedir `600000` ms
`WORK_MAX_OUTPUT_CHARS`	`50000`	Límite de stdout/stderr capturado por flujo
`WORK_MAX_AGENT_ROUNDS`	`48`	Presupuesto de rondas modelo/herramienta por ejecución
`WORK_STATUS_BLURB_MODEL`	`1`	Define `0` para omitir la solicitud al modelo que escribe el estado del agente en la barra lateral tras una ejecución
`WORK_MEMORY_LIMIT`	`2g`	Memoria por contenedor
`WORK_CPU_LIMIT`	`2`	CPU por contenedor
`WORK_PIDS_LIMIT`	`256`	Procesos por contenedor
`WORK_PREVIEW_PORT`	`4173`	Puerto que usa la vista previa dentro del contenedor
`WORK_PREVIEW_BIND`	`127.0.0.1`	Interfaz del host donde se publica la vista; los despliegues con Compose en Docker Engine nativo deben usar una interfaz de puente no pública y alcanzable
`WORK_DOCKER_PUBLISHED_HOST`	valor predeterminado de la app: igual que `WORK_PREVIEW_BIND`; valor predeterminado de Compose: `host.docker.internal`	Host/IP visto por el backend para puertos publicados
`WORK_COMPUTER_SCREEN_PORT`	`6080`	Puerto del puente de pantalla Work Computer (websockify) en entornos gráficos
`WORK_COMPUTER_AUDIO_PORT`	`6081`	Puerto del puente de audio (websockify → PulseAudio monitor)
`WORK_MAX_ACTIVE_RUNTIMES_GLOBAL`	`3`	Tareas simultáneas con entorno en la instancia
`WORK_MAX_ACTIVE_RUNTIMES_PER_USER`	`2`	Tareas simultáneas con entorno por usuario
`WORK_MAX_TASKS_GLOBAL`	`500`	Máximo de tareas persistentes en la instancia
`WORK_MAX_TASKS_PER_USER`	`100`	Máximo por administrador
`WORK_NETWORK_NAME`	`libre-webui-work`	Red puente administrada para tareas con red
`WORK_RUN_LEASE_WAIT_MS`	`60000`	Espera del arrendamiento compartido antes de informar conflicto de réplica (team)
`WORK_RUNTIME_DNS`	sin definir	IP de resolutores forzadas, separadas por comas
`WORK_DOCKER_SOCKET`	`DOCKER_HOST` si `unix://` o `tcp://`, si no `/var/run/docker.sock`	Endpoint de Docker Engine para terminales y diagnóstico
`WORK_TERMINAL_MAX_SESSIONS_PER_TASK`	`2`	Terminales de navegador simultáneos por tarea
`WORK_TERMINAL_IDLE_TIMEOUT_MS`	`900000`	Espera de inactividad antes de cerrar
`WORK_RUNTIME_IDLE_TIMEOUT_MS`	`0` (deshabilitado)	Detener un entorno tras esta inactividad, incluidas vistas
`WORK_HOST_WORKSPACES_ENABLED`	`false`	Permitir carpeta del host en vez de volumen
`WORK_HOST_WORKSPACE_ROOTS`	directorio personal del usuario del servidor	Raíces separadas por `:` en las que debe estar el espacio
`WORK_RUNTIME_BACKEND`	`docker`	Backend: `docker` o `kubernetes`
`WORK_K8S_NAMESPACE`	`libre-webui-work`	Namespace de Pods y PVC de entornos
`WORK_K8S_STORAGE_CLASS`	predeterminado del clúster	StorageClass de PVC
`WORK_K8S_WORKSPACE_SIZE`	`5Gi`	Tamaño de PVC por tarea (cuota real)
`WORK_K8S_POD_READY_TIMEOUT_MS`	`900000`	Espera hasta Running, incluidas descargas
`WORK_K8S_POD_GONE_TIMEOUT_MS`	`60000`	Espera hasta que desaparezca un Pod eliminado
`AGENT_CLI_MODELS_ENABLED`	sin definir (interruptor, desactivado)	Fijar Agents; sin valor queda al interruptor, desactivado por defecto
`TOOLS_ACCESS_MODE`	sin definir (interruptor, solo administradores)	Fijar herramientas a `admins` o `all-users` y bloquear el interruptor
`STT_ACCESS_MODE`	sin definir (interruptor, todos)	Fijar voz a texto a `admins` o `all-users`
`TTS_ACCESS_MODE`	sin definir (interruptor, todos)	Fijar texto a voz a `admins` o `all-users`
`VOICE_MODE_ACCESS_MODE`	sin definir (interruptor, todos)	Fijar el modo manos libres a `admins` o `all-users`
`VOICE_CLONING_ACCESS_MODE`	sin definir (interruptor, todos)	Fijar clonación a `admins` o `all-users`
`TOOLS_PRIVATE_NETWORK_ALLOWLIST`	sin definir	Nombres exactos que herramientas y webhooks pueden resolver a direcciones privadas; separados por comas y fijados
`AGENT_CLI_TIMEOUT_MS`	`600000`	Tiempo de ejecución de un CLI antes de terminarlo
`CODEX_OAUTH_MODELS_ENABLED`	`true`	Ofrecer el proveedor Codex (ChatGPT) a administradores
`CODEX_HOME`	`~/.codex`	Ubicación de credenciales del CLI Codex (`auth.json`)

Los binarios CLI y credenciales OAuth Codex son locales al nodo. Solo se admiten en solo, donde descubrimiento y ejecución ven el mismo entorno. Team ejecuta chats duraderos en un trabajador y exige AGENT_CLI_MODELS_ENABLED=false y CODEX_OAUTH_MODELS_ENABLED=false; el inicio rechaza otros valores en vez de anunciar un proveedor de una sola réplica. Usa Ollama o un plugin con credenciales compartidas.

En Docker, una carpeta del host se monta en /workspace y la tarea lee y escribe directamente. Kubernetes la rechaza. Es una reducción deliberada del aislamiento: mantén WORK_HOST_WORKSPACES_ENABLED apagado y WORK_HOST_WORKSPACE_ROOTS estrecho. Se resuelven enlaces antes de comprobar raíces y se rechazan .ssh, .gnupg, .aws y .config.

Los modelos CLI exponen agentes instalados (claude, codex) como modelos de chat para usar suscripciones sin clave. Solo los ven administradores; el CLI se ejecuta como usuario del servidor y hereda sus credenciales. Equivale a dar acceso de shell a esos agentes.

Las tareas Docker con red se conectan a WORK_NETWORK_NAME, con comunicación entre contenedores desactivada. WORK_RUNTIME_DNS es el punto de política: usa un resolutor filtrante; se rechazan valores no IPv4/IPv6. DNS no limita salida por IP directa; añade cortafuegos. Kubernetes usa NetworkPolicies y work.networkPolicy.blockedEgressCidrs.

El terminal y diagnóstico hablan con Docker Engine. Siguen WORK_DOCKER_SOCKET, luego DOCKER_HOST —socket unix:// o endpoint tcp:// HTTP como un proxy (consulta docker-compose.socket-proxy.yml)— y finalmente /var/run/docker.sock. Un valor no compatible (ssh:// o tcp:// con DOCKER_TLS_VERIFY) marca terminal y diagnóstico no disponibles; Work sigue por el CLI. Kubernetes usa exec y no Docker.

Work lee valores al iniciar. El puerto de vista es interno; Libre WebUI lo publica en un puerto de bucle invertido dinámico.

Fija la imagen a una versión o resumen revisado. Aumentar concurrencia o recursos amplía lo que consumen ejecuciones autónomas. WORK_MAX_AGENT_ROUNDS se aplica igual a Ollama y plugins. El presupuesto de herramientas es max(128, WORK_MAX_AGENT_ROUNDS × 8). Al agotarlo, Work pide una entrega final sin herramientas y termina en needs_input, no con error bruto ni falso éxito. Un seguimiento continúa en el mismo espacio. La salida persistente tiene un límite aparte de unas 20,000 fuentes más marcador.

Estas variables ajustan un entorno ya accesible. Compose de instancia única lo activa montando el socket. Dos variables controlan el cableado:

Variable	Predeterminado	Finalidad
`DOCKER_GID`	`0`	Grupo del socket añadido al usuario contenedor
`DOCKER_SOCKET`	`/var/run/docker.sock`	Ruta del socket del host que montar

DOCKER_GID debe ser el grupo visto dentro de un contenedor; macOS informa otro. Compose team no monta socket y mantiene Work no disponible hasta añadir docker-compose.team.work.yml. Esa capa proporciona el mismo proxy filtrado a aplicación y trabajador, nunca socket ni grupo. El proxy limita secciones, pero crear contenedores sigue siendo una credencial de control del host; usa un daemon dedicado o sin root para un límite más fuerte. Helm nunca monta socket; activa Pod/PVC con work.enabled=true.

solo debe tener cero o una réplica porque usa SQLite, archivos y coordinación local. Helm acepta cero para suspender y rechaza más o autoescalado. team completo admite varias réplicas y trabajador gracias a PostgreSQL, S3, PGVector y Redis. Los Pods de Work escalan aparte y el trabajador recibe imagen, StorageClass y límites work.env iguales.

Compose también acepta WEBUI_BIND_ADDRESS (predeterminado 127.0.0.1) y WEBUI_PORT (8080). Mantén el bucle salvo que una LAN fiable o proxy de host deba llegar al puerto.

Descubrimiento de modelos

El catálogo se redescubre cuando falta o caduca para reflejar modelos actuales:

Variable	Predeterminado	Finalidad
`PLUGIN_MODEL_DISCOVERY_TTL_MS`	`21600000` (6 h)	Edad para actualizar al leer la lista
`PLUGIN_MODEL_DISCOVERY_RETRY_MS`	`600000` (10 min)	Intervalo mínimo entre intentos
`PLUGIN_MODEL_DISCOVERY_REFRESH_DEADLINE_MS`	`3000`	Tiempo que espera una respuesta por actualizaciones

Una actualización que supera el plazo termina y se sirve después. Actualizar modelos siempre contacta al proveedor.

Claves de plugins de proveedores

Las claves de entorno pueden ser valores de despliegue:

Variable	Proveedor
`OPENAI_API_KEY`	OpenAI y OpenAI TTS
`ANTHROPIC_API_KEY`	Anthropic
`GROQ_API_KEY`	Groq
`GEMINI_API_KEY`	Google Gemini
`MISTRAL_API_KEY`	Mistral
`OPENROUTER_API_KEY`	OpenRouter
`KIMI_API_KEY`	Kimi Code de Moonshot AI
`GITHUB_API_KEY`	GitHub Models
`HUGGINGFACE_API_KEY`	API de Hugging Face configuradas
`ELEVENLABS_API_KEY`	ElevenLabs TTS
`COMFYUI_API_KEY`	Despliegues ComfyUI que exigen clave

Los usuarios también pueden guardar credenciales. Las claves de entorno solo se usan con el enrutamiento de una definición incluida no sombreada. Las importadas, escribibles que reutilizan ID o rutas personalizadas exigen credencial de la cuenta; Libre no adjunta la de entorno ni la expone. La confianza procede del hash compilado del manifiesto, por lo que rutas compartidas siguen siendo compatibles sin confiar en un archivo modificado.

Las claves guardadas se vinculan a definición, fuente, autenticación y enrutamiento. Hay que guardarlas de nuevo tras cambiar el destino. Las antiguas no vinculadas solo se aceptan para una definición incluida exacta y se vinculan al primer uso.

En inicios desde fuente, PLUGINS_DIR relativo se resuelve desde el backend; el lanzador empaquetado convierte un valor explícito desde el invocador. Libre también lee backend/plugins y ubicaciones históricas. Mueve definiciones a $DATA_DIR/plugins; recuperación las marca como estado externo y bloquea una instantánea solo de volúmenes mientras existan. Directorios y JSON deben ser entradas físicas; no se siguen enlaces simbólicos.

Frontend

Variable	Predeterminado	Finalidad
`VITE_API_BASE_URL`	proxy de desarrollo del mismo origen o API de producción	URL base de la API
`VITE_WS_BASE_URL`	inferido de la API	Base absoluta `ws:`/`wss:` para Chat y Work
`VITE_APP_VERSION`	versión inyectada por Vite	Versión mostrada
`VITE_DEMO_MODE`	`false`	Activa simulaciones con `true`
`VITE_API_TIMEOUT`	`300000`	Espera de API en milisegundos
`VITE_BACKEND_URL`	`http://localhost:3001`	Usada por auxiliares de autenticación
`VITE_DEBUG_VERBOSE`	sin definir	Activa registros detallados en desarrollo
`VITE_LOG_LEVEL`	sin definir	Anula el nivel de registro
`ELECTRON_BUILD`	sin definir	Activa comportamiento de Electron con `true`

VITE_WS_BASE_URL anula todos los valores de WebSocket para Chat y terminal Work. Puede incluir prefijo de proxy, pero debe ser URL absoluta ws: o wss: sin credenciales, consulta ni fragmento. Sin valor, clientes Electron file: usan ws://localhost:3001; los navegadores derivan de VITE_API_BASE_URL y luego del origen del navegador. Vite reenvía el origen de desarrollo al backend en el puerto 3001.

Scripts de mantenimiento

Variable	Finalidad
`CHANGELOG_AI`	Define `0` para desactivar borradores asistidos
`CHANGELOG_AI_MODEL`	Modelo Ollama para versiones/registros
`CHANGELOG_AI_TIMEOUT_MS`	Espera de generación en milisegundos

Ejemplo:

CHANGELOG_AI_MODEL=glm-5.2:cloud npm run changelog
CHANGELOG_AI=0 npm run release:minor

Ejemplo de producción

NODE_ENV=production
PORT=3001
SERVE_FRONTEND=true
DATA_DIR=/data/libre-webui
CORS_ORIGIN=https://librewebui.example
BASE_URL=https://librewebui.example

JWT_SECRET=replace-with-a-long-random-secret
ENCRYPTION_KEY=replace-with-64-hex-characters
ENABLE_SIGNUP=false

OLLAMA_BASE_URL=http://ollama:11434
OLLAMA_TIMEOUT=300000
OLLAMA_LONG_OPERATION_TIMEOUT=900000
OLLAMA_MAX_CONTEXT=32768

TURNSTILE_SITE_KEY=...
TURNSTILE_SECRET_KEY=...
TURNSTILE_EXPECTED_HOSTNAME=librewebui.example

Servidor backend​

Base de la plataforma​

Auxiliar de copias privadas​

Autenticación y seguridad​

Inicio de sesión único OIDC genérico​

OAuth​

Ollama​

Búsqueda web​

Libre Claw​

Entorno de Work​

Descubrimiento de modelos​

Claves de plugins de proveedores​

Frontend​

Scripts de mantenimiento​

Ejemplo de producción​

Documentación relacionada​