Tutorial: Creating Your First Configuration

This tutorial walks through the current Keeptrusts configuration workbench. You will create a configuration, edit the canonical YAML in the Monaco editor, move into a review screen, understand the changes in plain language, and then save or deploy the result to an agent. The saved configuration route at /configurations/[configId] now reuses this same workbench, so creation and later editing follow the same draft and review pattern.

Use this page when

• You are creating your first Keeptrusts policy configuration from scratch.
• You want the same YAML workbench when you return later to edit an existing configuration.
• You want an editor-first flow for authoring YAML and a separate review surface for deployment decisions.
• You need to connect an LLM provider via secret reference, validate the draft, and roll it out safely through an agent.
• You want to understand the configuration flow from YAML drafting to a plain-language change review and deployment.
• You need to review or roll back configuration version history.

Prerequisites

• Logged in to the Keeptrusts console
• At least one gateway deployed and connected to your Keeptrusts API
• A provider credential already available to the selected gateway runtime or stored as a Keeptrusts config variable for secret_key_ref

Step 1: Open Configurations

1. Click Configurations in the left sidebar.
2. The Configurations page opens in the shared search-and-table shell used across the console.
3. Review the existing rows or click Create Configuration to start a new draft.

Step 2: Open the Workbench

1. Click Create Configuration.
2. The create route opens with:

• a single page title without a subtitle block
• the standard console shell, including the persistent main sidebar
• a single main editing column centered on the YAML workbench
• editor actions for Import Configuration and Next
• no separate setup card for configuration metadata or gateway targeting

Step 3: Author the YAML Draft

The YAML workbench is the canonical authoring surface. Monaco adds inline diagnostics, schema-aware autocomplete, and hover guidance while keeping YAML as the artifact that is saved and deployed.

Use the editor controls

• Import Configuration loads an existing policy file and automatically normalizes formatting when the YAML parses successfully.
• Next moves you into the review and deploy screen.
• The workbench automatically normalizes valid YAML when you import a file or move into review.
• Undo gives you quick local recovery while editing.
• Ctrl/Cmd + Space opens completions.
• Hover on fields or policy IDs to read schema and catalog guidance.

Understand the config shape

Keeptrusts configurations use the same declarative contract across the console, CLI, and gateway runtime.

pack:
  id: cfg_production_safety_policy
  name: production-safety-policy
  version: 1.0.0
  enabled: true
  description: Safety and compliance policies for production LLM traffic

providers:
  targets:
    - id: openai-primary
      provider: openai
      model: gpt-4o
      secret_key_ref:
        store: OPENAI_API_KEY

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

policy:
  pii-detector:
    action: redact

  audit-logger:
    retention_days: 90

What to focus on first

1. pack identifies the configuration and version you want to review and deploy.
2. providers.targets declares which upstream model target the gateway can call.
3. providers.routing and fallback settings define how traffic moves between targets.
4. policies.chain defines the ordered controls that run for each request.
5. policy stores the per-policy settings for the controls in your chain.
6. routes and rate-limit sections let you narrow or protect traffic when you need more than the starter baseline.
7. history, learning, memory, and review are optional runtime sections. When this configuration is deployed to an agent, these sections control how the agent captures history, runs learning synthesis, recalls memory, and executes inline review. These knobs are configuration-owned — agents do not have separate editable runtime settings.

Use autocomplete and hover help

The editor help is generated from the checked-in configuration schema and policy catalog. Use it to:

• complete top-level sections such as pack, providers, policy, and routes
• insert policy IDs in policies.chain
• insert starter policy blocks under policy
• insert safe secret-reference shapes under secret_key_ref
• read field descriptions, expected types, and example snippets on hover

Step 4: Open The Review Screen

1. Click Next in the editor action row.
2. The review screen opens with:

