Variáveis de ambiente
Esta página lista as variáveis destinadas a operadores que são lidas pelo backend, frontend e scripts de manutenção atuais. Canários internos exclusivos de testes são omitidos.
Servidor backend
| Variável | Padrão | Finalidade |
|---|---|---|
NODE_ENV | development | Modo do runtime |
PORT | 3001 em desenvolvimento, 8080 em produção | Porta HTTP do backend |
TRUST_PROXY | não definido (0 no Helm) | Número exato de saltos de proxy confiáveis usado para obter o endereço do cliente |
CORS_ORIGIN | origens locais de desenvolvimento | Origens permitidas, separadas por vírgula |
SERVE_FRONTEND | não definido | Servir o frontend compilado quando true |
DOCKER_ENV | não definido | Ativar comportamento voltado ao Docker quando true |
DATA_DIR | backend/data; ~/.libre-webui no CLI empacotado | Diretório de dados persistentes |
PLATFORM_PREFLIGHT_TMP_DIR | backend/temp/preflight; cache do usuário no CLI | Área de trabalho para inspeção privada de DB/WAL; dimensione para ambos |
PLUGIN_UPLOAD_TEMP_DIR | libre-webui-plugin-uploads no temporário do SO | Área para uploads em andamento |
PLUGINS_DIR | $DATA_DIR/plugins | Diretório gravável de plugins instalados/personalizados |
BASE_URL | http://localhost:3001 | URL base usada nos callbacks OAuth |
LOG_LEVEL | info (warn em testes) | Nível do log |
LOG_FORMAT | text | json ativa logs estruturados em uma linha com horários, IDs e redação |
OTEL_EXPORTER_OTLP_ENDPOINT | não definido | Exportação opcional OTLP/HTTP JSON; ausente significa que nada sai do processo |
OTEL_EXPORTER_OTLP_HEADERS | não definido | Cabeçalhos key=value separados por vírgula enviados ao coletor |
OTEL_SERVICE_NAME | libre-webui | Atributo service.name da telemetria |
WEBUI_HOST | loopback; 0.0.0.0 no Docker | Endereço de escuta HTTP |
OPEN_BROWSER | true ao servir o frontend | Defina false para não abrir o navegador |
FULL_DOCUMENT_CONTEXT_MAX_TOKENS | 32000 | Proteção de tokens no modo de documento completo (1000-2000000) |
GALLERY_RETENTION_DAYS | não definido (manter para sempre) | Excluir mídia mais antiga pelo agendador |
RECOVERY_DRILL_INTERVAL_HOURS | não definido (simulações desativadas) | Executar simulação verificada a cada N horas (solo) |
RECOVERY_DRILL_HISTORY | 60 | Entradas de histórico retidas |
Execuções pelo código-fonte ancoram DATA_DIR, PLUGINS_DIR e PLATFORM_PREFLIGHT_TMP_DIR relativos no diretório do backend, independentemente do shell. Com DATA_DIR ausente ou DATA_DIR=./data, comandos usam backend/data. Por compatibilidade, DATA_DIR=./backend/data continua selecionando backend/backend/data; altere somente em uma migração parada e com backup. Sem valor, o perfil também usa o diretório histórico se for o único armazenamento. Se ambos contiverem estado e nenhum for escolhido, a inicialização falha em vez de adivinhar, copiar ou mesclar.
Os executores npx, npm global e Homebrew preservam em ~/.libre-webui. Um DATA_DIR relativo explícito é resolvido do diretório do chamador e convertido em absoluto antes do backend. PLUGINS_DIR relativo segue a mesma regra; ausente, permanece em $DATA_DIR/plugins. A área de inspeção usa cache gravável fora dos dados: ~/Library/Caches/libre-webui no macOS, %LOCALAPPDATA%\libre-webui no Windows ou ${XDG_CACHE_HOME:-~/.cache}/libre-webui nos demais. O serviço Homebrew usa Homebrew var/libre-webui/preflight. Defina PLATFORM_PREFLIGHT_TMP_DIR se não couber banco e WAL. Docker e Helm usam /app/backend/data e /app/backend/temp/preflight em montagens separadas.
Fundação da plataforma
O perfil solo usa SQLite, blobs e vetores locais criptografados, coordenação local e worker durável embutido. team usa PostgreSQL, blobs S3 privados, PGVector, Redis e worker externo. A configuração team falha de forma segura se as dependências compartilhadas não forem selecionadas juntas.
| Variável | Padrão | Finalidade |
|---|---|---|
LIBRE_PLATFORM_MODE | solo | Selecionar perfil coerente solo ou team |
DATABASE_BACKEND | sqlite | Selecionar sqlite ou postgres |
DATABASE_URL | não definido | URL PostgreSQL, obrigatória com postgres |
DATABASE_SSL_MODE | verify-full | Política TLS: disable, require ou verify-full com verificação de host |
POSTGRES_MIGRATION_MODE | apply | Executar migrações sob lock do líder ou validate para validar sem gravar |
POSTGRES_POOL_MAX | 10 | Conexões máximas por processo (1-100) |
POSTGRES_CONNECT_TIMEOUT_MS | 5000 | Timeout de conexão (1-60000 ms) |
POSTGRES_IDLE_TIMEOUT_MS | 30000 | Timeout ocioso (1-600000 ms) |
POSTGRES_STATEMENT_TIMEOUT_MS | 30000 | Timeout de instrução (1-600000 ms) |
POSTGRES_MIGRATION_LOCK_TIMEOUT_MS | 60000 | Espera pelo lock de migração (1-600000 ms) |
BLOB_STORE_BACKEND | local | Armazenamento local criptografado ou s3 privado |
VECTOR_STORE_BACKEND | embedded com SQLite | Vetores embedded criptografados ou pgvector |
COORDINATION_BACKEND | local em solo; redis em team | Coordenação local ou Redis |
REDIS_URL | não definido | URL redis: ou rediss:, obrigatória com Redis |
REDIS_KEY_PREFIX | libre | Namespace de 1-64 caracteres |
REDIS_CONNECT_TIMEOUT_MS | 5000 | Timeout inicial, máximo 60 segundos |
JOB_WORKER_MODE | embedded em solo; external em team | Executar manipuladores no app ou worker compartilhado |
RESOURCE_LEASE_TTL_MS | 30000 | TTL de concessão de recursos (5000-300000; fora da faixa falha) |
JOB_WORKER_CONCURRENCY | 4 | Trabalhos simultâneos por worker (1-32) |
CHAT_STREAM_EVENT_RETENTION_HOURS | 24 | Horas de retenção dos segmentos de chat |
PLATFORM_EVENT_RETENTION_DAYS | 30 | Dias de retenção de eventos |
PLATFORM_JOB_RETENTION_DAYS | 30 | Dias de retenção de trabalhos concluídos |
LIBRE_SKIP_STARTUP_INTEGRITY_SCAN | não definido | 1 ignora uma inspeção profunda na próxima inicialização |
STORAGE_ENCRYPTION_KEYS | não definido | Mapa JSON secreto; deve incluir legacy igual a ENCRYPTION_KEY |
STORAGE_ENCRYPTION_ACTIVE_KEY_ID | não definido | ID para novas gravações de blobs e vetores |
BLOB_QUOTA_BYTES_PER_USER | 10737418240 | Máximo de bytes em texto simples por proprietário |
BLOB_QUOTA_RESERVATION_TTL_MS | 3600000 | Vida de reserva abandonada (mínimo 60000 ms) |
S3_BUCKET | não definido | Bucket privado, obrigatório com s3 |
S3_REGION | não definido | Região, obrigatória com s3 |
S3_ENDPOINT | padrão do provedor | Endpoint HTTP(S) absoluto opcional para MinIO |
S3_ACCESS_KEY_ID | cadeia de credenciais do SDK | Chave explícita opcional |
S3_SECRET_ACCESS_KEY | cadeia de credenciais do SDK | Obrigatória quando a chave explícita está definida |
S3_SESSION_TOKEN | não definido | Token opcional |
S3_FORCE_PATH_STYLE | false | true para serviços que exigem path-style |
S3_BLOB_PREFIX | libre/blobs | Prefixo opaco de chave do bucket |
Sem mapa versionado, os adaptadores usam ENCRYPTION_KEY como ID legacy; sem ela, leem ${DATA_DIR}/.encryption_key sem gerar nem modificar. Configuração explícita e arquivo devem coincidir. Ao introduzir mapa com chave antiga, mantenha-a sob legacy até regravar ou reencapsular e verificar todos os objetos. Conflitos, permissões inseguras, symlinks e chaves ausentes falham de forma segura.
Redis é coordenação, não persistência canônica. Selecioná-lo sozinho não torna SQLite ou arquivos seguros entre réplicas. Em team, limites HTTP, conexões, trabalho STT/TTS/áudio, importações e terminais Work usam admissão compartilhada. Capacidades valem entre réplicas. Falhas retornam 503 ou abortam a operação; não há fallback local. Consulte Fundação da plataforma.
Os perfis team do Compose e Helm encaminham todos os seletores e ajustes para aplicação e worker. No Helm, seletores não secretos ficam em env; conexões e chaves em secrets.redisUrl, secrets.databaseUrl e secrets.storageEncryptionKeys. Os pools são por processo: reserve (replicaCount + worker.replicaCount) * POSTGRES_POOL_MAX, mais margem. Mantenha DATABASE_SSL_MODE=verify-full no PostgreSQL remoto; somente o Compose isolado usa disable. Team Helm exige um secrets.jwtSecret estável em todos os Pods. S3 recebe chaves opacas e texto cifrado; URLs não entram nos metadados.
Arquivos integrados solo/team preservam ajustes de pool e timeout, Redis, cotas de blobs, seletores e endereçamento S3 na configuração assinada e criptografada, permitindo restauração limpa sem metadados em texto simples.
Aplicação e worker recebem os mesmos OLLAMA_BASE_URL, OLLAMA_TIMEOUT, OLLAMA_LONG_OPERATION_TIMEOUT e OLLAMA_MAX_CONTEXT. Chamadas ocorrem no worker e os valores não podem divergir. Ambos analisam os três números como inteiros decimais positivos completos. Valores como 300000ms, notação exponencial/hexadecimal, fora de faixa ou timeout longo menor que o padrão fazem a inicialização falhar.
Helm restringe TRUST_PROXY a 0–16 e envia somente aos Pods HTTP. Use 0 no tráfego direto e o número exato em uma cadeia fixa; nunca true. Número errado agrupa clientes sob o proxy ou confia em endereço fornecido pelo cliente.
A compatibilidade PostgreSQL é de versão exata. App e worker usam Recreate; drene e termine todos os Pods antigos antes da atualização e deixe um novo processo migrar sob advisory lock. Não execute binários mistos nem alegue rollout sem interrupção. Rollback restaura o arquivo verificado anterior em PostgreSQL/S3 limpos antes do binário antigo.
Uma aplicação team ativa exige worker.replicaCount >= 1. Zere aplicação e worker para suspensão total. App zero e worker positivo é modo deliberado de drenagem/recuperação que consome a fila sem servir web.
Auxiliar de backup privado
Estas variáveis configuram deploy/private/libre-webui-backup e são lidas pelo script de manutenção, não pela aplicação:
| Variável | Padrão | Finalidade |
|---|---|---|
LIBRE_WEBUI_STACK_DIR | /opt/libre-webui | Diretório do Compose privado |
LIBRE_WEBUI_BACKUP_DIR | /var/backups/libre-webui | Diretório protegido dos backups e lock |
LIBRE_WEBUI_BACKUP_RETENTION_DAYS | 14 | Idade para remover conjuntos concluídos |
LIBRE_WEBUI_CONTAINER_NAME | libre-webui | Contêiner implantado a inspecionar |
LIBRE_WEBUI_BACKUP_KEY_DIR | /etc/libre-webui/backup-keys | Diretório privado de chaves de criptografia e assinatura |
LIBRE_WEBUI_RESTORE_IMAGE | obrigatório para restaurar | ID ou digest imutável revisado |
LIBRE_WEBUI_RESTORE_CONFIG_DIR | caminho por volume em /etc/libre-webui/restored | Novo diretório da configuração recuperada |
A unidade systemd lê substituições do arquivo opcional /etc/libre-webui/backup.env, de propriedade de root. Use modo 0600. Diretório da pilha, retenção, contêiner e chaves podem ser definidos ali. O sandbox permite escrita somente no diretório padrão. Um LIBRE_WEBUI_BACKUP_DIR personalizado também exige o diretório exato previamente criado em um drop-in ReadWritePaths=; consulte Implantação remota privada.
Autenticação e segurança
| Variável | Padrão | Finalidade |
|---|---|---|
ENABLE_SIGNUP | false | Permitir cadastro após o primeiro administrador |
JWT_SECRET | gerado/fallback em desenvolvimento | Segredo de assinatura; defina em produção |
JWT_EXPIRES_IN | 7d | Vida do token |
ENCRYPTION_KEY | gerada automaticamente | Chave hexadecimal de 64 caracteres |
DEBUG_ENCRYPTION | não definido | Registra depuração da criptografia |
TURNSTILE_SITE_KEY | não definido | Chave de site Turnstile |
TURNSTILE_SECRET_KEY | não definido | Chave secreta de verificação |
TURNSTILE_EXPECTED_HOSTNAME | host de BASE_URL | Host exigido na resposta |
MFA_REQUIRED_MODE | não definido (controle administrativo, optional) | Fixar política em optional ou required |
WEBAUTHN_RP_ID | host da solicitação | ID relying-party fixo para passkeys em vários hosts |
VAPID_PUBLIC_KEY | gerada e armazenada criptografada | Fixar chave pública VAPID (base64url P-256 point) |
VAPID_PRIVATE_KEY | gerada e armazenada criptografada | Fixar chave privada VAPID (base64url scalar) |
VAPID_SUBJECT | mailto:admin@localhost | Contato em autorizações Web Push |
Turnstile só é ativado com ambas as chaves.
ENABLE_SIGNUP=false ainda permite o primeiro administrador em banco vazio e bloqueia os demais. Proteja uma rota inicial remota com uma fronteira externa de identidade.
Todo JWT é vinculado a uma sessão no servidor (claim sid), então logout ou revogação invalida imediatamente em todas as réplicas e fecha WebSockets. Retenção:
| Variável | Padrão | Finalidade |
|---|---|---|
AUDIT_RETENTION_DAYS | 180 | Dias de retenção do log de auditoria |
Single Sign-On OIDC genérico
Qualquer provedor OpenID Connect com documento de descoberta pode ser usado. O fluxo usa PKCE (S256), estado CSRF e nonce validado dentro do ID token cuja assinatura foi verificada. Identidades são ligadas pela claim estável sub.
| Variável | Padrão | Finalidade |
|---|---|---|
OIDC_ISSUER_URL | não definido | URL do emissor; busca em <issuer>/.well-known/openid-configuration |
OIDC_CLIENT_ID | não definido | ID OAuth registrado |
OIDC_CLIENT_SECRET | não definido | Segredo OAuth |
OIDC_DISPLAY_NAME | Single Sign-On | Rótulo no botão |
OIDC_SCOPES | openid profile email | Escopos solicitados |
OIDC_CALLBACK_URL | BASE_URL + rota OIDC | URI de redirecionamento |
OIDC_ALLOWED_EMAIL_DOMAINS | não definido | Lista por vírgulas de domínios de e-mail verificado |
OIDC_GROUP_CLAIM | groups | Claim com nomes de grupos |
OIDC_ADMIN_GROUPS | não definido | Lista que controla o papel admin em cada login |
OIDC_SYNC_GROUPS | false | true sincroniza grupos Libre em cada login |
OIDC só é ativado com URL, ID e segredo. Um e-mail já usado por conta local não vinculada é rejeitado em vez de mesclado, e a criação respeita ENABLE_SIGNUP.
É possível ajustar a admissão WebSocket sem enfraquecer autenticação:
| Variável | Padrão | Finalidade |
|---|---|---|
CHAT_WS_MAX_PAYLOAD_BYTES | 10 MiB | Tamanho máximo de mensagem |
CHAT_WS_MAX_MESSAGES_PER_MINUTE | 120 | Limite por conexão |
CHAT_WS_MAX_ACTIVE_GENERATIONS_PER_USER | 4 | Gerações por conta |
CHAT_WS_MAX_CONNECTIONS_PER_USER | 5 | Sockets simultâneos |
WEBSOCKET_TICKET_TTL_MS | 30000 | Vida do ticket único, máximo 60 segundos |
O navegador troca Authorization por ticket opaco e coloca apenas esse valor curto no URL de upgrade. Tickets são únicos, vinculados ao protocolo e sessão e armazenados como hash. Quando CORS_ORIGIN ou BASE_URL está definido, o Origin do navegador deve coincidir. Defina ao menos um em implantação remota; sem ambos, o filtro é permissivo para desenvolvimento.
Upgrades sem Origin continuam disponíveis para Electron e clientes não navegador, mas exigem ticket válido e as mesmas verificações. Trate o ticket como fronteira e restrinja com TLS, firewall e proxy.
OAuth
| Variável | Finalidade |
|---|---|
GITHUB_CLIENT_ID | ID do cliente GitHub |
GITHUB_CLIENT_SECRET | Segredo GitHub |
GITHUB_CALLBACK_URL | Substituição do callback |
HUGGINGFACE_CLIENT_ID | ID do cliente Hugging Face |
HUGGINGFACE_CLIENT_SECRET | Segredo Hugging Face |
HUGGINGFACE_CALLBACK_URL | Substituição do callback |
Sem callbacks definidos, o Libre WebUI cria padrões a partir de BASE_URL.
Ollama
| Variável | Padrão | Finalidade |
|---|---|---|
OLLAMA_BASE_URL | http://localhost:11434 | URL base |
OLLAMA_TIMEOUT | 300000 | Timeout padrão (1.000-3.600.000 ms) |
OLLAMA_LONG_OPERATION_TIMEOUT | 900000 | Timeout longo (mesma faixa e não menor que OLLAMA_TIMEOUT) |
OLLAMA_MAX_CONTEXT | 32768 | Contexto máximo adotado (128-2.097.152 tokens) |
Busca na web
| Variável | Padrão | Finalidade |
|---|---|---|
SEARXNG_URL | não definido | Endpoint padrão; administrador ainda ativa em Configurações > Busca |
Libre Claw
| Variável | Padrão | Finalidade |
|---|---|---|
LIBRE_CLAW_BASE_URL | http://127.0.0.1:8766 | URL opcional do daemon |
LIBRE_CLAW_TIMEOUT_MS | 30000 | Timeout HTTP |
Runtime do Work
Estas variáveis configuram a execução na máquina ou cluster do backend. Docker é o padrão; Helm escolhe Kubernetes com work.enabled=true.
| Variável | Padrão | Finalidade |
|---|---|---|
WORK_RUNTIME_IMAGE | node:22.22-bookworm@sha256:2d178f2785b96dfbf62a416ca2e40f50e30150b4ff3320d706f0d96e90600eb3 | Imagem fixada dos sandboxes |
WORK_DOCKER_COMMAND | docker | Executável CLI |
WORK_COMMAND_TIMEOUT_MS | 120000 | Timeout padrão; ferramenta pode pedir 600000 ms |
WORK_MAX_OUTPUT_CHARS | 50000 | Limite por stream de stdout/stderr |
WORK_MAX_AGENT_ROUNDS | 48 | Rodadas modelo/ferramenta por execução |
WORK_STATUS_BLURB_MODEL | 1 | 0 ignora a chamada que escreve o status do agente |
WORK_MEMORY_LIMIT | 2g | Memória por contêiner |
WORK_CPU_LIMIT | 2 | CPU por contêiner |
WORK_PIDS_LIMIT | 256 | Processos por contêiner |
WORK_PREVIEW_PORT | 4173 | Porta interna da prévia |
WORK_PREVIEW_BIND | 127.0.0.1 | Interface do host para publicar; implantações Compose no Docker Engine nativo precisam usar uma interface de bridge não pública e alcançável |
WORK_DOCKER_PUBLISHED_HOST | padrão do app: igual a WORK_PREVIEW_BIND; padrão do Compose: host.docker.internal | Host/IP visto pelo backend para prévia, tela e áudio |
WORK_COMPUTER_SCREEN_PORT | 6080 | Porta da ponte de tela websockify |
WORK_COMPUTER_AUDIO_PORT | 6081 | Porta da ponte de áudio websockify/PulseAudio |
WORK_MAX_ACTIVE_RUNTIMES_GLOBAL | 3 | Tarefas simultâneas na instância |
WORK_MAX_ACTIVE_RUNTIMES_PER_USER | 2 | Tarefas simultâneas por usuário |
WORK_MAX_TASKS_GLOBAL | 500 | Tarefas persistidas na instância |
WORK_MAX_TASKS_PER_USER | 100 | Tarefas persistidas por administrador |
WORK_NETWORK_NAME | libre-webui-work | Rede bridge gerenciada |
WORK_RUN_LEASE_WAIT_MS | 60000 | Espera pela concessão compartilhada antes de conflito (team) |
WORK_RUNTIME_DNS | não definido | IPs de resolvedores separados por vírgula |
WORK_DOCKER_SOCKET | DOCKER_HOST se unix:// ou tcp://, senão /var/run/docker.sock | Endpoint Docker Engine de terminais e diagnóstico |
WORK_TERMINAL_MAX_SESSIONS_PER_TASK | 2 | Terminais simultâneos por tarefa |
WORK_TERMINAL_IDLE_TIMEOUT_MS | 900000 | Timeout ocioso |
WORK_RUNTIME_IDLE_TIMEOUT_MS | 0 (desativado) | Parar sandbox após inatividade, inclusive prévias |
WORK_HOST_WORKSPACES_ENABLED | false | Permitir pasta do host |
WORK_HOST_WORKSPACE_ROOTS | diretório pessoal do usuário | Raízes permitidas separadas por : |
WORK_RUNTIME_BACKEND | docker | docker ou kubernetes |
WORK_K8S_NAMESPACE | libre-webui-work | Namespace de Pods/PVCs |
WORK_K8S_STORAGE_CLASS | padrão do cluster | StorageClass |
WORK_K8S_WORKSPACE_SIZE | 5Gi | PVC por tarefa, cota real |
WORK_K8S_POD_READY_TIMEOUT_MS | 900000 | Espera pelo Pod Running |
WORK_K8S_POD_GONE_TIMEOUT_MS | 60000 | Espera pelo desaparecimento |
AGENT_CLI_MODELS_ENABLED | não definido (controle administrativo, desligado) | Fixar Agents ligado/desligado |
TOOLS_ACCESS_MODE | não definido (somente administradores) | Fixar ferramentas em admins ou all-users |
STT_ACCESS_MODE | não definido (todos) | Fixar STT em admins ou all-users |
TTS_ACCESS_MODE | não definido (todos) | Fixar TTS em admins ou all-users |
VOICE_MODE_ACCESS_MODE | não definido (todos) | Fixar modo de voz em admins ou all-users |
VOICE_CLONING_ACCESS_MODE | não definido (todos) | Fixar clonagem em admins ou all-users |
TOOLS_PRIVATE_NETWORK_ALLOWLIST | não definido | Hosts exatos que ferramentas/Webhooks podem resolver em rede privada |
AGENT_CLI_TIMEOUT_MS | 600000 | Tempo até encerrar agent CLI |
CODEX_OAUTH_MODELS_ENABLED | true | Oferecer Codex (ChatGPT) a administradores |
CODEX_HOME | ~/.codex | Local de auth.json |
Binários Agent CLI e credenciais Codex OAuth são locais ao nó e só funcionam em solo, onde descoberta e execução veem o mesmo ambiente. Team executa trabalhos no worker e exige AGENT_CLI_MODELS_ENABLED=false e CODEX_OAUTH_MODELS_ENABLED=false; outros valores são rejeitados. Use Ollama ou plugin com estado compartilhado.
No Docker, uma pasta do host é montada em /workspace, permitindo leitura/escrita direta. Kubernetes rejeita. Isso reduz o isolamento: mantenha WORK_HOST_WORKSPACES_ENABLED desligado e WORK_HOST_WORKSPACE_ROOTS estreito. Caminhos resolvem symlinks e .ssh, .gnupg, .aws, .config são recusados.
Modelos Agent CLI expõem agentes instalados (claude, codex) sem chave. Somente administradores veem; o CLI roda como usuário do servidor e herda credenciais — equivalente a conceder acesso de shell a esses agentes.
Tarefas com rede entram na bridge WORK_NETWORK_NAME com comunicação entre contêineres desativada. WORK_RUNTIME_DNS aponta a resolvedor filtrante; entradas não IP são recusadas. DNS não restringe IP direto, exigindo firewall. Kubernetes usa NetworkPolicies e work.networkPolicy.blockedEgressCidrs.
Terminal e diagnóstico Docker falam diretamente com Engine API: WORK_DOCKER_SOCKET, ou DOCKER_HOST (unix:// ou tcp:// HTTP como proxy; veja docker-compose.socket-proxy.yml), ou /var/run/docker.sock. ssh:// e tcp:// com DOCKER_TLS_VERIFY tornam terminal/diagnóstico indisponíveis; o resto continua pelo CLI. Kubernetes usa Pod exec.
Os valores são lidos na inicialização. A porta de prévia é interna e publicada em loopback dinâmico.
Fixe a imagem em versão/digest revisado. Aumentar concorrência amplia recursos consumidos. WORK_MAX_AGENT_ROUNDS vale igualmente para Ollama e plugins. O orçamento de chamadas é max(128, WORK_MAX_AGENT_ROUNDS × 8). Ao esgotar, o Work pede uma entrega final sem ferramentas e termina em needs_input, não erro bruto nem conclusão falsa. Uma nova execução continua no mesmo espaço. A saída persistida limita-se a cerca de 20.000 caracteres e marcador.
Essas variáveis ajustam um runtime já acessível. Compose de instância única habilita por padrão com CLI e socket. Duas variáveis de nível Compose:
| Variável | Padrão | Finalidade |
|---|---|---|
DOCKER_GID | 0 | Grupo do socket adicionado ao usuário |
DOCKER_SOCKET | /var/run/docker.sock | Caminho do socket |
DOCKER_GID deve ser o grupo visto dentro do contêiner; macOS informa outro. A base team não monta socket até adicionar docker-compose.team.work.yml; esse overlay dá a app e worker o mesmo proxy interno filtrado. Criar contêiner ainda é credencial de controle do host; prefira daemon dedicado/rootless. Helm nunca monta socket do nó; ative Pod/PVC com work.enabled=true.
solo deve ter zero ou uma réplica. Helm aceita zero para suspensão e rejeita mais ou autoscaling. team completo usa múltiplas réplicas e worker por ter PostgreSQL, S3, PGVector e Redis. Pods Work escalam à parte, e worker recebe mesma imagem, StorageClass e work.env.
Compose também aceita WEBUI_BIND_ADDRESS (padrão 127.0.0.1) e WEBUI_PORT (padrão 8080). Mantenha loopback salvo necessidade confiável.
Descoberta de modelos de provedores
Catálogos ausentes ou antigos são redescobertos:
| Variável | Padrão | Finalidade |
|---|---|---|
PLUGIN_MODEL_DISCOVERY_TTL_MS | 21600000 (6 h) | Idade para atualizar na próxima leitura |
PLUGIN_MODEL_DISCOVERY_RETRY_MS | 600000 (10 min) | Intervalo mínimo após falha |
PLUGIN_MODEL_DISCOVERY_REFRESH_DEADLINE_MS | 3000 | Espera antes de responder |
Uma atualização tardia aparece na próxima solicitação. Atualizar modelos ignora o intervalo.
Chaves de plugins de provedores
| Variável | Provedor |
|---|---|
OPENAI_API_KEY | OpenAI e 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 da Moonshot AI |
GITHUB_API_KEY | GitHub Models |
HUGGINGFACE_API_KEY | APIs Hugging Face configuradas |
ELEVENLABS_API_KEY | ElevenLabs TTS |
COMFYUI_API_KEY | ComfyUI com chave |
Usuários também salvam credenciais na interface. Chaves ambientais valem somente para definição incluída não shadowed. Importadas, graváveis com ID incluído e rotas personalizadas exigem credencial da conta; o Libre não anexa a chave nem a expõe em descoberta. A confiança vem do hash compilado.
Chaves salvas são vinculadas à definição, origem, autenticação e rota. Devem ser salvas novamente após mudança. Legadas sem vínculo só migram no primeiro uso de definição e rota exatas.
Em source, PLUGINS_DIR relativo resolve do backend; no pacote, vira absoluto do chamador. Por compatibilidade, também lê backend/plugins e locais antigos. Mova para $DATA_DIR/plugins; a recuperação bloqueia snapshot só de volume enquanto houver estado externo. Diretórios e JSON devem ser entradas físicas regulares; symlinks não são seguidos.
Frontend
| Variável | Padrão | Finalidade |
|---|---|---|
VITE_API_BASE_URL | proxy de desenvolvimento de mesma origem ou API de produção | URL base da API |
VITE_WS_BASE_URL | inferido da API | Base absoluta ws:/wss: para Chat e Work |
VITE_APP_VERSION | versão injetada pelo Vite | Versão exibida |
VITE_DEMO_MODE | false | Simulações quando true |
VITE_API_TIMEOUT | 300000 | Timeout em ms |
VITE_BACKEND_URL | http://localhost:3001 | Usado por componentes de autenticação |
VITE_DEBUG_VERBOSE | não definido | Logs detalhados em desenvolvimento |
VITE_LOG_LEVEL | não definido | Substitui o nível |
ELECTRON_BUILD | não definido | Comportamento Electron quando true |
VITE_WS_BASE_URL substitui todos os fallbacks WebSocket. Pode incluir prefixo, mas deve ser URL ws: ou wss: absoluto sem credenciais, consulta ou fragmento. Ausente, Electron file: usa ws://localhost:3001; navegador deriva de VITE_API_BASE_URL, depois da origem do navegador. O Vite faz proxy da origem de desenvolvimento para o backend na porta 3001.
Scripts de manutenção
| Variável | Finalidade |
|---|---|
CHANGELOG_AI | 0 desativa rascunhos assistidos |
CHANGELOG_AI_MODEL | Modelo Ollama para release/changelog |
CHANGELOG_AI_TIMEOUT_MS | Timeout em ms |
CHANGELOG_AI_MODEL=glm-5.2:cloud npm run changelog
CHANGELOG_AI=0 npm run release:minor
Exemplo de produção
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