The shape of it
The three runtime layers and the logical data flow between them.
The control plane
The control plane is the boundary for everything durable. It owns:- The agent registry — which agents exist, which are online, and what each advertises.
- Run lifecycle — starting runs, tracking them, and streaming progress.
- How work starts — schedules, inbound endpoints, channel routing, chat, workflows, and modules.
- Evidence ingestion — the spans, logs, messages, artifacts, output, and token usage that arrive from agents during a run.
- Identity, authorization, and audit — who and what may act, and the record of what they did.
- Durable storage — it is the only component that talks to the database.
Agents and workers
An agent is the governed identity and behavior. A worker is the process that runs it, built with the Python or Go SDK. One worker runs one agent. A worker does two things continuously, independent of any run:- Registers and stays present. It reports in periodically; the first report registers the agent, and if reports stop, the agent shows as offline.
- Ships evidence. During a run it streams spans, logs, messages, output updates, and token usage back to the control plane in batches.
How work reaches an agent
Two transports, chosen by what the network allows rather than by the caller:- Outbound channel (most common)
- Direct call
The worker holds an outbound connection open to the control plane, and work is pushed down it.
Nothing needs to reach into the worker — which is what lets agents run behind NAT, inside a
private cluster, or with outbound-only egress.
The practical consequence: an agent needs outbound access to the control plane, and nothing
more. You do not have to expose an inbound endpoint to run agents in a private network.
What can start a run
See Run — how it works.
Workspace isolation
Every agent, run, integration, credential, and record belongs to exactly one workspace, and that boundary is enforced on every read and write. An agent in one workspace cannot see or reach another’s data. Agents themselves are governed principals: an agent’s permissions are checked at the moment it acts, not just when someone starts it. See Agent identity and Agent isolation & tenancy.Boundaries you can rely on
- Only the control plane talks to the database. Agents never need database access.
- The console talks only to the control plane.
- Agents need outbound access to the control plane; inbound access to an agent is optional.
- Secrets are delivered to a run in memory and never exposed to you or written to its evidence.
- When nothing is running, presence traffic is the only continuous agent-to-control-plane activity.
Next steps
Deployment methods
Which parts run on Komodor’s infrastructure and which run on yours.
Runs & evidence
What the evidence trail contains and how to read it.
Interfaces
Every surface that talks to the control plane.
Security overview
How access and actions are governed.