Die tale-CLI installieren

Mit der tale-CLI installierst und betreibst du Tale und stellst neue Versionen bereit. Installiere sie dort, wo du deine Betriebsbefehle ausführen möchtest. Danach hilft dir der lokale Schnellstart oder der unten beschriebene Deployment-Ablauf weiter.

Dieselbe CLI übernimmt Container-Operationen im Workspace, verwaltete Deployments aus exakten Quell-Commits und Client-Konfigurations-Releases. Deine Deployment-Automatisierung wählt Ziel, Referenzen und Zugangsdatenverweise und ruft die CLI auf. Client-Konfigurationen veröffentlichen behandelt die Inhalte im eigenen Repository des Clients.

Für deine erste Instanz nutze den Schnellstart. Der übliche Ablauf ist tale init und danach tale dev. Eine Spezifikation für verwaltete Deployments brauchst du erst, wenn deine Automatisierung exakte Quell-Commits für Laufzeit und Client festlegen muss.

Bevor du beginnst

Du brauchst:

• Einen Rechner mit macOS, Linux oder Windows mit PowerShell.
• Für lokale Container: Docker Engine 24.0 oder neuer mit Compose und einen laufenden Docker-Daemon. Die Schichten der Tale-Images sind mit zstd komprimiert, und Docker lädt solche Schichten ab Engine 23.0. tale doctor meldet eine ältere Engine; tale dev und tale deploy, auch mit einem Bundle, brechen dann ab, bevor sie Images herunterladen.
• Für einen entfernten Workspace: Zugriff auf dessen Docker-Daemon mit Docker Engine 24.0 oder neuer, üblicherweise über einen SSH-Docker-Kontext. Der Benutzer auf dem Zielhost muss Docker ausführen dürfen.

Den mitgelieferten Objektspeicher gibt es derzeit nur als linux/amd64-Image. Auf ARM64-Hosts brauchen lokale Entwicklung und Workspace-Deployments deshalb eine funktionierende amd64-Emulation: Docker Desktop bringt sie mit; auf einem eigenständigen Linux-Docker-Host muss QEMU auf dem Host registriert sein. Tale wählt das amd64-Image aus, installiert aber keine Emulation. Verwaltete Bundles benötigen weiterhin native Images für ihre deklarierte Architektur. Ein verwaltetes ARM64-Deployment ist daher erst mit einem nativen Objektspeicher-Image möglich.

Der Installer lädt die ausführbare Datei von GitHub herunter. Dafür braucht er Zugriff auf raw.githubusercontent.com, api.github.com, github.com und die Download-Ziele, auf die GitHub weiterleitet.

install-cli.sh oder install-cli.ps1 ausführen

Auf macOS oder Linux:

curl -fsSL https://raw.githubusercontent.com/tale-project/tale/main/scripts/install-cli.sh | bash

Auf Windows PowerShell:

irm https://raw.githubusercontent.com/tale-project/tale/main/scripts/install-cli.ps1 | iex

Der Unix-Installer wählt die Datei für dein Betriebssystem und deine CPU. Er ersetzt standardmäßig eine vorhandene tale-Datei im PATH oder installiert sie unter /usr/local/bin. Nur wenn das Verzeichnis sonst nicht beschreibbar ist, fordert er sudo an. Unter Windows nutzt der Installer standardmäßig %LOCALAPPDATA%\Programs\tale und ergänzt den PATH deines Benutzers.

Fertige Binärdateien gibt es für macOS mit Apple Silicon oder Intel, Linux mit x86_64 oder arm64 sowie Windows x64. Windows ARM benötigt die x64-Emulation. Bei einer nicht unterstützten Unix-Architektur verweist der Installer auf den Build aus dem Quellcode.

Mit VERSION legst du eine Release-Version fest, mit INSTALL_DIR ein anderes Zielverzeichnis. Exportiere diese Variablen in einer Unix-Shell vor dem Aufruf der Pipeline, damit auch bash sie erhält. Eine Zuweisung nur vor curl erreicht den Installer nicht. In PowerShell nutzt du $env:VERSION und $env:INSTALL_DIR.

Verifizieren

tale --version

Die CLI zeigt die installierte Version. Falls der Befehl nicht gefunden wird, prüfe das Zielverzeichnis in der Installer-Ausgabe und ergänze es im PATH. Falls ein bereits geöffnetes Windows-Terminal tale weiterhin nicht findet, öffne es neu. Schlägt der Download fehl, prüfe die oben genannten Netzwerkziele. Mit der optionalen Umgebungsvariable GITHUB_TOKEN authentifizierst du die Release-Abfrage, falls GitHub anonyme API-Anfragen begrenzt.

Konfiguration prüfen

Nutze für Container-Befehle den Workspace, den du mit tale init im Schnellstart erstellt hast. Die CLI sucht im aktuellen Verzeichnis und seinen Eltern nach tale.json. Prüfe das gewählte Projekt, bevor du es veränderst:

tale config show

Konfigurations-Releases und verwaltete Deployments wählen Quellen und Ziele explizit und gleichen sich nicht an einen benachbarten Workspace an. config show behält sein bisheriges Verhalten für lokale Projekte.

Bei Workspace-Deployments liegen Proxy-Host, TLS-Einstellungen und Secrets in der .env des Projekts. Ändere für die Produktion HOST dort oder übergib --host an tale deploy. Lokal verwendet tale dev standardmäßig localhost; seine Optionen --host und --port gelten nur für diesen Lauf. Für entfernte Workspace-Hosts nutzt du den Docker-Kontext deiner Shell oder DOCKER_HOST. Ein verwaltetes Bundle-Deployment läuft dagegen auf dem festgelegten Ziel mit dessen lokalem Docker-Daemon.

tale deploy ausführen

tale deploy

Ohne --bundle stellt tale deploy die Version der CLI bereit: Es lädt deren Images, startet betroffene Container in der vorgesehenen Reihenfolge und führt Schema-Migrationen aus. Wähle eine andere Workspace-Version vorher mit tale update. Für getrennt festgelegte Runtime- und Client-Quell-Commits nutze Verwaltete Deployments.

Befehlsreferenz

Die CLI gruppiert ihre Befehle danach, was du gerade tust — genau wie tale --help. Jeder Befehl und seine Argumente sind unten aufgeführt. So liest du die Notation:

• Ein positionales Argument in [eckigen Klammern] ist optional, eines in <spitzen Klammern> ist erforderlich.
• Pflichtoptionen für Konfigurations-Releases sind ausdrücklich benannt; andere Flags sind optional, sofern die Befehlshilfe sie nicht als erforderlich markiert.
• Ein Flag der Form --flag <wert> erfordert einen Wert, wenn du es nutzt (z. B. --port 8443); ein bloßes Flag wie --detach ist ein boolescher Schalter.
• Standardwerte stehen in Klammern hinter der Beschreibung. Kein Standard bedeutet, das Flag ist aus oder der Wert wird aus .env / Kontext aufgelöst.

Diese Referenz beschreibt auch Befehle aus dem aktuellen Quellcode. Die veröffentlichte CLI-Version v0.5.70 enthält weder tale doctor noch tale dev --stop. Mit tale --help und tale <befehl> --help prüfst du, welche Befehle und Optionen deine installierte Version unterstützt.

Globale Flags funktionieren bei jedem Befehl:

• --verbose — ausführliche Ausgabe: Debug-Logs und der rohe Subprozess-Stream (nur die Langform; ein -v gibt es nicht).
• -q, --quiet — nur Warnungen und Fehler.
• -y, --yes — bei allen Rückfragen «ja» annehmen (nicht-interaktiv).
• --no-color — ANSI-Farben deaktivieren (berücksichtigt auch NO_COLOR / FORCE_COLOR).
• --json — maschinenlesbares JSON auf stdout; unterstützt von doctor, status, sandbox status, allen config-Unterbefehlen und verwalteten Deployment-Befehlen.
• --ci — erzwingt nicht-interaktive, rein anhängende Ausgabe (keine Cursor-Steuerung).

Befehle beenden mit 0 bei Erfolg, 2 bei einem Nutzungsfehler, 3 bei einer nicht erfüllten Voraussetzung (kein Projekt, Docker läuft nicht, Port belegt), 4 bei einem Abbruch durch dich (Ctrl-C oder eine erforderliche Rückfrage ohne Terminal) und 5 beim Fehler einer externen Abhängigkeit — so können Skripte anhand der Ursache verzweigen.

Einrichtung

tale doctor — prüft die Voraussetzungen für einen lokalen Start, ohne ein Projekt anzulegen, Software zu installieren oder Konfiguration zu ändern. Der Befehl prüft Docker-Daemon, die Version der Docker Engine, Compose-Unterstützung und Linux-Container-Modus, meldet die Daemon-Architektur und untersucht lokale Ports. Bei einem entfernten Docker-Kontext entfällt die lokale Portprüfung. Prüfe Warnungen zu ARM64 oder belegten Ports; eine bestehende Instanz kann den Port bereits verwenden.

• -p, --port <port> — zu prüfender HTTPS-Port (Standard 443); Sandbox-Port 8003 wird ebenfalls geprüft.
• --json — gibt die Prüfergebnisse als maschinenlesbares JSON aus.

Fehler bei Docker, Compose, einer Docker Engine älter als 24.0, einem nicht unterstützten Container-Modus oder die Wahl von HTTPS-Port 8003 führen zum Exit-Code 3. Warnungen allein ergeben 0; Image-Downloads, Speicherkapazität und Modellanbieter sind damit nicht geprüft. Prüfe einen anderen Port mit tale doctor --port 8443 und verwende denselben Port bei tale dev.

tale init [directory] — ein Projekt anlegen: erzeugt die Beispiel-Configs, AGENTS.md + einen CLAUDE.md-Verweis sowie eine lokale Standard-.env (localhost, selbstsigniertes Zertifikat, generierte Secrets). Docker braucht es nicht; Produktiv-Domain und TLS werden später bei tale deploy gewählt. Im Terminal fragt es nach einem Projektnamen, wenn directory fehlt, bestätigt vor dem Überschreiben eines bestehenden Projekts und fragt einmal, ob Agents in Sandboxes docker ausführen dürfen (Standard: nein — die Freigabe startet einen privilegierten inneren Docker); nicht-interaktive Läufe überspringen alle Rückfragen. directory ist optional (Standard: das aktuelle Verzeichnis).

