Configurations

Manage configuration in a file

A gateway reads its providers, routes, and rules from one YAML file, policy-config.yaml. When you keep that file in Git, you can review each change, test it before deployment, and go back to a known good version.

This page changes the configuration of a gateway that you set up in the quickstart. It does not create an agent or a gateway.

Get a configuration

If your agent already has a configuration, open it in Configurations in the Console. Copy its YAML into policy-config.yaml.

To start from nothing, run verdictan init in an empty directory:

verdictan init

The command writes a starter pack with one control and one test:

policy-config.yaml
tests/
└── blocks_obvious_injection.json

policy-config.yaml

pack:
    name: my-policy
    version: 0.1.0
    enabled: true
    description: "Verdictan policy configuration"

policies:
    chain:
        - prompt-injection

policy:
    # Defaults apply; override fields here if desired.
    prompt-injection: {}

Add a provider target and the rules that you need. Provider Configuration shows the target fields, and the Policy Controls Catalog lists each control.

Refer to a provider key by the name of its environment variable. Do not put the key value in the file:

Inside a provider target

secret_key_ref:
  env: OPENAI_API_KEY

The gateway reads OPENAI_API_KEY from the terminal or container that runs it.

The file controls gateway behavior only. Members, API tokens, and budgets stay in their Console pages or in control manifests. These settings can also allow or stop a request, and the file does not replace them.

Lint and test the file

Run these commands in the directory that contains policy-config.yaml:

verdictan policy lint --file policy-config.yaml
verdictan policy test --json

Lint checks the structure of the file and its references. policy test runs each JSON case in tests/ and each suite in the testing section of the file. Correct each failure before you continue.

For each rule that you change, add one case that the rule allows and one case that it blocks. Test Configuration describes the case format.

These checks do not call a model. They do not prove that provider credentials, model access, or network connections work. A live request proves those.

Try the change on a test gateway

Use a test agent and its gateway. A deployment goes to every gateway of the selected agent. Make sure that the test agent serves no other traffic.

Before you deploy, increase pack.version in the file. The gateway logs this value when it loads the configuration, so you can see which version it runs.

Stop the gateway. Set the provider variable in the same terminal. Start the gateway again with its previous command. Keep the same agent, runtime registration, API URL, and gateway token. The gateway reads provider credentials from its own environment.
In the Console, open Configurations. Then open the editor:
- For a new configuration, select Create Configuration.
- To change a saved configuration, open the configuration that the test agent uses. Then select Edit.
Paste the complete YAML into the editor. To use a file instead, select Import Configuration. Then select the file. Select Next.
In Deploy to agent, select the test agent. The review summary shows how many gateways receive the configuration.
Select Deploy. Examine the Deployment approval dialog. Then select Deploy to 1 gateway.
Watch the gateway terminal. The gateway checks for configuration about every 30 seconds. When it applies the configuration, it logs connected read model refresh applied updated config. Check the new config_version. Record the config_sha256.

Do not use verdictan gateway run --policy-config for this step. The current control-plane API does not serve the routes that this command calls. The gateway does not start. See verdictan gateway run.

With CLI 0.1.14 or later, you can also deploy the file from your terminal.

After either procedure, check the configuration sync status in Gateways. Then send the test requests below.

If you use the quickstart in Docker, do the same Console steps. The container downloads its configuration from Verdictan and does not read a local file. To see the log line, run docker compose logs -f gateway.

Use the quickstart in Docker with a different provider

A variable that you export on your computer does not go into the container automatically.

In compose.yaml, find services.gateway.environment. Replace the VERDICTAN_OPENAI_API_KEY entry with the variable that your provider guide names. For example, a Groq target uses:
Inside services.gateway.environment
```
VERDICTAN_GROQ_API_KEY: ${VERDICTAN_GROQ_API_KEY:?Set your Groq API key}
```

Set that variable in the terminal where you run Docker Compose, and create the gateway container again:

export VERDICTAN_GROQ_API_KEY="replace-with-your-groq-key"
docker compose config --quiet
docker compose up -d --force-recreate gateway

Deploy the complete policy-config.yaml from the provider guide to the same test agent. Use steps 2 to 5 of the procedure above.
Run docker compose logs -f gateway. Wait for connected read model refresh applied updated config with your pack.version.
Send the test request from the provider guide. Its model must match the deployed target.

Keep one environment entry for each credential that the active configuration uses. Remove the OpenAI entry only when no target uses it.

To lint the file without a CLI installation on your computer, run the image:

docker run --rm \
  -v "$PWD/policy-config.yaml:/work/policy-config.yaml:ro" \
  verdictan/verdictan:0.1.14 policy lint --file /work/policy-config.yaml

Send two requests through the agent URL with the application token that you used before:

A usual request. It must return a model response.
A request that matches the new rule. It must return the decision that the rule specifies.

Find both requests in History, or read the delivered events from a terminal:

verdictan events tail --since 10m --json

events tail uses your signed-in CLI profile. It does not use the gateway token or the application token. See API token management for the job of each token.

Deploy the tested version

Open Configurations. For a new configuration, select Create Configuration. To change a saved configuration, open the configuration of the target agent. Then select Edit.
Import the file that passed the tests. Select Next.
In Deploy to agent, select the target agent.
Examine the changes and the number of gateways that receive them.
Select Deploy. Then confirm in the Deployment approval dialog.
In the log of each gateway, wait for connected read model refresh applied updated config with the new config_version. Each gateway loads the configuration on its next pull, within 30 seconds.
Send a test request through each gateway. Examine its decision.

Configurations describes these controls and how to roll back a version.

Deploy from the CLI

Use CLI 0.1.14 or later. Sign in with an account that can deploy to the agent. Use a separate terminal from the gateway process. The CLI needs your account credential, not the gateway runtime token.

Copy the test gateway ID from Gateways.

Set the ID in your CLI terminal:

export GATEWAY_ID="replace-with-test-gateway-id"

Deploy the file that passed your local tests:

verdictan policy push \
  --file policy-config.yaml \
  --gateway-id "$GATEWAY_ID" \
  --change-detail "Deploy tested configuration"

The command saves a configuration version and updates the deployment of the linked agent. This command assigns the version to the selected gateway. Other gateways keep their assigned version. If the gateway has several linked agents, add --agent <agent-id> to select one.

To deploy to every gateway of an agent, use --agent <agent-id> without --gateway-id. Check the agent and its gateways before you run that command. See Policy Lifecycle for permissions and all options.

A successful push confirms the assignment. It does not confirm that the gateway applied the configuration. An unchanged result means that the saved content and selected assignments already match. Check In sync. Then send your allow and block requests.

If a live request and a local test give different results, compare the active configuration, the request, the token permissions, the provider response, and the budget state. A different result does not prove that the gateway uses the wrong file.

Keep the file in version control

Commit the YAML and its tests together. Do not commit credentials or local environment files.

ai-config/
├── policy-config.yaml
└── tests/
    ├── normal-request.json
    └── blocked-request.json

If each environment needs different settings, give each one its own directory. Then run the tests for one directory:

verdictan policy test --pack-dir ./configs/staging --json

Next steps

Managing Policy Changes: review a change and roll it back.
Declarative Config Reference: find a field.
verdictan policy test: read the test case format and output.

Get a configuration​

Lint and test the file​

Try the change on a test gateway​

Deploy the tested version​

Deploy from the CLI​

Keep the file in version control​

Next steps​