Mandrel Collet
The Mandrel Collet is the definitive enforcement proxy (sidecar) for autonomous AI agents. It “clamps” agents to their Mandrel Specifications by intercepting every turn to verify identity, governance thresholds, and operational limits.
This component serves as the official reference implementation for a Mandrel-compliant enforcement proxy. While this version is optimized for containerized sidecar deployment, the Mandrel ecosystem is designed for extensibility. Future implementations supporting alternative deployment modes (e.g., eBPF-based enforcement, cloud-native gateways, or language-specific interceptors) will be developed by The Mandrel Project and contributing partner organizations.
Key Features
- Zero-Trust Enforcement: Turn-level verification of Nested JWTs and SPIFFE identities.
- Circuit Breaking: Sub-millisecond failsafe behavior when governance boundaries are breached.
- Loop Prevention: Hard enforcement of hop limits and trace history.
- Polymorphic Governance: Native support for threshold and category-based enforcement matrices.
Installation
The Collet is primarily distributed as a Docker image for easy integration into containerized environments.
docker pull gitlab.com/the-mandrel-project/mandrel-collet:v1
Usage
The Collet runs as a sidecar alongside your agent. It loads a Mandrel Spec from disk, listens on a port, and forwards accepted traffic to the agent it is clamping.
collet --spec ./realized-spec.yaml \
--port 50052 \
--target localhost:50051
With an egress declaration, so the configured target is checked against the spec before the Collet serves anything:
collet --spec ./realized-spec.yaml \
--port 50052 \
--target localhost:50051 \
--target-spiffe-id spiffe://prod.example.internal/ns/ledger/sa/default
Flags
| Flag | Required | Description |
|---|---|---|
--spec | yes | Path to the Mandrel Spec YAML |
--port | yes | Port on which the Collet listens |
--target | yes | Address of the Specialist Agent being clamped |
--target-spiffe-id | when the spec declares egress-spiffe-targets | SPIFFE ID of the target, checked against the spec at startup |
Startup sequence
- Load the spec from
--spec. Fail if it cannot be parsed. - Check
--target-spiffe-idagainstspec.network.egress-spiffe-targets. A target outside the declared egress is a deployment contradicting its own governance, so the Collet refuses to start rather than discovering it per request. - Dial the target and begin serving.
If the spec declares egress targets and no --target-spiffe-id is supplied, startup fails.
Skipping the check would leave a required field unenforced, which is the state
egress-spiffe-targets was in before it was wired up.
The egress check is a configuration check, not a cryptographic one. Until the Collet dials downstream over mTLS, the target’s identity is asserted by the operator rather than proven by a certificate. It catches a misconfigured deployment, not a hostile one.
Enforcement layers
| Layer | Enforces |
|---|---|
| 0 | Intent verification posture (spec parsed; classifier call not yet implemented) |
| 1 | Loop prevention — max-hops-allowed |
| 2 | Identity — required-oidc-scopes |
| 3 | Network — ingress-spiffe-allow-list |
| 4 | Governance — enforcement-matrices |
| 5 | Fan-out — max-fan-out, per-turn concurrency |
| 6 | Delegation volume — max-delegations.per-turn |
| 7 | Timeout — timeout-seconds |
Layer 3 in detail
The presented workload identity is matched against ingress-spiffe-allow-list by whole path
segments. An entry for /ns/finance/* admits /ns/finance/sa/ledger and does not admit
/ns/finance-test/sa/ledger — a byte-wise prefix comparison would admit the second, so a
workload in a test namespace would satisfy a production rule.
There are three outcomes, and the third is deliberately distinct from the second:
| Outcome | Code | Meaning |
|---|---|---|
| Permitted | — | An entry matched |
| Denied | PermissionDenied | No entry matched |
| Unresolved | FailedPrecondition | The list still contains a path-only reference or a tag |
An unresolved reference means the spec was never realized: a metrology lab resolves those forms against the platform’s trust domain at promotion time. Reporting it as a denial would make a broken promotion pipeline indistinguishable from a legitimate refusal.
What the Collet does not do yet
Stated plainly, because a reference page that only lists capabilities reads as though the gaps are closed.
| Not implemented | Consequence |
|---|---|
| mTLS on either connection | The presented workload identity is taken from the request body, so it is self-asserted rather than verified. The egress target identity is likewise operator-asserted |
| Realized Spec signature verification at load | status.phase is trusted as presented |
| Nested JWT verification | required-oidc-scopes is matched against the token string rather than against verified claims |
| Intent classifier call | Layer 0 parses the posture and logs it |
These are tracked work, not oversights in the design. The identity architecture describes the intended end state.
Architecture & Performance
Engineered in Go, the Collet is designed for high-throughput and sub-millisecond latency. It acts as the “Layer 7” enforcement point in the Mandrel mesh, ensuring that every interaction between agents and enterprise systems remains within the defined risk envelope.
License
The Mandrel Collet is licensed under the Business Source License (BSL) 1.1. It is free for non-production use and for organizations with less than $5M in annual revenue.
Each major version converts to Apache 2.0 on an N-2 basis: a given major version becomes Apache 2.0 when the second subsequent major release ships. For example, v1.x converts when v3.x is released.
Source
The Collet source code is hosted on GitLab: gitlab.com/the-mandrel-project/mandrel-collet