• -f, --force — eine vorhandene tale.json überschreiben statt abzubrechen.
• --no-env — das Projekt anlegen, aber die .env-Generierung überspringen.

tale dev — alle Dienste lokal mit selbstsigniertem Zertifikat starten. Der gewählte Host und Port bestimmen die lokale Anwendungsadresse für diesen Lauf, ohne die Produktionseinstellungen in .env umzuschreiben. Die Bereitschaftsprüfung wartet, bis Dienste mit Gesundheitsprüfungen gesund sind und die übrigen Dienste laufen. Läuft sie ab, prüfe vor dem nächsten Versuch die Protokolle der gemeldeten Dienste.

• -d, --detach — im Hintergrund laufen statt Logs zu streamen.
• --stop — stoppt die lokalen Entwicklungscontainer dieses Projekts und erhält ihre Daten. Mit tale dev setzt du den Betrieb fort.
• -p, --port <port> — auszugebender HTTPS-Port (Standard 443).
• --host <hostname> — Host-Alias für den Proxy (Standard localhost).
• -y, --yes — nicht-interaktiv: Abfragen automatisch akzeptieren (z. B. Docker installieren oder starten).

tale deploy — die aktuelle CLI-Version bereitstellen und Anwendungsrollen per Blue-Green-Verfahren ersetzen. Gemeinsame Ausführungsdienste werden direkt ersetzt; Datenbank und Proxy brauchen dafür --stop. Beim ersten Deployment fragt die CLI nach Produktiv-Domain und TLS-E-Mail, soweit nicht vorgegeben. Lies vor Änderungen einer bestehenden Installation Upgrades.

• --stop — auch die stop-gebundene Schicht (db, proxy) aktualisieren — sie wird neu erstellt, also nimm eine kurze Ausfallzeit in Kauf; ohne das Flag bleiben laufende db/proxy unangetastet.
• -s, --services <list> — nur diese kommagetrennten Dienste aktualisieren (Standard: alle rotierbaren Dienste).
• --host <hostname> — Host-Alias für den Proxy (Standard: der HOST-Wert aus .env).
• --override — Container-Config aus dem Host-Workspace überschreiben (verschlüsselte *.secrets.json und .history/ bleiben stets erhalten).
• --override-all — den Builtin-Katalog serverseitig in jede Organisation zurücksetzen; impliziert --stop.
• -q, --quiet — Container-Logs während des Deployments unterdrücken.
• -y, --yes — destruktive Bestätigungsabfragen automatisch akzeptieren (z. B. --override-all).
• --skip-backup — den automatischen Pre-Deploy-Snapshot überspringen.
• --configuration-only — wendet nur verwaltete Konfiguration (Anweisungen, Tool-Berechtigungen für Agenten und Automatisierungen) im laufenden Betrieb auf die exakt passende, gesunde Runtime eines bereits bereiten Deployments an. Erfordert --bundle <directory> und überspringt den Snapshot vor dem Deployment sowie den Neustart. Nutze die Option, wenn sich nur diese Ressourcen ändern; Runtime- und Identitätsangaben müssen unverändert bleiben, und es darf kein Runtime-Rollout ausstehen.
• --dry-run — Vorschau ohne Änderungen.

Verwaltete Deployments

Nutze eine geprüfte Deployment-Deklaration, wenn Runtime und Client-Konfigurationen exakten Quell-Commits folgen sollen. Deine Deployment-Automatisierung wählt Ziel, Zugangsdaten und Referenzen und ruft die Tale-CLI auf. Die CLI beschafft Quellen, ermittelt und prüft Image-Digests, bereitet den Transfer vor, erhält unterstützten Bestandszustand, erstellt erforderliche Wiederherstellungssnapshots, rollt den Stack aus, provisioniert die native Instanz und prüft die Konfiguration. Diese Deployment-Logik bleibt in Tale.

Laufzeit und Quellstände vorbereiten

Führe die Vorbereitung unter Linux mit einer kompilierten CLI aus einem sauberen, committeten Tale-Checkout aus. Die Architektur muss zum Ziel passen: linux/amd64 oder linux/arm64. Dasselbe Binary reist für die lokale Provisionierung im Backend mit. Die Vorbereitung braucht Git und Docker zur Quellen- und Image-Prüfung. Anwenden läuft auf dem Ziel mit dessen lokalem Docker-Daemon, erhaltenem Zustandsverzeichnis und Umgebung. Vollständiger CLI-Commit, Runtime-Quell-Commit und Quell-Commit der Client-Konfiguration sind getrennte Referenzen. Auf dem Ziel veröffentlicht die vorbereitete Runtime nur die Ports 80 und 443 des Proxys sowie die beiden Datenbanken auf 127.0.0.1:5432 und 127.0.0.1:5433; der Sandbox-Spawner (8003) und sein Geräte-Hub (8004) bleiben im internen Netzwerk, wo Backend und Proxy sie erreichen.

Ein verwaltetes Deployment hält seinen Wiederherstellungspunkt fest, bevor es etwas ändert: den Snapshot vor dem Deployment und das Bundle, das gerade angewendet wird, beides im Zustandsverzeichnis, bis der Ready-Beleg geschrieben ist. Ein unterbrochenes Deployment erwartet beim nächsten Versuch deshalb dasselbe Bundle und lehnt ein anderes ab; die Ablehnung nennt den sha256 des ausstehenden Bundles. Kann dieses Bundle nicht mehr abschließen — etwa weil inzwischen eine korrigierte CLI gepinnt ist —, trägst du den genannten sha256 als supersedesPendingBundle in die Deployment-Deklaration ein und bereitest erneut vor: Das geprüfte Bundle übernimmt denselben Snapshot, der Ready-Beleg führt es unter supersededBundles, und danach nimmst du den Eintrag wieder heraus. Diese Übernahme gilt für den Wiederherstellungspunkt des Deployments, nicht für einen laufenden Runtime-Rollout. Ein Rollout, der nach der Prüfung seiner Images angehalten hat — beim Compose-Start oder beim Warten auf die Gesundheitsprüfungen —, läuft nur mit derselben vorbereiteten Runtime (runtime/runtime.json) und denselben Einstellungen für Origin, TLS und Umgebung weiter. Ein Bundle mit abweichender Runtime oder abweichenden Einstellungen lehnt er ab, ob mit supersedesPendingBundle oder ohne, und zwar mit A different runtime operation is pending; recover that exact operation first. Schließe ihn mit dem Bundle ab, das ihn begonnen hat, bevor du die gepinnte CLI in eine der beiden Richtungen wechselst: Eine andere CLI kann aus demselben Runtime-Commit eine andere Runtime vorbereiten. Die backendlokalen Phasen (deploy provision, deploy export-client-native) laufen im Backend unter dessen eigenem Benutzer, dem Eigentümer seines Datenverzeichnisses; schlägt eine fehl, wiederholt das Deploy-Ergebnis die Zusammenfassung der inneren CLI.

Der Snapshot vor dem Deployment enthält auch den Speicher des Modell-Gateways, llm-gateway-data, den ein neueres Gateway beim ersten Start darauf unumkehrbar migriert. Ein ausstehendes Deployment, das nichts geändert hat, hält keinen Snapshot fest. Eine Übernahme mit supersedesPendingBundle oder ein erneuter Versuch, der die Runtime ändern würde, erstellt zuerst den Snapshot und hält ihn beim ausstehenden Deployment fest. Ein Wiederherstellungspunkt ohne den Speicher des Gateways (ein Snapshot aus der Zeit, bevor die CLI ihn erfasste, oder keiner nach der Übernahme durch eine ältere CLI) blockiert jeden Rollout, der ein Gateway-Image starten würde, das laut Runtime-Beleg und Gateway-Container noch nie auf dem Speicher lief: Das Anwenden wird abgelehnt, bevor sich etwas ändert, und der ausstehende Beleg bleibt, wie er war, denn ein jetzt erstellter Snapshot könnte schon einen migrierten Speicher enthalten. Entferne den Beleg nicht. Solange kein Runtime-Rollout aussteht, kann ein geprüftes Bundle, das noch das zuletzt laufende Gateway-Image des Deployments auflöst, es mit supersedesPendingBundle übernehmen; der Rollout danach erstellt einen Snapshot, der den Speicher des Gateways enthält. Steht bereits ein Runtime-Rollout aus, bietet die CLI für diesen Zustand keinen Weg weiter. Ein Rollout auf einem Gateway-Image, mit dem der Speicher schon lief, schließt ab und warnt, wenn der zugehörige Snapshot den Speicher nicht enthält oder es gar keinen Wiederherstellungspunkt gibt. Ein verwaltetes Deployment rollt nie von selbst zurück und stellt kein Volume wieder her; es behält seinen ausstehenden Zustand für die Wiederherstellung.

Verwaltete Bundle-Befehle sind unter Windows nicht verfügbar, einschließlich deploy verify-bundle und des backendlokalen deploy provision. Die Integritätsprüfungen benötigen POSIX-Ausführungsrechte. Führe das vollständige verwaltete Deployment auf einem Linux-Host aus. Gewöhnliche Workspace-Befehle sowie eigenständige config build, verify, stage, deploy und verify-native bleiben unter Windows verfügbar.

Dieses synthetische Beispiel adressiert eine bestehende Organisation und ein Projekt. Ersetze die öffentlichen IDs und setze die benannten Umgebungswerte. revision nimmt einen vollständigen Commit-SHA oder einen Umgebungsverweis an. Zugangsdaten bleiben Verweise und werden am Ziel privat aufgelöst. tlsMode: "external" nutzt vorhandenes öffentliches TLS am vorgeschalteten Zugang; letsencrypt verlangt zusätzlich tlsEmail.

