> ## Documentation Index
> Fetch the complete documentation index at: https://docs.komodor.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Control plane
> Understand the control plane's ownership of identity, routing, durable state, API surfaces, and worker evidence.
Identify what the control plane owns and how workers and clients communicate with it.
The control plane in the Komodor Agentic Operation Platform (KAOP) coordinates execution and
maintains the durable platform record. Workers
perform agent tasks; the control plane manages the identities, routing, state, and evidence around
those tasks.
This page maps those responsibilities to the interfaces you use when operating or integrating the
platform.
## What the control plane owns
| Area | Responsibility |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| **Agent registry** | Registered identities, advertised capabilities, worker heartbeat freshness, and derived online/offline status. |
| **Run lifecycle** | Invocation APIs, state tracking, and progress streaming. |
| **Work routing** | Scheduled triggers, inbound endpoints, Slack channels, chat, workflows, and mediated A2A or MCP invocation. |
| **Evidence ingestion** | Spans, logs, messages, artifacts, output updates, and usage sent by workers. |
| **Identity and authorization** | Authentication and the roles and grants that govern actions. |
| **Audit** | Records of governed changes, sensitive reads, and rejected attempts. |
| **Durable storage** | Persistent platform state in the database. |
The database boundary applies to **the platform's database**. Workers do not connect to it to
register themselves, retrieve jobs, or store evidence; they use the control-plane interfaces. This
does not prohibit an authorized agent from using an external database as part of its own task.
Durable platform state is also distinct from a worker's local source files, configuration, or
task-specific storage. Avoid treating every persistent file in an agent environment as
control-plane-owned state.
## How the console is served
The web console is a separately served static single-page application. Deployment ingress routes
API, authentication, gateway, and documentation paths to the control plane and other paths to the
console.
The browser communicates with the API without a console-server proxy hop. UI and backend releases
are decoupled: a backend release does not itself replace the console application.
This distinction matters when inspecting routing or streaming failures. Serving the console
successfully is not proof that the API or a long-lived stream is reachable.
## API and protocol surfaces
These paths share the workspace host:
| Surface | Path | Purpose |
| ----------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **REST** | `/api/v1/...` | Manage and inspect platform resources, including agents, workers, runs, endpoints, schedules, quality, and integrations. |
| **Chat** | `/api/v1/chat/...` | Sessions, messages, and streamed responses. |
| **A2A** | `/a2a/{agent_id}/...` | Control-plane-mediated agent invocation, message send/stream, and task polling. |
| **Platform MCP server** | `/internal/mcp` | Expose platform inspection and invocation tools to MCP clients. |
| **MCP Gateway** | `/gateway/mcp` | Proxy access to configured upstream MCP tools. |
| **Authentication** | `/auth/...` | Sign-in and session endpoints. |
| **Interactive API reference** | `/api/docs` | Inspect endpoint-specific request and response contracts. |
**Internal names the server, not a bypass** Despite its name, `/internal/mcp` is the supported
endpoint for external MCP-capable clients. It names the platform's own MCP server; it is not an
unauthenticated internal-network bypass.
The platform MCP server and MCP Gateway have opposite roles: one lets a client operate KAOP, while
the other lets an agent use upstream tools. See Interfaces for their connection and authorization
boundaries.
## Worker registration and presence
A worker advertises the agent it hosts and authenticates with an agent-bound worker token. In the
documented Python runtime, the worker sends heartbeats approximately every 10 seconds to:
```text theme={null}
PUT /api/v1/workers/{worker_id}/heartbeat
```
The first heartbeat registers the agent. Subsequent heartbeats carry its manifest and let the
control plane derive presence from freshness. A draft created in the Add agent wizard becomes live
on its worker's first heartbeat.
**Disabled is not revoked** Disabling an agent stops automated triggers but still permits manual
and chat execution, and a later heartbeat does not re-enable it. Worker-token rotation immediately
invalidates the old token, and revocation cuts off the worker's authenticated access. Use token
controls when that identity must stop connecting, rather than relying on heartbeat status alone.
## Dispatch and evidence use separate paths
| Communication | Documented endpoint or behavior |
| -------------------------- | -------------------------------------------------------------------------------------------------- |
| Client invokes an agent | `POST /api/v1/agents/{agent_id}/invoke`. |
| Reverse invocation channel | Worker holds `GET /api/v1/workers/{worker_id}/channel` open over SSE. |
| Direct invocation | Control plane sends an A2A JSON-RPC request to the registered worker endpoint. |
| Worker event uplink | `POST /api/v1/workers/{worker_id}/frames`, including batched `run_events` frames during execution. |
The agent invoke API prefers a live reverse channel and falls back to direct worker dispatch. A
private worker can therefore receive work over an outbound connection without opening an inbound
path.
During a run, evidence and lifecycle events return from the worker to the control plane.
Registration traffic tells you the worker is present; run-event traffic tells you what it reported
while executing.
When idle, the architecture reference identifies heartbeats and the idle reverse channel, where
used, as the continuous platform communication. Run evidence is generated during execution rather
than being reconstructed by rereading the worker afterward.
## Identity, authorization, and audit
Authentication establishes the caller; authorization decides what that caller may do.
* **Browser:** SSO establishes a signed, short-lived session.
* **Script or integration:** a bearer API key acts as its associated person or service account.
* **Worker:** a worker token establishes the agent identity and account. A caller-supplied identity
header does not override the token.
When authentication is enabled, unauthenticated API, A2A, MCP, and worker requests receive a JSON
`401`. A valid identity can still receive `403` when it lacks permission for an action.
Every request is scoped to one account. Internal MCP tools are checked against the same capability
as their HTTP equivalents; choosing another protocol does not grant another role.
The audit trail is separate from the run trace. The security reference describes an append-only
record of governed mutations and selected sensitive reads, including actor, time, action, and
outcome. It also records rejected attempts. Audit entries for changes are written in the same
transaction as the change.
## Diagnose the boundary that failed
| Symptom | Inspection path |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Console loads, but API operations fail | Check the API response and deployment routing; console availability alone does not verify backend access. |
| Worker is offline | Inspect heartbeat delivery and the worker token's status. |
| Worker is present, but an invocation cannot reach it | Check its live reverse channel or direct endpoint reachability. |
| Run exists, but evidence is missing | Inspect execution and the worker event uplink separately from heartbeat traffic. |
| Request returns `401` | Check missing, invalid, revoked, or rotated authentication credentials. |
| Request returns `403` | Inspect the authenticated identity, roles, and grants. |
These checks locate the communication or authorization boundary; they do not substitute for
inspecting the worker's own execution error.
## Next steps
See exactly what a job and its telemetry can contain
Choose a supported client path
Review worker identity and lifecycle
Manage principals, roles, and tokens
## Related topics
- [Self-hosted control plane](/get-started/on-prem/overview.md)
- [Architecture](/get-started/architecture.md)
- [Deployment methods](/get-started/deployment-methods.md)
- [Network & egress control](/security-and-governance/architecture-considerations/network-egress-control.md)
- [Data flow](/get-started/architecture/data-flow.md)