Architecture Overview
Why local-first, compiled enforcement
The foundational architecture decision is that the workstation agent is the decision engine, and the control plane is a policy distributor and audit sink.
Three alternatives were considered and rejected before settling on this model:
| Alternative | Why it was rejected |
|---|---|
| Server-side decisioning (agent asks a central server "allow or block?" per event) | Introduces a network round-trip into the enforcement hot path, weakens fail-closed guarantees under network partition, and makes latency and availability a function of the control plane's uptime rather than the workstation's. |
| Thin local wrapper + heavy cloud logic (agent only forwards data, all detection happens server-side) | Violates the on-premise trust boundary the product exists to provide, and makes "zero-knowledge" impossible by construction — the data would have to leave the workstation to be evaluated. |
| Full cloud SaaS control plane | Incompatible with air-gapped and regulated on-prem deployment as a first-class mode, not a degraded fallback. |
The accepted model: the workstation agent evaluates every decision against a locally cached, signed policy snapshot. The control plane's role is to author, sign, and distribute that snapshot, and to receive a redacted audit trail after the fact. This is recorded as the project's first architecture decision and is treated as effectively immutable — changing it requires a new ADR.
Trust boundary
%%{init: {"theme": "base", "themeVariables": {"fontFamily": "-apple-system, Segoe UI, Helvetica, Arial, sans-serif", "primaryColor": "#eef2f7", "primaryTextColor": "#0b0b0b", "primaryBorderColor": "#5b6b7c", "lineColor": "#5b6b7c", "secondaryColor": "#eef4ff", "tertiaryColor": "#f4f3f0", "clusterBkg": "#f9f9f7", "clusterBorder": "#c3c2b7", "edgeLabelBackground": "#fcfcfb", "actorBkg": "#eef2f7", "actorBorder": "#5b6b7c", "actorTextColor": "#0b0b0b", "actorLineColor": "#5b6b7c", "signalColor": "#52514e", "signalTextColor": "#0b0b0b", "labelBoxBkgColor": "#eef4ff", "labelBoxBorderColor": "#5b6b7c", "labelTextColor": "#0b0b0b", "loopTextColor": "#0b0b0b", "noteBkgColor": "#fdf3d9", "noteBorderColor": "#c98500", "noteTextColor": "#3d2f00", "activationBorderColor": "#5b6b7c", "activationBkgColor": "#eef4ff", "sequenceNumberColor": "#ffffff"}}}%%
flowchart TB
subgraph Workstation["Developer Workstation — trust boundary A"]
direction TB
Shell["Shell interception<br/>(PTY: bash/zsh, PowerShell, cmd.exe)"]
MCP["MCP JSON-RPC proxy"]
Clip["Clipboard monitor"]
Repo["Local repo scanner"]
Kernel["Kernel-level file mediation<br/>(fanotify / Endpoint Security)"]
Detect["Detection engine<br/>(regex + entropy + checksum + NER)"]
Mask["Streaming masking engine"]
Policy["Policy engine<br/>(signed snapshot, fail-closed)"]
Shell --> Detect
MCP --> Detect
Clip --> Detect
Repo --> Detect
Kernel --> Policy
Detect --> Mask
Policy --> Shell
Policy --> MCP
Policy --> Clip
end
subgraph ControlPlane["On-Prem Control Plane — trust boundary B"]
direction TB
PolicyAPI["Policy authoring & signing"]
EventAPI["Event & heartbeat ingest"]
AdminUI["Admin UI"]
PG[("PostgreSQL")]
IdP["OIDC / Keycloak-compatible"]
PolicyAPI --> PG
EventAPI --> PG
AdminUI --> PolicyAPI
AdminUI --> EventAPI
AdminUI --> IdP
end
Policy -. "pulls signed snapshot" .-> PolicyAPI
Mask -. "redacted events only\n(hashes, counts, classifications)" .-> EventAPI
The decision is made and applied inside trust boundary A. Nothing inside boundary B can force an outcome on the workstation faster than the next signed-policy pull, and nothing that crosses from A to B carries raw sensitive content — see Zero-Knowledge Telemetry for the exact sanitization guarantee.
Continue to Kernel-Level Enforcement.