pistra documentation

pistra is the AI enforcement layer. Every model, tool and agent call is checked against your policy in line. Every decision leaves a signed record you can prove to anyone.

Run it

One provider, no config file:

$ pistra -listen :8484 -upstream https://api.openai.com

Two tutorials, each building a working configuration from nothing. The first puts pistra in front of a provider as the listener. The second runs it as an inspector behind a gateway you already have.

Govern your first provider: a virtual key, a budget, a CEL rule and a guardrail, end to end
Guard traffic you don’t route: put pistra behind an Envoy you already have, and stop a credit card reaching a backend. No routing, no keys, no migration

Evaluating it

If you are evaluating pistra rather than deploying it, read Silent degradation first: how a gateway can quietly do less than it claims, the seven places pistra guards against it, and the metric for each. Then the threat model for what is not claimed.

Choose your shape

One binary runs in three shapes. Which one you are building decides most of what follows, so settle it first. Architecture describes all three if none of them is an obvious fit.

The front door: pistra owns the listener. It terminates TLS, mints and checks virtual keys, holds the budgets, inspects content and routes to the provider.
Behind a gateway: The same process with the TLS and the listener left to the gateway you already run. Everything else is unchanged; there is no second binary.
Beside a gateway: Guardrails only, served over ext_proc to a gateway’s own listener. No provider, no credential, and no routing decision to make.

Deployment requirements

The rungs below are the second fork. Each rung adds a capability and costs something to operate, and a deployment takes them on in about this order. Deployment requirements covers each rung, and pistra check says which rungs a file is on.

rung	adds	requires	guides
Run	a listener in front of your traffic, the providers behind it, and a request passed through byte for byte	one process, a node file and a deployment document, one directory for its log	Govern your first provider, Deploy the front door with Helm, Run the front door on VMs, Add a custom provider, Add a provider with a catalog overlay, Schedule a pool with an endpoint picker, Watch the gateway
Govern	virtual keys, team profiles, budgets, CEL access rules, a signed audit trail, and a configuration you write through an API	nothing more than the node already runs, plus an admin door on it, either the local socket or a loopback listener	Mint, rotate and revoke a virtual key, Give a team its own policy, Cap what a team spends, Test your rules before they ship, Audit your metering against the provider, Query the gateway’s state, Suspend a key, provider or rule, Verify the audit trail, Ship the audit trail to your SIEM, Manage the configuration through the API, Manage the deployment with Terraform, Store a secret through the API
Inspect	PII, secret and identifier detection on the pattern tier, redaction and restore, guardrail rules over what was found	nothing more. and beside a gateway it needs that gateway’s ext_proc	Guard traffic you don’t route, Deploy guardrails beside your gateway, Redact PII from model output, Run a slow detector off the request path, Run a detector in shadow mode, Exempt placeholders from a credential rule, Add your own recognizer, Find Gulf identifiers, Start from a control pack, Write a control pack, Measure a detector
Identify	tokens from your identity provider on both planes, the agent and the user in every rule, admin roles from claims, sign-in from the command line, and a credential exchanged per caller at an MCP server or agent	an identity provider you administer, and a Cedar policy file for the admin plane	Connect your identity provider, Sign in from the command line, Restrict what an admin caller can do, Authenticate agents with your identity provider, Reach the admin API without your identity provider, Connect your AI governance platform
Replicate	several nodes holding one log, a control plane that survives a node, snapshots, and a cluster secret that rotates	three nodes in three failure domains, a shared secret, a volume each	Back up and restore the cluster, Recover a cluster that has lost quorum, Rotate the cluster secret, Spread a cluster across zones
Front peers	MCP servers and A2A agents behind the same keys, rules, budgets and guardrails, each agent’s card projected at the gateway’s address, and a private MCP registry	a public_url, for the cards and the resource metadata a client asks for	Front a peer agent, Serve a private MCP registry
Model detectors	names in any script, prompt injection, topics, and a model as judge	ONNX Runtime and the tokenizer shim on the node, or a remote analyzer, plus a cache directory for the models	Detect names with a model from the HuggingFace Hub, Stop prompt injection with a classifier, Keep the assistant on topic with examples, Judge with a model