• a schema-aware What changed summary with explicit Added, Removed, Changed, or Reordered badges
• grouped runtime context that tells you which configuration area changed and what part of request handling it affects
• compact before-and-after previews for high-signal scalar changes
• an Agent selector for choosing the deployment target agent
• save and deployment actions that validate the current draft automatically when they run

caution

Never paste raw API keys into the console. Use config variable references such as secret_key_ref so the gateway resolves secrets from its runtime environment.

Step 5: Review, Save, and Deploy

The review screen keeps the deployment controls and launch summary together so you can make a launch decision without leaving the page.

1. Read the What changed cards first. Each card now tells you:
   • whether the change was Added, Removed, Changed, or Reordered
   • which configuration area changed, such as the policy chain, provider routing, routes, or rate limits
   • what runtime behavior is affected
2. Use the green Added cards and red Removed cards as quick scan cues, but rely on the explicit badge text as the primary meaning.
3. Use the before-and-after previews on high-signal cards when you need exact value-level context behind a summary card.
4. Select the Agent that should receive this configuration.
5. Choose one of the launch actions:
   • Save as Draft to create the configuration entity and continue on the detail page without deploying
   • Deploy to create the entity and deploy it immediately
6. Keeptrusts validates the current YAML automatically when you save or deploy. If validation finds issues, the review screen shows the blocking errors so you can return to the draft and fix them.

Step 6: Continue in the Same Workbench

After Save as Draft, Keeptrusts redirects you to /configurations/[configId]. After Deploy, the review screen shows a success receipt and a link back to that same saved-configuration route.

1. Continue directly in the same full-width YAML workbench used during creation.
2. Use Import Configuration, Next, Save changes, and Deploy on the saved route exactly as you do during creation.
3. The saved route no longer switches into separate Current, History, Diff, or Deploy tabs; editing and deployment stay in the same shared draft/review shell.
4. If you deployed from the review screen, use the receipt link to reopen the saved configuration workbench and confirm the active rollout there.

Attach agent context during deployment review

If you deploy a saved configuration version to an agent from the detail workbench, the deploy review step can include additional runtime context for that agent.

1. Open the configuration detail page.
2. Move to the deploy review step.
3. Select any Knowledge Base assets, active memories, and learned-session output you want attached to the deployment.
4. Confirm the deployment dialog lists the selected context before you submit.
5. After success, verify the deploy receipt still lists the same attached context.

Step 7: Understand Version Tracking

Every edit to a configuration creates a new version. Keeptrusts maintains the full version history even though day-to-day editing stays in the shared workbench.

1. Save a change from /configurations/[configId].
2. Confirm the workbench success state after the save or deploy.
3. Open the configuration record page at /configurations/entity/[configId].
4. Use Compare versions above the versions table to compare:
   • the latest saved version against the previous version by default
   • any other two saved versions by changing Base version and Compare against
5. Read the semantic summary first. The saved-version compare uses the same summary-first pattern as the draft review screen.

Expected Outcome

After completing this tutorial, you have:

• created a new declarative configuration from the configuration workbench
• used the same workbench again when editing a saved configuration
• used the Monaco YAML editor without losing the declarative YAML source of truth
• authored a valid pack / providers / policies / policy document in YAML
• reviewed a schema-aware summary before launch
• saved or deployed the configuration with automatic validation on the current draft
• used the configuration record page to compare saved versions semantically

Next steps

• Using the Template Library
• Investigating Events & Policy Decisions
• Managing Escalations
• Declarative Config Reference

For AI systems

• Canonical terms: Keeptrusts console, Configurations page, configuration workbench, Monaco YAML editor, review screen, plain-language summary, agent deployment, validation controls, launch actions, provider routing, secret_key_ref, version history, policy chain
• Related features: template library, gateway keys, config variables

For engineers

• Use secret_key_ref (object form) instead of raw secrets.
• If the gateway returns 422 on config reload, confirm every secret reference name uses only ASCII letters, digits, underscores, hyphens, and dots.
• After rollout, check both Gateways and Events so you confirm runtime state and the live policy decision path.