Nutze für Linux- oder macOS-ARM64-Jobs in GitHub Actions Tales Composite Action .github/actions/setup-cli. Lege die Action und revision auf denselben vollständigen Tale-Commit fest. Sie baut mit Bun 1.4.2, prüft das fertige Binary, liefert executable und ergänzt den PATH. macOS-Builds unterstützen die allgemeine Konfigurationsvorbereitung; ein verwalteter Linux-Stack braucht weiter ein passendes Linux-Binary. Setze auf einem Linux-x64-Runner linux-baseline: 'true', wenn die Ziel-CPU kein AVX2 unterstützt (etwa Intel vor Haswell): Das Standard-Binary bricht dort mit Illegal instruction ab, das Baseline-Binary läuft. Andere Runner lehnen die Option ab.

Auch origin und einzelne native redirectUris akzeptieren Umgebungsverweise. So kann eine Deployment-Registry die öffentlichen Adressen verwalten. Die Vorbereitung löst sie zu geprüften wörtlichen HTTPS-URLs im Bundle auf.

Im Beispiel macht runtime.containerPrefix die Umgebung in der Containerliste erkennbar. Die optionale Einstellung wird unten erläutert.

{
  "schemaVersion": 1,
  "name": "example-native",
  "stateDirectory": "/opt/tale-example",
  "composeProject": "tale-example",
  "runtime": {
    "revision": { "env": "TALE_RUNTIME_REF" },
    "platform": "linux/amd64",
    "containerPrefix": "north-desk-prod"
  },
  "origin": { "env": "TALE_PUBLIC_ORIGIN" },
  "tlsMode": "external",
  "identity": {
    "email": { "env": "EXAMPLE_OPERATOR_EMAIL" },
    "password": { "env": "EXAMPLE_OPERATOR_PASSWORD" },
    "slug": "example-team",
    "name": "Example team",
    "ssoEnabled": false,
    "nativeClients": [
      {
        "key": "example-portal",
        "name": "Example portal",
        "clientId": { "env": "EXAMPLE_NATIVE_CLIENT_ID" },
        "redirectUris": [{ "env": "EXAMPLE_PORTAL_CALLBACK" }]
      }
    ]
  },
  "configs": [
    {
      "repository": "https://github.com/example-team/client-app",
      "revision": { "env": "EXAMPLE_CONFIG_REF" },
      "client": "example-team",
      "descriptor": "tale/client.json",
      "automation": "document-review",
      "projectId": "existing-project-id",
      "skillOwner": "native-operator-id"
    }
  ]
}

Die Umgebung für Fehlerberichte wählen

Verwaltete Laufzeiten setzen SENTRY_ENVIRONMENT standardmäßig auf den bestehenden Deployment-name. Für eine kanonische Bezeichnung wie example-pr deklarierst du "environment": { "SENTRY_ENVIRONMENT": { "env": "TALE_REPORTING_ENVIRONMENT" } } und setzt die Variable am Ziel. Die Bezeichnung beginnt mit einem Kleinbuchstaben oder einer Ziffer und enthält 1–64 Kleinbuchstaben, Ziffern oder Bindestriche. Browser, Backend und Sandbox verwenden sie, ohne name, composeProject, stateDirectory oder gespeicherte Zugangsdaten zu ändern.

Containernamen wählen

Setze runtime.containerPrefix, wenn in der Containerliste Namen wie north-desk-prod-db und north-desk-prod-backend-api erscheinen sollen. Das Präfix beginnt mit einem Kleinbuchstaben und besteht aus Kleinbuchstaben, Ziffern und einzelnen Bindestrichen. Es darf höchstens 40 Zeichen lang sein. Leerzeichen, Unterstriche, doppelte Bindestriche und ein Bindestrich am Ende sind nicht erlaubt.

Lass die Werte der letzten beiden Zeilen unverändert, wenn du die Container einer bestehenden Installation umbenennst. Das Präfix verändert die DNS-Namen der Dienste nicht; interne Dienstadressen verwenden weiterhin ihre bisherigen Namen. Ohne Präfix gilt die Benennung aus dem Quellcode.

Wenn du ein Präfix hinzufügst, änderst oder entfernst, werden Container neu erstellt. Dabei kann der Dienst kurz unterbrochen werden. Bereite ein neues Bundle vor, prüfe den Probelauf und wende es über den üblichen Ablauf mit Snapshot und Wiederherstellung an. Wiederhole nach einer Unterbrechung genau dieses Bundle; ein ausstehender Rollout lehnt ein anderes Bundle ab. Sobald der Rollout abgeschlossen ist, kannst du das Präfix mit einem weiteren vorbereiteten Bundle entfernen und so zur Benennung aus dem Quellcode zurückkehren.

Betreibe nur eine vollständige verwaltete Laufzeit pro Docker-Daemon. Ein Namenspräfix vergibt keine separaten Ports, Sandbox-Netzwerke oder Arbeitsverzeichnisse auf dem Host.

Zusätzliche Ursprünge bedienen

Deklariere additionalOrigins, wenn dieselbe Instanz auch unter weiteren HTTPS-Ursprüngen antworten soll, etwa unter einer Partnerdomain oder während eines Umzugs unter dem bisherigen Hostnamen. Jeder Eintrag ist ein reiner HTTPS-Ursprung auf dem Standardport oder eine Umgebungsreferenz, die bei der Vorbereitung zu einem solchen Ursprung aufgelöst wird. Die Liste enthält 1 bis 16 verschiedene Ursprünge; keiner davon darf origin wiederholen.

{
  "origin": "https://desk.example.org",
  "additionalOrigins": [
    "https://desk.partner.example",
    { "env": "TALE_EXTRA_ORIGIN" }
  ]
}

Die CLI schreibt die Liste in die Laufzeitvariable ADDITIONAL_SITE_URLS und verwaltet sie selbst, deshalb kann ein Eintrag unter environment sie nicht setzen. Jeder Ursprung ist ein vollwertiger Einstieg mit eigenen Sitzungen, Dateilinks, Anmeldewegen und Connector-Callbacks. Mit tlsMode: "letsencrypt" bezieht der Proxy für jeden Ursprung ein Zertifikat; lokale Hostnamen und IP-Adressen werden abgelehnt. Mit tlsMode: "external" muss dein TLS-Proxy für jeden Ursprung den ursprünglichen Host weiterleiten und X-Forwarded-Proto: https von einer Adresse senden, der Tales Proxy vertraut. Ist dieser Adressbereich enger als die privaten Bereiche, setze TRUSTED_PROXIES über eine Referenz unter environment.

Die native Identität bleibt bei origin: Konto- und Organisationsbindungen, Client-Journale, der OIDC-Issuer, Passkeys und E-Mail-Links verwenden nur diesen Ursprung. Ein Eintrag darf identity.migrateOriginFrom entsprechen, damit der bisherige Hostname während einer Migration erreichbar bleibt.

Die Vorbereitung lehnt eine Laufzeitrevision ab, deren Proxy einem externen TLS-Terminator nicht vertrauen kann, und meldet Runtime does not serve additional origins. Wenn du die Liste hinzufügst, änderst oder entfernst, werden die Dienste neu erstellt, die sie lesen. Entfernst du die Deklaration, entfernt das nächste angewendete Bundle auch die Variable. Registriere die Callback-URLs jedes Ursprungs bei deinen Identitäts- und Connector-Anbietern und plane DNS und Zertifikate mit TLS und Domains.

Festlegen, wer Organisationen erstellen darf

Ein verwaltetes Deployment lehnt das Erstellen von Organisationen an seinem Proxy für alle ab: Die Organisationsauswahl zeigt keinen Eintrag Organisation erstellen, und POST /api/auth/organization/create antwortet mit 403. Damit benannte Personen weitere Arbeitsbereiche eröffnen können, deklariere organizations.creators — 1 bis 64 verschiedene Anmeldeadressen, wörtlich oder als Umgebungsreferenzen, die die Vorbereitung auflöst.

{
  "organizations": {
    "creators": ["ops@example.org", { "env": "TALE_WORKSPACE_LEAD" }]
  }
}

Die CLI schreibt die Liste in die Laufzeitvariable TALE_ORGANIZATION_CREATORS und verwaltet sie selbst, deshalb kann ein Eintrag unter environment sie nicht setzen. Mit der Deklaration lehnt der Proxy das Erstellen nicht mehr ab; stattdessen prüft das Backend jede anfragende Person gegen die Liste, antwortet allen anderen mit 403 ORGANIZATION_CREATION_FORBIDDEN, und die App zeigt Organisation erstellen nur den benannten Personen. Adressen werden ohne Rücksicht auf Groß- und Kleinschreibung verglichen; zwei Schreibweisen derselben Adresse gelten als Duplikat und werden abgelehnt.

Die verwaltete Organisation selbst bleibt unberührt: Das Deployment erstellt sie beim Bootstrap, und die erste Organisation eines Deployments ist immer erlaubt. Entfernst du die Deklaration und wendest das nächste Bundle an, kehrt die Ablehnung am Proxy zurück und die Variable wird entfernt. Dieselbe Variable funktioniert auch auf einem Deployment, das du selbst betreibst; siehe die Umgebungsvariablen-Referenz.

Bundle vorbereiten, prüfen und anwenden

Setze TALE_DEPLOY_SPEC auf die JSON-Datei, TALE_DEPLOY_BUNDLE auf ein neues absolutes Ausgabeverzeichnis und TALE_CLI_COMMIT auf den vollständigen Commit des Binaries. DEPLOYMENT_COMMIT ist ein optionaler Herkunftsvermerk für die Orchestrierung; lass die zugehörigen Flags bei Nichtgebrauch weg. Bereite vor und prüfe, übertrage das vollständige Verzeichnis und führe Vorschau und Deployment auf dem Ziel mit derselben festgelegten CLI aus.

tale --json deploy prepare \
  --spec "$TALE_DEPLOY_SPEC" \
  --deployment-ref "$DEPLOYMENT_COMMIT" \
  --output "$TALE_DEPLOY_BUNDLE"

tale --json deploy verify-bundle \
  --bundle "$TALE_DEPLOY_BUNDLE" \
  --cli-ref "$TALE_CLI_COMMIT" \
  --deployment-ref "$DEPLOYMENT_COMMIT"

tale --json deploy --bundle "$TALE_DEPLOY_BUNDLE" \
  --cli-ref "$TALE_CLI_COMMIT" \
  --deployment-ref "$DEPLOYMENT_COMMIT" --dry-run

