Declarative Config Reference

This page describes the structure of policy-config.yaml: the top-level sections, the fields of pack and policies, and where to find the settings of each control. For your first file, start with the Policy Configuration Overview.

verdictan policy lint checks structure against the schema. The gateway and each control decide what happens at request time. A clean lint does not prove that credentials work or that a setting is enforced.

Syntax

The schema accepts two document shapes.

Config document

The shape for gateways, templates, and test suites. pack and policies are required.

policy-config.yaml

pack:
  name: demo-pack
  version: 1.0.0
  enabled: true
  description: Demo config

policies:
  chain:
    - audit-logger
    - pii-detector

policy:
  audit-logger: {}
  pii-detector:
    action: redact

Single-policy document

A standalone document for prompt-injection, agent-firewall, citation-verifier, or quality-scorer, without a pack. See Single-Policy Documents. Use a config document for a gateway or a test suite.

Fields

Top-level sections

A config document has these 30 top-level keys. Lint rejects any other key.

Section	Use	Guide
pack	Name, version, enabled switch, and tags of the document	Pack Metadata and Versions
policies	The ordered policy chain	This page
policy	One settings block for each control	Policy field reference
providers	Provider targets, routing, fallback, model groups, and pipelines	Provider Configuration
region	Operating region of the gateway	Cloud Provider Configuration
silent_engine	Privacy boundary that turns off optional telemetry and payload storage	silent_engine section
testing	Test suites for verdictan policy test	Test Configuration
assertion_packs	Named groups of quality assertions	Quality Assertion Configuration
routes	Path rules that select policy chains	Routes and Consumer Groups
consumer_groups	Client groups with their own limits and chains	Routes and Consumer Groups
cache	Exact or semantic response cache	Runtime Configuration
token_rate_limit	Sliding-window token limit for buffered Chat Completions	Rate Limit Configuration
global_rate_limit	Request limit for the whole gateway	Rate Limit Configuration
ip_rate_limit	Request limit for each client IP	Rate Limit Configuration
user_rate_limit	Request limit for each user header value	Rate Limit Configuration
distributed_rate_limit	Shared state for the global request limit	Rate Limit Configuration
size_limits	Byte limits for body, headers, URL, and response	Security and Network Configuration
ip_allowlist	Allowed source IP addresses	Security and Network Configuration
cors	CORS policy for gateway endpoints	Security and Network Configuration
callbacks	Observability sink definitions. The gateway parses them but does not send events to them.	Observability Configuration
health_monitor	Background health probes of provider endpoints. The runtime reads only providers[].name and providers[].endpoint.	Provider Control Features
auto	Virtual auto provider with cost and latency scoring	auto section
models	Behavior of the /v1/models endpoint	Runtime Configuration
moderation	External provider for /v1/moderations	Runtime Configuration
history	History capture settings	Runtime Configuration
review	Review executor controls for agent execution	Execution Targets and Runners
agents	Agent declarations for Context Fabric and MCP settings	agents section
context_fabric	Gateway-level Context Fabric defaults	Context Fabric Lifecycle
mcp_server	Gateway-level MCP server defaults	Gateway MCP Surface
tool_servers	Tool server declarations for governed MCP execution	Gateway MCP Surface

pack section

Field	Type	Default	Description
name	string, 1 to 200 characters		Name of the pack. Required.
version	SemVer string		Version of the pack. Required.
enabled	boolean		Master switch. Required.
id	string, 1 to 200 characters	The name value	Identifier for API references
author	string, up to 200 characters	""	Owner of the pack
description	string, up to 2000 characters	""	What the pack enforces
tags	map of string to string		Tags for the declaratively managed configuration

When enabled is false, the gateway loads nothing from the document: no chain, routes, providers, callbacks, or tests. It records pack.excluded evidence.

policies section

policies.chain is required and must have at least one entry. An entry is the name of a control, or an object whose only key is the name:

