Config-First Workflow
Keeptrusts is designed around declarative config. For most teams, policy-config.yaml is the primary artifact because it defines routing, policy evaluation, secrets references, tests, and the runtime behavior you later verify in the product.
The working rule
Use this default split:
- If a change affects runtime AI behavior, put it in
policy-config.yaml. - If a change stores secret material, reference it from config with
secret_key_ref.envorsecret_key_ref.store. - If a change versions, reviews, or rolls out config, use the console or CLI.
- If a change is about users, teams, SSO, tokens, budgets, or billing controls, use the corresponding product surface rather than embedding it in runtime policy.
Recommended operating loop
Minimal loop
kt init
kt policy lint --file policy-config.yaml
kt policy test --json
export KEEPTRUSTS_API_URL="https://api.keeptrusts.com"
export KEEPTRUSTS_API_TOKEN="kt_your_gateway_runtime_token"
kt gateway run --listen 127.0.0.1:41002 --agent docs-demo --policy-config policy-config.yaml
That loop is the core product experience: author config, validate it, run it, and improve it based on observed behavior.
What belongs where
| Concern | Primary surface | Why |
|---|---|---|
| Runtime policy behavior, routing, fallbacks, rate limits, and audit settings | policy-config.yaml | This is the source of truth for request-time behavior |
| Provider credentials for local development | Environment variables referenced by secret_key_ref.env | Keeps credentials out of YAML |
| Provider credentials for centrally managed runtimes | Stored secrets referenced by secret_key_ref.store | Keeps the same config portable across environments |
| Version history, review, rollout, and rollback | Configurations in the console or the matching CLI flow | These workflows move the same YAML safely |
| Runtime verification and investigation | kt events or GET /v1/events with required since for request outcomes; the applicable Gateways, Inbox, Trail, Usage, or capture-enabled History console surface | Each command, API, or console surface proves a different part of live behavior; History contains session content only when capture is enabled |
| Team access, SSO, tokens, budgets, and billing | The corresponding settings or billing surfaces | These are surrounding product controls, not request-time policy |
Recommended repository layout
For a single 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 hidden inheritance or manual runtime drift.