Guides by topic

How it works

How pistra is built, and what it does not claim. Start with the architecture page for the overall shape, then read the page covering whichever design decision you need to understand.

Architecture: the three deployment shapes, the eleven steps a request takes, and the four planes of a deployment
Two configuration documents: the node file and the deployment document: what each holds, why they are two files, and how the second becomes a stored source with one writer
The guardrail pipeline: the guardrail pipeline end to end: segments, why a detector can only annotate, the two axes, and the three actions a rule may take
Threat model: the thirteen things it stops, the eleven it does not, and which claims hold only under which deployment shape
Threat model disclosure: the same claims arranged for a security review: four trust boundaries, the STRIDE map, what the deployment owns, and the four supply-chain artifacts
Deployment requirements: what each rung of capability adds, and what a node must run to reach it
What a cluster survives: what three replicas survive in each failure domain, and what a lost quorum stops
Silent degradation: how a gateway can quietly do less than it claims, the seven places pistra guards against it, and the metric for each
Authorization: the two authorization systems: a Cedar admin plane that denies by default, and a CEL data plane that allows by default
Inference pools: the two ways a self-hosted pool is reached, why a pool is declared rather than detected, and what the picker’s answer is checked against
Passthrough: why the bytes are not rebuilt
Metering: why the gateway never counts tokens itself, the three wire shapes it reads them from, and what a budget is denominated in
Channels and fidelity: why routing is per-capability rather than per-provider
Translation: the two dialect pairs that are carried, what each one drops, and why an available translator is not a reason to use one
The commit horizon: how a stream is inspected without being buffered
Schedules: sync, overlap and async, and what each one concedes
The audit trail: how the trail is chained and signed, and what a gap in it means
Releases and compatibility: what a tagged release contains, how to verify the build you are running, and what is promised about the next one

Deploy

Where the process runs and how much of the request path it owns. Choose the shape first: front door, behind a gateway, or beside one as an inspector. The substrate, Kubernetes or plain machines, matters less.

Deploying pistra: the two independent questions: how much of the request path pistra owns, and what it runs on
Deploy the front door with Helm: the StatefulSet behind a LoadBalancer, its own TLS, and the raft cluster the replicas form
Run the front door on VMs: three machines behind a load balancer, one raft cluster, no Kubernetes
Spread a cluster across zones: checking the voters landed in three zones, and when to make the spread a requirement
Deploy guardrails beside your gateway: the ext_proc inspector on Istio, Envoy Gateway, kgateway, agentgateway or GKE
Schedule a pool with an endpoint picker: self-hosted model servers, scheduled by llm-d or any endpoint picker

Providers and models

Reaching an endpoint that answers. Most need a name, a dialect and a URL. The remaining guides cover a catalog that is wrong about a model, and reconciling the token ledger against your bill.

Providers and models: three facts reach most endpoints; the catalog is a separate thing you touch only when pricing or capabilities are wrong
Add a custom provider: a name, a dialect and a URL; no preset, no overlay
Add a provider with a catalog overlay: correct or extend the built-in catalog at load time, without waiting for a release
Audit your metering against the provider: the second ledger, what a drift verdict means, and the metric to alert on

Detectors

What finds something in the content. Six types, cheapest first: patterns and checksums, a token classifier, a sequence classifier, an embedding model, an LLM judge, or a Presidio you already run. All of them only annotate, so choose on cost and evidence.

Detectors: the six types side by side with what each costs, then the guides arranged by what you are trying to catch
Stop prompt injection with a classifier: type: classify: Prompt Guard or ProtectAI’s DeBERTa from the Hub, on a CPU, in milliseconds; and when to reach for the judge instead
Keep the assistant on topic with examples: type: embed: an embedding model and your own example sentences per topic, in any language; scope, off-limits subjects, known jailbreak phrasings; why the threshold is read off a sweep
Judge with a model: type: llm: prompt injection, off-topic and content safety as a policy in prose, through a provider you already have; what it costs and how to pay less
Detect names with a model from the HuggingFace Hub: pistra models pin, a commit and the Hub’s own digests; gated repositories, mirrors, air-gapped
Add your own recognizer: an employee-id format or a codename list as a pii recognizer, and the vocabulary check that follows
Find Gulf identifiers: what is built in for Saudi Arabia, the UAE, Qatar, Kuwait, Bahrain and Oman, what it costs, and how to hold it to real identifiers
Measure a detector: pistra guardrails eval: labelled text through the gateway’s own inspection, scored at byte offsets; the Arabic NER and injection numbers, and why the clitic line reads 0.25

