Umgebungsvariablen-Referenz

Tale liest seine Konfiguration aus einer einzigen .env-Datei im Repo-Stammverzeichnis. Etwa ein Dutzend Variablen sind beim ersten Boot Pflicht; der Rest stimmt das Verhalten ab. Diese Seite listet jede Variable, die .env.example mitbringt, was sie als Default hat und welche Oberfläche im Produkt sie konsumiert.

Gruppen sind danach geordnet, wann du sie zuerst brauchst: Domain-Identität, TLS, Secrets, Datenbank, Instanz, Observability, Provider-Verschlüsselung. Ändert sich der Wert einer Variable, starte die Services neu, die sie lesen (docker compose restart platform backend-api backend-worker), damit sie wirkt.

Wie du diese Seite liest

Jede Gruppe ist eine Name | Default | Beschreibung-Tabelle. Variablen, die als Pflicht markiert sind, müssen gesetzt sein, damit docker compose up erfolgreich ist. Optionale Variablen können unset bleiben; die Beschreibung benennt, was das Deaktivieren des Features bedeutet.

Die .env.example-Datei bringt Inline-Kommentare mit, die jede Variable im Kontext erklären; diese Seite ist die strukturierte, gruppierte Referenz für dieselbe Menge.

Domain-Identität (Pflicht beim ersten Boot)

Die SITE_URL muss exakt mit dem übereinstimmen, was der Benutzer im Browser eingibt. Ein nachgestellter Slash, ein fehlender Port oder http statt https brechen den Auth-Callback und produzieren Sign-in-Schleifen. Bedient ein Deployment mehrere Domains, bleibt SITE_URL die kanonische und der Rest kommt in ADDITIONAL_SITE_URLS; ein Eintrag dort muss ein blanker Origin sein, und ein fehlerhafter stoppt das Backend beim Boot, statt eine Domain zu hinterlassen, auf der sich niemand anmelden kann.

TLS

selfsigned lässt Caddy mit einem generierten Cert laufen — der Browser warnt, in Ordnung für Development. letsencrypt braucht eine echte Domain und Ports 80/443 vom öffentlichen Internet erreichbar. external lässt Caddy nur HTTP servieren; ein vorgelagerter Reverse-Proxy terminiert TLS.

Sicherheits-Secrets (Pflicht)

Ersetze die Werte, die in .env.example mitkommen, bevor du die Instanz exponierst — sie sind absichtlich unsichere Platzhalter.

Datenbank

Tale hält zwei Datenbanken: den operativen Speicher (tale_app — Agents, Runs, das Audit-Log) und den Wissens-Korpus (tale_knowledge — Dokument-Chunks, Embeddings, gecrawlte Seiten). Ein Produktions-Stack faltet beide in einen ParadeDB-Service (db, Port 5432, aliasiert knowledge-db). Beide teilen sich DB_PASSWORD, und der Korpus lässt sich für sich auf externe Infrastruktur zeigen.

Die auto-konstruierte operative Form ist postgresql://tale:${DB_PASSWORD}@db:5432 — ohne Datenbanknamen; die operative Datenbank wird aus der Instanz-Konfiguration abgeleitet. Das Application-Backend speichert seine Daten in der tale_app-Datenbank auf demselben Server (überschreib den Namen mit APP_DB_NAME). Der Wissens-Korpus lebt in tale_knowledge mit den Schemata private_knowledge und public_web; diese Variablen setzen die Deployment-Defaults, die alle Organisationen teilen; eine Organisation kann zusätzlich ihren eigenen Korpus und ihren eigenen Bucket unter Einstellungen > Datenresidenz auf eigene Infrastruktur richten (Dateien pro Organisation, live wirksam, kein Neustart), behandelt in Datenresidenz.

Object-Store

Hochgeladene Dokumente, Chat-Anhänge, Audio und generierte Medien leben im gebündelten S3-kompatiblen Store (dem object-store-Service, MinIO). Es ist das einzige Blob-Backend, sodass ein Deployment, das es nicht erreicht, jeden Upload ablehnt. Das Backend seedet die Deployment-Default-Verbindung beim ersten Boot dagegen und legt den Bucket an; eine Org, die ihre Blobs auf einen externen Bucket zeigt (Einstellungen > Datenresidenz), wird vor diesem Default aufgelöst und ist unberührt.

Der Store ist standardmäßig rein intern: presignte URLs werden vom Backend gegen den internen Endpoint signiert und vom Proxy weitergereicht, der Store selbst wird also nie publiziert.

Der erste Boot seedet aus diesen Variablen die Deployment-Default-Verbindung ins Config-Volume (default/object-storage/connection.json) und überschreibt einen bereits vorhandenen Default nie — wer den Store umgebogen hat, behält seine Änderung. Ein Stack, der ohne OBJECT_STORE_PUBLIC_ENDPOINT gebootet ist, gibt Browsern deshalb presignte URLs auf dem internen Hostnamen, und die Variable nachträglich zu setzen ändert daran nichts: Trag "publicEndpoint" in die geseedete Verbindungsdatei ein und starte das Backend neu. tale deploy schreibt die Variable für dich — das hier ist der Fall selbst gebauter Compose-Stacks (Compose selbst fahren).

