Architecture and components

An installation of Labtagon AI OS is one Helm release in one namespace, the platform namespace. The tool servers people and organisations build are not part of the release: they are data in Postgres, and a controller turns them into pods in namespaces of their own.

How a call travels

• A person in the console. The browser loads the console and talks to the control API under /api. The control API signs the person in through your OpenID Connect provider. A chat message that needs a model goes through the LLM gateway inside the control API to a model provider.
• A client over MCP. Claude Code, Codex, Cursor or an agent calls https://<host>/mcp. The MCP gateway checks the token, looks up the client’s profile, holds a call that needs an approval, records the call and passes it on: to an instance of a tool server, or to AI OS’s own tools in the control API.
• A tool server going out. An instance reaches nothing but the egress gateway. The egress gateway lets it reach only the hosts approved for it, and only on the way out puts the real key or token in place of the placeholder the instance holds.
• An application of your own. It calls the OpenAI-compatible API at /api/llm/v1 with an API key; the control API answers through the same LLM gateway as the chat.

The components

The chart’s components (components.* in values.yaml), each a Deployment with a ServiceAccount and a Service:

Component	Image	What it does
Console	ai-os-console	The app people use in the browser, served as static files.
Control API	ai-os-control-api	The console’s API and sign-in; the LLM gateway (/api/llm/v1 and every model call); AI OS’s own tools, Studio’s included; the capabilities; the bundle port that build jobs and instances fetch code from; the authorization server for clients (/api/agent-sign-in).
MCP gateway	ai-os-gateway	The one address /mcp for every client: checks tokens, applies profiles, holds calls for approval, records them, and serves file links at /f.
Controller	ai-os-controller	Turns what Postgres says into Kubernetes objects: people’s and organisations’ namespaces, instances, build jobs, sandboxes, their network policies. The only component with rights on the Kubernetes API. Applies the database migrations at start. Two replicas with leader election.
Egress gateway	ai-os-egress	The only way out for instances, build jobs and sandboxes. Enforces the approved hosts and API rules (ADR 0054), fills in credentials on the way out, and is the token broker for OAuth sign-ins (ADR 0020). The only component that can decrypt stored credentials.
Classifier	ai-os-classifier	Optional, off by default: an action classifier on llama.cpp (ADR 0015), with a GPU if you give it one.

Images that the controller and the build jobs use:

Image	What it does
Bundle fetcher (ai-os-bundle-fetch)	The init container of every instance: fetches the tool server’s code bundle from the control API, checks its SHA-256 against the digest in the approval and unpacks it read-only. Build jobs use it to fetch their source and hand in the bundle.
Build checks (ai-os-build-checks)	The steps of every build (ADR 0052): an SBOM (syft), known vulnerabilities and malicious packages (osv-scanner), a code check (bandit, eslint) and the server’s own tests. Without checks.digest or checks.tag, builds run without checks.
Runtimes	Official upstream images a tool server runs on: uv with Python 3.13, Node 24, Playwright for Python and for Node, each pinned by digest (runtimes.*), all run as user 65532.
Sandbox (ai-os-sandbox)	Code sandboxes (ADR 0064): code__run for Python and JavaScript/TypeScript in a pod per person and conversation, under gVisor. Off by default (sandboxes.enabled).
Code environments (ai-os-devenv)	A repository and a coding CLI in a pod per session (ADR 0094, a draft). Off by default (devenvs.enabled).

Services the chart runs beside them, each reachable only by the components that need it:

Service	Default	What it does
Postgres (CloudNativePG)	on, 2 instances	Everything AI OS keeps: chats, servers and their versions and bundles, builds, instances, approvals, settings, memories with their vectors (pgvector), the audit log, and credentials as age ciphertext.
Garage or any S3	Garage, one node	The bytes of files, encrypted by the control API and the gateway before they leave (ADR 0093).
SearXNG	on	Web search for the capability Search the web.
Docling (docling-serve)	on	Reads PDFs, Office files, web pages and pictures for the capability Read documents, with its models in the image.
Gotenberg	off	Shows Office documents as PDFs in the console (LibreOffice, macros off).
Presidio	off	Finds personal data in prompts and tool calls; reached by the gateway and the control API.

Outside the chart: your OpenID Connect provider (Keycloak, or another), the model providers your administrators set up, and the services tool servers call on the internet.

Where people’s tool servers run

• A person’s instances run in a namespace of their own: instances.namespacePrefix (ai-os-u-) followed by 12 hex digits of a hash of their subject, on instances.quota.
• The instances an organisation shares run in its namespace (instances.orgNamespacePrefix, ai-os-o-), on instances.orgQuota (ADR 0044, 0057).
• Build jobs run in builds.namespace (ai-os-builds); sandboxes and code environments in sandboxes.namespace (ai-os-sandboxes).
• An admission policy lets only the controller write workloads into these namespaces, and pods there run only images by digest from allowedRegistries and AI OS’s own registry.
• An idle instance goes to sleep after 15 minutes by default and wakes on the next call (settings instances.idleTimeout and instances.idleTimeoutMax, at most 4 hours by default).

Keys

The platform’s keys come in one Secret (keys.existingSecret, default ai-os-keys); each component mounts only its part. What they are for, and why you must keep them, is in Installing with Helm and Backups and restore.