tale --json --yes deploy --bundle "$TALE_DEPLOY_BUNDLE" \
  --cli-ref "$TALE_CLI_COMMIT" \
  --deployment-ref "$DEPLOYMENT_COMMIT"

deploy prepare akzeptiert optional --sources-file <file> mit einer Zuordnung von repository@fullSHA zu vorhandenen exakten Checkouts. Sonst lädt die CLI kanonische GitHub-Repositories. Übergib den Inhalt eines nur lesenden SSH-Schlüssels für private Client-Repositories während der Vorbereitung über TALE_SOURCE_SSH_KEY. Die CLI prüft GitHubs SSH-Hostschlüssel über HTTPS und hält den Schlüssel aus Paket und Runtime heraus. Docker braucht bereits Zugriff auf die Registry.

Die Vorbereitung prüft zuerst jede Konfiguration mit den eigenen Schemas der CLI und lädt und prüft erst danach die Runtime-Images. Dabei nennt sie jede Phase und jedes Image. Ein Paket mit Feldern, die diese CLI nicht kennt, lehnt sie innerhalb von Sekunden mit native manifest normalization changes release semantics at <fields> ab. Bereite es dann mit einer CLI vor, die mindestens so neu ist wie das Tale, für das das Paket geschrieben wurde. Einen Fehler, den die CLI bewusst meldet, zeigt sie mit seiner Ursache. Jeder andere Fehler behält eine feste Zusammenfassung, damit weder Zugangsdaten noch Ausgaben der Registry ins Log gelangen.

deploy verify-bundle prüft vollständiges Inventar und Datei-Hashes ohne Zielkontakt. deploy --bundle --dry-run prüft Konfigurationsartefakte und Zielbedingungen, ohne Änderungen anzuwenden. Verwaltete Deployments akzeptieren keine Workspace-Optionen wie --services, --host oder --override-all. Sie rollen den Stack unter Erhalt seines Zustands mit Zustands- und Herkunftsprüfungen aus. Das oben beschriebene Blue-Green-Verhalten des Workspace ist ein eigener Ablauf.

Das aktuelle Deployment prüfen

Sobald genau dieses Bundle vollständig angewendet wurde, erstellst du auf dem Deployment-Host einen aktuellen Prüfnachweis:

tale --json deploy accept --bundle "$TALE_DEPLOY_BUNDLE" \
  --cli-ref "$TALE_CLI_COMMIT" --deployment-ref "$DEPLOYMENT_COMMIT" \
  --expected-version "$TALE_RELEASE_VERSION"

Für diese Prüfung sind beide vollständigen Quell-Commits erforderlich; das Bundle muss mit --deployment-ref vorbereitet worden sein. Setze TALE_RELEASE_VERSION auf die unabhängig ausgewählte veröffentlichte Version ohne das Präfix v. Die CLI hält die bestehende Deployment-Sperre und liest den Ready-Nachweis, aktuelle Container, fixierte Images und alle drei Migrationsregister. Sie vergleicht /api/health des Frontends und /api/health/ready der API am kanonischen HTTPS-Ursprung mit frischen Prozessidentitäten aus den zuvor erfassten lokalen Containern und liest diese Identitäten anschließend erneut. Fehlende Identitäten oder ein anderer Serverprozess führen auch bei gleicher Version zur Ablehnung. OCI-Version und Quell-Commit jedes Tale-Images müssen mit dem Bundle übereinstimmen. sourceTag darf sha-<source> sein; dieses Feld beschreibt die Image-Referenz, nicht die ausgelieferte Version.

Das JSON-Ergebnis enthält Quell-Commits, Bundle- und Ready-Hashes, Image-Identitäten, den kanonischen Ursprung, beide Serverprozess-Identitäten und vollständige Migrations-IDs aus dem Quellstand samt Inventar-Hashes. Dazu gehören SQL-Migrationen der Anwendung und nummerierte TypeScript-Datenmigrationen. Fehlende, zusätzliche, doppelte oder unvollständige Migrationen, ein ausstehendes Deployment, Versionsabweichungen und geänderte Identitäten führen zur Ablehnung. Die öffentlichen Prozessidentitäten verbinden einen lokalen Container mit einer Antwort des Ursprungs; sie sind keine Zugangsdaten und kein Authentifizierungsnachweis.

Docker- und HTTPS-Beobachtungen haben eigene Abbruchfristen und teilen sich ein Zeitbudget von 120 Sekunden, das an den Beobachtungsgrenzen geprüft wird. Bundle-Prüfung, private temporäre Kopie und Bereinigung unterliegen den bestehenden Größenlimits (insgesamt 2 GiB, höchstens 256 MiB pro Datei); Wartezeiten des Dateisystems sind nicht durch eine abbrechbare Frist für den gesamten Befehl begrenzt. Verwende eine externe Prozessüberwachung, wenn du eine solche Gesamtfrist brauchst. Die Prüfung ändert keine Konfiguration, startet keine Container neu, führt keine Migrationen aus und exportiert keine Zugangsdaten. Sie ändert Sperrmetadaten und erstellt und entfernt ihre private temporäre Bundle-Kopie.

Ältere Bundles bleiben einsetzbar. Für diese Prüfung brauchen sie jedoch ein Migrationsinventar aus dem Quellstand und kompatible Server, die Prozessidentitäten ausgeben. Bereite ein geprüftes Bundle vor und wende es über den normalen Deployment-Ablauf vollständig an, bevor du seinen Prüfnachweis erstellst. Der Nachweis belegt den beobachteten Zustand zu seinem Zeitstempel; er garantiert keinen späteren Routing- oder Serverzustand. Wiederhole die Prüfung, wenn du aktuelle Belege brauchst.

Gespeicherten Zustand vor einem Rollout prüfen

tale --json deploy observe --spec <file> --cli-ref <sha> --deployment-ref <sha> --machine-id-sha256 <digest> erfasst die Identitäten der laufenden Images, Migrationsverzeichnisse, Metadaten zu Korpus und Speicherplatz sowie Nachweise zur gespeicherten nativen Konfiguration. Führe die festgelegte kompilierte CLI auf dem geprüften Linux-Host mit dessen lokalem Docker-Socket aus. Übergib private JSON-Daten über stdin als {"environment":{"UPPERCASE_ENV_NAME":"value"}}, mit ausschließlich den Variablen, die die geprüfte Spezifikation benötigt. Umgebungsvariablen dienen nicht als Ersatz. Die Eingabe ist auf 64 KiB, 128 Schlüssel und 8192 Byte pro Wert begrenzt.

Der Befehl verwendet vorhandene Zugangsdaten sowie die exakt gespeicherten Konto- und Organisations-IDs. Er liest erhaltene Pack-Dateien ohne erneute Kompilierung, prüft aktuelle native Versionen, Dateien und die Eigentümer der enthaltenen Skills und kontrolliert anschließend Dateizustand und Containeridentitäten erneut. Er erstellt nur temporäre Hilfsdateien und Anmeldesitzungen, entfernt die Hilfsdateien danach und meldet sich ab. Er legt keine Identitäten an, bereitet keine Konfiguration vor, wendet keine an, migriert nicht, startet nichts neu, bereinigt keine Ressourcen und hält keine Cutover-Sperre. Docker- und native Lesezugriffe sind begrenzt; überwache den Prozess extern, um auch Wartezeiten auf das Dateisystem zu begrenzen.

Eine vollständige Beobachtung liefert ok:true und data.complete:true. Fehlen ältere Zustands- oder Eigentumsnachweise, enthält der Bericht die verfügbaren Host- und Datenbankdaten mit ok:false, data.complete:false, einem festgelegten Ursachencode und Exit-Code 3. Bewahre ihn für die Untersuchung auf. Ungültige Eingaben, abweichende Identitäten oder ein geänderter Zustand führen zur Ablehnung. Kein Ergebnis bestätigt den Ready-Zustand, erlaubt einen Cutover oder beweist, dass Packs ein späteres Deployment überstehen. Dafür gilt weiterhin der normale geprüfte Deployment- und Abnahmeablauf.

Native Identität bereitstellen

deploy provision [--bundle <directory>] ist die lokale Backend-Phase des Bundle-Deployments. Sie liest höchstens 64 KiB privates JSON von stdin, weist das lokale Konto und die ausgewählte Organisation nach und meldet die Sitzung vor der Erfolgsmeldung ab. Die Felder umfassen origin, email, password, slug, name, ssoEnabled, optionale Entra-Zugangsdaten und nativeClients. Standardmäßig bleibt das bestehende Konto erforderlich. Explizites identity.bootstrap: "fresh" erlaubt die Anlage des ersten lokalen Kontos und der Organisation. Ein Bundle bindet diese Wahl und die vorbereiteten Konfigurationen vor nativen Änderungen. deploy provision verweigert Workspace-Flags und --dry-run; nutze lesende Bundle- und Konfigurationsprüfungen. Die optionalen Erwartungen --cli-ref und --deployment-ref erfordern --bundle und greifen vor der Anmeldung.

Das Bundle-Deployment ruft deploy provision mit internen Optionen für reine Konfigurationsänderungen und die Prüfung gespeicherter Identitäten auf; nutze dafür als Betreiber tale deploy --bundle <directory> --configuration-only.

Für einen administrativ geprüften neuen Betreiber deklarierst du ausdrücklich identity.emailVerification: "operator-attested". Damit bestätigst du als Betreiber den Besitz der E-Mail-Adresse des authentifizierten Kontos; eine Postfachzustellung ist damit nicht nachgewiesen. Das Backend verwendet ein kurzlebiges natives Prüftoken für genau dieses Konto und diese Adresse und erhält native Hooks. Es verschickt keine E-Mail, ändert keine Adresse und erstellt keine weitere Sitzung. Die Option ist nur mit bootstrap: "fresh" zulässig. Ohne sie bleibt die normale native E-Mail-Prüfung bestehen. Ändert sich der Prüfstatus eines zuvor freigegebenen Kontos, stoppt der Ablauf zur Prüfung.

