Control Plane Architecture¶

The Runtime is the data plane. The Control Plane is optional governance above it.

This page is the architectural model for how a company Control Plane sits above Engineering Runtime binaries. Operator surfaces and editions live under the Control Plane tab.

Data plane and control plane¶

     Humans · AI Agents · CI/CD

              │

              ▼

     Engineering Runtime                 ← Data Plane
     (authenticate, context, policy,
      execute, audit — all local)

              │  optional HTTPS
              │  (client off by default)

              ▼

     Control Plane API                   ← Governance Plane
     (publish policy, ingest audit,
      fleet presence)

              │

              ▼

     Demo UI · Enterprise UI             ← Operator views only

Plane	Owns	Does not
Data plane (Runtime)	Execution, local policy evaluation, local audit	Depend on the Control Plane to run
Control plane (API + UIs)	Shared policy, fleet view, central audit	Execute engineering operations

The Data Plane executes. The Control Plane observes and distributes.

One shared API, two surfaces¶

There is a single Control Plane API with two path prefixes and the same Runtime-facing route shapes:

Surface	Prefix	Audience
Public / Community	`/api/public`	Demo Live mode, Community Runtime uplink
Enterprise	`/api/v1`	App SaaS, enterprise Runtime uplink

portal.  (Live Demo)  ──►  /api/public/*  ──┐
                                            ├──  api.  (shared API)
app.     (Enterprise) ──►  /api/v1/*      ──┘

Hostnames today:

Host	Role
`api.engineeringruntime.com`	Shared Control Plane API
`portal.engineeringruntime.com`	Demo UI (Static fixtures or Live Demo)
`app.engineeringruntime.com`	Enterprise SaaS UI

UIs never become a second API. Both talk to api.; the Runtime client points portal.base_url at the API origin, not at a UI hostname.

What crosses the network¶

When the Runtime Control Plane client is enabled, exactly three calls happen under the configured path_prefix:

Direction	Call	When
Runtime → API	`POST …/audit`	After every local audit write (best-effort)
Runtime ← API	`GET …/policies?active=true`	On `runtime portal sync` only
Runtime → API	`POST …/fleet/heartbeat`	Once per process

Nothing else is required for governance to work locally.

publish policy (central)
        │
        ▼
runtime portal sync          ← explicit pull
        │
        ▼
policy-config.yaml (cache)
        │
        ▼
every command evaluates locally

command runs
        │
        ▼
local audit write            ← authoritative
        │
        ▼
optional uplink              ← best-effort, never blocks

Invariants (do not break these)¶

Invariant	Meaning
No second execution path	Capabilities and engines never target the Control Plane
Local evaluation	A Control Plane outage cannot widen, narrow, or block a command
Local audit first	Uplink failure must not turn success into failure
Explicit sync	Bootstrap and ordinary commands do not pull policy implicitly
Optional	Community / laptop use never requires a Control Plane

The Runtime keeps working when the Control Plane does not.

Where to go next¶

You want	Go to
Operator view (Static / Live Demo, enterprise app)	Take Me to the Portal
Community vs Enterprise editions	Community and Enterprise
Why a company needs this layer	Why Enterprises Need a Control Plane
Client config (`path_prefix`, env, sync)	docs — Control Plane (Portal)

Design Principle¶

Policy is distributed centrally. Policy is enforced locally.

Central governance must never become a runtime dependency.