Audit-Log-Signierung

Die Audit-Hash-Kette wird durch eine HMAC-SHA256-Signatur über ihre Retention- und PII-Scrub-Checkpoints manipulationssicher gemacht (SOC 2 CC7.2, ISO 27001); der tägliche Integritäts-Cron verifiziert sie. Ein zweiter Schlüssel pseudonymisiert die personenbezogenen Daten, die ein fehlgeschlagener Login in der Kette hinterlässt.

Siehe Audit-Log-Integrität für das Verifikationsmodell.

Observability

METRICS_BEARER_TOKEN zu setzen exponiert die Metrics-Endpoints hinter dem Token: /metrics/platform, /metrics/backend (die Metriken des Application-Backends) und /metrics/sla-rules. Siehe Observability-Konfig für die Scrape-Konfiguration.

Provider-Secrets-Verschlüsselung

Wenn beide age-Vars unset sind, speichert Tale providers/*.secrets.json als Klartext-JSON mit Modus 0600. Erreich diesen Modus nur, wenn der Host-Storage at-rest verschlüsselt ist oder die Dateien von externem Tooling erzeugt werden (ein Kubernetes-Secret-Mount, ein Vault-Template). Einen age-Key zu rotieren bedeutet, den neuen Key anzuhängen, jeden Provider in der UI neu zu speichern, dann den alten Key zu entfernen. Siehe Secrets mit SOPS für den vollen Rotations-Walkthrough.

Die Umgebungsvariablen-Schlüsselquelle braucht keinen Deployment-Schalter: Zugangsdaten können statt eines gespeicherten Schlüssels nur den Namen einer Umgebungsvariable halten, solange dieser Name das reservierte Präfix TALE_PROVIDER_KEY_ trägt. Die Schranke ist fail-closed — jeder andere Name wird abgelehnt, das Feld kann also nie auf ein fremdes Deployment-Geheimnis zeigen — und Namen sind auf 40 Zeichen begrenzt. Definier die Variable hier oder in deinem Secret-Manager, damit sowohl die Plattform als auch das Backend sie lesen können; den vollen Mechanismus beschreibt Anbieter. Zugangsdaten mit Subscription-Broker haben einen zweiten, getrennten Namensraum für das Geheimnis, das Tale dem Broker präsentiert: Dieses Feld nimmt einen Umgebungsvariablen-Namen unter dem reservierten Präfix TALE_TOKEN_SOURCE_, begrenzt auf 60 Zeichen. Die zwei Präfixe bleiben mit Absicht getrennt — ein Broker-Geheimnis ist kein Anbieter-API-Schlüssel, und keines der Felder kann eine Variable außerhalb seines eigenen Namensraums benennen.

Connector-OAuth-Apps

OAuth-Connectoren (Gmail, Google Drive, Outlook, Teams, Slack, …) lösen ihre Vendor-App zuerst pro Organisation auf: Eine unter Einstellungen > Connectors > OAuth-Apps hinterlegte App gewinnt für diese Org. Die Umgebung liefert darunter den deployment-weiten Standard (und ist die einzige Quelle für Slack, dessen Event-Signaturprüfung läuft, bevor eine Org bekannt ist). Pro Connector-Slug:

Registriere ${SITE_URL}${BASE_PATH}/api/connectors/oauth2/callback in der Vendor-App, für Slack zusätzlich ${SITE_URL}${BASE_PATH}/api/connectors/slack/events als Events Request URL. Details: Connectors (Develop).

Knowledge-Cloud-Import (Dokumente)

Pro-Benutzer-Autorisierungen für OneDrive / Google Drive unter Wissen → Dokumente sind getrennt von Org-Connectors und vom Login. Auch hier hat eine unter Einstellungen > Connectors > OAuth-Apps hinterlegte Org-App Vorrang — der google-drive-Eintrag wird mit der Connector-Bahn geteilt, OneDrive / SharePoint (Wissens-Import) hat einen eigenen Eintrag; die Ketten unten greifen überall dort, wo die Org keine hinterlegt hat. Registriere diese Redirect-URI in der Microsoft- (oder Google-)App:

${SITE_URL}${BASE_PATH}/api/cloud-import/oauth2/callback

Credential-Auflösung für OneDrive (erster Treffer gewinnt):

Single-Tenant-Entra-App-Registrierungen brauchen eine tenant-spezifische Authorize-URL — /common scheitert mit AADSTS50194. Setze die Tenant-ID (oder organizations / common für eine Multi-Tenant-App). Fehlt sie, fällt Tale auf den Entra-SSO-Issuer-Tenant der Organisation zurück, falls konfiguriert.

Der Microsoft-Freigabe-Dialog fordert Graph Files.Read und Sites.Read.All (OneDrive und SharePoint listen/laden), User.Read (Konto-Label) und offline_access (Refresh-Token für Sync). Die Freigabe ist absichtlich und pro Benutzer — sie kommt nicht mit der Tale-Anmeldung.

Google Drive nutzt nur eine eigene App (kein Login-App-Fallback):

Registriere dieselbe Cloud-Import-Callback-URI am Google-OAuth-Client. Die Freigabe fordert drive.readonly und userinfo.email.

Feature-Flags

Optionale Schalter für Features, die standardmässig nicht aktiviert sind. Jeder Flag schaltet ein Feature beim Boot ein oder aus; das Umschalten braucht einen Neustart des Plattform-Containers.

RAG-Retrieval-Tuning

Optionale Stellschrauben für die Wissensdatenbank-Suche. Der RAG-Pfad bewertet Ergebnisse mit einem Cross-Encoder neu, wenn Re-Ranking an ist. Alle tragen das RAG_-Präfix und werden vom Backend beim Boot gelesen; nach einer Änderung führe docker compose restart backend-api backend-worker aus, damit sie wirkt.

Re-Ranking ist standardmässig deaktiviert, weil es Latenz pro Query addiert und von einem externen Endpoint abhängt. Aktiviere es — indem du RAG_RERANKING_PROVIDER=api setzt und RAG_RERANKING_API_BASE_URL auf einen gehosteten Rerank-Service zeigst — wenn Retrieval-Präzision wichtiger ist als Antwortzeit. Es gibt kein In-Process-Modell zum Herunterladen oder Cachen; mit ausgeschaltetem Re-Ranking gibt die Suche das einfache zusammengeführte BM25-+-Vektor-Ranking zurück.

Deployment-Topologie

Wie viele Replicas jeder zustandslosen Rolle eine Farbe fährt. tale deploy liest sie aus der .env des Projekts; ein Wert außerhalb des Bereichs wird mit einer Warnung geklemmt statt abgelehnt — null Replicas der API ist ein Ausfall, den niemand absichtlich konfiguriert.

Ein Deploy fährt beide Farben gleichzeitig, jede Zahl verdoppelt sich also für die Dauer des Kipps. Setz den Worker zuerst hoch — das ist am günstigsten. Upgrades ist, wann diese Zahlen greifen.

Sitzungen

Lass es unset, um die Standard-Sitzungsdauer zu behalten. Wenn gesetzt, läuft eine inaktive Sitzung serverseitig ab, sobald das Fenster verstrichen ist, während eine aktive sich bei jeder Anfrage weiter verschiebt. Org-Admins können das wirksame Fenster pro Organisation verkürzen — niemals über diese Obergrenze hinaus verlängern — über die Governance-Richtlinie zur Sitzungs-Leerlaufzeit; inaktive Sitzungen unter dieser Richtlinie widerruft ein Lauf, der etwa alle fünf Minuten läuft.

Sandbox-Agent-Turns

Erhöhe den Wert, wenn lange Agent-Turns auf einem langsamen Host als abgeräumte Waisen zurückkommen; die Plattform bindet sich selbst wieder an, das Fenster beendet also nur einen Turn, dessen Abnehmerkette gestorben ist. Das Backend liest ihn beim Start — starte backend-api backend-worker nach einer Änderung neu.

Video-Link-Ingestion (yt-dlp)

Liest Tale einen Video-Link ein, holt es dessen Transkript für den Agenten. YouTube blockiert automatisierten Zugriff von Rechenzentrums-/Server-IPs, sodass dies bei einer Cloud-Bereitstellung fehlschlagen kann. Die Bereitstellung bringt standardmäßig einen PO-Token-Provider verdrahtet mit (das vollständige Bild liefert Video-Ingestion); die Optionen unten sind optionale Überschreibungen und Eskalationen. Keine garantiert eine Umgehung — eine saubere Ausgangs-IP ist der wirksamste Hebel. Vom Backend-Worker gelesen und bei jeder Ingestion neu ausgewertet, sodass eine Änderung ohne Neustart greift.

Keine dieser Optionen garantiert Erfolg gegen YouTubes adaptive Erkennung. Gewöhnliche öffentliche Videos, weniger aggressive Plattformen oder eine Bereitstellung mit Residential-IP bzw. Selbst-Hosting funktionieren üblicherweise auch ohne sie.

Wo das hingehört

Die Variablen hier sind die Kontaktoberfläche des Operators; die UI-Oberfläche, die die meisten von ihnen konsumiert, lebt unter Plattform-Verwaltung. Provider-Keys sind die eine Halb-und-Halb-Sache: die Keys selbst leben in providers/*.secrets.json, aber die UI unter Einstellungen > KI-Anbieter ist, wie du sie in der Praxis hinzufügst und rotierst. Die nächste Lektüre, die sich lohnt, ist Anbieter — sie behandelt die mitgelieferten Connector-Dateien und die reservierten Variablen, die Anbieter-Schlüssel halten.