Skip to main content

Quickstart

This quickstart takes you from an empty working directory to a running Keeptrusts gateway with a small, reviewable policy chain.

What you will do​

  1. Create a starter policy-config.yaml
  2. Keep provider credentials out of YAML
  3. Lint and test the config
  4. Start the gateway
  5. Send a governed request through the gateway
  6. Verify the result before broader rollout
Using centrally managed BYOK routing?

If your organization already manages provider keys, role bindings, and resource tags in the control plane, follow Providers & BYOK Routing to connect an agent to an authorized provider key.

Before you begin​

  • Install kt by following Install the Gateway.
  • Have at least one provider credential ready, such as KEEPTRUSTS_OPENAI_API_KEY.
  • Have KEEPTRUSTS_API_URL and a runtime token for KEEPTRUSTS_API_TOKEN; the current kt gateway run --policy-config flow uses them when it binds local YAML to an agent.

1. Create a starter config​

kt init

Replace policy-config.yaml with a minimal config:

policy-config.yaml
pack:
  name: local-quickstart
  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: KEEPTRUSTS_OPENAI_API_KEY

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

policy:
  pii-detector:
    action: redact

  audit-logger: {}

2. Keep secrets out of YAML​

For a local gateway, export the provider credential in your shell:

export KEEPTRUSTS_OPENAI_API_KEY="sk-..."

If you are using a centrally managed runtime, store the secret in Keeptrusts and reference it with secret_key_ref.store:

kt secret create \
  --name KEEPTRUSTS_OPENAI_API_KEY \
  --env-var KEEPTRUSTS_OPENAI_API_KEY
store-backed provider target
providers:
  targets:
    - id: openai-primary
      provider: openai
      model: gpt-5.4-mini
      base_url: https://api.openai.com
      secret_key_ref:
        store: KEEPTRUSTS_OPENAI_API_KEY

The environment-variable name is operator-defined; the gateway also resolves legacy names such as OPENAI_API_KEY. Keeptrusts-prefixed names are recommended because they make the credential's owner and intended process explicit.

3. Lint and test the config​

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

Keep expanding the generated tests/ directory as your policy chain grows.

4. Start the gateway​

When you start the gateway from local YAML, the current CLI requires both an agent binding and a runtime API token:

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

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

KEEPTRUSTS_API_TOKEN is for the runtime itself. Do not reuse it as the client credential for ordinary application requests.

5. Send your first request through the gateway​

The gateway accepts the supported OpenAI request families, so an OpenAI client can use it by changing the base URL and supplying a Keeptrusts application token. Provider credentials remain in the gateway process.

Create an API token for the calling application. The token value is displayed once, so copy it into your secret manager rather than a shared terminal log:

kt token create --name quickstart-app --purpose general

Then export that value separately from the gateway 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": "gpt-5.4-mini",
    "messages": [
      {"role": "user", "content": "Hello, world!"}
    ]
  }'

Connected gateways require request authentication. The provider credential is used only for the upstream call and cannot replace the application token.

6. Verify the config is live​

Follow the public event stream, send another representative request, and confirm that its request, provider, model, and policy verdict appear:

kt events tail --since 10m --follow

Also verify:

  • Configurations shows the version you expect.
  • Gateways shows the runtime as healthy.
  • The kt events tail output shows the matching request ID, verdict, and routing outcome.
  • If conversation capture is enabled, History shows the captured request or session context.
  • A request with a missing or invalid application token is rejected before an upstream provider call.

Next steps​