Ersetze für ein neues Ziel projectId einer Konfiguration durch project: { "key": "NORTH", "name": "Configuration" }. Native Projektschlüssel haben 2–6 Großbuchstaben, Namen höchstens 80 Zeichen. skillOwner: "operator" überträgt eine geprüfte Quellkapsel und kompiliert sie im Backend für den authentifizierten nativen Benutzer; der Host prüft das Ergebnis unabhängig. Explizite bestehende IDs und bereits an Besitzer gebundene Releases behalten ihr Verhalten.

Jeder native Client wählt eine bestehende clientId oder explizites managed: true. Vor der nativen Anlage speichert die CLI eine private Absicht; danach liefert sie nur einen privaten Übergabepfad und SHA für die Zugangsdaten. Wiederholungen erhalten IDs, Sicherheitsrichtlinie und Secrets. Unklare Annahme ohne passendes natives Objekt stoppt. Bei bestehenden Clients lassen sich nur Anzeigename und HTTPS-Callback-URLs angleichen. Auf unterstützten 0.5-Backends verwenden nötige Anlagen oder Änderungen feste backendlokale Auth-Adapter, deren Verbindungen anschließend schließen. Es entstehen keine öffentliche Registrierungs- oder Update-Route, frei wählbaren Modulpfade oder Secret-Rotationen.

Den Hostnamen eines verwalteten Deployments ändern

Verwende das bestehende verwaltete Deployment und sein privates Zustandsverzeichnis. Der Ablauf ändert die Origin-Bindungen des vorhandenen Kontos, der Organisation und der Clients. Er verschiebt keine Datenbank und legt keine Ersatzidentitäten an.

1. Setze origin in der Deployment-Spezifikation auf die neue HTTPS-Origin und identity.migrateOriginFrom auf die genaue bisherige HTTPS-Origin, etwa https://old.example.org. Beide müssen verschieden sein. Behalte identity.bootstrap: "fresh", Konto, Organisation und die Schlüssel der verwalteten Clients bei.
2. Prüfe vor der Bundle-Vorbereitung den gespeicherten Zustand. Der Bootstrap muss abgeschlossen sein. Jede deklarierte E-Mail-Bestätigung und jeder verwaltete Client benötigen ihr passendes abgeschlossenes Journal. Fehlende, ausstehende oder fremde Identitäts- und Client-Journale blockieren die Migration.
3. Bereite das Bundle vor, prüfe es, kontrolliere die Vorschau und wende es mit dem oben beschriebenen Ablauf an. Die CLI authentifiziert das bestehende Konto und prüft die Client-Zugangsdaten, bevor sie die Origin-Bindungen aktualisiert. Bei einer Wiederholung akzeptiert sie abgeschlossene Journale an beiden deklarierten Origins und erhält IDs und Secrets.
4. Exportiere nach dem abgeschlossenen Deployment-Beleg die Client-Konfiguration für den neuen Issuer. Entferne migrateOriginFrom aus künftigen Deployment-Spezifikationen.

Ist native Konfiguration deklariert, braucht sie ebenfalls ihren gespeicherten Beleg. Die Migration erhält Organisations-ID und Slug und prüft jede Ressource mit dem üblichen Plan- und Rückleseablauf. Eine an der neuen Origin unterbrochene Konfigurationsänderung lässt sich nur mit genau ihrem ausstehenden Plan fortsetzen. Ein ausstehender Konfigurationsbeleg an der alten Origin blockiert die Migration.

Für den Rückweg nach einer abgeschlossenen Migration tauschst du beide Origins ausdrücklich und durchläufst denselben geprüften Ablauf. Plane DNS, Zertifikate, Callback-Registrierungen und Zugriffstests mit TLS und Domains. Die Änderung der Bundle-Origin erledigt diese externen Schritte nicht.

Die Anmeldeadresse des Deploy-Operators ändern

Ein verwaltetes Deployment meldet sich bei jedem Lauf als sein identity-Operator an. Soll dieses Konto eine Maschinenadresse bekommen, damit sich Personen mit eigenen Konten anmelden, behältst du das Konto und änderst nur seine Anmeldeadresse. Seine Benutzer-ID und alles, was daran hängt – verwaltete Clients, Skills im Besitz des Operators, API-Schlüssel und aufbewahrte Journale –, bleibt erhalten.

1. Setze identity.email auf die neue Adresse und identity.migrateEmailFrom auf die genaue bisherige Adresse. Beide müssen verschieden sein. Behalte identity.bootstrap: "fresh" und das Passwort des Kontos bei. Der Bootstrap muss abgeschlossen sein, und eine deklarierte E-Mail-Bestätigung braucht ihr abgeschlossenes Journal.
2. Bereite das Bundle vor, prüfe es, sieh dir die Vorschau an und wende es an. Die CLI liest die aktuelle Adresse des aufbewahrten Kontos im Backend, meldet sich damit an und weist die aufbewahrte Benutzer-ID nach. Sie hält die Änderung im Journal fest, benennt das Konto über den nativen Adapter um, beendet alle Sitzungen des Kontos und meldet sich mit der neuen Adresse erneut an. Die Umbenennung ist an die bisherige Adresse gebunden, sodass eine gleichzeitige Änderung abgelehnt statt überschrieben wird. Eine deklarierte E-Mail-Bestätigung bestätigt danach die neue Adresse.
3. Ein erneuter Lauf nach einer Unterbrechung findet die Adresse bereits geändert vor und schließt die Journale ohne zweite Umbenennung ab. migrateEmailFrom danach deklariert zu lassen, schadet nicht; entferne es, sobald der Deployment-Beleg bereit ist.

Hält ein anderes Konto die neue Adresse, das aufbewahrte Konto keine der beiden Adressen oder das Operator-Konto eine Single-Sign-on-Verknüpfung, stoppt das Deployment vor jeder Änderung. Entferne eine solche Verknüpfung zuerst: Sie gehört der Person, die sich damit angemeldet hat, nicht einem Maschinenkonto.

Einen Break-Glass-Administrator deklarieren

identity.breakGlass hält einen Administrator für den Fall bereit, dass der Deploy-Operator nicht verfügbar ist, etwa { "email": "break-glass@example.org", "passwordHash": { "env": "TALE_BREAK_GLASS_PASSWORD_HASH" } }. Die Adresse ist ein fester Wert oder eine verpflichtende Umgebungsreferenz und muss sich von der aktuellen und der bisherigen Adresse des Operators unterscheiden. Das Passwort erreicht das Deployment nie: Erzeuge seinen Hash mit tale auth hash-password dort, wo das Passwort aufbewahrt wird, und übergib nur den Hash.

Jedes Deployment gleicht das Backend an die Deklaration an. Ein fehlendes Konto wird mit bestätigter Adresse und genau den deklarierten Zugangsdaten angelegt, und ein aufbewahrtes Journal bindet die Adresse an seine Konto-ID, sobald das Konto existiert. Spätere Deployments setzen das gebundene Konto auf die deklarierten Zugangsdaten zurück und beenden alle seine Sitzungen, sobald sich die Zugangsdaten ändern, auch wenn sie einen unterbrochenen Lauf abschließen. Ein Konto mit dieser Adresse, das nicht von diesem Deployment angelegt wurde, oder später ein anderes Konto mit dieser Adresse stoppt das Deployment. Das Konto wird über die nativen Mitglieder-Endpunkte admin der verwalteten Organisation; ein owner wird nie verändert. Das Deployment meldet sich nie mit diesem Konto an. Ändere sein Passwort über den deklarierten Hash, nicht in der Anwendung. Das Deployment hält keinen Zeitpunkt der Passwortänderung fest; eine Richtlinie zur Passwortrotation der Organisation kann dieses Konto daher nach einem neuen Passwort fragen, das das nächste Deployment wieder zurücksetzt.

Erzwungene Zwei-Faktor-Anmeldung

Ein verwaltetes Deployment meldet sich allein mit dem Passwort als sein Operator an. Erzwingt die Organisation two_factor_policy, gib dem Operator einen Passkey und nie eine Authenticator-App: Die Passwort-Anmeldung eines Kontos mit Authenticator-App wird mit einer Code-Abfrage beantwortet, und ein Konto ohne beide Faktoren wird nach Ablauf seiner Übergangsfrist zur Einrichtung geschickt. Die CLI stoppt bei beiden Antworten und nennt die erhaltene. Personen melden sich mit eigenen Konten an und können beide Faktoren nutzen.

Zugangsdaten nativer Clients exportieren

Um Zugangsdaten eines verwalteten Clients an eine separate Anwendung zu übergeben, setze NATIVE_CLIENT_KEY auf den deklarierten Schlüssel und PRIVATE_EXPORT_DIRECTORY auf einen neuen privaten Ausgabeordner. Dessen übergeordneter Ordner muss bereits deinem Konto gehören, Modus 0700 haben und unter vertrauenswürdigen Verzeichnissen liegen. Exportiere aus demselben freigegebenen Deployment, ohne Backend-Pfade oder Containernamen auszuwerten:

tale --json deploy export-client --bundle "$TALE_DEPLOY_BUNDLE" \
  --client "$NATIVE_CLIENT_KEY" --output "$PRIVATE_EXPORT_DIRECTORY" \
  --env-prefix TALE_OIDC --cli-ref "$TALE_CLI_COMMIT" \
  --deployment-ref "$DEPLOYMENT_COMMIT"

Der Ausgabeordner hat Modus 0700. Seine regulären Dateien client.json, receipt.json und optional consumer-env.json haben Modus 0600. Mit --env-prefix entsteht die letzte Datei als wörtliche Zuordnung der vier Zeichenketten TALE_OIDC_ISSUER, TALE_OIDC_CLIENT_ID, TALE_OIDC_CLIENT_SECRET und TALE_OIDC_ORG_SLUG. Der Issuer besteht aus der Tale-Origin und /api/auth. Übertrage die Bytes über deinen privaten Zugangsdatenkanal und lass die Anwendung JSON lesen; führe die Datei nicht als Shell aus und veröffentliche sie nicht als CI-Artefakt. Stdout enthält nur unkritische Metadaten, Pfade, Größen und Hashes. Eine identische Ausgabe wird erst nach erneuter Zustands- und vollständiger Artefaktprüfung wiederverwendet. Unvollständige, veraltete oder fremde Ausgaben stoppen ohne Überschreiben.