Guardrails

What happens once a detector has found something. Rules are CEL over the annotations. Three axes matter first: which side is inspected, when the detector runs, and whether it enforces yet.

Guardrails: the three axes people conflate: which side is inspected, when the detector runs, and whether it enforces at all
Redact PII from model output: response scanning is opt-in; the apply_to: [output] entry, and narrowing a rule to one side
Run a slow detector off the request path: schedule: overlap and schedule: async: a transformer on the path without the transformer’s milliseconds
Run a detector in shadow mode: mode: shadow, what it records, and the evidence to promote it on
Exempt placeholders from a credential rule: the two layers an exemption can live in, why the rule is the better one, and the allow-list entry that quietly suppresses real keys

Control packs

One reading of a regulatory regime, published as data: rules that cite the regime’s controls, a suite that proves what they decide, and a page naming what each pack leaves to you. A pack certifies nothing, and after pack add copies it in, the document is yours.

Control packs: whether you need a pack at all, which to add first, and what each one leaves to you
Control packs: every pack that ships, the controls each cites, and what a pack deliberately is not
The control pack format: the four files, every field of pack.yaml, and the checks a pack is held to before it merges
Write a control pack: a pack of your own: the namespace, declaring a control before a rule cites it, and building on one that ships
Start from a control pack: pistra pack add: one regime’s rules, each naming its article, copied into your document with the suite that proves them; never a mode
Saudi Personal Data Protection Law: the Saudi Personal Data Protection Law: the articles read, the redactions, and what the pack leaves to the controller
NDMO data classification: the NDMO classification and personal data regulations: the four levels on a key, and what marking documents still needs
SAMA Cyber Security Framework: SAMA’s cyber security framework: the cloud approval and location conditions held at the call
SDAIA AI ethics and generative AI guidelines: SDAIA’s AI instruments: what classification may reach a generative AI tool outside the entity

Keys, teams and budgets

What a client may do once it holds a credential. A virtual key is an identity, a profile is what that identity may do, and a budget is what the profile’s traffic draws from. Each is edited once for everyone holding it.

Keys, teams and budgets: the key, the profile and the budget, and which of the three your question is actually about
Mint, rotate and revoke a virtual key: the token shown once, the four different ways a key stops working, and why rotating one means minting a second name
Give a team its own policy: profiles, the two rule layers, and which detectors inspect a team
Authenticate agents with your identity provider: the token an agent already holds as its credential, bound to the data plane with its own audience, and rules over agent and user
Cap what a team spends: budgets: the window, the unit, and whether a team shares one allowance or every key gets its own
Test your rules before they ship: -test-rules: your CEL run against fixtures in CI, before a typo denies real traffic
Connect your AI governance platform: the platform writes the rules it wants enforced into one source it owns, each naming its controls, and reads back a signed record of every decision

Admin access

Who may change the deployment, as against who may use it. The caller is a person or a workload rather than a key, identity comes from a provider you already run, and the default is deny. This system is separate from the data plane.

Admin access: authenticated by your identity provider, then authorized by Cedar: two separate steps, neither using a shared secret
Connect your identity provider: one public client, two redirect URIs, and a group claim that becomes roles; workloads bring their own token and need none of it
Sign in from the command line: pistra login: PKCE, the device flow for headless hosts, and why there is still no admin secret
Restrict what an admin caller can do: roles, Cedar policy, and what the gateway refuses to start on

MCP and peer agents

Tool calls and agent-to-agent calls governed the same way model calls are. An MCP server is a provider whose arguments and results are segments. A peer agent is one whose message parts are. The same detectors and rules apply to both.

