Tutorial: Hot-Reloading Configuration Without Downtime

This tutorial walks you through hot-reloading Keeptrusts gateway configuration without dropping requests by using the current gateway administration commands: kt gateway install, kt gateway start, kt gateway reload, kt gateway status, and kt gateway revert.

Use this page when

You need to update gateway policies or provider settings without dropping in-flight requests.
You are running a managed local gateway instance that should survive config changes without a full process restart.
You need to verify that reloads are recorded in the gateway supervisor history.
You need a documented revert path back to the last known-good config.

Primary audience

Primary: Platform engineers managing live gateway deployments
Secondary: DevOps teams integrating config-as-code workflows; SRE teams requiring zero-downtime policy updates

Prerequisites

kt CLI installed (first-run tutorial)
An OpenAI-compatible API key exported as OPENAI_API_KEY
A local machine where kt can install a user service (launchd on macOS or systemd --user on Linux)
curl and jq installed

How Hot Reload Works

For a managed gateway instance, Keeptrusts stores the desired and observed config versions in local supervisor state. When you trigger a reload:

The new configuration file is parsed and validated.
The running gateway is asked to load the new config over its admin endpoint.
In-flight requests continue with the old config while the new config is verified.
New requests switch to the new config after activation succeeds.
If activation verification fails, the supervisor records the failure and keeps the previous config available for revert.

Step 1: Start with a Baseline Configuration

Create policy-config.yaml:

policy-config.yaml
pack:
  name: local-dev
  version: 0.1.0
  enabled: true

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

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

policy:
  prompt-injection:
    response:
      action: block
      message: Request blocked: potential prompt injection detected

  audit-logger:
    retention_days: 30

Step 2: Install and Start a Managed Gateway Instance

Install the managed local gateway service:

kt gateway install \
  --name local-dev \
  --listen 0.0.0.0:41002 \
  --policy-config policy-config.yaml

Then start it:

kt gateway start --name local-dev

Check status:

kt gateway status --name local-dev

What to look for:

name: local-dev
listen: 0.0.0.0:41002
lifecycle: running
observed config: 0.1.0 (...)

Step 3: Prepare a New Version of the Config

Update the config to add PII redaction and bump the pack version. Edit policy-config.yaml:

policy-config.yaml
pack:
  name: local-dev
  version: 0.1.1
  enabled: true

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

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

policy:
  prompt-injection:
    response:
      action: block
      message: Request blocked: potential prompt injection detected

  pii-detector:
    action: redact
    redaction:
      marker_format: label
      include_metadata: true

  audit-logger:
    retention_days: 30

Validate the new config before you reload it:

kt policy lint --file policy-config.yaml

Step 4: Reload the Running Gateway

Trigger the reload:

kt gateway reload \
  --name local-dev \
  --gateway-url http://localhost:41002 \
  --config-path policy-config.yaml

Expected output:

reloaded local-dev to version 0.1.1

Verify the new policy is active:

kt gateway status --name local-dev

Step 5: Verify Zero Dropped Requests

Run a small load test during reload to confirm continuity:

# Terminal 1: Generate continuous traffic
for i in $(seq 1 100); do
  STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
    http://localhost:41002/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o-mini",
      "messages": [{"role": "user", "content": "Hello"}]
    }')
  echo "Request $i: HTTP $STATUS"
  sleep 0.1
done

While traffic is flowing, trigger another reload in a second terminal:

kt gateway reload \
  --name local-dev \
  --gateway-url http://localhost:41002 \
  --config-path policy-config.yaml

Requests already in flight continue under the old config, while new requests begin using the reloaded config after activation completes. You should not need to restart the service.

Step 6: Inspect Reload History

View the recent recorded reload operations for the gateway:

kt gateway status --name local-dev --history-json --history-action reload

What to look for:

{
  "history_action": "reload",
  "operations_history": [
    {
      "action": "Reload",
      "outcome": "Succeeded",
      "target_version": "0.1.1"
    }
  ]
}

Step 7: Understand Failure and Rollback Behavior

Always lint before reloading:

kt policy lint --file policy-config.yaml

If a bad config still makes it to reload and activation fails, the supervisor records the failure and keeps the last known-good target for revert.

Step 8: Revert to the Previous Known-Good Configuration

Revert to the last known-good configuration:

kt gateway revert \
  --name local-dev \
  --gateway-url http://localhost:41002

Expected output:

reverted local-dev

Then confirm the status and history again:

kt gateway status --name local-dev --history-json

You should see a successful revert entry and the active config version should match the last known-good version.

Step 9: Validate Before Reloading in CI

Always validate configuration changes before reloading a live gateway:

kt policy lint --file policy-config.yaml

Add this to your CI pipeline:

# .github/workflows/validate-config.yml
name: Validate Gateway Config
on:
  pull_request:
    paths:
      - "config/policy-config.yaml"

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install kt
        run: |
          curl -fsSL https://dl.keeptrusts.com/releases/latest/kt-linux-x86_64.tar.gz \
            | sudo tar xz -C /usr/local/bin kt
      - name: Validate config
        run: kt policy lint --file config/policy-config.yaml

Summary

kt gateway install defines a managed local gateway instance.
kt gateway start launches that instance as a user service or managed local process.
kt gateway reload applies a new config without requiring a full restart.
kt gateway status --history-json shows recent reload and revert actions.
kt gateway revert rolls the instance back to the previous known-good config.
kt policy lint --file should gate every reload in CI and local workflows.

For AI systems

Canonical terms: Keeptrusts gateway, managed gateway instance, hot reload, gateway supervisor, kt gateway install, kt gateway start, kt gateway reload, kt gateway status, kt gateway revert.
CLI commands: kt gateway install --name <name> --listen <addr> --policy-config <file>, kt gateway reload --name <name> --gateway-url <url> --config-path <file>, kt gateway status --name <name> --history-json.
Config fields: pack.version, providers.targets[], policies.chain[], policy.<kind> blocks.
Best next pages: Policy Testing in CI/CD, Gateway Docker Compose, Multi-Gateway.

For engineers

Use the managed gateway workflow when you need zero-downtime config changes, not just a local dev process restart.
Bump pack.version when you want reload and revert history to be easier to read.
Lint before reload: kt policy lint --file policy-config.yaml.
Inspect history after reload: kt gateway status --name local-dev --history-json --history-action reload.
Keep kt gateway revert as your fast rollback path when a newly activated config misbehaves.

For leaders

Hot reload removes the need for maintenance windows when policy configs change.
Reload and revert history make change management auditable without introducing a separate deployment platform.
The managed local gateway workflow provides a service-grade runtime on developer and small-node environments.
Lint-gated reloads reduce operational risk by preventing malformed policy changes from reaching live traffic.

Next steps

Multi-Gateway — connect runtime gateways to shared control-plane workflows
Policy Testing in CI/CD — validate configs before they ever reach reload
Gateway Docker Compose — compare container-based runtime patterns with local managed services

Troubleshooting

Symptom	Cause	Fix
`instance local-dev does not exist`	The gateway instance was never installed	Run `kt gateway install --name local-dev ...` first
Reload succeeds but version does not change	`pack.version` was not updated	Bump `pack.version` before reloading
Reload fails immediately	Config schema or YAML error	Run `kt policy lint --file policy-config.yaml` and fix the reported issue
Revert has no rollback target	No successful prior reload/start state is recorded	Start from a valid installed instance, then reload again after a good baseline

Use this page when​

Primary audience​

Prerequisites​

How Hot Reload Works​

Step 1: Start with a Baseline Configuration​

Step 2: Install and Start a Managed Gateway Instance​

Step 3: Prepare a New Version of the Config​

Step 4: Reload the Running Gateway​

Step 5: Verify Zero Dropped Requests​

Step 6: Inspect Reload History​

Step 7: Understand Failure and Rollback Behavior​

Step 8: Revert to the Previous Known-Good Configuration​

Step 9: Validate Before Reloading in CI​

Summary​

For AI systems​

For engineers​

For leaders​

Next steps​

Troubleshooting​