Installation mit Helm

Labtagon AI OS wird mit einem Helm-Chart installiert, deploy/helm/ai-os. Diese Seite geht die Werte durch, die du setzen musst, die Schlüssel und die Anmeldung. Das Chart verweigert das Rendern, wenn ein Pflichtwert fehlt oder zwei Werte sich widersprechen; die meisten Fehler zeigen sich also, bevor etwas den Cluster erreicht.

Bevor du anfängst

Kubernetes 1.30 oder neuer, mit einem Metrics Server, wenn du die Autoscaler eingeschaltet lässt.
Eine Gateway-API-Implementierung mit einem Gateway für deinen Host, oder einen Ingress-Controller.
Den CloudNativePG-Operator (postgres.operatorNamespace, Standard cnpg-system) oder ein eigenes Postgres mit pgvector 0.8 oder neuer.
Einen OpenID-Connect-Provider. Die Beispiele verwenden Keycloak.
DNS und ein TLS-Zertifikat für deinen Host am Gateway oder Ingress.
Wenn du Sandboxes oder abgeschottete Tool-Server einschaltest: die RuntimeClass gvisor auf den Knoten, die sie ausführen (instances.sandboxedRuntimeClass, sandboxes.runtimeClass).

Die Pflichtwerte

Wert	Was
`global.host`	Der öffentliche Host der Konsole und des MCP-Endpunkts, zum Beispiel `ai.example.com`.
`global.imageRegistry`	Wo die eigenen Komponenten-Images von AI OS veröffentlicht werden.
`keycloak.issuer`	Der Issuer deines Providers, bei Keycloak `https://<keycloak>/realms/<realm>`.
`keycloak.*`	Die Clients, Scopes und Claims, wenn deine anders heißen als die Standardwerte (unten).
`routes.kind`, `routes.parentRefs`	`httproute` (Standard) mit den Gateways, an die die Route sich hängt, oder `ingress` mit `ingressClassName` und `tlsSecretName`. `routes.fromNamespace` nennt den Namespace des Gateways oder Ingress-Controllers für die Network Policies (Standard `envoy-gateway-system`).
`keys.existingSecret`	Das Secret mit den Schlüsseln der Plattform (Standard `ai-os-keys`), oder `keys.externalSecret.enabled: true`, damit das Chart ein ExternalSecret anlegt.
`postgres.*`	`create: true` (Standard) legt einen CloudNativePG-Cluster mit `instances: 2` und `storage: 10Gi` an. Mit `create: false` nennt `existingSecret` ein Secret mit dem Schlüssel `uri` und `port` den Port, den die Network Policy öffnet.
`storage.*`	Wohin die Bytes der Dateien gehen: `garage` (Standard, das Chart betreibt Garage), `external` (jedes S3, mit `endpoint`, `region` und einem Secret mit `access-key-id` und `secret-access-key`) oder `postgres` (kein Objektspeicher).

Optional und auf einer eigenen Seite beschrieben: global.appHost, siehe App-Host.

Eine kleine Values-Datei:

global:
  host: ai.example.com
  imageRegistry: registry.example.com/ai-os
keycloak:
  issuer: https://id.example.com/realms/example
routes:
  kind: httproute
  parentRefs:
    - { name: platform, namespace: envoy-gateway-system, sectionName: https }
keys:
  existingSecret: ai-os-keys
postgres:
  create: true
  instances: 2
  storage: 10Gi
storage:
  mode: garage

helm lint deploy/helm/ai-os -f values.yaml
helm upgrade --install ai-os deploy/helm/ai-os -n ai-os-system --create-namespace -f values.yaml

Nach der Installation listen die Hinweise des Charts auf, was außerhalb noch zu tun ist.

Die Schlüssel

Ein Secret enthält die Schlüssel der Plattform. Leg sie einmal an; jede Komponente bindet nur ein, was sie braucht.

Schlüssel	Was er ist	Erzeugt mit
`age-identity`, `age-recipient`	Entschlüsselt und verschlüsselt die gespeicherten Anmeldungen und Schlüssel der Tool-Server (age). Nur das Egress-Gateway hat die Identity.	`age-keygen`
`approval-signing-key`, `approval-verify-key`	Die Control API signiert Freigaben, der Controller prüft sie, bevor er etwas startet. Die Schlüssel der LLM-Provider sind mit einem Schlüssel verschlüsselt, der vom Signaturschlüssel abgeleitet ist.	Ed25519-Schlüsselpaar
`agent-token-key`	Signiert die Access Tokens, die AI OS an Clients ausgibt (ADR 0059).	EC-P-256-Schlüssel, PKCS #8
`session-key`	Zufällige Bytes, eingebunden ins MCP-Gateway.	Zufallsbytes
`egress-ca.crt`, `egress-ca.key`	Die CA, mit der das Egress-Gateway je Host ein Zertifikat ausstellt; Instanzen vertrauen ihr.	ein CA-Zertifikat und sein Schlüssel

deploy/openbao/seed-ai-os.sh keys <mount> aus dem Repository legt alle direkt in OpenBao an, ohne sie auszugeben, und überschreibt keine vorhandenen.

Weitere Secrets, jedes optional:

storage.encryption: der Speicherschlüssel, der die Schlüssel der Dateien umhüllt. Ohne existingSecret legt das Chart einmal einen an und behält ihn (siehe Backups und Wiederherstellung).
push.secretName (ai-os-push): das VAPID-Schlüsselpaar für Browser-Benachrichtigungen. Ohne es gibt es keine.
fileLinks.secretName (ai-os-file-links): der Schlüssel der Vorschau-Links für Dateien in Clients, die Widgets zeigen (link-key). Ohne ihn gibt es keine Vorschauen.
modelKeys.*: API-Schlüssel der Sicherheits-, Entscheidungs- und Personendaten-Modelle, die das Gateway fragt.