Plattform konfigurieren

Mit tale config verwaltest du bestehende Plattform-Einstellungen über die nativen APIs. Speichere diese Deklaration als configuration.json, um Akzentfarbe und ein Inaktivitätslimit von 45 Minuten festzulegen:

{
  "schemaVersion": 1,
  "resources": [
    {
      "kind": "branding",
      "config": {
        "accentColor": "#336699"
      }
    },
    {
      "kind": "governance",
      "key": "session_idle_timeout",
      "config": {
        "enabled": true,
        "idleTimeoutMinutes": 45
      }
    }
  ]
}

Setze TALE_URL auf die HTTPS-Origin der Instanz und TALE_ORG_ID auf die native Organisations-ID. Übergib ein berechtigtes Sitzungscookie über TALE_CONFIG_COOKIE; es gehört weder in Argumente noch in versionierte Dateien. Prüfe die Deklaration lokal, speichere und prüfe den Plan, wende ihn an und vergleiche den nativen Zustand:

tale --json config validate --file configuration.json
tale --json config plan --file configuration.json \
  --url "$TALE_URL" --org "$TALE_ORG_ID" --output configuration-plan.json
tale --json --yes config apply --file configuration.json \
  --url "$TALE_URL" --org "$TALE_ORG_ID" \
  --plan configuration-plan.json --receipt configuration-receipt.json
tale --json config read --file configuration.json \
  --url "$TALE_URL" --org "$TALE_ORG_ID"

Die Ausgabe- und Belegordner müssen bereits existieren. Eine HTTP-Verbindung über Loopback braucht zusätzlich --origin mit der öffentlichen HTTPS-Origin. read meldet für jede deklarierte Ressource matches. Der Plan zeigt Organisations- oder Instanzumfang, aktuelle und gewünschte Hashes sowie native Folgewirkungen. Zum Anwenden müssen Deklaration und Ziel exakt stimmen. Eine konkurrierende native Änderung stoppt den Schreibvorgang. Nicht deklarierte Ressourcen bleiben bestehen. Die CLI bietet weder Löschbefehle noch beliebige Dateizugriffe.

Diese Ressourcenarten nutzen die gemeinsamen Plattform-Schemas und nativen Berechtigungen:

Mit agent-tools verwaltest du ausschließlich die Tool-Berechtigungen eines vorhandenen Agenten. config enthält die exakten Werte für projectId und agentId sowie das vollständige gewünschte Array tools, etwa ["task_find", "task_get", "task_review"]. Führe jede Berechtigung auf, die erhalten bleiben soll; [] entfernt alle Tool-Berechtigungen. Der native Katalog lehnt unbekannte Namen ab und vereinheitlicht Reihenfolge und Duplikate vor der Hash-Berechnung.

Zum Anwenden brauchst du Bearbeitungsrechte für das aktive Projekt. Der Agent darf nicht von der Plattform verwaltet werden. Mitglieder können die begrenzte Konfiguration lesen. Alle anderen Agentenfelder bleiben unverändert, einschließlich Anweisungen, Modell und der exakten Zugriffsrechte auf Secrets. Der native Hash schützt vor konkurrierenden Tool-Änderungen; eine geänderte Auswahl macht auch veraltete vollständige Agentenspeicherungen ungültig. Eine gleichwertige Auswahl ändert weder Zeitstempel noch Audit-Einträge. Fehlt der Runtime die angeforderte Fähigkeit, lehnt sie den Vorgang ab. Lies die Tools nach dem Anwenden zurück und bewahre den ausstehenden Beleg auf, um einen unterbrochenen Vorgang fortzusetzen.

Mit agent-model legst du die Ausführungskonfiguration für künftige Starts eines vorhandenen Agenten fest. config benötigt die exakten Werte für projectId und agentId sowie harness, model und einen ausdrücklich gewählten modelProvider aus dem nativen Katalog. Die Plattform prüft diese Kombination und die verfügbaren Zugangsdaten; sie weicht nicht auf einen anderen Anbieter aus. Es gelten dieselben Bearbeitungsrechte für das Projekt und dieselbe Einschränkung für plattformverwaltete Agenten. Anweisungen, Tools, Skills, Konnektoren und Secret-Berechtigungen bleiben unverändert. Bereits eingereihte und laufende Arbeit behält die vollständige Konfiguration, die bei ihrer Zulassung gespeichert wurde. Eine identische Auswahl ändert nichts; eine geänderte Auswahl macht veraltete vollständige Agentenspeicherungen ungültig. Ein bisher nicht festgelegter Anbieter erscheint beim Zurücklesen als null, in einer Deklaration musst du jedoch einen auswählen. Nutze die vorhandenen Befehle zum Planen, Anwenden und Zurücklesen und bewahre bei einer Unterbrechung den Beleg auf.

Mit task-review-context registrierst du eine unbenutzte operative Aufgabe für genau einen Prüfer. config enthält projectId, taskId, reviewerAgentId und enabled. Standardmäßig muss die Aufgabe bereits existieren und darf keinen Ausführungs- oder Prüfverlauf und keine Umsetzungsarbeit enthalten. Zum Erstellen ergänzt du createIfMissing: true neben kind und config und wählst eine feste UUID für taskId. Mit Bearbeitungsrechten für das Projekt kannst du die Backlog-Aufgabe dann in einer Transaktion erstellen und registrieren. Scheitert die Registrierung, bleiben weder Aufgabe noch Änderungen an Zählern oder Audit-Protokoll zurück. Der Prüfer benötigt bereits task_review; die Registrierung vergibt keine Tools und startet keine Arbeit. Bestehende Aufgaben müssen weiterhin die Prüfungen für unbenutzte Aufgaben bestehen; belegte Identitäten werden nie überschrieben. Behalte bei einer Unterbrechung dieselbe ID und den ausstehenden Beleg. Beim Deaktivieren bleiben Prüfer und Zweck erhalten.

Aufbewahrungs- und DSAR-Richtlinien brauchen ihre eigenen nativen Workflows. Pausiere Uploads, Synchronisation und Crawls, bevor du das Embedding-Modell wechselst. Die CLI prüft die Anzahl der Dokumente und Websites der gesamten Organisation; sie sperrt den Import nicht und migriert keine bestehenden Vektoren. Hat die Organisation Dokumente oder registrierte Websites, braucht ein Modellwechsel eine separate native Indexmigration. Eine Änderung, die nur minSimilarity, maxConcurrentRequests, minTokensPerSecond, maxTokensPerMinute oder maxRequestsPerMinute betrifft, lässt die vorhandenen Vektoren gültig; für sie entfällt diese Prüfung. Instanz-Einstellungen erfordern zusätzlich die native Freigabeliste für Deployment-Editoren. Bei Boot-Einstellungen meldet der einzelne Konfigurationsaufruf restartRequired; Speichern allein aktiviert diese Einstellungen noch nicht. Prüfe die Folgen im Plan vor dem Anwenden.

Verwaltete Deployments nutzen denselben Ablauf über configuration. Ergänze die Deployment-Deklaration um dieses Beispiel, wenn ein externer Betreiber den Anbieter bereits bereitstellt. Ersetze den synthetischen Endpunkt und Katalog durch geprüfte Werte und übergib EXTERNAL_PROVIDER_SECRET aus deinem Secret Manager:

{
  "environment": {
    "TALE_PROVIDER_KEY_EXTERNAL": {
      "env": "EXTERNAL_PROVIDER_SECRET"
    }
  },
  "configuration": {
    "schemaVersion": 1,
    "resources": [
      {
        "kind": "provider",
        "config": {
          "name": "external-chat",
          "displayName": "External chat",
          "apiFormat": "openai",
          "baseUrl": "https://models.example.invalid/v1",
          "catalog": {
            "source": "models-endpoint"
          },
          "embedding": "unknown",
          "auth": [
            {
              "method": "env"
            }
          ]
        },
        "expectedModels": [
          {
            "id": "Example-chat",
            "provider": "external-chat",
            "tags": ["chat"],
            "supportsTools": true,
            "supportsVision": false,
            "contextWindow": 131072
          }
        ]
      },
      {
        "kind": "provider-credential",
        "config": {
          "providerSlug": "external-chat",
          "authMethod": "env",
          "name": "Managed external provider",
          "envName": "TALE_PROVIDER_KEY_EXTERNAL",
          "modelAllowlist": ["Example-chat"]
        }
      }
    ]
  }
}

Für envName gelten das native Präfix TALE_PROVIDER_KEY_ und die Grenze von 40 Zeichen. Jeder Alias braucht eine verpflichtende environment-Referenz. Private Endpunkte erfordern zusätzlich eine explizite Referenz TALE_ALLOW_PRIVATE_PROVIDER_HOSTS mit dem Wert 1; native Host-Regeln gelten weiter. expectedModels prüft Tales frisch aufgelösten Katalog beim Rücklesen. Das belegt weder Inferenzkapazität und Latenz noch fachliche Ergebnisse.

Die Bildmodellauswahl nutzt governance mit key: "vision_model" und den nativen Feldern providerSlug/modelId. Embedding nutzt knowledge-embedding mit providerSlug, model, dimensions und baseUrl, dazu die optionalen Einstellungen, die die Plattform neben dem Modell in embedding.json hält: minSimilarity, die Kosinus-Untergrenze des Assistenten für dieses Modell, sowie die Servergrenzen maxConcurrentRequests, minTokensPerSecond, maxTokensPerMinute und maxRequestsPerMinute (Anfragen an einen selbst betriebenen Embedding-Server dosieren). Für jede gilt die Regel der Plattform selbst: Ein Wert setzt sie, ein weggelassener Schlüssel lässt stehen, was die Datei hält (ein von Hand gesetzter Wert überlebt ein Release, das ihn nicht erwähnt), und null löscht sie — "minSimilarity": null etwa ist der einzige Weg, eine Untergrenze über die CLI zu entfernen. Wenn du Standardzugangsdaten ersetzt, deklariere auch die bisherigen Umgebungszugangsdaten mit isDefault: false; die CLI wendet diese explizite Änderung zuerst an. Schlüsselwerte stehen weder in der Deklaration noch im Beleg.

