Skip to main content

kt gateway run

Start the Keeptrusts gateway.

Usage​

kt gateway run [OPTIONS]

Key options​

FlagDescription
--listen <host:port>Listen address. Default: 0.0.0.0:41002
--agent <selector>With --policy-config, an agent name to create or reuse; without local config, an existing agent name or ID
--policy-config <path>One or more declarative config files. Requires --agent
--config-name <name>Optional configuration name when syncing a local pack
--fail-mode <allow|block>Behavior when every upstream attempt ends in a transport error. Default: block
--upstream <url>Debug-only upstream override
--upstream-api-key <key>Debug-only upstream credential override; exposes the secret in process arguments
--max-concurrency <n>Runtime concurrency ceiling
--api-token <token>Runtime token for control-plane sync, telemetry, and inspection; prefer KEEPTRUSTS_API_TOKEN to avoid process arguments

Important rule​

When you pass --policy-config, the current CLI requires both:

  1. --agent <name>
  2. a runtime API token through --api-token or KEEPTRUSTS_API_TOKEN

That combination lets the CLI sync the YAML to a real agent identity before the gateway starts.

Example: connected runtime from local YAML​

export KEEPTRUSTS_API_URL="https://api.keeptrusts.com"
export KEEPTRUSTS_API_TOKEN="kt_your_gateway_runtime_token"
export KEEPTRUSTS_OPENAI_API_KEY="provider-secret"

kt gateway run \
  --agent docs-demo \
  --listen 127.0.0.1:41002 \
  --policy-config policy-config.yaml

Example: fail-open debugging​

kt gateway run \
  --agent docs-demo \
  --listen 127.0.0.1:41002 \
  --policy-config policy-config.yaml \
  --fail-mode allow

Fail-open does not send an unreachable request somewhere else. When every upstream attempt ends in a transport error, it returns an HTTP 200 synthetic degraded response with reason proxy.degraded_allow. The default block mode returns 503, or 504 for a timeout. Use allow only when that synthetic success contract is an approved product requirement.

The CLI default listens on all interfaces. Local examples bind to 127.0.0.1; use an all-interface address only behind intentional ingress, firewall, TLS, and application-token controls.

Multi-provider example​

policy-config.yaml
pack:
  name: multi-provider
  version: 0.1.0
  enabled: true

providers:
  targets:
    - id: openai-primary
      provider: openai
      model: your-openai-model
      base_url: https://api.openai.com
      secret_key_ref:
        env: KEEPTRUSTS_OPENAI_API_KEY
    - id: azure-fallback
      provider: azure
      provider_type: azure-openai
      format: openai
      model: your-azure-openai-model
      base_url: https://replace-with-resource-name.openai.azure.com
      secret_key_ref:
        env: KEEPTRUSTS_AZURE_OPENAI_API_KEY
      azure_api_version: your-supported-api-version
      azure_deployment: your-azure-deployment

  fallback:
    trigger_on:
      - rate_limit
      - server_error
      - timeout

  routing:
    strategy: ordered

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

Replace both model placeholders with IDs supported by those provider accounts. See Multi-Provider Fallback for the current trigger and attempt-limit behavior before relying on this routing pattern.

Sending traffic through the gateway​

Use a client API token that is separate from the runtime token:

export KEEPTRUSTS_REQUEST_TOKEN="kt_your_application_token"

curl http://localhost:41002/v1/chat/completions \
  -H "Authorization: Bearer ${KEEPTRUSTS_REQUEST_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-openai-model",
    "messages": [
      {"role": "user", "content": "Explain quantum computing"}
    ]
  }'

Pinning a provider target​

curl http://localhost:41002/v1/chat/completions \
  -H "Authorization: Bearer ${KEEPTRUSTS_REQUEST_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "X-Keeptrusts-Provider: openai-primary" \
  -H "X-Keeptrusts-Model: your-openai-model" \
  -d '{"model":"your-openai-model","messages":[{"role":"user","content":"Hello"}]}'

An unknown provider pin is rejected instead of silently falling back. Model and provider pins must also be compatible with the declared target.

Check process health independently of a model request:

curl http://127.0.0.1:41002/healthz

Next steps​