Field	Type	Default	Description
when	object	Always matches	Conditions on path, header, and model. Every condition that you set must match.
when.path	string		Prefix of the request path
when.header	map of string to string		Exact value of each named header. The value comparison ignores case.
when.model	array of string		The request model must be one of these values.
stage	pre-request, post-request, or pre-response	Default of the control	Phase in which the entry runs
parallel	boolean	false	Runs the entry in one batch with adjacent parallel entries
targeting	object		Limits the entry to teams or gateways

The schema and policy lint also accept stage: post-response, but the gateway rejects it when it loads the file. verdictan config validate and verdictan gateway check report the error:

Error: invalid chain entry: stage 'post-response' is no longer supported in chain entry 'pii-detector'. Use 'pre-response' for blocking/mutation controls and API-owned events for durable side effects.

How the chain runs:

• Entries run in chain order within a stage.
• A block or escalate verdict stops the later entries of that stage.
• A control in chain without a policy.<kind> block runs with its defaults.
• A policy.<kind> block without a chain entry passes lint but does not run.

Conditional Chain Configuration describes conditions, stages, and targeting.

policy section

policy has one block for each control. The schema accepts the 39 controls in the policy field reference and rejects any other key.

providers section

Declare targets in providers.targets, then add routing, model groups, retries, or pipelines as you need them. Provider Configuration shows which fields the runtime uses and which only parse.

A data_policy on a target records terms that you got from the provider. It does not verify them. To filter targets by this metadata, add data-routing-policy to the chain.

agents section

agents declares agents for Context Fabric and MCP settings:

Field	Type	Description
id	string	Agent identifier. Required.
team	string	Slug of the owning team. Required.
context_fabric	object	Context Fabric overrides for this agent
mcp	object	MCP session settings for this agent

policy-config.yaml

pack:
  name: agent-declaration-example
  version: 1.0.0
  enabled: true
agents:
  - id: support-agent
    team: customer-success
policies:
  chain:
    - audit-logger
policy:
  audit-logger: {}

Lint rejects usage_constraints here. Agent usage constraints live in the control plane: use GET or POST /v1/agents/{id}/usage-constraints, and PUT or DELETE /v1/agents/{id}/usage-constraints/{constraint_id}.

auto section

Field	Type	Default	Description
enabled	boolean	false in the schema, true at runtime	Turns on the virtual provider. Set it explicitly.
name	string	"auto"	Model name that clients send to use automatic routing
description	string		Text in /v1/models
routing.cost_weight	number	0.5 at runtime	Weight of price in the score
routing.latency_weight	number	0.5 at runtime	Weight of latency in the score
routing.max_price_per_1m_tokens	number		Targets above this price are not eligible.

If the price limit excludes every target, the request fails with no_eligible_provider. Automatic routing pins the request to one target and does not try another provider after a failure.

silent_engine section

silent_engine stops optional telemetry and the storage of request and response payloads. Authentication, ABAC, expiry, request and budget counters, and rate limits stay active.

policy-config.yaml

silent_engine:
  enabled: true
  minimum_state_mode: standard
  disable_history: true
  disable_payload_logging: true

Field	Type	Description
enabled	boolean	Turns on the privacy mode. Required.
minimum_state_mode	standard or enforcement_only	Keeps the standard runtime state, or only the state that enforcement needs. Required.
disable_callbacks	boolean	Turns off callback side effects
disable_history	boolean	Turns off History storage of entries with payloads
disable_gateway_telemetry	boolean	Turns off the periodic gateway telemetry reports
disable_payload_logging	boolean	Turns off logs and telemetry that contain payloads
disable_citation_writeback	boolean	Turns off citation storage and other writeback from payloads

Examples

Lint the config

verdictan policy lint --file policy-config.yaml

A valid file exits with code 0. The command can also print information logs.

Start the gateway with a policy config

Apply the file to a registered test agent with the config-first workflow. Use the gateway runtime token from the setup of that agent, and keep provider credentials in the gateway environment.

