Five components, and the boundaries between them.
NopsAI separates the system that holds the truth from the system that assigns work, the system that owns containers and the process that interprets a pipeline. The separation is what makes the blast radius of a run describable.
How a signal becomes a running container.
Everything inside the dashed boundary runs on your infrastructure. The only path out of a run is to the model providers and systems your pipeline names.
Two return paths are left off the diagram to keep it legible: the agent reports status, fetches workspace data, starts child runs and receives cancellation over gRPC to the dispatcher, and it posts approvals, declared outputs and AI usage to the API over authenticated HTTP. The API and git-bot also exchange repository and check calls in both directions.
Who is authoritative for what.
Most failure modes in distributed execution come from two components believing they own the same fact. These boundaries are drawn so that only one does.
Control plane owns the truth
The nopsai API holds pipeline definitions, run records, approvals, checkpoints, secrets and evidence in PostgreSQL. Nothing downstream is authoritative: a runner or an agent that disagrees with the control plane is wrong by construction.
AAA owns the decision
A separate authorization service resolves the caller and answers check, batch-check and filter questions over an internal-token-protected interface. Authorization is a call to a service, not a library the API can accidentally bypass.
Dispatcher owns assignment
The dispatcher accepts a job over gRPC and holds a bidirectional stream with each connected runner. It decides which runner takes a run. It does not interpret pipelines and does not hold customer data.
Runner owns the agent lifecycle
A runner creates, watches and tears down exactly one agent container or pod per run, plus the run's workspace volume. It does not read the pipeline. Runners can be remote, and more than one can serve the same control plane.
Agent owns pipeline semantics
The per-run agent resolves the DAG, evaluates conditions, calls models, enforces guardrails and creates step containers. It exists for the length of one run — or one segment of a run, if an approval interrupts it.
What crosses each hop.
Transport and direction matter to a security review, because they determine what has to be reachable from where.
Browser and CLI to the API
REST over HTTP. Every request resolves to a subject before it reaches a resource, and the effective subject is recorded on the run itself.
Git providers to the API
GitHub events arrive through git-bot, which validates them before forwarding a normalized event. GitLab, Bitbucket and Gitea post webhooks to the API directly.
API to dispatcher
gRPC job submission, one way. The dispatcher reports back to the API over authenticated HTTP callbacks rather than sharing its database.
Dispatcher to runner
A single long-lived bidirectional gRPC stream, opened by the runner. Runners dial out; the control plane does not need inbound network access to them.
Agent to control plane
Authenticated HTTP for approvals, checkpoints, declared outputs and AI usage accounting — and gRPC to the dispatcher for status, workspace fetch, child runs and cancellation.
Agent to providers
Provider HTTP APIs for models, and the Docker or Kubernetes API for step containers. These are the only two paths that leave the run.
What the agent can reach.
The two runtimes have genuinely different blast radii. Stating that plainly is more useful than a diagram that implies they are equivalent.
Kubernetes runner: the production model
The agent runs as a namespaced pod under a dedicated workload service account. The container drops all Linux capabilities, disables privilege escalation and runs under the runtime default seccomp profile. What the agent can create is bounded by that service account's RBAC — a real, reviewable boundary.
Docker runner: the single-node model
The Docker runner binds the host's Docker socket into the agent container, because that is how the agent creates step containers on a single host. This is the honest cost of the Docker path: an agent with the Docker socket can do anything the Docker daemon can do on that host. The runner host is the trust boundary, and it should be a host dedicated to running jobs.
Step containers in both models
Steps run in their own containers with new privileges disabled, a process limit, an init process and named-volume workspace mounts. They are not given the Docker socket. A step is the narrowest scope in the system.
The control plane does not take the socket
Container visibility for system logs goes through a dedicated socket proxy that accepts only GET requests for ping, version, container list, and inspect or logs on allow-listed platform containers. Mutations, events, stats and archive endpoints are rejected. The API container itself never mounts the socket.
The practical recommendation follows from the second point: run production workloads on the Kubernetes runner, and treat a Docker runner host as a dedicated job host rather than a shared server. See runtime and execution for placement, pools and affinity.
What never leaves your environment.
NopsAI is self-hosted, so this is a statement about where the components run, not a promise about how a vendor behaves with your data. Deployment planes are covered on integrations.
- Pipeline definitions, run records, task history and approvals stay in your PostgreSQL instance
- Workspace checkpoints, including the archived workspace itself, are stored by your control plane
- Secrets are stored encrypted and decrypted only by the control plane; a runner never sees them, and an agent receives resolved values for its own run
- Runners and agents run on your infrastructure and dial outward to your control plane
- The only outbound path from a run is to the model providers you configured and the systems your pipeline names