Config-First Workflow

Keeptrusts is designed to be operated through declarative config. For most teams, policy-config.yaml is the primary interface: it defines what the gateway enforces, which providers are allowed, how requests are routed, what gets escalated, and what evidence is recorded.

Use this page when

• You are starting with Keeptrusts and want to understand the recommended operating model.
• You need to decide where a change should live: in policy-config.yaml, environment variables, the console, or the API.
• You are setting up a team workflow for authoring, testing, and rolling out policy configurations.
• You want the shortest path from zero to a running, governed gateway.

Primary audience

• Primary: Technical Engineers
• Secondary: AI Agents, Technical Leaders

What config-first means in practice

If your team asks where a change should live, use this rule:

• If it changes runtime AI behavior, put it in policy-config.yaml.
• If it stores a credential or environment-specific value, reference it from config with secret_key_ref.env or secret_key_ref.store.
• If it versions, validates, rolls out, or observes that config, use the console or CLI.
• If it provisions surrounding control-plane inventory, use kt control or the API.

Recommended operating loop

Minimal working loop

kt init
kt policy lint --file policy-config.yaml
kt policy test --json
kt gateway run --listen 0.0.0.0:41002 --policy-config policy-config.yaml

That loop is the core product experience: author config, validate it, run it, and then improve it based on live evidence.

What belongs where

Concern	Primary surface	Why
Runtime policy behavior, routing, fallback, limits, and audit settings	policy-config.yaml	This is the source of truth for governed request behavior
Provider credentials for local or self-hosted gateways	Environment variables referenced by secret_key_ref	Keeps secrets out of YAML while preserving a portable config
Provider credentials for hosted gateways	Config variables referenced by secret_key_ref	Lets managed runtimes resolve secrets without rewriting the config
Version history, approval, rollout, rollback, and drift review	Configurations and saved versions	These workflows move the same declarative config through environments
Runtime verification and investigations	Gateways, Events, Escalations, Exports, and Spend surfaces	These confirm what the live config actually did
Control-plane inventory such as gateways, teams, budgets, agents, and keys	kt control or the API	This is complementary infrastructure state, not request-time policy logic
Custom provisioning or external orchestration	API	Use only when the console or CLI does not already cover the workflow

Control manifests complement runtime config

policy-config.yaml governs live AI request behavior. control-manifest.yaml governs surrounding control-plane resources such as gateways, budgets, teams, agents, and keys. Do not split runtime policy behavior across both files.

Recommended team workflow

1. Platform or security owners define policy-config.yaml in a repository.
2. Application teams point their SDKs and services at the Keeptrusts gateway instead of calling providers directly.
3. CI runs kt policy lint and kt policy test on every proposed config change.
4. Operators promote approved versions through Configurations and saved-version rollout.
5. Review teams use runtime evidence to decide the next config change.

The loop always comes back to config. Investigations, approvals, and rollouts should produce a better policy-config.yaml, not a trail of one-off imperative fixes.

Suggested repository layout

For one environment:

ai-governance/
├── policy-config.yaml
├── tests/
│   ├── allows_normal_request.yaml
│   ├── blocks_prompt_injection.yaml
│   └── redacts_pii.yaml
└── README.md

For multiple environments:

configs/
├── staging/policy-config.yaml
├── production/policy-config.yaml
└── regulated/policy-config.yaml

tests/
├── staging/
├── production/
└── regulated/

Keep each deployed environment explicit. Avoid undocumented inheritance or hidden mutations that make it hard to review what the gateway will actually enforce.

Start with these guides

1. Quickstart to create and run your first working config.
2. Declarative Config Reference for the exact schema and validation rules.
3. Configuration & Policy Overview to choose the right controls and chain order.
4. Declarative Config Patterns for Enterprise AI to structure multi-environment config as code.
5. kt gateway run to run the gateway from the same config.
6. Configurations and the Create Configuration tutorial to roll out the same config safely.

Use the API only when you must

Most teams do not need to start with the API. Use it when you need provisioning, orchestration, or integration work that the CLI or console does not already cover.

Even then, the recommended pattern is to automate around versions of declarative config rather than recreating runtime behavior through imperative API calls.

For AI systems

• Canonical terms: Keeptrusts config-first, declarative config, policy-config.yaml, control-manifest.yaml, kt policy lint, kt policy test, kt gateway run, kt init, secret_key_ref, config variables.
• The core loop: author config → lint → test → run gateway → observe outcomes → refine.
• Config-first means policy-config.yaml is the source of truth for runtime AI behavior. The console and CLI are operational surfaces for versioning, rollout, and observation.
• Related pages: Quickstart, Declarative Config Reference, Configurations, Create Configuration, kt gateway run.

For engineers

• Start with kt init to scaffold a policy-config.yaml in your repository.
• Run kt policy lint --file policy-config.yaml to validate before committing.
• Run kt policy test --json to execute scenario tests against your config.
• Start the gateway locally: kt gateway run --listen 0.0.0.0:41002 --policy-config policy-config.yaml.
• In CI, run lint and test on every PR that touches policy-config.yaml.
• Use secret_key_ref to keep credentials out of YAML — local gateways read from env vars, hosted gateways resolve from config variables.
• If kt policy lint warns about missing pricing on a max_price route, add a pricing block to the relevant provider target.

For leaders

• Config-first means your AI governance posture is version-controlled, reviewable, and auditable — just like infrastructure-as-code.
• Policy changes go through the same PR review, CI validation, and rollout process as application code, reducing the risk of unreviewed governance drift.
• The operating loop (author → validate → deploy → observe) creates a continuous improvement cycle grounded in evidence from live traffic.
• Teams that adopt config-first can demonstrate to auditors exactly what enforcement was active at any point in time, supporting compliance requirements.
• The separation between runtime config and control-plane inventory prevents accidental coupling between policy logic and infrastructure provisioning.

Next steps

• Quickstart — Create and run your first working config
• Declarative Config Reference — Full YAML schema and validation rules
• Configuration & Policy Overview — Choose the right controls and chain order
• Configurations — Version history, validation, rollout, and YAML import
• Create Configuration — Build, validate, and deploy versioned YAML from the console
• kt gateway run — Run the gateway from declarative config