A name in a startup command does not create an agent. The quickstart gives you the agent and its connection command.

Verify the active config

With admin permission, read the active configuration with verdictan gateway config, and compare its version and chain with your file. Then send a test request and find its decision in runtime events.

A loaded configuration proves that the gateway accepted the file. A test request proves that the rule ran.

Policy field reference

Each control has its own page with its fields, a copyable example, the expected results, and its limits.

Access, tools, and routing

Block	What it configures
agent-firewall	Tool access by authenticated role, and action and transaction limits
rbac	Required verified identity and role permissions. A header from the caller does not prove a role.
cjis-mode	Required verified identity, accepted proof, and MFA assurance
audit-logger	An allow-only audit marker. The block is empty: audit-logger: {}.
data-routing-policy	Target filtering by declared retention and data-use metadata
tool-validation	Checks of tool declarations and optional schemas in the request
tool-security	Checks of tool JSON by local matching or an external analysis provider
tool-budget	Declared request budgets. It does not meter spend or completed tool runs.
gdpr-compliance	A required, non-empty consent header. Your application validates the consent itself.

Privacy, safety, and content

Block	What it configures
prompt-injection	Prompt-injection patterns, decoding, and boundary checks
pii-detector	Personal-data patterns and redaction format
hipaa-phi-detector	Health-identifier matching
dlp-filter	Data-loss patterns and terms
document-analyzer	Checks of document content in the request
code-sanitizer	Code patterns to detect
content-extractor	URL recording and optional text fetch. Later controls do not examine the fetched text.
bot-detector	Client indicators. A header match does not prove a human.
dual-use-filter	Dual-use terms and the action for a match
embedding-detector	Sensitive reference categories. The default backend uses word overlap, not an embedding API.
entity-list-filter	Entity names that you maintain
external-moderation	A moderation provider and its failure behavior
itar-ear-filter	Export-control terms
safety-filter	Safety terms. A list that you supply replaces the default list.
student-privacy	Student identifiers and optional supplied age metadata
case-privacy	Case-number patterns
language-validator	Allowed input languages. Low-confidence text can pass.

Output and domain compliance

Block	What it configures
citation-verifier	Citation checks against supplied source context
quality-scorer	Output assertions, scores, and thresholds
human-oversight	Escalation of each response. The only action is escalate.
flagged-review	Review of each response by a different provider, or escalation
bias-monitor	The built-in HR bias pattern and its threshold
mnpi-filter	MNPI phrases to block in buffered output
financial-compliance	Financial phrases and disclaimers for buffered output
healthcare-compliance	Health phrases and disclaimers for buffered output
legal-privilege	Privilege markers to block in buffered output
upl-filter	Legal-service phrases to block, or an educational disclaimer
request-rewriter	Request text rules and system message changes
response-rewriter	Text rules for buffered output

Reporting only

Block	What it configures
eu-ai-act	A report of control coverage. Keep it out of policies.chain, where it blocks every request with policy.reporting_only.

Limits and failure behavior

• Lint rejects an unknown top-level key, an unknown control in chain or policy, and an unknown key in a policy.<kind> block.
• Lint rejects a config document without pack or policies, and an empty policies.chain.
• Lint rejects a single-policy document for any control other than the four supported ones.
• A YAML syntax error stops the run before schema validation.
• Lint does not catch every load error. Run verdictan config validate or verdictan gateway check too.
• Tags of a declarative resource come from pack.tags. Change them in the configuration, not in the Console.

Next steps

• Policy Controls Catalog: select controls by phase and purpose.
• Provider Configuration: declare targets, routing, and fallback.
• Test Configuration: add tests to the same file.
• Environment Variable Use: refer to secrets and environment values in the file.
• Escalation Routing Configuration: send escalated requests to a team queue or one user.
• Complete Configuration Scenarios: start from one verified config and add the checks that you need.