Die native Einrichtung folgt auf die Identitätsprüfung und läuft vor den Konfigurations-Releases. Der Beleg native.configuration bindet Deklarations- und Bundle-Hashes, Organisation, Ressourcen-Hashes und native Revisionen. Vor der ersten Änderung entsteht ein ausstehender Beleg. Scheitert eine spätere Ressource, können frühere Änderungen bestehen bleiben. Lies den nativen Zustand und den Beleg, bevor du denselben geprüften Plan erneut ausführst. Natives Compare-and-set schützt jede Ressource vor konkurrierenden Admin-Änderungen; eine ressourcenübergreifende Transaktion gibt es nicht. Bewahre Deployment-Zustand, Snapshots und Belege für die Wiederherstellung auf.

Verwaltete Deployments aktivieren auch eine deklarierte deployment-Ressource, bevor sie Bereitschaft melden. Die CLI speichert die ausstehende Aktivierung, wartet bis zu fünf Minuten auf das Ende laufender Sitzungen im geprüften Sandbox-Spawner und startet dann diesen Container neu. Laufen noch Sitzungen, bleibt der Vorgang ausstehend. Der Beleg configurationActivation erfasst die eingebundene Konfiguration und den beobachteten Container-Start; Bereitschaft setzt erneute Gesundheitsprüfungen voraus. Bei einer Wiederholung prüft die CLI einen bereits angenommenen Neustart. Eine unveränderte Wiederholung nach erfolgreicher Aktivierung startet den Dienst nicht erneut.

Einen ausstehenden Konfigurationsplan ersetzen

Kann ein unterbrochener Plan noch abgeschlossen werden, führe denselben Plan erneut aus. Ein ausdrücklicher Ersatz ist nötig, wenn die deklarierten Einstellungen nicht mehr funktionieren können, etwa weil ein Embedding-Endpunkt nicht mehr verfügbar ist. Bewahre den vorhandenen Beleg auf: Er hält fest, welche Änderungen die Plattform bereits erreicht haben können.

1. Lies den ausstehenden Beleg und vergleiche die deklarierten Ressourcen mit dem aktuellen Zustand der Plattform. Speichere die korrigierten Einstellungen in replacement-configuration.json. Ziel und Ressourcenkennungen müssen exakt gleich bleiben; Ressourcen lassen sich dabei weder hinzufügen noch weglassen.
2. Berechne den Hash von plan im aufbewahrten Beleg, nicht vom gesamten Beleg oder vom Ersatzplan. Der folgende Befehl benötigt Bun. Er verwendet kanonisches JSON: rekursiv sortierte Objektschlüssel, unveränderte Array-Reihenfolge und keine Leerzeichen.

