Umgebungsvariablen-Referenz

Hier findest du Bereitstellungsvariablen, ihre Standardwerte und die Prozesse, die sie benötigen. Die Projektdatei .env ist eine mögliche Quelle; Container-Umgebungen und Secret-Manager können Werte ebenfalls bereitstellen. Die Beispieldatei enthält die zugehörige Quellkonfiguration.

Erstelle betroffene Dienste nach einer Umgebungsänderung über deinen Bereitstellungsablauf neu. docker compose restart behält die vorhandene Containerumgebung. Dateibasierte Organisationskonfiguration hat einen getrennten Lebenszyklus.

Wie du diese Seite liest

Die Tabellen nennen Variablennamen, Standardwerte und Zweck. Erforderliche Werte müssen den jeweiligen Dienst erreichen; einige erzeugt die Bereitstellung automatisch. Optionale Werte können ungesetzt bleiben. Ein angegebener Standard kann aus Compose stammen statt aus dem Prozess selbst.

Nutze zusätzlich die kommentierte Beispieldatei und prüfe bei fehlenden Werten die wirksame Umgebung des betroffenen Dienstes.

Domain-Identität (Pflicht beim ersten Boot)

SITE_URL bezeichnet den kanonischen öffentlichen Ursprung. Protokoll, Hostname und Port müssen zur Browseradresse und zu registrierten Callbacks passen. BASE_PATH ergänzt einen Bereitstellungspfad. Einen abschließenden Schrägstrich normalisiert der Proxy. Weitere Adressen gehören als reine Ursprünge in ADDITIONAL_SITE_URLS. Ungültige zusätzliche Ursprünge verhindern den Backend-Start.

Die Dokumentation verwendet eine eigene Origin. Auf der Plattform-Origin öffnet /docs die interaktive API-Referenz; /openapi.json liefert deren Schema. DOCS_URL ändert den Docs-Host des Proxys. Die Variable installiert keinen Docs-Dienst und schreibt keine Links in vorhandenen Client-Bundles um. TALE_DOCS_URL in den SEO-Buildwerkzeugen und das Build- und Laufzeitpfadpräfix DOCS_BASE_URL des Docs-Dienstes sind separate Einstellungen.

Eine Änderung von TOTP_CLIENT_NAME oder TOTP_ENVIRONMENT gilt für neu erzeugte QR-Codes und Einrichtungs-URIs, auch wenn ein bestehender Schlüssel erneut angezeigt wird, und für danach heruntergeladene Backup-Codes. Sie ändert weder den Schlüssel noch den Namen eines bereits auf deinem Gerät gespeicherten Eintrags. Diesen kannst du bei Bedarf in deiner Authenticator-App umbenennen.

TLS

selfsigned erstellt ein lokales Caddy-Zertifikat. Vertraue der zugehörigen CA nur für deine eigene kontrollierte Installation. letsencrypt benötigt eine öffentliche Domain sowie erreichbare Ports 80/443. Bei external bedient Caddy HTTP hinter einem TLS-Proxy.

Sicherheits-Secrets (Pflicht)

Ersetze die unsicheren Beispielwerte aus .env.example, bevor du die Instanz für andere zugänglich machst.

Datenbank

Tale verwendet tale_app für Anwendungsdaten und tale_knowledge für Textabschnitte, Embeddings und Webseiten. Der Standardaufbau betreibt beide in einem Postgres-Dienst db mit dem Alias knowledge-db. Externe Verbindungen kannst du getrennt konfigurieren.

Die erzeugte Verbindungs-URL lautet postgresql://tale:${DB_PASSWORD}@db:5432/tale_app; APP_DB_NAME ändert den Datenbanknamen. Der Wissenskorpus nutzt die Schemata private_knowledge und public_web. Unter Einstellungen > Datenresidenz kann eine Organisation eigene Verbindungen wählen. Eine gespeicherte URL ändert den Speicherort, überträgt aber keine Daten. Siehe Datenresidenz.

Zwei Dinge musst du wissen, bevor du eine der beiden Datenbanken auf eigene Infrastruktur richtest:

• Der Wissens-Korpus braucht ein installiertes pgvector. Tale legt Schemata und Tabellen auf einer leeren Datenbank selbst an, installiert aber nie Extensions — die Chunk-Tabelle hat eine vector-Spalte, also muss CREATE EXTENSION vector; auf der Zieldatenbank bereits gelaufen sein. ParadeDBs pg_search ist optional: Fehlt es, fällt die Suche auf reine Vektorsuche zurück, statt zu scheitern. Die operative Datenbank braucht gar keine Extensions.
• Verwende eine direkte oder sitzungskompatible Postgres-Verbindung. Job-Benachrichtigungen, Migrationssperren und vorbereitete Abfragen brauchen Sitzungseigenschaften. Prüfe einen verwalteten Verbindungsproxy anhand dieser Anforderungen.

Object-Store

Dateien und Medien verwenden S3-kompatiblen Speicher. Diese Variablen bestimmen den Bereitstellungsstandard. Eine ausdrücklich gewählte Organisationsverbindung hat Vorrang; ein ausgefallener Standardspeicher bedeutet nicht, dass auch die eigenen Buckets aller Organisationen ausfallen.

Der mitgelieferte Proxy macht die Objektroute im Browser erreichbar, ohne den Verwaltungsport des Speichers zu veröffentlichen. Ein externer Speicher kann über seinen eigenen öffentlichen Endpunkt erreichbar sein.

Wie diese Variablen im laufenden Deployment ankommen

Beim Start gleicht das Backend default/object-storage/connection.json mit seiner Umgebung ab. Erstelle backend-api und backend-worker mit den geänderten Werten neu. Die Startmeldungen unterscheiden diese Ergebnisse:

Willst du den Store lieber von Hand führen, trag "managedBy": "operator" in connection.json ein; das Backend fasst die Datei dann nie wieder an. Eine Datei ganz ohne managedBy — vor diesem Verhalten geschrieben — übernimmt das Backend nur, wenn sie noch denselben Bucket am selben Endpoint nennt wie die Umgebung; hattest du sie von Hand umgebogen, bleibt deine Änderung stehen.

Bucket-Rechte: Das Backend prüft mit HeadBucket, ob der Bucket existiert, und legt ihn nur an, wenn nicht. Ein Schlüssel, der Objekte lesen, schreiben und löschen darf, aber keine Buckets anlegen, reicht also — solange du den Bucket selbst anlegst. Presignte Up- und Downloads laufen im Browser, ein externer Bucket braucht deshalb zusätzlich eine CORS-Policy, die den Origin deines Deployments mit GET, PUT und HEAD zulässt — siehe Datenresidenz.

Datenschutz im Audit-Log

Ein Pepper pseudonymisiert personenbezogene Daten fehlgeschlagener Anmeldungen. Frühere Releases haben zusätzlich TALE_AUDIT_SIGNING_KEY und TALE_AUDIT_SIGNING_KEY_PREVIOUS erzeugt. Beide liest nichts mehr, einen vorhandenen Wert kannst du also behalten oder löschen.

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

Observability

Mit METRICS_BEARER_TOKEN schützt der Proxy die Routen /metrics/platform, /metrics/backend und /metrics/sla-rules. Überwachung einrichten erklärt Inhalt und Grenzen der Messwerte.

Provider-Secrets-Verschlüsselung

SOPS schützt unterstützte Geheimnisdateien der Konfiguration. Aktuelle Anbieterzugangsdaten in der Datenbank verwenden ENCRYPTION_SECRET_HEX aus dem Abschnitt zu Sicherheitsgeheimnissen.

Ohne age-Schlüssel schreibt der SOPS-Helfer unterstützte Geheimnisdateien als Klartext mit Modus 0600. Bereits verschlüsselte Dateien brauchen weiterhin ihren Schlüssel. Lies Geheimnisse mit SOPS, bevor du eine der Variablen änderst.

Anbieterzugangsdaten können stattdessen eine Variable mit Präfix TALE_PROVIDER_KEY_ und höchstens 40 Zeichen referenzieren. Zugangsdaten für Abonnement-Broker verwenden das getrennte Präfix TALE_TOKEN_SOURCE_ mit höchstens 60 Zeichen. Diese Felder speichern Variablennamen, keine Geheimniswerte. Übergib Werte an die Backend-Prozesse und erstelle betroffene Container nach Änderungen neu. Anbieter beschreibt die Einrichtung.

Connector-OAuth-Apps

