Zum Inhalt springen
AI OSHandbuch

Aufbau und Komponenten

Eine Installation von Labtagon AI OS ist ein Helm-Release in einem Namespace, dem Plattform-Namespace. Die Tool-Server, die Personen und Organisationen bauen, gehören nicht zum Release. Sie sind Daten in Postgres, und ein Controller macht daraus Pods in eigenen Namespaces.

Aufbau einer Installation von Labtagon AI OSEingang: HTTPRoute (Gateway API) oder Ingress · global.host: /mcp, /api, /f, / · optional global.appHostPlattform-Namespace · abgeschottetNamespaces, die der Controller anlegtPersonen im Browserdie Konsole (App)Clients und AgentenClaude Code, Codex, Cursor … über MCPEigene AnwendungenAPI-Schlüssel, /api/llm/v1Konsoledie AppControl APIKonsolen-API, LLM-Gateway, StudioMCP-GatewayProfile, Freigaben, Tool-AufrufeControllerMigrationen, InstanzenPostgresCloudNativePGGarage / S3verschlüsseltEingebaute DiensteSearXNG, Docling, Gotenberg, PresidioEgress-Gatewayeinziger Weg hinausSandboxes, Code-UmgebungengVisor, je PersonBuild-Jobsmit Prüfungen: SBOM, OSV, TestsTool-Server-Instanzenje Person oder OrganisationAußerhalbInternet, Modelle, OIDC

Welchen Weg ein Aufruf nimmt

Abschnitt betitelt „Welchen Weg ein Aufruf nimmt“
  • Eine Person in der Konsole. Der Browser lädt die Konsole und spricht unter /api mit der Control API. Die Control API meldet die Person über deinen OpenID-Connect-Provider an. Eine Chat-Nachricht, die ein Modell braucht, geht durch das LLM-Gateway in der Control API zu einem Modell-Provider.
  • Ein Client über MCP. Claude Code, Codex, Cursor oder ein Agent ruft https://<host>/mcp auf. Das MCP-Gateway prüft das Token, schlägt das Profil des Clients nach, hält einen Aufruf an, der eine Freigabe braucht, zeichnet den Aufruf auf und reicht ihn weiter: an eine Instanz eines Tool-Servers oder an die eigenen Tools von AI OS in der Control API.
  • Ein Tool-Server nach außen. Eine Instanz erreicht nichts außer dem Egress-Gateway. Das Egress-Gateway lässt sie nur zu den Hosts, die für sie freigegeben sind, und setzt erst auf dem Weg hinaus den echten Schlüssel oder das Token anstelle des Platzhalters ein, den die Instanz hat.
  • Eine eigene Anwendung. Sie ruft die OpenAI-kompatible API unter /api/llm/v1 mit einem API-Schlüssel auf; die Control API antwortet über dasselbe LLM-Gateway wie der Chat.

Die Komponenten

Abschnitt betitelt „Die Komponenten“

Die Komponenten des Charts (components.* in values.yaml), jede ein Deployment mit ServiceAccount und Service:

Komponente Image Was sie tut
Konsole ai-os-console Die App, die Personen im Browser benutzen, als statische Dateien.
Control API ai-os-control-api Die API und die Anmeldung der Konsole; das LLM-Gateway (/api/llm/v1 und jeder Modellaufruf); die eigenen Tools von AI OS, auch die von Studio; die Capabilities; der Bundle-Port, von dem Build-Jobs und Instanzen Code holen; der Autorisierungsserver für Clients (/api/agent-sign-in).
MCP-Gateway ai-os-gateway Die eine Adresse /mcp für alle Clients: prüft Tokens, wendet Profile an, hält Aufrufe zur Freigabe an, zeichnet sie auf und liefert Datei-Links unter /f.
Controller ai-os-controller Macht aus dem, was in Postgres steht, Kubernetes-Objekte: Namespaces von Personen und Organisationen, Instanzen, Build-Jobs, Sandboxes und ihre Network Policies. Die einzige Komponente mit Rechten an der Kubernetes-API. Spielt beim Start die Datenbank-Migrationen ein. Zwei Replikas mit Leader Election.
Egress-Gateway ai-os-egress Der einzige Weg hinaus für Instanzen, Build-Jobs und Sandboxes. Setzt die freigegebenen Hosts und API-Regeln durch (ADR 0054), setzt Zugangsdaten auf dem Weg hinaus ein und ist der Token-Broker für OAuth-Anmeldungen (ADR 0020). Die einzige Komponente, die gespeicherte Zugangsdaten entschlüsseln kann.
Classifier ai-os-classifier Optional, standardmäßig aus: ein Aktions-Classifier auf llama.cpp (ADR 0015), mit GPU, wenn du ihm eine gibst.

