Skip to main content

How To: Roll Out a New Template

Use this guide when your team wants to start from a Keeptrusts template and move it into a verified runtime workflow.

Outcome​

By the end of this workflow, you should have:

  • Chosen the right template.
  • Initialized and edited a local declarative config.
  • Validated the config locally.
  • Applied it to a running gateway.
  • Verified runtime behavior from customer-facing product surfaces.

Workflow diagram​

Step 1: Pick the closest template​

Open the public Templates catalog and compare:

  • Policy goals.
  • Provider assumptions.
  • Human-review behavior.
  • The amount of tuning your environment will still need.

Choose the template that is closest to your operating domain, even if you expect to tune it later.

Templates are reviewable starters, not certifications, legal advice, or proof that a workload complies with a named framework. Your deployed configuration, provider contract, operating controls, and evidence determine the real boundary.

Step 2: Initialize and edit locally​

First confirm that the authenticated CLI can resolve the exact template ID:

kt init --list
kt init --template <template-id> --dir ./keeptrusts-template
cd ./keeptrusts-template

If the selected ID is not listed, stop and correct the API token, API endpoint, or template availability before continuing. Do not initialize a similarly named template and assume it has the same controls.

Then:

  1. Read the generated policy-config.yaml before changing it.
  2. Edit provider targets, models, regions, and secret references for your environment.
  3. Review every policy action and threshold; remove controls that are not applicable and add required controls that the starter does not include.
  4. Add representative allow, block, redact, and escalate cases under tests/.
  5. Review the declarative config reference when you need field-level validation help.

Step 3: Validate before traffic​

Run lint and tests before you expose representative traffic to the new config.

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

Linting proves the public config shape. The test suite proves only the cases you authored. Neither command proves provider connectivity, production identity, or organization-wide compliance.

If your team uses the console to manage saved versions and rollout scope, open Configurations after local validation so you can review history, save a version with change detail, and choose rollout targets explicitly.

Step 4: Verify what the gateway is actually running​

For a connected gateway, bind the explicit config to the intended agent:

export KEEPTRUSTS_API_TOKEN="<gateway-runtime-token>"

kt gateway run \
  --agent <agent-name> \
  --listen 127.0.0.1:41002 \
  --policy-config policy-config.yaml

The runtime token belongs to the gateway. Use a separate gateway key, access key, or personal API token for representative client requests.

After you start or update the gateway:

  1. Open Gateways.
  2. Open the target gateway detail.
  3. Confirm the gateway is healthy and the applied configuration matches the rollout you expect.

If the gateway detail does not reflect the config you intended, stop there and correct the rollout before treating the template as live.

Step 5: Validate with representative traffic​

Send representative traffic through the gateway and then inspect:

  • kt events tail --since 10m --json or GET /v1/events?since=10m for request outcomes and policy behavior.
  • History for captured session context when conversation capture is enabled.
  • Inbox if the template introduces human-review paths.
  • Trail if you need audit evidence for the rollout.

Step 6: Decide whether to continue or tune​

  • If runtime behavior matches intent, document the rollout and its owners.
  • If false positives or unexpected review volume appear, narrow the policy scope and repeat the cycle.

Rollout checklist​

  • Template chosen.
  • Local config initialized.
  • Lint and tests passed.
  • Running config verified in Gateways.
  • Representative traffic reviewed with kt events or the Events API.
  • Captured session context reviewed in History when conversation capture is enabled.
  • Review queues checked when applicable.

Next steps​