Skip to main content

kt gateway run: Launching a Policy Gateway in 30 Seconds

If you already have a valid policy-config.yaml, kt gateway run is the moment Keeptrusts becomes real. It starts the runtime that sits in front of upstream providers, enforces your chain on every request and response, and exposes an OpenAI-compatible endpoint that existing clients can usually target with only a base URL change.

Use this page when​

  • You already have a policy config and want the fastest route to a running gateway.
  • You want to understand what kt gateway run needs and what it should read from config versus environment.
  • You need a short operational guide for local startup, smoke testing, and first traffic.

Primary audience​

  • Primary: Technical Engineers and platform teams
  • Secondary: Technical Leaders, solution architects, AI agents

The problem​

Teams often overcomplicate gateway startup. They assume they need a custom reverse proxy, a new SDK, a complex bootstrap service, or a provider-specific wrapper. In reality, once the config is valid, the gateway runtime itself is the simplest part of the system.

What makes startup feel complicated is usually a mismatch between responsibilities. People mix provider secrets into YAML, treat debug flags as permanent config, or forget that the runtime should read its provider definitions from policy-config.yaml rather than from ad hoc CLI overrides.

That leads to three avoidable problems:

  • the runtime starts with settings that cannot be reproduced later
  • the config used in development is different from the config reviewed in CI
  • “temporary” overrides become permanent operating practice

kt gateway run works best when it is treated as the executor of a declarative contract, not as a place to invent runtime behavior on the fly.

The solution​

Keeptrusts recommends a simple split of responsibilities.

  • Put provider targets, routing, fallback, and policy behavior in policy-config.yaml.
  • Put secrets in environment variables or managed stores referenced through secret_key_ref.
  • Use kt gateway run to execute that contract.

That model is why the command can be so short. If the config already describes the runtime, startup is mostly just choosing a listen address and pointing the gateway at the config file.

Implementation​

Here is a minimal but real gateway config:

pack:
  name: quick-launch
  version: 0.1.0
  enabled: true

providers:
  targets:
    - id: openai-primary
      provider: openai
      model: gpt-5.4-mini
      base_url: https://api.openai.com
      secret_key_ref:
        env: OPENAI_API_KEY

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

policy:
  prompt-injection:
    threshold: 0.8
    action: block

  audit-logger:
    retention_days: 30

Start the runtime with one environment variable and one command:

export OPENAI_API_KEY="sk-live-team-gateway-key"
kt gateway run --listen 0.0.0.0:41002 --policy-config policy-config.yaml

That is the core path. There are other flags, and there are emergency upstream overrides, but the recommended operating model is to keep real runtime definitions in the config.

Once the gateway is running, test it like a client would:

curl http://localhost:41002/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [
      {"role": "user", "content": "Summarize the principle of least privilege."}
    ]
  }'

If you want the gateway to report into the Keeptrusts control plane, add the reporting environment variables before startup:

export KEEPTRUSTS_API_URL="https://api.keeptrusts.com"
export KEEPTRUSTS_API_TOKEN="kt_gw_prod_runtime_token"

Then rerun the same kt gateway run command. The runtime behavior stays the same, but events, config resolution, and authenticated inspection can now integrate with the control plane.

One subtle but important habit is to keep kt policy lint and kt policy test --json immediately before startup in any serious workflow. A gateway is cheap to launch, so there is no reason to treat startup itself as validation. Validation should already have happened.

That is especially relevant when teams start using multi-provider routing. kt gateway run can handle ordered fallback and multiple targets, but those decisions still belong in YAML. The runtime should be predictable because the config was reviewable before it was executed.

Results and impact​

The obvious result is speed. A gateway can be live quickly once the config exists.

The less obvious result is operational discipline. When engineers learn to think of kt gateway run as “execute the reviewed config” rather than “figure it out at startup,” the whole deployment story gets cleaner. Development, staging, and production behave more consistently because the runtime command is stable while the config evolves intentionally.

It also lowers the adoption barrier for existing applications. Because the gateway is OpenAI-compatible, teams can often keep their client code and change only the base URL. That makes policy enforcement, audit logging, and routing control much easier to adopt incrementally.

Key takeaways​

  • kt gateway run should execute a reviewed policy-config.yaml, not replace it.
  • Keep secrets in environment variables or managed stores referenced by secret_key_ref.
  • The fastest safe path is config validation first, startup second, smoke test third.
  • Reporting into the control plane is additive and does not change the runtime contract.
  • The gateway becomes your application-facing AI endpoint, which is the core Keeptrusts boundary.

Next steps​