Front a peer agent: an A2A agent behind /a2a/: the 1.0 JSON-RPC binding, rules over peer and method, guardrails over message parts, and what the door refuses
Serve a private MCP registry: the official registry API over the servers you already govern, with Cedar deciding who publishes under each namespace

Configuration and secrets

Where the running configuration comes from once it stops being a file on disk. Named sources let an operator, a human and Terraform each own part of one document. Credentials are sealed into the raft log instead of written into it.

Configuration and secrets: named sources so several writers share one document, and why no credential is in it
Manage the configuration through the API: named sources, so an operator and a human never fight over one document
Manage the deployment with Terraform: three resources over the same source ownership, so Terraform is one writer among several rather than the only one
Store a secret through the API: ${secret:NAME}: a credential written once from the console, sealed into the raft log, never read back
Rotate the cluster secret: the keyring: add a wrapping, roll, drop; rotate the data key; move the key off the cluster secret

Operate the cluster

Day-two operation: what to scrape, what to alert on, how to verify the audit trail, how to restore state, and the two break-glass doors. Each recovery step is a command rather than a configuration edit.

Operating the cluster: the five day-two jobs in order, ending with the two break-glass doors
Watch the gateway: /metrics on its own listener or pushed as OTLP, the Grafana dashboard, what to alert on, and the OTEL_* switch for traces and logs
Query the gateway’s state: pistra query: one SQL statement over the list endpoints as tables, offered on each endpoint’s own grant
Verify the audit trail: pistra audit verify: what each finding means, and the witnessed heads that catch a trail cut at the end
Ship the audit trail to your SIEM: the pistra/audit scope, routing it away from operational logs, and verifying what the SIEM stored
Back up and restore the cluster: pistra snapshot save|restore: the whole replicated state as one checksummed archive, restored into whichever cluster receives it
Recover a cluster that has lost quorum: pistra cluster recover, offline and on a stopped node, and what dropping a member commits you to
Suspend a key, provider or rule: break-glass suspensions, and the lease each one runs on
Reach the admin API without your identity provider: the local admin socket, and how it differs from the network listener

Reference

Generated from the code and tested against it. No page here is written by hand, so an error on one of these pages points at the code it reads.

Configuration reference: every key, from the config structs
Command-line reference: every command the binary accepts, from the usage blocks it prints
Policy reference: every action a Cedar policy may name and every variable a CEL condition may read, asked of the engines that enforce them
Annotation reference: what a detector may say: the five namespaces, the eight segment kinds, the offset units and the recognition metadata
PII coverage: every kind of personal data the built-in recognizers detect, with checksum, fpe alphabet and streaming span, pinned to the Presidio release they came from
Credential coverage: every API key format the same detector finds, what carries each row, and what is deliberately absent
Metrics: every series on /metrics, with its type, labels and the help text it publishes
Audit trail reference: every event the trail records and every field a record carries, from the package that emits them
Performance: every published number, with the machine and the spread that produced it
Changelog: what changed that alters a configuration or a result, curated, newest first
Admin API: OpenAPI 3.1, from the handlers

Four kinds of document

The four kinds are kept apart on purpose. Mixing them is how a page ends up useless to everyone. A tutorial that stops to explain a design decision loses the reader who wanted it to work, and an explanation interrupted by setup steps loses the reader who wanted to understand.

Tutorials: learning by doing. Written to work as printed, with no choices to make and nothing to substitute.
How-to guides: getting something done. They assume you have run a gateway before and skip the explanation; each links to the explanation that goes with it.
Reference: the facts. Generated from the code and tested against it. Nothing here is edited by hand, so if a page is wrong, the fix belongs in the code it reads.
Explanation: why it works this way. The reasoning, the limits and the trade-offs: what is enforced, what is proved, and what is deliberately not claimed. If you are deciding whether to put this in front of your traffic, this is the tier to read.

section/ is the one directory that is not a kind. A page there is the front door to a topic, the fork to settle before picking a guide. It exists because that question is one people arrive at from a search engine rather than from this index.

Regenerate the reference pages with make generate (and make gen-perf-docs for the measured page, which wants an idle machine). make check fails when a committed page has drifted from its source, this index included. The index is generated from nav.yaml so that a new page cannot be missing from it.