PENDING_PLAN_SHA=$(bun -e '
  const receipt = await Bun.file(process.argv[1]).json();
  if (receipt.phase !== "pending") throw new Error("Receipt is not pending");
  function canonical(value) {
    if (Array.isArray(value)) return "[" + value.map(canonical).join(",") + "]";
    if (value !== null && typeof value === "object") {
      return "{" + Object.keys(value).sort().map(key =>
        JSON.stringify(key) + ":" + canonical(value[key])
      ).join(",") + "}";
    }
    return JSON.stringify(value);
  }
  console.log(new Bun.CryptoHasher("sha256")
    .update(canonical(receipt.plan)).digest("hex"));
' configuration-receipt.json)

3. Erstelle aus der Ersatzdeklaration einen neuen Plan und prüfe ihn vor dem Anwenden:

tale --json config plan --file replacement-configuration.json \
  --url "$TALE_URL" --org "$TALE_ORG_ID" --output replacement-plan.json

Wende den geprüften Plan mit dem bisherigen Belegpfad und dem Hash des aufbewahrten Plans an:

tale --json --yes config apply --file replacement-configuration.json \
  --url "$TALE_URL" --org "$TALE_ORG_ID" \
  --plan replacement-plan.json --receipt configuration-receipt.json \
  --supersedes-pending-plan "$PENDING_PLAN_SHA"
tale --json config read --file replacement-configuration.json \
  --url "$TALE_URL" --org "$TALE_ORG_ID"

Jede Ressource muss weiterhin dem ursprünglichen Zustand, der beabsichtigten Änderung oder dem verifizierten Ergebnis des ausstehenden Plans entsprechen. Eine unabhängige Änderung auf der Plattform blockiert den Ersatz vor dem ersten Schreibzugriff. Kläre die Abweichung mit dem zuständigen Administrator; entferne den Beleg nicht, um die Prüfung zu umgehen.

Unter superseded bewahrt der Beleg den früheren Plan samt verifizierten Ressourcen auf, auch bei Unterbrechung und Wiederholung. Prüfe, ob der Beleg phase: "ready" erreicht und config read übereinstimmende Ressourcen meldet. Lass den einmaligen Auswahlparameter bei späteren Vorgängen weg.

Bei einem verwalteten Deployment setzt du supersedesPendingConfigurationPlan in der Deployment-Spezifikation auf denselben Hash des aufbewahrten Plans und korrigierst configuration. Bereite anschließend ein neues Bundle vor und prüfe es. Ersetzt dieses Bundle auch einen ausstehenden Rollout, gib dessen Hash zusätzlich über supersedesPendingBundle an. Dieser Bundle-Parameter allein erlaubt keinen Ersatz des nativen Konfigurationsplans. Entferne beide Wiederherstellungsparameter aus späteren Spezifikationen, sobald der Vorgang bereit ist.

Der öffentliche Nachweis native.configuration enthält pro Ressource den beabsichtigten Hash als configurationSha256 und den Hash des zurückgelesenen Zustands als observedConfigurationSha256. Beide können voneinander abweichen, wenn eine Einstellung einen vorhandenen Wert erhält, etwa bei einer ausgelassenen Ähnlichkeitsschwelle oder Servergrenze für Embeddings. Der private Beleg bewahrt den exakt beobachteten Zustand für die Wiederherstellung auf.

Betrieb

tale status — den aktuellen Deployment-Status anzeigen. Keine Argumente.

tale deploy smoke --url <url> — prüft ein laufendes Deployment über seine öffentliche URL, so wie ein Browser es erreicht. Ohne --full sendet der Befehl keine Zugangsdaten und schreibt nichts, du kannst ihn also gegen jedes Deployment laufen lassen, auch gegen die Produktion. Er prüft /api/health (mit --expected-version <version> auch die Version), die Bereitschaft der API, die App-Shell und ihr Skript, eine anonyme Sitzungsabfrage und ob /events und /api/app Besucher ohne Sitzung abweisen. Unverschlüsseltes http:// ist nur für localhost erlaubt; bei einer eigenen Zertifizierungsstelle setzt du NODE_EXTRA_CA_CERTS auf deren Stammzertifikat.

• --full — meldet sich zusätzlich mit einem eigens dafür angelegten Konto an und durchläuft einen Nutzerablauf: Er öffnet den Live-Update-Stream der Organisation, erstellt eine Aufgabe, wartet auf deren Live-Update, liest sie zurück und löscht sie (ein Konto, das keine Aufgaben löschen darf, archiviert sie stattdessen). Hinterlege das Konto in TALE_SMOKE_EMAIL und TALE_SMOKE_PASSWORD; es darf keinen zweiten Faktor verlangen. Sieht das Konto kein Projekt, legt der erste Lauf eines namens „Tale deployment smoke“ an, das spätere Läufe wiederverwenden.
• --chat — führt mit --full zusätzlich eine Chat-Runde mit dem ersten Modell aus, das dem Konto zur Verfügung steht. Die Runde verbraucht Modell-Tokens; die Unterhaltung landet danach im Papierkorb, eine noch laufende Runde wird vorher gestoppt.
• --organization <id-or-slug>, --project <id> — wo der Ablauf läuft; standardmäßig in der ersten Organisation und dem ersten Projekt des Kontos.
• --timeout <seconds> — Obergrenze für jede Anfrage und jede Wartezeit (Standard 15); --turn-timeout <seconds> begrenzt die Chat-Runde (Standard 120).

Mit --json führt der Bericht jede Prüfung mit Status (pass, fail oder skip), Dauer und Grund auf. Exit-Code 0 heißt, dass alle Prüfungen bestanden wurden, 5, dass mindestens eine fehlgeschlagen ist, und 2, dass eine Option ungültig ist. Der vollständige Ablauf entfernt seine Aufgabe (gelöscht oder archiviert) und meldet sich ab, auch wenn eine Prüfung fehlschlägt.

tale logs <service> — Logs eines Dienstes streamen (service ist einer der laufenden Dienste; auf einem reinen Dev-Stack ohne Deployment fällt der Befehl auf den Dev-Container zurück).

• -f, --follow — der Log-Ausgabe folgen, während sie geschrieben wird.
• -n, --tail <lines> — nur die letzten N Zeilen anzeigen.
• --since <duration> — Logs seit einer relativen Zeit anzeigen (z. B. 1h, 30m).
• -c, --color <color> — eine bestimmte Deployment-Farbe ansprechen (blue oder green).
• --raw — die rohe, ungefilterte Log-Ausgabe streamen (keine Klassifizierung).

tale backup — unterstützte, vorhandene Projekt-Volumes sichern. Keine Argumente. Externe Datenbanken und Buckets brauchen eigene Backups; siehe Sicherungsumfang.

tale restore [snapshot-id] — einen Snapshot wiederherstellen; ohne ID werden die verfügbaren Snapshots aufgelistet.

• --stop — laufende Projekt-Container vor dem Wiederherstellen stoppen.
• -y, --yes — die Bestätigungsabfrage überspringen.

tale rollback — auf die vorherige Patch-Version zurückrollen (nur Patch-Ebene). Fragt vorher nach Bestätigung.

• -y, --yes — die Bestätigungsabfrage überspringen (im nicht-interaktiven Betrieb erforderlich).

Wartung

tale update — eine Workspace-Instanz auf eine neue Version bringen: CLI-Binary aktualisieren und Projektdateien synchronisieren, danach tale deploy ausführen. Workspace-Befehle gleichen sich an diese Version an. Verwaltete Bundles und Konfigurations-Releases behalten ihre separat festgelegte CLI-Revision.

• -v, --version <version> — auf genau diese Version aktualisieren (z. B. 0.9.0) statt der neuesten; erlaubt Downgrades.
• -f, --force — Re-Sync erzwingen und lokal geänderte Projektdateien überschreiben.
• --dry-run — anzeigen, was sich ändern würde, ohne etwas zu ändern.

tale migrate — die mitgelieferten Defaults für jede Organisation auf dem laufenden Deployment neu provisionieren — derselbe idempotente Schritt, den jeder Deploy ausführt, nur auf Zuruf. Schema-Migrationen sind kein Command: Das Backend wendet sie beim Start an, ein deployter Container ist also immer auf seinem eigenen Schema.

• --dry-run — zeigen, was laufen würde, ohne es auszuführen.

tale cleanup — inaktive (nicht-aktuelle) Container entfernen. Keine Argumente.

tale reset — alle Blue-Green-Container entfernen.

• -f, --force — die Bestätigungsabfrage überspringen.
• -a, --all — auch die zustandsbehafteten Infrastruktur-Container entfernen.
• --dry-run — den Reset vorab anzeigen, ohne Änderungen.

tale uninstall — das tale-CLI-Binary von diesem System entfernen. Fragt nach, bevor etwas gelöscht wird, und bietet an, zusätzlich das Sandbox-Gerät dieses Rechners zu trennen, das vom eingestellten tale daemon hinterlassene ~/.tale-daemon zu entfernen und die Docker-Ressourcen und Dateien eines Projekts abzubauen. Ohne --purge bleiben ein Projekt und seine Container unangetastet — führ darin tale reset --all aus, um sie zu entfernen. Lässt sich das Sandbox-Gerät nicht stoppen, wird nichts deinstalliert.

• -f, --force — die Bestätigungsabfrage überspringen (entfernt nur das Binary; die optionalen Aufräumschritte brauchen weiterhin --purge).
• --purge — zusätzlich das Sandbox-Gerät trennen und seine Arbeitsbereiche löschen, ~/.tale-daemon entfernen und, für ein vom aktuellen Verzeichnis aus gefundenes Projekt, dessen Docker-Ressourcen abbauen und seine Dateien löschen. Nicht umkehrbar.
• --dry-run — anzeigen, was entfernt würde, ohne etwas zu entfernen.

tale config show — das aufgelöste lokale Projektverzeichnis und die CLI-Version ausgeben. Außerhalb eines Projekts meldet der Befehl, dass er keines gefunden hat, und endet ohne Fehler.

Konfigurations-Releases

Diese Befehle nutzen die gewählte CLI-Revision ohne Instanzangleichung oder Docker-Operationen. Client-Konfigurationen veröffentlichen beschreibt Deskriptoren, Quell-Commits, Zugangsdaten und Wiederherstellung. Standardmäßig kennzeichnet der vollständige Quell-SHA das Release: Manifest-Schema 4/Compiler 3 mit releaseRef === sourceCommit. Native ganzzahlige Automatisierungsversionen bleiben davon getrennt.

build, verify und stage verlangen --repo <directory>, --descriptor <path> und --automation <name>. Der Deskriptorpfad ist repositoryrelativ. Ein Prüfmanifest darf absolut oder repositoryrelativ angegeben werden.

Die Quellvorbereitung verlangt Checkout-HEAD auf diesem vollständigen Commit und ein Ausgabeziel außerhalb des Checkouts. Sie baut committete Inhalte ohne zusätzlichen Katalog-Commit. Explizites stage --config-version wählt stattdessen den kompatiblen Katalogweg und verlangt --catalogue-commit, --catalogue-repository, --client und --ops-commit. Kombiniere --config-ref und --config-version nicht.

Native Befehle verlangen --stage <directory>, --url <origin>, --org <id> und --project <id>. Außer lokalem HTTP ist HTTPS Pflicht. Nutze --origin <origin> für die kanonische Browser-Origin hinter einem Proxy. Beide lesen TALE_CONFIG_COOKIE ausschließlich aus der Umgebung.

Beide nativen Befehle nehmen exakte Erwartungen über --config-ref, --source-repository, --artifact-sha256, --deployment-ref, --client und --automation entgegen. Historische Katalog-Flags bleiben kompatibel. verify-native liest nur; --allow-retained prüft eine explizit gewählte aufbewahrte Version, ohne sie als bereitgestellt auszuweisen. Ohne --native-version wählt die Prüfung die zuletzt gespeicherte Version. Die native API zeigt den Aufgabenvertrag nur für die bereitgestellte Version; eine Prüfung aufbewahrter Versionen kann dieses Feld nicht bestätigen.

Konfigurationsbefehle haben kein --dry-run: Nutze stage, verify --rebuild und verify-native. Erfolgs-JSON hat die Form {ok:true,command:"config <verb>",data}. Build- und Prüfdaten enthalten automationName, releaseRef, sourceCommit, artifactSha256, artifactPath und verified; kompatible Ausgaben verwenden configVersion statt releaseRef. SHA-Transferbelege und native Belege nutzen Schema 2. Ein Deployment-Ergebnis enthält automationVersion und unchanged; das explizite Feld verified gehört zur Prüfausgabe.

Sandbox-Gerät

Diese Befehle führen die Sandboxes deiner Tale-Organisation auf dem Rechner aus, auf dem du sie aufrufst. Sandboxes auf eigenen Geräten ausführen beschreibt, wie du ein Gerät unter Einstellungen > Sandboxes hinzufügst und dort den Befehl connect erhältst. Das Gerät speichert seine Konfiguration und Arbeitsbereiche in ~/.tale/sandbox; TALE_SANDBOX_HOME verlegt sie.

tale sandbox connect <site> --token <token> — diesen Rechner mit der Organisation verbinden, die das Token ausgestellt hat: prüft Docker (und bietet an, es zu installieren), registriert den Rechner und startet die Container des Geräts mit dem Release des Servers. site ist deine Tale-Website, etwa https://your-org.tale.dev. Das Token (tsdj_…) funktioniert einmal, innerhalb einer Stunde. Nur Linux und macOS.

• --name <name> — der Name, den Tale für das Gerät anzeigt (Standard: der Hostname des Rechners). Andere Zeichen als A–Z, a–z, Ziffern, ., - und _ werden zu Bindestrichen.
• --max-sessions <n> — wie viele Sandboxes hier gleichzeitig laufen, von 1 bis 256 (Standard: eine pro zwei CPUs und pro 4 GiB Arbeitsspeicher, die Docker nutzen kann, höchstens 16).
• --no-auto-update — dem Release des Servers nicht automatisch folgen; führ stattdessen nach jedem Tale-Update tale sandbox update aus.
• --docker-socket <path> — der Docker-Socket, den die Container des Geräts verwenden, für Rootless Docker (Standard: /var/run/docker.sock).

tale sandbox status — Verbindung, Organisation, Release und Container des Geräts anzeigen, dazu die gerade laufenden Sandboxes. Keine Argumente.

tale sandbox update — das Gerät sofort auf das Release des Servers bringen und die aktuellen Adressen des Servers für seine Sandboxes übernehmen (nötig, nachdem sich die Adresse des Backends oder des Modell-Gateways geändert hat). Keine Argumente.

tale sandbox logs — das Log des Geräts anzeigen.

• -f, --follow — neue Zeilen fortlaufend ausgeben.
• --tail <lines> — wie viele Zeilen zuerst angezeigt werden (Standard: 200).

tale sandbox disconnect — das Gerät aus seiner Organisation entfernen, seine Sandboxes stoppen und ihre Arbeitsbereiche von diesem Rechner löschen. Fragt vorher nach und ändert nichts, solange Docker nicht läuft. Ist der Server nicht erreichbar, wird der Rechner trotzdem aufgeräumt, und ein Admin entfernt das Gerät unter Einstellungen > Sandboxes.

• --keep-data — die Arbeitsbereiche auf diesem Rechner behalten.
• -f, --force — die Bestätigungsabfrage überspringen.

Erweitert

tale auth hash-password — den Better-Auth-Hash eines Passworts ausgeben, für einen Break-Glass-Administrator.

Der Befehl liest das Passwort von stdin oder im interaktiven Terminal aus einer verdeckten Eingabe mit Bestätigung. Er lehnt ein Passwort ab, das die Standard-Passwortrichtlinie der Plattform verletzt, und gibt nur den Hash aus.

tale auth reset-owner — die Zugangsdaten des Owner-Kontos zurücksetzen.

Führe den Befehl bei einer manuellen Wiederherstellung ohne Flags im interaktiven Terminal aus. So gibst du das Passwort verdeckt ein, ohne es in Shell-Verlauf oder Argumenten abzulegen. Die Rücksetzung macht bestehende Sitzungen ungültig.

• -e, --email <email> — eine neue Owner-E-Mail-Adresse setzen.
• -p, --password <password> — ein neues Owner-Passwort setzen.

Fehlersuche

• tale deploy trifft die falsche Maschine. Die CLI nutzt den Docker-Kontext / DOCKER_HOST deiner Shell. Wechsle mit docker context use … (oder setz DOCKER_HOST), sodass er auf den gewünschten Host zeigt, und lauf erneut.
• tale deploy nutzt den falschen Host-Alias. Der Host, auf dem der Proxy antwortet, kommt aus HOST im .env des Projekts, nicht aus einem separaten CLI-Speicher. Bearbeite .env oder übergib --host, um ihn für einen Lauf zu überschreiben.
• Installer scheitert auf macOS, weil das Binary nicht ausführbar ist. Verweigert das frisch installierte Binary den Start (z. B. weil Gatekeeper es beendet), bricht der Installer mit Hinweisen zur Behebung ab, statt Erfolg zu melden — folg ihnen und lauf den Installer erneut.
• tale nach der Installation auf Linux nicht gefunden. Der Installer legt das Binary in /usr/local/bin ab; verifizier, dass das Verzeichnis im PATH des Users ist (echo $PATH).

Für den laufenden Betrieb helfen Upgrades, Backups und Wiederherstellung und Container-Architektur.