CopilotKit Intelligence architecture
How a CopilotKit runtime connects to Intelligence, and how cloud-hosted differs from self-hosted.
Overview#
You want to see how your app, your runtime, and Intelligence fit together, and which deployment to run. This page is that map. It applies to cloud-hosted Intelligence and to self-hosted Intelligence.
To connect a runtime, follow the quickstart. For the Kubernetes install, go to self-host on Kubernetes.
Runtime and platform roles#
A CopilotKit app has three layers:
- Frontend. Your application uses the CopilotKit frontend SDK to render chat, generative UI, tools, and thread controls.
- Runtime. Your application server hosts the CopilotKit runtime and connects to your agent framework through AG-UI.
- CopilotKit Intelligence. The platform service that stores threads, serves project APIs, and powers the web app.
The runtime is the bridge. It receives requests from your app, streams AG-UI events to and from your agent, and uses CopilotKit Intelligence when a capability needs durable platform state.
Project boundaries#
The platform scopes data through three concepts:
- Organization. The billing and workspace boundary.
- Project. One application or environment inside an organization, such as production, staging, or a demo.
- User. The signed-in person from your application.
Project API keys are issued per project. Threads, events, and dashboard history are visible only inside the project that owns them, so production and staging can share the same platform deployment without sharing conversation data.
Threads#
A thread is the saved conversation for one user in one project. Read Rich Threads for the product. Read how a thread is saved for replay and sync.
Realtime sync#
Realtime sync keeps thread metadata and active conversation state aligned across clients. When enabled, clients subscribe to platform-backed updates so changes such as renames, archives, and active-run status can appear without a page reload.
The important application-level contract is simple: your app uses the same frontend APIs, while the runtime points at the platform endpoint for the selected deployment.
Inspection#
Open a stored thread in the cloud-hosted project. API keys and plans live on Cloud-hosted and Plans.
Hosting model#
Cloud-hosted and self-hosted CopilotKit Intelligence share the same application contract:
| Deployment | What changes | What stays the same |
|---|---|---|
| Cloud-hosted | CopilotKit runs the platform, database, web app, project API keys, and plan management. | Your frontend APIs, runtime APIs, AG-UI agent connection, and thread APIs. |
| Self-hosted | You run the platform in your own Kubernetes cluster and own its infrastructure dependencies. | Your frontend APIs, runtime APIs, AG-UI agent connection, and thread APIs. |
Self-hosted changes who operates the platform. The frontend integration stays the same. Moving from cloud-hosted to self-hosted is available on the Team Self-hosted plan or the Enterprise plan. See Plans.
Error handling model#
Platform-backed features are networked features. If the platform endpoint is unavailable or credentials are invalid, thread operations surface as runtime errors rather than silently falling back to local-only state.
Common debugging checks:
- Confirm the runtime is using the right platform URL for the selected deployment.
- Confirm the runtime API key or license is valid for the project or self-hosted environment.
- Confirm the user and project context you pass from the app match the thread history you expect to see.
- Confirm realtime sync is configured when you expect cross-tab or cross-device updates.
Next steps#
- Overview lists each feature on its own page.
- Cloud-hosted creates the project and the API key.
- Self-host on Kubernetes installs the platform in your cluster.
- How a thread is saved covers replay and sync.