Get started

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, no migration:

$ 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 providerPut pistra in front of an LLM provider and give it a virtual key, a token budget, a CEL access rule and a PII guardrail, end to end.

Guard traffic you don't routeRun pistra as an ext_proc inspector behind an Envoy you already have, and stop a credit card reaching the backend. No routing, no keys.

Evaluating it

Read Silent degradation first if you are deciding whether this belongs in front of your traffic. It covers the failure mode worth checking any gateway for, quietly doing less than it claims, the seven places pistra is built against it, and the metric that verifies each one. The threat model says what is not claimed.

Choose your shape

One binary, three shapes. Which one you are building decides which of the pages below apply to you. Architecture draws all three if none of them is obviously you.

The front doorpistra owns the listener. It terminates TLS, mints and checks virtual keys, holds the budgets, inspects content and routes to the provider.

Behind a gatewayThe 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 gatewayGuardrails only, served over ext_proc to a gateway's own listener. No provider, no credential, and no routing decision to make.

Deployment requirements

The second fork. Each rung adds something and costs something to operate, and a deployment takes them on in about this order. Nothing on a higher rung is required by a lower one. Deployment requirements is the argument behind the order, and pistra check says which rungs a given file is on.

Run

a listener in front of your traffic, the providers behind it, and a request passed through byte for byte.

Requires: 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.

Requires: 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.

Requires: 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.

Requires: 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.

Requires: 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.

Requires: 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.

Requires: 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

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.

Overview · Deploy the front door with Helm · Run the front door on VMs · Spread a cluster across zones · Deploy guardrails beside your gateway · Schedule a pool with an 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.

Overview · Add a custom provider · Add a provider with a catalog overlay · Audit your metering against the provider

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.

Overview · Stop prompt injection with a classifier · Keep the assistant on topic with examples · Judge with a model · Detect names with a model from the HuggingFace Hub · Add your own recognizer · Find Gulf identifiers · Measure a detector

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.

Overview · 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

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.

Overview · Control packs · The control pack format · Write a control pack · Start from a control pack · Saudi Personal Data Protection Law · NDMO data classification · SAMA Cyber Security Framework · SDAIA AI ethics and generative AI guidelines

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.

Overview · Mint, rotate and revoke a virtual key · Give a team its own policy · Authenticate agents with your identity provider · Cap what a team spends · Test your rules before they ship · Connect your AI governance platform

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.

Overview · Connect your identity provider · Sign in from the command line · Restrict what an admin caller can do

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 · Serve a private MCP registry

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.

Overview · Manage the configuration through the API · Manage the deployment with Terraform · Store a secret through the API · Rotate 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.

Overview · Watch the gateway · Query the gateway's state · Verify the audit trail · Ship the audit trail to your SIEM · Back up and restore the cluster · Recover a cluster that has lost quorum · Suspend a key, provider or rule · Reach the admin API without your identity provider

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.

ArchitectureThe map the other pages sit on: the three deployment shapes, the eleven steps a request takes, and the four planes of a deployment.

Two configuration documentsWhy a node runs from two documents: the node file that configures one process and the deployment document the cluster stores, and the one-writer rule that follows.

The guardrail pipelineHow guardrails work end to end: segments, six detector types that only annotate, schedule against mode, and the CEL rules that decide.

Threat modelWhat pistra defends against, what it explicitly does not, and which claims hold only under which deployment shape.

Threat model disclosureThe threat model arranged for a vendor security review: trust boundaries, a STRIDE map, residual risk, and what each published artifact covers.

Deployment requirementsWhat each pistra capability adds and what a node must run for it, rung by rung: from one process and a file to three nodes, an identity provider and model libraries.

What a cluster survivesWhat a pistra cluster survives node by node, zone by zone and region by region, and what stops when it loses quorum.

Silent degradationHow a gateway quietly does less than it claims, the seven places pistra is built against that, and the metric that verifies each one.

AuthorizationThe two authorization systems in pistra: a Cedar admin plane that denies by default, a CEL data plane that allows by default, and why both.

Inference poolsHow pistra reaches self-hosted model servers: fronted by an inference gateway or asking the endpoint picker itself, and why a pool is declared rather than detected.

PassthroughWhy pistra forwards the request body byte for byte instead of rebuilding it, and what that buys when a provider adds a field.

MeteringWhy pistra never counts tokens itself, the three wire shapes it reads provider counts from, and what a budget is denominated in.

Channels and fidelityWhy routing is per (provider, model, dialect, capability) rather than per provider, and why a channel that would drop one is refused.

TranslationThe two dialect pairs pistra carries, exactly what each one drops, and why having a translator available is not a reason to use it.

The commit horizonHow a streamed response is inspected for policy violations without being buffered, and how far the horizon actually reaches.

SchedulesWhy mode and schedule are separate axes, and what sync, overlap and async each concede in exchange for what they give.

The audit trailWhy the audit trail is a separate signal from the log: a hash chain per node, signed, verifiable without trusting the node that wrote it.

Releases and compatibilityWhat a pistra release contains, how to verify the build you are running against its digest, and what is promised about the next one.

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 referenceEvery key of the pistra configuration file, in the order the file is read, generated from the config structs and tested against them.

Command-line referenceEvery command pistra accepts and every flag it takes, generated from the usage blocks and flag declarations in the binary itself.

Policy referenceEvery name a pistra policy may use: the Cedar admin actions by resource class, and the variables each CEL condition scope declares.

Annotation referenceThe annotation schema every pistra detector produces: namespaces, segment kinds, offset units, metadata keys and the built-in vocabulary.

PII coverageEvery kind of personal data the built-in recognizers detect, with checksum, FPE alphabet and streaming span, pinned to its Presidio release.

Credential coverageEvery API key, token and private-key format pistra detects by default, the prefix that carries each one, and the formats left out.

MetricsEvery metric pistra exports, with its type, labels, buckets and help text, generated from the Prometheus registry a scrape serves.

Audit trail referenceEvery event the pistra audit trail records, every field of the signed record, and the OTLP attributes a collector can filter on.

PerformanceEvery published pistra number, with the machine, the method and the spread that produced it.

These are filed under four kinds of document: tutorial, how-to, reference and explanation. The overview says what each kind is for and why they are kept apart.