Umgebungsvariablen
Diese Seite listet die derzeit vom Backend, Frontend und den Wartungsskripten gelesenen, für Betreiber bestimmten Umgebungsvariablen auf. Interne reine Testindikatoren sind bewusst ausgelassen.
Backend-Server
| Variable | Standard | Zweck |
|---|---|---|
NODE_ENV | development | Laufzeitmodus |
PORT | 3001 in Entwicklung, 8080 in Produktion | HTTP-Port des Backends |
TRUST_PROXY | nicht gesetzt (0 in Helm) | Exakte Zahl vertrauenswürdiger Reverseproxy-Hops zur Ableitung der Clientadresse |
CORS_ORIGIN | lokale Entwicklungsursprünge | Erlaubte Browserursprünge, kommagetrennt |
SERVE_FRONTEND | nicht gesetzt | Gebautes Frontend bei true vom Backend ausliefern |
DOCKER_ENV | nicht gesetzt | Dockerorientiertes Verhalten bei true aktivieren |
DATA_DIR | backend/data; ~/.libre-webui im gepackten CLI | Persistentes Datenverzeichnis |
PLATFORM_PREFLIGHT_TMP_DIR | backend/temp/preflight; Benutzercache im gepackten CLI | Arbeitsbereich für private DB-/WAL-Prüfkopie; für Datenbank plus WAL dimensionieren |
PLUGIN_UPLOAD_TEMP_DIR | libre-webui-plugin-uploads im temporären OS-Verzeichnis | Arbeitsbereich für laufende Plugin-Uploads |
PLUGINS_DIR | $DATA_DIR/plugins | Beschreibbares Verzeichnis installierter oder angepasster Plugins |
BASE_URL | http://localhost:3001 | Basis-URL für OAuth-Callback-Vorgaben |
LOG_LEVEL | info (warn in Tests) | Backend-Protokollstufe |
LOG_FORMAT | text | json schaltet auf strukturierte einzeilige Protokolle mit Zeit, Korrelation und Redigierung |
OTEL_EXPORTER_OTLP_ENDPOINT | nicht gesetzt | Optionale OTLP/HTTP-JSON-Telemetrie; ohne Wert verlässt keine Telemetrie den Prozess |
OTEL_EXPORTER_OTLP_HEADERS | nicht gesetzt | Kommagetrennte key=value-Kopfzeilen an den OTLP-Sammler |
OTEL_SERVICE_NAME | libre-webui | Ressourcenattribut service.name in exportierter Telemetrie |
WEBUI_HOST | Loopback; 0.0.0.0 in Docker | HTTP-Lauschadresse |
OPEN_BROWSER | true bei ausgeliefertem Frontend | Auf false setzen, um Browserstart zu unterdrücken |
FULL_DOCUMENT_CONTEXT_MAX_TOKENS | 32000 | Tokengrenze des vollständigen Dokumentmodus je Chat (1000-2000000) |
GALLERY_RETENTION_DAYS | nicht gesetzt (dauerhaft behalten) | Ältere Galeriemedien beim Planerlauf nach dieser Tageszahl löschen |
RECOVERY_DRILL_INTERVAL_HOURS | nicht gesetzt (Übungen aus) | Verifizierte Wiederherstellungsübung alle N Stunden automatisch ausführen (solo) |
RECOVERY_DRILL_HISTORY | 60 | Aufbewahrte Einträge im Übungsverlauf |
Quellstarts verankern relative Werte von DATA_DIR, PLUGINS_DIR und PLATFORM_PREFLIGHT_TMP_DIR im Backendverzeichnis, unabhängig vom Shell-Verzeichnis. Ohne DATA_DIR – oder mit DATA_DIR=./data – verwenden Stamm- und Backendbefehle backend/data. Aus Kompatibilität wählt eine bestehende Konfiguration DATA_DIR=./backend/data weiterhin backend/backend/data; ändere dies nur bei bewusster Sicherung und Migration im Stillstand. Ein Profil ohne Wert verwendet das historische Verzeichnis auch dann, wenn es der einzige bestehende Speicher ist. Enthalten beide Zustand und ist kein Pfad gewählt, schlägt der Start sicher fehl statt zu raten, kopieren oder zusammenzuführen.
Die npx-, globale npm- und interaktive Homebrew-Startvariante bewahren Daten unter ~/.libre-webui. Ein explizites relatives DATA_DIR wird vom Arbeitsverzeichnis des Aufrufers aufgelöst und vor dem Backendstart absolut gemacht. Ein relatives PLUGINS_DIR folgt derselben Regel; ohne Wert bleiben Plugins unter $DATA_DIR/plugins. Prüfdateien liegen standardmäßig in einem beschreibbaren Cache außerhalb der Daten: ~/Library/Caches/libre-webui auf macOS, %LOCALAPPDATA%\libre-webui auf Windows oder ${XDG_CACHE_HOME:-~/.cache}/libre-webui andernorts. Der Homebrew-Dienst fixiert dasselbe Datenverzeichnis und nutzt var/libre-webui/preflight. Setze PLATFORM_PREFLIGHT_TMP_DIR, wenn der Cache Datenbank plus WAL nicht fasst. Docker und Helm verwenden /app/backend/data und /app/backend/temp/preflight auf getrennten Einbindungen.
Plattformgrundlage
Das Standardprofil solo nutzt SQLite, lokale verschlüsselte Blobs, verschlüsselte eingebettete Vektoren, lokale Koordination und einen eingebetteten dauerhaften Worker. team nutzt PostgreSQL, private S3-kompatible Blobs, PGVector, Redis und einen externen Worker. Die Teamkonfiguration schlägt sicher fehl; alle gemeinsamen Abhängigkeiten müssen zusammen gewählt werden.
| Variable | Standard | Zweck |
|---|---|---|
LIBRE_PLATFORM_MODE | solo | Zusammenhängendes Profil solo oder team wählen |
DATABASE_BACKEND | sqlite | sqlite oder postgres wählen |
DATABASE_URL | nicht gesetzt | PostgreSQL-Verbindungs-URL, bei postgres erforderlich |
DATABASE_SSL_MODE | verify-full | TLS-Richtlinie: disable, require oder hostprüfendes verify-full |
POSTGRES_MIGRATION_MODE | apply | Migrationen unter Leader-Lock ausführen oder mit validate das Schema nur lesen |
POSTGRES_POOL_MAX | 10 | Maximale PostgreSQL-Verbindungen pro App- oder Workerprozess (1-100) |
POSTGRES_CONNECT_TIMEOUT_MS | 5000 | Verbindungszeitlimit (1-60000 ms) |
POSTGRES_IDLE_TIMEOUT_MS | 30000 | Inaktivitätszeitlimit (1-600000 ms) |
POSTGRES_STATEMENT_TIMEOUT_MS | 30000 | Anweisungszeitlimit (1-600000 ms) |
POSTGRES_MIGRATION_LOCK_TIMEOUT_MS | 60000 | Wartezeit auf Migrations-Lock (1-600000 ms) |
BLOB_STORE_BACKEND | local | Verschlüsselten local- oder privaten s3-Speicher wählen |
VECTOR_STORE_BACKEND | embedded mit SQLite | Verschlüsselte embedded-Vektoren oder pgvector wählen |
COORDINATION_BACKEND | local in solo; redis in team | Prozesslokale oder Redis-Koordination wählen |
REDIS_URL | nicht gesetzt | redis:- oder rediss:-URL, mit Redis erforderlich |
REDIS_KEY_PREFIX | libre | 1–64 Zeichen langer Namespace für Koordinationsschlüssel |
REDIS_CONNECT_TIMEOUT_MS | 5000 | Erste Redis-Verbindungswartezeit, höchstens 60 Sekunden |
JOB_WORKER_MODE | embedded in solo; external in team | Handler in App oder eigenständigem gemeinsamem Worker ausführen |
RESOURCE_LEASE_TTL_MS | 30000 | Koordinationslease für dauerhaften Ressourcenbesitz (5000-300000; Start scheitert außerhalb) |
JOB_WORKER_CONCURRENCY | 4 | Gleichzeitige dauerhafte Aufträge pro Worker (1-32) |
CHAT_STREAM_EVENT_RETENTION_HOURS | 24 | Stunden bis zum stündlichen Entfernen von Chat-Streamereignissen |
PLATFORM_EVENT_RETENTION_DAYS | 30 | Tage bis zum Entfernen dauerhafter Ereignisse |
PLATFORM_JOB_RETENTION_DAYS | 30 | Tage bis zum Entfernen beendeter Nicht-Lebenszyklusaufträge |
LIBRE_SKIP_STARTUP_INTEGRITY_SCAN | nicht gesetzt | 1 überspringt einmalig den tiefen Altdaten-Scan (Notausgang; sonst je Schemageneration gecacht) |
STORAGE_ENCRYPTION_KEYS | nicht gesetzt | Geheime JSON-Schlüsselkarte; muss derzeit legacy passend zu ENCRYPTION_KEY enthalten |
STORAGE_ENCRYPTION_ACTIVE_KEY_ID | nicht gesetzt | Schlüssel-ID für neue lokale Blob- und eingebettete Vektorschreibvorgänge |
BLOB_QUOTA_BYTES_PER_USER | 10737418240 | Dauerhaftes Maximum unverschlüsselter Blobbytes pro Besitzer |
BLOB_QUOTA_RESERVATION_TTL_MS | 3600000 | Lebensdauer einer verlassenen Streamingreservierung (mindestens 60000 ms) |
S3_BUCKET | nicht gesetzt | Privater S3-kompatibler Bucket, bei s3 erforderlich |
S3_REGION | nicht gesetzt | S3-Region, bei s3 erforderlich |
S3_ENDPOINT | Anbietervorgabe | Optionaler absoluter HTTP(S)-Endpunkt für MinIO oder kompatiblen Dienst |
S3_ACCESS_KEY_ID | SDK-Zugangsdatenkette | Optionaler expliziter S3-Zugriffsschlüssel |
S3_SECRET_ACCESS_KEY | SDK-Zugangsdatenkette | Bei explizitem Zugriffsschlüssel erforderlich |
S3_SESSION_TOKEN | nicht gesetzt | Optionales Token zu expliziten S3-Zugangsdaten |
S3_FORCE_PATH_STYLE | false | Auf true setzen, wenn pfadbasiertes Adressieren nötig ist |
S3_BLOB_PREFIX | libre/blobs | Undurchsichtiger Bucket-Schlüsselpräfix im Besitz von Libre |
Fehlt die versionierte Schlüsselkarte, verwenden Speicheradapter ENCRYPTION_KEY als ID legacy; fehlt auch dieser, lesen sie ${DATA_DIR}/.encryption_key, ohne ihn zu erzeugen oder ändern. Explizite Konfiguration und Datei müssen übereinstimmen. Wird bei vorhandenem Altschlüssel eine Karte eingeführt, bewahre ihn unter der exakten ID legacy, bis alle Objekte und Vektoren neu geschrieben oder umhüllt und geprüft sind. Konflikte, unsichere Berechtigungen, Symlinks und fehlende konfigurierte Schlüssel führen zu sicherem Fehlschlag.
Redis ist Koordination, keine kanonische Persistenz. Allein seine Auswahl macht SQLite, lokale Dateien oder prozesseigenen Zustand nicht replika-sicher. In team verwenden HTTP-Limits, Chat-/WebSocket-Verbindungen, STT-/TTS-/Audioarbeiten, Archivimporte und Work-Terminals gemeinsame Redis-Zulassung. Kapazitäten gelten über alle Replikate. Zulassungs- oder Verlängerungsfehler geben 503 zurück oder brechen ab; Libre fällt nie auf einen lokalen Zähler zurück. Siehe Plattformgrundlage.
Der gebündelte Team-Compose-Stack und Helm-Chart geben alle Selektoren und Werte an App und Worker weiter. In Helm liegen nicht geheime Selektoren unter env; setze secrets.redisUrl, secrets.databaseUrl und secrets.storageEncryptionKeys für Verbindungen und Schlüssel. PostgreSQL-Pools gelten pro Prozess: Plane mindestens (replicaCount + worker.replicaCount) * POSTGRES_POOL_MAX Verbindungen plus Reserve. Behalte DATABASE_SSL_MODE=verify-full für verwaltetes oder entferntes PostgreSQL. Nur Team-Compose setzt disable, da sein Listener im privaten Netz isoliert ist. Team-Helm erfordert ein stabiles secrets.jwtSecret in allen Pods; sonst würde jeder Prozess eigenes Signaturmaterial erzeugen. S3 erhält undurchsichtige Schlüssel und Chiffretext; Bucket- und Anbieter-URLs stehen nicht in Anwendungsmetadaten.
Integrierte Solo- und Teamarchive bewahren Pool- und Zeitwerte, Redis-Zeitlimit, Blobkontingente, Plattformselektoren und S3-Adressierung in signierter und verschlüsselter geschützter Konfiguration. Eine saubere Wiederherstellung kann dadurch die nötigen Betriebswerte veröffentlichen, ohne sie in Klartextmetadaten zu legen.
App-/Workerpaare erhalten dieselben OLLAMA_BASE_URL, OLLAMA_TIMEOUT, OLLAMA_LONG_OPERATION_TIMEOUT und OLLAMA_MAX_CONTEXT. Anbieteraufrufe für Einbettungen, dauerhafte Chats und Work laufen im Worker, daher dürfen Werte nicht abweichen. Beide Serverstartpunkte parsen die drei Zahlen als vollständige positive Basis-10-Ganzzahlen, bevor Zustand entsteht oder verbunden wird. Teilwerte wie 300000ms, Exponential-/Hexnotation, Werte außerhalb des Bereichs oder ein langes Limit unter dem normalen lassen den Start scheitern.
Helm begrenzt TRUST_PROXY auf eine exakte Ganzzahl von 0 bis 16 und sendet sie nur an HTTP-Pods. Behalte 0 für direkten Verkehr, setze für eine feste Proxykette die genaue Zahl und verwende nie true. Eine falsche Zahl gruppiert Clients oder vertraut einer Clientangabe.
PostgreSQL-Schemakompatibilität ist exakt. Helm-App und -Worker nutzen Recreate; beende alle alten Pods vor dem Teamupgrade und lasse einen neuen Prozess unter Advisory-Lock migrieren. Führe keine gemischten Versionen aus und verspreche keine unterbrechungsfreie Schemamigration. Rollback bedeutet, das verifizierte Vorupgradearchiv in saubere PostgreSQL-/S3-Ziele wiederherzustellen, bevor das passende ältere Programm startet.
Eine aktive Team-App benötigt worker.replicaCount >= 1; Helm verweigert eine laufende App ohne Worker. Setze App und Worker für vollständige Pause auf null. App null mit positivem Worker ist ein bewusster Abfluss-/Wiederherstellungsmodus und verarbeitet die Warteschlange ohne Webverkehr.
Privater Sicherungshelfer
Diese Variablen konfigurieren deploy/private/libre-webui-backup und werden vom Wartungsskript, nicht vom Anwendungsprozess gelesen:
| Variable | Standard | Zweck |
|---|---|---|
LIBRE_WEBUI_STACK_DIR | /opt/libre-webui | Verzeichnis der privaten Compose-Datei |
LIBRE_WEBUI_BACKUP_DIR | /var/backups/libre-webui | Geschütztes Verzeichnis für Sicherungen und Lockdatei |
LIBRE_WEBUI_BACKUP_RETENTION_DAYS | 14 | Alter, nach dem fertige Sicherungen entfernt werden |
LIBRE_WEBUI_CONTAINER_NAME | libre-webui | Zu prüfender bereitgestellter Anwendungscontainer |
LIBRE_WEBUI_BACKUP_KEY_DIR | /etc/libre-webui/backup-keys | Privates Verzeichnis für Verschlüsselungs-/Signierschlüssel |
LIBRE_WEBUI_RESTORE_IMAGE | zur Wiederherstellung erforderlich | Geprüfte unveränderliche Libre-Image-ID oder Digest |
LIBRE_WEBUI_RESTORE_CONFIG_DIR | volumenbezogener Pfad unter /etc/libre-webui/restored | Neues Verzeichnis wiederhergestellter Konfiguration |
Die systemd-Unit lädt Überschreibungen aus der optionalen Root-Datei /etc/libre-webui/backup.env. Setze Modus 0600. Stackverzeichnis, Aufbewahrung, Containername und Schlüsselverzeichnis können dort stehen. Die Dateisystem-Sandbox erlaubt Schreibzugriff nur unter dem Standardsicherungsverzeichnis. Ein eigenes LIBRE_WEBUI_BACKUP_DIR erfordert zusätzlich dieses vorab erstellte Verzeichnis in einem ReadWritePaths=-Drop-in; siehe Private Remote-Bereitstellung.
Authentifizierung und Sicherheit
| Variable | Standard | Zweck |
|---|---|---|
ENABLE_SIGNUP | false | Registrierung nach erstem lokalen Administrator erlauben |
JWT_SECRET | erzeugt/Fallback in Entwicklung | JWT-Signiergeheimnis; in Produktion explizit setzen |
JWT_EXPIRES_IN | 7d | Lebensdauer des Sitzungstokens |
ENCRYPTION_KEY | automatisch erzeugt | 64-stelliger Hexschlüssel für verschlüsselte Werte |
DEBUG_ENCRYPTION | nicht gesetzt | Verschlüsselungs-Debugausgabe protokollieren |
TURNSTILE_SITE_KEY | nicht gesetzt | Cloudflare Turnstile-Siteschlüssel |
TURNSTILE_SECRET_KEY | nicht gesetzt | Geheimer Turnstile-Prüfschlüssel |
TURNSTILE_EXPECTED_HOSTNAME | Hostname aus BASE_URL | Erforderlicher Host in Cloudflare-Antwort |
MFA_REQUIRED_MODE | nicht gesetzt (Schalter, optional) | Zwei-Faktor-Richtlinie auf optional oder required fixieren |
WEBAUTHN_RP_ID | Anfragehostname | Feste Relying-Party-ID für Passkeys hinter mehreren Hosts |
VAPID_PUBLIC_KEY | erzeugt und verschlüsselt gespeichert | Öffentlichen Web-Push-VAPID-Schlüssel fixieren |
VAPID_PRIVATE_KEY | erzeugt und verschlüsselt gespeichert | Privaten Web-Push-VAPID-Schlüssel fixieren |
VAPID_SUBJECT | mailto:admin@localhost | Kontaktangabe in signierten Web-Push-Genehmigungen |
Turnstile ist nur mit beiden Schlüsseln aktiv.
ENABLE_SIGNUP=false erlaubt weiterhin den ersten lokalen Administrator einer leeren Datenbank und blockiert danach weitere Konten. Schütze eine remote erreichbare Startstrecke vor dem ersten Start durch eine äußere Identitätsgrenze.
Jedes JWT ist an eine serverseitige Sitzung gebunden (sid-Claim), daher entwertet Abmelden oder Widerrufen unter Einstellungen → Sitzungen das Token sofort auf allen Replikaten und schließt WebSockets. Die Prüfaufbewahrung ist konfigurierbar:
| Variable | Standard | Zweck |
|---|---|---|
AUDIT_RETENTION_DAYS | 180 | Aufbewahrungstage des Sicherheitsprüfprotokolls |
Allgemeines OIDC-Single-Sign-On
Jeder OpenID-Connect-Anbieter mit Ermittlungsdokument kann genutzt werden. Der Ablauf verwendet PKCE (S256), CSRF-Zustand und einen im signaturgeprüften ID-Token verifizierten Nonce. Identitäten werden anhand des stabilen sub-Claims verknüpft.
| Variable | Standard | Zweck |
|---|---|---|
OIDC_ISSUER_URL | nicht gesetzt | Aussteller-URL; Ermittlung unter <issuer>/.well-known/openid-configuration |
OIDC_CLIENT_ID | nicht gesetzt | Beim Anbieter registrierte OAuth-Client-ID |
OIDC_CLIENT_SECRET | nicht gesetzt | OAuth-Clientgeheimnis |
OIDC_DISPLAY_NAME | Single Sign-On | Beschriftung der Anmeldeschaltfläche |
OIDC_SCOPES | openid profile email | Angeforderte Bereiche |
OIDC_CALLBACK_URL | BASE_URL + OIDC-Callback-Route | Beim Anbieter registrierter Redirect-URI |
OIDC_ALLOWED_EMAIL_DOMAINS | nicht gesetzt | Kommaliste; erfordert verifizierte E-Mail aus einer Domain |
OIDC_GROUP_CLAIM | groups | ID-Token-Claim mit Gruppennamen |
OIDC_ADMIN_GROUPS | nicht gesetzt | Kommaliste; Administratorrolle folgt bei jeder Anmeldung der Mitgliedschaft |
OIDC_SYNC_GROUPS | false | true gleicht Libre-Gruppen bei jeder Anmeldung mit dem Claim ab |
OIDC ist nur aktiv, wenn Aussteller-URL, Client-ID und Clientgeheimnis vorhanden sind. Eine bereits von einem unverknüpften lokalen Konto verwendete E-Mail wird abgewiesen statt still zusammengeführt, und die Kontoerstellung beachtet weiterhin ENABLE_SIGNUP.
Die Chat-WebSocket-Zulassung lässt sich einstellen, ohne die Authentifizierung zu schwächen:
| Variable | Standard | Zweck |
|---|---|---|
CHAT_WS_MAX_PAYLOAD_BYTES | 10 MiB | Maximale akzeptierte WebSocket-Nachrichtengröße |
CHAT_WS_MAX_MESSAGES_PER_MINUTE | 120 | Nachrichtenobergrenze pro Verbindung |
CHAT_WS_MAX_ACTIVE_GENERATIONS_PER_USER | 4 | Erlaubte Anbietergenerierungen pro Konto |
CHAT_WS_MAX_CONNECTIONS_PER_USER | 5 | Gleichzeitige authentifizierte Sockets pro Konto |
WEBSOCKET_TICKET_TTL_MS | 30000 | Lebensdauer eines Chat-/Work-Einmaltickets, max. 60 s |
Der Browser tauscht Authorization gegen ein undurchsichtiges Ticket und legt nur diesen kurzlebigen Wert in die WebSocket-URL. Tickets sind einmalig, an Protokoll und Sitzung gebunden und nur als Hash gespeichert, sodass dauerhafte Tokens nicht in Proxyzielprotokollen stehen. Bei CORS_ORIGIN oder BASE_URL muss Origin übereinstimmen. Setze für Remotezugriff mindestens eines; ohne beide bleibt der Filter für lokale Kompatibilität offen. Herkunftslose Upgrades sind für Electron und andere Clients absichtlich möglich, benötigen aber ein gültiges Ticket und dieselben Konto-, Work- und Aufgabenprüfungen. Behandle das Ticket als Authentifizierungsgrenze und begrenze Zugriff mit TLS, Firewall und Proxy.
OAuth
| Variable | Zweck |
|---|---|
GITHUB_CLIENT_ID | GitHub-OAuth-Client-ID |
GITHUB_CLIENT_SECRET | GitHub-OAuth-Clientgeheimnis |
GITHUB_CALLBACK_URL | Überschreibung der GitHub-Callback-URL |
HUGGINGFACE_CLIENT_ID | Hugging Face-OAuth-Client-ID |
HUGGINGFACE_CLIENT_SECRET | Hugging Face-OAuth-Clientgeheimnis |
HUGGINGFACE_CALLBACK_URL | Überschreibung der Hugging Face-Callback-URL |
Ohne Callback-URLs erstellt Libre WebUI Vorgaben aus BASE_URL.
Ollama
| Variable | Standard | Zweck |
|---|---|---|
OLLAMA_BASE_URL | http://localhost:11434 | Ollama-API-Basis-URL |
OLLAMA_TIMEOUT | 300000 | Standardanfrage-Zeitlimit (1,000-3,600,000 ms) |
OLLAMA_LONG_OPERATION_TIMEOUT | 900000 | Langes Zeitlimit (1,000-3,600,000 ms und nicht kleiner als OLLAMA_TIMEOUT) |
OLLAMA_MAX_CONTEXT | 32768 | Automatisch übernommener maximaler Modellkontext (128-2,097,152 Tokens) |
Websuche
| Variable | Standard | Zweck |
|---|---|---|
SEARXNG_URL | nicht gesetzt | Standard-SearXNG-Endpunkt; ein Administrator aktiviert ihn weiterhin unter Einstellungen > Suche |
Libre Claw
| Variable | Standard | Zweck |
|---|---|---|
LIBRE_CLAW_BASE_URL | http://127.0.0.1:8766 | Optionale Libre Claw-Daemon-URL |
LIBRE_CLAW_TIMEOUT_MS | 30000 | HTTP-Anfragezeitlimit |
Work-Laufzeit
Diese Variablen konfigurieren Work auf dem Rechner oder Kubernetes-Cluster des Backends. Docker ist Standard; Helm wählt Kubernetes bei work.enabled=true.
| Variable | Standard | Zweck |
|---|---|---|
WORK_RUNTIME_IMAGE | node:22.22-bookworm@sha256:2d178f2785b96dfbf62a416ca2e40f50e30150b4ff3320d706f0d96e90600eb3 | Festgelegtes Image für Work-Sandboxes |
WORK_DOCKER_COMMAND | docker | Für den Prozess verfügbares Docker-CLI |
WORK_COMMAND_TIMEOUT_MS | 120000 | Standardzeitlimit; Werkzeug kann bis 600000 ms anfordern |
WORK_MAX_OUTPUT_CHARS | 50000 | Grenze erfasster stdout-/stderr-Zeichen je Stream |
WORK_MAX_AGENT_ROUNDS | 48 | Anbieterunabhängiges Modell-/Werkzeugrundenbudget je Ausführung |
WORK_STATUS_BLURB_MODEL | 1 | Auf 0 setzen, um den Modellaufruf für die Agentenstatuszeile nach einer Ausführung zu überspringen |
WORK_MEMORY_LIMIT | 2g | Speicherlimit je Work-Container |
WORK_CPU_LIMIT | 2 | CPU-Limit je Container |
WORK_PIDS_LIMIT | 256 | Prozesslimit je Container |
WORK_PREVIEW_PORT | 4173 | Interner Port des Vorschau-Servers |
WORK_PREVIEW_BIND | 127.0.0.1 | Hostschnittstelle für den veröffentlichten Vorschauport; Compose-Deployments mit nativer Docker Engine brauchen eine erreichbare, nicht öffentliche Bridge-Schnittstelle |
WORK_DOCKER_PUBLISHED_HOST | App-Standard: wie WORK_PREVIEW_BIND; Compose-Standard: host.docker.internal | Backendseitiger Host/IP für veröffentlichte Vorschau-, Bildschirm- und Audioports |
WORK_COMPUTER_SCREEN_PORT | 6080 | Containerport der Work Computer-Bildschirmbrücke (websockify) in GUI-Sandboxes |
WORK_COMPUTER_AUDIO_PORT | 6081 | Containerport der Audiobrücke (websockify → PulseAudio monitor) |
WORK_MAX_ACTIVE_RUNTIMES_GLOBAL | 3 | Gleichzeitige laufzeitgestützte Aufgaben in der Instanz |
WORK_MAX_ACTIVE_RUNTIMES_PER_USER | 2 | Gleichzeitige laufzeitgestützte Aufgaben pro Benutzer |
WORK_MAX_TASKS_GLOBAL | 500 | Maximale persistente Work-Aufgaben der Instanz |
WORK_MAX_TASKS_PER_USER | 100 | Maximale persistente Aufgaben pro Administrator |
WORK_NETWORK_NAME | libre-webui-work | Verwaltetes Brückennetz für vernetzte Aufgaben |
WORK_RUN_LEASE_WAIT_MS | 60000 | Wartezeit auf gemeinsames Laufzeitlease vor Replikakonfliktmeldung (team) |
WORK_RUNTIME_DNS | nicht gesetzt | Erzwungene Resolver-IPs für vernetzte Aufgaben, kommagetrennt |
WORK_DOCKER_SOCKET | DOCKER_HOST bei unix:// oder tcp://, sonst /var/run/docker.sock | Docker-Engine-Endpunkt für Terminals und Diagnose |
WORK_TERMINAL_MAX_SESSIONS_PER_TASK | 2 | Gleichzeitige Browserterminals pro Aufgabe |
WORK_TERMINAL_IDLE_TIMEOUT_MS | 900000 | Inaktivitätszeit bis zum Schließen |
WORK_RUNTIME_IDLE_TIMEOUT_MS | 0 (deaktiviert) | Sandbox nach dieser Inaktivität stoppen, einschließlich Vorschauen |
WORK_HOST_WORKSPACES_ENABLED | false | Hostordner statt Volume erlauben |
WORK_HOST_WORKSPACE_ROOTS | Homeverzeichnis des Serverbenutzers | Mit : getrennte Wurzeln, innerhalb derer Hostarbeitsbereiche liegen müssen |
WORK_RUNTIME_BACKEND | docker | Sandbox-Backend: docker oder kubernetes |
WORK_K8S_NAMESPACE | libre-webui-work | Namespace für Kubernetes-Sandbox-Pods und PVCs |
WORK_K8S_STORAGE_CLASS | Clusterstandard | StorageClass für Arbeitsbereich-PVCs |
WORK_K8S_WORKSPACE_SIZE | 5Gi | PVC-Größe je Aufgabe (echtes Datenträgerkontingent) |
WORK_K8S_POD_READY_TIMEOUT_MS | 900000 | Auf Running warten, einschließlich Imageabruf |
WORK_K8S_POD_GONE_TIMEOUT_MS | 60000 | Auf Verschwinden eines gelöschten Pods warten |
AGENT_CLI_MODELS_ENABLED | nicht gesetzt (Adminschalter, aus) | Agents fest ein-/ausschalten; ohne Wert bleibt es beim standardmäßig deaktivierten Schalter |
TOOLS_ACCESS_MODE | nicht gesetzt (Adminschalter, nur Administratoren) | Chatwerkzeuge auf admins oder all-users fixieren und Schalter sperren |
STT_ACCESS_MODE | nicht gesetzt (Adminschalter, alle) | Sprache-zu-Text auf admins oder all-users fixieren |
TTS_ACCESS_MODE | nicht gesetzt (Adminschalter, alle) | Text-zu-Sprache auf admins oder all-users fixieren |
VOICE_MODE_ACCESS_MODE | nicht gesetzt (Adminschalter, alle) | Freihändigen Sprachmodus auf admins oder all-users fixieren |
VOICE_CLONING_ACCESS_MODE | nicht gesetzt (Adminschalter, alle) | Stimmenklonen auf admins oder all-users fixieren |
TOOLS_PRIVATE_NETWORK_ALLOWLIST | nicht gesetzt | Exakte private Hosts für Werkzeugserver und Webhooks, kommagetrennt und fixiert |
AGENT_CLI_TIMEOUT_MS | 600000 | Laufzeit eines Agent-CLI bis zur Beendigung |
CODEX_OAUTH_MODELS_ENABLED | true | Codex-Anbieter (ChatGPT) Administratoren anbieten |
CODEX_HOME | ~/.codex | Ort der Codex-CLI-Anmeldung (auth.json) |
Agent-CLI-Programme und Codex-OAuth-Zugangsdaten sind knotenlokal. Sie werden nur in solo unterstützt, wo Ermittlung und Ausführung dasselbe Dateisystem sehen. Team führt dauerhafte Chat-Aufträge im externen Worker aus und erfordert AGENT_CLI_MODELS_ENABLED=false sowie CODEX_OAUTH_MODELS_ENABLED=false; andere Werte werden beim Start abgewiesen, statt einen nur auf einer App-Replik vorhandenen Anbieter anzukündigen. Verwende Ollama oder ein Plugin mit gemeinsam gespeicherten oder identisch weitergegebenen Zugangsdaten.
Unter Docker bindet ein Hostarbeitsbereich ein echtes Verzeichnis unter /workspace ein und erlaubt direktes Lesen und Schreiben. Kubernetes lehnt Hostordner ab. Das reduziert bewusst die Sandbox: Lasse WORK_HOST_WORKSPACES_ENABLED aus und beschränke WORK_HOST_WORKSPACE_ROOTS. Pfade werden durch Symlinks aufgelöst, bevor Wurzeln geprüft werden; .ssh, .gnupg, .aws und .config werden abgewiesen.
Agent-CLI-Modelle stellen installierte Programmieragenten (claude, codex) als Chatmodelle bereit, sodass Abonnementagenten ohne API-Schlüssel antworten. Nur Administratoren sehen sie; das CLI läuft als Libre WebUI-Serverbenutzer und erbt dessen Zugangsdaten. Behandle dies wie Shellzugriff für diese Agenten.
Vernetzte Docker-Aufgaben verwenden die Brücke WORK_NETWORK_NAME, auf der Containerkommunikation deaktiviert ist. WORK_RUNTIME_DNS ist der Docker-Ausgangshaken: Nutze einen filternden Resolver; Nicht-IP-Werte werden abgewiesen und protokolliert. DNS begrenzt direkte IP-Ausgänge nicht; ergänze Hostfirewallregeln. Kubernetes verwendet NetworkPolicies und work.networkPolicy.blockedEgressCidrs.
Terminal und Diagnose sprechen direkt mit Docker Engine. Sie folgen WORK_DOCKER_SOCKET, dann DOCKER_HOST – unix://-Socket oder einfacher HTTP-tcp://-Endpunkt wie ein Socketproxy (siehe docker-compose.socket-proxy.yml) – und sonst /var/run/docker.sock. Ein nicht unterstützter Wert (ssh:// oder tcp:// mit DOCKER_TLS_VERIFY) meldet Terminal und Diagnose als nicht verfügbar; Work läuft über das Docker-CLI weiter. Kubernetes verwendet Pod-exec und keinen Docker-Endpunkt.
Work liest die Werte beim Backendstart. Der Vorschauport ist containerintern; Libre WebUI veröffentlicht ihn dynamisch auf Loopback.
Fixiere das Laufzeitimage auf eine geprüfte Version oder Digest. Mehr Parallelität oder Ressourcen erhöhen den Verbrauch autonomer Läufe. WORK_MAX_AGENT_ROUNDS gilt gleich für Ollama und Plugins. Das Sicherheitsbudget ist max(128, WORK_MAX_AGENT_ROUNDS × 8). Beim Erreichen fordert Work eine letzte werkzeuglose Übergabe an und endet in needs_input, statt einen rohen Fehler oder falschen Erfolg zu melden. Ein Folgelauf nutzt denselben Arbeitsbereich. Persistente Werkzeugausgabe ist separat auf etwa 20,000 Quellzeichen plus Markierung begrenzt.
Diese Variablen justieren eine bereits erreichbare Laufzeit. Repository-Compose mit einer Instanz aktiviert sie durch Einbinden des Sockets. Zwei Variablen steuern dies:
| Variable | Standard | Zweck |
|---|---|---|
DOCKER_GID | 0 | Gruppe des Host-Sockets für den Containerbenutzer |
DOCKER_SOCKET | /var/run/docker.sock | Einzubindender Hostpfad des Docker-Sockets |
DOCKER_GID muss die Gruppe aus Sicht eines Containers sein; macOS meldet eine andere. Die Team-Compose-Basis bindet keinen Socket ein und lässt Docker-Work aus, bis docker-compose.team.work.yml hinzukommt. Diese Ebene gibt App und Worker denselben internen gefilterten Proxy, nie Socket oder Gruppe. Der Proxy erlaubt nur benötigte API-Bereiche, aber Containererstellung bleibt eine Hostkontrollzugangsdaten; verwende für stärkere Grenzen einen eigenen oder rootlosen Daemon. Helm bindet keinen Knotensocket ein; aktiviere Pod/PVC mit work.enabled=true.
solo muss wegen SQLite, lokalen Dateien und lokaler Koordination null oder eine App-Replik haben. Helm akzeptiert null zur Pause und verweigert mehr oder Autoscaling. Ein vollständiges team erlaubt mehrere Replikate und externen Worker dank PostgreSQL, S3, PGVector und Redis. Work-Pods skalieren unabhängig; der Worker erhält dasselbe Kubernetes-Image, dieselbe StorageClass und dieselben work.env-Grenzen.
Compose akzeptiert außerdem WEBUI_BIND_ADDRESS (Standard 127.0.0.1) und WEBUI_PORT (8080). Behalte Loopback, außer ein vertrauenswürdiges LAN oder ein Hostproxy muss den Port erreichen.
Anbietermodellermittlung
Ein fehlender oder veralteter Katalog wird automatisch neu ermittelt, damit Neuladen aktuelle Modelle zeigt:
| Variable | Standard | Zweck |
|---|---|---|
PLUGIN_MODEL_DISCOVERY_TTL_MS | 21600000 (6 h) | Alter für Aktualisierung bei nächster Pluginlistenabfrage |
PLUGIN_MODEL_DISCOVERY_RETRY_MS | 600000 (10 min) | Mindestabstand zwischen Versuchen |
PLUGIN_MODEL_DISCOVERY_REFRESH_DEADLINE_MS | 3000 | Wartezeit einer Pluginlistenantwort auf Aktualisierungen |
Eine Aktualisierung jenseits des Zeitlimits wird fertiggestellt und bei der nächsten Anfrage geliefert. Modelle aktualisieren kontaktiert den Anbieter immer.
Schlüssel für Anbieter-Plugins
Umgebungsschlüssel können bereitstellungsweite Vorgaben sein:
| Variable | Anbieter |
|---|---|
OPENAI_API_KEY | OpenAI und 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 von Moonshot AI |
GITHUB_API_KEY | GitHub Models |
HUGGINGFACE_API_KEY | Konfigurierte Hugging Face-APIs |
ELEVENLABS_API_KEY | ElevenLabs TTS |
COMFYUI_API_KEY | ComfyUI-Bereitstellungen mit API-Schlüssel |
Benutzer können ebenfalls Zugangsdaten speichern. Umgebungsschlüssel werden nur für Weiterleitung und Authentifizierung einer nicht überschatteten gebündelten Definition verwendet. Importierte oder beschreibbare Definitionen mit gebündelter ID sowie benutzerdefinierte Routen benötigen Zugangsdaten desselben Kontos; Libre fügt dort keinen Umgebungsschlüssel an und zeigt ihn nicht bei Prüfungen. Vertrauen basiert auf einem kompilierten Manifest-Hash, sodass gemeinsame Containerpfade funktionieren, ohne einem geänderten Manifest zu vertrauen.
Gespeicherte Schlüssel sind an Definition, Quelle, Authentifizierungsvertrag und Routing gebunden. Nach Zieländerung müssen Benutzer neu speichern. Alte ungebundene Schlüssel werden nur für eine exakte gebündelte Definition akzeptiert und bei erster Nutzung gebunden.
Bei Quellstarts wird ein relatives PLUGINS_DIR vom Backendverzeichnis aufgelöst; der gepackte Starter macht einen expliziten relativen Wert vom Aufrufer aus absolut. Libre liest aus Kompatibilität auch backend/plugins und historische Orte. Verschiebe Definitionen nach $DATA_DIR/plugins; die Wiederherstellung meldet sie als externen Zustand und blockiert reine Volume-Snapshots, solange sie dort verbleiben. Verzeichnisse und JSON müssen physische reguläre Einträge sein; Plugin-Symlinks werden nicht verfolgt.
Frontend
| Variable | Standard | Zweck |
|---|---|---|
VITE_API_BASE_URL | Same-Origin-Entwicklungsproxy oder Produktions-API | Frontend-API-Basis-URL |
VITE_WS_BASE_URL | aus API-URL abgeleitet | Absolute ws:-/wss:-Basis für Chat und Work |
VITE_APP_VERSION | von Vite injizierte Paketversion | Angezeigte Version |
VITE_DEMO_MODE | false | Aktiviert Demosimulationen bei true |
VITE_API_TIMEOUT | 300000 | Frontend-API-Zeitlimit in Millisekunden |
VITE_BACKEND_URL | http://localhost:3001 | Von einigen Authentifizierungshilfen verwendet |
VITE_DEBUG_VERBOSE | nicht gesetzt | Ausführliche Frontend-Debugprotokolle |
VITE_LOG_LEVEL | nicht gesetzt | Überschreibt die Frontend-Protokollstufe |
ELECTRON_BUILD | nicht gesetzt | Electron-spezifisches Vite-Verhalten bei true |
VITE_WS_BASE_URL überschreibt alle WebSocket-Fallbacks für Chat und Work-Terminal. Sie darf einen Proxypfad enthalten, muss aber eine absolute ws:- oder wss:-URL ohne Zugangsdaten, Abfrage oder Fragment sein. Ohne Wert verwenden Electron-file:-Clients ws://localhost:3001; Browser leiten von VITE_API_BASE_URL, dann vom Browser-Ursprung ab. Vite leitet den Entwicklungsursprung an das Backend auf Port 3001 weiter.
Wartungsskripte
| Variable | Zweck |
|---|---|
CHANGELOG_AI | Auf 0 setzen, um KI-Entwürfe zu deaktivieren |
CHANGELOG_AI_MODEL | Ollama-Modell für Release-/Changelog-Erzeugung |
CHANGELOG_AI_TIMEOUT_MS | Zeitlimit für KI-Changelog-Erzeugung in Millisekunden |
Beispiel:
CHANGELOG_AI_MODEL=glm-5.2:cloud npm run changelog
CHANGELOG_AI=0 npm run release:minor
Produktionsbeispiel
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