OAuth-Connectors (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

Diese Variablen steuern Backend-Anmeldung, Datei-Ereignisse und Betreiberrechte. Erstelle die betroffenen Backend-Rollen nach einer Umgebungsänderung neu. Nur den Webcontainer zu ändern reicht nicht aus.

Die Freigabe privater Crawl-Ziele betrifft zwei Grenzen: Website-Registrierung und Crawler-Anfragen sowie die Validierung der imageUrl eines Produkts. Ohne Freigabe erhält ein privates Website-Ziel 400 WEBSITE_DOMAIN_NOT_CRAWLABLE; eine private Produktbild-URL erhält 400 INVALID_BODY. Bei Produktbildern wird nur die Hostzeichenfolge geprüft, ohne Bildabruf oder DNS-Auflösung. Website-Registrierung und Crawler prüfen zusätzlich die aufgelösten Adressen. Aktiviere die Variable nur, wenn die Installation diese privaten Ziele braucht. Sie ist unabhängig von der Freigabe privater Modellanbieter.

Deployment-Topologie

Diese Werte prägen die Anwendungsrollen eines Workspace-Deployments: die Replikatzahlen, die tale deploy aus der Projektumgebung liest und mit einer Warnung auf den unterstützten Bereich begrenzt, und wie viel Arbeit ein einzelnes Worker-Replikat gleichzeitig übernimmt.

Bei einem Workspace-Deployment laufen vorübergehend beide Farben. Plane Kapazität für diese Überschneidung. Erhöhe die Rolle, deren gemessene Last den Engpass bildet. Mehr Replikate brauchen auch mehr Datenbankverbindungen und Arbeitsspeicher. Siehe Upgrades.

Sitzungen

Ohne Wert gilt die normale Sitzungsdauer. Mit gesetztem Limit läuft eine inaktive Sitzung serverseitig ab; Aktivität verschiebt das Fenster. Organisationsadmins können es über die Richtlinie zur Sitzungsinaktivität weiter verkürzen. Die zugehörige Bereinigung läuft ungefähr alle fünf Minuten.

Support-Link

Trag hier deinen eigenen Helpdesk ein, damit Personen nach einem Fehler das Team erreichen, das dein Deployment betreibt. Kennt die Fehlerseite die Organisation, hängt der Link organizationId=<id> an den Query-String an, hinter eine bereits vorhandene Query, und ersetzt einen organizationId-Parameter, den die URL schon trägt. Jeder andere Wert, etwa mailto: oder eine URL ohne Schema, wird mit einer Warnung im Log des Dienstes platform ignoriert, und der Link behält den Standardwert.

MCP-Endpunkt

Coding-Agents im Terminal und serverseitige Clients senden keinen Origin, für sie greift die Prüfung nie. Eine Browserseite einer anderen Website sendet einen, und über einen API-Schlüssel in einer solchen Seite würde diese Website den Endpunkt erreichen. Solange die Durchsetzung aus ist, protokolliert der Endpunkt jede Anfrage von einem Origin außerhalb der Liste als [mcp] origin-mismatch mit dem Origin, der Organisation und der Person. Lies diese Zeilen, um zu sehen, welche deiner Clients einen Origin senden, bevor du TALE_MCP_ORIGIN_ENFORCE=true setzt, und trag ihre Origins in TALE_MCP_ALLOWED_ORIGINS ein.

Die vier Einstellungen am Ende der Tabelle gehören zur Anmeldung von Coding-Agents, mit der sich ein Agent ohne API-Schlüssel mit dem MCP-Endpunkt verbindet. Solange sie nicht vollständig ist, verbinden sich Agents mit einem API-Schlüssel, und beide Wege bleiben ausgeschaltet. Um ein Client-Metadatendokument zu lesen, braucht das Backend ausgehendes HTTPS zum Host des Agents. Es ruft nie ein Dokument von einer privaten Adresse oder vom eigenen Deployment ab und folgt nie einer Weiterleitung. Die Selbstregistrierung nimmt nur die Scopes für Coding-Agents an und ist pro Quelladresse und pro Deployment begrenzt.

Sandbox-Infrastruktur

Der Sandbox-Spawner liest die folgenden Einstellungen. Übergib sie seiner Umgebung und erstelle den Dienst nach einer Änderung neu. SANDBOX_MAX_SESSIONS legt die gemeinsame Kapazität aller Organisationen fest. Die drei Arbeitslimits einer Organisation ergeben automatisch ihre Gesamtsumme; liegt sie über dieser Kapazität, kannst du die Limits nicht speichern. Unter Sandboxes verwaltest du die Limits und siehst tatsächliche Laufzeitzahlen und Host-Messwerte getrennt von der Kontingentbelegung.

Die Backend-Einstellungen oben müssen API und Worker erreichen. Erstelle beide Dienste nach einer Änderung neu. Der Spawner prüft freien Arbeitsspeicher und Plattenplatz auch beim erneuten Belegen einer freigegebenen Sitzung; daher kann auch ein warmer Arbeitsbereich auf Kapazität warten.

Verbundene Geräte prüfen Arbeitsspeicher und freien Speicherplatz nach denselben Regeln wie ein lokaler Docker-Host; ihre konfigurierte Session-Obergrenze bleibt bestehen.

Ein absichtlich gestoppter Docker-Daemon bleibt für den nächsten Befehl bereit; Zustandsprüfungen starten ihn nicht. Eine fehlgeschlagene Prüfung sperrt sofort neue Arbeit, stoppt aber allein noch nicht die Session. Dafür müssen mindestens drei abgeschlossene Prüfungen über einen Zeitraum von mindestens fünf Sekunden fehlschlagen. Eine erfolgreiche Prüfung oder eine neue Engine setzt diese Fehlerhistorie zurück. Ein bestätigter Startfehler oder ein unerwartetes Ende der Engine kann die Wiederherstellung sofort auslösen. Der Spawner kann dann eine inaktive, nicht angepinnte Session nach einer atomaren Aktivitätsprüfung stoppen und ihren Arbeitsbereich für den nächsten Start behalten. Unter Docker geht beim Stoppen der gesamten Session ihr innerer Docker-Speicher verloren; beim automatischen Leerlaufstopp nur der inneren Engine bleibt er erhalten. Beschäftigte oder angepinnte Sessions bleiben bestehen und lehnen neue Starts ab, bis Docker wieder antwortet oder der Betreiber die Störung behebt.

Behalte bei einem schrittweisen Upgrade für jeden alten Spawner sein bisheriges, fest referenziertes Runtime-Image bei, bis der Spawner ersetzt ist. Ändere keinen Runtime-Tag, den ein alter Spawner noch verwendet: Er unterscheidet vorübergehende Prüfungsfehler nicht von bestätigten Ausfällen. Ein neuer Spawner mit einer älteren Runtime lehnt neue Arbeit bei einem fehlerhaften Zustand ab und behält die üblichen Grenzen für Leerlauf und Lebensdauer bei.

Ein Spawner im Container prüft Dockers Daten-Dateisystem automatisch, wenn sich sein vorhandener /etc/hostname-Mount anhand des Daemons verifizieren lässt. Gelingt die Erkennung nicht, bleibt die Prüfung der Arbeitsbereiche aktiv; /health meldet die Docker-Datenträgerüberwachung als unavailable. Ein ausdrücklich konfigurierter, schreibgeschützter Mount des Docker-Datenverzeichnisses hat Vorrang. Lässt er sich nicht verifizieren oder lesen, wartet die Zulassung neuer Arbeit, bis er verfügbar ist. Lies zur Konfiguration docker info --format '{{.DockerRootDir}}' aus und verwende diesen tatsächlichen Host-Pfad. Docker Desktop und entfernte Daemons können einen anderen Aufbau benötigen. Ergänze bei direktem Compose den folgenden Override und übergib beide Variablen an den Sandbox-Dienst:

services:
  sandbox:
    environment:
      SANDBOX_DOCKER_DATA_ROOT: ${SANDBOX_DOCKER_DATA_ROOT}
      SANDBOX_DOCKER_DATA_PATH: /var/lib/tale-sandbox/docker-data
    volumes:
      - ${SANDBOX_DOCKER_DATA_ROOT}:/var/lib/tale-sandbox/docker-data:ro

Eine Speichergrenze für die Zulassung ist keine Speicherquote pro Sitzung. Docker-Named-Volumes haben kein portables Größenlimit, und die Durchsetzung einer Kubernetes-PVC-Größenanforderung hängt vom Storage-Backend ab. Nutze für harte Quoten ein Dateisystem oder eine Storage-Klasse mit Quotenunterstützung. Überwache separat eingehängte containerd-Speicher, Volume-Verzeichnisse und externe Volume-Treiber zusätzlich zu Arbeitsbereichen, Image-Layern und Build-Caches.

Kubernetes-Sitzungen verwenden /readyz für die Startprüfung und /livez für die Lebendigkeitsprüfung des Daemons. Ein absichtlich gestoppter innerer Docker-Daemon gilt beim Start als bereit; ein laufender Docker-Daemon muss auf seine Gesundheitsprüfung antworten. Die Lebendigkeitsprüfung erfasst nur den Sandbox-Daemon, damit Fehler bei Abhängigkeiten keine beschäftigte Sitzung neu starten. Ein blockierter Daemon kann auch bei angehefteter Sitzung neu starten. Docker- und Egress-Diagnosen erscheinen unter /healthz.

Eine bereits aktive Generation wird nicht erneut angerechnet. Ein Workflow ohne inneres Docker behält die Identität und Werkzeuge seines Agenten, startet aber keinen Docker-Daemon und hält keine Build-Cache-Hilfscontainer aktiv. Ohne expliziten Wert für SANDBOX_AGENT_MEMORY gilt pro Session standardmäßig 4g ohne inneres Docker oder 8g mit Docker, auch wenn andere Sessions im Deployment Docker nutzen. Ein expliziter Wert gilt für beide Varianten. Die Grenzen sind Obergrenzen, kein reservierter Arbeitsspeicher.

Bei voller Kapazität kann der Spawner eine freigegebene, nicht angepinnte Session im Leerlauf schon vor Ablauf des Leerlauffensters stoppen, um neue Arbeit zuzulassen, zuerst die am längsten untätige. Der Daemon muss bestätigen, dass keine Arbeit läuft; beschäftigte Sessions und Sessions mit unbekanntem Zustand bleiben geschützt. Das dauerhafte Arbeitsverzeichnis oder Volume bleibt beim Stoppen erhalten. Lässt sich keine Session sicher freigeben, blockiert die Kapazitätsgrenze weiterhin neue Starts. Dasselbe gilt, wenn der freie Speicher des Hosts unter SANDBOX_MIN_FREE_MEMORY fallen würde. Solange der Datenträger mit den Arbeitsverzeichnissen der Sessions unter SANDBOX_MIN_FREE_DISK liegt, wartet neue Arbeit, ohne dass Sessions im Leerlauf gestoppt werden: Eine gestoppte Session behält ihr Arbeitsverzeichnis. Erst unterhalb von SANDBOX_CRITICAL_FREE_DISK stoppt der Spawner freigegebene Sessions mit Docker in der Sandbox im Leerlauf sofort, weil ihr Stopp ihre inneren Image-Speicher entfernt.

Datensätze im Agent-Laufzeit-Protokoll, einschließlich unvollständiger Zeilen, sind auf 8 MiB begrenzt. Zu große oder unvollständige Ausgaben führen zu einem ausdrücklichen Fehler; eine begrenzte Fortschrittsvorschau gilt nie als vollständiges strukturiertes Ergebnis. Vollständige Endantworten bleiben getrennt von dieser Vorschau erhalten.

Auch die Wiederaufnahme einer freigegebenen, noch laufenden Session prüft die Speicherreserve und reserviert vorab den erwarteten Arbeitsspeicher. Gleichzeitige Wiederaufnahmen teilen sich diese Berechnung. Eine Antwort „beschäftigt“ lässt sich erneut versuchen; sie löscht weder das Arbeitsverzeichnis noch unterbricht sie bereits belegte Sessions. Diese Reservierungen begrenzen nicht den späteren Speicherzuwachs aktiver Werkzeuge oder der Builder einer Organisation.

Ist Docker in Agent-Sandboxes aktiviert, startet der Daemon automatisch beim ersten Docker-Befehl. Agenten müssen keinen Modus wählen. Nach fünf Minuten ohne verbundene Clients stoppt er nur, wenn kein Container läuft, neu startet oder pausiert ist und für alle Container die automatische Neustartregel deaktiviert ist; bei unbekanntem Zustand läuft er weiter. Der nächste Befehl startet ihn mit denselben Images, Volumes und demselben Arbeitsverzeichnis. Sind beim Start des Session-Containers bereits Container-Metadaten vorhanden, startet der Daemon sofort, damit die Neustartregeln weiterhin greifen. Isolation, Berechtigungen und Speichergrenzen des Deployments bleiben dabei unverändert.

Session-Kapazität bemessen

Fehlt SANDBOX_MAX_SESSIONS auf einem Docker-Host, bemisst der Spawner die Kapazität nach Speicher und CPUs des Hosts (eine Session je 768 MiB über der Reserve, höchstens zwei je CPU: Ein Host mit 16 GiB und 8 CPUs erhält 16 Sessions, einer mit 64 GiB und 16 CPUs 32; ein Host mit 16 GiB erhält 9, wenn Agent-Sessions einen eigenen Docker-Daemon betreiben) und lässt eine neue Session nur zu, solange der Host SANDBOX_MIN_FREE_MEMORY frei behält, wobei er mitzählt, was noch startende und eben gestartete Sessions gleich belegen werden. Eine Lastspitze neuer Sessions, die den Host überbuchen würde, wartet deshalb, statt zu starten; Sessions, die bereits laufen, hindert diese Prüfung nicht daran, weiter zu wachsen. Steht die CPU des Hosts unter Druck (SANDBOX_CPU_PRESSURE_PERCENT), starten neue Sessions ebenso einzeln, statt die Last weiter zu erhöhen. Jeder Lauf eines Projektagenten, der gleichzeitig mit einem anderen arbeitet, bekommt eine eigene Session, einen Agenten-Worker: Ein Agent, der an drei Aufgaben gleichzeitig arbeitet, betreibt drei Sessions, jede mit ihrem eigenen Limit SANDBOX_AGENT_MEMORY. Diese beiden Einstellungen begrenzen also, wie viel Agentenarbeit parallel läuft. Lege die Kapazität selbst fest unter Kubernetes, mit einem entfernten Docker-Daemon oder wenn auf dem Host auch andere speicherhungrige Dienste laufen: Teste dann die Aufgaben, die deine Bereitstellung gleichzeitig ausführen soll. Browser-Rendering und Docker-Builds haben unterschiedliche Lastspitzen; berücksichtige Agents, Workflows und Crawling aller Organisationen. Ein freier Session-Platz garantiert keine ausreichenden Ressourcen.

Miss unter Docker den Ressourcenbedarf, während typische Aufgaben gleichzeitig laufen. Wiederhole diesen Befehl während des Durchlaufs; eine Messung im Leerlauf zeigt keine Lastspitzen:

docker stats --no-stream --format 'table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}'

Ziehe den Bedarf von Betriebssystem, Plattformdiensten, Datenbanken und Build-Cache-Hilfscontainern sowie eine Sicherheitsreserve vom Host-Speicher ab. Teile den verbleibenden Speicher durch den gemessenen Spitzenbedarf je aktiver Session und runde ab. Beispiel: Ein Host mit 32 GiB, davon 8 GiB für Dienste und Reserve, und einem gemessenen Spitzenbedarf von 3 GiB je Session ergibt (32 - 8) / 3 = 8 Sessions. Das ist ein Rechenbeispiel, kein Benchmark. Bei gemischten Aufgaben addierst du die gleichzeitig auftretenden Spitzen. Prüfe außerdem CPU-Auslastung und Aufgabendauer, bevor du die Grenze erhöhst.

Die 4 GiB oder 8 GiB eines Agents sind eine Speicherobergrenze; beim Start reserviert er diesen Speicher nicht. Acht Agents mit laufenden Docker-Builds können daher deutlich mehr Speicher benötigen als acht überwiegend untätige Sessions. Miss unter typischer Last und halte Reserven frei. Erhöhe die Kapazität erst auf 16 oder mehr, wenn der Host die Last dauerhaft trägt. Verringere vor einer Absenkung alle Organisationssummen, die über dem neuen Wert liegen. Die Standardlimits einer Organisation ergeben 6; eine kleinere Bereitstellungskapazität braucht entsprechend kleinere Organisationslimits.

Eine Kapazitätsänderung anwenden

Ergänze oder ändere diese Zeile in der .env deiner Bereitstellung. Behalte die übrigen Einträge bei. Explizite Werte gelten auch nach Upgrades weiter; ohne einen bemisst ein Docker-Host die Kapazität wie oben beschrieben nach seinem Speicher, und Kubernetes verwendet 8.

SANDBOX_MAX_SESSIONS=8

Erstelle bei einem selbst verwalteten Compose-Stack nur den Sandbox-Dienst mit seinem vorhandenen lokalen Image neu:

docker compose up -d --no-deps --no-build --pull never sandbox

Verwende dasselbe Projekt, dieselben -f-Dateien und dieselben Optionen für Umgebungsdateien wie beim laufenden Stack. Ein Neustart allein lädt eine geänderte .env nicht. Für CLI-verwaltete Installationen folgst du dem Deployment-Ablauf unter Upgrades. Setze unter Kubernetes die Variable im Deployment des Sandbox-Spawners und führe dessen Rollout aus.

Prüfe die neue Bereitstellungskapazität unter Sandboxes. Bei Organisationslimits von 2/2/2 und einer Kapazität von 8 zeigt die Summe 6 / 8. Bestehende Organisationseinstellungen bleiben erhalten; zum Speichern muss ihre Summe weiterhin in die aktuelle Kapazität passen. Die Kapazitätsänderung erhöht keine CPU- oder Speichergrenze eines Containers.

Nach einem Upgrade

Die Standardkapazität lag bisher bei 16, und Organisationen aus früheren Versionen wurden mit den Limits 2/4/4 angelegt, also einer Summe von 10. Eine Bereitstellung, die SANDBOX_MAX_SESSIONS nie gesetzt hat, startet mit der neuen Version daher mit einer Kapazität von 8 und Organisationen, deren gespeicherte Summe darüber liegt. Laufende Arbeit ist davon nicht betroffen, und jede Organisation lässt weiterhin Arbeit unter ihren gespeicherten Limits zu; nur das Speichern der Sandbox-Seite bleibt gesperrt, bis die Summe passt, und niedrigere Limits lassen sich weiterhin speichern. Setze entweder SANDBOX_MAX_SESSIONS=16 explizit, um die bisherige Kapazität zu behalten, oder bitte jede betroffene Organisation, ein Limit zu verringern.

Ab dieser Version erhält eine Docker-Bereitstellung, die SANDBOX_MAX_SESSIONS nie gesetzt hat, eine nach dem Host-Speicher bemessene Kapazität statt 8, nie weniger als 8. Sie kann mehr Sessions gleichzeitig zulassen als zuvor, und das nur, solange der Host Speicher übrig hat. Ein expliziter Wert legt die Kapazität fest und schaltet die adaptive Speicherprüfung beim Start einer Session ab; bemiss ihn nach gemessenen Speicherspitzen. Die Datenträgerprüfung bleibt aktiv.

Diese bemessene Kapazität beträgt jetzt außerdem höchstens zwei Sessions je CPU; ein Host mit viel Speicher und wenigen CPUs erhält daher weniger Sessions als zuvor (ein Host mit 16 GiB und 4 CPUs: 8 statt 19). Steht die CPU des Hosts unter Druck, starten neue Sessions zudem einzeln (SANDBOX_CPU_PRESSURE_PERCENT, 0 schaltet das ab). Ein expliziter Wert für SANDBOX_MAX_SESSIONS bleibt unverändert.

Docker-Build-Caches

Die Vorbereitung des gemeinsamen Build-Caches verwendet SANDBOX_BUILDKITD_PROVISION_TIMEOUT_MS (standardmäßig 5 Sekunden). Eine Session wartet höchstens so lange oder ein Viertel ihres gesamten Startbudgets, falls das kürzer ist. Danach nutzt sie ihren lokalen Builder. Die gemeinsame Vorbereitung hat ein eigenes begrenztes Zeitbudget: Wird die Wartezeit einer Session abgebrochen, läuft die Vorbereitung für andere Sessions weiter. Eine Session, die bereits ihren lokalen Builder nutzt, wechselt bei einem verspäteten Ergebnis nicht nachträglich zum gemeinsamen Builder. Registry-Mirrors werden parallel vorbereitet. Die Zahl gleichzeitiger Schritte des gemeinsamen Builders ergibt sich aus seiner abgerundeten CPU-Grenze und beträgt mindestens eins; seine Speichergrenze gilt weiterhin. Die Vorbereitungszeit wird vom verbleibenden Startbudget der Session abgezogen.

Docker-Build-Caches sind nach Organisation getrennt. Jede Organisation nutzt einen privilegierten Builder und drei Registry-Mirrors ohne erhöhte Rechte. Sobald keine Session mehr auf sie zugreifen könnte, stoppen die Hilfscontainer nach SANDBOX_BUILDKITD_IDLE_MS (10 Minuten), und die Registry-Mirrors werden mit ihren Caches entfernt, denn der eigene Cache des Builders behält die Basis-Layer, die seine Builds genutzt haben. Der nächste Build startet den Builder mit seinem erhaltenen Cache-Volume neu und erstellt die Mirrors neu. Unmittelbar bevor der Builder stoppt, kürzt der Spawner seinen Cache auf SANDBOX_BUILDKITD_IDLE_CACHE, denn seine Speicherbereinigung läuft nur, solange er läuft. Der Cache einer gestoppten Organisation wird danach nicht weiter gekürzt; nach SANDBOX_BUILDKITD_CACHE_RETENTION (14 Tage) ohne Build werden ihre Hilfscontainer und Caches entfernt, sonst gehen sie mit der Organisation. Solange der Datenträger der Sessions unter SANDBOX_MIN_FREE_DISK liegt, gehen die Caches gestoppter Organisationen früher, die am längsten gestoppten zuerst. Das Netzwerk und das Cache-Volume des Builders bleiben für die Wiederverwendung bestehen. Kubernetes-Sessions nutzen ihren eigenen inneren Docker-Builder; der Kubernetes-Abgleich ruft für diese Hilfscontainer keine Docker-CLI auf.

Der Spawner füllt den ersten verfügbaren Docker-Adresspool mit Organisationsnetzwerken, bevor er zum nächsten wechselt. Standardmäßig erhält jedes Netzwerk ein /23 mit 512 Adressen; ein ansonsten freies /16 bietet damit Platz für 128 Organisationsnetzwerke. Kleinere in Docker konfigurierte Subnetze bleiben kleiner. Der Spawner schließt vorhandene Docker-Netzwerke, Routen und DNS-Serveradressen auf dem Host des Docker-Daemons sowie 172.31.0.0/16 für ältere Runtime-Images aus und prüft anschließend das angelegte Netzwerk.

Auch bei einem entfernten Docker-Daemon erfasst der Spawner dessen Host über einen kurzlebigen Container aus dem konfigurierten BuildKit-Image. Dieser läuft im Host-Netzwerk-Namespace mit schreibgeschütztem Dateisystem, ohne Capabilities und ohne Mounts. Scheitert diese Abfrage oder bleibt kein sicheres Subnetz frei, bauen Sessions lokal ohne gemeinsamen Cache. Ein ungenutztes eigenes Netzwerk mit ungültigem Subnetz legt der Spawner neu an; belegte und fremde Netzwerke bleiben erhalten.

Beim Upgrade entstehen leere Organisationscaches; die alten globalen Cachedaten bleiben vorerst erhalten. Alte Hilfscontainer stoppen automatisch, sobald keine laufende Session mehr auf sie angewiesen ist. Sind sie länger als SANDBOX_BUILDKITD_CACHE_RETENTION (14 Tage) gestoppt und ist weiterhin keine Session auf sie angewiesen, entfernt der Spawner diese Hilfscontainer und die vier alten Cache-Volumes (tale-buildkitd-cache sowie tale-buildkitd-mirror-cache-docker-io, -ghcr-io, -quay-io), jeweils nur, solange sie die alte Build-Cache-Markierung ohne Organisation tragen, und protokolliert jede Entfernung; off behält sie. Lass alte angepinnte Sessions auslaufen oder stoppe sie, um den Übergang abzuschließen; bis dahin bleibt der alte gemeinsame Cachedienst erreichbar. Browserautomatisierung nutzt Chromium ohne grafische Oberfläche. Die Live-Ansicht und manuelle Browserübernahme sind entfernt.

Images der inneren Docker-Engine

Ist der gemeinsame Build-Cache aktiv, lädt die innere Docker-Engine einer Session Docker-Hub-Images über den docker.io-Registry-Mirror ihrer Organisation, also denselben Cache, den ihre Builds nutzen. Läuft dieser Mirror nicht, lädt sie direkt von Docker Hub. Images aus anderen Registries lädt sie direkt. Geht eine innere Engine mit mehr als 10 GiB an Images und Build-Cache in den Leerlauf, entfernt sie vorher ihre unbenannten, unbenutzten Images und kürzt ihren Build-Cache auf die zuletzt genutzten 5 GiB; benannte Images, Container und Volumes bleiben. Unter Kubernetes begrenzt stattdessen die Größenbeschränkung des Volumes den inneren Speicher, wenn sie unter 10 GiB liegt.

Innere Docker-Netzwerke

Die automatische Auswahl prüft unter Docker und Kubernetes IPv4-Routen und Gateways aus allen Routingtabellen, Adressen und Präfixe der Schnittstellen, DNS-Server sowie die aufgelösten Adressen der beim Containerstart konfigurierten Proxy- und Gateway-Hosts. Hosts, die erst während eines Agent-Turns übergeben werden, fehlen in dieser anfänglichen Erfassung. Ein später angeschlossenes Docker-Organisationsnetzwerk berücksichtigt sie ebenfalls. Die Runtime bevorzugt ein freies 172.31.0.0/16 und prüft danach andere private /16-Bereiche. Das erste /24 gehört zu docker0; innere Compose-Netzwerke erhalten /24-Blöcke aus demselben Pool. Im automatischen Modus startet die Session nicht, wenn Abfragen scheitern oder kein privater Bereich frei bleibt.

Aus seinem eigenen Netzwerk-Namespace kennt ein Pod nicht die vollständigen Pod-, Service- und VPC-CIDRs des Clusters. Setze für DinD auf Kubernetes SANDBOX_DIND_INNER_POOL auf ein privates /16, das du gegen all diese Netze geprüft hast. Auch ein vorgegebener Pool scheitert bei jeder erkannten Überschneidung oder einem ungültigen Wert. Bleiben einzelne Abfragen ohne Ergebnis, nennt die Runtime sie in einer Warnung und kann mit dem vorgegebenen Pool fortfahren. Den nicht sichtbaren Adressraum musst du selbst berücksichtigen.

Starte nach einer Änderung dieses Pools den Spawner neu und erstelle bestehende Sessions neu, damit sie den Wert übernehmen. Ein Runner-Neustart innerhalb desselben Kubernetes-Pods behält dessen Umgebung und den inneren Docker-Speicher bei.

Der Egress-Proxy erlaubt DNS-Anfragen an die geprüften Nameserver-IP-Adressen aus seiner /etc/resolv.conf, auch an einen privaten Cluster-DNS-Dienst. Jede Ausnahme gilt nur für diese eine IP und den UDP-/TCP-Zielport 53. Andere private Ziele und die Weiterleitung zwischen angeschlossenen Netzwerken bleiben gesperrt.

IPv6-Weiterleitungsschutz

Halte sandbox, sandbox-egress und SANDBOX_RUNTIME_IMAGE beim Upgrade auf demselben Release. Bevor der Spawner unter Docker das Build-Netzwerk einer Organisation anschließt, prüft er den Weiterleitungsschutz der Session. Compose und generierte Docker-Session-Container deaktivieren IPv6 mit net.ipv6.conf.all.disable_ipv6=1 und net.ipv6.conf.default.disable_ipv6=1. Übernimm beide Werte in eigene Docker-Definitionen.

Kubernetes-Pods erhalten nicht automatisch unsichere Sysctls. Der Egress-Proxy braucht eine funktionierende IPv6-Firewall oder deaktiviertes IPv6 in seinem Netzwerk-Namespace. Ist die IPv6-Firewall nicht verfügbar, versucht der Entrypoint IPv6 dort zu deaktivieren und prüft danach den Standardwert und jede Schnittstelle. Ein schreibgeschütztes /proc/sys oder fehlende Schreibrechte können das verhindern; ohne Schutz für weiterhin aktives IPv6 startet der Proxy nicht. Konfiguriere den Egress-Pod vor dem Deployment mit den Netzwerkeinstellungen, die dein Cluster erlaubt.

SSH-Zugang zu Repositories

Die native Sandbox enthält OpenSSH und netcat-openbsd. Gib einen austauschbaren, auf das Repository beschränkten Schlüssel als benanntes Agent-Secret frei und lade ihn im berechtigten Lauf über stdin in ssh-agent. Die privaten Bytes bleiben in der Umgebung; schreibe keine Schlüsseldatei und gib sie nie aus. Ein von einem Mitglied gestarteter Lauf erhält keine Agent-Secrets. Git-Commits nutzen den Namen und die E-Mail des Workspace-Eigentümers auch ohne Freigabe eines GitHub-Connectors.

Interne Sitzungen nutzen ihren bestehenden HTTP_PROXY für ausgehende Verbindungen. Direktes SSH kann in diesem Netz nicht auf externe DNS-Auflösung bauen. Nutze den HTTP-CONNECT-Tunnel des Proxys und einen erlaubten Port. GitHub unterstützt SSH über ssh.github.com:443; prüfe den Host gegen GitHubs veröffentlichte Fingerabdrücke, wie unter SSH über Port 443 beschrieben. Lege eine öffentliche Known-Hosts-Datei mit dem unabhängig geprüften Schlüssel an und konfiguriere den Befehl, nachdem der Agent den privaten Schlüssel geladen hat:

import os
import shlex
import subprocess
from urllib.parse import urlsplit

proxy = urlsplit(os.environ["HTTP_PROXY"])
if proxy.scheme != "http" or not proxy.hostname or not proxy.port or proxy.username or proxy.password:
    raise ValueError("Expected the existing unauthenticated HTTP egress proxy")
connect = shlex.join(["nc", "-X", "connect", "-x", f"{proxy.hostname}:{proxy.port}", "%h", "%p"])
environment = os.environ.copy()
environment["GIT_SSH_COMMAND"] = shlex.join([
    "ssh", "-o", f"ProxyCommand={connect}", "-o", "StrictHostKeyChecking=yes",
    "-o", "UserKnownHostsFile=/tmp/repository-known-hosts",
    "-o", "GlobalKnownHostsFile=/dev/null", "-o", "BatchMode=yes",
    "-o", "ConnectTimeout=20",
])
subprocess.run(["git", "ls-remote", "--exit-code", "ssh://git@ssh.github.com:443/org/repository.git", "HEAD"], env=environment, check=True, timeout=30)

Die Known-Hosts-Datei enthält nur den öffentlichen Hostschlüssel des Anbieters; der private Repository-Schlüssel bleibt in ssh-agent. Die bestehende Egress-Richtlinie und der Zugriffsumfang des Repository-Schlüssels gelten weiterhin. Eine weitergehende GitHub-Connector-Freigabe ist nicht nötig.

Sandbox-Geräte

Organisationen können ihre Sandboxes auf eigenen Rechnern ausführen, die sie unter Einstellungen > Sandboxes verbinden. Ein Gerät baut über HTTPS eine Verbindung zu <SITE_URL><BASE_PATH>/sandbox/tunnel auf und hält einen WebSocket offen. Der mitgelieferte Proxy leitet diesen Pfad, und nur diesen, an den Geräte-Hub des Spawners weiter; die signierte API des Spawners bleibt im internen Netz. Geräte brauchen das Docker-Backend: Mit Kubernetes bleibt der Hub ausgeschaltet.

Ein Gerät läuft immer mit dem Release des Servers. Es erfährt das Release bei jeder Erneuerung seiner Verbindung und ersetzt seine eigenen Container, sobald der Server weiterzieht, außer es wurde mit --no-auto-update verbunden. Es legt keine Daten auf dem Server ab: Seine Arbeitsbereiche bleiben auf dem Rechner. Sandboxes auf einem Gerät erreichen die Sandbox-Endpunkte des Backends und das Modell-Gateway über die Verbindung des Geräts, auf denselben Pfaden wie Sitzungen auf dem Server; die Verwaltungs-API des Gateways ist auf diesem Weg nie erreichbar. Ein Gerät behält die Adressen von Backend und Gateway, die es beim Verbinden erhalten hat: Nachdem du SANDBOX_HTTP_API_BASE_URL oder EXTERNAL_AGENT_GATEWAY_URL geändert hast, führe auf jedem Gerät tale sandbox update aus.

Ein Gerät muss dem TLS-Zertifikat der Website vertrauen. Eine Bereitstellung mit TLS_MODE=selfsigned kann keine Geräte aufnehmen.

Setzt du statt des mitgelieferten Proxys einen eigenen ein, leite /sandbox/tunnel an den Port SANDBOX_HUB_PORT des Spawners weiter, lass WebSocket-Upgrades und den Header Authorization unverändert und erlaube Verbindungen, die stundenlang offen bleiben.

Sandbox-Agent-Turns

Untersuche zuerst, warum die Ausgabe nicht mehr gelesen wird. Die Frist begrenzt verwaiste Ausgabeströme, nicht die gesamte Aufgabendauer. Erstelle die betroffenen Backend-Rollen nach einer Umgebungsänderung neu.

Eine geänderte Worker-Zahl des Gateways erreicht einen Anbieter, sobald eine Organisation, die ihn nutzt, die nächste Sandbox-Sitzung startet oder die Modell-Endpunkte aufruft. Eine niedrigere Zahl erreicht auch alle anderen Anbieter, die das Gateway hält: Nach einem Neustart passt das Backend sie zwei bis fünf Minuten nach seiner ersten Sandbox-Sitzung oder Anfrage an die Modell-Endpunkte an.

Eine Ausnahme ist ein Anbieter, dessen Upstream-Host sich nicht mehr auflösen lässt, etwa der eines entfernten Connectors oder eines Hosts, den du aus deinem Netzwerk genommen hast: Das Gateway lehnt es ab, ihn neu zu schreiben, er behält also seine Worker, und das Backend protokolliert nach jedem Neustart eine Warnung, die ihn nennt. Lösche einen solchen Anbieter aus dem Gateway. Ein Anbieter, der noch genutzt wird, wird bei seiner nächsten Sandbox-Sitzung oder Anfrage an die Modell-Endpunkte neu eingerichtet. Schicke die Anfrage aus einem Backend-Container, der das Gateway erreicht und sein Admin-Passwort kennt; auf einem Host mit tale deploy enthält sein Name -backend-api:

docker exec <backend-api-container> sh -c 'curl -fsS -X DELETE -u "${SANDBOX_LLM_GATEWAY_ADMIN_USERNAME:-admin}:$SANDBOX_LLM_GATEWAY_ADMIN_PASSWORD" "${SANDBOX_LLM_GATEWAY_URL:-http://sandbox-llm-gateway:8080}/api/providers/<name>"'

Unter Kubernetes verwendest du kubectl exec -n tale deploy/backend-api -- statt docker exec <backend-api-container>.

Das Gateway startet die Worker aller Anbieter beim Hochfahren, bevor das Backend es erreicht. Anbieter, die mit mehr Workern gespeichert sind, als diese Werte vorgeben (der eigene Default des Gateways ist 1.000), können mehr Speicher brauchen als das Limit des Gateways, 512 MiB mit tale deploy und im Kubernetes-Manifest. Das Gateway wird dann bei jedem Start beendet. Lösche sein Volume nicht: Es enthält das Admin-Konto des Gateways und die Schlüssel, die es ausgegeben hat. Erhöhe stattdessen das Limit, bis das Gateway startet: auf einem Host mit tale deploy mit docker update --memory 2g --memory-swap 2g <container> für den Container, dessen Name auf -sandbox-llm-gateway endet; unter Kubernetes über resources.limits.memory seines Deployments. Starte dann eine Sandbox-Sitzung oder rufe die Modell-Endpunkte auf und warte auf die Logzeile [llm-gateway] provider worker resize finished des Backends, die zwei bis fünf Minuten später erscheint. Sie zählt die Anbieter, die das Backend angepasst hat, die das Gateway abgelehnt hat und die das Backend nicht bestätigen konnte. Ein abgelehnter oder unbestätigter Anbieter behält seine Worker, und eine Warnung vor der Zeile nennt ihn; ein neu gestartetes Backend versucht einen unbestätigten Anbieter erneut. Lösche einen abgelehnten Anbieter, dessen Upstream-Host sich nicht mehr auflösen lässt, wie oben beschrieben, bevor du das Limit zurücksetzt. Setze das Limit danach mit docker update --memory 512m --memory-swap 1g <container> und docker restart <container> zurück, unter Kubernetes auf den ursprünglichen Wert des Deployments.

Video-Link-Ingestion (yt-dlp)

Der Worker verwendet diese Werte zum Abrufen von Videotranskripten. Sein Image enthält yt-dlp und ein PO-Token-Plugin. Video-Import hilft bei Quellenbeschränkungen, Egress-Problemen und berechtigten Sitzungen. Erstelle den Worker nach Änderungen seiner Umgebung neu. Erneutes Lesen einer Prozessvariablen lädt .env nicht nach.