Anmeldung

Personen melden sich in der Konsole über deinen OpenID-Connect-Provider an. Richte dort ein:

Den Client der Konsole keycloak.consoleClientId (ai-os-console), vertraulich, mit der Weiterleitungsadresse https://<App-Host>/api/auth/callback (ohne App-Host: global.host). Sein Secret kommt in das Secret keycloak.consoleClientSecretName (ai-os-console-oidc), Schlüssel client-secret.
Die Anmeldung der Clients. keycloak.agentClients listet die Clients, die der Verbinden-Dialog der Konsole zeigt, je einen Reiter: standardmäßig Claude Code, Codex, Cursor, claude.ai, Hermes und AI OS Workbench. Jeder Eintrag nennt eine Client-ID, einen Titel und eine eingebaute Anleitung (claude-code, codex, claude-ai, cursor, generic, workbench). Solange der Provider die Tokens der Clients ausgibt, ist jede ID ein öffentlicher Client mit PKCE beim Provider, und der Client Scope keycloak.mcpScope (ai-os-mcp) schreibt die Audience keycloak.audience in seine Tokens.
AI OS als Autorisierungsserver der Clients (ADR 0055, 0059): Mit profiles.signInChooser: true gibt AI OS die Tokens der Clients selbst aus, und Personen wählen ein Profil, wenn ein Client sich anmeldet. Der Provider meldet dann nur noch Personen in der Konsole an; kein Client je Werkzeug und keine zusätzliche Weiterleitungsadresse nötig. profiles.agentTokens sagt, wessen Tokens das Gateway annimmt: ai-os, upstream oder both (Standard, während eine Installation umzieht).
Claims. keycloak.rolesClaim (roles) trägt Realm-Rollen; die Rolle keycloak.adminRole (ai-os-admin) öffnet die Verwaltung. keycloak.groupsClaim (groups) trägt Gruppenpfade wie /sales: Bilde sie mit dem Group Membership Mapper von Keycloak (Full Path an) in das ID-Token der Konsole und in den Scope ai-os-mcp ab. Die Gruppen der Verwaltung entstehen daraus.
Organisationen. orgs.source ordnet Personen einer Organisation zu: nach der Domain ihrer bestätigten E-Mail-Adresse (domain, Standard) oder nach einem Claim (claim, bei Keycloak organization). orgs.bootstrap legt beim ersten Start Organisationen an. Siehe Organisationen und Anmeldung.
Ein Provider für die ganze Plattform (signIn.platform, ADR 0078): neben deinem eigenen, zum Beispiel Microsoft Entra ID für Organisationen ohne eigenen Provider.
„Mit AI OS anmelden“ für Tool-Server (ADR 0020): der vertrauliche Client keycloak.connectionsClientId (ai-os-connections) mit Offline-Zugriff und Token Exchange; nur der Token-Broker im Egress-Gateway liest sein Secret. Ohne ihn ist diese eine eingebaute Anmeldung aus; andere Provider funktionieren weiter.

Images und Festlegen per Digest

Die Komponenten von AI OS laufen per Tag (Standard: die appVersion des Charts), solange du sie nicht festlegst: components.<name>.digest, bundles.fetchDigest und checks.digest, jeweils sha256: und 64 Hex-Ziffern. Ist eine Komponente festgelegt, müssen es alle eingeschalteten und der Bundle-Fetcher auch sein; sonst rendert das Chart nicht.
Build-Prüfungen brauchen checks.digest (lokal checks.tag). Ohne laufen Builds ohne Prüfungen, und Verwaltung → Plattform sagt das.
Ein Mirror für Images von Dritten: global.mirror, ein Präfix im Aufbau der Proxy-Caches von Harbor, oder {prefix, registries}. Runtimes, Presidio, Postgres, Garage, SearXNG, Docling und die Images, die Personen ihren Servern geben, werden darüber geholt. allowedRegistries listet die ursprünglichen Registries, aus denen Pods ziehen dürfen, immer per Digest.

Einstellungen, die die Installation festlegt

Das meiste Verhalten von AI OS steht in Einstellungen, die Administratoren in der Konsole ändern. settings: in den Values legt einige für alle Organisationen fest; die Konsole zeigt sie dann gesperrt. Zum Beispiel:

settings:
  instances.idleTimeout: 15m
  instances.idleTimeoutMax: 4h
  builds.allowHosts: "registry.npmjs.org,pypi.org,files.pythonhosted.org"

Das Chart lehnt einen Standardwert für das Einschlafen ab, der länger ist als der längste erlaubte.

Eine zweite Installation im selben Cluster

global.installation benennt eine Installation (zum Beispiel staging) und kennzeichnet alles, was sie anlegt. Sie braucht außerdem einen eigenen Release-Namen, Namespace, instances.namespacePrefix, instances.orgNamespacePrefix und builds.namespace.

Den ersten Start prüfen

Der Controller spielt beim Start die Datenbank-Migrationen ein; warte, bis seine Pods bereit sind.
Öffne https://<host>/ und melde dich mit einem Konto an, das die Rolle ai-os-admin hat.
Unter Verwaltung → Plattform siehst du Komponenten, Datenbank, Builds und Namespaces, wie der Controller sie sieht (alle 15 Sekunden, observe.interval).
Richte den ersten Modell-Provider ein: siehe Modelle und Provider.