Architecture decision records

ADRs document why we chose a particular design. They’re living documents — when a decision is revisited, we write a new ADR that supersedes the old one rather than editing history.

Source: docs/adr/ in the repo.

#	Title	Status
001	Policy engine	Accepted
002	gRPC event schema	Accepted
003	Agent identity	Accepted
004	Kernel enforcement model	Accepted
005	Multi-env control plane	Accepted
006	TLS interception	Accepted

Summaries

001 — Policy engine

Chose Cedar over OPA/Rego. Cedar has formal semantics, fast evaluation, and a simpler mental model for the access-control use case. We author in YAML for operator ergonomics and compile to Cedar + BPF maps.

002 — gRPC event schema

Chose gRPC bidirectional streaming over WebSockets or NATS. Bidi lets the server push policies back. Protobuf gives us forward/backward compat. mTLS gives us agent authentication for free.

003 — Agent identity

Server runs an internal CA. Agents generate a keypair, request a CSR, server signs. This avoids dependency on external PKI and keeps bootstrap simple (one enrollment token, no manual cert plumbing).

004 — Kernel enforcement model

eBPF + LSM hooks over ptrace, LD_PRELOAD, or user-mode firewalls. LSM BPF is universal (works on Ubuntu 22.04+, RHEL 9, modern kernels) and non-bypassable from userspace. Tracepoints fill in where LSM doesn’t reach.

005 — Multi-env control plane

One server, many agents. Agents are identical across laptops, bare-metal, VMs, containers. Kubernetes support is a thin layer on top (DaemonSet + CRDs) rather than a separate control plane.

006 — TLS interception

SNI extraction only, no decryption. We hook OpenSSL/rustls uprobes to read the hostname from the ClientHello. This gives us LLM-provider tagging without any MITM attack surface, and respects the user’s privacy.

Proposing a new ADR

Create docs/adr/NNN-short-title.md with the standard template (Context / Decision / Consequences).
Set Status: Proposed.
Open a PR for discussion.
On merge, flip to Status: Accepted.

Template:

# NNN — Title

- **Date**: YYYY-MM-DD
- **Status**: Proposed | Accepted | Superseded by NNN

## Context

What's the problem or question?

## Decision

What did we decide and why?

## Consequences

Good and bad effects; what we're giving up.

## Alternatives considered

Briefly.

→ Next: Releases