Proposal: CAIPE External Apps

[subbaksh]

CAIPE External Apps

Discussion proposal

• Status: For discussion
• Audience: CAIPE technical and product leadership
• Purpose: Agree on the platform direction and MVP boundary before writing detailed contracts

Proposal

CAIPE should support externally developed web applications as first-class UI
surfaces. An app would run as its own microservice, potentially from a separate
repository, while appearing inside CAIPE as an app or tab.

CAIPE would remain the host and security boundary. It would own app registration,
navigation, authentication, authorization, proxying, theme and user context, and
access to CAIPE agents. The app would own its UI, domain APIs, and data.

This gives teams a supported extension point without requiring them to fork the
CAIPE frontend or depend on internal React components.

Why this is worth doing

Dashboards, operational workbenches, reports, and domain tools are often better
expressed as focused applications than as chat alone. Today they must either:

• Add their source directly to CAIPE and couple their release cycle to it.
• Run separately and lose the CAIPE identity, authorization, theme, and agent
  experience.
• Integrate informally against internal APIs that were not designed as a stable
  platform boundary.

The proposed middle ground is independently owned code with centrally governed
integration.

Architecture in one picture

flowchart LR
  U[User] --> H[CAIPE UI and BFF]
  H -->|same-origin app route| W[External app web service]
  H --> C[CAS]
  H --> D[Dynamic Agents]
  D --> G[AgentGateway]
  G --> M[Optional app MCP service]
  W --> A[(App-owned data and jobs)]
  W -->|resource decisions| H

Loading

The important boundary is not the iframe. The important boundary is that CAIPE
continues to mediate identity, policy, and agent access while the external
service remains responsible for its own domain behavior.

Responsibilities

Area	CAIPE owns	App owns
Experience	Navigation, app frame, lifecycle	Pages and interaction design
Identity	User authentication and trusted app identity	Verification and local request context
Authorization	CAS decisions and relationship management	Enforcement on app API and data boundaries
Theme	Resolved theme values and change notifications	Applying those values to app styles
Agents	Discovery, user authorization, invocation and streaming	Deciding where agents improve the app experience
Data	No direct ownership of app domain data	Storage, jobs, artifacts and domain lifecycle
Operations	Installation, enablement, health policy and audit	Runtime health, scaling and dependency handling

The platform contracts we need

This proposal needs a small number of stable contracts. Detailed manifests,
payloads, schemas, and endpoint definitions should be defined in the next design
notes rather than as part of this discussion.

Host context

The browser app needs a small CAIPE SDK providing:

• Safe information about the current user.
• The current theme as resolved CSS variables, not only a name such as nord.
• Notification when the theme or appearance preferences change.
• The app's own identity and mount context.

This is a browser bridge, not access to CAIPE session state or credentials.

App identity

CAIPE authenticates and authorizes requests before proxying them to the app with
a short-lived identity bound to the user and app. The app verifies that identity;
browser JavaScript never receives it. Public-key verification avoids sharing a
platform-wide signing secret with independently owned apps.

App resources and CAS

Apps describe the resource kinds they own, such as reports, repositories, jobs,
or artifacts. CAIPE maps them into a generic, app-namespaced model rather than
changing OpenFGA for every app.

CAS remains the policy decision point. Enforcement remains with the component
serving the resource:

• CAIPE enforces access to CAIPE APIs and app launch.
• The app service enforces access to its APIs and data.
• An app MCP service enforces access to resources exposed through tools.
• Dynamic Agents enforces access to agents.

UI checks improve the experience; the serving API makes the authoritative check.
Authorization failures and CAS outages fail closed.

Agents

Apps consume CAIPE agents, not LLMs. CAIPE retains models, prompts, tools,
credentials, and execution policy.

The browser SDK should support:

• Listing agents available to this app and the current user.
• Invoking an agent.
• Streaming output and handling interruption, resume, and cancellation.

The list is the intersection of agents allowed for the app and for the user, and
contains no internal agent configuration. The MVP supports browser calls using
the user's CAIPE session; server-side agent delegation is deferred.

How a separate microservice participates

