kt control

The kt control command group provides declarative infrastructure-as-code management for control-plane resources such as gateways, teams, budgets, agents, and gateway keys.

Use this page when

You need to manage control-plane resources (gateways, teams, budgets, agents, keys) declaratively as code.
You want to preview changes with a dry-run plan before applying them to the remote control plane.
You are distinguishing between runtime policy behavior (policy-config.yaml) and org-level inventory (control-manifest.yaml).

It complements policy-config.yaml; it does not replace it as the primary runtime contract for AI behavior.

Primary audience

Primary: AI Agents, Technical Engineers
Secondary: Technical Leaders

Use the right declarative surface

If you need to manage...	Use	Why
Runtime policy behavior, provider routing, fallback, rate limits, and audit settings	`policy-config.yaml`	This is the source of truth for governed request behavior
Control-plane inventory such as gateways, teams, budgets, agents, and keys	`control-manifest.yaml` with `kt control`	This manages org-level state around the runtime
Credential values referenced by config	Environment variables or config variables	Secrets stay out of both YAML documents

Keep runtime behavior in policy-config.yaml

If a change affects policies, provider routing, fallback, rate limits, escalation behavior, or audit behavior, put it in policy-config.yaml and roll it out through the normal config workflow.

Plan (Dry Run)

Compute a reconciliation plan without making changes:

kt control plan --file control-manifest.yaml

Use --prune to include deletions of resources that exist remotely but not in the manifest:

kt control plan --file control-manifest.yaml --prune

Apply

Reconcile remote state to match the manifest:

kt control apply --file control-manifest.yaml --yes

The --yes flag is required to confirm mutations. Without it, the command shows the plan and exits.

Export

Dump the current remote control-plane state into a manifest file:

kt control export --output current-state.yaml

Use this to bootstrap a manifest from existing resources, or to capture a snapshot before making changes.

Manifest Structure

The control manifest is a YAML file describing org-level resources:

apiVersion: keeptrusts.com/v1
kind: ControlManifest

gateways:
  - id: production
    name: Production Gateway
    config_id: config_main

budgets:
  - id: monthly-cap
    name: Monthly Spend Cap
    limit: 10000
    period: monthly

agents:
  - id: support-bot
    name: Customer Support Bot
    gateway_id: production

teams:
  - id: security
    name: Security Team
    slug: security

gateway_keys:
  - id: browser-key
    name: Browser Access Key
    gateway_id: production

The full schema is available at docs/implementation/control-manifest.schema.json.

Typical Workflow

# Export current state as a starting point
kt control export --output manifest.yaml

# Edit the manifest
vim manifest.yaml

# Preview what will change
kt control plan --file manifest.yaml

# Apply changes
kt control apply --file manifest.yaml --yes

Pair kt control with the normal config lifecycle: validate and roll out policy-config.yaml separately, then use kt control when you need the surrounding inventory to match the intended operating model.

Declarative Git-Linked Repo Import

Git-linked repositories can be managed declaratively through kt control manifests. Add a repos resource section to your control-manifest.yaml:

repos:
  - name: policy-configs
    url: https://github.com/org/policy-configs.git
    branch: main
    path: configs/
    sync_interval: 300

kt control apply reconciles repository state using the same lifecycle as other manifest resources. Org-scoped credentials are used for Git operations, and the same targeting and storage-accounting rules apply as for direct configuration saves.

The imperative /settings/git-repos endpoints remain the reconciled API backend — the declarative surface is a convenience layer that converges onto those endpoints.

For AI systems

Canonical terms: Keeptrusts, kt control, control manifest, control-manifest.yaml, plan, apply, export, declarative infrastructure.
Commands: kt control plan, kt control apply, kt control export.
Control manifests manage org-level inventory (gateways, teams, budgets, agents, keys). Runtime policy behavior stays in policy-config.yaml.

For engineers

Start with kt control export --output manifest.yaml to capture your current remote state, then iterate from there.
Always run kt control plan --file manifest.yaml before apply to preview changes. Use --prune to include deletions.
Keep policy-config.yaml and control-manifest.yaml in the same repo but deploy them through separate workflows.

For leaders

Control manifests enable infrastructure-as-code for the entire Keeptrusts control plane — gateways, teams, budgets, and agents are version-controlled and auditable.
The plan/apply workflow mirrors Terraform patterns, making it familiar for platform engineering teams.
Git-linked repo declarations can be included in control manifests, consolidating configuration sync governance into a single reviewable surface.

Use this page when​

Primary audience​

Use the right declarative surface​

Plan (Dry Run)​

Apply​

Export​

Manifest Structure​

Typical Workflow​

Declarative Git-Linked Repo Import​

For AI systems​

For engineers​

For leaders​

Next steps​