Copilot Managed Runtime architecture (preview)

[This article is prerelease documentation and is subject to change.]

Copilot Managed Runtime architecture consists of:

• The Copilot Managed Runtime SDK (@microsoft/managed-apps)
• The Microsoft Copilot Managed Runtime CLI (@microsoft/managed-apps-cli)
• Generated models and services for connectors
• The ms.config.json configuration file
• The app's Git repository, either the platform-managed repository or an external GitHub repository you provide
• The Microsoft Copilot Managed Runtime host

Understanding how these parts collaborate through development, publishing, and runtime execution makes you more successful. Read this article to learn:

• The role of each layer: your code, the Copilot Managed Runtime SDK, and the Copilot Managed Runtime host.
• How models and services are generated and consumed when you add or remove connectors.
• What is packaged and published when you run ms app deploy.

App development

A TypeScript or JavaScript single-page application (SPA) is a prerequisite for using apps. The Copilot Managed Runtime CLI scaffolds a project that already includes the Copilot Managed Runtime SDK. Together, the CLI and SDK enable your app to use connectors and be hosted in a Copilot Managed Runtime environment.

Component	Description
ms.config.json	A file generated by the Copilot Managed Runtime CLI that contains metadata. The CLI and SDK read this metadata to wire up connections and to deploy the app to an environment. Your app logic isn't expected to interact with ms.config.json directly.
Copilot Managed Runtime SDK	The @microsoft/managed-apps npm package. It exposes typed APIs that your app calls directly and contains the logic that manages models and services as connections are added and removed from the app.
Copilot Managed Runtime CLI	The @microsoft/managed-apps-cli npm package, invoked as ms. It creates apps, scaffolds projects, manages connectors, and deploys to the Copilot Managed Runtime platform.
Git repository	The Git repository is the single source of truth. It can be platform-provisioned or an external GitHub repository you provide. Builds and deploys flow from real commits in this repository.

Important

Don't edit ms.config.json directly. The CLI and SDK own this file, and manual edits can put your app's local state out of sync with the platform. Update its contents through the appropriate ms commands instead; for example, use ms app add data-source to register a connector, or ms app set-setting to change app settings.

Runtime

When an app runs, it uses three logical components:

• Your code
• The Copilot Managed Runtime SDK: exposes APIs that your code uses and the generated models and services your app uses to perform data requests through connectors.
• The Copilot Managed Runtime host: manages end-user authentication through Microsoft Entra, app loading, runtime governance (Conditional Access, DLP, ACP, sharing limits), and surfaces contextual messages if the app fails to load.

Project files

The Copilot Managed Runtime CLI scaffolds a standard SPA project layout. The files specific to apps are:

File or folder	Purpose
ms.config.json	App metadata, including the app ID, the bound environment, and the registered connectors. The CLI and the SDK manage this file. Don't edit it directly. Use ms commands like ms app set-setting or ms app add data-source to update its contents.
generated/	Strongly typed models and services generated by ms app add data-source. Your code imports from this folder to call data sources.
package.json	Includes the Copilot Managed Runtime SDK as a dependency and any framework scripts your project uses.

The rest of the project, including components, routes, styles, and tests, is whatever your framework calls for. Copilot Managed Runtime doesn't impose conventions on your app code beyond the SDK API surface.