1. An operator installs an app and configures its internal service origin.
2. CAIPE shows the app only to users who may launch it.
3. The browser loads it through a CAIPE-owned, same-origin route.
4. CAIPE proxies requests to the service with a short-lived app identity.
5. The service verifies that identity and uses CAS for protected app resources.
6. Browser code calls CAIPE's App Agent API when it needs an agent.

The service needs no CAIPE cookie, user OIDC token, direct OpenFGA access, or
direct Dynamic Agents access. This preserves independent deployment while
keeping policy and audit consistent.

How dashboard-apps fits

The generic App platform and dashboard-apps are related but orthogonal. The
platform defines how any external app integrates; dashboard-apps packages a
set of first-party dashboard experiences.

A shared dashboard-apps Deployment can serve Weather, FinOps, and OSS
Repository Management modules. CAIPE should still register each module as a
separate app with its own route, visibility, health, resource kinds, and allowed
agents. They may point to the same service origin today and separate into
different services later without changing the platform contract.

An optional MCP service can expose typed dashboard actions through AgentGateway,
and long-running analysis can use workers or Jobs. Neither is a generic App
platform requirement. This separation preserves both options:

• First-party suites can optimize packaging and operations.
• Independently owned apps can deploy separately.
• Both use the same CAIPE integration and security model.

Security position

The MVP is for explicitly installed applications inside the deployment trust
boundary, not arbitrary marketplace code. Even within that boundary:

• CAIPE credentials and browser cookies are not forwarded to app services.
• App identity is short-lived and audience-bound.
• Apps cannot use their identity to query another app's resources.
• Launch permission is not treated as permission to every app resource.
• Apps call CAIPE/CAS rather than reproducing authorization logic.
• Agent access is checked on every invocation.
• Decisions and important operations carry both user and app identity in audit.

A less-trusted sandboxed or cross-origin mode can follow later.

Road to an MVP

Step	What it proves
1. Recover the experimental host foundation on current main	A separate service can be installed, health-gated, and safely loaded through CAIPE
2. Add browser context and theme	The app feels integrated without reading CAIPE internals or credentials
3. Add generic app resources to CAS	The service can create, share, and protect domain data while acting as a thin PEP
4. Add browser-side agents and pilot with Weather	An external app can use context, theme, protected resources, and a permitted agent end to end

The MVP is complete when a second app can be registered without modifying CAIPE
source, proving that the host contains no app-specific integration logic.

Next design steps

After agreeing the overall direction, define the following contracts as separate,
short design notes:

Next design step	Scope
App registration contract	Manifest, install state, route ownership, compatibility and health
Proxy and identity contract	Header policy, token claims, signing/JWKS, CSRF and audit
Browser SDK contract	Message handshake, safe user DTO and theme CSS variable allowlist
App authorization contract	Resource namespace, lifecycle, decisions, grants and failure semantics
App Agent API contract	Safe agent DTO, allowlisting, conversation behavior and streaming
Dashboard runtime design	Module layout, optional MCP server, workers, jobs and artifacts

References

• Current CAIPE CAS architecture
• Current CAS decision API
• Current RBAC-filtered agent discovery
• Current agent streaming proxy
• Current CAIPE theme variables
• Experimental Agentic Apps documentation

[sriaradhyula]

@subbaksh - We need some more detail on the parent app binding with external apps using microfrontends.

[subbaksh]

Ack. Will add more detail here on the binding. Apps are essentially microservices with same and must be in the same trust boundary. I will see if i can prototype this, and add specificity.

[sriaradhyula]

@subbaksh - We could look at SPIFFE

[subbaksh]

Ack. Will look at SPIFFE and how we can give apps identity.

[sriaradhyula]

@subbaksh - How do we update the apps agentically and deploy via runtime?

[subbaksh]

So the idea is that the deployment of the apps is completely separate and its own container/microservice.
The main thing is having a contract/API + reusable modules that can be used by Apps.

Dashboards itself can be an app with its own codebase.

[sriaradhyula]

@subbaksh - Suggestion to call it "Agentic apps"?

[subbaksh]

Yes happy to say these are Agentic apps.
Apps is also okay, maybe CAIPE apps, we can see what name suits better in UX and with wider community

[subbaksh]

A pre-requisite for having a standardized API for apps is CAS
https://github.com/orgs/caipe-io/discussions/2406