Images, die der Controller und die Build-Jobs benutzen:

Image Was es tut
Bundle-Fetcher (ai-os-bundle-fetch) Der Init-Container jeder Instanz: holt das Code-Bundle des Tool-Servers von der Control API, prüft seinen SHA-256 gegen den Digest in der Freigabe und entpackt es schreibgeschützt. Build-Jobs holen damit ihren Quelltext und liefern das Bundle ab.
Build-Prüfungen (ai-os-build-checks) Die Schritte jedes Builds (ADR 0052): eine SBOM (syft), bekannte Schwachstellen und Schadpakete (osv-scanner), eine Code-Prüfung (bandit, eslint) und die eigenen Tests des Servers. Ohne checks.digest oder checks.tag laufen Builds ohne Prüfungen.
Runtimes Offizielle Images, auf denen ein Tool-Server läuft: uv mit Python 3.13, Node 24, Playwright für Python und für Node, jedes per Digest festgelegt (runtimes.*), alle als Benutzer 65532.
Sandbox (ai-os-sandbox) Code-Sandboxes (ADR 0064): code__run für Python und JavaScript/TypeScript in einem Pod je Person und Unterhaltung, unter gVisor. Standardmäßig aus (sandboxes.enabled).
Code-Umgebungen (ai-os-devenv) Ein Repository und ein Coding-CLI in einem Pod je Sitzung (ADR 0094, ein Entwurf). Standardmäßig aus (devenvs.enabled).

Dienste, die das Chart daneben betreibt, jeder nur für die Komponenten erreichbar, die ihn brauchen:

Dienst Standard Was er tut
Postgres (CloudNativePG) an, 2 Instanzen Alles, was AI OS aufbewahrt: Chats, Tool-Server mit ihren Versionen und Bundles, Builds, Instanzen, Freigaben, Einstellungen, Erinnerungen mit ihren Vektoren (pgvector), das Audit-Log und Zugangsdaten als age-Chiffrat.
Garage oder jedes S3 Garage, ein Knoten Die Bytes der Dateien, von Control API und Gateway verschlüsselt, bevor sie hinausgehen (ADR 0093).
SearXNG an Websuche für die Fähigkeit Im Web suchen.
Docling (docling-serve) an Liest PDFs, Office-Dateien, Webseiten und Bilder für die Fähigkeit Dokumente lesen, mit seinen Modellen im Image.
Gotenberg aus Zeigt Office-Dokumente in der Konsole als PDF (LibreOffice, Makros aus).
Presidio aus Findet personenbezogene Daten in Prompts und Tool-Aufrufen; erreichbar für Gateway und Control API.

Außerhalb des Charts: dein OpenID-Connect-Provider (Keycloak oder ein anderer), die Modell-Provider, die deine Administratoren einrichten, und die Dienste im Internet, die Tool-Server aufrufen.

Wo die Tool-Server der Personen laufen

Abschnitt betitelt „Wo die Tool-Server der Personen laufen“
  • Die Instanzen einer Person laufen in einem eigenen Namespace: instances.namespacePrefix (ai-os-u-) und 12 Hex-Ziffern eines Hashs ihres Subjects, mit instances.quota.
  • Die Instanzen, die eine Organisation teilt, laufen in deren Namespace (instances.orgNamespacePrefix, ai-os-o-), mit instances.orgQuota (ADR 0044, 0057).
  • Build-Jobs laufen in builds.namespace (ai-os-builds), Sandboxes und Code-Umgebungen in sandboxes.namespace (ai-os-sandboxes).
  • Eine Admission Policy lässt nur den Controller Workloads in diese Namespaces schreiben, und Pods dort starten nur Images per Digest aus allowedRegistries und der eigenen Registry von AI OS.
  • Eine Instanz ohne Aufrufe schläft standardmäßig nach 15 Minuten ein und wacht beim nächsten Aufruf auf (Einstellungen instances.idleTimeout und instances.idleTimeoutMax, standardmäßig höchstens 4 Stunden).

Schlüssel

Abschnitt betitelt „Schlüssel“

Die Schlüssel der Plattform kommen in einem Secret (keys.existingSecret, Standard ai-os-keys); jede Komponente bindet nur ihren Teil ein. Wofür sie sind und warum du sie aufbewahren musst, steht unter Installation mit Helm und Backups und Wiederherstellung.