App host

By default everything of Labtagon AI OS is at one host, global.host: the console, /api, /mcp and its sign-in metadata. ADR 0097 lets you move the console to a host of its own.

The console on a host of its own

Set global.appHost, for example app.example.com:

global:
  host: example.com
  appHost: app.example.com
routes:
  parentRefs:
    - { name: platform, namespace: envoy-gateway-system, sectionName: https }
  # Only when the app host is on another Gateway:
  appParentRefs: []

Then:

• On the app host are the console and /api. People sign in and work there; the session’s cookies are the app host’s.
• The main host keeps what clients, agents and applications call: /mcp, the sign-in metadata under /.well-known, /api (the clients’ sign-in, the LLM gateway’s /api/llm/v1, the callbacks registered at providers) and the file links under /f. Registrations and tokens of clients stay as they are.
• The browser’s steps of signing in move to the app host: /api/auth/*, a connection’s callback and a client’s authorization answer with a redirect to the same address on the app host.
• / of the main host sends the browser to the app host. To answer there with something of your own, such as your website, set routes.mainHostRoot: false and route / of the main host yourself.

What to change elsewhere:

• The console’s OpenID Connect client needs the app host’s callback, https://<app host>/api/auth/callback, and its address after signing out.
• The new host needs a listener on the Gateway (or an Ingress), a certificate and a DNS record. With a listener per host on the same Gateway, appParentRefs can stay empty: Gateway API picks the listener by the route’s host names.

Links that AI OS writes into notifications and shares still name the main host, which sends them on to the app host (one redirect more).

The handbook

This handbook is a container of its own (ai-os-docs, from docs/handbook): a static site behind an unprivileged nginx on port 8080, with no analytics, no cookies and nothing loaded from other hosts. It is not part of the chart.