Policy Configuration Overview

Policies are the rules that the gateway applies to model traffic. A policy can block an attempt to override the system prompt, replace a personal identifier before the model sees it, or send a response to a person for review.

You choose policies and their settings in a policy config, the policy-config.yaml file that the gateway loads. Add one rule, test it, then add the next.

Policy Controls CatalogEvery control with its phase, request families, and a minimal configuration.Config ReferenceEvery top-level section of policy-config.yaml and the fields in it.Test ConfigurationWrite cases that verdictan policy test runs before you deploy.

Run your first policy test

1. Open Prompt Injection Detection.
2. Copy its configuration and its two test cases into policy-config.yaml.
3. Run verdictan policy lint --file policy-config.yaml.
4. Run verdictan policy test --json. The attack example must be blocked and the usual question allowed.
5. Apply the tested file to a test agent with the config-first workflow.

The offline test does not call a model. A live request then proves that the gateway, the provider, and the policy work together.

What a policy config contains

Only pack and policies are required. Add other sections when you need them.

Section	Required	Use
pack	Yes	Name, version, and the enabled switch of the document
policies.chain	Yes	The ordered list of controls that the gateway runs
policy.<kind>	No	Settings for one control in the chain
providers	No	Provider targets, routing, fallback, and data policies
routes, consumer_groups	No	Path rules and client groups with their own chains and limits
token_rate_limit, global_rate_limit, ip_rate_limit, user_rate_limit, size_limits	No	Rate and size limits
cache, callbacks, history, testing	No	Caching, observability sinks, capture, and tests

Lint rejects a top-level key that the schema does not define. The Declarative Config Reference lists every section.

Chain and control

• The policy chain is the ordered list in policies.chain.
• A policy control is one entry in the chain, such as pii-detector. Its settings go in policy.<kind>.

An entry is either the name of a control, or an object with the name as its only key. The object form adds when, stage, parallel, and targeting:

policies:
  chain:
    - audit-logger
    - pii-detector:
        when:
          path: /v1/chat/completions
        stage: pre-request

Conditional Chain Configuration describes when and the stages.

Phases and verdicts

Controls run in one of two phases:

• The input phase (stage: pre-request) runs before the provider call. A control examines the request.
• The output phase (stage: pre-response) runs on the complete provider response, before your application receives it.

Each control has a default phase. For example, prompt-injection runs on input and quality-scorer runs on output. The Policy Controls Catalog lists the phase of each control.

Each control returns a verdict and a reason code:

Verdict	Next control	Result
allow	Runs	The gateway forwards the request or response.
redact	Runs	The gateway applies the supported replacements, then forwards. Some controls only report this verdict. Read the page of the control.
block	Does not run	The gateway returns a blocked result and the reason code.
escalate	Does not run	The gateway returns an escalated result and opens an escalation.

If one control in a phase returns block or escalate, that is the verdict of the phase. Otherwise, a redaction sets the verdict to redact. Examine the replacement details to see which text changed.

Ordering rules

• In one phase, controls run in the order of policies.chain.
• After a control returns block or escalate, the other controls of that phase do not run.
• audit-logger always returns allow. Put it before blocking controls if every evaluated request must have the audit marker.
• language-validator checks input text only. apply_to: output does not add output enforcement.
• pack.enabled: false turns off the whole document. The gateway registers no chain, routes, or providers from it.

Configure other parts

Task	Page
Define provider targets, routing, and fallback	Provider Configuration
Send traffic only to approved zero-retention targets	Zero-Retention Routing
Give paths and client groups their own rules	Routes and Consumer Groups
Limit request rate and size	Rate Limits
Send a review to a person	Escalation Routing
Validate a file from the command line	verdictan policy lint